.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\&.