AVR Libc Home Page | AVR Libc Development Pages | ||||
Main Page | User Manual | Library Reference | FAQ | Alphabetical Index | Example Projects |
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.h 2135 2010-06-08 11:28:03Z joerg_wunsch $ 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_ */