$treeview $search $mathjax $extrastylesheet
avr-libc  2.0.0
$projectbrief
$projectbrief
$searchbox

AVR Libc Home Page

AVRs

AVR Libc Development Pages

Main Page

User Manual

Library Reference

FAQ

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