.TH "stdio.h" 3avr "Fri Jan 1 2021" "Version 2.0.0" "avr-libc" \" -*- nroff -*-
.ad l
.nh
.SH NAME
stdio.h
.SH SYNOPSIS
.br
.PP
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBstdin\fP   (__iob[0])"
.br
.ti -1c
.RI "#define \fBstdout\fP   (__iob[1])"
.br
.ti -1c
.RI "#define \fBstderr\fP   (__iob[2])"
.br
.ti -1c
.RI "#define \fBEOF\fP   (\-1)"
.br
.ti -1c
.RI "#define \fBfdev_set_udata\fP(stream,  u)   do { (stream)\->udata = u; } while(0)"
.br
.ti -1c
.RI "#define \fBfdev_get_udata\fP(stream)   ((stream)\->udata)"
.br
.ti -1c
.RI "#define \fBfdev_setup_stream\fP(stream,  put,  get,  rwflag)"
.br
.ti -1c
.RI "#define \fB_FDEV_SETUP_READ\fP   __SRD"
.br
.ti -1c
.RI "#define \fB_FDEV_SETUP_WRITE\fP   __SWR"
.br
.ti -1c
.RI "#define \fB_FDEV_SETUP_RW\fP   (__SRD|__SWR)"
.br
.ti -1c
.RI "#define \fB_FDEV_ERR\fP   (\-1)"
.br
.ti -1c
.RI "#define \fB_FDEV_EOF\fP   (\-2)"
.br
.ti -1c
.RI "#define \fBFDEV_SETUP_STREAM\fP(put,  get,  rwflag)"
.br
.ti -1c
.RI "#define \fBfdev_close\fP()"
.br
.ti -1c
.RI "#define \fBputc\fP(__c,  __stream)   \fBfputc\fP(__c, __stream)"
.br
.ti -1c
.RI "#define \fBputchar\fP(__c)   \fBfputc\fP(__c, \fBstdout\fP)"
.br
.ti -1c
.RI "#define \fBgetc\fP(__stream)   \fBfgetc\fP(__stream)"
.br
.ti -1c
.RI "#define \fBgetchar\fP()   \fBfgetc\fP(\fBstdin\fP)"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct __file \fBFILE\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBfclose\fP (\fBFILE\fP *__stream)"
.br
.ti -1c
.RI "int \fBvfprintf\fP (\fBFILE\fP *__stream, const char *__fmt, va_list __ap)"
.br
.ti -1c
.RI "int \fBvfprintf_P\fP (\fBFILE\fP *__stream, const char *__fmt, va_list __ap)"
.br
.ti -1c
.RI "int \fBfputc\fP (int __c, \fBFILE\fP *__stream)"
.br
.ti -1c
.RI "int \fBprintf\fP (const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBprintf_P\fP (const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBvprintf\fP (const char *__fmt, va_list __ap)"
.br
.ti -1c
.RI "int \fBsprintf\fP (char *__s, const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBsprintf_P\fP (char *__s, const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBsnprintf\fP (char *__s, size_t __n, const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBsnprintf_P\fP (char *__s, size_t __n, const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBvsprintf\fP (char *__s, const char *__fmt, va_list ap)"
.br
.ti -1c
.RI "int \fBvsprintf_P\fP (char *__s, const char *__fmt, va_list ap)"
.br
.ti -1c
.RI "int \fBvsnprintf\fP (char *__s, size_t __n, const char *__fmt, va_list ap)"
.br
.ti -1c
.RI "int \fBvsnprintf_P\fP (char *__s, size_t __n, const char *__fmt, va_list ap)"
.br
.ti -1c
.RI "int \fBfprintf\fP (\fBFILE\fP *__stream, const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBfprintf_P\fP (\fBFILE\fP *__stream, const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBfputs\fP (const char *__str, \fBFILE\fP *__stream)"
.br
.ti -1c
.RI "int \fBfputs_P\fP (const char *__str, \fBFILE\fP *__stream)"
.br
.ti -1c
.RI "int \fBputs\fP (const char *__str)"
.br
.ti -1c
.RI "int \fBputs_P\fP (const char *__str)"
.br
.ti -1c
.RI "size_t \fBfwrite\fP (const void *__ptr, size_t __size, size_t __nmemb, \fBFILE\fP *__stream)"
.br
.ti -1c
.RI "int \fBfgetc\fP (\fBFILE\fP *__stream)"
.br
.ti -1c
.RI "int \fBungetc\fP (int __c, \fBFILE\fP *__stream)"
.br
.ti -1c
.RI "char * \fBfgets\fP (char *__str, int __size, \fBFILE\fP *__stream)"
.br
.ti -1c
.RI "char * \fBgets\fP (char *__str)"
.br
.ti -1c
.RI "size_t \fBfread\fP (void *__ptr, size_t __size, size_t __nmemb, \fBFILE\fP *__stream)"
.br
.ti -1c
.RI "void \fBclearerr\fP (\fBFILE\fP *__stream)"
.br
.ti -1c
.RI "int \fBfeof\fP (\fBFILE\fP *__stream)"
.br
.ti -1c
.RI "int \fBferror\fP (\fBFILE\fP *__stream)"
.br
.ti -1c
.RI "int \fBvfscanf\fP (\fBFILE\fP *__stream, const char *__fmt, va_list __ap)"
.br
.ti -1c
.RI "int \fBvfscanf_P\fP (\fBFILE\fP *__stream, const char *__fmt, va_list __ap)"
.br
.ti -1c
.RI "int \fBfscanf\fP (\fBFILE\fP *__stream, const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBfscanf_P\fP (\fBFILE\fP *__stream, const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBscanf\fP (const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBscanf_P\fP (const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBvscanf\fP (const char *__fmt, va_list __ap)"
.br
.ti -1c
.RI "int \fBsscanf\fP (const char *__buf, const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBsscanf_P\fP (const char *__buf, const char *__fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBfflush\fP (\fBFILE\fP *stream)"
.br
.in -1c
.SH "Macro Definition Documentation"
.PP 
.SS "#define _FDEV_EOF   (\-2)"
Return code for an end-of-file condition during device read\&.
.PP
To be used in the get function of \fBfdevopen()\fP\&. 
.SS "#define _FDEV_ERR   (\-1)"
Return code for an error condition during device read\&.
.PP
To be used in the get function of \fBfdevopen()\fP\&. 
.SS "#define _FDEV_SETUP_READ   __SRD"
\fBfdev_setup_stream()\fP with read intent 
.SS "#define _FDEV_SETUP_RW   (__SRD|__SWR)"
\fBfdev_setup_stream()\fP with read/write intent 
.SS "#define _FDEV_SETUP_WRITE   __SWR"
\fBfdev_setup_stream()\fP with write intent 
.SS "#define EOF   (\-1)"
\fCEOF\fP 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\&. 
.SS "#define fdev_close()"
This macro frees up any library resources that might be associated with \fCstream\fP\&. It should be called if \fCstream\fP is no longer needed, right before the application is going to destroy the \fCstream\fP object itself\&.
.PP
(Currently, this macro evaluates to nothing, but this might change in future versions of the library\&.) 
.SS "#define fdev_get_udata(stream)   ((stream)\->udata)"
This macro retrieves a pointer to user defined data from a FILE stream object\&. 
.SS "#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\&.
.PP
The user data can be useful for tracking state in the put and get functions supplied to the \fBfdevopen()\fP function\&. 
.SS "#define FDEV_SETUP_STREAM(put, get, rwflag)"

