Provided by: avr-libc_2.0.0+Atmel3.6.2-3_all bug

NAME

       stdio.h

SYNOPSIS

   Macros
       #define stdin   (__iob[0])
       #define stdout   (__iob[1])
       #define stderr   (__iob[2])
       #define EOF   (-1)
       #define fdev_set_udata(stream,  u)   do { (stream)->udata = u; } while(0)
       #define fdev_get_udata(stream)   ((stream)->udata)
       #define fdev_setup_stream(stream,  put,  get,  rwflag)
       #define _FDEV_SETUP_READ   __SRD
       #define _FDEV_SETUP_WRITE   __SWR
       #define _FDEV_SETUP_RW   (__SRD|__SWR)
       #define _FDEV_ERR   (-1)
       #define _FDEV_EOF   (-2)
       #define FDEV_SETUP_STREAM(put,  get,  rwflag)
       #define fdev_close()
       #define putc(__c,  __stream)   fputc(__c, __stream)
       #define putchar(__c)   fputc(__c, stdout)
       #define getc(__stream)   fgetc(__stream)
       #define getchar()   fgetc(stdin)

   Typedefs
       typedef struct __file FILE

   Functions
       int fclose (FILE *__stream)
       int vfprintf (FILE *__stream, const char *__fmt, va_list __ap)
       int vfprintf_P (FILE *__stream, const char *__fmt, va_list __ap)
       int fputc (int __c, FILE *__stream)
       int printf (const char *__fmt,...)
       int printf_P (const char *__fmt,...)
       int vprintf (const char *__fmt, va_list __ap)
       int sprintf (char *__s, const char *__fmt,...)
       int sprintf_P (char *__s, const char *__fmt,...)
       int snprintf (char *__s, size_t __n, const char *__fmt,...)
       int snprintf_P (char *__s, size_t __n, const char *__fmt,...)
       int vsprintf (char *__s, const char *__fmt, va_list ap)
       int vsprintf_P (char *__s, const char *__fmt, va_list ap)
       int vsnprintf (char *__s, size_t __n, const char *__fmt, va_list ap)
       int vsnprintf_P (char *__s, size_t __n, const char *__fmt, va_list ap)
       int fprintf (FILE *__stream, const char *__fmt,...)
       int fprintf_P (FILE *__stream, const char *__fmt,...)
       int fputs (const char *__str, FILE *__stream)
       int fputs_P (const char *__str, FILE *__stream)
       int puts (const char *__str)
       int puts_P (const char *__str)
       size_t fwrite (const void *__ptr, size_t __size, size_t __nmemb, FILE *__stream)
       int fgetc (FILE *__stream)
       int ungetc (int __c, FILE *__stream)
       char * fgets (char *__str, int __size, FILE *__stream)
       char * gets (char *__str)
       size_t fread (void *__ptr, size_t __size, size_t __nmemb, FILE *__stream)
       void clearerr (FILE *__stream)
       int feof (FILE *__stream)
       int ferror (FILE *__stream)
       int vfscanf (FILE *__stream, const char *__fmt, va_list __ap)
       int vfscanf_P (FILE *__stream, const char *__fmt, va_list __ap)
       int fscanf (FILE *__stream, const char *__fmt,...)
       int fscanf_P (FILE *__stream, const char *__fmt,...)
       int scanf (const char *__fmt,...)
       int scanf_P (const char *__fmt,...)
       int vscanf (const char *__fmt, va_list __ap)
       int sscanf (const char *__buf, const char *__fmt,...)
       int sscanf_P (const char *__buf, const char *__fmt,...)
       int fflush (FILE *stream)

