AVR Libc Home Page AVRs AVR Libc Development Pages
Main Page User Manual Library Reference FAQ Alphabetical Index Example Projects

stdio.h
Go to the documentation of this file.
00001 /* Copyright (c) 2002, 2005, 2007 Joerg Wunsch
00002    All rights reserved.
00003 
00004    Portions of documentation Copyright (c) 1990, 1991, 1993
00005    The Regents of the University of California.
00006 
00007    All rights reserved.
00008 
00009    Redistribution and use in source and binary forms, with or without
00010    modification, are permitted provided that the following conditions are met:
00011 
00012    * Redistributions of source code must retain the above copyright
00013      notice, this list of conditions and the following disclaimer.
00014 
00015    * Redistributions in binary form must reproduce the above copyright
00016      notice, this list of conditions and the following disclaimer in
00017      the documentation and/or other materials provided with the
00018      distribution.
00019 
00020    * Neither the name of the copyright holders nor the names of
00021      contributors may be used to endorse or promote products derived
00022      from this software without specific prior written permission.
00023 
00024   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00025   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00026   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00027   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00028   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00029   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00030   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00031   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00032   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00033   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00034   POSSIBILITY OF SUCH DAMAGE.
00035 
00036   $Id: stdio_8h_source.html,v 1.1.1.4 2012/01/03 16:04:22 joerg_wunsch Exp $
00037 */
00038 
00039 #ifndef _STDIO_H_
00040 #define _STDIO_H_ 1
00041 
00042 #ifndef __ASSEMBLER__
00043 
00044 #include <inttypes.h>
00045 #include <stdarg.h>
00046 
00047 #define __need_NULL
00048 #define __need_size_t
00049 #include <stddef.h>
00050 
00051 /** \file */
00052 /** \defgroup avr_stdio <stdio.h>: Standard IO facilities
00053     \code #include <stdio.h> \endcode
00054 
00055     <h3>Introduction to the Standard IO facilities</h3>
00056 
00057     This file declares the standard IO facilities that are implemented
00058     in \c avr-libc.  Due to the nature of the underlying hardware,
00059     only a limited subset of standard IO is implemented.  There is no
00060     actual file implementation available, so only device IO can be
00061     performed.  Since there's no operating system, the application
00062     needs to provide enough details about their devices in order to
00063     make them usable by the standard IO facilities.
00064 
00065     Due to space constraints, some functionality has not been
00066     implemented at all (like some of the \c printf conversions that
00067     have been left out).  Nevertheless, potential users of this
00068     implementation should be warned: the \c printf and \c scanf families of functions, although
00069     usually associated with presumably simple things like the
00070     famous "Hello, world!" program, are actually fairly complex
00071     which causes their inclusion to eat up a fair amount of code space.
00072     Also, they are not fast due to the nature of interpreting the
00073     format string at run-time.  Whenever possible, resorting to the
00074     (sometimes non-standard) predetermined conversion facilities that are
00075     offered by avr-libc will usually cost much less in terms of speed
00076     and code size.
00077 
00078     <h3>Tunable options for code size vs. feature set</h3>
00079 
00080     In order to allow programmers a code size vs. functionality tradeoff,
00081     the function vfprintf() which is the heart of the printf family can be
00082     selected in different flavours using linker options.  See the
00083     documentation of vfprintf() for a detailed description.  The same
00084     applies to vfscanf() and the \c scanf family of functions.
00085 
00086     <h3>Outline of the chosen API</h3>
00087 
00088     The standard streams \c stdin, \c stdout, and \c stderr are
00089     provided, but contrary to the C standard, since avr-libc has no
00090     knowledge about applicable devices, these streams are not already
00091     pre-initialized at application startup.  Also, since there is no
00092     notion of "file" whatsoever to avr-libc, there is no function
00093     \c fopen() that could be used to associate a stream to some device.
00094     (See \ref stdio_note1 "note 1".)  Instead, the function \c fdevopen()
00095     is provided to associate a stream to a device, where the device
00096     needs to provide a function to send a character, to receive a
00097     character, or both.  There is no differentiation between "text" and
00098     "binary" streams inside avr-libc.  Character \c \\n is sent
00099     literally down to the device's \c put() function.  If the device
00100     requires a carriage return (\c \\r) character to be sent before
00101     the linefeed, its \c put() routine must implement this (see
00102     \ref stdio_note2 "note 2").
00103 
00104     As an alternative method to fdevopen(), the macro
00105     fdev_setup_stream() might be used to setup a user-supplied FILE
00106     structure.
00107 
00108     It should be noted that the automatic conversion of a newline
00109     character into a carriage return - newline sequence breaks binary
00110     transfers.  If binary transfers are desired, no automatic
00111     conversion should be performed, but instead any string that aims
00112     to issue a CR-LF sequence must use <tt>"\r\n"</tt> explicitly.
00113 
00114     For convenience, the first call to \c fdevopen() that opens a
00115     stream for reading will cause the resulting stream to be aliased
00116     to \c stdin.  Likewise, the first call to \c fdevopen() that opens
00117     a stream for writing will cause the resulting stream to be aliased
00118     to both, \c stdout, and \c stderr.  Thus, if the open was done
00119     with both, read and write intent, all three standard streams will
00120     be identical.  Note that these aliases are indistinguishable from
00121     each other, thus calling \c fclose() on such a stream will also
00122     effectively close all of its aliases (\ref stdio_note3 "note 3").
00123 
00124     It is possible to tie additional user data to a stream, using
00125     fdev_set_udata().  The backend put and get functions can then
00126     extract this user data using fdev_get_udata(), and act
00127     appropriately.  For example, a single put function could be used
00128     to talk to two different UARTs that way, or the put and get
00129     functions could keep internal state between calls there.
00130 
00131     <h3>Format strings in flash ROM</h3>
00132 
00133     All the \c printf and \c scanf family functions come in two flavours: the
00134     standard name, where the format string is expected to be in
00135     SRAM, as well as a version with the suffix "_P" where the format
00136     string is expected to reside in the flash ROM.  The macro
00137     \c PSTR (explained in \ref avr_pgmspace) becomes very handy
00138     for declaring these format strings.
00139 
00140     \anchor stdio_without_malloc
00141     <h3>Running stdio without malloc()</h3>
00142 
00143     By default, fdevopen() requires malloc().  As this is often
00144     not desired in the limited environment of a microcontroller, an
00145     alternative option is provided to run completely without malloc().
00146 
00147     The macro fdev_setup_stream() is provided to prepare a
00148     user-supplied FILE buffer for operation with stdio.
00149 
00150     <h4>Example</h4>
00151 
00152     \code
00153     #include <stdio.h>
00154 
00155     static int uart_putchar(char c, FILE *stream);
00156 
00157     static FILE mystdout = FDEV_SETUP_STREAM(uart_putchar, NULL,
00158                                              _FDEV_SETUP_WRITE);
00159 
00160     static int
00161     uart_putchar(char c, FILE *stream)
00162     {
00163 
00164       if (c == '\n')
00165         uart_putchar('\r', stream);
00166       loop_until_bit_is_set(UCSRA, UDRE);
00167       UDR = c;
00168       return 0;
00169     }
00170 
00171     int
00172     main(void)
00173     {
00174       init_uart();
00175       stdout = &mystdout;
00176       printf("Hello, world!\n");
00177 
00178       return 0;
00179     }
00180     \endcode
00181 
00182     This example uses the initializer form FDEV_SETUP_STREAM() rather
00183     than the function-like fdev_setup_stream(), so all data
00184     initialization happens during C start-up.
00185 
00186     If streams initialized that way are no longer needed, they can be
00187     destroyed by first calling the macro fdev_close(), and then
00188     destroying the object itself.  No call to fclose() should be
00189     issued for these streams.  While calling fclose() itself is
00190     harmless, it will cause an undefined reference to free() and thus
00191     cause the linker to link the malloc module into the application.
00192 
00193     <h3>Notes</h3>
00194 
00195     \anchor stdio_note1 \par Note 1:
00196     It might have been possible to implement a device abstraction that
00197     is compatible with \c fopen() but since this would have required
00198     to parse a string, and to take all the information needed either
00199     out of this string, or out of an additional table that would need to be
00200     provided by the application, this approach was not taken.
00201 
00202     \anchor stdio_note2 \par Note 2:
00203     This basically follows the Unix approach: if a device such as a
00204     terminal needs special handling, it is in the domain of the
00205     terminal device driver to provide this functionality.  Thus, a
00206     simple function suitable as \c put() for \c fdevopen() that talks
00207     to a UART interface might look like this:
00208 
00209     \code
00210     int
00211     uart_putchar(char c, FILE *stream)
00212     {
00213 
00214       if (c == '\n')
00215         uart_putchar('\r');
00216       loop_until_bit_is_set(UCSRA, UDRE);
00217       UDR = c;
00218       return 0;
00219     }
00220     \endcode
00221 
00222     \anchor stdio_note3 \par Note 3:
00223     This implementation has been chosen because the cost of maintaining
00224     an alias is considerably smaller than the cost of maintaining full
00225     copies of each stream.  Yet, providing an implementation that offers
00226     the complete set of standard streams was deemed to be useful.  Not
00227     only that writing \c printf() instead of <tt>fprintf(mystream, ...)</tt>
00228     saves typing work, but since avr-gcc needs to resort to pass all
00229     arguments of variadic functions on the stack (as opposed to passing
00230     them in registers for functions that take a fixed number of
00231     parameters), the ability to pass one parameter less by implying
00232     \c stdin or stdout will also save some execution time.
00233 */
00234 
00235 #if !defined(__DOXYGEN__)
00236 
00237 /*
00238  * This is an internal structure of the library that is subject to be
00239  * changed without warnings at any time.  Please do *never* reference
00240  * elements of it beyond by using the official interfaces provided.
00241  */
00242 struct __file {
00243         char    *buf;           /* buffer pointer */
00244         unsigned char unget;    /* ungetc() buffer */
00245         uint8_t flags;          /* flags, see below */
00246 #define __SRD   0x0001          /* OK to read */
00247 #define __SWR   0x0002          /* OK to write */
00248 #define __SSTR  0x0004          /* this is an sprintf/snprintf string */
00249 #define __SPGM  0x0008          /* fmt string is in progmem */
00250 #define __SERR  0x0010          /* found error */
00251 #define __SEOF  0x0020          /* found EOF */
00252 #define __SUNGET 0x040          /* ungetc() happened */
00253 #define __SMALLOC 0x80          /* handle is malloc()ed */
00254 #if 0
00255 /* possible future extensions, will require uint16_t flags */
00256 #define __SRW   0x0100          /* open for reading & writing */
00257 #define __SLBF  0x0200          /* line buffered */
00258 #define __SNBF  0x0400          /* unbuffered */
00259 #define __SMBF  0x0800          /* buf is from malloc */
00260 #endif
00261         int     size;           /* size of buffer */
00262         int     len;            /* characters read or written so far */
00263         int     (*put)(char, struct __file *);  /* function to write one char to device */
00264         int     (*get)(struct __file *);        /* function to read one char from device */
00265         void    *udata;         /* User defined and accessible data. */
00266 };
00267 
00268 #endif /* not __DOXYGEN__ */
00269 
00270 /*@{*/
00271 /**
00272    \c FILE is the opaque structure that is passed around between the
00273    various standard IO functions.
00274 */
00275 #define FILE    struct __file
00276 
00277 /**
00278    Stream that will be used as an input stream by the simplified
00279    functions that don't take a \c stream argument.
00280 
00281    The first stream opened with read intent using \c fdevopen()
00282    will be assigned to \c stdin.
00283 */
00284 #define stdin (__iob[0])
00285 
00286 /**
00287    Stream that will be used as an output stream by the simplified
00288    functions that don't take a \c stream argument.
00289 
00290    The first stream opened with write intent using \c fdevopen()
00291    will be assigned to both, \c stdin, and \c stderr.
00292 */
00293 #define stdout (__iob[1])
00294 
00295 /**
00296    Stream destined for error output.  Unless specifically assigned,
00297    identical to \c stdout.
00298 
00299    If \c stderr should point to another stream, the result of
00300    another \c fdevopen() must be explicitly assigned to it without
00301    closing the previous \c stderr (since this would also close
00302    \c stdout).
00303 */
00304 #define stderr (__iob[2])
00305 
00306 /**
00307    \c EOF declares the value that is returned by various standard IO
00308    functions in case of an error.  Since the AVR platform (currently)
00309    doesn't contain an abstraction for actual files, its origin as
00310    "end of file" is somewhat meaningless here.
00311 */
00312 #define EOF     (-1)
00313 
00314 /** This macro inserts a pointer to user defined data into a FILE
00315     stream object.
00316 
00317     The user data can be useful for tracking state in the put and get
00318     functions supplied to the fdevopen() function. */
00319 #define fdev_set_udata(stream, u) do { (stream)->udata = u; } while(0)
00320 
00321 /** This macro retrieves a pointer to user defined data from a FILE
00322     stream object. */
00323 #define fdev_get_udata(stream) ((stream)->udata)
00324 
00325 #if defined(__DOXYGEN__)
00326 /**
00327    \brief Setup a user-supplied buffer as an stdio stream
00328 
00329    This macro takes a user-supplied buffer \c stream, and sets it up
00330    as a stream that is valid for stdio operations, similar to one that
00331    has been obtained dynamically from fdevopen(). The buffer to setup
00332    must be of type FILE.
00333 
00334    The arguments \c put and \c get are identical to those that need to
00335    be passed to fdevopen().
00336 
00337    The \c rwflag argument can take one of the values _FDEV_SETUP_READ,
00338    _FDEV_SETUP_WRITE, or _FDEV_SETUP_RW, for read, write, or read/write
00339    intent, respectively.
00340 
00341    \note No assignments to the standard streams will be performed by
00342    fdev_setup_stream().  If standard streams are to be used, these
00343    need to be assigned by the user.  See also under
00344    \ref stdio_without_malloc "Running stdio without malloc()".
00345  */
00346 #define fdev_setup_stream(stream, put, get, rwflag)
00347 #else  /* !DOXYGEN */
00348 #define fdev_setup_stream(stream, p, g, f) \
00349         do { \
00350                 (stream)->put = p; \
00351                 (stream)->get = g; \
00352                 (stream)->flags = f; \
00353                 (stream)->udata = 0; \
00354         } while(0)
00355 #endif /* DOXYGEN */
00356 
00357 #define _FDEV_SETUP_READ  __SRD /**< fdev_setup_stream() with read intent */
00358 #define _FDEV_SETUP_WRITE __SWR /**< fdev_setup_stream() with write intent */
00359 #define _FDEV_SETUP_RW    (__SRD|__SWR) /**< fdev_setup_stream() with read/write intent */
00360 
00361 /**
00362  * Return code for an error condition during device read.
00363  *
00364  * To be used in the get function of fdevopen().
00365  */
00366 #define _FDEV_ERR (-1)
00367 
00368 /**
00369  * Return code for an end-of-file condition during device read.
00370  *
00371  * To be used in the get function of fdevopen().
00372  */
00373 #define _FDEV_EOF (-2)
00374 
00375 #if defined(__DOXYGEN__)
00376 /**
00377    \brief Initializer for a user-supplied stdio stream
00378 
00379    This macro acts similar to fdev_setup_stream(), but it is to be
00380    used as the initializer of a variable of type FILE.
00381 
00382    The remaining arguments are to be used as explained in
00383    fdev_setup_stream().
00384  */
00385 #define FDEV_SETUP_STREAM(put, get, rwflag)
00386 #else  /* !DOXYGEN */
00387 #define FDEV_SETUP_STREAM(p, g, f) \
00388         { \
00389                 .put = p, \
00390                 .get = g, \
00391                 .flags = f, \
00392                 .udata = 0, \
00393         }
00394 #endif /* DOXYGEN */
00395 
00396 #ifdef __cplusplus
00397 extern "C" {
00398 #endif
00399 
00400 #if !defined(__DOXYGEN__)
00401 /*
00402  * Doxygen documentation can be found in fdevopen.c.
00403  */
00404 
00405 extern struct __file *__iob[];
00406 
00407 #if defined(__STDIO_FDEVOPEN_COMPAT_12)
00408 /*
00409  * Declare prototype for the discontinued version of fdevopen() that
00410  * has been in use up to avr-libc 1.2.x.  The new implementation has
00411  * some backwards compatibility with the old version.
00412  */
00413 extern FILE *fdevopen(int (*__put)(char), int (*__get)(void),
00414                       int __opts __attribute__((unused)));
00415 #else  /* !defined(__STDIO_FDEVOPEN_COMPAT_12) */
00416 /* New prototype for avr-libc 1.4 and above. */
00417 extern FILE *fdevopen(int (*__put)(char, FILE*), int (*__get)(FILE*));
00418 #endif /* defined(__STDIO_FDEVOPEN_COMPAT_12) */
00419 
00420 #endif /* not __DOXYGEN__ */
00421 
00422 /**
00423    This function closes \c stream, and disallows and further
00424    IO to and from it.
00425 
00426    When using fdevopen() to setup the stream, a call to fclose() is
00427    needed in order to free the internal resources allocated.
00428 
00429    If the stream has been set up using fdev_setup_stream() or
00430    FDEV_SETUP_STREAM(), use fdev_close() instead.
00431 
00432    It currently always returns 0 (for success).
00433 */
00434 extern int      fclose(FILE *__stream);
00435 
00436 /**
00437    This macro frees up any library resources that might be associated
00438    with \c stream.  It should be called if \c stream is no longer
00439    needed, right before the application is going to destroy the
00440    \c stream object itself.
00441 
00442    (Currently, this macro evaluates to nothing, but this might change
00443    in future versions of the library.)
00444 */
00445 #if defined(__DOXYGEN__)
00446 # define fdev_close()
00447 #else
00448 # define fdev_close() ((void)0)
00449 #endif
00450 
00451 /**
00452    \c vfprintf is the central facility of the \c printf family of
00453    functions.  It outputs values to \c stream under control of a
00454    format string passed in \c fmt.  The actual values to print are
00455    passed as a variable argument list \c ap.
00456 
00457    \c vfprintf returns the number of characters written to \c stream,
00458    or \c EOF in case of an error.  Currently, this will only happen
00459    if \c stream has not been opened with write intent.
00460 
00461    The format string is composed of zero or more directives: ordinary
00462    characters (not \c %), which are copied unchanged to the output
00463    stream; and conversion specifications, each of which results in
00464    fetching zero or more subsequent arguments.  Each conversion
00465    specification is introduced by the \c % character.  The arguments must
00466    properly correspond (after type promotion) with the conversion
00467    specifier.  After the \c %, the following appear in sequence:
00468 
00469    - Zero or more of the following flags:
00470       <ul>
00471       <li> \c # The value should be converted to an "alternate form".  For
00472             c, d, i, s, and u conversions, this option has no effect.
00473             For o conversions, the precision of the number is
00474             increased to force the first character of the output
00475             string to a zero (except if a zero value is printed with
00476             an explicit precision of zero).  For x and X conversions,
00477             a non-zero result has the string `0x' (or `0X' for X
00478             conversions) prepended to it.</li>
00479       <li> \c 0 (zero) Zero padding.  For all conversions, the converted
00480             value is padded on the left with zeros rather than blanks.
00481             If a precision is given with a numeric conversion (d, i,
00482             o, u, i, x, and X), the 0 flag is ignored.</li>
00483       <li> \c - A negative field width flag; the converted value is to be
00484             left adjusted on the field boundary.  The converted value
00485             is padded on the right with blanks, rather than on the
00486             left with blanks or zeros.  A - overrides a 0 if both are
00487             given.</li>
00488       <li> ' ' (space) A blank should be left before a positive number
00489             produced by a signed conversion (d, or i).</li>
00490       <li> \c + A sign must always be placed before a number produced by a
00491             signed conversion.  A + overrides a space if both are
00492             used.</li>
00493       </ul>
00494       
00495    -   An optional decimal digit string specifying a minimum field width.
00496        If the converted value has fewer characters than the field width, it
00497        will be padded with spaces on the left (or right, if the left-adjustment
00498        flag has been given) to fill out the field width.
00499    -   An optional precision, in the form of a period . followed by an
00500        optional digit string.  If the digit string is omitted, the
00501        precision is taken as zero.  This gives the minimum number of
00502        digits to appear for d, i, o, u, x, and X conversions, or the
00503        maximum number of characters to be printed from a string for \c s
00504        conversions.
00505    -   An optional \c l or \c h length modifier, that specifies that the
00506        argument for the d, i, o, u, x, or X conversion is a \c "long int"
00507        rather than \c int. The \c h is ignored, as \c "short int" is
00508        equivalent to \c int.
00509    -   A character that specifies the type of conversion to be applied.
00510 
00511    The conversion specifiers and their meanings are:
00512 
00513    - \c diouxX The int (or appropriate variant) argument is converted
00514            to signed decimal (d and i), unsigned octal (o), unsigned
00515            decimal (u), or unsigned hexadecimal (x and X) notation.
00516            The letters "abcdef" are used for x conversions; the
00517            letters "ABCDEF" are used for X conversions.  The
00518            precision, if any, gives the minimum number of digits that
00519            must appear; if the converted value requires fewer digits,
00520            it is padded on the left with zeros.
00521    - \c p  The <tt>void *</tt> argument is taken as an unsigned integer,
00522            and converted similarly as a <tt>%\#x</tt> command would do.
00523    - \c c  The \c int argument is converted to an \c "unsigned char", and the
00524            resulting character is written.
00525    - \c s  The \c "char *" argument is expected to be a pointer to an array
00526            of character type (pointer to a string).  Characters from
00527            the array are written up to (but not including) a
00528            terminating NUL character; if a precision is specified, no
00529            more than the number specified are written.  If a precision
00530            is given, no null character need be present; if the
00531            precision is not specified, or is greater than the size of
00532            the array, the array must contain a terminating NUL
00533            character.
00534    - \c %  A \c % is written.  No argument is converted.  The complete
00535            conversion specification is "%%".
00536    - \c eE The double argument is rounded and converted in the format
00537            \c "[-]d.ddde┬▒dd" where there is one digit before the
00538            decimal-point character and the number of digits after it
00539            is equal to the precision; if the precision is missing, it
00540            is taken as 6; if the precision is zero, no decimal-point
00541            character appears.  An \e E conversion uses the letter \c 'E'
00542            (rather than \c 'e') to introduce the exponent.  The exponent
00543            always contains two digits; if the value is zero,
00544            the exponent is 00.
00545    - \c fF The double argument is rounded and converted to decimal notation
00546            in the format \c "[-]ddd.ddd", where the number of digits after the
00547            decimal-point character is equal to the precision specification.
00548            If the precision is missing, it is taken as 6; if the precision
00549            is explicitly zero, no decimal-point character appears.  If a
00550            decimal point appears, at least one digit appears before it.
00551    - \c gG The double argument is converted in style \c f or \c e (or
00552            \c F or \c E for \c G conversions).  The precision
00553            specifies the number of significant digits.  If the
00554            precision is missing, 6 digits are given; if the precision
00555            is zero, it is treated as 1.  Style \c e is used if the
00556            exponent from its conversion is less than -4 or greater
00557            than or equal to the precision.  Trailing zeros are removed
00558            from the fractional part of the result; a decimal point
00559            appears only if it is followed by at least one digit.
00560    - \c S  Similar to the \c s format, except the pointer is expected to
00561            point to a program-memory (ROM) string instead of a RAM string.
00562 
00563    In no case does a non-existent or small field width cause truncation of a
00564    numeric field; if the result of a conversion is wider than the field
00565    width, the field is expanded to contain the conversion result.
00566 
00567    Since the full implementation of all the mentioned features becomes
00568    fairly large, three different flavours of vfprintf() can be
00569    selected using linker options.  The default vfprintf() implements
00570    all the mentioned functionality except floating point conversions.
00571    A minimized version of vfprintf() is available that only implements
00572    the very basic integer and string conversion facilities, but only
00573    the \c # additional option can be specified using conversion
00574    flags (these flags are parsed correctly from the format
00575    specification, but then simply ignored).  This version can be
00576    requested using the following \ref gcc_minusW "compiler options":
00577 
00578    \code
00579    -Wl,-u,vfprintf -lprintf_min
00580    \endcode
00581 
00582    If the full functionality including the floating point conversions
00583    is required, the following options should be used:
00584 
00585    \code
00586    -Wl,-u,vfprintf -lprintf_flt -lm
00587    \endcode
00588 
00589    \par Limitations:
00590    - The specified width and precision can be at most 255.
00591 
00592    \par Notes:
00593    - For floating-point conversions, if you link default or minimized
00594      version of vfprintf(), the symbol \c ? will be output and double
00595      argument will be skiped. So you output below will not be crashed.
00596      For default version the width field and the "pad to left" ( symbol
00597      minus ) option will work in this case.
00598    - The \c hh length modifier is ignored (\c char argument is
00599      promouted to \c int). More exactly, this realization does not check
00600      the number of \c h symbols.
00601    - But the \c ll length modifier will to abort the output, as this
00602      realization does not operate \c long \c long arguments.
00603    - The variable width or precision field (an asterisk \c * symbol)
00604      is not realized and will to abort the output.
00605 
00606  */
00607 
00608 extern int      vfprintf(FILE *__stream, const char *__fmt, va_list __ap);
00609 
00610 /**
00611    Variant of \c vfprintf() that uses a \c fmt string that resides
00612    in program memory.
00613 */
00614 extern int      vfprintf_P(FILE *__stream, const char *__fmt, va_list __ap);
00615 
00616 /**
00617    The function \c fputc sends the character \c c (though given as type
00618    \c int) to \c stream.  It returns the character, or \c EOF in case
00619    an error occurred.
00620 */
00621 extern int      fputc(int __c, FILE *__stream);
00622 
00623 #if !defined(__DOXYGEN__)
00624 
00625 /* putc() function implementation, required by standard */
00626 extern int      putc(int __c, FILE *__stream);
00627 
00628 /* putchar() function implementation, required by standard */
00629 extern int      putchar(int __c);
00630 
00631 #endif /* not __DOXYGEN__ */
00632 
00633 /**
00634    The macro \c putc used to be a "fast" macro implementation with a
00635    functionality identical to fputc().  For space constraints, in
00636    \c avr-libc, it is just an alias for \c fputc.
00637 */
00638 #define putc(__c, __stream) fputc(__c, __stream)
00639 
00640 /**
00641    The macro \c putchar sends character \c c to \c stdout.
00642 */
00643 #define putchar(__c) fputc(__c, stdout)
00644 
00645 /**
00646    The function \c printf performs formatted output to stream
00647    \c stdout.  See \c vfprintf() for details.
00648 */
00649 extern int      printf(const char *__fmt, ...);
00650 
00651 /**
00652    Variant of \c printf() that uses a \c fmt string that resides
00653    in program memory.
00654 */
00655 extern int      printf_P(const char *__fmt, ...);
00656 
00657 /**
00658    The function \c vprintf performs formatted output to stream
00659    \c stdout, taking a variable argument list as in vfprintf().
00660 
00661    See vfprintf() for details.
00662 */
00663 extern int      vprintf(const char *__fmt, va_list __ap);
00664 
00665 /**
00666    Variant of \c printf() that sends the formatted characters
00667    to string \c s.
00668 */
00669 extern int      sprintf(char *__s, const char *__fmt, ...);
00670 
00671 /**
00672    Variant of \c sprintf() that uses a \c fmt string that resides
00673    in program memory.
00674 */
00675 extern int      sprintf_P(char *__s, const char *__fmt, ...);
00676 
00677 /**
00678    Like \c sprintf(), but instead of assuming \c s to be of infinite
00679    size, no more than \c n characters (including the trailing NUL
00680    character) will be converted to \c s.
00681 
00682    Returns the number of characters that would have been written to
00683    \c s if there were enough space.
00684 */
00685 extern int      snprintf(char *__s, size_t __n, const char *__fmt, ...);
00686 
00687 /**
00688    Variant of \c snprintf() that uses a \c fmt string that resides
00689    in program memory.
00690 */
00691 extern int      snprintf_P(char *__s, size_t __n, const char *__fmt, ...);
00692 
00693 /**
00694    Like \c sprintf() but takes a variable argument list for the
00695    arguments.
00696 */
00697 extern int      vsprintf(char *__s, const char *__fmt, va_list ap);
00698 
00699 /**
00700    Variant of \c vsprintf() that uses a \c fmt string that resides
00701    in program memory.
00702 */
00703 extern int      vsprintf_P(char *__s, const char *__fmt, va_list ap);
00704 
00705 /**
00706    Like \c vsprintf(), but instead of assuming \c s to be of infinite
00707    size, no more than \c n characters (including the trailing NUL
00708    character) will be converted to \c s.
00709 
00710    Returns the number of characters that would have been written to
00711    \c s if there were enough space.
00712 */
00713 extern int      vsnprintf(char *__s, size_t __n, const char *__fmt, va_list ap);
00714 
00715 /**
00716    Variant of \c vsnprintf() that uses a \c fmt string that resides
00717    in program memory.
00718 */
00719 extern int      vsnprintf_P(char *__s, size_t __n, const char *__fmt, va_list ap);
00720 /**
00721    The function \c fprintf performs formatted output to \c stream.
00722    See \c vfprintf() for details.
00723 */
00724 extern int      fprintf(FILE *__stream, const char *__fmt, ...);
00725 
00726 /**
00727    Variant of \c fprintf() that uses a \c fmt string that resides
00728    in program memory.
00729 */
00730 extern int      fprintf_P(FILE *__stream, const char *__fmt, ...);
00731 
00732 /**
00733    Write the string pointed to by \c str to stream \c stream.
00734 
00735    Returns 0 on success and EOF on error.
00736 */
00737 extern int      fputs(const char *__str, FILE *__stream);
00738 
00739 /**
00740    Variant of fputs() where \c str resides in program memory.
00741 */
00742 extern int      fputs_P(const char *__str, FILE *__stream);
00743 
00744 /**
00745    Write the string pointed to by \c str, and a trailing newline
00746    character, to \c stdout.
00747 */
00748 extern int      puts(const char *__str);
00749 
00750 /**
00751    Variant of puts() where \c str resides in program memory.
00752 */
00753 extern int      puts_P(const char *__str);
00754 
00755 /**
00756    Write \c nmemb objects, \c size bytes each, to \c stream.
00757    The first byte of the first object is referenced by \c ptr.
00758 
00759    Returns the number of objects successfully written, i. e.
00760    \c nmemb unless an output error occured.
00761  */
00762 extern size_t   fwrite(const void *__ptr, size_t __size, size_t __nmemb,
00763                        FILE *__stream);
00764 
00765 /**
00766    The function \c fgetc reads a character from \c stream.  It returns
00767    the character, or \c EOF in case end-of-file was encountered or an
00768    error occurred.  The routines feof() or ferror() must be used to
00769    distinguish between both situations.
00770 */
00771 extern int      fgetc(FILE *__stream);
00772 
00773 #if !defined(__DOXYGEN__)
00774 
00775 /* getc() function implementation, required by standard */
00776 extern int      getc(FILE *__stream);
00777 
00778 /* getchar() function implementation, required by standard */
00779 extern int      getchar(void);
00780 
00781 #endif /* not __DOXYGEN__ */
00782 
00783 /**
00784    The macro \c getc used to be a "fast" macro implementation with a
00785    functionality identical to fgetc().  For space constraints, in
00786    \c avr-libc, it is just an alias for \c fgetc.
00787 */
00788 #define getc(__stream) fgetc(__stream)
00789 
00790 /**
00791    The macro \c getchar reads a character from \c stdin.  Return
00792    values and error handling is identical to fgetc().
00793 */
00794 #define getchar() fgetc(stdin)
00795 
00796 /**
00797    The ungetc() function pushes the character \c c (converted to an
00798    unsigned char) back onto the input stream pointed to by \c stream.
00799    The pushed-back character will be returned by a subsequent read on
00800    the stream.
00801 
00802    Currently, only a single character can be pushed back onto the
00803    stream.
00804    
00805    The ungetc() function returns the character pushed back after the
00806    conversion, or \c EOF if the operation fails.  If the value of the
00807    argument \c c character equals \c EOF, the operation will fail and
00808    the stream will remain unchanged.
00809 */
00810 extern int      ungetc(int __c, FILE *__stream);
00811 
00812 /**
00813    Read at most <tt>size - 1</tt> bytes from \c stream, until a
00814    newline character was encountered, and store the characters in the
00815    buffer pointed to by \c str.  Unless an error was encountered while
00816    reading, the string will then be terminated with a \c NUL
00817    character.
00818 
00819    If an error was encountered, the function returns NULL and sets the
00820    error flag of \c stream, which can be tested using ferror().
00821    Otherwise, a pointer to the string will be returned.  */
00822 extern char     *fgets(char *__str, int __size, FILE *__stream);
00823 
00824 /**
00825    Similar to fgets() except that it will operate on stream \c stdin,
00826    and the trailing newline (if any) will not be stored in the string.
00827    It is the caller's responsibility to provide enough storage to hold
00828    the characters read.  */
00829 extern char     *gets(char *__str);
00830 
00831 /**
00832    Read \c nmemb objects, \c size bytes each, from \c stream,
00833    to the buffer pointed to by \c ptr.
00834 
00835    Returns the number of objects successfully read, i. e.
00836    \c nmemb unless an input error occured or end-of-file was
00837    encountered.  feof() and ferror() must be used to distinguish
00838    between these two conditions.
00839  */
00840 extern size_t   fread(void *__ptr, size_t __size, size_t __nmemb,
00841                       FILE *__stream);
00842 
00843 /**
00844    Clear the error and end-of-file flags of \c stream.
00845  */
00846 extern void     clearerr(FILE *__stream);
00847 
00848 #if !defined(__DOXYGEN__)
00849 /* fast inlined version of clearerr() */
00850 #define clearerror(s) do { (s)->flags &= ~(__SERR | __SEOF); } while(0)
00851 #endif /* !defined(__DOXYGEN__) */
00852 
00853 /**
00854    Test the end-of-file flag of \c stream.  This flag can only be cleared
00855    by a call to clearerr().
00856  */
00857 extern int      feof(FILE *__stream);
00858 
00859 #if !defined(__DOXYGEN__)
00860 /* fast inlined version of feof() */
00861 #define feof(s) ((s)->flags & __SEOF)
00862 #endif /* !defined(__DOXYGEN__) */
00863 
00864 /**
00865    Test the error flag of \c stream.  This flag can only be cleared
00866    by a call to clearerr().
00867  */
00868 extern int      ferror(FILE *__stream);
00869 
00870 #if !defined(__DOXYGEN__)
00871 /* fast inlined version of ferror() */
00872 #define ferror(s) ((s)->flags & __SERR)
00873 #endif /* !defined(__DOXYGEN__) */
00874 
00875 extern int      vfscanf(FILE *__stream, const char *__fmt, va_list __ap);
00876 
00877 /**
00878    Variant of vfscanf() using a \c fmt string in program memory.
00879  */
00880 extern int      vfscanf_P(FILE *__stream, const char *__fmt, va_list __ap);
00881 
00882 /**
00883    The function \c fscanf performs formatted input, reading the
00884    input data from \c stream.
00885 
00886    See vfscanf() for details.
00887  */
00888 extern int      fscanf(FILE *__stream, const char *__fmt, ...);
00889 
00890 /**
00891    Variant of fscanf() using a \c fmt string in program memory.
00892  */
00893 extern int      fscanf_P(FILE *__stream, const char *__fmt, ...);
00894 
00895 /**
00896    The function \c scanf performs formatted input from stream \c stdin.
00897 
00898    See vfscanf() for details.
00899  */
00900 extern int      scanf(const char *__fmt, ...);
00901 
00902 /**
00903    Variant of scanf() where \c fmt resides in program memory.
00904  */
00905 extern int      scanf_P(const char *__fmt, ...);
00906 
00907 /**
00908    The function \c vscanf performs formatted input from stream
00909    \c stdin, taking a variable argument list as in vfscanf().
00910 
00911    See vfscanf() for details.
00912 */
00913 extern int      vscanf(const char *__fmt, va_list __ap);
00914 
00915 /**
00916    The function \c sscanf performs formatted input, reading the
00917    input data from the buffer pointed to by \c buf.
00918 
00919    See vfscanf() for details.
00920  */
00921 extern int      sscanf(const char *__buf, const char *__fmt, ...);
00922 
00923 /**
00924    Variant of sscanf() using a \c fmt string in program memory.
00925  */
00926 extern int      sscanf_P(const char *__buf, const char *__fmt, ...);
00927 
00928 #if defined(__DOXYGEN__)
00929 /**
00930    Flush \c stream.
00931 
00932    This is a null operation provided for source-code compatibility
00933    only, as the standard IO implementation currently does not perform
00934    any buffering.
00935  */
00936 extern int      fflush(FILE *stream);
00937 #else
00938 static __inline__ int fflush(FILE *stream __attribute__((unused)))
00939 {
00940         return 0;
00941 }
00942 #endif
00943 
00944 #ifdef __cplusplus
00945 }
00946 #endif
00947 
00948 /*@}*/
00949 
00950 /*
00951  * The following constants are currently not used by avr-libc's
00952  * stdio subsystem.  They are defined here since the gcc build
00953  * environment expects them to be here.
00954  */
00955 #define SEEK_SET 0
00956 #define SEEK_CUR 1
00957 #define SEEK_END 2
00958 
00959 #endif /* __ASSEMBLER */
00960 
00961 #endif /* _STDLIB_H_ */

Automatically generated by Doxygen 1.7.6.1 on Tue Jan 3 2012.