.PP
Initializer for a user-supplied stdio stream\&. This macro acts similar to \fBfdev_setup_stream()\fP, but it is to be used as the initializer of a variable of type FILE\&.
.PP
The remaining arguments are to be used as explained in \fBfdev_setup_stream()\fP\&. 
.SS "#define fdev_setup_stream(stream, put, get, rwflag)"

.PP
Setup a user-supplied buffer as an stdio stream\&. This macro takes a user-supplied buffer \fCstream\fP, and sets it up as a stream that is valid for stdio operations, similar to one that has been obtained dynamically from \fBfdevopen()\fP\&. The buffer to setup must be of type FILE\&.
.PP
The arguments \fCput\fP and \fCget\fP are identical to those that need to be passed to \fBfdevopen()\fP\&.
.PP
The \fCrwflag\fP 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\&.
.PP
\fBNote\fP
.RS 4
No assignments to the standard streams will be performed by \fBfdev_setup_stream()\fP\&. If standard streams are to be used, these need to be assigned by the user\&. See also under \fBRunning stdio without malloc()\fP\&. 
.RE
.PP

.SS "#define getc(__stream)   \fBfgetc\fP(__stream)"
The macro \fCgetc\fP used to be a 'fast' macro implementation with a functionality identical to \fBfgetc()\fP\&. For space constraints, in \fCavr-libc\fP, it is just an alias for \fCfgetc\fP\&. 
.SS "#define getchar(void)   \fBfgetc\fP(\fBstdin\fP)"
The macro \fCgetchar\fP reads a character from \fCstdin\fP\&. Return values and error handling is identical to \fBfgetc()\fP\&. 
.SS "#define putc(__c, __stream)   \fBfputc\fP(__c, __stream)"
The macro \fCputc\fP used to be a 'fast' macro implementation with a functionality identical to \fBfputc()\fP\&. For space constraints, in \fCavr-libc\fP, it is just an alias for \fCfputc\fP\&. 
.SS "#define putchar(__c)   \fBfputc\fP(__c, \fBstdout\fP)"
The macro \fCputchar\fP sends character \fCc\fP to \fCstdout\fP\&. 
.SS "#define stderr   (__iob[2])"
Stream destined for error output\&. Unless specifically assigned, identical to \fCstdout\fP\&.
.PP
If \fCstderr\fP should point to another stream, the result of another \fC\fBfdevopen()\fP\fP must be explicitly assigned to it without closing the previous \fCstderr\fP (since this would also close \fCstdout\fP)\&. 
.SS "#define stdin   (__iob[0])"
Stream that will be used as an input stream by the simplified functions that don't take a \fCstream\fP argument\&.
.PP
The first stream opened with read intent using \fC\fBfdevopen()\fP\fP will be assigned to \fCstdin\fP\&. 
.SS "#define stdout   (__iob[1])"
Stream that will be used as an output stream by the simplified functions that don't take a \fCstream\fP argument\&.
.PP
The first stream opened with write intent using \fC\fBfdevopen()\fP\fP will be assigned to both, \fCstdin\fP, and \fCstderr\fP\&. 
.SH "Typedef Documentation"
.PP 
.SS "typedef struct __file \fBFILE\fP"
\fCFILE\fP is the opaque structure that is passed around between the various standard IO functions\&. 
.SH "Function Documentation"
.PP 
.SS "void clearerr (\fBFILE\fP * __stream)"
Clear the error and end-of-file flags of \fCstream\fP\&. 
.SS "int fclose (\fBFILE\fP * __stream)"
This function closes \fCstream\fP, and disallows and further IO to and from it\&.
.PP
When using \fBfdevopen()\fP to setup the stream, a call to \fBfclose()\fP is needed in order to free the internal resources allocated\&.
.PP
If the stream has been set up using \fBfdev_setup_stream()\fP or \fBFDEV_SETUP_STREAM()\fP, use \fBfdev_close()\fP instead\&.
.PP
It currently always returns 0 (for success)\&. 
.SS "int feof (\fBFILE\fP * __stream)"
Test the end-of-file flag of \fCstream\fP\&. This flag can only be cleared by a call to \fBclearerr()\fP\&. 
.SS "int ferror (\fBFILE\fP * __stream)"
Test the error flag of \fCstream\fP\&. This flag can only be cleared by a call to \fBclearerr()\fP\&. 
.SS "int fflush (\fBFILE\fP * stream)"
Flush \fCstream\fP\&.
.PP
This is a null operation provided for source-code compatibility only, as the standard IO implementation currently does not perform any buffering\&. 
.SS "int fgetc (\fBFILE\fP * __stream)"
The function \fCfgetc\fP reads a character from \fCstream\fP\&. It returns the character, or \fCEOF\fP in case end-of-file was encountered or an error occurred\&. The routines \fBfeof()\fP or \fBferror()\fP must be used to distinguish between both situations\&. 
.SS "char* fgets (char * __str, int __size, \fBFILE\fP * __stream)"
Read at most \fCsize - 1\fP bytes from \fCstream\fP, until a newline character was encountered, and store the characters in the buffer pointed to by \fCstr\fP\&. Unless an error was encountered while reading, the string will then be terminated with a \fCNUL\fP character\&.
.PP
If an error was encountered, the function returns NULL and sets the error flag of \fCstream\fP, which can be tested using \fBferror()\fP\&. Otherwise, a pointer to the string will be returned\&. 
.SS "int fprintf (\fBFILE\fP * __stream, const char * __fmt,  \&.\&.\&.)"
The function \fCfprintf\fP performs formatted output to \fCstream\fP\&. See \fC\fBvfprintf()\fP\fP for details\&. 
.SS "int fprintf_P (\fBFILE\fP * __stream, const char * __fmt,  \&.\&.\&.)"
Variant of \fC\fBfprintf()\fP\fP that uses a \fCfmt\fP string that resides in program memory\&. 
.SS "int fputc (int __c, \fBFILE\fP * __stream)"
The function \fCfputc\fP sends the character \fCc\fP (though given as type \fCint\fP) to \fCstream\fP\&. It returns the character, or \fCEOF\fP in case an error occurred\&. 
.SS "int fputs (const char * __str, \fBFILE\fP * __stream)"
Write the string pointed to by \fCstr\fP to stream \fCstream\fP\&.
.PP
Returns 0 on success and EOF on error\&. 
.SS "int fputs_P (const char * __str, \fBFILE\fP * __stream)"
Variant of \fBfputs()\fP where \fCstr\fP resides in program memory\&. 
.SS "size_t fread (void * __ptr, size_t __size, size_t __nmemb, \fBFILE\fP * __stream)"
Read \fCnmemb\fP objects, \fCsize\fP bytes each, from \fCstream\fP, to the buffer pointed to by \fCptr\fP\&.
.PP
Returns the number of objects successfully read, i\&. e\&. \fCnmemb\fP unless an input error occured or end-of-file was encountered\&. \fBfeof()\fP and \fBferror()\fP must be used to distinguish between these two conditions\&. 
.SS "int fscanf (\fBFILE\fP * __stream, const char * __fmt,  \&.\&.\&.)"
The function \fCfscanf\fP performs formatted input, reading the input data from \fCstream\fP\&.
.PP
See \fBvfscanf()\fP for details\&. 
.SS "int fscanf_P (\fBFILE\fP * __stream, const char * __fmt,  \&.\&.\&.)"
Variant of \fBfscanf()\fP using a \fCfmt\fP string in program memory\&. 
.SS "size_t fwrite (const void * __ptr, size_t __size, size_t __nmemb, \fBFILE\fP * __stream)"
Write \fCnmemb\fP objects, \fCsize\fP bytes each, to \fCstream\fP\&. The first byte of the first object is referenced by \fCptr\fP\&.
.PP
Returns the number of objects successfully written, i\&. e\&. \fCnmemb\fP unless an output error occured\&. 
.SS "char* gets (char * __str)"
Similar to \fBfgets()\fP except that it will operate on stream \fCstdin\fP, 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\&. 
.SS "int printf (const char * __fmt,  \&.\&.\&.)"
The function \fCprintf\fP performs formatted output to stream \fCstdout\fP\&. See \fC\fBvfprintf()\fP\fP for details\&. 
.SS "int printf_P (const char * __fmt,  \&.\&.\&.)"
Variant of \fC\fBprintf()\fP\fP that uses a \fCfmt\fP string that resides in program memory\&. 
.SS "int puts (const char * __str)"
Write the string pointed to by \fCstr\fP, and a trailing newline character, to \fCstdout\fP\&. 
.SS "int puts_P (const char * __str)"
Variant of \fBputs()\fP where \fCstr\fP resides in program memory\&. 
.SS "int scanf (const char * __fmt,  \&.\&.\&.)"
The function \fCscanf\fP performs formatted input from stream \fCstdin\fP\&.
.PP
See \fBvfscanf()\fP for details\&. 
.SS "int scanf_P (const char * __fmt,  \&.\&.\&.)"
Variant of \fBscanf()\fP where \fCfmt\fP resides in program memory\&. 
.SS "int snprintf (char * __s, size_t __n, const char * __fmt,  \&.\&.\&.)"
Like \fC\fBsprintf()\fP\fP, but instead of assuming \fCs\fP to be of infinite size, no more than \fCn\fP characters (including the trailing NUL character) will be converted to \fCs\fP\&.
.PP
Returns the number of characters that would have been written to \fCs\fP if there were enough space\&. 
.SS "int snprintf_P (char * __s, size_t __n, const char * __fmt,  \&.\&.\&.)"
Variant of \fC\fBsnprintf()\fP\fP that uses a \fCfmt\fP string that resides in program memory\&. 
.SS "int sprintf (char * __s, const char * __fmt,  \&.\&.\&.)"
Variant of \fC\fBprintf()\fP\fP that sends the formatted characters to string \fCs\fP\&. 
.SS "int sprintf_P (char * __s, const char * __fmt,  \&.\&.\&.)"
Variant of \fC\fBsprintf()\fP\fP that uses a \fCfmt\fP string that resides in program memory\&. 
.SS "int sscanf (const char * __buf, const char * __fmt,  \&.\&.\&.)"
The function \fCsscanf\fP performs formatted input, reading the input data from the buffer pointed to by \fCbuf\fP\&.
.PP
See \fBvfscanf()\fP for details\&. 
.SS "int sscanf_P (const char * __buf, const char * __fmt,  \&.\&.\&.)"
Variant of \fBsscanf()\fP using a \fCfmt\fP string in program memory\&. 
.SS "int ungetc (int __c, \fBFILE\fP * __stream)"
The \fBungetc()\fP function pushes the character \fCc\fP (converted to an unsigned char) back onto the input stream pointed to by \fCstream\fP\&. The pushed-back character will be returned by a subsequent read on the stream\&.
.PP
Currently, only a single character can be pushed back onto the stream\&.
.PP
The \fBungetc()\fP function returns the character pushed back after the conversion, or \fCEOF\fP if the operation fails\&. If the value of the argument \fCc\fP character equals \fCEOF\fP, the operation will fail and the stream will remain unchanged\&. 
.SS "int vfprintf (\fBFILE\fP * __stream, const char * __fmt, va_list __ap)"
\fCvfprintf\fP is the central facility of the \fCprintf\fP family of functions\&. It outputs values to \fCstream\fP under control of a format string passed in \fCfmt\fP\&. The actual values to print are passed as a variable argument list \fCap\fP\&.
.PP
\fCvfprintf\fP returns the number of characters written to \fCstream\fP, or \fCEOF\fP in case of an error\&. Currently, this will only happen if \fCstream\fP has not been opened with write intent\&.
.PP
The format string is composed of zero or more directives: ordinary characters (not \fC%\fP), 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 \fC%\fP character\&. The arguments must properly correspond (after type promotion) with the conversion specifier\&. After the \fC%\fP, the following appear in sequence:
.PP
.IP "\(bu" 2
Zero or more of the following flags: 
.PD 0

