avr-libc  2.0.0 Standard C library for AVR-GCC
stdio.h
Go to the documentation of this file.
1 /* Copyright (c) 2002, 2005, 2007 Joerg Wunsch
3
4  Portions of documentation Copyright (c) 1990, 1991, 1993
5  The Regents of the University of California.
6
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: stdio_8h_source.html,v 1.1.1.6 2016/02/09 07:13:48 joerg_wunsch Exp$
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
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  */
244 struct __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 */
277 typedef 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,
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
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
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
399 extern "C" {
400 #endif
401
402 #if !defined(__DOXYGEN__)
403 /*
404  * Doxygen documentation can be found in fdevopen.c.
405  */
406
407 extern 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  */
415 extern 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. */
419 extern 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
433
434  It currently always returns 0 (for success).
435 */
436 extern 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
610 extern 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 */
616 extern 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 */
623 extern int fputc(int __c, FILE *__stream);
624
625 #if !defined(__DOXYGEN__)
626
627 /* putc() function implementation, required by standard */
628 extern int putc(int __c, FILE *__stream);
629
630 /* putchar() function implementation, required by standard */
631 extern 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 */
651 extern 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 */
657 extern 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 */
665 extern 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 */
671 extern 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 */
677 extern 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 */
687 extern 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 */
693 extern 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 */
699 extern 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 */
705 extern 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 */
715 extern 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 */
721 extern 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 */
726 extern 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 */
732 extern 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 */
739 extern int fputs(const char *__str, FILE *__stream);
740
741 /**
742  Variant of fputs() where \c str resides in program memory.
743 */
744 extern 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 */
750 extern int puts(const char *__str);
751
752 /**
753  Variant of puts() where \c str resides in program memory.
754 */
755 extern 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  */
764 extern 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 */
773 extern int fgetc(FILE *__stream);
774
775 #if !defined(__DOXYGEN__)
776
777 /* getc() function implementation, required by standard */
778 extern int getc(FILE *__stream);
779
780 /* getchar() function implementation, required by standard */
781 extern 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 */
812 extern 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. */
824 extern 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
831 extern 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  */
842 extern 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  */
848 extern 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  */
859 extern 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  */
870 extern 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
877 extern 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  */
882 extern 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  */
890 extern int fscanf(FILE *__stream, const char *__fmt, ...);
891
892 /**
893  Variant of fscanf() using a \c fmt string in program memory.
894  */
895 extern 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  */
902 extern int scanf(const char *__fmt, ...);
903
904 /**
905  Variant of scanf() where \c fmt resides in program memory.
906  */
907 extern 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 */
915 extern 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  */
923 extern int sscanf(const char *__buf, const char *__fmt, ...);
924
925 /**
926  Variant of sscanf() using a \c fmt string in program memory.
927  */
928 extern 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  */
938 extern int fflush(FILE *stream);
939 #else
940 static __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;
951 extern int fgetpos(FILE *stream, fpos_t *pos);
952 extern FILE *fopen(const char *path, const char *mode);
953 extern FILE *freopen(const char *path, const char *mode, FILE *stream);
954 extern FILE *fdopen(int, const char *);
955 extern int fseek(FILE *stream, long offset, int whence);
956 extern int fsetpos(FILE *stream, fpos_t *pos);
957 extern long ftell(FILE *stream);
958 extern int fileno(FILE *);
959 extern void perror(const char *s);
960 extern int remove(const char *pathname);
961 extern int rename(const char *oldpath, const char *newpath);
962 extern void rewind(FILE *stream);
963 extern void setbuf(FILE *stream, char *buf);
964 extern int setvbuf(FILE *stream, char *buf, int mode, size_t size);
965 extern FILE *tmpfile(void);
966 extern 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_ */
int vfscanf(FILE *__stream, const char *__fmt, va_list __ap)
Definition: vfscanf.c:704
int vprintf(const char *__fmt, va_list __ap)
Definition: vprintf.c:38
size_t fwrite(const void *__ptr, size_t __size, size_t __nmemb, FILE *__stream)
Definition: fwrite.c:38
int scanf(const char *__fmt,...)
Definition: scanf.c:38
#define getc(__stream)
Definition: stdio.h:790
struct __file FILE
Definition: stdio.h:277
int vscanf(const char *__fmt, va_list __ap)
Definition: vscanf.c:38
int fflush(FILE *stream)
int puts_P(const char *__str)
Definition: puts_p.c:41
int fclose(FILE *__stream)
Definition: fclose.c:40
int sprintf(char *__s, const char *__fmt,...)
Definition: sprintf.c:40
int snprintf_P(char *__s, size_t __n, const char *__fmt,...)
Definition: snprintf_p.c:39
int vfscanf_P(FILE *__stream, const char *__fmt, va_list __ap)
Definition: vfscanf_p.c:38
int vsnprintf(char *__s, size_t __n, const char *__fmt, va_list ap)
Definition: vsnprintf.c:39
#define putc(__c, __stream)
Definition: stdio.h:640
int sscanf(const char *__buf, const char *__fmt,...)
Definition: sscanf.c:40
int ferror(FILE *__stream)
Definition: ferror.c:40
int puts(const char *__str)
Definition: puts.c:38
int printf_P(const char *__fmt,...)
Definition: printf_p.c:39
int vsprintf(char *__s, const char *__fmt, va_list ap)
Definition: vsprintf.c:40
static __inline void __attribute__((__always_inline__)) __power_all_enable()
Definition: power.h:1148
FILE * fdevopen(int(*put)(char, FILE *), int(*get)(FILE *))
Definition: fdevopen.c:87
int scanf_P(const char *__fmt,...)
Definition: scanf_p.c:39
int vsprintf_P(char *__s, const char *__fmt, va_list ap)
Definition: vsprintf_p.c:40
char * gets(char *__str)
Definition: gets.c:38
int vfprintf_P(FILE *__stream, const char *__fmt, va_list __ap)
Definition: vfprintf_p.c:38
int fputs_P(const char *__str, FILE *__stream)
Definition: fputs_p.c:41
void clearerr(FILE *__stream)
Definition: clearerr.c:40
int fputs(const char *__str, FILE *__stream)
Definition: fputs.c:38
int snprintf(char *__s, size_t __n, const char *__fmt,...)
Definition: snprintf.c:39
#define putchar(__c)
Definition: stdio.h:645
unsigned char uint8_t
Definition: stdint.h:83
int fprintf_P(FILE *__stream, const char *__fmt,...)
Definition: fprintf_p.c:39
int feof(FILE *__stream)
Definition: feof.c:40
int fputc(int __c, FILE *__stream)
Definition: fputc.c:38
int fprintf(FILE *__stream, const char *__fmt,...)
Definition: fprintf.c:38
char * fgets(char *__str, int __size, FILE *__stream)
Definition: fgets.c:38
int fgetc(FILE *__stream)
Definition: fgetc.c:38
size_t fread(void *__ptr, size_t __size, size_t __nmemb, FILE *__stream)
int ungetc(int __c, FILE *__stream)
Definition: ungetc.c:38
int sscanf_P(const char *__buf, const char *__fmt,...)
Definition: sscanf_p.c:40
#define getchar()
Definition: stdio.h:796
int vsnprintf_P(char *__s, size_t __n, const char *__fmt, va_list ap)
Definition: vsnprintf_p.c:39
int fscanf(FILE *__stream, const char *__fmt,...)
Definition: fscanf.c:38
int fscanf_P(FILE *__stream, const char *__fmt,...)
Definition: fscanf_p.c:39
int printf(const char *__fmt,...)
Definition: printf.c:38
int sprintf_P(char *__s, const char *__fmt,...)
Definition: sprintf_p.c:40
int vfprintf(FILE *__stream, const char *__fmt, va_list __ap)
Definition: vfprintf.c:286