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