.IP "  \(bu" 4
\fC#\fP 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\&. 
.IP "  \(bu" 4
\fC0\fP (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\&. 
.IP "  \(bu" 4
\fC-\fP 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\&. 
.IP "  \(bu" 4
' ' (space) A blank should be left before a positive number produced by a signed conversion (d, or i)\&. 
.IP "  \(bu" 4
\fC+\fP A sign must always be placed before a number produced by a signed conversion\&. A + overrides a space if both are used\&. 
.PP

.IP "\(bu" 2
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\&.
.IP "\(bu" 2
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 \fCs\fP conversions\&.
.IP "\(bu" 2
An optional \fCl\fP or \fCh\fP length modifier, that specifies that the argument for the d, i, o, u, x, or X conversion is a \fC'long int'\fP rather than \fCint\fP\&. The \fCh\fP is ignored, as \fC'short int'\fP is equivalent to \fCint\fP\&.
.IP "\(bu" 2
A character that specifies the type of conversion to be applied\&.
.PP
.PP
The conversion specifiers and their meanings are:
.PP
.IP "\(bu" 2
\fCdiouxX\fP 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\&.
.IP "\(bu" 2
\fCp\fP The \fCvoid *\fP argument is taken as an unsigned integer, and converted similarly as a \fC%#x\fP command would do\&.
.IP "\(bu" 2
\fCc\fP The \fCint\fP argument is converted to an \fC'unsigned char'\fP, and the resulting character is written\&.
.IP "\(bu" 2
\fCs\fP The \fC'char *'\fP 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\&.
.IP "\(bu" 2
\fC%\fP A \fC%\fP is written\&. No argument is converted\&. The complete conversion specification is '%%'\&.
.IP "\(bu" 2
\fCeE\fP The double argument is rounded and converted in the format \fC'[-]d\&.ddde±dd'\fP 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 \fIE\fP conversion uses the letter \fC'E'\fP (rather than \fC'e'\fP) to introduce the exponent\&. The exponent always contains two digits; if the value is zero, the exponent is 00\&.
.IP "\(bu" 2
\fCfF\fP The double argument is rounded and converted to decimal notation in the format \fC'[-]ddd\&.ddd'\fP, 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\&.
.IP "\(bu" 2
\fCgG\fP The double argument is converted in style \fCf\fP or \fCe\fP (or \fCF\fP or \fCE\fP for \fCG\fP 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 \fCe\fP 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\&.
.IP "\(bu" 2
\fCS\fP Similar to the \fCs\fP format, except the pointer is expected to point to a program-memory (ROM) string instead of a RAM string\&.
.PP
.PP
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\&.
.PP
Since the full implementation of all the mentioned features becomes fairly large, three different flavours of \fBvfprintf()\fP can be selected using linker options\&. The default \fBvfprintf()\fP implements all the mentioned functionality except floating point conversions\&. A minimized version of \fBvfprintf()\fP is available that only implements the very basic integer and string conversion facilities, but only the \fC#\fP 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 \fBcompiler options\fP:
.PP
.PP
.nf
-Wl,-u,vfprintf -lprintf_min
.fi
.PP
.PP
If the full functionality including the floating point conversions is required, the following options should be used:
.PP
.PP
.nf
-Wl,-u,vfprintf -lprintf_flt -lm
.fi
.PP
.PP
\fBLimitations:\fP
.RS 4

.IP "\(bu" 2
The specified width and precision can be at most 255\&.
.PP
.RE
.PP
\fBNotes:\fP
.RS 4

.IP "\(bu" 2
For floating-point conversions, if you link default or minimized version of \fBvfprintf()\fP, the symbol \fC\fP? 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\&.
.IP "\(bu" 2
The \fChh\fP length modifier is ignored (\fCchar\fP argument is promouted to \fCint\fP)\&. More exactly, this realization does not check the number of \fCh\fP symbols\&.
.IP "\(bu" 2
But the \fCll\fP length modifier will to abort the output, as this realization does not operate \fClong\fP \fClong\fP arguments\&.
.IP "\(bu" 2
The variable width or precision field (an asterisk \fC*\fP symbol) is not realized and will to abort the output\&. 
.PP
.RE
.PP

.SS "int vfprintf_P (\fBFILE\fP * __stream, const char * __fmt, va_list __ap)"
Variant of \fC\fBvfprintf()\fP\fP that uses a \fCfmt\fP string that resides in program memory\&. 
.SS "int vfscanf (\fBFILE\fP * stream, const char * fmt, va_list ap)"
Formatted input\&. This function is the heart of the \fBscanf\fP family of functions\&.
.PP
Characters are read from \fIstream\fP and processed in a way described by \fIfmt\fP\&. Conversion results will be assigned to the parameters passed via \fIap\fP\&.
.PP
The format string \fIfmt\fP 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 \fIstream\fP\&.
.PP
Most conversions skip leading white space before starting the actual conversion\&.
.PP
Conversions are introduced with the character \fB%\fP\&. Possible options can follow the \fB%\fP:
.PP
.IP "\(bu" 2
a \fC*\fP indicating that the conversion should be performed but the conversion result is to be discarded; no parameters will be processed from \fCap\fP,
.IP "\(bu" 2
the character \fCh\fP indicating that the argument is a pointer to \fCshort int\fP (rather than \fCint\fP),
.IP "\(bu" 2
the 2 characters \fChh\fP indicating that the argument is a pointer to \fCchar\fP (rather than \fCint\fP)\&.
.IP "\(bu" 2
the character \fCl\fP indicating that the argument is a pointer to \fClong int\fP (rather than \fCint\fP, for integer type conversions), or a pointer to \fCdouble\fP (for floating point conversions),
.PP
.PP
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 \fCc\fP conversion that defaults to 1)\&.
.PP
The following conversion flags are supported:
.PP
.IP "\(bu" 2
\fC%\fP Matches a literal \fC%\fP character\&. This is not a conversion\&.
.IP "\(bu" 2
\fCd\fP Matches an optionally signed decimal integer; the next pointer must be a pointer to \fCint\fP\&.
.IP "\(bu" 2
\fCi\fP Matches an optionally signed integer; the next pointer must be a pointer to \fCint\fP\&. The integer is read in base 16 if it begins with \fB0x\fP or \fB0X\fP, in base 8 if it begins with \fB0\fP, and in base 10 otherwise\&. Only characters that correspond to the base are used\&.
.IP "\(bu" 2
\fCo\fP Matches an octal integer; the next pointer must be a pointer to \fCunsigned int\fP\&.
.IP "\(bu" 2
\fCu\fP Matches an optionally signed decimal integer; the next pointer must be a pointer to \fCunsigned int\fP\&.
.IP "\(bu" 2
\fCx\fP Matches an optionally signed hexadecimal integer; the next pointer must be a pointer to \fCunsigned int\fP\&.
.IP "\(bu" 2
\fCf\fP Matches an optionally signed floating-point number; the next pointer must be a pointer to \fCfloat\fP\&.
.IP "\(bu" 2
\fCe, g, F, E, G\fP Equivalent to \fCf\fP\&.
.IP "\(bu" 2
\fCs\fP Matches a sequence of non-white-space characters; the next pointer must be a pointer to \fCchar\fP, and the array must be large enough to accept all the sequence and the terminating \fCNUL\fP character\&. The input string stops at white space or at the maximum field width, whichever occurs first\&.
.IP "\(bu" 2
\fCc\fP Matches a sequence of width count characters (default 1); the next pointer must be a pointer to \fCchar\fP, and there must be enough room for all the characters (no terminating \fCNUL\fP is added)\&. The usual skip of leading white space is suppressed\&. To skip white space first, use an explicit space in the format\&.
.IP "\(bu" 2
\fC\fP[ Matches a nonempty sequence of characters from the specified set of accepted characters; the next pointer must be a pointer to \fCchar\fP, and there must be enough room for all the characters in the string, plus a terminating \fCNUL\fP 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 \fC\fP[ character and a close bracket \fC\fP] character\&. The set excludes those characters if the first character after the open bracket is a circumflex \fC^\fP\&. 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 \fC-\fP 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, \fC[^]0-9-]\fP means the set of \fIeverything except close bracket, zero through nine, and hyphen\fP\&. 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\&.
.IP "\(bu" 2
\fCp\fP Matches a pointer value (as printed by \fCp\fP in \fBprintf()\fP); the next pointer must be a pointer to \fCvoid\fP\&.
.IP "\(bu" 2
\fCn\fP 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 \fCint\fP\&. This is not a conversion, although it can be suppressed with the \fC*\fP flag\&.
.PP
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 \fCd\fP conversion\&. The value \fCEOF\fP 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\&.
.PP
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 \fClibscanf_flt\&.a\fP\&. 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:
.PP
.PP
.PP
.nf
-Wl,-u,vfscanf -lscanf_flt -lm
.fi
.PP
.PP
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 \fC%[\fP specification\&. This version is provided in the library \fClibscanf_min\&.a\fP, and can be requested using the following options in the link stage:
.PP
.PP
.nf
-Wl,-u,vfscanf -lscanf_min -lm
.fi
.PP
 
.SS "int vfscanf_P (\fBFILE\fP * __stream, const char * __fmt, va_list __ap)"
Variant of \fBvfscanf()\fP using a \fCfmt\fP string in program memory\&. 
.SS "int vprintf (const char * __fmt, va_list __ap)"
The function \fCvprintf\fP performs formatted output to stream \fCstdout\fP, taking a variable argument list as in \fBvfprintf()\fP\&.
.PP
See \fBvfprintf()\fP for details\&. 
.SS "int vscanf (const char * __fmt, va_list __ap)"
The function \fCvscanf\fP performs formatted input from stream \fCstdin\fP, taking a variable argument list as in \fBvfscanf()\fP\&.
.PP
See \fBvfscanf()\fP for details\&. 
.SS "int vsnprintf (char * __s, size_t __n, const char * __fmt, va_list ap)"
Like \fC\fBvsprintf()\fP\fP, but instead of assuming \fCs\fP to be of infinite size, no more than \fCn\fP characters (including the trailing NUL character) will be converted to \fCs\fP\&.
.PP
Returns the number of characters that would have been written to \fCs\fP if there were enough space\&. 
.SS "int vsnprintf_P (char * __s, size_t __n, const char * __fmt, va_list ap)"
Variant of \fC\fBvsnprintf()\fP\fP that uses a \fCfmt\fP string that resides in program memory\&. 
.SS "int vsprintf (char * __s, const char * __fmt, va_list ap)"
Like \fC\fBsprintf()\fP\fP but takes a variable argument list for the arguments\&. 
.SS "int vsprintf_P (char * __s, const char * __fmt, va_list ap)"
Variant of \fC\fBvsprintf()\fP\fP that uses a \fCfmt\fP string that resides in program memory\&. 
.SH "Author"
.PP 
Generated automatically by Doxygen for avr-libc from the source code\&.