Macro Definition Documentation

   #define _FDEV_EOF   (-2)
       Return code for an end-of-file condition during device read.

       To be used in the get function of fdevopen().

   #define _FDEV_ERR   (-1)
       Return code for an error condition during device read.

       To be used in the get function of fdevopen().

   #define _FDEV_SETUP_READ   __SRD
       fdev_setup_stream() with read intent

   #define _FDEV_SETUP_RW   (__SRD|__SWR)
       fdev_setup_stream() with read/write intent

   #define _FDEV_SETUP_WRITE   __SWR
       fdev_setup_stream() with write intent

   #define EOF   (-1)
       EOF declares the value that is returned by various standard IO functions in case of an
       error. Since the AVR platform (currently) doesn't contain an abstraction for actual files,
       its origin as 'end of file' is somewhat meaningless here.

   #define fdev_close()
       This macro frees up any library resources that might be associated with stream. It should
       be called if stream is no longer needed, right before the application is going to destroy
       the stream object itself.

       (Currently, this macro evaluates to nothing, but this might change in future versions of
       the library.)

   #define fdev_get_udata(stream)   ((stream)->udata)
       This macro retrieves a pointer to user defined data from a FILE stream object.

   #define fdev_set_udata(stream, u)   do { (stream)->udata = u; } while(0)
       This macro inserts a pointer to user defined data into a FILE stream object.

       The user data can be useful for tracking state in the put and get functions supplied to
       the fdevopen() function.

   #define FDEV_SETUP_STREAM(put, get, rwflag)
       Initializer for a user-supplied stdio stream. This macro acts similar to
       fdev_setup_stream(), but it is to be used as the initializer of a variable of type FILE.

       The remaining arguments are to be used as explained in fdev_setup_stream().

   #define fdev_setup_stream(stream, put, get, rwflag)
       Setup a user-supplied buffer as an stdio stream. This macro takes a user-supplied buffer
       stream, and sets it up as a stream that is valid for stdio operations, similar to one that
       has been obtained dynamically from fdevopen(). The buffer to setup must be of type FILE.

       The arguments put and get are identical to those that need to be passed to fdevopen().

       The rwflag argument can take one of the values _FDEV_SETUP_READ, _FDEV_SETUP_WRITE, or
       _FDEV_SETUP_RW, for read, write, or read/write intent, respectively.

       Note
           No assignments to the standard streams will be performed by fdev_setup_stream(). If
           standard streams are to be used, these need to be assigned by the user. See also under
           Running stdio without malloc().

   #define getc(__stream)   fgetc(__stream)
       The macro getc used to be a 'fast' macro implementation with a functionality identical to
       fgetc(). For space constraints, in avr-libc, it is just an alias for fgetc.

   #define getchar(void)   fgetc(stdin)
       The macro getchar reads a character from stdin. Return values and error handling is
       identical to fgetc().

   #define putc(__c, __stream)   fputc(__c, __stream)
       The macro putc used to be a 'fast' macro implementation with a functionality identical to
       fputc(). For space constraints, in avr-libc, it is just an alias for fputc.

   #define putchar(__c)   fputc(__c, stdout)
       The macro putchar sends character c to stdout.

   #define stderr   (__iob[2])
       Stream destined for error output. Unless specifically assigned, identical to stdout.

       If stderr should point to another stream, the result of another fdevopen() must be
       explicitly assigned to it without closing the previous stderr (since this would also close
       stdout).

   #define stdin   (__iob[0])
       Stream that will be used as an input stream by the simplified functions that don't take a
       stream argument.

       The first stream opened with read intent using fdevopen() will be assigned to stdin.

   #define stdout   (__iob[1])
       Stream that will be used as an output stream by the simplified functions that don't take a
       stream argument.

       The first stream opened with write intent using fdevopen() will be assigned to both,
       stdin, and stderr.

Typedef Documentation

   typedef struct __file FILE
       FILE is the opaque structure that is passed around between the various standard IO
       functions.

