avr-libc  2.0.0
Standard C library for AVR-GCC

AVR Libc Home Page

AVRs

AVR Libc Development Pages

Main Page

User Manual

Library Reference

FAQ

Example Projects

stdio.h
Go to the documentation of this file.
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 \c 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 \c 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 \anchor stdio_note1 \par Note 1:
198 It might have been possible to implement a device abstraction that
199 is compatible with \c fopen() but since this would have required
200 to parse a string, and to take all the information needed either
201 out of this string, or out of an additional table that would need to be
202 provided by the application, this approach was not taken.
203
204 \anchor stdio_note2 \par Note 2:
205 This basically follows the Unix approach: if a device such as a
206 terminal needs special handling, it is in the domain of the
207 terminal device driver to provide this functionality. Thus, a
208 simple function suitable as \c put() for \c fdevopen() that talks
209 to a UART interface might look like this:
210
211 \code
212 int
213 uart_putchar(char c, FILE *stream)
214 {
215
216 if (c == '\n')
217 uart_putchar('\r');
218 loop_until_bit_is_set(UCSRA, UDRE);
219 UDR = c;
220 return 0;
221 }
222 \endcode
223
224 \anchor stdio_note3 \par Note 3:
225 This implementation has been chosen because the cost of maintaining
226 an alias is considerably smaller than the cost of maintaining full
227 copies of each stream. Yet, providing an implementation that offers
228 the complete set of standard streams was deemed to be useful. Not
229 only that writing \c printf() instead of <tt>fprintf(mystream, ...)</tt>
230 saves typing work, but since avr-gcc needs to resort to pass all
231 arguments of variadic functions on the stack (as opposed to passing
232 them in registers for functions that take a fixed number of
233 parameters), the ability to pass one parameter less by implying
234 \c stdin or stdout will also save some execution time.
235*/
236
237#if !defined(__DOXYGEN__)
238
239/*
240 * This is an internal structure of the library that is subject to be
241 * changed without warnings at any time. Please do *never* reference
242 * elements of it beyond by using the official interfaces provided.
243 */
244struct __file {
245 char *buf; /* buffer pointer */
246 unsigned char unget; /* ungetc() buffer */
247 uint8_t flags; /* flags, see below */
248#define __SRD 0x0001 /* OK to read */
249#define __SWR 0x0002 /* OK to write */
250#define __SSTR 0x0004 /* this is an sprintf/snprintf string */
251#define __SPGM 0x0008 /* fmt string is in progmem */
252#define __SERR 0x0010 /* found error */
253#define __SEOF 0x0020 /* found EOF */
254#define __SUNGET 0x040 /* ungetc() happened */
255#define __SMALLOC 0x80 /* handle is malloc()ed */
256#if 0
257/* possible future extensions, will require uint16_t flags */
258#define __SRW 0x0100 /* open for reading & writing */
259#define __SLBF 0x0200 /* line buffered */
260#define __SNBF 0x0400 /* unbuffered */
261#define __SMBF 0x0800 /* buf is from malloc */
262#endif
263 int size; /* size of buffer */
264 int len; /* characters read or written so far */
265 int (*put)(char, struct __file *); /* function to write one char to device */
266 int (*get)(struct __file *); /* function to read one char from device */
267 void *udata; /* User defined and accessible data. */
268};
269
270#endif /* not __DOXYGEN__ */
271
272/*@{*/
273/**
274 \c FILE is the opaque structure that is passed around between the
275 various standard IO functions.
276*/
277typedef struct __file FILE;
278
279/**
280 Stream that will be used as an input stream by the simplified
281 functions that don't take a \c stream argument.
282
283 The first stream opened with read intent using \c fdevopen()
284 will be assigned to \c stdin.
285*/
286#define stdin (__iob[0])
287
288/**
289 Stream that will be used as an output stream by the simplified
290 functions that don't take a \c stream argument.
291
292 The first stream opened with write intent using \c fdevopen()
293 will be assigned to both, \c stdin, and \c stderr.
294*/
295#define stdout (__iob[1])
296
297/**
298 Stream destined for error output. Unless specifically assigned,
299 identical to \c stdout.
300
301 If \c stderr should point to another stream, the result of
302 another \c fdevopen() must be explicitly assigned to it without
303 closing the previous \c stderr (since this would also close
304 \c stdout).
305*/
306#define stderr (__iob[2])
307
308/**
309 \c EOF declares the value that is returned by various standard IO
310 functions in case of an error. Since the AVR platform (currently)
311 doesn't contain an abstraction for actual files, its origin as
312 "end of file" is somewhat meaningless here.
313*/
314#define EOF (-1)
315
316/** This macro inserts a pointer to user defined data into a FILE
317 stream object.
318
319 The user data can be useful for tracking state in the put and get
320 functions supplied to the fdevopen() function. */
321#define fdev_set_udata(stream, u) do { (stream)->udata = u; } while(0)
322
323/** This macro retrieves a pointer to user defined data from a FILE
324 stream object. */
325#define fdev_get_udata(stream) ((stream)->udata)
326
327#if defined(__DOXYGEN__)
328/**
329 \brief Setup a user-supplied buffer as an stdio stream
330
331 This macro takes a user-supplied buffer \c stream, and sets it up
332 as a stream that is valid for stdio operations, similar to one that
333 has been obtained dynamically from fdevopen(). The buffer to setup
334 must be of type FILE.
335
336 The arguments \c put and \c get are identical to those that need to
337 be passed to fdevopen().
338
339 The \c rwflag argument can take one of the values _FDEV_SETUP_READ,
340 _FDEV_SETUP_WRITE, or _FDEV_SETUP_RW, for read, write, or read/write
341 intent, respectively.
342
343 \note No assignments to the standard streams will be performed by
344 fdev_setup_stream(). If standard streams are to be used, these
345 need to be assigned by the user. See also under
346 \ref stdio_without_malloc "Running stdio without malloc()".
347 */
348#define fdev_setup_stream(stream, put, get, rwflag)
349#else /* !DOXYGEN */
350#define fdev_setup_stream(stream, p, g, f) \
351 do { \
352 (stream)->put = p; \
353 (stream)->get = g; \
354 (stream)->flags = f; \
355 (stream)->udata = 0; \
356 } while(0)
357#endif /* DOXYGEN */
358
359#define _FDEV_SETUP_READ __SRD /**< fdev_setup_stream() with read intent */
360#define _FDEV_SETUP_WRITE __SWR /**< fdev_setup_stream() with write intent */
361#define _FDEV_SETUP_RW (__SRD|__SWR) /**< fdev_setup_stream() with read/write intent */
362
363/**
364 * Return code for an error condition during device read.
365 *
366 * To be used in the get function of fdevopen().
367 */
368#define _FDEV_ERR (-1)
369
370/**
371 * Return code for an end-of-file condition during device read.
372 *
373 * To be used in the get function of fdevopen().
374 */
375#define _FDEV_EOF (-2)
376
377#if defined(__DOXYGEN__)
378/**
379 \brief Initializer for a user-supplied stdio stream
380
381 This macro acts similar to fdev_setup_stream(), but it is to be
382 used as the initializer of a variable of type FILE.
383
384 The remaining arguments are to be used as explained in
385 fdev_setup_stream().
386 */
387#define FDEV_SETUP_STREAM(put, get, rwflag)
388#else /* !DOXYGEN */
389#define FDEV_SETUP_STREAM(p, g, f) \
390 { \
391 .put = p, \
392 .get = g, \
393 .flags = f, \
394 .udata = 0, \
395 }
396#endif /* DOXYGEN */
397
398#ifdef __cplusplus
399extern "C" {
400#endif
401
402#if !defined(__DOXYGEN__)
403/*
404 * Doxygen documentation can be found in fdevopen.c.
405 */
406
407extern struct __file *__iob[];
408
409#if defined(__STDIO_FDEVOPEN_COMPAT_12)
410/*
411 * Declare prototype for the discontinued version of fdevopen() that
412 * has been in use up to avr-libc 1.2.x. The new implementation has
413 * some backwards compatibility with the old version.
414 */
415extern FILE *fdevopen(int (*__put)(char), int (*__get)(void),
416 int __opts __attribute__((unused)));
417#else /* !defined(__STDIO_FDEVOPEN_COMPAT_12) */
418/* New prototype for avr-libc 1.4 and above. */
419extern FILE *fdevopen(int (*__put)(char, FILE*), int (*__get)(FILE*));
420#endif /* defined(__STDIO_FDEVOPEN_COMPAT_12) */
421
422#endif /* not __DOXYGEN__ */
423
424/**
425 This function closes \c stream, and disallows and further
426 IO to and from it.
427
428 When using fdevopen() to setup the stream, a call to fclose() is
429 needed in order to free the internal resources allocated.
430
431 If the stream has been set up using fdev_setup_stream() or
432 FDEV_SETUP_STREAM(), use fdev_close() instead.
433
434 It currently always returns 0 (for success).
435*/
436extern int fclose(FILE *__stream);
437
438/**
439 This macro frees up any library resources that might be associated
440 with \c stream. It should be called if \c stream is no longer
441 needed, right before the application is going to destroy the
442 \c stream object itself.
443
444 (Currently, this macro evaluates to nothing, but this might change
445 in future versions of the library.)
446*/
447#if defined(__DOXYGEN__)
448# define fdev_close()
449#else
450# define fdev_close() ((void)0)
451#endif
452
453/**
454 \c vfprintf is the central facility of the \c printf family of
455 functions. It outputs values to \c stream under control of a
456 format string passed in \c fmt. The actual values to print are
457 passed as a variable argument list \c ap.
458
459 \c vfprintf returns the number of characters written to \c stream,
460 or \c EOF in case of an error. Currently, this will only happen
461 if \c stream has not been opened with write intent.
462
463 The format string is composed of zero or more directives: ordinary
464 characters (not \c %), which are copied unchanged to the output
465 stream; and conversion specifications, each of which results in
466 fetching zero or more subsequent arguments. Each conversion
467 specification is introduced by the \c % character. The arguments must
468 properly correspond (after type promotion) with the conversion
469 specifier. After the \c %, the following appear in sequence:
470
471 - Zero or more of the following flags:
472 <ul>
473 <li> \c # The value should be converted to an "alternate form". For
474 c, d, i, s, and u conversions, this option has no effect.
475 For o conversions, the precision of the number is
476 increased to force the first character of the output
477 string to a zero (except if a zero value is printed with
478 an explicit precision of zero). For x and X conversions,
479 a non-zero result has the string `0x' (or `0X' for X
480 conversions) prepended to it.</li>
481 <li> \c 0 (zero) Zero padding. For all conversions, the converted
482 value is padded on the left with zeros rather than blanks.
483 If a precision is given with a numeric conversion (d, i,
484 o, u, i, x, and X), the 0 flag is ignored.</li>
485 <li> \c - A negative field width flag; the converted value is to be
486 left adjusted on the field boundary. The converted value
487 is padded on the right with blanks, rather than on the
488 left with blanks or zeros. A - overrides a 0 if both are
489 given.</li>
490 <li> ' ' (space) A blank should be left before a positive number
491 produced by a signed conversion (d, or i).</li>
492 <li> \c + A sign must always be placed before a number produced by a
493 signed conversion. A + overrides a space if both are
494 used.</li>
495 </ul>
496
497 - An optional decimal digit string specifying a minimum field width.
498 If the converted value has fewer characters than the field width, it
499 will be padded with spaces on the left (or right, if the left-adjustment
500 flag has been given) to fill out the field width.
501 - An optional precision, in the form of a period . followed by an
502 optional digit string. If the digit string is omitted, the
503 precision is taken as zero. This gives the minimum number of
504 digits to appear for d, i, o, u, x, and X conversions, or the
505 maximum number of characters to be printed from a string for \c s
506 conversions.
507 - An optional \c l or \c h length modifier, that specifies that the
508 argument for the d, i, o, u, x, or X conversion is a \c "long int"
509 rather than \c int. The \c h is ignored, as \c "short int" is
510 equivalent to \c int.
511 - A character that specifies the type of conversion to be applied.
512
513 The conversion specifiers and their meanings are:
514
515 - \c diouxX The int (or appropriate variant) argument is converted
516 to signed decimal (d and i), unsigned octal (o), unsigned
517 decimal (u), or unsigned hexadecimal (x and X) notation.
518 The letters "abcdef" are used for x conversions; the
519 letters "ABCDEF" are used for X conversions. The
520 precision, if any, gives the minimum number of digits that
521 must appear; if the converted value requires fewer digits,
522 it is padded on the left with zeros.
523 - \c p The <tt>void *</tt> argument is taken as an unsigned integer,
524 and converted similarly as a <tt>%\#x</tt> command would do.
525 - \c c The \c int argument is converted to an \c "unsigned char", and the
526 resulting character is written.
527 - \c s The \c "char *" argument is expected to be a pointer to an array
528 of character type (pointer to a string). Characters from
529 the array are written up to (but not including) a
530 terminating NUL character; if a precision is specified, no
531 more than the number specified are written. If a precision
532 is given, no null character need be present; if the
533 precision is not specified, or is greater than the size of
534 the array, the array must contain a terminating NUL
535 character.
536 - \c % A \c % is written. No argument is converted. The complete
537 conversion specification is "%%".
538 - \c eE The double argument is rounded and converted in the format
539 \c "[-]d.ddde±dd" where there is one digit before the
540 decimal-point character and the number of digits after it
541 is equal to the precision; if the precision is missing, it
542 is taken as 6; if the precision is zero, no decimal-point
543 character appears. An \e E conversion uses the letter \c 'E'
544 (rather than \c 'e') to introduce the exponent. The exponent
545 always contains two digits; if the value is zero,
546 the exponent is 00.
547 - \c fF The double argument is rounded and converted to decimal notation
548 in the format \c "[-]ddd.ddd", where the number of digits after the
549 decimal-point character is equal to the precision specification.
550 If the precision is missing, it is taken as 6; if the precision
551 is explicitly zero, no decimal-point character appears. If a
552 decimal point appears, at least one digit appears before it.
553 - \c gG The double argument is converted in style \c f or \c e (or
554 \c F or \c E for \c G conversions). The precision
555 specifies the number of significant digits. If the
556 precision is missing, 6 digits are given; if the precision
557 is zero, it is treated as 1. Style \c e is used if the
558 exponent from its conversion is less than -4 or greater
559 than or equal to the precision. Trailing zeros are removed
560 from the fractional part of the result; a decimal point
561 appears only if it is followed by at least one digit.
562 - \c S Similar to the \c s format, except the pointer is expected to
563 point to a program-memory (ROM) string instead of a RAM string.
564
565 In no case does a non-existent or small field width cause truncation of a
566 numeric field; if the result of a conversion is wider than the field
567 width, the field is expanded to contain the conversion result.
568
569 Since the full implementation of all the mentioned features becomes
570 fairly large, three different flavours of vfprintf() can be
571 selected using linker options. The default vfprintf() implements
572 all the mentioned functionality except floating point conversions.
573 A minimized version of vfprintf() is available that only implements
574 the very basic integer and string conversion facilities, but only
575 the \c # additional option can be specified using conversion
576 flags (these flags are parsed correctly from the format
577 specification, but then simply ignored). This version can be
578 requested using the following \ref gcc_minusW "compiler options":
579
580 \code
581 -Wl,-u,vfprintf -lprintf_min
582 \endcode
583
584 If the full functionality including the floating point conversions
585 is required, the following options should be used:
586
587 \code
588 -Wl,-u,vfprintf -lprintf_flt -lm
589 \endcode
590
591 \par Limitations:
592 - The specified width and precision can be at most 255.
593
594 \par Notes:
595 - For floating-point conversions, if you link default or minimized
596 version of vfprintf(), the symbol \c ? will be output and double
597 argument will be skiped. So you output below will not be crashed.
598 For default version the width field and the "pad to left" ( symbol
599 minus ) option will work in this case.
600 - The \c hh length modifier is ignored (\c char argument is
601 promouted to \c int). More exactly, this realization does not check
602 the number of \c h symbols.
603 - But the \c ll length modifier will to abort the output, as this
604 realization does not operate \c long \c long arguments.
605 - The variable width or precision field (an asterisk \c * symbol)
606 is not realized and will to abort the output.
607
608 */
609
610extern int vfprintf(FILE *__stream, const char *__fmt, va_list __ap);
611
612/**
613 Variant of \c vfprintf() that uses a \c fmt string that resides
614 in program memory.
615*/
616extern int vfprintf_P(FILE *__stream, const char *__fmt, va_list __ap);
617
618/**
619 The function \c fputc sends the character \c c (though given as type
620 \c int) to \c stream. It returns the character, or \c EOF in case
621 an error occurred.
622*/
623extern int fputc(int __c, FILE *__stream);
624
625#if !defined(__DOXYGEN__)
626
627/* putc() function implementation, required by standard */
628extern int putc(int __c, FILE *__stream);
629
630/* putchar() function implementation, required by standard */
631extern int putchar(int __c);
632
633#endif /* not __DOXYGEN__ */
634
635/**
636 The macro \c putc used to be a "fast" macro implementation with a
637 functionality identical to fputc(). For space constraints, in
638 \c avr-libc, it is just an alias for \c fputc.
639*/
640#define putc(__c, __stream) fputc(__c, __stream)
641
642/**
643 The macro \c putchar sends character \c c to \c stdout.
644*/
645#define putchar(__c) fputc(__c, stdout)
646
647/**
648 The function \c printf performs formatted output to stream
649 \c stdout. See \c vfprintf() for details.
650*/
651extern int printf(const char *__fmt, ...);
652
653/**
654 Variant of \c printf() that uses a \c fmt string that resides
655 in program memory.
656*/
657extern int printf_P(const char *__fmt, ...);
658
659/**
660 The function \c vprintf performs formatted output to stream
661 \c stdout, taking a variable argument list as in vfprintf().
662
663 See vfprintf() for details.
664*/
665extern int vprintf(const char *__fmt, va_list __ap);
666
667/**
668 Variant of \c printf() that sends the formatted characters
669 to string \c s.
670*/
671extern int sprintf(char *__s, const char *__fmt, ...);
672
673/**
674 Variant of \c sprintf() that uses a \c fmt string that resides
675 in program memory.
676*/
677extern int sprintf_P(char *__s, const char *__fmt, ...);
678
679/**
680 Like \c sprintf(), but instead of assuming \c s to be of infinite
681 size, no more than \c n characters (including the trailing NUL
682 character) will be converted to \c s.
683
684 Returns the number of characters that would have been written to
685 \c s if there were enough space.
686*/
687extern int snprintf(char *__s, size_t __n, const char *__fmt, ...);
688
689/**
690 Variant of \c snprintf() that uses a \c fmt string that resides
691 in program memory.
692*/
693extern int snprintf_P(char *__s, size_t __n, const char *__fmt, ...);
694
695/**
696 Like \c sprintf() but takes a variable argument list for the
697 arguments.
698*/
699extern int vsprintf(char *__s, const char *__fmt, va_list ap);
700
701/**
702 Variant of \c vsprintf() that uses a \c fmt string that resides
703 in program memory.
704*/
705extern int vsprintf_P(char *__s, const char *__fmt, va_list ap);
706
707/**
708 Like \c vsprintf(), but instead of assuming \c s to be of infinite
709 size, no more than \c n characters (including the trailing NUL
710 character) will be converted to \c s.
711
712 Returns the number of characters that would have been written to
713 \c s if there were enough space.
714*/
715extern int vsnprintf(char *__s, size_t __n, const char *__fmt, va_list ap);
716
717/**
718 Variant of \c vsnprintf() that uses a \c fmt string that resides
719 in program memory.
720*/
721extern int vsnprintf_P(char *__s, size_t __n, const char *__fmt, va_list ap);
722/**
723 The function \c fprintf performs formatted output to \c stream.
724 See \c vfprintf() for details.
725*/
726extern int fprintf(FILE *__stream, const char *__fmt, ...);
727
728/**
729 Variant of \c fprintf() that uses a \c fmt string that resides
730 in program memory.
731*/
732extern int fprintf_P(FILE *__stream, const char *__fmt, ...);
733
734/**
735 Write the string pointed to by \c str to stream \c stream.
736
737 Returns 0 on success and EOF on error.
738*/
739extern int fputs(const char *__str, FILE *__stream);
740
741/**
742 Variant of fputs() where \c str resides in program memory.
743*/
744extern int fputs_P(const char *__str, FILE *__stream);
745
746/**
747 Write the string pointed to by \c str, and a trailing newline
748 character, to \c stdout.
749*/
750extern int puts(const char *__str);
751
752/**
753 Variant of puts() where \c str resides in program memory.
754*/
755extern int puts_P(const char *__str);
756
757/**
758 Write \c nmemb objects, \c size bytes each, to \c stream.
759 The first byte of the first object is referenced by \c ptr.
760
761 Returns the number of objects successfully written, i. e.
762 \c nmemb unless an output error occured.
763 */
764extern size_t fwrite(const void *__ptr, size_t __size, size_t __nmemb,
765 FILE *__stream);
766
767/**
768 The function \c fgetc reads a character from \c stream. It returns
769 the character, or \c EOF in case end-of-file was encountered or an
770 error occurred. The routines feof() or ferror() must be used to
771 distinguish between both situations.
772*/
773extern int fgetc(FILE *__stream);
774
775#if !defined(__DOXYGEN__)
776
777/* getc() function implementation, required by standard */
778extern int getc(FILE *__stream);
779
780/* getchar() function implementation, required by standard */
781extern int getchar(void);
782
783#endif /* not __DOXYGEN__ */
784
785/**
786 The macro \c getc used to be a "fast" macro implementation with a
787 functionality identical to fgetc(). For space constraints, in
788 \c avr-libc, it is just an alias for \c fgetc.
789*/
790#define getc(__stream) fgetc(__stream)
791
792/**
793 The macro \c getchar reads a character from \c stdin. Return
794 values and error handling is identical to fgetc().
795*/
796#define getchar() fgetc(stdin)
797
798/**
799 The ungetc() function pushes the character \c c (converted to an
800 unsigned char) back onto the input stream pointed to by \c stream.
801 The pushed-back character will be returned by a subsequent read on
802 the stream.
803
804 Currently, only a single character can be pushed back onto the
805 stream.
806
807 The ungetc() function returns the character pushed back after the
808 conversion, or \c EOF if the operation fails. If the value of the
809 argument \c c character equals \c EOF, the operation will fail and
810 the stream will remain unchanged.
811*/
812extern int ungetc(int __c, FILE *__stream);
813
814/**
815 Read at most <tt>size - 1</tt> bytes from \c stream, until a
816 newline character was encountered, and store the characters in the
817 buffer pointed to by \c str. Unless an error was encountered while
818 reading, the string will then be terminated with a \c NUL
819 character.
820
821 If an error was encountered, the function returns NULL and sets the
822 error flag of \c stream, which can be tested using ferror().
823 Otherwise, a pointer to the string will be returned. */
824extern char *fgets(char *__str, int __size, FILE *__stream);
825
826/**
827 Similar to fgets() except that it will operate on stream \c stdin,
828 and the trailing newline (if any) will not be stored in the string.
829 It is the caller's responsibility to provide enough storage to hold
830 the characters read. */
831extern char *gets(char *__str);
832
833/**
834 Read \c nmemb objects, \c size bytes each, from \c stream,
835 to the buffer pointed to by \c ptr.
836
837 Returns the number of objects successfully read, i. e.
838 \c nmemb unless an input error occured or end-of-file was
839 encountered. feof() and ferror() must be used to distinguish
840 between these two conditions.
841 */
842extern size_t fread(void *__ptr, size_t __size, size_t __nmemb,
843 FILE *__stream);
844
845/**
846 Clear the error and end-of-file flags of \c stream.
847 */
848extern void clearerr(FILE *__stream);
849
850#if !defined(__DOXYGEN__)
851/* fast inlined version of clearerr() */
852#define clearerror(s) do { (s)->flags &= ~(__SERR | __SEOF); } while(0)
853#endif /* !defined(__DOXYGEN__) */
854
855/**
856 Test the end-of-file flag of \c stream. This flag can only be cleared
857 by a call to clearerr().
858 */
859extern int feof(FILE *__stream);
860
861#if !defined(__DOXYGEN__)
862/* fast inlined version of feof() */
863#define feof(s) ((s)->flags & __SEOF)
864#endif /* !defined(__DOXYGEN__) */
865
866/**
867 Test the error flag of \c stream. This flag can only be cleared
868 by a call to clearerr().
869 */
870extern int ferror(FILE *__stream);
871
872#if !defined(__DOXYGEN__)
873/* fast inlined version of ferror() */
874#define ferror(s) ((s)->flags & __SERR)
875#endif /* !defined(__DOXYGEN__) */
876
877extern int vfscanf(FILE *__stream, const char *__fmt, va_list __ap);
878
879/**
880 Variant of vfscanf() using a \c fmt string in program memory.
881 */
882extern int vfscanf_P(FILE *__stream, const char *__fmt, va_list __ap);
883
884/**
885 The function \c fscanf performs formatted input, reading the
886 input data from \c stream.
887
888 See vfscanf() for details.
889 */
890extern int fscanf(FILE *__stream, const char *__fmt, ...);
891
892/**
893 Variant of fscanf() using a \c fmt string in program memory.
894 */
895extern int fscanf_P(FILE *__stream, const char *__fmt, ...);
896
897/**
898 The function \c scanf performs formatted input from stream \c stdin.
899
900 See vfscanf() for details.
901 */
902extern int scanf(const char *__fmt, ...);
903
904/**
905 Variant of scanf() where \c fmt resides in program memory.
906 */
907extern int scanf_P(const char *__fmt, ...);
908
909/**
910 The function \c vscanf performs formatted input from stream
911 \c stdin, taking a variable argument list as in vfscanf().
912
913 See vfscanf() for details.
914*/
915extern int vscanf(const char *__fmt, va_list __ap);
916
917/**
918 The function \c sscanf performs formatted input, reading the
919 input data from the buffer pointed to by \c buf.
920
921 See vfscanf() for details.
922 */
923extern int sscanf(const char *__buf, const char *__fmt, ...);
924
925/**
926 Variant of sscanf() using a \c fmt string in program memory.
927 */
928extern int sscanf_P(const char *__buf, const char *__fmt, ...);
929
930#if defined(__DOXYGEN__)
931/**
932 Flush \c stream.
933
934 This is a null operation provided for source-code compatibility
935 only, as the standard IO implementation currently does not perform
936 any buffering.
937 */
938extern int fflush(FILE *stream);
939#else
940static __inline__ int fflush(FILE *stream __attribute__((unused)))
941{
942 return 0;
943}
944#endif
945
946#ifndef __DOXYGEN__
947/* only mentioned for libstdc++ support, not implemented in library */
948#define BUFSIZ 1024
949#define _IONBF 0
950__extension__ typedef long long fpos_t;
951extern int fgetpos(FILE *stream, fpos_t *pos);
952extern FILE *fopen(const char *path, const char *mode);
953extern FILE *freopen(const char *path, const char *mode, FILE *stream);
954extern FILE *fdopen(int, const char *);
955extern int fseek(FILE *stream, long offset, int whence);
956extern int fsetpos(FILE *stream, fpos_t *pos);
957extern long ftell(FILE *stream);
958extern int fileno(FILE *);
959extern void perror(const char *s);
960extern int remove(const char *pathname);
961extern int rename(const char *oldpath, const char *newpath);
962extern void rewind(FILE *stream);
963extern void setbuf(FILE *stream, char *buf);
964extern int setvbuf(FILE *stream, char *buf, int mode, size_t size);
965extern FILE *tmpfile(void);
966extern char *tmpnam (char *s);
967#endif /* !__DOXYGEN__ */
968
969#ifdef __cplusplus
970}
971#endif
972
973/*@}*/
974
975#ifndef __DOXYGEN__
976/*
977 * The following constants are currently not used by avr-libc's
978 * stdio subsystem. They are defined here since the gcc build
979 * environment expects them to be here.
980 */
981#define SEEK_SET 0
982#define SEEK_CUR 1
983#define SEEK_END 2
984
985#endif
986
987#endif /* __ASSEMBLER */
988
989#endif /* _STDLIB_H_ */
unsigned char uint8_t
Definition: stdint.h:83
FILE * fdevopen(int(*put)(char, FILE *), int(*get)(FILE *))
Definition: fdevopen.c:87
static __inline void __attribute__((__always_inline__)) __power_all_enable()
Definition: power.h:1188
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:640
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
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:645
int vfscanf(FILE *__stream, const char *__fmt, va_list __ap)
Definition: vfscanf.c:704
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:286
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:796
int vsnprintf(char *__s, size_t __n, const char *__fmt, va_list ap)
Definition: vsnprintf.c:39
#define getc(__stream)
Definition: stdio.h:790
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:277
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