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