Function Documentation

   void clearerr (FILE * __stream)
       Clear the error and end-of-file flags of stream.

   int fclose (FILE * __stream)
       This function closes stream, and disallows and further IO to and from it.

       When using fdevopen() to setup the stream, a call to fclose() is needed in order to free
       the internal resources allocated.

       If the stream has been set up using fdev_setup_stream() or FDEV_SETUP_STREAM(), use
       fdev_close() instead.

       It currently always returns 0 (for success).

   int feof (FILE * __stream)
       Test the end-of-file flag of stream. This flag can only be cleared by a call to
       clearerr().

   int ferror (FILE * __stream)
       Test the error flag of stream. This flag can only be cleared by a call to clearerr().

   int fflush (FILE * stream)
       Flush stream.

       This is a null operation provided for source-code compatibility only, as the standard IO
       implementation currently does not perform any buffering.

   int fgetc (FILE * __stream)
       The function fgetc reads a character from stream. It returns the character, or EOF in case
       end-of-file was encountered or an error occurred. The routines feof() or ferror() must be
       used to distinguish between both situations.

   char* fgets (char * __str, int __size, FILE * __stream)
       Read at most size - 1 bytes from stream, until a newline character was encountered, and
       store the characters in the buffer pointed to by str. Unless an error was encountered
       while reading, the string will then be terminated with a NUL character.

       If an error was encountered, the function returns NULL and sets the error flag of stream,
       which can be tested using ferror(). Otherwise, a pointer to the string will be returned.

   int fprintf (FILE * __stream, const char * __fmt,  ...)
       The function fprintf performs formatted output to stream. See vfprintf() for details.

   int fprintf_P (FILE * __stream, const char * __fmt,  ...)
       Variant of fprintf() that uses a fmt string that resides in program memory.

   int fputc (int __c, FILE * __stream)
       The function fputc sends the character c (though given as type int) to stream. It returns
       the character, or EOF in case an error occurred.

   int fputs (const char * __str, FILE * __stream)
       Write the string pointed to by str to stream stream.

       Returns 0 on success and EOF on error.

   int fputs_P (const char * __str, FILE * __stream)
       Variant of fputs() where str resides in program memory.

   size_t fread (void * __ptr, size_t __size, size_t __nmemb, FILE * __stream)
       Read nmemb objects, size bytes each, from stream, to the buffer pointed to by ptr.

       Returns the number of objects successfully read, i. e. nmemb unless an input error occured
       or end-of-file was encountered. feof() and ferror() must be used to distinguish between
       these two conditions.

   int fscanf (FILE * __stream, const char * __fmt,  ...)
       The function fscanf performs formatted input, reading the input data from stream.

       See vfscanf() for details.

   int fscanf_P (FILE * __stream, const char * __fmt,  ...)
       Variant of fscanf() using a fmt string in program memory.

   size_t fwrite (const void * __ptr, size_t __size, size_t __nmemb, FILE * __stream)
       Write nmemb objects, size bytes each, to stream. The first byte of the first object is
       referenced by ptr.

       Returns the number of objects successfully written, i. e. nmemb unless an output error
       occured.

   char* gets (char * __str)
       Similar to fgets() except that it will operate on stream stdin, and the trailing newline
       (if any) will not be stored in the string. It is the caller's responsibility to provide
       enough storage to hold the characters read.

   int printf (const char * __fmt,  ...)
       The function printf performs formatted output to stream stdout. See vfprintf() for
       details.

   int printf_P (const char * __fmt,  ...)
       Variant of printf() that uses a fmt string that resides in program memory.

   int puts (const char * __str)
       Write the string pointed to by str, and a trailing newline character, to stdout.

   int puts_P (const char * __str)
       Variant of puts() where str resides in program memory.

   int scanf (const char * __fmt,  ...)
       The function scanf performs formatted input from stream stdin.

       See vfscanf() for details.

   int scanf_P (const char * __fmt,  ...)
       Variant of scanf() where fmt resides in program memory.

   int snprintf (char * __s, size_t __n, const char * __fmt,  ...)
       Like sprintf(), but instead of assuming s to be of infinite size, no more than n
       characters (including the trailing NUL character) will be converted to s.

       Returns the number of characters that would have been written to s if there were enough
       space.

   int snprintf_P (char * __s, size_t __n, const char * __fmt,  ...)
       Variant of snprintf() that uses a fmt string that resides in program memory.

   int sprintf (char * __s, const char * __fmt,  ...)
       Variant of printf() that sends the formatted characters to string s.

   int sprintf_P (char * __s, const char * __fmt,  ...)
       Variant of sprintf() that uses a fmt string that resides in program memory.

   int sscanf (const char * __buf, const char * __fmt,  ...)
       The function sscanf performs formatted input, reading the input data from the buffer
       pointed to by buf.

       See vfscanf() for details.

   int sscanf_P (const char * __buf, const char * __fmt,  ...)
       Variant of sscanf() using a fmt string in program memory.

   int ungetc (int __c, FILE * __stream)
       The ungetc() function pushes the character c (converted to an unsigned char) back onto the
       input stream pointed to by stream. The pushed-back character will be returned by a
       subsequent read on the stream.

       Currently, only a single character can be pushed back onto the stream.

       The ungetc() function returns the character pushed back after the conversion, or EOF if
       the operation fails. If the value of the argument c character equals EOF, the operation
       will fail and the stream will remain unchanged.

   int vfprintf (FILE * __stream, const char * __fmt, va_list __ap)
       vfprintf is the central facility of the printf family of functions. It outputs values to
       stream under control of a format string passed in fmt. The actual values to print are
       passed as a variable argument list ap.

       vfprintf returns the number of characters written to stream, or EOF in case of an error.
       Currently, this will only happen if stream has not been opened with write intent.

       The format string is composed of zero or more directives: ordinary characters (not %),
       which are copied unchanged to the output stream; and conversion specifications, each of
       which results in fetching zero or more subsequent arguments. Each conversion specification
       is introduced by the % character. The arguments must properly correspond (after type
       promotion) with the conversion specifier. After the %, the following appear in sequence:

       • Zero or more of the following flags:

         • # The value should be converted to an 'alternate form'. For c, d, i, s, and u
           conversions, this option has no effect. For o conversions, the precision of the number
           is increased to force the first character of the output string to a zero (except if a
           zero value is printed with an explicit precision of zero). For x and X conversions, a
           non-zero result has the string `0x' (or `0X' for X conversions) prepended to it.
         • 0 (zero) Zero padding. For all conversions, the converted value is padded on the left
           with zeros rather than blanks. If a precision is given with a numeric conversion (d,
           i, o, u, i, x, and X), the 0 flag is ignored.
         • - A negative field width flag; the converted value is to be left adjusted on the field
           boundary. The converted value is padded on the right with blanks, rather than on the
           left with blanks or zeros. A - overrides a 0 if both are given.
         •
         • + A sign must always be placed before a number produced by a signed conversion. A +
           overrides a space if both are used.
       • An optional decimal digit string specifying a minimum field width. If the converted
         value has fewer characters than the field width, it will be padded with spaces on the
         left (or right, if the left-adjustment flag has been given) to fill out the field width.
       • An optional precision, in the form of a period . followed by an optional digit string.
         If the digit string is omitted, the precision is taken as zero. This gives the minimum
         number of digits to appear for d, i, o, u, x, and X conversions, or the maximum number
         of characters to be printed from a string for s conversions.
       • An optional l or h length modifier, that specifies that the argument for the d, i, o, u,
         x, or X conversion is a 'long int' rather than int. The h is ignored, as 'short int' is
         equivalent to int.
       • A character that specifies the type of conversion to be applied.
       The conversion specifiers and their meanings are:
       • diouxX The int (or appropriate variant) argument is converted to signed decimal (d and
         i), unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (x and X)
         notation. The letters 'abcdef' are used for x conversions; the letters 'ABCDEF' are used
         for X conversions. The precision, if any, gives the minimum number of digits that must
         appear; if the converted value requires fewer digits, it is padded on the left with
         zeros.
       • p The void * argument is taken as an unsigned integer, and converted similarly as a %#x
         command would do.
       • c The int argument is converted to an 'unsigned char', and the resulting character is
         written.
       • s The 'char *' argument is expected to be a pointer to an array of character type
         (pointer to a string). Characters from the array are written up to (but not including) a
         terminating NUL character; if a precision is specified, no more than the number
         specified are written. If a precision is given, no null character need be present; if
         the precision is not specified, or is greater than the size of the array, the array must
         contain a terminating NUL character.
       • % A % is written. No argument is converted. The complete conversion specification is
         '%%'.
       • eE The double argument is rounded and converted in the format '[-]d.ddde±dd' where there
         is one digit before the decimal-point character and the number of digits after it is
         equal to the precision; if the precision is missing, it is taken as 6; if the precision
         is zero, no decimal-point character appears. An E conversion uses the letter 'E' (rather
         than 'e') to introduce the exponent. The exponent always contains two digits; if the
         value is zero, the exponent is 00.
       • fF The double argument is rounded and converted to decimal notation in the format
         '[-]ddd.ddd', where the number of digits after the decimal-point character is equal to
         the precision specification. If the precision is missing, it is taken as 6; if the
         precision is explicitly zero, no decimal-point character appears. If a decimal point
         appears, at least one digit appears before it.
       • gG The double argument is converted in style f or e (or F or E for G conversions). The
         precision specifies the number of significant digits. If the precision is missing, 6
         digits are given; if the precision is zero, it is treated as 1. Style e is used if the
         exponent from its conversion is less than -4 or greater than or equal to the precision.
         Trailing zeros are removed from the fractional part of the result; a decimal point
         appears only if it is followed by at least one digit.
       • S Similar to the s format, except the pointer is expected to point to a program-memory
         (ROM) string instead of a RAM string.
       In no case does a non-existent or small field width cause truncation of a numeric field;
       if the result of a conversion is wider than the field width, the field is expanded to
       contain the conversion result.
       Since the full implementation of all the mentioned features becomes fairly large, three
       different flavours of vfprintf() can be selected using linker options. The default
       vfprintf() implements all the mentioned functionality except floating point conversions. A
       minimized version of vfprintf() is available that only implements the very basic integer
       and string conversion facilities, but only the # additional option can be specified using
       conversion flags (these flags are parsed correctly from the format specification, but then
       simply ignored). This version can be requested using the following compiler options:
       -Wl,-u,vfprintf -lprintf_min
       If the full functionality including the floating point conversions is required, the
       following options should be used:
       -Wl,-u,vfprintf -lprintf_flt -lm
       Limitations:

           • The specified width and precision can be at most 255.
       Notes:

           • For floating-point conversions, if you link default or minimized version of
             vfprintf(), the symbol ? will be output and double argument will be skiped. So you
             output below will not be crashed. For default version the width field and the 'pad
             to left' ( symbol minus ) option will work in this case.
           • The hh length modifier is ignored (char argument is promouted to int). More exactly,
             this realization does not check the number of h symbols.
           • But the ll length modifier will to abort the output, as this realization does not
             operate long long arguments.
           • The variable width or precision field (an asterisk * symbol) is not realized and
             will to abort the output.
   int vfprintf_P (FILE * __stream, const char * __fmt, va_list __ap)
       Variant of vfprintf() that uses a fmt string that resides in program memory.
   int vfscanf (FILE * stream, const char * fmt, va_list ap)
       Formatted input. This function is the heart of the scanf family of functions.
       Characters are read from stream and processed in a way described by fmt. Conversion
       results will be assigned to the parameters passed via ap.
       The format string fmt is scanned for conversion specifications. Anything that doesn't
       comprise a conversion specification is taken as text that is matched literally against the
       input. White space in the format string will match any white space in the data (including
       none), all other characters match only itself. Processing is aborted as soon as the data
       and format string no longer match, or there is an error or end-of-file condition on
       stream.
       Most conversions skip leading white space before starting the actual conversion.
       Conversions are introduced with the character %. Possible options can follow the %:
       • a * indicating that the conversion should be performed but the conversion result is to
         be discarded; no parameters will be processed from ap,
       • the character h indicating that the argument is a pointer to short int (rather than
         int),
       • the 2 characters hh indicating that the argument is a pointer to char (rather than int).
       • the character l indicating that the argument is a pointer to long int (rather than int,
         for integer type conversions), or a pointer to double (for floating point conversions),
       In addition, a maximal field width may be specified as a nonzero positive decimal integer,
       which will restrict the conversion to at most this many characters from the input stream.
       This field width is limited to at most 255 characters which is also the default value
       (except for the c conversion that defaults to 1).
       The following conversion flags are supported:
       • % Matches a literal % character. This is not a conversion.
       • d Matches an optionally signed decimal integer; the next pointer must be a pointer to
         int.
       • i Matches an optionally signed integer; the next pointer must be a pointer to int. The
         integer is read in base 16 if it begins with 0x or 0X, in base 8 if it begins with 0,
         and in base 10 otherwise. Only characters that correspond to the base are used.
       • o Matches an octal integer; the next pointer must be a pointer to unsigned int.
       • u Matches an optionally signed decimal integer; the next pointer must be a pointer to
         unsigned int.
       • x Matches an optionally signed hexadecimal integer; the next pointer must be a pointer
         to unsigned int.
       • f Matches an optionally signed floating-point number; the next pointer must be a pointer
         to float.
       • e, g, F, E, G Equivalent to f.
       • s Matches a sequence of non-white-space characters; the next pointer must be a pointer
         to char, and the array must be large enough to accept all the sequence and the
         terminating NUL character. The input string stops at white space or at the maximum field
         width, whichever occurs first.
       • c Matches a sequence of width count characters (default 1); the next pointer must be a
         pointer to char, and there must be enough room for all the characters (no terminating
         NUL is added). The usual skip of leading white space is suppressed. To skip white space
         first, use an explicit space in the format.
       • [ Matches a nonempty sequence of characters from the specified set of accepted
         characters; the next pointer must be a pointer to char, and there must be enough room
         for all the characters in the string, plus a terminating NUL character. The usual skip
         of leading white space is suppressed. The string is to be made up of characters in (or
         not in) a particular set; the set is defined by the characters between the open bracket
         [ character and a close bracket ] character. The set excludes those characters if the
         first character after the open bracket is a circumflex ^. To include a close bracket in
         the set, make it the first character after the open bracket or the circumflex; any other
         position will end the set. The hyphen character - is also special; when placed between
         two other characters, it adds all intervening characters to the set. To include a
         hyphen, make it the last character before the final close bracket. For instance,
         [^]0-9-] means the set of everything except close bracket, zero through nine, and
         hyphen. The string ends with the appearance of a character not in the (or, with a
         circumflex, in) set or when the field width runs out. Note that usage of this conversion
         enlarges the stack expense.
       • p Matches a pointer value (as printed by p in printf()); the next pointer must be a
         pointer to void.
       • n Nothing is expected; instead, the number of characters consumed thus far from the
         input is stored through the next pointer, which must be a pointer to int. This is not a
         conversion, although it can be suppressed with the * flag.
       These functions return the number of input items assigned, which can be fewer than
       provided for, or even zero, in the event of a matching failure. Zero indicates that, while
       there was input available, no conversions were assigned; typically this is due to an
       invalid input character, such as an alphabetic character for a d conversion. The value EOF
       is returned if an input failure occurs before any conversion such as an end-of-file
       occurs. If an error or end-of-file occurs after conversion has begun, the number of
       conversions which were successfully completed is returned.
       By default, all the conversions described above are available except the floating-point
       conversions and the width is limited to 255 characters. The float-point conversion will be
       available in the extended version provided by the library libscanf_flt.a. Also in this
       case the width is not limited (exactly, it is limited to 65535 characters). To link a
       program against the extended version, use the following compiler flags in the link stage:
       -Wl,-u,vfscanf -lscanf_flt -lm
       A third version is available for environments that are tight on space. In addition to the
       restrictions of the standard one, this version implements no %[ specification. This
       version is provided in the library libscanf_min.a, and can be requested using the
       following options in the link stage:
       -Wl,-u,vfscanf -lscanf_min -lm
   int vfscanf_P (FILE * __stream, const char * __fmt, va_list __ap)
       Variant of vfscanf() using a fmt string in program memory.
   int vprintf (const char * __fmt, va_list __ap)
       The function vprintf performs formatted output to stream stdout, taking a variable
       argument list as in vfprintf().
       See vfprintf() for details.
   int vscanf (const char * __fmt, va_list __ap)
       The function vscanf performs formatted input from stream stdin, taking a variable argument
       list as in vfscanf().
       See vfscanf() for details.
   int vsnprintf (char * __s, size_t __n, const char * __fmt, va_list ap)
       Like vsprintf(), but instead of assuming s to be of infinite size, no more than n
       characters (including the trailing NUL character) will be converted to s.
       Returns the number of characters that would have been written to s if there were enough
       space.
   int vsnprintf_P (char * __s, size_t __n, const char * __fmt, va_list ap)
       Variant of vsnprintf() that uses a fmt string that resides in program memory.
   int vsprintf (char * __s, const char * __fmt, va_list ap)
       Like sprintf() but takes a variable argument list for the arguments.
   int vsprintf_P (char * __s, const char * __fmt, va_list ap)
       Variant of vsprintf() that uses a fmt string that resides in program memory.

Author

       Generated automatically by Doxygen for avr-libc from the source code.