$treeview $search $mathjax $extrastylesheet
avr-libc
2.0.0
$projectbrief
|
$projectbrief
|
$searchbox |
AVR Libc Home Page |
AVR Libc Development Pages |
||||
Main Page |
User Manual |
Library Reference |
FAQ |
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$ 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_ */