AVR-LibC  2.2.0
Standard C library for AVR-GCC
 

AVR-LibC Documentation

Logo

AVR-LibC Development Pages

Main Page

User Manual

Library Reference

FAQ

Example Projects

File List

Loading...
Searching...
No Matches
stdio.h
Go to the documentation of this file.
1/* Copyright (c) 2002, 2005, 2007 Joerg Wunsch
2 All rights reserved.
3
4 Portions of documentation Copyright (c) 1990, 1991, 1993
5 The Regents of the University of California.
6
7 All rights reserved.
8
9 Redistribution and use in source and binary forms, with or without
10 modification, are permitted provided that the following conditions are met:
11
12 * Redistributions of source code must retain the above copyright
13 notice, this list of conditions and the following disclaimer.
14
15 * Redistributions in binary form must reproduce the above copyright
16 notice, this list of conditions and the following disclaimer in
17 the documentation and/or other materials provided with the
18 distribution.
19
20 * Neither the name of the copyright holders nor the names of
21 contributors may be used to endorse or promote products derived
22 from this software without specific prior written permission.
23
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 POSSIBILITY OF SUCH DAMAGE.
35
36 $Id$
37*/
38
39#ifndef _STDIO_H_
40#define _STDIO_H_ 1
41
42#ifndef __ASSEMBLER__
43
44#include <inttypes.h>
45#include <stdarg.h>
46
47#ifndef __DOXYGEN__
48#define __need_NULL
49#define __need_size_t
50#include <stddef.h>
51#endif /* !__DOXYGEN__ */
52
53/** \file */
54/** \defgroup avr_stdio <stdio.h>: Standard IO facilities
55 \code #include <stdio.h> \endcode
56
57 <h3>Introduction to the Standard IO facilities</h3>
58
59 This file declares the standard IO facilities that are implemented
60 in AVR-LibC. Due to the nature of the underlying hardware,
61 only a limited subset of standard IO is implemented. There is no
62 actual file implementation available, so only device IO can be
63 performed. Since there's no operating system, the application
64 needs to provide enough details about their devices in order to
65 make them usable by the standard IO facilities.
66
67 Due to space constraints, some functionality has not been
68 implemented at all (like some of the \c printf conversions that
69 have been left out). Nevertheless, potential users of this
70 implementation should be warned: the \c printf and \c scanf families of functions, although
71 usually associated with presumably simple things like the
72 famous "Hello, world!" program, are actually fairly complex
73 which causes their inclusion to eat up a fair amount of code space.
74 Also, they are not fast due to the nature of interpreting the
75 format string at run-time. Whenever possible, resorting to the
76 (sometimes non-standard) predetermined conversion facilities that are
77 offered by AVR-LibC will usually cost much less in terms of speed
78 and code size.
79
80 <h3>Tunable options for code size vs. feature set</h3>
81
82 In order to allow programmers a code size vs. functionality tradeoff,
83 the function vfprintf() which is the heart of the printf family can be
84 selected in different flavours using linker options. See the
85 documentation of vfprintf() for a detailed description. The same
86 applies to vfscanf() and the \c scanf family of functions.
87
88 <h3>Outline of the chosen API</h3>
89
90 The standard streams \c stdin, \c stdout, and \c stderr are
91 provided, but contrary to the C standard, since AVR-LibC has no
92 knowledge about applicable devices, these streams are not already
93 pre-initialized at application startup. Also, since there is no
94 notion of "file" whatsoever to AVR-LibC, there is no function
95 \c fopen() that could be used to associate a stream to some device.
96 (See \ref stdio_note1 "note 1".) Instead, the function \c fdevopen()
97 is provided to associate a stream to a device, where the device
98 needs to provide a function to send a character, to receive a
99 character, or both. There is no differentiation between "text" and
100 "binary" streams inside AVR-LibC. Character \c \\n is sent
101 literally down to the device's \c put() function. If the device
102 requires a carriage return (\c \\r) character to be sent before
103 the linefeed, its \c put() routine must implement this (see
104 \ref stdio_note2 "note 2").
105
106 As an alternative method to fdevopen(), the macro
107 fdev_setup_stream() might be used to setup a user-supplied FILE
108 structure.
109
110 It should be noted that the automatic conversion of a newline
111 character into a carriage return - newline sequence breaks binary
112 transfers. If binary transfers are desired, no automatic
113 conversion should be performed, but instead any string that aims
114 to issue a CR-LF sequence must use <tt>"\r\n"</tt> explicitly.
115
116 For convenience, the first call to \c fdevopen() that opens a
117 stream for reading will cause the resulting stream to be aliased
118 to \c stdin. Likewise, the first call to \c fdevopen() that opens
119 a stream for writing will cause the resulting stream to be aliased
120 to both, \c stdout, and \c stderr. Thus, if the open was done
121 with both, read and write intent, all three standard streams will
122 be identical. Note that these aliases are indistinguishable from
123 each other, thus calling \c fclose() on such a stream will also
124 effectively close all of its aliases (\ref stdio_note3 "note 3").
125
126 It is possible to tie additional user data to a stream, using
127 fdev_set_udata(). The backend put and get functions can then
128 extract this user data using fdev_get_udata(), and act
129 appropriately. For example, a single put function could be used
130 to talk to two different UARTs that way, or the put and get
131 functions could keep internal state between calls there.
132
133 <h3>Format strings in flash ROM</h3>
134
135 All the \c printf and \c scanf family functions come in two flavours: the
136 standard name, where the format string is expected to be in
137 SRAM, as well as a version with the suffix "_P" where the format
138 string is expected to reside in the flash ROM. The macro
139 #PSTR (explained in \ref avr_pgmspace) becomes very handy
140 for declaring these format strings.
141
142 \anchor stdio_without_malloc
143 <h3>Running stdio without malloc()</h3>
144
145 By default, fdevopen() requires malloc(). As this is often
146 not desired in the limited environment of a microcontroller, an
147 alternative option is provided to run completely without malloc().
148
149 The macro fdev_setup_stream() is provided to prepare a
150 user-supplied FILE buffer for operation with stdio.
151
152 <h4>Example</h4>
153
154 \code
155 #include <stdio.h>
156
157 static int uart_putchar(char c, FILE *stream);
158
159 static FILE mystdout = FDEV_SETUP_STREAM(uart_putchar, NULL,
160 _FDEV_SETUP_WRITE);
161
162 static int
163 uart_putchar(char c, FILE *stream)
164 {
165
166 if (c == '\n')
167 uart_putchar('\r', stream);
168 loop_until_bit_is_set(UCSRA, UDRE);
169 UDR = c;
170 return 0;
171 }
172
173 int
174 main(void)
175 {
176 init_uart();
177 stdout = &mystdout;
178 printf("Hello, world!\n");
179
180 return 0;
181 }
182 \endcode
183
184 This example uses the initializer form FDEV_SETUP_STREAM() rather
185 than the function-like fdev_setup_stream(), so all data
186 initialization happens during C start-up.
187
188 If streams initialized that way are no longer needed, they can be
189 destroyed by first calling the macro fdev_close(), and then
190 destroying the object itself. No call to fclose() should be
191 issued for these streams. While calling fclose() itself is
192 harmless, it will cause an undefined reference to free() and thus
193 cause the linker to link the malloc module into the application.
194
195 <h3>Notes</h3>
196
197<dl>
198<dt>\anchor stdio_note1 Note 1:</dt>
199<dd>
200 It might have been possible to implement a device abstraction that
201 is compatible with \c fopen() but since this would have required
202 to parse a string, and to take all the information needed either
203 out of this string, or out of an additional table that would need to be
204 provided by the application, this approach was not taken.
205</dd>
206<dt>\anchor stdio_note2 Note 2:</dt>
207<dd>
208 This basically follows the Unix approach: if a device such as a
209 terminal needs special handling, it is in the domain of the
210 terminal device driver to provide this functionality. Thus, a
211 simple function suitable as \c put() for \c fdevopen() that talks
212 to a UART interface might look like this:
213
214 \code
215 int
216 uart_putchar(char c, FILE *stream)
217 {
218
219 if (c == '\n')
220 uart_putchar('\r', stream);
221 loop_until_bit_is_set(UCSRA, UDRE);
222 UDR = c;
223 return 0;
224 }
225 \endcode
226</dd>
227<dt>\anchor stdio_note3 Note 3:</dt>
228<dd>
229 This implementation has been chosen because the cost of maintaining
230 an alias is considerably smaller than the cost of maintaining full
231 copies of each stream. Yet, providing an implementation that offers
232 the complete set of standard streams was deemed to be useful. Not
233 only that writing \c printf() instead of <tt>fprintf(mystream, ...)</tt>
234 saves typing work, but since avr-gcc needs to resort to pass all
235 arguments of variadic functions on the stack (as opposed to passing
236 them in registers for functions that take a fixed number of
237 parameters), the ability to pass one parameter less by implying
238 \c stdin or stdout will also save some execution time.
239</dd>
240</dl>
241*/
242
243#if !defined(__DOXYGEN__)
244
245/*
246 * This is an internal structure of the library that is subject to be
247 * changed without warnings at any time. Please do *never* reference
248 * elements of it beyond by using the official interfaces provided.
249 */
250struct __file {
251 char *buf; /* buffer pointer */
252 unsigned char unget; /* ungetc() buffer */
253 uint8_t flags; /* flags, see below */
254#define __SRD 0x0001 /* OK to read */
255#define __SWR 0x0002 /* OK to write */
256#define __SSTR 0x0004 /* this is an sprintf/snprintf string */
257#define __SPGM 0x0008 /* fmt string is in progmem */
258#define __SERR 0x0010 /* found error */
259#define __SEOF 0x0020 /* found EOF */
260#define __SUNGET 0x040 /* ungetc() happened */
261#define __SMALLOC 0x80 /* handle is malloc()ed */
262#if 0
263/* possible future extensions, will require uint16_t flags */
264#define __SRW 0x0100 /* open for reading & writing */
265#define __SLBF 0x0200 /* line buffered */
266#define __SNBF 0x0400 /* unbuffered */
267#define __SMBF 0x0800 /* buf is from malloc */
268#endif
269 int size; /* size of buffer */
270 int len; /* characters read or written so far */
271 int (*put)(char, struct __file *); /* function to write one char to device */
272 int (*get)(struct __file *); /* function to read one char from device */
273 void *udata; /* User defined and accessible data. */
274};
275
276#endif /* not __DOXYGEN__ */
277
278/**@{*/
279/**
280 \c FILE is the opaque structure that is passed around between the
281 various standard IO functions.
282*/
283typedef struct __file FILE;
284
285/**
286 Stream that will be used as an input stream by the simplified
287 functions that don't take a \c stream argument.
288
289 The first stream opened with read intent using \c fdevopen()
290 will be assigned to \c stdin.
291*/
292#define stdin (__iob[0])
293
294/**
295 Stream that will be used as an output stream by the simplified
296 functions that don't take a \c stream argument.
297
298 The first stream opened with write intent using \c fdevopen()
299 will be assigned to both, \c stdin, and \c stderr.
300*/
301#define stdout (__iob[1])
302
303/**
304 Stream destined for error output. Unless specifically assigned,
305 identical to \c stdout.
306
307 If \c stderr should point to another stream, the result of
308 another \c fdevopen() must be explicitly assigned to it without
309 closing the previous \c stderr (since this would also close
310 \c stdout).
311*/
312#define stderr (__iob[2])
313
314/**
315 \c EOF declares the value that is returned by various standard IO
316 functions in case of an error. Since the AVR platform (currently)
317 doesn't contain an abstraction for actual files, its origin as
318 "end of file" is somewhat meaningless here.
319*/
320#define EOF (-1)
321
322/** This macro inserts a pointer to user defined data into a FILE
323 stream object.
324
325 The user data can be useful for tracking state in the put and get
326 functions supplied to the fdevopen() function. */
327#define fdev_set_udata(stream, u) do { (stream)->udata = u; } while(0)
328
329/** This macro retrieves a pointer to user defined data from a FILE
330 stream object. */
331#define fdev_get_udata(stream) ((stream)->udata)
332
333#if defined(__DOXYGEN__)
334/**
335 \brief Setup a user-supplied buffer as an stdio stream
336
337 This macro takes a user-supplied buffer \c stream, and sets it up
338 as a stream that is valid for stdio operations, similar to one that
339 has been obtained dynamically from fdevopen(). The buffer to setup
340 must be of type #FILE.
341
342 The arguments \c put and \c get are identical to those that need to
343 be passed to fdevopen().
344
345 The \c rwflag argument can take one of the values #_FDEV_SETUP_READ,
346 #_FDEV_SETUP_WRITE, or #_FDEV_SETUP_RW, for read, write, or read/write
347 intent, respectively.
348
349 \note No assignments to the standard streams will be performed by
350 fdev_setup_stream(). If standard streams are to be used, these
351 need to be assigned by the user. See also under
352 \ref stdio_without_malloc "Running stdio without malloc()".
353 */
354#define fdev_setup_stream(stream, put, get, rwflag)
355#else /* !DOXYGEN */
356#define fdev_setup_stream(stream, p, g, f) \
357 do { \
358 (stream)->put = p; \
359 (stream)->get = g; \
360 (stream)->flags = f; \
361 (stream)->udata = 0; \
362 } while(0)
363#endif /* DOXYGEN */
364
365#define _FDEV_SETUP_READ __SRD /**< fdev_setup_stream() with read intent */
366#define _FDEV_SETUP_WRITE __SWR /**< fdev_setup_stream() with write intent */
367#define _FDEV_SETUP_RW (__SRD|__SWR) /**< fdev_setup_stream() with read/write intent */
368
369/**
370 * Return code for an error condition during device read.
371 *
372 * To be used in the get function of fdevopen().
373 */
374#define _FDEV_ERR (-1)
375
376/**
377 * Return code for an end-of-file condition during device read.
378 *
379 * To be used in the get function of fdevopen().
380 */
381#define _FDEV_EOF (-2)
382
383#if defined(__DOXYGEN__)
384/**
385 \brief Initializer for a user-supplied stdio stream
386
387 This macro acts similar to fdev_setup_stream(), but it is to be
388 used as the initializer of a variable of type FILE.
389
390 The remaining arguments are to be used as explained in
391 fdev_setup_stream().
392 */
393#define FDEV_SETUP_STREAM(put, get, rwflag)
394#else /* !DOXYGEN */
395/* In order to work with C++, we have to mention the fields in the order
396 as they appear in struct __file. Also, designated initializers are
397 only supported since C++20. */
398#define FDEV_SETUP_STREAM(PU, GE, FL) \
399 { \
400 (char*) 0 /* buf */, \
401 0u /* unget */, \
402 FL /* flags */, \
403 0 /* size */, \
404 0 /* len */, \
405 PU /* put */, \
406 GE /* get */, \
407 (void*) 0 /* udata */ \
408 }
409#endif /* DOXYGEN */
410
411#ifdef __cplusplus
412extern "C" {
413#endif
414
415#if !defined(__DOXYGEN__)
416/*
417 * Doxygen documentation can be found in fdevopen.c.
418 */
419
420extern struct __file *__iob[];
421
422#if defined(__STDIO_FDEVOPEN_COMPAT_12)
423/*
424 * Declare prototype for the discontinued version of fdevopen() that
425 * has been in use up to AVR-LibC 1.2.x. The new implementation has
426 * some backwards compatibility with the old version.
427 */
428extern FILE *fdevopen(int (*__put)(char), int (*__get)(void),
429 int __opts __attribute__((unused)));
430#else /* !defined(__STDIO_FDEVOPEN_COMPAT_12) */
431/* New prototype for AVR-LibC 1.4 and above. */
432extern FILE *fdevopen(int (*__put)(char, FILE*), int (*__get)(FILE*));
433#endif /* defined(__STDIO_FDEVOPEN_COMPAT_12) */
434
435#endif /* not __DOXYGEN__ */
436
437/**
438 This function closes \c stream, and disallows and further
439 IO to and from it.
440
441 When using fdevopen() to setup the stream, a call to fclose() is
442 needed in order to free the internal resources allocated.
443
444 If the stream has been set up using fdev_setup_stream() or
445 FDEV_SETUP_STREAM(), use fdev_close() instead.
446
447 It currently always returns 0 (for success).
448*/
449extern int fclose(FILE *__stream);
450
451/**
452 This macro frees up any library resources that might be associated
453 with \c stream. It should be called if \c stream is no longer
454 needed, right before the application is going to destroy the
455 \c stream object itself.
456
457 (Currently, this macro evaluates to nothing, but this might change
458 in future versions of the library.)
459*/
460#if defined(__DOXYGEN__)
461# define fdev_close()
462#else
463# define fdev_close() ((void)0)
464#endif
465
466/**
467 \c vfprintf is the central facility of the \c printf family of
468 functions. It outputs values to \c stream under control of a
469 format string passed in \c fmt. The actual values to print are
470 passed as a variable argument list \c ap.
471
472 \c vfprintf returns the number of characters written to \c stream,
473 or \c EOF in case of an error. Currently, this will only happen
474 if \c stream has not been opened with write intent.
475
476 The format string is composed of zero or more directives: ordinary
477 characters (not \c %), which are copied unchanged to the output
478 stream; and conversion specifications, each of which results in
479 fetching zero or more subsequent arguments. Each conversion
480 specification is introduced by the \c % character. The arguments must
481 properly correspond (after type promotion) with the conversion
482 specifier. After the \c %, the following appear in sequence:
483
484 - Zero or more of the following flags:
485 <ul>
486 <li> \c # The value should be converted to an "alternate form". For
487 c, d, i, s, and u conversions, this option has no effect.
488 For o conversions, the precision of the number is
489 increased to force the first character of the output
490 string to a zero (except if a zero value is printed with
491 an explicit precision of zero). For x and X conversions,
492 a non-zero result has the string `0x' (or `0X' for X
493 conversions) prepended to it.</li>
494 <li> \c 0 (zero) Zero padding. For all conversions, the converted
495 value is padded on the left with zeros rather than blanks.
496 If a precision is given with a numeric conversion (d, i,
497 o, u, i, x, and X), the 0 flag is ignored.</li>
498 <li> \c - A negative field width flag; the converted value is to be
499 left adjusted on the field boundary. The converted value
500 is padded on the right with blanks, rather than on the
501 left with blanks or zeros. A - overrides a 0 if both are
502 given.</li>
503 <li> ' ' (space) A blank should be left before a positive number
504 produced by a signed conversion (d, or i).</li>
505 <li> \c + A sign must always be placed before a number produced by a
506 signed conversion. A + overrides a space if both are
507 used.</li>
508 </ul>
509
510 - An optional decimal digit string specifying a minimum field width.
511 If the converted value has fewer characters than the field width, it
512 will be padded with spaces on the left (or right, if the left-adjustment
513 flag has been given) to fill out the field width.
514 - An optional precision, in the form of a period . followed by an
515 optional digit string. If the digit string is omitted, the
516 precision is taken as zero. This gives the minimum number of
517 digits to appear for d, i, o, u, x, and X conversions, or the
518 maximum number of characters to be printed from a string for \c s
519 conversions.
520 - An optional \c l or \c h length modifier, that specifies that the
521 argument for the d, i, o, u, x, or X conversion is a \c "long int"
522 rather than \c int. The \c h is ignored, as \c "short int" is
523 equivalent to \c int.
524 - A character that specifies the type of conversion to be applied.
525
526 The conversion specifiers and their meanings are:
527
528 - \c diouxX The int (or appropriate variant) argument is converted
529 to signed decimal (d and i), unsigned octal (o), unsigned
530 decimal (u), or unsigned hexadecimal (x and X) notation.
531 The letters "abcdef" are used for x conversions; the
532 letters "ABCDEF" are used for X conversions. The
533 precision, if any, gives the minimum number of digits that
534 must appear; if the converted value requires fewer digits,
535 it is padded on the left with zeros.
536 - \c p The <tt>void *</tt> argument is taken as an unsigned integer,
537 and converted similarly as a <tt>%\#x</tt> command would do.
538 - \c c The \c int argument is converted to an \c "unsigned char", and the
539 resulting character is written.
540 - \c s The \c "char *" argument is expected to be a pointer to an array
541 of character type (pointer to a string). Characters from
542 the array are written up to (but not including) a
543 terminating NUL character; if a precision is specified, no
544 more than the number specified are written. If a precision
545 is given, no null character need be present; if the
546 precision is not specified, or is greater than the size of
547 the array, the array must contain a terminating NUL
548 character.
549 - \c % A \c % is written. No argument is converted. The complete
550 conversion specification is "%%".
551 - \c eE The double argument is rounded and converted in the format
552 \c "[-]d.ddde±dd" where there is one digit before the
553 decimal-point character and the number of digits after it
554 is equal to the precision; if the precision is missing, it
555 is taken as 6; if the precision is zero, no decimal-point
556 character appears. An \e E conversion uses the letter \c 'E'
557 (rather than \c 'e') to introduce the exponent. The exponent
558 always contains two digits; if the value is zero,
559 the exponent is 00.
560 - \c fF The double argument is rounded and converted to decimal notation
561 in the format \c "[-]ddd.ddd", where the number of digits after the
562 decimal-point character is equal to the precision specification.
563 If the precision is missing, it is taken as 6; if the precision
564 is explicitly zero, no decimal-point character appears. If a
565 decimal point appears, at least one digit appears before it.
566 - \c gG The double argument is converted in style \c f or \c e (or
567 \c F or \c E for \c G conversions). The precision
568 specifies the number of significant digits. If the
569 precision is missing, 6 digits are given; if the precision
570 is zero, it is treated as 1. Style \c e is used if the
571 exponent from its conversion is less than -4 or greater
572 than or equal to the precision. Trailing zeros are removed
573 from the fractional part of the result; a decimal point
574 appears only if it is followed by at least one digit.
575 - \c S Similar to the \c s format, except the pointer is expected to
576 point to a program-memory (ROM) string instead of a RAM string.
577
578 In no case does a non-existent or small field width cause truncation of a
579 numeric field; if the result of a conversion is wider than the field
580 width, the field is expanded to contain the conversion result.
581
582 Since the full implementation of all the mentioned features becomes
583 fairly large, three different flavours of vfprintf() can be
584 selected using linker options. The default vfprintf() implements
585 all the mentioned functionality except floating point conversions.
586 A minimized version of vfprintf() is available that only implements
587 the very basic integer and string conversion facilities, but only
588 the \c # additional option can be specified using conversion
589 flags (these flags are parsed correctly from the format
590 specification, but then simply ignored). This version can be
591 requested using the following \ref gcc_minusW "compiler options":
592
593 \code
594 -Wl,-u,vfprintf -lprintf_min
595 \endcode
596
597 If the full functionality including the floating point conversions
598 is required, the following options should be used:
599
600 \code
601 -Wl,-u,vfprintf -lprintf_flt -lm
602 \endcode
603
604 \par Limitations:
605 - The specified width and precision can be at most 255.
606
607 \par Notes:
608 - For floating-point conversions, if you link default or minimized
609 version of vfprintf(), the symbol \c ? will be output and double
610 argument will be skipped. So you output below will not be crashed.
611 For default version the width field and the "pad to left" ( symbol
612 minus ) option will work in this case.
613 - The \c hh length modifier is ignored (\c char argument is
614 promouted to \c int). More exactly, this realization does not check
615 the number of \c h symbols.
616 - But the \c ll length modifier will to abort the output, as this
617 realization does not operate \c long \c long arguments.
618 - The variable width or precision field (an asterisk \c * symbol)
619 is not realized and will to abort the output.
620
621 */
622
623extern int vfprintf(FILE *__stream, const char *__fmt, va_list __ap);
624
625/**
626 Variant of \c vfprintf() that uses a \c fmt string that resides
627 in program memory.
628*/
629extern int vfprintf_P(FILE *__stream, const char *__fmt, va_list __ap);
630
631/**
632 The function \c fputc sends the character \c c (though given as type
633 \c int) to \c stream. It returns the character, or \c EOF in case
634 an error occurred.
635*/
636extern int fputc(int __c, FILE *__stream);
637
638#if !defined(__DOXYGEN__)
639
640/* putc() function implementation, required by standard */
641extern int putc(int __c, FILE *__stream);
642
643/* putchar() function implementation, required by standard */
644extern int putchar(int __c);
645
646#endif /* not __DOXYGEN__ */
647
648/**
649 The macro \c putc used to be a "fast" macro implementation with a
650 functionality identical to fputc(). For space constraints, in
651 AVR-LibC, it is just an alias for \c fputc.
652*/
653#define putc(__c, __stream) fputc(__c, __stream)
654
655/**
656 The macro \c putchar sends character \c c to \c stdout.
657*/
658#define putchar(__c) fputc(__c, stdout)
659
660/**
661 The function \c printf performs formatted output to stream
662 \c stdout. See \c vfprintf() for details.
663*/
664extern int printf(const char *__fmt, ...);
665
666/**
667 Variant of \c printf() that uses a \c fmt string that resides
668 in program memory.
669*/
670extern int printf_P(const char *__fmt, ...);
671
672/**
673 The function \c vprintf performs formatted output to stream
674 \c stdout, taking a variable argument list as in vfprintf().
675
676 See vfprintf() for details.
677*/
678extern int vprintf(const char *__fmt, va_list __ap);
679
680/**
681 Variant of \c printf() that sends the formatted characters
682 to string \c s.
683*/
684extern int sprintf(char *__s, const char *__fmt, ...);
685
686/**
687 Variant of \c sprintf() that uses a \c fmt string that resides
688 in program memory.
689*/
690extern int sprintf_P(char *__s, const char *__fmt, ...);
691
692/**
693 Like \c sprintf(), but instead of assuming \c s to be of infinite
694 size, no more than \c n characters (including the trailing NUL
695 character) will be converted to \c s.
696
697 Returns the number of characters that would have been written to
698 \c s if there were enough space.
699*/
700extern int snprintf(char *__s, size_t __n, const char *__fmt, ...);
701
702/**
703 Variant of \c snprintf() that uses a \c fmt string that resides
704 in program memory.
705*/
706extern int snprintf_P(char *__s, size_t __n, const char *__fmt, ...);
707
708/**
709 Like \c sprintf() but takes a variable argument list for the
710 arguments.
711*/
712extern int vsprintf(char *__s, const char *__fmt, va_list ap);
713
714/**
715 Variant of \c vsprintf() that uses a \c fmt string that resides
716 in program memory.
717*/
718extern int vsprintf_P(char *__s, const char *__fmt, va_list ap);
719
720/**
721 Like \c vsprintf(), but instead of assuming \c s to be of infinite
722 size, no more than \c n characters (including the trailing NUL
723 character) will be converted to \c s.
724
725 Returns the number of characters that would have been written to
726 \c s if there were enough space.
727*/
728extern int vsnprintf(char *__s, size_t __n, const char *__fmt, va_list ap);
729
730/**
731 Variant of \c vsnprintf() that uses a \c fmt string that resides
732 in program memory.
733*/
734extern int vsnprintf_P(char *__s, size_t __n, const char *__fmt, va_list ap);
735/**
736 The function \c fprintf performs formatted output to \c stream.
737 See \c vfprintf() for details.
738*/
739extern int fprintf(FILE *__stream, const char *__fmt, ...);
740
741/**
742 Variant of \c fprintf() that uses a \c fmt string that resides
743 in program memory.
744*/
745extern int fprintf_P(FILE *__stream, const char *__fmt, ...);
746
747/**
748 Write the string pointed to by \c str to stream \c stream.
749
750 Returns 0 on success and EOF on error.
751*/
752extern int fputs(const char *__str, FILE *__stream);
753
754/**
755 Variant of fputs() where \c str resides in program memory.
756*/
757extern int fputs_P(const char *__str, FILE *__stream);
758
759/**
760 Write the string pointed to by \c str, and a trailing newline
761 character, to \c stdout.
762*/
763extern int puts(const char *__str);
764
765/**
766 Variant of puts() where \c str resides in program memory.
767*/
768extern int puts_P(const char *__str);
769
770/**
771 Write \c nmemb objects, \c size bytes each, to \c stream.
772 The first byte of the first object is referenced by \c ptr.
773
774 Returns the number of objects successfully written, i. e.
775 \c nmemb unless an output error occured.
776 */
777extern size_t fwrite(const void *__ptr, size_t __size, size_t __nmemb,
778 FILE *__stream);
779
780/**
781 The function \c fgetc reads a character from \c stream. It returns
782 the character, or \c EOF in case end-of-file was encountered or an
783 error occurred. The routines feof() or ferror() must be used to
784 distinguish between both situations.
785*/
786extern int fgetc(FILE *__stream);
787
788#if !defined(__DOXYGEN__)
789
790/* getc() function implementation, required by standard */
791extern int getc(FILE *__stream);
792
793/* getchar() function implementation, required by standard */
794extern int getchar(void);
795
796#endif /* not __DOXYGEN__ */
797
798/**
799 The macro \c getc used to be a "fast" macro implementation with a
800 functionality identical to fgetc(). For space constraints, in
801 AVR-LibC, it is just an alias for \c fgetc.
802*/
803#define getc(__stream) fgetc(__stream)
804
805/**
806 The macro \c getchar reads a character from \c stdin. Return
807 values and error handling is identical to fgetc().
808*/
809#define getchar() fgetc(stdin)
810
811/**
812 The ungetc() function pushes the character \c c (converted to an
813 unsigned char) back onto the input stream pointed to by \c stream.
814 The pushed-back character will be returned by a subsequent read on
815 the stream.
816
817 Currently, only a single character can be pushed back onto the
818 stream.
819
820 The ungetc() function returns the character pushed back after the
821 conversion, or \c EOF if the operation fails. If the value of the
822 argument \c c character equals \c EOF, the operation will fail and
823 the stream will remain unchanged.
824*/
825extern int ungetc(int __c, FILE *__stream);
826
827/**
828 Read at most <tt>size - 1</tt> bytes from \c stream, until a
829 newline character was encountered, and store the characters in the
830 buffer pointed to by \c str. Unless an error was encountered while
831 reading, the string will then be terminated with a \c NUL
832 character.
833
834 If an error was encountered, the function returns NULL and sets the
835 error flag of \c stream, which can be tested using ferror().
836 Otherwise, a pointer to the string will be returned. */
837extern char *fgets(char *__str, int __size, FILE *__stream);
838
839/**
840 Similar to fgets() except that it will operate on stream \c stdin,
841 and the trailing newline (if any) will not be stored in the string.
842 It is the caller's responsibility to provide enough storage to hold
843 the characters read. */
844extern char *gets(char *__str);
845
846/**
847 Read \c nmemb objects, \c size bytes each, from \c stream,
848 to the buffer pointed to by \c ptr.
849
850 Returns the number of objects successfully read, i. e.
851 \c nmemb unless an input error occured or end-of-file was
852 encountered. feof() and ferror() must be used to distinguish
853 between these two conditions.
854 */
855extern size_t fread(void *__ptr, size_t __size, size_t __nmemb,
856 FILE *__stream);
857
858/**
859 Clear the error and end-of-file flags of \c stream.
860 */
861extern void clearerr(FILE *__stream);
862
863#if !defined(__DOXYGEN__)
864/* fast inlined version of clearerr() */
865#define clearerror(s) do { (s)->flags &= ~(__SERR | __SEOF); } while(0)
866#endif /* !defined(__DOXYGEN__) */
867
868/**
869 Test the end-of-file flag of \c stream. This flag can only be cleared
870 by a call to clearerr().
871 */
872extern int feof(FILE *__stream);
873
874#if !defined(__DOXYGEN__)
875/* fast inlined version of feof() */
876#define feof(s) ((s)->flags & __SEOF)
877#endif /* !defined(__DOXYGEN__) */
878
879/**
880 Test the error flag of \c stream. This flag can only be cleared
881 by a call to clearerr().
882 */
883extern int ferror(FILE *__stream);
884
885#if !defined(__DOXYGEN__)
886/* fast inlined version of ferror() */
887#define ferror(s) ((s)->flags & __SERR)
888#endif /* !defined(__DOXYGEN__) */
889
890extern int vfscanf(FILE *__stream, const char *__fmt, va_list __ap);
891
892/**
893 Variant of vfscanf() using a \c fmt string in program memory.
894 */
895extern int vfscanf_P(FILE *__stream, const char *__fmt, va_list __ap);
896
897/**
898 The function \c fscanf performs formatted input, reading the
899 input data from \c stream.
900
901 See vfscanf() for details.
902 */
903extern int fscanf(FILE *__stream, const char *__fmt, ...);
904
905/**
906 Variant of fscanf() using a \c fmt string in program memory.
907 */
908extern int fscanf_P(FILE *__stream, const char *__fmt, ...);
909
910/**
911 The function \c scanf performs formatted input from stream \c stdin.
912
913 See vfscanf() for details.
914 */
915extern int scanf(const char *__fmt, ...);
916
917/**
918 Variant of scanf() where \c fmt resides in program memory.
919 */
920extern int scanf_P(const char *__fmt, ...);
921
922/**
923 The function \c vscanf performs formatted input from stream
924 \c stdin, taking a variable argument list as in vfscanf().
925
926 See vfscanf() for details.
927*/
928extern int vscanf(const char *__fmt, va_list __ap);
929
930/**
931 The function \c sscanf performs formatted input, reading the
932 input data from the buffer pointed to by \c buf.
933
934 See vfscanf() for details.
935 */
936extern int sscanf(const char *__buf, const char *__fmt, ...);
937
938/**
939 Variant of sscanf() using a \c fmt string in program memory.
940 */
941extern int sscanf_P(const char *__buf, const char *__fmt, ...);
942
943#if defined(__DOXYGEN__)
944/**
945 Flush \c stream.
946
947 This is a null operation provided for source-code compatibility
948 only, as the standard IO implementation currently does not perform
949 any buffering.
950 */
951extern int fflush(FILE *stream);
952#else
953static __inline__ int fflush(FILE *stream __attribute__((unused)))
954{
955 return 0;
956}
957#endif
958
959#ifndef __DOXYGEN__
960/* only mentioned for libstdc++ support, not implemented in library */
961#define BUFSIZ 1024
962#define _IONBF 0
963__extension__ typedef long long fpos_t;
964extern int fgetpos(FILE *stream, fpos_t *pos);
965extern FILE *fopen(const char *path, const char *mode);
966extern FILE *freopen(const char *path, const char *mode, FILE *stream);
967extern FILE *fdopen(int, const char *);
968extern int fseek(FILE *stream, long offset, int whence);
969extern int fsetpos(FILE *stream, fpos_t *pos);
970extern long ftell(FILE *stream);
971extern int fileno(FILE *);
972extern void perror(const char *s);
973extern int remove(const char *pathname);
974extern int rename(const char *oldpath, const char *newpath);
975extern void rewind(FILE *stream);
976extern void setbuf(FILE *stream, char *buf);
977extern int setvbuf(FILE *stream, char *buf, int mode, size_t size);
978extern FILE *tmpfile(void);
979extern char *tmpnam (char *s);
980#endif /* !__DOXYGEN__ */
981
982#ifdef __cplusplus
983}
984#endif
985
986/**@}*/
987
988#ifndef __DOXYGEN__
989/*
990 * The following constants are currently not used by AVR-LibC's
991 * stdio subsystem. They are defined here since the gcc build
992 * environment expects them to be here.
993 */
994#define SEEK_SET 0
995#define SEEK_CUR 1
996#define SEEK_END 2
997
998#endif
999
1000#endif /* __ASSEMBLER */
1001
1002#endif /* _STDIO_H_ */
unsigned char uint8_t
Definition: stdint.h:83
int vprintf(const char *__fmt, va_list __ap)
Definition: vprintf.c:38
int fscanf(FILE *__stream, const char *__fmt,...)
Definition: fscanf.c:38
int fprintf(FILE *__stream, const char *__fmt,...)
Definition: fprintf.c:38
int scanf_P(const char *__fmt,...)
Definition: scanf_p.c:39
int fputs(const char *__str, FILE *__stream)
Definition: fputs.c:38
int vsnprintf_P(char *__s, size_t __n, const char *__fmt, va_list ap)
Definition: vsnprintf_p.c:39
#define putc(__c, __stream)
Definition: stdio.h:653
int sprintf_P(char *__s, const char *__fmt,...)
Definition: sprintf_p.c:40
int puts(const char *__str)
Definition: puts.c:38
int fprintf_P(FILE *__stream, const char *__fmt,...)
Definition: fprintf_p.c:39
int fputs_P(const char *__str, FILE *__stream)
Definition: fputs_p.c:41
int scanf(const char *__fmt,...)
Definition: scanf.c:38
int printf_P(const char *__fmt,...)
Definition: printf_p.c:39
int feof(FILE *__stream)
Definition: feof.c:40
int printf(const char *__fmt,...)
Definition: printf.c:38
FILE * fdevopen(int(*put)(char, FILE *), int(*get)(FILE *))
Definition: fdevopen.c:87
int snprintf_P(char *__s, size_t __n, const char *__fmt,...)
Definition: snprintf_p.c:39
size_t fread(void *__ptr, size_t __size, size_t __nmemb, FILE *__stream)
Definition: fread.c:38
int sscanf(const char *__buf, const char *__fmt,...)
Definition: sscanf.c:40
int vfprintf_P(FILE *__stream, const char *__fmt, va_list __ap)
Definition: vfprintf_p.c:38
int sprintf(char *__s, const char *__fmt,...)
Definition: sprintf.c:40
#define putchar(__c)
Definition: stdio.h:658
int vfscanf(FILE *__stream, const char *__fmt, va_list __ap)
Definition: vfscanf.c:744
char * gets(char *__str)
Definition: gets.c:38
int vfscanf_P(FILE *__stream, const char *__fmt, va_list __ap)
Definition: vfscanf_p.c:38
int snprintf(char *__s, size_t __n, const char *__fmt,...)
Definition: snprintf.c:39
int fscanf_P(FILE *__stream, const char *__fmt,...)
Definition: fscanf_p.c:39
int fgetc(FILE *__stream)
Definition: fgetc.c:38
int vscanf(const char *__fmt, va_list __ap)
Definition: vscanf.c:38
int vfprintf(FILE *__stream, const char *__fmt, va_list __ap)
Definition: vfprintf.c:129
int ferror(FILE *__stream)
Definition: ferror.c:40
void clearerr(FILE *__stream)
Definition: clearerr.c:40
int vsprintf(char *__s, const char *__fmt, va_list ap)
Definition: vsprintf.c:40
int puts_P(const char *__str)
Definition: puts_p.c:41
int ungetc(int __c, FILE *__stream)
Definition: ungetc.c:38
#define getchar()
Definition: stdio.h:809
int vsnprintf(char *__s, size_t __n, const char *__fmt, va_list ap)
Definition: vsnprintf.c:39
#define getc(__stream)
Definition: stdio.h:803
int fclose(FILE *__stream)
Definition: fclose.c:40
int fflush(FILE *stream)
char * fgets(char *__str, int __size, FILE *__stream)
Definition: fgets.c:38
size_t fwrite(const void *__ptr, size_t __size, size_t __nmemb, FILE *__stream)
Definition: fwrite.c:38
int sscanf_P(const char *__buf, const char *__fmt,...)
Definition: sscanf_p.c:40
struct __file FILE
Definition: stdio.h:283
int fputc(int __c, FILE *__stream)
Definition: fputc.c:38
int vsprintf_P(char *__s, const char *__fmt, va_list ap)
Definition: vsprintf_p.c:40