update from main archive 961114
[kopensolaris-gnu/glibc.git] / manual / stdio.texi
1 @node I/O on Streams, Low-Level I/O, I/O Overview, Top
2 @chapter Input/Output on Streams
3
4 This chapter describes the functions for creating streams and performing
5 input and output operations on them.  As discussed in @ref{I/O
6 Overview}, a stream is a fairly abstract, high-level concept
7 representing a communications channel to a file, device, or process.
8
9 @menu
10 * Streams::                     About the data type representing a stream.
11 * Standard Streams::            Streams to the standard input and output
12                                  devices are created for you.
13 * Opening Streams::             How to create a stream to talk to a file.
14 * Closing Streams::             Close a stream when you are finished with it.
15 * Simple Output::               Unformatted output by characters and lines.
16 * Character Input::             Unformatted input by characters and words.
17 * Line Input::                  Reading a line or a record from a stream.
18 * Unreading::                   Peeking ahead/pushing back input just read.
19 * Block Input/Output::          Input and output operations on blocks of data.
20 * Formatted Output::            @code{printf} and related functions.
21 * Customizing Printf::          You can define new conversion specifiers for
22                                  @code{printf} and friends.
23 * Formatted Input::             @code{scanf} and related functions.
24 * EOF and Errors::              How you can tell if an I/O error happens.
25 * Binary Streams::              Some systems distinguish between text files
26                                  and binary files.
27 * File Positioning::            About random-access streams.
28 * Portable Positioning::        Random access on peculiar ANSI C systems.
29 * Stream Buffering::            How to control buffering of streams.
30 * Other Kinds of Streams::      Streams that do not necessarily correspond
31                                  to an open file.
32 @end menu
33
34 @node Streams
35 @section Streams
36
37 For historical reasons, the type of the C data structure that represents
38 a stream is called @code{FILE} rather than ``stream''.  Since most of
39 the library functions deal with objects of type @code{FILE *}, sometimes
40 the term @dfn{file pointer} is also used to mean ``stream''.  This leads
41 to unfortunate confusion over terminology in many books on C.  This
42 manual, however, is careful to use the terms ``file'' and ``stream''
43 only in the technical sense.
44 @cindex file pointer
45
46 @pindex stdio.h
47 The @code{FILE} type is declared in the header file @file{stdio.h}.
48
49 @comment stdio.h
50 @comment ANSI
51 @deftp {Data Type} FILE
52 This is the data type used to represent stream objects.  A @code{FILE}
53 object holds all of the internal state information about the connection
54 to the associated file, including such things as the file position
55 indicator and buffering information.  Each stream also has error and
56 end-of-file status indicators that can be tested with the @code{ferror}
57 and @code{feof} functions; see @ref{EOF and Errors}.
58 @end deftp
59
60 @code{FILE} objects are allocated and managed internally by the
61 input/output library functions.  Don't try to create your own objects of
62 type @code{FILE}; let the library do it.  Your programs should
63 deal only with pointers to these objects (that is, @code{FILE *} values)
64 rather than the objects themselves.
65 @c !!! should say that FILE's have "No user-servicable parts inside."
66
67 @node Standard Streams
68 @section Standard Streams
69 @cindex standard streams
70 @cindex streams, standard
71
72 When the @code{main} function of your program is invoked, it already has
73 three predefined streams open and available for use.  These represent
74 the ``standard'' input and output channels that have been established
75 for the process.
76
77 These streams are declared in the header file @file{stdio.h}.
78 @pindex stdio.h
79
80 @comment stdio.h
81 @comment ANSI
82 @deftypevar {FILE *} stdin
83 The @dfn{standard input} stream, which is the normal source of input for the
84 program.
85 @end deftypevar
86 @cindex standard input stream
87
88 @comment stdio.h
89 @comment ANSI
90 @deftypevar {FILE *} stdout
91 The @dfn{standard output} stream, which is used for normal output from
92 the program.
93 @end deftypevar
94 @cindex standard output stream
95
96 @comment stdio.h
97 @comment ANSI
98 @deftypevar {FILE *} stderr
99 The @dfn{standard error} stream, which is used for error messages and
100 diagnostics issued by the program.
101 @end deftypevar
102 @cindex standard error stream
103
104 In the GNU system, you can specify what files or processes correspond to
105 these streams using the pipe and redirection facilities provided by the
106 shell.  (The primitives shells use to implement these facilities are
107 described in @ref{File System Interface}.)  Most other operating systems
108 provide similar mechanisms, but the details of how to use them can vary.
109
110 In the GNU C library, @code{stdin}, @code{stdout}, and @code{stderr} are
111 normal variables which you can set just like any others.  For example, to redirect
112 the standard output to a file, you could do:
113
114 @smallexample
115 fclose (stdout);
116 stdout = fopen ("standard-output-file", "w");
117 @end smallexample
118
119 Note however, that in other systems @code{stdin}, @code{stdout}, and
120 @code{stderr} are macros that you cannot assign to in the normal way.
121 But you can use @code{freopen} to get the effect of closing one and
122 reopening it.  @xref{Opening Streams}.
123
124 @node Opening Streams
125 @section Opening Streams
126
127 @cindex opening a stream
128 Opening a file with the @code{fopen} function creates a new stream and
129 establishes a connection between the stream and a file.  This may
130 involve creating a new file.
131
132 @pindex stdio.h
133 Everything described in this section is declared in the header file
134 @file{stdio.h}.
135
136 @comment stdio.h
137 @comment ANSI
138 @deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype})
139 The @code{fopen} function opens a stream for I/O to the file
140 @var{filename}, and returns a pointer to the stream.
141
142 The @var{opentype} argument is a string that controls how the file is
143 opened and specifies attributes of the resulting stream.  It must begin
144 with one of the following sequences of characters:
145
146 @table @samp
147 @item r
148 Open an existing file for reading only.
149
150 @item w
151 Open the file for writing only.  If the file already exists, it is
152 truncated to zero length.  Otherwise a new file is created.
153
154 @item a
155 Open a file for append access; that is, writing at the end of file only.
156 If the file already exists, its initial contents are unchanged and
157 output to the stream is appended to the end of the file.
158 Otherwise, a new, empty file is created.
159
160 @item r+
161 Open an existing file for both reading and writing.  The initial contents
162 of the file are unchanged and the initial file position is at the
163 beginning of the file.
164
165 @item w+
166 Open a file for both reading and writing.  If the file already exists, it
167 is truncated to zero length.  Otherwise, a new file is created.
168
169 @item a+
170 Open or create file for both reading and appending.  If the file exists,
171 its initial contents are unchanged.  Otherwise, a new file is created.
172 The initial file position for reading is at the beginning of the file,
173 but output is always appended to the end of the file.
174 @end table
175
176 As you can see, @samp{+} requests a stream that can do both input and
177 output.  The ANSI standard says that when using such a stream, you must
178 call @code{fflush} (@pxref{Stream Buffering}) or a file positioning
179 function such as @code{fseek} (@pxref{File Positioning}) when switching
180 from reading to writing or vice versa.  Otherwise, internal buffers
181 might not be emptied properly.  The GNU C library does not have this
182 limitation; you can do arbitrary reading and writing operations on a
183 stream in whatever order.
184
185 Additional characters may appear after these to specify flags for the
186 call.  Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is
187 the only part you are guaranteed will be understood by all systems.
188
189 The GNU C library defines one additional character for use in
190 @var{opentype}: the character @samp{x} insists on creating a new
191 file---if a file @var{filename} already exists, @code{fopen} fails
192 rather than opening it.  If you use @samp{x} you can are guaranteed that
193 you will not clobber an existing file.  This is equivalent to the
194 @code{O_EXCL} option to the @code{open} function (@pxref{Opening and
195 Closing Files}).
196
197 The character @samp{b} in @var{opentype} has a standard meaning; it
198 requests a binary stream rather than a text stream.  But this makes no
199 difference in POSIX systems (including the GNU system).  If both
200 @samp{+} and @samp{b} are specified, they can appear in either order.
201 @xref{Binary Streams}.
202
203 Any other characters in @var{opentype} are simply ignored.  They may be
204 meaningful in other systems.
205
206 If the open fails, @code{fopen} returns a null pointer.
207 @end deftypefun
208
209 You can have multiple streams (or file descriptors) pointing to the same
210 file open at the same time.  If you do only input, this works
211 straightforwardly, but you must be careful if any output streams are
212 included.  @xref{Stream/Descriptor Precautions}.  This is equally true
213 whether the streams are in one program (not usual) or in several
214 programs (which can easily happen).  It may be advantageous to use the
215 file locking facilities to avoid simultaneous access.  @xref{File
216 Locks}.
217
218 @comment stdio.h
219 @comment ANSI
220 @deftypevr Macro int FOPEN_MAX
221 The value of this macro is an integer constant expression that
222 represents the minimum number of streams that the implementation
223 guarantees can be open simultaneously.  You might be able to open more
224 than this many streams, but that is not guaranteed.  The value of this
225 constant is at least eight, which includes the three standard streams
226 @code{stdin}, @code{stdout}, and @code{stderr}.  In POSIX.1 systems this
227 value is determined by the @code{OPEN_MAX} parameter; @pxref{General
228 Limits}.  In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE}
229 resource limit; @pxref{Limits on Resources}.
230 @end deftypevr
231
232 @comment stdio.h
233 @comment ANSI
234 @deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
235 This function is like a combination of @code{fclose} and @code{fopen}.
236 It first closes the stream referred to by @var{stream}, ignoring any
237 errors that are detected in the process.  (Because errors are ignored,
238 you should not use @code{freopen} on an output stream if you have
239 actually done any output using the stream.)  Then the file named by
240 @var{filename} is opened with mode @var{opentype} as for @code{fopen},
241 and associated with the same stream object @var{stream}.
242
243 If the operation fails, a null pointer is returned; otherwise,
244 @code{freopen} returns @var{stream}.
245
246 @code{freopen} has traditionally been used to connect a standard stream
247 such as @code{stdin} with a file of your own choice.  This is useful in
248 programs in which use of a standard stream for certain purposes is
249 hard-coded.  In the GNU C library, you can simply close the standard
250 streams and open new ones with @code{fopen}.  But other systems lack
251 this ability, so using @code{freopen} is more portable.
252 @end deftypefun
253
254
255 @node Closing Streams
256 @section Closing Streams
257
258 @cindex closing a stream
259 When a stream is closed with @code{fclose}, the connection between the
260 stream and the file is cancelled.  After you have closed a stream, you
261 cannot perform any additional operations on it.
262
263 @comment stdio.h
264 @comment ANSI
265 @deftypefun int fclose (FILE *@var{stream})
266 This function causes @var{stream} to be closed and the connection to
267 the corresponding file to be broken.  Any buffered output is written
268 and any buffered input is discarded.  The @code{fclose} function returns
269 a value of @code{0} if the file was closed successfully, and @code{EOF}
270 if an error was detected.
271
272 It is important to check for errors when you call @code{fclose} to close
273 an output stream, because real, everyday errors can be detected at this
274 time.  For example, when @code{fclose} writes the remaining buffered
275 output, it might get an error because the disk is full.  Even if you
276 know the buffer is empty, errors can still occur when closing a file if
277 you are using NFS.
278
279 The function @code{fclose} is declared in @file{stdio.h}.
280 @end deftypefun
281
282 If the @code{main} function to your program returns, or if you call the
283 @code{exit} function (@pxref{Normal Termination}), all open streams are
284 automatically closed properly.  If your program terminates in any other
285 manner, such as by calling the @code{abort} function (@pxref{Aborting a
286 Program}) or from a fatal signal (@pxref{Signal Handling}), open streams
287 might not be closed properly.  Buffered output might not be flushed and
288 files may be incomplete.  For more information on buffering of streams,
289 see @ref{Stream Buffering}.
290
291 @node Simple Output
292 @section Simple Output by Characters or Lines
293
294 @cindex writing to a stream, by characters
295 This section describes functions for performing character- and
296 line-oriented output.
297
298 These functions are declared in the header file @file{stdio.h}.
299 @pindex stdio.h
300
301 @comment stdio.h
302 @comment ANSI
303 @deftypefun int fputc (int @var{c}, FILE *@var{stream})
304 The @code{fputc} function converts the character @var{c} to type
305 @code{unsigned char}, and writes it to the stream @var{stream}.
306 @code{EOF} is returned if a write error occurs; otherwise the
307 character @var{c} is returned.
308 @end deftypefun
309
310 @comment stdio.h
311 @comment ANSI
312 @deftypefun int putc (int @var{c}, FILE *@var{stream})
313 This is just like @code{fputc}, except that most systems implement it as
314 a macro, making it faster.  One consequence is that it may evaluate the
315 @var{stream} argument more than once, which is an exception to the
316 general rule for macros.  @code{putc} is usually the best function to
317 use for writing a single character.
318 @end deftypefun
319
320 @comment stdio.h
321 @comment ANSI
322 @deftypefun int putchar (int @var{c})
323 The @code{putchar} function is equivalent to @code{putc} with
324 @code{stdout} as the value of the @var{stream} argument.
325 @end deftypefun
326
327 @comment stdio.h
328 @comment ANSI
329 @deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
330 The function @code{fputs} writes the string @var{s} to the stream
331 @var{stream}.  The terminating null character is not written.
332 This function does @emph{not} add a newline character, either.
333 It outputs only the characters in the string.
334
335 This function returns @code{EOF} if a write error occurs, and otherwise
336 a non-negative value.
337
338 For example:
339
340 @smallexample
341 fputs ("Are ", stdout);
342 fputs ("you ", stdout);
343 fputs ("hungry?\n", stdout);
344 @end smallexample
345
346 @noindent
347 outputs the text @samp{Are you hungry?} followed by a newline.
348 @end deftypefun
349
350 @comment stdio.h
351 @comment ANSI
352 @deftypefun int puts (const char *@var{s})
353 The @code{puts} function writes the string @var{s} to the stream
354 @code{stdout} followed by a newline.  The terminating null character of
355 the string is not written.  (Note that @code{fputs} does @emph{not}
356 write a newline as this function does.)
357
358 @code{puts} is the most convenient function for printing simple
359 messages.  For example:
360
361 @smallexample
362 puts ("This is a message.");
363 @end smallexample
364 @end deftypefun
365
366 @comment stdio.h
367 @comment SVID
368 @deftypefun int putw (int @var{w}, FILE *@var{stream})
369 This function writes the word @var{w} (that is, an @code{int}) to
370 @var{stream}.  It is provided for compatibility with SVID, but we
371 recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
372 @end deftypefun
373
374 @node Character Input
375 @section Character Input
376
377 @cindex reading from a stream, by characters
378 This section describes functions for performing character-oriented input.
379 These functions are declared in the header file @file{stdio.h}.
380 @pindex stdio.h
381
382 These functions return an @code{int} value that is either a character of
383 input, or the special value @code{EOF} (usually -1).  It is important to
384 store the result of these functions in a variable of type @code{int}
385 instead of @code{char}, even when you plan to use it only as a
386 character.  Storing @code{EOF} in a @code{char} variable truncates its
387 value to the size of a character, so that it is no longer
388 distinguishable from the valid character @samp{(char) -1}.  So always
389 use an @code{int} for the result of @code{getc} and friends, and check
390 for @code{EOF} after the call; once you've verified that the result is
391 not @code{EOF}, you can be sure that it will fit in a @samp{char}
392 variable without loss of information.
393
394 @comment stdio.h
395 @comment ANSI
396 @deftypefun int fgetc (FILE *@var{stream})
397 This function reads the next character as an @code{unsigned char} from
398 the stream @var{stream} and returns its value, converted to an
399 @code{int}.  If an end-of-file condition or read error occurs,
400 @code{EOF} is returned instead.
401 @end deftypefun
402
403 @comment stdio.h
404 @comment ANSI
405 @deftypefun int getc (FILE *@var{stream})
406 This is just like @code{fgetc}, except that it is permissible (and
407 typical) for it to be implemented as a macro that evaluates the
408 @var{stream} argument more than once.  @code{getc} is often highly
409 optimized, so it is usually the best function to use to read a single
410 character.
411 @end deftypefun
412
413 @comment stdio.h
414 @comment ANSI
415 @deftypefun int getchar (void)
416 The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
417 as the value of the @var{stream} argument.
418 @end deftypefun
419
420 Here is an example of a function that does input using @code{fgetc}.  It
421 would work just as well using @code{getc} instead, or using
422 @code{getchar ()} instead of @w{@code{fgetc (stdin)}}.
423
424 @smallexample
425 int
426 y_or_n_p (const char *question)
427 @{
428   fputs (question, stdout);
429   while (1)
430     @{
431       int c, answer;
432       /* @r{Write a space to separate answer from question.} */
433       fputc (' ', stdout);
434       /* @r{Read the first character of the line.}
435          @r{This should be the answer character, but might not be.} */
436       c = tolower (fgetc (stdin));
437       answer = c;
438       /* @r{Discard rest of input line.} */
439       while (c != '\n' && c != EOF)
440         c = fgetc (stdin);
441       /* @r{Obey the answer if it was valid.} */
442       if (answer == 'y')
443         return 1;
444       if (answer == 'n')
445         return 0;
446       /* @r{Answer was invalid: ask for valid answer.} */
447       fputs ("Please answer y or n:", stdout);
448     @}
449 @}
450 @end smallexample
451
452 @comment stdio.h
453 @comment SVID
454 @deftypefun int getw (FILE *@var{stream})
455 This function reads a word (that is, an @code{int}) from @var{stream}.
456 It's provided for compatibility with SVID.  We recommend you use
457 @code{fread} instead (@pxref{Block Input/Output}).  Unlike @code{getc},
458 any @code{int} value could be a valid result.  @code{getw} returns
459 @code{EOF} when it encounters end-of-file or an error, but there is no
460 way to distinguish this from an input word with value -1.
461 @end deftypefun
462
463 @node Line Input
464 @section Line-Oriented Input
465
466 Since many programs interpret input on the basis of lines, it's
467 convenient to have functions to read a line of text from a stream.
468
469 Standard C has functions to do this, but they aren't very safe: null
470 characters and even (for @code{gets}) long lines can confuse them.  So
471 the GNU library provides the nonstandard @code{getline} function that
472 makes it easy to read lines reliably.
473
474 Another GNU extension, @code{getdelim}, generalizes @code{getline}.  It
475 reads a delimited record, defined as everything through the next
476 occurrence of a specified delimiter character.
477
478 All these functions are declared in @file{stdio.h}.
479
480 @comment stdio.h
481 @comment GNU
482 @deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
483 This function reads an entire line from @var{stream}, storing the text
484 (including the newline and a terminating null character) in a buffer
485 and storing the buffer address in @code{*@var{lineptr}}.
486
487 Before calling @code{getline}, you should place in @code{*@var{lineptr}}
488 the address of a buffer @code{*@var{n}} bytes long, allocated with
489 @code{malloc}.  If this buffer is long enough to hold the line,
490 @code{getline} stores the line in this buffer.  Otherwise,
491 @code{getline} makes the buffer bigger using @code{realloc}, storing the
492 new buffer address back in @code{*@var{lineptr}} and the increased size
493 back in @code{*@var{n}}.
494 @xref{Unconstrained Allocation}.
495
496 If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}}
497 to zero, before the call, then @code{getline} allocates the initial
498 buffer for you by calling @code{malloc}.
499
500 In either case, when @code{getline} returns,  @code{*@var{lineptr}} is
501 a @code{char *} which points to the text of the line.
502
503 When @code{getline} is successful, it returns the number of characters
504 read (including the newline, but not including the terminating null).
505 This value enables you to distinguish null characters that are part of
506 the line from the null character inserted as a terminator.
507
508 This function is a GNU extension, but it is the recommended way to read
509 lines from a stream.  The alternative standard functions are unreliable.
510
511 If an error occurs or end of file is reached, @code{getline} returns
512 @code{-1}.
513 @end deftypefun
514
515 @comment stdio.h
516 @comment GNU
517 @deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream})
518 This function is like @code{getline} except that the character which
519 tells it to stop reading is not necessarily newline.  The argument
520 @var{delimiter} specifies the delimiter character; @code{getdelim} keeps
521 reading until it sees that character (or end of file).
522
523 The text is stored in @var{lineptr}, including the delimiter character
524 and a terminating null.  Like @code{getline}, @code{getdelim} makes
525 @var{lineptr} bigger if it isn't big enough.
526
527 @code{getline} is in fact implemented in terms of @code{getdelim}, just
528 like this:
529
530 @smallexample
531 ssize_t
532 getline (char **lineptr, size_t *n, FILE *stream)
533 @{
534   return getdelim (lineptr, n, '\n', stream);
535 @}
536 @end smallexample
537 @end deftypefun
538
539 @comment stdio.h
540 @comment ANSI
541 @deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
542 The @code{fgets} function reads characters from the stream @var{stream}
543 up to and including a newline character and stores them in the string
544 @var{s}, adding a null character to mark the end of the string.  You
545 must supply @var{count} characters worth of space in @var{s}, but the
546 number of characters read is at most @var{count} @minus{} 1.  The extra
547 character space is used to hold the null character at the end of the
548 string.
549
550 If the system is already at end of file when you call @code{fgets}, then
551 the contents of the array @var{s} are unchanged and a null pointer is
552 returned.  A null pointer is also returned if a read error occurs.
553 Otherwise, the return value is the pointer @var{s}.
554
555 @strong{Warning:}  If the input data has a null character, you can't tell.
556 So don't use @code{fgets} unless you know the data cannot contain a null.
557 Don't use it to read files edited by the user because, if the user inserts
558 a null character, you should either handle it properly or print a clear
559 error message.  We recommend using @code{getline} instead of @code{fgets}.
560 @end deftypefun
561
562 @comment stdio.h
563 @comment ANSI
564 @deftypefn {Deprecated function} {char *} gets (char *@var{s})
565 The function @code{gets} reads characters from the stream @code{stdin}
566 up to the next newline character, and stores them in the string @var{s}.
567 The newline character is discarded (note that this differs from the
568 behavior of @code{fgets}, which copies the newline character into the
569 string).  If @code{gets} encounters a read error or end-of-file, it
570 returns a null pointer; otherwise it returns @var{s}.
571
572 @strong{Warning:} The @code{gets} function is @strong{very dangerous}
573 because it provides no protection against overflowing the string
574 @var{s}.  The GNU library includes it for compatibility only.  You
575 should @strong{always} use @code{fgets} or @code{getline} instead.  To
576 remind you of this, the linker (if using GNU @code{ld}) will issue a
577 warning whenever you use @code{gets}.
578 @end deftypefn
579
580 @node Unreading
581 @section Unreading
582 @cindex peeking at input
583 @cindex unreading characters
584 @cindex pushing input back
585
586 In parser programs it is often useful to examine the next character in
587 the input stream without removing it from the stream.  This is called
588 ``peeking ahead'' at the input because your program gets a glimpse of
589 the input it will read next.
590
591 Using stream I/O, you can peek ahead at input by first reading it and
592 then @dfn{unreading} it (also called  @dfn{pushing it back} on the stream).
593 Unreading a character makes it available to be input again from the stream,
594 by  the next call to @code{fgetc} or other input function on that stream.
595
596 @menu
597 * Unreading Idea::              An explanation of unreading with pictures.
598 * How Unread::                  How to call @code{ungetc} to do unreading.
599 @end menu
600
601 @node Unreading Idea
602 @subsection What Unreading Means
603
604 Here is a pictorial explanation of unreading.  Suppose you have a
605 stream reading a file that contains just six characters, the letters
606 @samp{foobar}.  Suppose you have read three characters so far.  The
607 situation looks like this:
608
609 @smallexample
610 f  o  o  b  a  r
611          ^
612 @end smallexample
613
614 @noindent
615 so the next input character will be @samp{b}.
616
617 @c @group   Invalid outside @example
618 If instead of reading @samp{b} you unread the letter @samp{o}, you get a
619 situation like this:
620
621 @smallexample
622 f  o  o  b  a  r
623          |
624       o--
625       ^
626 @end smallexample
627
628 @noindent
629 so that the next input characters will be @samp{o} and @samp{b}.
630 @c @end group
631
632 @c @group
633 If you unread @samp{9} instead of @samp{o}, you get this situation:
634
635 @smallexample
636 f  o  o  b  a  r
637          |
638       9--
639       ^
640 @end smallexample
641
642 @noindent
643 so that the next input characters will be @samp{9} and @samp{b}.
644 @c @end group
645
646 @node How Unread
647 @subsection Using @code{ungetc} To Do Unreading
648
649 The function to unread a character is called @code{ungetc}, because it
650 reverses the action of @code{getc}.
651
652 @comment stdio.h
653 @comment ANSI
654 @deftypefun int ungetc (int @var{c}, FILE *@var{stream})
655 The @code{ungetc} function pushes back the character @var{c} onto the
656 input stream @var{stream}.  So the next input from @var{stream} will
657 read @var{c} before anything else.
658
659 If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
660 @code{EOF}.  This lets you call @code{ungetc} with the return value of
661 @code{getc} without needing to check for an error from @code{getc}.
662
663 The character that you push back doesn't have to be the same as the last
664 character that was actually read from the stream.  In fact, it isn't
665 necessary to actually read any characters from the stream before
666 unreading them with @code{ungetc}!  But that is a strange way to write
667 a program; usually @code{ungetc} is used only to unread a character
668 that was just read from the same stream.
669
670 The GNU C library only supports one character of pushback---in other
671 words, it does not work to call @code{ungetc} twice without doing input
672 in between.  Other systems might let you push back multiple characters;
673 then reading from the stream retrieves the characters in the reverse
674 order that they were pushed.
675
676 Pushing back characters doesn't alter the file; only the internal
677 buffering for the stream is affected.  If a file positioning function
678 (such as @code{fseek} or @code{rewind}; @pxref{File Positioning}) is
679 called, any pending pushed-back characters are discarded.
680
681 Unreading a character on a stream that is at end of file clears the
682 end-of-file indicator for the stream, because it makes the character of
683 input available.  After you read that character, trying to read again
684 will encounter end of file.
685 @end deftypefun
686
687 Here is an example showing the use of @code{getc} and @code{ungetc} to
688 skip over whitespace characters.  When this function reaches a
689 non-whitespace character, it unreads that character to be seen again on
690 the next read operation on the stream.
691
692 @smallexample
693 #include <stdio.h>
694 #include <ctype.h>
695
696 void
697 skip_whitespace (FILE *stream)
698 @{
699   int c;
700   do
701     /* @r{No need to check for @code{EOF} because it is not}
702        @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.}  */
703     c = getc (stream);
704   while (isspace (c));
705   ungetc (c, stream);
706 @}
707 @end smallexample
708
709 @node Block Input/Output
710 @section Block Input/Output
711
712 This section describes how to do input and output operations on blocks
713 of data.  You can use these functions to read and write binary data, as
714 well as to read and write text in fixed-size blocks instead of by
715 characters or lines.
716 @cindex binary I/O to a stream
717 @cindex block I/O to a stream
718 @cindex reading from a stream, by blocks
719 @cindex writing to a stream, by blocks
720
721 Binary files are typically used to read and write blocks of data in the
722 same format as is used to represent the data in a running program.  In
723 other words, arbitrary blocks of memory---not just character or string
724 objects---can be written to a binary file, and meaningfully read in
725 again by the same program.
726
727 Storing data in binary form is often considerably more efficient than
728 using the formatted I/O functions.  Also, for floating-point numbers,
729 the binary form avoids possible loss of precision in the conversion
730 process.  On the other hand, binary files can't be examined or modified
731 easily using many standard file utilities (such as text editors), and
732 are not portable between different implementations of the language, or
733 different kinds of computers.
734
735 These functions are declared in @file{stdio.h}.
736 @pindex stdio.h
737
738 @comment stdio.h
739 @comment ANSI
740 @deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
741 This function reads up to @var{count} objects of size @var{size} into
742 the array @var{data}, from the stream @var{stream}.  It returns the
743 number of objects actually read, which might be less than @var{count} if
744 a read error occurs or the end of the file is reached.  This function
745 returns a value of zero (and doesn't read anything) if either @var{size}
746 or @var{count} is zero.
747
748 If @code{fread} encounters end of file in the middle of an object, it
749 returns the number of complete objects read, and discards the partial
750 object.  Therefore, the stream remains at the actual end of the file.
751 @end deftypefun
752
753 @comment stdio.h
754 @comment ANSI
755 @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
756 This function writes up to @var{count} objects of size @var{size} from
757 the array @var{data}, to the stream @var{stream}.  The return value is
758 normally @var{count}, if the call succeeds.  Any other value indicates
759 some sort of error, such as running out of space.
760 @end deftypefun
761
762 @node Formatted Output
763 @section Formatted Output
764
765 @cindex format string, for @code{printf}
766 @cindex template, for @code{printf}
767 @cindex formatted output to a stream
768 @cindex writing to a stream, formatted
769 The functions described in this section (@code{printf} and related
770 functions) provide a convenient way to perform formatted output.  You
771 call @code{printf} with a @dfn{format string} or @dfn{template string}
772 that specifies how to format the values of the remaining arguments.
773
774 Unless your program is a filter that specifically performs line- or
775 character-oriented processing, using @code{printf} or one of the other
776 related functions described in this section is usually the easiest and
777 most concise way to perform output.  These functions are especially
778 useful for printing error messages, tables of data, and the like.
779
780 @menu
781 * Formatted Output Basics::     Some examples to get you started.
782 * Output Conversion Syntax::    General syntax of conversion
783                                  specifications.
784 * Table of Output Conversions:: Summary of output conversions and
785                                  what they do.
786 * Integer Conversions::         Details about formatting of integers.
787 * Floating-Point Conversions::  Details about formatting of
788                                  floating-point numbers.
789 * Other Output Conversions::    Details about formatting of strings,
790                                  characters, pointers, and the like.
791 * Formatted Output Functions::  Descriptions of the actual functions.
792 * Dynamic Output::              Functions that allocate memory for the output.
793 * Variable Arguments Output::   @code{vprintf} and friends.
794 * Parsing a Template String::   What kinds of args does a given template
795                                  call for?
796 * Example of Parsing::          Sample program using @code{parse_printf_format}.
797 @end menu
798
799 @node Formatted Output Basics
800 @subsection Formatted Output Basics
801
802 The @code{printf} function can be used to print any number of arguments.
803 The template string argument you supply in a call provides
804 information not only about the number of additional arguments, but also
805 about their types and what style should be used for printing them.
806
807 Ordinary characters in the template string are simply written to the
808 output stream as-is, while @dfn{conversion specifications} introduced by
809 a @samp{%} character in the template cause subsequent arguments to be
810 formatted and written to the output stream.  For example,
811 @cindex conversion specifications (@code{printf})
812
813 @smallexample
814 int pct = 37;
815 char filename[] = "foo.txt";
816 printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
817         filename, pct);
818 @end smallexample
819
820 @noindent
821 produces output like
822
823 @smallexample
824 Processing of `foo.txt' is 37% finished.
825 Please be patient.
826 @end smallexample
827
828 This example shows the use of the @samp{%d} conversion to specify that
829 an @code{int} argument should be printed in decimal notation, the
830 @samp{%s} conversion to specify printing of a string argument, and
831 the @samp{%%} conversion to print a literal @samp{%} character.
832
833 There are also conversions for printing an integer argument as an
834 unsigned value in octal, decimal, or hexadecimal radix (@samp{%o},
835 @samp{%u}, or @samp{%x}, respectively); or as a character value
836 (@samp{%c}).
837
838 Floating-point numbers can be printed in normal, fixed-point notation
839 using the @samp{%f} conversion or in exponential notation using the
840 @samp{%e} conversion.  The @samp{%g} conversion uses either @samp{%e}
841 or @samp{%f} format, depending on what is more appropriate for the
842 magnitude of the particular number.
843
844 You can control formatting more precisely by writing @dfn{modifiers}
845 between the @samp{%} and the character that indicates which conversion
846 to apply.  These slightly alter the ordinary behavior of the conversion.
847 For example, most conversion specifications permit you to specify a
848 minimum field width and a flag indicating whether you want the result
849 left- or right-justified within the field.
850
851 The specific flags and modifiers that are permitted and their
852 interpretation vary depending on the particular conversion.  They're all
853 described in more detail in the following sections.  Don't worry if this
854 all seems excessively complicated at first; you can almost always get
855 reasonable free-format output without using any of the modifiers at all.
856 The modifiers are mostly used to make the output look ``prettier'' in
857 tables.
858
859 @node Output Conversion Syntax
860 @subsection Output Conversion Syntax
861
862 This section provides details about the precise syntax of conversion
863 specifications that can appear in a @code{printf} template
864 string.
865
866 Characters in the template string that are not part of a
867 conversion specification are printed as-is to the output stream.
868 Multibyte character sequences (@pxref{Extended Characters}) are permitted in
869 a template string.
870
871 The conversion specifications in a @code{printf} template string have
872 the general form:
873
874 @example
875 % @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion}
876 @end example
877
878 For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-}
879 is a flag, @samp{10} specifies the field width, the precision is
880 @samp{8}, the letter @samp{l} is a type modifier, and @samp{d} specifies
881 the conversion style.  (This particular type specifier says to
882 print a @code{long int} argument in decimal notation, with a minimum of
883 8 digits left-justified in a field at least 10 characters wide.)
884
885 In more detail, output conversion specifications consist of an
886 initial @samp{%} character followed in sequence by:
887
888 @itemize @bullet
889 @item
890 Zero or more @dfn{flag characters} that modify the normal behavior of
891 the conversion specification.
892 @cindex flag character (@code{printf})
893
894 @item
895 An optional decimal integer specifying the @dfn{minimum field width}.
896 If the normal conversion produces fewer characters than this, the field
897 is padded with spaces to the specified width.  This is a @emph{minimum}
898 value; if the normal conversion produces more characters than this, the
899 field is @emph{not} truncated.  Normally, the output is right-justified
900 within the field.
901 @cindex minimum field width (@code{printf})
902
903 You can also specify a field width of @samp{*}.  This means that the
904 next argument in the argument list (before the actual value to be
905 printed) is used as the field width.  The value must be an @code{int}.
906 If the value is negative, this means to set the @samp{-} flag (see
907 below) and to use the absolute value as the field width.
908
909 @item
910 An optional @dfn{precision} to specify the number of digits to be
911 written for the numeric conversions.  If the precision is specified, it
912 consists of a period (@samp{.}) followed optionally by a decimal integer
913 (which defaults to zero if omitted).
914 @cindex precision (@code{printf})
915
916 You can also specify a precision of @samp{*}.  This means that the next
917 argument in the argument list (before the actual value to be printed) is
918 used as the precision.  The value must be an @code{int}, and is ignored
919 if it is negative.  If you specify @samp{*} for both the field width and
920 precision, the field width argument precedes the precision argument.
921 Other C library versions may not recognize this syntax.
922
923 @item
924 An optional @dfn{type modifier character}, which is used to specify the
925 data type of the corresponding argument if it differs from the default
926 type.  (For example, the integer conversions assume a type of @code{int},
927 but you can specify @samp{h}, @samp{l}, or @samp{L} for other integer
928 types.)
929 @cindex type modifier character (@code{printf})
930
931 @item
932 A character that specifies the conversion to be applied.
933 @end itemize
934
935 The exact options that are permitted and how they are interpreted vary
936 between the different conversion specifiers.  See the descriptions of the
937 individual conversions for information about the particular options that
938 they use.
939
940 With the @samp{-Wformat} option, the GNU C compiler checks calls to
941 @code{printf} and related functions.  It examines the format string and
942 verifies that the correct number and types of arguments are supplied.
943 There is also a GNU C syntax to tell the compiler that a function you
944 write uses a @code{printf}-style format string.
945 @xref{Function Attributes, , Declaring Attributes of Functions,
946 gcc.info, Using GNU CC}, for more information.
947
948 @node Table of Output Conversions
949 @subsection Table of Output Conversions
950 @cindex output conversions, for @code{printf}
951
952 Here is a table summarizing what all the different conversions do:
953
954 @table @asis
955 @item @samp{%d}, @samp{%i}
956 Print an integer as a signed decimal number.  @xref{Integer
957 Conversions}, for details.  @samp{%d} and @samp{%i} are synonymous for
958 output, but are different when used with @code{scanf} for input
959 (@pxref{Table of Input Conversions}).
960
961 @item @samp{%o}
962 Print an integer as an unsigned octal number.  @xref{Integer
963 Conversions}, for details.
964
965 @item @samp{%u}
966 Print an integer as an unsigned decimal number.  @xref{Integer
967 Conversions}, for details.
968
969 @item @samp{%x}, @samp{%X}
970 Print an integer as an unsigned hexadecimal number.  @samp{%x} uses
971 lower-case letters and @samp{%X} uses upper-case.  @xref{Integer
972 Conversions}, for details.
973
974 @item @samp{%f}
975 Print a floating-point number in normal (fixed-point) notation.
976 @xref{Floating-Point Conversions}, for details.
977
978 @item @samp{%e}, @samp{%E}
979 Print a floating-point number in exponential notation.  @samp{%e} uses
980 lower-case letters and @samp{%E} uses upper-case.  @xref{Floating-Point
981 Conversions}, for details.
982
983 @item @samp{%g}, @samp{%G}
984 Print a floating-point number in either normal or exponential notation,
985 whichever is more appropriate for its magnitude.  @samp{%g} uses
986 lower-case letters and @samp{%G} uses upper-case.  @xref{Floating-Point
987 Conversions}, for details.
988
989 @item @samp{%c}
990 Print a single character.  @xref{Other Output Conversions}.
991
992 @item @samp{%s}
993 Print a string.  @xref{Other Output Conversions}.
994
995 @item @samp{%p}
996 Print the value of a pointer.  @xref{Other Output Conversions}.
997
998 @item @samp{%n}
999 Get the number of characters printed so far.  @xref{Other Output Conversions}.
1000 Note that this conversion specification never produces any output.
1001
1002 @item @samp{%m}
1003 Print the string corresponding to the value of @code{errno}.
1004 (This is a GNU extension.)
1005 @xref{Other Output Conversions}.
1006
1007 @item @samp{%%}
1008 Print a literal @samp{%} character.  @xref{Other Output Conversions}.
1009 @end table
1010
1011 If the syntax of a conversion specification is invalid, unpredictable
1012 things will happen, so don't do this.  If there aren't enough function
1013 arguments provided to supply values for all the conversion
1014 specifications in the template string, or if the arguments are not of
1015 the correct types, the results are unpredictable.  If you supply more
1016 arguments than conversion specifications, the extra argument values are
1017 simply ignored; this is sometimes useful.
1018
1019 @node Integer Conversions
1020 @subsection Integer Conversions
1021
1022 This section describes the options for the @samp{%d}, @samp{%i},
1023 @samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
1024 specifications.  These conversions print integers in various formats.
1025
1026 The @samp{%d} and @samp{%i} conversion specifications both print an
1027 @code{int} argument as a signed decimal number; while @samp{%o},
1028 @samp{%u}, and @samp{%x} print the argument as an unsigned octal,
1029 decimal, or hexadecimal number (respectively).  The @samp{%X} conversion
1030 specification is just like @samp{%x} except that it uses the characters
1031 @samp{ABCDEF} as digits instead of @samp{abcdef}.
1032
1033 The following flags are meaningful:
1034
1035 @table @asis
1036 @item @samp{-}
1037 Left-justify the result in the field (instead of the normal
1038 right-justification).
1039
1040 @item @samp{+}
1041 For the signed @samp{%d} and @samp{%i} conversions, print a
1042 plus sign if the value is positive.
1043
1044 @item @samp{ }
1045 For the signed @samp{%d} and @samp{%i} conversions, if the result
1046 doesn't start with a plus or minus sign, prefix it with a space
1047 character instead.  Since the @samp{+} flag ensures that the result
1048 includes a sign, this flag is ignored if you supply both of them.
1049
1050 @item @samp{#}
1051 For the @samp{%o} conversion, this forces the leading digit to be
1052 @samp{0}, as if by increasing the precision.  For @samp{%x} or
1053 @samp{%X}, this prefixes a leading @samp{0x} or @samp{0X} (respectively)
1054 to the result.  This doesn't do anything useful for the @samp{%d},
1055 @samp{%i}, or @samp{%u} conversions.  Using this flag produces output
1056 which can be parsed by the @code{strtoul} function (@pxref{Parsing of
1057 Integers}) and @code{scanf} with the @samp{%i} conversion
1058 (@pxref{Numeric Input Conversions}).
1059
1060 @item @samp{'}
1061 Separate the digits into groups as specified by the locale specified for
1062 the @code{LC_NUMERIC} category; @pxref{General Numeric}.  This flag is a
1063 GNU extension.
1064
1065 @item @samp{0}
1066 Pad the field with zeros instead of spaces.  The zeros are placed after
1067 any indication of sign or base.  This flag is ignored if the @samp{-}
1068 flag is also specified, or if a precision is specified.
1069 @end table
1070
1071 If a precision is supplied, it specifies the minimum number of digits to
1072 appear; leading zeros are produced if necessary.  If you don't specify a
1073 precision, the number is printed with as many digits as it needs.  If
1074 you convert a value of zero with an explicit precision of zero, then no
1075 characters at all are produced.
1076
1077 Without a type modifier, the corresponding argument is treated as an
1078 @code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
1079 @code{unsigned int} (for the unsigned conversions @samp{%o}, @samp{%u},
1080 @samp{%x}, and @samp{%X}).  Recall that since @code{printf} and friends
1081 are variadic, any @code{char} and @code{short} arguments are
1082 automatically converted to @code{int} by the default argument
1083 promotions.  For arguments of other integer types, you can use these
1084 modifiers:
1085
1086 @table @samp
1087 @item h
1088 Specifies that the argument is a @code{short int} or @code{unsigned
1089 short int}, as appropriate.  A @code{short} argument is converted to an
1090 @code{int} or @code{unsigned int} by the default argument promotions
1091 anyway, but the @samp{h} modifier says to convert it back to a
1092 @code{short} again.
1093
1094 @item l
1095 Specifies that the argument is a @code{long int} or @code{unsigned long
1096 int}, as appropriate.  Two @samp{l} characters is like the @samp{L}
1097 modifier, below.
1098
1099 @item L
1100 @itemx ll
1101 @itemx q
1102 Specifies that the argument is a @code{long long int}.  (This type is
1103 an extension supported by the GNU C compiler.  On systems that don't
1104 support extra-long integers, this is the same as @code{long int}.)
1105
1106 The @samp{q} modifier is another name for the same thing, which comes
1107 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
1108 @code{int}.
1109
1110 @item Z
1111 Specifies that the argument is a @code{size_t}.  This is a GNU extension.
1112 @end table
1113
1114 Here is an example.  Using the template string:
1115
1116 @smallexample
1117 "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
1118 @end smallexample
1119
1120 @noindent
1121 to print numbers using the different options for the @samp{%d}
1122 conversion gives results like:
1123
1124 @smallexample
1125 |    0|0    |   +0|+0   |    0|00000|     |   00|0|
1126 |    1|1    |   +1|+1   |    1|00001|    1|   01|1|
1127 |   -1|-1   |   -1|-1   |   -1|-0001|   -1|  -01|-1|
1128 |100000|100000|+100000| 100000|100000|100000|100000|100000|
1129 @end smallexample
1130
1131 In particular, notice what happens in the last case where the number
1132 is too large to fit in the minimum field width specified.
1133
1134 Here are some more examples showing how unsigned integers print under
1135 various format options, using the template string:
1136
1137 @smallexample
1138 "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
1139 @end smallexample
1140
1141 @smallexample
1142 |    0|    0|    0|    0|    0|  0x0|  0X0|0x00000000|
1143 |    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
1144 |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
1145 @end smallexample
1146
1147
1148 @node Floating-Point Conversions
1149 @subsection Floating-Point Conversions
1150
1151 This section discusses the conversion specifications for floating-point
1152 numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G}
1153 conversions.
1154
1155 The @samp{%f} conversion prints its argument in fixed-point notation,
1156 producing output of the form
1157 @w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
1158 where the number of digits following the decimal point is controlled
1159 by the precision you specify.
1160
1161 The @samp{%e} conversion prints its argument in exponential notation,
1162 producing output of the form
1163 @w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}.
1164 Again, the number of digits following the decimal point is controlled by
1165 the precision.  The exponent always contains at least two digits.  The
1166 @samp{%E} conversion is similar but the exponent is marked with the letter
1167 @samp{E} instead of @samp{e}.
1168
1169 The @samp{%g} and @samp{%G} conversions print the argument in the style
1170 of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
1171 than -4 or greater than or equal to the precision; otherwise they use the
1172 @samp{%f} style.  Trailing zeros are removed from the fractional portion
1173 of the result and a decimal-point character appears only if it is
1174 followed by a digit.
1175
1176 The following flags can be used to modify the behavior:
1177
1178 @comment We use @asis instead of @samp so we can have ` ' as an item.
1179 @table @asis
1180 @item @samp{-}
1181 Left-justify the result in the field.  Normally the result is
1182 right-justified.
1183
1184 @item @samp{+}
1185 Always include a plus or minus sign in the result.
1186
1187 @item @samp{ }
1188 If the result doesn't start with a plus or minus sign, prefix it with a
1189 space instead.  Since the @samp{+} flag ensures that the result includes
1190 a sign, this flag is ignored if you supply both of them.
1191
1192 @item @samp{#}
1193 Specifies that the result should always include a decimal point, even
1194 if no digits follow it.  For the @samp{%g} and @samp{%G} conversions,
1195 this also forces trailing zeros after the decimal point to be left
1196 in place where they would otherwise be removed.
1197
1198 @item @samp{'}
1199 Separate the digits of the integer part of the result into groups as
1200 specified by the locale specified for the @code{LC_NUMERIC} category;
1201 @pxref{General Numeric}.  This flag is a GNU extension.
1202
1203 @item @samp{0}
1204 Pad the field with zeros instead of spaces; the zeros are placed
1205 after any sign.  This flag is ignored if the @samp{-} flag is also
1206 specified.
1207 @end table
1208
1209 The precision specifies how many digits follow the decimal-point
1210 character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions.  For
1211 these conversions, the default precision is @code{6}.  If the precision
1212 is explicitly @code{0}, this suppresses the decimal point character
1213 entirely.  For the @samp{%g} and @samp{%G} conversions, the precision
1214 specifies how many significant digits to print.  Significant digits are
1215 the first digit before the decimal point, and all the digits after it.
1216 If the precision @code{0} or not specified for @samp{%g} or @samp{%G},
1217 it is treated like a value of @code{1}.  If the value being printed
1218 cannot be expressed accurately in the specified number of digits, the
1219 value is rounded to the nearest number that fits.
1220
1221 Without a type modifier, the floating-point conversions use an argument
1222 of type @code{double}.  (By the default argument promotions, any
1223 @code{float} arguments are automatically converted to @code{double}.)
1224 The following type modifier is supported:
1225
1226 @table @samp
1227 @item L
1228 An uppercase @samp{L} specifies that the argument is a @code{long
1229 double}.
1230 @end table
1231
1232 Here are some examples showing how numbers print using the various
1233 floating-point conversions.  All of the numbers were printed using
1234 this template string:
1235
1236 @smallexample
1237 "|%12.4f|%12.4e|%12.4g|\n"
1238 @end smallexample
1239
1240 Here is the output:
1241
1242 @smallexample
1243 |      0.0000|  0.0000e+00|           0|
1244 |      1.0000|  1.0000e+00|           1|
1245 |     -1.0000| -1.0000e+00|          -1|
1246 |    100.0000|  1.0000e+02|         100|
1247 |   1000.0000|  1.0000e+03|        1000|
1248 |  10000.0000|  1.0000e+04|       1e+04|
1249 |  12345.0000|  1.2345e+04|   1.234e+04|
1250 | 100000.0000|  1.0000e+05|       1e+05|
1251 | 123456.0000|  1.2346e+05|   1.234e+05|
1252 @end smallexample
1253
1254 Notice how the @samp{%g} conversion drops trailing zeros.
1255
1256 @node Other Output Conversions
1257 @subsection Other Output Conversions
1258
1259 This section describes miscellaneous conversions for @code{printf}.
1260
1261 The @samp{%c} conversion prints a single character.  The @code{int}
1262 argument is first converted to an @code{unsigned char}.  The @samp{-}
1263 flag can be used to specify left-justification in the field, but no
1264 other flags are defined, and no precision or type modifier can be given.
1265 For example:
1266
1267 @smallexample
1268 printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
1269 @end smallexample
1270
1271 @noindent
1272 prints @samp{hello}.
1273
1274 The @samp{%s} conversion prints a string.  The corresponding argument
1275 must be of type @code{char *} (or @code{const char *}).  A precision can
1276 be specified to indicate the maximum number of characters to write;
1277 otherwise characters in the string up to but not including the
1278 terminating null character are written to the output stream.  The
1279 @samp{-} flag can be used to specify left-justification in the field,
1280 but no other flags or type modifiers are defined for this conversion.
1281 For example:
1282
1283 @smallexample
1284 printf ("%3s%-6s", "no", "where");
1285 @end smallexample
1286
1287 @noindent
1288 prints @samp{ nowhere }.
1289
1290 If you accidentally pass a null pointer as the argument for a @samp{%s}
1291 conversion, the GNU library prints it as @samp{(null)}.  We think this
1292 is more useful than crashing.  But it's not good practice to pass a null
1293 argument intentionally.
1294
1295 The @samp{%m} conversion prints the string corresponding to the error
1296 code in @code{errno}.  @xref{Error Messages}.  Thus:
1297
1298 @smallexample
1299 fprintf (stderr, "can't open `%s': %m\n", filename);
1300 @end smallexample
1301
1302 @noindent
1303 is equivalent to:
1304
1305 @smallexample
1306 fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
1307 @end smallexample
1308
1309 @noindent
1310 The @samp{%m} conversion is a GNU C library extension.
1311
1312 The @samp{%p} conversion prints a pointer value.  The corresponding
1313 argument must be of type @code{void *}.  In practice, you can use any
1314 type of pointer.
1315
1316 In the GNU system, non-null pointers are printed as unsigned integers,
1317 as if a @samp{%#x} conversion were used.  Null pointers print as
1318 @samp{(nil)}.  (Pointers might print differently in other systems.)
1319
1320 For example:
1321
1322 @smallexample
1323 printf ("%p", "testing");
1324 @end smallexample
1325
1326 @noindent
1327 prints @samp{0x} followed by a hexadecimal number---the address of the
1328 string constant @code{"testing"}.  It does not print the word
1329 @samp{testing}.
1330
1331 You can supply the @samp{-} flag with the @samp{%p} conversion to
1332 specify left-justification, but no other flags, precision, or type
1333 modifiers are defined.
1334
1335 The @samp{%n} conversion is unlike any of the other output conversions.
1336 It uses an argument which must be a pointer to an @code{int}, but
1337 instead of printing anything it stores the number of characters printed
1338 so far by this call at that location.  The @samp{h} and @samp{l} type
1339 modifiers are permitted to specify that the argument is of type
1340 @code{short int *} or @code{long int *} instead of @code{int *}, but no
1341 flags, field width, or precision are permitted.
1342
1343 For example,
1344
1345 @smallexample
1346 int nchar;
1347 printf ("%d %s%n\n", 3, "bears", &nchar);
1348 @end smallexample
1349
1350 @noindent
1351 prints:
1352
1353 @smallexample
1354 3 bears
1355 @end smallexample
1356
1357 @noindent
1358 and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven
1359 characters.
1360
1361
1362 The @samp{%%} conversion prints a literal @samp{%} character.  This
1363 conversion doesn't use an argument, and no flags, field width,
1364 precision, or type modifiers are permitted.
1365
1366
1367 @node Formatted Output Functions
1368 @subsection Formatted Output Functions
1369
1370 This section describes how to call @code{printf} and related functions.
1371 Prototypes for these functions are in the header file @file{stdio.h}.
1372 Because these functions take a variable number of arguments, you
1373 @emph{must} declare prototypes for them before using them.  Of course,
1374 the easiest way to make sure you have all the right prototypes is to
1375 just include @file{stdio.h}.
1376 @pindex stdio.h
1377
1378 @comment stdio.h
1379 @comment ANSI
1380 @deftypefun int printf (const char *@var{template}, @dots{})
1381 The @code{printf} function prints the optional arguments under the
1382 control of the template string @var{template} to the stream
1383 @code{stdout}.  It returns the number of characters printed, or a
1384 negative value if there was an output error.
1385 @end deftypefun
1386
1387 @comment stdio.h
1388 @comment ANSI
1389 @deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
1390 This function is just like @code{printf}, except that the output is
1391 written to the stream @var{stream} instead of @code{stdout}.
1392 @end deftypefun
1393
1394 @comment stdio.h
1395 @comment ANSI
1396 @deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
1397 This is like @code{printf}, except that the output is stored in the character
1398 array @var{s} instead of written to a stream.  A null character is written
1399 to mark the end of the string.
1400
1401 The @code{sprintf} function returns the number of characters stored in
1402 the array @var{s}, not including the terminating null character.
1403
1404 The behavior of this function is undefined if copying takes place
1405 between objects that overlap---for example, if @var{s} is also given
1406 as an argument to be printed under control of the @samp{%s} conversion.
1407 @xref{Copying and Concatenation}.
1408
1409 @strong{Warning:} The @code{sprintf} function can be @strong{dangerous}
1410 because it can potentially output more characters than can fit in the
1411 allocation size of the string @var{s}.  Remember that the field width
1412 given in a conversion specification is only a @emph{minimum} value.
1413
1414 To avoid this problem, you can use @code{snprintf} or @code{asprintf},
1415 described below.
1416 @end deftypefun
1417
1418 @comment stdio.h
1419 @comment GNU
1420 @deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{})
1421 The @code{snprintf} function is similar to @code{sprintf}, except that
1422 the @var{size} argument specifies the maximum number of characters to
1423 produce.  The trailing null character is counted towards this limit, so
1424 you should allocate at least @var{size} characters for the string @var{s}.
1425
1426 The return value is the number of characters stored, not including the
1427 terminating null.  If this value equals @code{@var{size} - 1}, then
1428 there was not enough space in @var{s} for all the output.  You should
1429 try again with a bigger output string.  Here is an example of doing
1430 this:
1431
1432 @smallexample
1433 @group
1434 /* @r{Construct a message describing the value of a variable}
1435    @r{whose name is @var{name} and whose value is @var{value}.} */
1436 char *
1437 make_message (char *name, char *value)
1438 @{
1439   /* @r{Guess we need no more than 100 chars of space.} */
1440   int size = 100;
1441   char *buffer = (char *) xmalloc (size);
1442 @end group
1443 @group
1444   while (1)
1445     @{
1446       /* @r{Try to print in the allocated space.} */
1447       int nchars = snprintf (buffer, size,
1448                              "value of %s is %s",
1449                              name, value);
1450       /* @r{If that worked, return the string.} */
1451       if (nchars < size)
1452         return buffer;
1453       /* @r{Else try again with twice as much space.} */
1454       size *= 2;
1455       buffer = (char *) xrealloc (size, buffer);
1456     @}
1457 @}
1458 @end group
1459 @end smallexample
1460
1461 In practice, it is often easier just to use @code{asprintf}, below.
1462 @end deftypefun
1463
1464 @node Dynamic Output
1465 @subsection Dynamically Allocating Formatted Output
1466
1467 The functions in this section do formatted output and place the results
1468 in dynamically allocated memory.
1469
1470 @comment stdio.h
1471 @comment GNU
1472 @deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
1473 This function is similar to @code{sprintf}, except that it dynamically
1474 allocates a string (as with @code{malloc}; @pxref{Unconstrained
1475 Allocation}) to hold the output, instead of putting the output in a
1476 buffer you allocate in advance.  The @var{ptr} argument should be the
1477 address of a @code{char *} object, and @code{asprintf} stores a pointer
1478 to the newly allocated string at that location.
1479
1480 Here is how to use @code{asprintf} to get the same result as the
1481 @code{snprintf} example, but more easily:
1482
1483 @smallexample
1484 /* @r{Construct a message describing the value of a variable}
1485    @r{whose name is @var{name} and whose value is @var{value}.} */
1486 char *
1487 make_message (char *name, char *value)
1488 @{
1489   char *result;
1490   asprintf (&result, "value of %s is %s", name, value);
1491   return result;
1492 @}
1493 @end smallexample
1494 @end deftypefun
1495
1496 @comment stdio.h
1497 @comment GNU
1498 @deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
1499 This function is similar to @code{asprintf}, except that it uses the
1500 obstack @var{obstack} to allocate the space.  @xref{Obstacks}.
1501
1502 The characters are written onto the end of the current object.
1503 To get at them, you must finish the object with @code{obstack_finish}
1504 (@pxref{Growing Objects}).@refill
1505 @end deftypefun
1506
1507 @node Variable Arguments Output
1508 @subsection Variable Arguments Output Functions
1509
1510 The functions @code{vprintf} and friends are provided so that you can
1511 define your own variadic @code{printf}-like functions that make use of
1512 the same internals as the built-in formatted output functions.
1513
1514 The most natural way to define such functions would be to use a language
1515 construct to say, ``Call @code{printf} and pass this template plus all
1516 of my arguments after the first five.''  But there is no way to do this
1517 in C, and it would be hard to provide a way, since at the C language
1518 level there is no way to tell how many arguments your function received.
1519
1520 Since that method is impossible, we provide alternative functions, the
1521 @code{vprintf} series, which lets you pass a @code{va_list} to describe
1522 ``all of my arguments after the first five.''
1523
1524 When it is sufficient to define a macro rather than a real function,
1525 the GNU C compiler provides a way to do this much more easily with macros.
1526 For example:
1527
1528 @smallexample
1529 #define myprintf(a, b, c, d, e, rest...) printf (mytemplate , ## rest...)
1530 @end smallexample
1531
1532 @noindent
1533 @xref{Macro Varargs, , Macros with Variable Numbers of Arguments,
1534 gcc.info, Using GNU CC}, for details.  But this is limited to macros,
1535 and does not apply to real functions at all.
1536
1537 Before calling @code{vprintf} or the other functions listed in this
1538 section, you @emph{must} call @code{va_start} (@pxref{Variadic
1539 Functions}) to initialize a pointer to the variable arguments.  Then you
1540 can call @code{va_arg} to fetch the arguments that you want to handle
1541 yourself.  This advances the pointer past those arguments.
1542
1543 Once your @code{va_list} pointer is pointing at the argument of your
1544 choice, you are ready to call @code{vprintf}.  That argument and all
1545 subsequent arguments that were passed to your function are used by
1546 @code{vprintf} along with the template that you specified separately.
1547
1548 In some other systems, the @code{va_list} pointer may become invalid
1549 after the call to @code{vprintf}, so you must not use @code{va_arg}
1550 after you call @code{vprintf}.  Instead, you should call @code{va_end}
1551 to retire the pointer from service.  However, you can safely call
1552 @code{va_start} on another pointer variable and begin fetching the
1553 arguments again through that pointer.  Calling @code{vprintf} does not
1554 destroy the argument list of your function, merely the particular
1555 pointer that you passed to it.
1556
1557 GNU C does not have such restrictions.  You can safely continue to fetch
1558 arguments from a @code{va_list} pointer after passing it to
1559 @code{vprintf}, and @code{va_end} is a no-op.  (Note, however, that
1560 subsequent @code{va_arg} calls will fetch the same arguments which
1561 @code{vprintf} previously used.)
1562
1563 Prototypes for these functions are declared in @file{stdio.h}.
1564 @pindex stdio.h
1565
1566 @comment stdio.h
1567 @comment ANSI
1568 @deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
1569 This function is similar to @code{printf} except that, instead of taking
1570 a variable number of arguments directly, it takes an argument list
1571 pointer @var{ap}.
1572 @end deftypefun
1573
1574 @comment stdio.h
1575 @comment ANSI
1576 @deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
1577 This is the equivalent of @code{fprintf} with the variable argument list
1578 specified directly as for @code{vprintf}.
1579 @end deftypefun
1580
1581 @comment stdio.h
1582 @comment ANSI
1583 @deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
1584 This is the equivalent of @code{sprintf} with the variable argument list
1585 specified directly as for @code{vprintf}.
1586 @end deftypefun
1587
1588 @comment stdio.h
1589 @comment GNU
1590 @deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
1591 This is the equivalent of @code{snprintf} with the variable argument list
1592 specified directly as for @code{vprintf}.
1593 @end deftypefun
1594
1595 @comment stdio.h
1596 @comment GNU
1597 @deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
1598 The @code{vasprintf} function is the equivalent of @code{asprintf} with the
1599 variable argument list specified directly as for @code{vprintf}.
1600 @end deftypefun
1601
1602 @comment stdio.h
1603 @comment GNU
1604 @deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
1605 The @code{obstack_vprintf} function is the equivalent of
1606 @code{obstack_printf} with the variable argument list specified directly
1607 as for @code{vprintf}.@refill
1608 @end deftypefun
1609
1610 Here's an example showing how you might use @code{vfprintf}.  This is a
1611 function that prints error messages to the stream @code{stderr}, along
1612 with a prefix indicating the name of the program
1613 (@pxref{Error Messages}, for a description of
1614 @code{program_invocation_short_name}).
1615
1616 @smallexample
1617 @group
1618 #include <stdio.h>
1619 #include <stdarg.h>
1620
1621 void
1622 eprintf (const char *template, ...)
1623 @{
1624   va_list ap;
1625   extern char *program_invocation_short_name;
1626
1627   fprintf (stderr, "%s: ", program_invocation_short_name);
1628   va_start (ap, count);
1629   vfprintf (stderr, template, ap);
1630   va_end (ap);
1631 @}
1632 @end group
1633 @end smallexample
1634
1635 @noindent
1636 You could call @code{eprintf} like this:
1637
1638 @smallexample
1639 eprintf ("file `%s' does not exist\n", filename);
1640 @end smallexample
1641
1642 In GNU C, there is a special construct you can use to let the compiler
1643 know that a function uses a @code{printf}-style format string.  Then it
1644 can check the number and types of arguments in each call to the
1645 function, and warn you when they do not match the format string.
1646 For example, take this declaration of @code{eprintf}:
1647
1648 @smallexample
1649 void eprintf (const char *template, ...)
1650         __attribute__ ((format (printf, 1, 2)));
1651 @end smallexample
1652
1653 @noindent
1654 This tells the compiler that @code{eprintf} uses a format string like
1655 @code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input});
1656 the format string appears as the first argument;
1657 and the arguments to satisfy the format begin with the second.
1658 @xref{Function Attributes, , Declaring Attributes of Functions,
1659 gcc.info, Using GNU CC}, for more information.
1660
1661 @node Parsing a Template String
1662 @subsection Parsing a Template String
1663 @cindex parsing a template string
1664
1665 You can use the function @code{parse_printf_format} to obtain
1666 information about the number and types of arguments that are expected by
1667 a given template string.  This function permits interpreters that
1668 provide interfaces to @code{printf} to avoid passing along invalid
1669 arguments from the user's program, which could cause a crash.
1670
1671 All the symbols described in this section are declared in the header
1672 file @file{printf.h}.
1673
1674 @comment printf.h
1675 @comment GNU
1676 @deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
1677 This function returns information about the number and types of
1678 arguments expected by the @code{printf} template string @var{template}.
1679 The information is stored in the array @var{argtypes}; each element of
1680 this array describes one argument.  This information is encoded using
1681 the various @samp{PA_} macros, listed below.
1682
1683 The @var{n} argument specifies the number of elements in the array
1684 @var{argtypes}.  This is the most elements that
1685 @code{parse_printf_format} will try to write.
1686
1687 @code{parse_printf_format} returns the total number of arguments required
1688 by @var{template}.  If this number is greater than @var{n}, then the
1689 information returned describes only the first @var{n} arguments.  If you
1690 want information about more than that many arguments, allocate a bigger
1691 array and call @code{parse_printf_format} again.
1692 @end deftypefun
1693
1694 The argument types are encoded as a combination of a basic type and
1695 modifier flag bits.
1696
1697 @comment printf.h
1698 @comment GNU
1699 @deftypevr Macro int PA_FLAG_MASK
1700 This macro is a bitmask for the type modifier flag bits.  You can write
1701 the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the
1702 flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to
1703 extract just the basic type code.
1704 @end deftypevr
1705
1706 Here are symbolic constants that represent the basic types; they stand
1707 for integer values.
1708
1709 @table @code
1710 @comment printf.h
1711 @comment GNU
1712 @item PA_INT
1713 @vindex PA_INT
1714 This specifies that the base type is @code{int}.
1715
1716 @comment printf.h
1717 @comment GNU
1718 @item PA_CHAR
1719 @vindex PA_CHAR
1720 This specifies that the base type is @code{int}, cast to @code{char}.
1721
1722 @comment printf.h
1723 @comment GNU
1724 @item PA_STRING
1725 @vindex PA_STRING
1726 This specifies that the base type is @code{char *}, a null-terminated string.
1727
1728 @comment printf.h
1729 @comment GNU
1730 @item PA_POINTER
1731 @vindex PA_POINTER
1732 This specifies that the base type is @code{void *}, an arbitrary pointer.
1733
1734 @comment printf.h
1735 @comment GNU
1736 @item PA_FLOAT
1737 @vindex PA_FLOAT
1738 This specifies that the base type is @code{float}.
1739
1740 @comment printf.h
1741 @comment GNU
1742 @item PA_DOUBLE
1743 @vindex PA_DOUBLE
1744 This specifies that the base type is @code{double}.
1745
1746 @comment printf.h
1747 @comment GNU
1748 @item PA_LAST
1749 @vindex PA_LAST
1750 You can define additional base types for your own programs as offsets
1751 from @code{PA_LAST}.  For example, if you have data types @samp{foo}
1752 and @samp{bar} with their own specialized @code{printf} conversions,
1753 you could define encodings for these types as:
1754
1755 @smallexample
1756 #define PA_FOO  PA_LAST
1757 #define PA_BAR  (PA_LAST + 1)
1758 @end smallexample
1759 @end table
1760
1761 Here are the flag bits that modify a basic type.  They are combined with
1762 the code for the basic type using inclusive-or.
1763
1764 @table @code
1765 @comment printf.h
1766 @comment GNU
1767 @item PA_FLAG_PTR
1768 @vindex PA_FLAG_PTR
1769 If this bit is set, it indicates that the encoded type is a pointer to
1770 the base type, rather than an immediate value.
1771 For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.
1772
1773 @comment printf.h
1774 @comment GNU
1775 @item PA_FLAG_SHORT
1776 @vindex PA_FLAG_SHORT
1777 If this bit is set, it indicates that the base type is modified with
1778 @code{short}.  (This corresponds to the @samp{h} type modifier.)
1779
1780 @comment printf.h
1781 @comment GNU
1782 @item PA_FLAG_LONG
1783 @vindex PA_FLAG_LONG
1784 If this bit is set, it indicates that the base type is modified with
1785 @code{long}.  (This corresponds to the @samp{l} type modifier.)
1786
1787 @comment printf.h
1788 @comment GNU
1789 @item PA_FLAG_LONG_LONG
1790 @vindex PA_FLAG_LONG_LONG
1791 If this bit is set, it indicates that the base type is modified with
1792 @code{long long}.  (This corresponds to the @samp{L} type modifier.)
1793
1794 @comment printf.h
1795 @comment GNU
1796 @item PA_FLAG_LONG_DOUBLE
1797 @vindex PA_FLAG_LONG_DOUBLE
1798 This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with
1799 a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
1800 @end table
1801
1802 @ifinfo
1803 For an example of using these facilitles, see @ref{Example of Parsing}.
1804 @end ifinfo
1805
1806 @node Example of Parsing
1807 @subsection Example of Parsing a Template String
1808
1809 Here is an example of decoding argument types for a format string.  We
1810 assume this is part of an interpreter which contains arguments of type
1811 @code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
1812 perhaps others which are not valid here).
1813
1814 @smallexample
1815 /* @r{Test whether the @var{nargs} specified objects}
1816    @r{in the vector @var{args} are valid}
1817    @r{for the format string @var{format}:}
1818    @r{if so, return 1.}
1819    @r{If not, return 0 after printing an error message.}  */
1820
1821 int
1822 validate_args (char *format, int nargs, OBJECT *args)
1823 @{
1824   int *argtypes;
1825   int nwanted;
1826
1827   /* @r{Get the information about the arguments.}
1828      @r{Each conversion specification must be at least two characters}
1829      @r{long, so there cannot be more specifications than half the}
1830      @r{length of the string.}  */
1831
1832   argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
1833   nwanted = parse_printf_format (string, nelts, argtypes);
1834
1835   /* @r{Check the number of arguments.}  */
1836   if (nwanted > nargs)
1837     @{
1838       error ("too few arguments (at least %d required)", nwanted);
1839       return 0;
1840     @}
1841
1842   /* @r{Check the C type wanted for each argument}
1843      @r{and see if the object given is suitable.}  */
1844   for (i = 0; i < nwanted; i++)
1845     @{
1846       int wanted;
1847
1848       if (argtypes[i] & PA_FLAG_PTR)
1849         wanted = STRUCTURE;
1850       else
1851         switch (argtypes[i] & ~PA_FLAG_MASK)
1852           @{
1853           case PA_INT:
1854           case PA_FLOAT:
1855           case PA_DOUBLE:
1856             wanted = NUMBER;
1857             break;
1858           case PA_CHAR:
1859             wanted = CHAR;
1860             break;
1861           case PA_STRING:
1862             wanted = STRING;
1863             break;
1864           case PA_POINTER:
1865             wanted = STRUCTURE;
1866             break;
1867           @}
1868       if (TYPE (args[i]) != wanted)
1869         @{
1870           error ("type mismatch for arg number %d", i);
1871           return 0;
1872         @}
1873     @}
1874   return 1;
1875 @}
1876 @end smallexample
1877
1878 @node Customizing Printf
1879 @section Customizing @code{printf}
1880 @cindex customizing @code{printf}
1881 @cindex defining new @code{printf} conversions
1882 @cindex extending @code{printf}
1883
1884 The GNU C library lets you define your own custom conversion specifiers
1885 for @code{printf} template strings, to teach @code{printf} clever ways
1886 to print the important data structures of your program.
1887
1888 The way you do this is by registering the conversion with the function
1889 @code{register_printf_function}; see @ref{Registering New Conversions}.
1890 One of the arguments you pass to this function is a pointer to a handler
1891 function that produces the actual output; see @ref{Defining the Output
1892 Handler}, for information on how to write this function.
1893
1894 You can also install a function that just returns information about the
1895 number and type of arguments expected by the conversion specifier.
1896 @xref{Parsing a Template String}, for information about this.
1897
1898 The facilities of this section are declared in the header file
1899 @file{printf.h}.
1900
1901 @menu
1902 * Registering New Conversions::         Using @code{register_printf_function}
1903                                          to register a new output conversion.
1904 * Conversion Specifier Options::        The handler must be able to get
1905                                          the options specified in the
1906                                          template when it is called.
1907 * Defining the Output Handler::         Defining the handler and arginfo
1908                                          functions that are passed as arguments
1909                                          to @code{register_printf_function}.
1910 * Printf Extension Example::            How to define a @code{printf}
1911                                          handler function.
1912 @end menu
1913
1914 @strong{Portability Note:} The ability to extend the syntax of
1915 @code{printf} template strings is a GNU extension.  ANSI standard C has
1916 nothing similar.
1917
1918 @node Registering New Conversions
1919 @subsection Registering New Conversions
1920
1921 The function to register a new output conversion is
1922 @code{register_printf_function}, declared in @file{printf.h}.
1923 @pindex printf.h
1924
1925 @comment printf.h
1926 @comment GNU
1927 @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function})
1928 This function defines the conversion specifier character @var{spec}.
1929 Thus, if @var{spec} is @code{'z'}, it defines the conversion @samp{%z}.
1930 You can redefine the built-in conversions like @samp{%s}, but flag
1931 characters like @samp{#} and type modifiers like @samp{l} can never be
1932 used as conversions; calling @code{register_printf_function} for those
1933 characters has no effect.
1934
1935 The @var{handler-function} is the function called by @code{printf} and
1936 friends when this conversion appears in a template string.
1937 @xref{Defining the Output Handler}, for information about how to define
1938 a function to pass as this argument.  If you specify a null pointer, any
1939 existing handler function for @var{spec} is removed.
1940
1941 The @var{arginfo-function} is the function called by
1942 @code{parse_printf_format} when this conversion appears in a
1943 template string.  @xref{Parsing a Template String}, for information
1944 about this.
1945
1946 @c The following is not true anymore.  The `parse_printf_format' function
1947 @c is now also called from `vfprintf' via `parse_one_spec'.
1948 @c --drepper@gnu, 1996/11/14
1949 @c
1950 @c Normally, you install both functions for a conversion at the same time,
1951 @c but if you are never going to call @code{parse_printf_format}, you do
1952 @c not need to define an arginfo function.
1953
1954 @strong{Attention:} In the GNU C library version before 2.0 the
1955 @var{arginfo-function} function did not need to be installed unless
1956 the user uses the @code{parse_printf_format} function.  This changed.
1957 Now a call to any of the @code{printf} functions will call this
1958 function when this format specifier appears in the format string.
1959
1960 The return value is @code{0} on success, and @code{-1} on failure
1961 (which occurs if @var{spec} is out of range).
1962
1963 You can redefine the standard output conversions, but this is probably
1964 not a good idea because of the potential for confusion.  Library routines
1965 written by other people could break if you do this.
1966 @end deftypefun
1967
1968 @node Conversion Specifier Options
1969 @subsection Conversion Specifier Options
1970
1971 If you define a meaning for @samp{%A}, what if the template contains
1972 @samp{%+23A} or @samp{%-#A}?  To implement a sensible meaning for these,
1973 the handler when called needs to be able to get the options specified in
1974 the template.
1975
1976 Both the @var{handler-function} and @var{arginfo-function} arguments
1977 to @code{register_printf_function} accept an argument that points to a
1978 @code{struct printf_info}, which contains information about the options
1979 appearing in an instance of the conversion specifier.  This data type
1980 is declared in the header file @file{printf.h}.
1981 @pindex printf.h
1982
1983 @comment printf.h
1984 @comment GNU
1985 @deftp {Type} {struct printf_info}
1986 This structure is used to pass information about the options appearing
1987 in an instance of a conversion specifier in a @code{printf} template
1988 string to the handler and arginfo functions for that specifier.  It
1989 contains the following members:
1990
1991 @table @code
1992 @item int prec
1993 This is the precision specified.  The value is @code{-1} if no precision
1994 was specified.  If the precision was given as @samp{*}, the
1995 @code{printf_info} structure passed to the handler function contains the
1996 actual value retrieved from the argument list.  But the structure passed
1997 to the arginfo function contains a value of @code{INT_MIN}, since the
1998 actual value is not known.
1999
2000 @item int width
2001 This is the minimum field width specified.  The value is @code{0} if no
2002 width was specified.  If the field width was given as @samp{*}, the
2003 @code{printf_info} structure passed to the handler function contains the
2004 actual value retrieved from the argument list.  But the structure passed
2005 to the arginfo function contains a value of @code{INT_MIN}, since the
2006 actual value is not known.
2007
2008 @item wchar_t spec
2009 This is the conversion specifier character specified.  It's stored in
2010 the structure so that you can register the same handler function for
2011 multiple characters, but still have a way to tell them apart when the
2012 handler function is called.
2013
2014 @item unsigned int is_long_double
2015 This is a boolean that is true if the @samp{L}, @samp{ll}, or @samp{q}
2016 type modifier was specified.  For integer conversions, this indicates
2017 @code{long long int}, as opposed to @code{long double} for floating
2018 point conversions.
2019
2020 @item unsigned int is_short
2021 This is a boolean that is true if the @samp{h} type modifier was specified.
2022
2023 @item unsigned int is_long
2024 This is a boolean that is true if the @samp{l} type modifier was specified.
2025
2026 @item unsigned int alt
2027 This is a boolean that is true if the @samp{#} flag was specified.
2028
2029 @item unsigned int space
2030 This is a boolean that is true if the @samp{ } flag was specified.
2031
2032 @item unsigned int left
2033 This is a boolean that is true if the @samp{-} flag was specified.
2034
2035 @item unsigned int showsign
2036 This is a boolean that is true if the @samp{+} flag was specified.
2037
2038 @item unsigned int group
2039 This is a boolean that is true if the @samp{'} flag was specified.
2040
2041 @item unsigned int extra
2042 This flag has a special meaning depending on the context.  It could
2043 be used freely by the user-defined handlers but when called from
2044 the @code{printf} function this variable always contains the value
2045 @code{0}.
2046
2047 @item wchar_t pad
2048 This is the character to use for padding the output to the minimum field
2049 width.  The value is @code{'0'} if the @samp{0} flag was specified, and
2050 @code{' '} otherwise.
2051 @end table
2052 @end deftp
2053
2054
2055 @node Defining the Output Handler
2056 @subsection Defining the Output Handler
2057
2058 Now let's look at how to define the handler and arginfo functions
2059 which are passed as arguments to @code{register_printf_function}.
2060
2061 @strong{Compatibility Note:} The interface change in the GNU libc
2062 version 2.0.  Previously the third argument was of type
2063 @code{va_list *}.
2064
2065 You should define your handler functions with a prototype like:
2066
2067 @smallexample
2068 int @var{function} (FILE *stream, const struct printf_info *info,
2069                     const void *const *args)
2070 @end smallexample
2071
2072 The @var{stream} argument passed to the handler function is the stream to
2073 which it should write output.
2074
2075 The @var{info} argument is a pointer to a structure that contains
2076 information about the various options that were included with the
2077 conversion in the template string.  You should not modify this structure
2078 inside your handler function.  @xref{Conversion Specifier Options}, for
2079 a description of this data structure.
2080
2081 @c The following changes some time back.  --drepper@gnu, 1996/11/14
2082 @c
2083 @c The @code{ap_pointer} argument is used to pass the tail of the variable
2084 @c argument list containing the values to be printed to your handler.
2085 @c Unlike most other functions that can be passed an explicit variable
2086 @c argument list, this is a @emph{pointer} to a @code{va_list}, rather than
2087 @c the @code{va_list} itself.  Thus, you should fetch arguments by
2088 @c means of @code{va_arg (*ap_pointer, @var{type})}.
2089 @c
2090 @c (Passing a pointer here allows the function that calls your handler
2091 @c function to update its own @code{va_list} variable to account for the
2092 @c arguments that your handler processes.  @xref{Variadic Functions}.)
2093
2094 The @var{args} is a vector of pointers to the arguments data.
2095 The number of arguments were determined by calling the argument
2096 information function provided by the user.
2097
2098 Your handler function should return a value just like @code{printf}
2099 does: it should return the number of characters it has written, or a
2100 negative value to indicate an error.
2101
2102 @comment printf.h
2103 @comment GNU
2104 @deftp {Data Type} printf_function
2105 This is the data type that a handler function should have.
2106 @end deftp
2107
2108 If you are going to use @w{@code{parse_printf_format}} in your
2109 application, you must also define a function to pass as the
2110 @var{arginfo-function} argument for each new conversion you install with
2111 @code{register_printf_function}.
2112
2113 You have to define these functions with a prototype like:
2114
2115 @smallexample
2116 int @var{function} (const struct printf_info *info,
2117                     size_t n, int *argtypes)
2118 @end smallexample
2119
2120 The return value from the function should be the number of arguments the
2121 conversion expects.  The function should also fill in no more than
2122 @var{n} elements of the @var{argtypes} array with information about the
2123 types of each of these arguments.  This information is encoded using the
2124 various @samp{PA_} macros.  (You will notice that this is the same
2125 calling convention @code{parse_printf_format} itself uses.)
2126
2127 @comment printf.h
2128 @comment GNU
2129 @deftp {Data Type} printf_arginfo_function
2130 This type is used to describe functions that return information about
2131 the number and type of arguments used by a conversion specifier.
2132 @end deftp
2133
2134 @node Printf Extension Example
2135 @subsection @code{printf} Extension Example
2136
2137 Here is an example showing how to define a @code{printf} handler function.
2138 This program defines a data structure called a @code{Widget} and
2139 defines the @samp{%W} conversion to print information about @w{@code{Widget *}}
2140 arguments, including the pointer value and the name stored in the data
2141 structure.  The @samp{%W} conversion supports the minimum field width and
2142 left-justification options, but ignores everything else.
2143
2144 @smallexample
2145 @include rprintf.c.texi
2146 @end smallexample
2147
2148 The output produced by this program looks like:
2149
2150 @smallexample
2151 |<Widget 0xffeffb7c: mywidget>|
2152 |      <Widget 0xffeffb7c: mywidget>|
2153 |<Widget 0xffeffb7c: mywidget>      |
2154 @end smallexample
2155
2156 @node Formatted Input
2157 @section Formatted Input
2158
2159 @cindex formatted input from a stream
2160 @cindex reading from a stream, formatted
2161 @cindex format string, for @code{scanf}
2162 @cindex template, for @code{scanf}
2163 The functions described in this section (@code{scanf} and related
2164 functions) provide facilities for formatted input analogous to the
2165 formatted output facilities.  These functions provide a mechanism for
2166 reading arbitrary values under the control of a @dfn{format string} or
2167 @dfn{template string}.
2168
2169 @menu
2170 * Formatted Input Basics::      Some basics to get you started.
2171 * Input Conversion Syntax::     Syntax of conversion specifications.
2172 * Table of Input Conversions::  Summary of input conversions and what they do.
2173 * Numeric Input Conversions::   Details of conversions for reading numbers.
2174 * String Input Conversions::    Details of conversions for reading strings.
2175 * Dynamic String Input::        String conversions that @code{malloc} the buffer.
2176 * Other Input Conversions::     Details of miscellaneous other conversions.
2177 * Formatted Input Functions::   Descriptions of the actual functions.
2178 * Variable Arguments Input::    @code{vscanf} and friends.
2179 @end menu
2180
2181 @node Formatted Input Basics
2182 @subsection Formatted Input Basics
2183
2184 Calls to @code{scanf} are superficially similar to calls to
2185 @code{printf} in that arbitrary arguments are read under the control of
2186 a template string.  While the syntax of the conversion specifications in
2187 the template is very similar to that for @code{printf}, the
2188 interpretation of the template is oriented more towards free-format
2189 input and simple pattern matching, rather than fixed-field formatting.
2190 For example, most @code{scanf} conversions skip over any amount of
2191 ``white space'' (including spaces, tabs, and newlines) in the input
2192 file, and there is no concept of precision for the numeric input
2193 conversions as there is for the corresponding output conversions.
2194 Ordinarily, non-whitespace characters in the template are expected to
2195 match characters in the input stream exactly, but a matching failure is
2196 distinct from an input error on the stream.
2197 @cindex conversion specifications (@code{scanf})
2198
2199 Another area of difference between @code{scanf} and @code{printf} is
2200 that you must remember to supply pointers rather than immediate values
2201 as the optional arguments to @code{scanf}; the values that are read are
2202 stored in the objects that the pointers point to.  Even experienced
2203 programmers tend to forget this occasionally, so if your program is
2204 getting strange errors that seem to be related to @code{scanf}, you
2205 might want to double-check this.
2206
2207 When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
2208 leaving the first non-matching character as the next character to be
2209 read from the stream.  The normal return value from @code{scanf} is the
2210 number of values that were assigned, so you can use this to determine if
2211 a matching error happened before all the expected values were read.
2212 @cindex matching failure, in @code{scanf}
2213
2214 The @code{scanf} function is typically used for things like reading in
2215 the contents of tables.  For example, here is a function that uses
2216 @code{scanf} to initialize an array of @code{double}:
2217
2218 @smallexample
2219 void
2220 readarray (double *array, int n)
2221 @{
2222   int i;
2223   for (i=0; i<n; i++)
2224     if (scanf (" %lf", &(array[i])) != 1)
2225       invalid_input_error ();
2226 @}
2227 @end smallexample
2228
2229 The formatted input functions are not used as frequently as the
2230 formatted output functions.  Partly, this is because it takes some care
2231 to use them properly.  Another reason is that it is difficult to recover
2232 from a matching error.
2233
2234 If you are trying to read input that doesn't match a single, fixed
2235 pattern, you may be better off using a tool such as Flex to generate a
2236 lexical scanner, or Bison to generate a parser, rather than using
2237 @code{scanf}.  For more information about these tools, see @ref{, , ,
2238 flex.info, Flex: The Lexical Scanner Generator}, and @ref{, , ,
2239 bison.info, The Bison Reference Manual}.
2240
2241 @node Input Conversion Syntax
2242 @subsection Input Conversion Syntax
2243
2244 A @code{scanf} template string is a string that contains ordinary
2245 multibyte characters interspersed with conversion specifications that
2246 start with @samp{%}.
2247
2248 Any whitespace character (as defined by the @code{isspace} function;
2249 @pxref{Classification of Characters}) in the template causes any number
2250 of whitespace characters in the input stream to be read and discarded.
2251 The whitespace characters that are matched need not be exactly the same
2252 whitespace characters that appear in the template string.  For example,
2253 write @samp{ , } in the template to recognize a comma with optional
2254 whitespace before and after.
2255
2256 Other characters in the template string that are not part of conversion
2257 specifications must match characters in the input stream exactly; if
2258 this is not the case, a matching failure occurs.
2259
2260 The conversion specifications in a @code{scanf} template string
2261 have the general form:
2262
2263 @smallexample
2264 % @var{flags} @var{width} @var{type} @var{conversion}
2265 @end smallexample
2266
2267 In more detail, an input conversion specification consists of an initial
2268 @samp{%} character followed in sequence by:
2269
2270 @itemize @bullet
2271 @item
2272 An optional @dfn{flag character} @samp{*}, which says to ignore the text
2273 read for this specification.  When @code{scanf} finds a conversion
2274 specification that uses this flag, it reads input as directed by the
2275 rest of the conversion specification, but it discards this input, does
2276 not use a pointer argument, and does not increment the count of
2277 successful assignments.
2278 @cindex flag character (@code{scanf})
2279
2280 @item
2281 An optional flag character @samp{a} (valid with string conversions only)
2282 which requests allocation of a buffer long enough to store the string in.
2283 (This is a GNU extension.)
2284 @xref{Dynamic String Input}.
2285
2286 @item
2287 An optional decimal integer that specifies the @dfn{maximum field
2288 width}.  Reading of characters from the input stream stops either when
2289 this maximum is reached or when a non-matching character is found,
2290 whichever happens first.  Most conversions discard initial whitespace
2291 characters (those that don't are explicitly documented), and these
2292 discarded characters don't count towards the maximum field width.
2293 String input conversions store a null character to mark the end of the
2294 input; the maximum field width does not include this terminator.
2295 @cindex maximum field width (@code{scanf})
2296
2297 @item
2298 An optional @dfn{type modifier character}.  For example, you can
2299 specify a type modifier of @samp{l} with integer conversions such as
2300 @samp{%d} to specify that the argument is a pointer to a @code{long int}
2301 rather than a pointer to an @code{int}.
2302 @cindex type modifier character (@code{scanf})
2303
2304 @item
2305 A character that specifies the conversion to be applied.
2306 @end itemize
2307
2308 The exact options that are permitted and how they are interpreted vary
2309 between the different conversion specifiers.  See the descriptions of the
2310 individual conversions for information about the particular options that
2311 they allow.
2312
2313 With the @samp{-Wformat} option, the GNU C compiler checks calls to
2314 @code{scanf} and related functions.  It examines the format string and
2315 verifies that the correct number and types of arguments are supplied.
2316 There is also a GNU C syntax to tell the compiler that a function you
2317 write uses a @code{scanf}-style format string.
2318 @xref{Function Attributes, , Declaring Attributes of Functions,
2319 gcc.info, Using GNU CC}, for more information.
2320
2321 @node Table of Input Conversions
2322 @subsection Table of Input Conversions
2323 @cindex input conversions, for @code{scanf}
2324
2325 Here is a table that summarizes the various conversion specifications:
2326
2327 @table @asis
2328 @item @samp{%d}
2329 Matches an optionally signed integer written in decimal.  @xref{Numeric
2330 Input Conversions}.
2331
2332 @item @samp{%i}
2333 Matches an optionally signed integer in any of the formats that the C
2334 language defines for specifying an integer constant.  @xref{Numeric
2335 Input Conversions}.
2336
2337 @item @samp{%o}
2338 Matches an unsigned integer written in octal radix.
2339 @xref{Numeric Input Conversions}.
2340
2341 @item @samp{%u}
2342 Matches an unsigned integer written in decimal radix.
2343 @xref{Numeric Input Conversions}.
2344
2345 @item @samp{%x}, @samp{%X}
2346 Matches an unsigned integer written in hexadecimal radix.
2347 @xref{Numeric Input Conversions}.
2348
2349 @item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
2350 Matches an optionally signed floating-point number.  @xref{Numeric Input
2351 Conversions}.
2352
2353 @item @samp{%s}
2354 Matches a string containing only non-whitespace characters.
2355 @xref{String Input Conversions}.
2356
2357 @item @samp{%[}
2358 Matches a string of characters that belong to a specified set.
2359 @xref{String Input Conversions}.
2360
2361 @item @samp{%c}
2362 Matches a string of one or more characters; the number of characters
2363 read is controlled by the maximum field width given for the conversion.
2364 @xref{String Input Conversions}.
2365
2366 @item @samp{%p}
2367 Matches a pointer value in the same implementation-defined format used
2368 by the @samp{%p} output conversion for @code{printf}.  @xref{Other Input
2369 Conversions}.
2370
2371 @item @samp{%n}
2372 This conversion doesn't read any characters; it records the number of
2373 characters read so far by this call.  @xref{Other Input Conversions}.
2374
2375 @item @samp{%%}
2376 This matches a literal @samp{%} character in the input stream.  No
2377 corresponding argument is used.  @xref{Other Input Conversions}.
2378 @end table
2379
2380 If the syntax of a conversion specification is invalid, the behavior is
2381 undefined.  If there aren't enough function arguments provided to supply
2382 addresses for all the conversion specifications in the template strings
2383 that perform assignments, or if the arguments are not of the correct
2384 types, the behavior is also undefined.  On the other hand, extra
2385 arguments are simply ignored.
2386
2387 @node Numeric Input Conversions
2388 @subsection Numeric Input Conversions
2389
2390 This section describes the @code{scanf} conversions for reading numeric
2391 values.
2392
2393 The @samp{%d} conversion matches an optionally signed integer in decimal
2394 radix.  The syntax that is recognized is the same as that for the
2395 @code{strtol} function (@pxref{Parsing of Integers}) with the value
2396 @code{10} for the @var{base} argument.
2397
2398 The @samp{%i} conversion matches an optionally signed integer in any of
2399 the formats that the C language defines for specifying an integer
2400 constant.  The syntax that is recognized is the same as that for the
2401 @code{strtol} function (@pxref{Parsing of Integers}) with the value
2402 @code{0} for the @var{base} argument.  (You can print integers in this
2403 syntax with @code{printf} by using the @samp{#} flag character with the
2404 @samp{%x}, @samp{%o}, or @samp{%d} conversion.  @xref{Integer Conversions}.)
2405
2406 For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
2407 could be read in as integers under the @samp{%i} conversion.  Each of
2408 these specifies a number with decimal value @code{10}.
2409
2410 The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned
2411 integers in octal, decimal, and hexadecimal radices, respectively.  The
2412 syntax that is recognized is the same as that for the @code{strtoul}
2413 function (@pxref{Parsing of Integers}) with the appropriate value
2414 (@code{8}, @code{10}, or @code{16}) for the @var{base} argument.
2415
2416 The @samp{%X} conversion is identical to the @samp{%x} conversion.  They
2417 both permit either uppercase or lowercase letters to be used as digits.
2418
2419 The default type of the corresponding argument for the @code{%d} and
2420 @code{%i} conversions is @code{int *}, and @code{unsigned int *} for the
2421 other integer conversions.  You can use the following type modifiers to
2422 specify other sizes of integer:
2423
2424 @table @samp
2425 @item h
2426 Specifies that the argument is a @code{short int *} or @code{unsigned
2427 short int *}.
2428
2429 @item l
2430 Specifies that the argument is a @code{long int *} or @code{unsigned
2431 long int *}.  Two @samp{l} characters is like the @samp{L} modifier, below.
2432
2433 @need 100
2434 @item ll
2435 @itemx L
2436 @itemx q
2437 Specifies that the argument is a @code{long long int *} or @code{unsigned long long int *}.  (The @code{long long} type is an extension supported by the
2438 GNU C compiler.  For systems that don't provide extra-long integers, this
2439 is the same as @code{long int}.)
2440
2441 The @samp{q} modifier is another name for the same thing, which comes
2442 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
2443 @code{int}.
2444 @end table
2445
2446 All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
2447 input conversions are interchangeable.  They all match an optionally
2448 signed floating point number, in the same syntax as for the
2449 @code{strtod} function (@pxref{Parsing of Floats}).
2450
2451 For the floating-point input conversions, the default argument type is
2452 @code{float *}.  (This is different from the corresponding output
2453 conversions, where the default type is @code{double}; remember that
2454 @code{float} arguments to @code{printf} are converted to @code{double}
2455 by the default argument promotions, but @code{float *} arguments are
2456 not promoted to @code{double *}.)  You can specify other sizes of float
2457 using these type modifiers:
2458
2459 @table @samp
2460 @item l
2461 Specifies that the argument is of type @code{double *}.
2462
2463 @item L
2464 Specifies that the argument is of type @code{long double *}.
2465 @end table
2466
2467 For all the above number parsing formats there is an additional optional
2468 flag @samp{'}.  When this flag is given the @code{scanf} function
2469 expects the number represented in the input string to be formatted
2470 according to the grouping rules of the currently selected locale
2471 (@pxref{General Numeric}).
2472
2473 If the @code{"C"} or @code{"POSIX"} locale is selected there is no
2474 difference.  But for a locale which specifies values for the appropriate
2475 fields in the locale the input must have the correct form in the input.
2476 Otherwise the longest prefix with a correct form is processed.
2477
2478 @node String Input Conversions
2479 @subsection String Input Conversions
2480
2481 This section describes the @code{scanf} input conversions for reading
2482 string and character values: @samp{%s}, @samp{%[}, and @samp{%c}.
2483
2484 You have two options for how to receive the input from these
2485 conversions:
2486
2487 @itemize @bullet
2488 @item
2489 Provide a buffer to store it in.  This is the default.  You
2490 should provide an argument of type @code{char *}.
2491
2492 @strong{Warning:} To make a robust program, you must make sure that the
2493 input (plus its terminating null) cannot possibly exceed the size of the
2494 buffer you provide.  In general, the only way to do this is to specify a
2495 maximum field width one less than the buffer size.  @strong{If you
2496 provide the buffer, always specify a maximum field width to prevent
2497 overflow.}
2498
2499 @item
2500 Ask @code{scanf} to allocate a big enough buffer, by specifying the
2501 @samp{a} flag character.  This is a GNU extension.  You should provide
2502 an argument of type @code{char **} for the buffer address to be stored
2503 in.  @xref{Dynamic String Input}.
2504 @end itemize
2505
2506 The @samp{%c} conversion is the simplest: it matches a fixed number of
2507 characters, always.  The maximum field with says how many characters to
2508 read; if you don't specify the maximum, the default is 1.  This
2509 conversion doesn't append a null character to the end of the text it
2510 reads.  It also does not skip over initial whitespace characters.  It
2511 reads precisely the next @var{n} characters, and fails if it cannot get
2512 that many.  Since there is always a maximum field width with @samp{%c}
2513 (whether specified, or 1 by default), you can always prevent overflow by
2514 making the buffer long enough.
2515
2516 The @samp{%s} conversion matches a string of non-whitespace characters.
2517 It skips and discards initial whitespace, but stops when it encounters
2518 more whitespace after having read something.  It stores a null character
2519 at the end of the text that it reads.
2520
2521 For example, reading the input:
2522
2523 @smallexample
2524  hello, world
2525 @end smallexample
2526
2527 @noindent
2528 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
2529 reading the same input with the conversion @samp{%10s} produces
2530 @code{"hello,"}.
2531
2532 @strong{Warning:} If you do not specify a field width for @samp{%s},
2533 then the number of characters read is limited only by where the next
2534 whitespace character appears.  This almost certainly means that invalid
2535 input can make your program crash---which is a bug.
2536
2537 To read in characters that belong to an arbitrary set of your choice,
2538 use the @samp{%[} conversion.  You specify the set between the @samp{[}
2539 character and a following @samp{]} character, using the same syntax used
2540 in regular expressions.  As special cases:
2541
2542 @itemize @bullet
2543 @item
2544 A literal @samp{]} character can be specified as the first character
2545 of the set.
2546
2547 @item
2548 An embedded @samp{-} character (that is, one that is not the first or
2549 last character of the set) is used to specify a range of characters.
2550
2551 @item
2552 If a caret character @samp{^} immediately follows the initial @samp{[},
2553 then the set of allowed input characters is the everything @emph{except}
2554 the characters listed.
2555 @end itemize
2556
2557 The @samp{%[} conversion does not skip over initial whitespace
2558 characters.
2559
2560 Here are some examples of @samp{%[} conversions and what they mean:
2561
2562 @table @samp
2563 @item %25[1234567890]
2564 Matches a string of up to 25 digits.
2565
2566 @item %25[][]
2567 Matches a string of up to 25 square brackets.
2568
2569 @item %25[^ \f\n\r\t\v]
2570 Matches a string up to 25 characters long that doesn't contain any of
2571 the standard whitespace characters.  This is slightly different from
2572 @samp{%s}, because if the input begins with a whitespace character,
2573 @samp{%[} reports a matching failure while @samp{%s} simply discards the
2574 initial whitespace.
2575
2576 @item %25[a-z]
2577 Matches up to 25 lowercase characters.
2578 @end table
2579
2580 One more reminder: the @samp{%s} and @samp{%[} conversions are
2581 @strong{dangerous} if you don't specify a maximum width or use the
2582 @samp{a} flag, because input too long would overflow whatever buffer you
2583 have provided for it.  No matter how long your buffer is, a user could
2584 supply input that is longer.  A well-written program reports invalid
2585 input with a comprehensible error message, not with a crash.
2586
2587 @node Dynamic String Input
2588 @subsection Dynamically Allocating String Conversions
2589
2590 A GNU extension to formatted input lets you safely read a string with no
2591 maximum size.  Using this feature, you don't supply a buffer; instead,
2592 @code{scanf} allocates a buffer big enough to hold the data and gives
2593 you its address.  To use this feature, write @samp{a} as a flag
2594 character, as in @samp{%as} or @samp{%a[0-9a-z]}.
2595
2596 The pointer argument you supply for where to store the input should have
2597 type @code{char **}.  The @code{scanf} function allocates a buffer and
2598 stores its address in the word that the argument points to.  You should
2599 free the buffer with @code{free} when you no longer need it.
2600
2601 Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]}
2602 conversion specification to read a ``variable assignment'' of the form
2603 @samp{@var{variable} = @var{value}}.
2604
2605 @smallexample
2606 @{
2607   char *variable, *value;
2608
2609   if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
2610                  &variable, &value))
2611     @{
2612       invalid_input_error ();
2613       return 0;
2614     @}
2615
2616   @dots{}
2617 @}
2618 @end smallexample
2619
2620 @node Other Input Conversions
2621 @subsection Other Input Conversions
2622
2623 This section describes the miscellaneous input conversions.
2624
2625 The @samp{%p} conversion is used to read a pointer value.  It recognizes
2626 the same syntax as is used by the @samp{%p} output conversion for
2627 @code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
2628 number just as the @samp{%x} conversion accepts.  The corresponding
2629 argument should be of type @code{void **}; that is, the address of a
2630 place to store a pointer.
2631
2632 The resulting pointer value is not guaranteed to be valid if it was not
2633 originally written during the same program execution that reads it in.
2634
2635 The @samp{%n} conversion produces the number of characters read so far
2636 by this call.  The corresponding argument should be of type @code{int *}.
2637 This conversion works in the same way as the @samp{%n} conversion for
2638 @code{printf}; see @ref{Other Output Conversions}, for an example.
2639
2640 The @samp{%n} conversion is the only mechanism for determining the
2641 success of literal matches or conversions with suppressed assignments.
2642 If the @samp{%n} follows the locus of a matching failure, then no value
2643 is stored for it since @code{scanf} returns before processing the
2644 @samp{%n}.  If you store @code{-1} in that argument slot before calling
2645 @code{scanf}, the presence of @code{-1} after @code{scanf} indicates an
2646 error occurred before the @samp{%n} was reached.
2647
2648 Finally, the @samp{%%} conversion matches a literal @samp{%} character
2649 in the input stream, without using an argument.  This conversion does
2650 not permit any flags, field width, or type modifier to be specified.
2651
2652 @node Formatted Input Functions
2653 @subsection Formatted Input Functions
2654
2655 Here are the descriptions of the functions for performing formatted
2656 input.
2657 Prototypes for these functions are in the header file @file{stdio.h}.
2658 @pindex stdio.h
2659
2660 @comment stdio.h
2661 @comment ANSI
2662 @deftypefun int scanf (const char *@var{template}, @dots{})
2663 The @code{scanf} function reads formatted input from the stream
2664 @code{stdin} under the control of the template string @var{template}.
2665 The optional arguments are pointers to the places which receive the
2666 resulting values.
2667
2668 The return value is normally the number of successful assignments.  If
2669 an end-of-file condition is detected before any matches are performed
2670 (including matches against whitespace and literal characters in the
2671 template), then @code{EOF} is returned.
2672 @end deftypefun
2673
2674 @comment stdio.h
2675 @comment ANSI
2676 @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
2677 This function is just like @code{scanf}, except that the input is read
2678 from the stream @var{stream} instead of @code{stdin}.
2679 @end deftypefun
2680
2681 @comment stdio.h
2682 @comment ANSI
2683 @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
2684 This is like @code{scanf}, except that the characters are taken from the
2685 null-terminated string @var{s} instead of from a stream.  Reaching the
2686 end of the string is treated as an end-of-file condition.
2687
2688 The behavior of this function is undefined if copying takes place
2689 between objects that overlap---for example, if @var{s} is also given
2690 as an argument to receive a string read under control of the @samp{%s}
2691 conversion.
2692 @end deftypefun
2693
2694 @node Variable Arguments Input
2695 @subsection Variable Arguments Input Functions
2696
2697 The functions @code{vscanf} and friends are provided so that you can
2698 define your own variadic @code{scanf}-like functions that make use of
2699 the same internals as the built-in formatted output functions.
2700 These functions are analogous to the @code{vprintf} series of output
2701 functions.  @xref{Variable Arguments Output}, for important
2702 information on how to use them.
2703
2704 @strong{Portability Note:} The functions listed in this section are GNU
2705 extensions.
2706
2707 @comment stdio.h
2708 @comment GNU
2709 @deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
2710 This function is similar to @code{scanf} except that, instead of taking
2711 a variable number of arguments directly, it takes an argument list
2712 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
2713 @end deftypefun
2714
2715 @comment stdio.h
2716 @comment GNU
2717 @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
2718 This is the equivalent of @code{fscanf} with the variable argument list
2719 specified directly as for @code{vscanf}.
2720 @end deftypefun
2721
2722 @comment stdio.h
2723 @comment GNU
2724 @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
2725 This is the equivalent of @code{sscanf} with the variable argument list
2726 specified directly as for @code{vscanf}.
2727 @end deftypefun
2728
2729 In GNU C, there is a special construct you can use to let the compiler
2730 know that a function uses a @code{scanf}-style format string.  Then it
2731 can check the number and types of arguments in each call to the
2732 function, and warn you when they do not match the format string.
2733 @xref{Function Attributes, , Declaring Attributes of Functions,
2734 gcc.info, Using GNU CC}, for details.
2735
2736 @node EOF and Errors
2737 @section End-Of-File and Errors
2738
2739 @cindex end of file, on a stream
2740 Many of the functions described in this chapter return the value of the
2741 macro @code{EOF} to indicate unsuccessful completion of the operation.
2742 Since @code{EOF} is used to report both end of file and random errors,
2743 it's often better to use the @code{feof} function to check explicitly
2744 for end of file and @code{ferror} to check for errors.  These functions
2745 check indicators that are part of the internal state of the stream
2746 object, indicators set if the appropriate condition was detected by a
2747 previous I/O operation on that stream.
2748
2749 These symbols are declared in the header file @file{stdio.h}.
2750 @pindex stdio.h
2751
2752 @comment stdio.h
2753 @comment ANSI
2754 @deftypevr Macro int EOF
2755 This macro is an integer value that is returned by a number of functions
2756 to indicate an end-of-file condition, or some other error situation.
2757 With the GNU library, @code{EOF} is @code{-1}.  In other libraries, its
2758 value may be some other negative number.
2759 @end deftypevr
2760
2761 @comment stdio.h
2762 @comment ANSI
2763 @deftypefun void clearerr (FILE *@var{stream})
2764 This function clears the end-of-file and error indicators for the
2765 stream @var{stream}.
2766
2767 The file positioning functions (@pxref{File Positioning}) also clear the
2768 end-of-file indicator for the stream.
2769 @end deftypefun
2770
2771 @comment stdio.h
2772 @comment ANSI
2773 @deftypefun int feof (FILE *@var{stream})
2774 The @code{feof} function returns nonzero if and only if the end-of-file
2775 indicator for the stream @var{stream} is set.
2776 @end deftypefun
2777
2778 @comment stdio.h
2779 @comment ANSI
2780 @deftypefun int ferror (FILE *@var{stream})
2781 The @code{ferror} function returns nonzero if and only if the error
2782 indicator for the stream @var{stream} is set, indicating that an error
2783 has occurred on a previous operation on the stream.
2784 @end deftypefun
2785
2786 In addition to setting the error indicator associated with the stream,
2787 the functions that operate on streams also set @code{errno} in the same
2788 way as the corresponding low-level functions that operate on file
2789 descriptors.  For example, all of the functions that perform output to a
2790 stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are
2791 implemented in terms of @code{write}, and all of the @code{errno} error
2792 conditions defined for @code{write} are meaningful for these functions.
2793 For more information about the descriptor-level I/O functions, see
2794 @ref{Low-Level I/O}.
2795
2796 @node Binary Streams
2797 @section Text and Binary Streams
2798
2799 The GNU system and other POSIX-compatible operating systems organize all
2800 files as uniform sequences of characters.  However, some other systems
2801 make a distinction between files containing text and files containing
2802 binary data, and the input and output facilities of ANSI C provide for
2803 this distinction.  This section tells you how to write programs portable
2804 to such systems.
2805
2806 @cindex text stream
2807 @cindex binary stream
2808 When you open a stream, you can specify either a @dfn{text stream} or a
2809 @dfn{binary stream}.  You indicate that you want a binary stream by
2810 specifying the @samp{b} modifier in the @var{opentype} argument to
2811 @code{fopen}; see @ref{Opening Streams}.  Without this
2812 option, @code{fopen} opens the file as a text stream.
2813
2814 Text and binary streams differ in several ways:
2815
2816 @itemize @bullet
2817 @item
2818 The data read from a text stream is divided into @dfn{lines} which are
2819 terminated by newline (@code{'\n'}) characters, while a binary stream is
2820 simply a long series of characters.  A text stream might on some systems
2821 fail to handle lines more than 254 characters long (including the
2822 terminating newline character).
2823 @cindex lines (in a text file)
2824
2825 @item
2826 On some systems, text files can contain only printing characters,
2827 horizontal tab characters, and newlines, and so text streams may not
2828 support other characters.  However, binary streams can handle any
2829 character value.
2830
2831 @item
2832 Space characters that are written immediately preceding a newline
2833 character in a text stream may disappear when the file is read in again.
2834
2835 @item
2836 More generally, there need not be a one-to-one mapping between
2837 characters that are read from or written to a text stream, and the
2838 characters in the actual file.
2839 @end itemize
2840
2841 Since a binary stream is always more capable and more predictable than a
2842 text stream, you might wonder what purpose text streams serve.  Why not
2843 simply always use binary streams?  The answer is that on these operating
2844 systems, text and binary streams use different file formats, and the
2845 only way to read or write ``an ordinary file of text'' that can work
2846 with other text-oriented programs is through a text stream.
2847
2848 In the GNU library, and on all POSIX systems, there is no difference
2849 between text streams and binary streams.  When you open a stream, you
2850 get the same kind of stream regardless of whether you ask for binary.
2851 This stream can handle any file content, and has none of the
2852 restrictions that text streams sometimes have.
2853
2854 @node File Positioning
2855 @section File Positioning
2856 @cindex file positioning on a stream
2857 @cindex positioning a stream
2858 @cindex seeking on a stream
2859
2860 The @dfn{file position} of a stream describes where in the file the
2861 stream is currently reading or writing.  I/O on the stream advances the
2862 file position through the file.  In the GNU system, the file position is
2863 represented as an integer, which counts the number of bytes from the
2864 beginning of the file.  @xref{File Position}.
2865
2866 During I/O to an ordinary disk file, you can change the file position
2867 whenever you wish, so as to read or write any portion of the file.  Some
2868 other kinds of files may also permit this.  Files which support changing
2869 the file position are sometimes referred to as @dfn{random-access}
2870 files.
2871
2872 You can use the functions in this section to examine or modify the file
2873 position indicator associated with a stream.  The symbols listed below
2874 are declared in the header file @file{stdio.h}.
2875 @pindex stdio.h
2876
2877 @comment stdio.h
2878 @comment ANSI
2879 @deftypefun {long int} ftell (FILE *@var{stream})
2880 This function returns the current file position of the stream
2881 @var{stream}.
2882
2883 This function can fail if the stream doesn't support file positioning,
2884 or if the file position can't be represented in a @code{long int}, and
2885 possibly for other reasons as well.  If a failure occurs, a value of
2886 @code{-1} is returned.
2887 @end deftypefun
2888
2889 @comment stdio.h
2890 @comment ANSI
2891 @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
2892 The @code{fseek} function is used to change the file position of the
2893 stream @var{stream}.  The value of @var{whence} must be one of the
2894 constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
2895 indicate whether the @var{offset} is relative to the beginning of the
2896 file, the current file position, or the end of the file, respectively.
2897
2898 This function returns a value of zero if the operation was successful,
2899 and a nonzero value to indicate failure.  A successful call also clears
2900 the end-of-file indicator of @var{stream} and discards any characters
2901 that were ``pushed back'' by the use of @code{ungetc}.
2902
2903 @code{fseek} either flushes any buffered output before setting the file
2904 position or else remembers it so it will be written later in its proper
2905 place in the file.
2906 @end deftypefun
2907
2908 @strong{Portability Note:} In non-POSIX systems, @code{ftell} and
2909 @code{fseek} might work reliably only on binary streams.  @xref{Binary
2910 Streams}.
2911
2912 The following symbolic constants are defined for use as the @var{whence}
2913 argument to @code{fseek}.  They are also used with the @code{lseek}
2914 function (@pxref{I/O Primitives}) and to specify offsets for file locks
2915 (@pxref{Control Operations}).
2916
2917 @comment stdio.h
2918 @comment ANSI
2919 @deftypevr Macro int SEEK_SET
2920 This is an integer constant which, when used as the @var{whence}
2921 argument to the @code{fseek} function, specifies that the offset
2922 provided is relative to the beginning of the file.
2923 @end deftypevr
2924
2925 @comment stdio.h
2926 @comment ANSI
2927 @deftypevr Macro int SEEK_CUR
2928 This is an integer constant which, when used as the @var{whence}
2929 argument to the @code{fseek} function, specifies that the offset
2930 provided is relative to the current file position.
2931 @end deftypevr
2932
2933 @comment stdio.h
2934 @comment ANSI
2935 @deftypevr Macro int SEEK_END
2936 This is an integer constant which, when used as the @var{whence}
2937 argument to the @code{fseek} function, specifies that the offset
2938 provided is relative to the end of the file.
2939 @end deftypevr
2940
2941 @comment stdio.h
2942 @comment ANSI
2943 @deftypefun void rewind (FILE *@var{stream})
2944 The @code{rewind} function positions the stream @var{stream} at the
2945 begining of the file.  It is equivalent to calling @code{fseek} on the
2946 @var{stream} with an @var{offset} argument of @code{0L} and a
2947 @var{whence} argument of @code{SEEK_SET}, except that the return
2948 value is discarded and the error indicator for the stream is reset.
2949 @end deftypefun
2950
2951 These three aliases for the @samp{SEEK_@dots{}} constants exist for the
2952 sake of compatibility with older BSD systems.  They are defined in two
2953 different header files: @file{fcntl.h} and @file{sys/file.h}.
2954
2955 @table @code
2956 @comment sys/file.h
2957 @comment BSD
2958 @item L_SET
2959 @vindex L_SET
2960 An alias for @code{SEEK_SET}.
2961
2962 @comment sys/file.h
2963 @comment BSD
2964 @item L_INCR
2965 @vindex L_INCR
2966 An alias for @code{SEEK_CUR}.
2967
2968 @comment sys/file.h
2969 @comment BSD
2970 @item L_XTND
2971 @vindex L_XTND
2972 An alias for @code{SEEK_END}.
2973 @end table
2974
2975 @node Portable Positioning
2976 @section Portable File-Position Functions
2977
2978 On the GNU system, the file position is truly a character count.  You
2979 can specify any character count value as an argument to @code{fseek} and
2980 get reliable results for any random access file.  However, some ANSI C
2981 systems do not represent file positions in this way.
2982
2983 On some systems where text streams truly differ from binary streams, it
2984 is impossible to represent the file position of a text stream as a count
2985 of characters from the beginning of the file.  For example, the file
2986 position on some systems must encode both a record offset within the
2987 file, and a character offset within the record.
2988
2989 As a consequence, if you want your programs to be portable to these
2990 systems, you must observe certain rules:
2991
2992 @itemize @bullet
2993 @item
2994 The value returned from @code{ftell} on a text stream has no predictable
2995 relationship to the number of characters you have read so far.  The only
2996 thing you can rely on is that you can use it subsequently as the
2997 @var{offset} argument to @code{fseek} to move back to the same file
2998 position.
2999
3000 @item
3001 In a call to @code{fseek} on a text stream, either the @var{offset} must
3002 either be zero; or @var{whence} must be @code{SEEK_SET} and the
3003 @var{offset} must be the result of an earlier call to @code{ftell} on
3004 the same stream.
3005
3006 @item
3007 The value of the file position indicator of a text stream is undefined
3008 while there are characters that have been pushed back with @code{ungetc}
3009 that haven't been read or discarded.  @xref{Unreading}.
3010 @end itemize
3011
3012 But even if you observe these rules, you may still have trouble for long
3013 files, because @code{ftell} and @code{fseek} use a @code{long int} value
3014 to represent the file position.  This type may not have room to encode
3015 all the file positions in a large file.
3016
3017 So if you do want to support systems with peculiar encodings for the
3018 file positions, it is better to use the functions @code{fgetpos} and
3019 @code{fsetpos} instead.  These functions represent the file position
3020 using the data type @code{fpos_t}, whose internal representation varies
3021 from system to system.
3022
3023 These symbols are declared in the header file @file{stdio.h}.
3024 @pindex stdio.h
3025
3026 @comment stdio.h
3027 @comment ANSI
3028 @deftp {Data Type} fpos_t
3029 This is the type of an object that can encode information about the
3030 file position of a stream, for use by the functions @code{fgetpos} and
3031 @code{fsetpos}.
3032
3033 In the GNU system, @code{fpos_t} is equivalent to @code{off_t} or
3034 @code{long int}.  In other systems, it might have a different internal
3035 representation.
3036 @end deftp
3037
3038 @comment stdio.h
3039 @comment ANSI
3040 @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
3041 This function stores the value of the file position indicator for the
3042 stream @var{stream} in the @code{fpos_t} object pointed to by
3043 @var{position}.  If successful, @code{fgetpos} returns zero; otherwise
3044 it returns a nonzero value and stores an implementation-defined positive
3045 value in @code{errno}.
3046 @end deftypefun
3047
3048 @comment stdio.h
3049 @comment ANSI
3050 @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t @var{position})
3051 This function sets the file position indicator for the stream @var{stream}
3052 to the position @var{position}, which must have been set by a previous
3053 call to @code{fgetpos} on the same stream.  If successful, @code{fsetpos}
3054 clears the end-of-file indicator on the stream, discards any characters
3055 that were ``pushed back'' by the use of @code{ungetc}, and returns a value
3056 of zero.  Otherwise, @code{fsetpos} returns a nonzero value and stores
3057 an implementation-defined positive value in @code{errno}.
3058 @end deftypefun
3059
3060 @node Stream Buffering
3061 @section Stream Buffering
3062
3063 @cindex buffering of streams
3064 Characters that are written to a stream are normally accumulated and
3065 transmitted asynchronously to the file in a block, instead of appearing
3066 as soon as they are output by the application program.  Similarly,
3067 streams often retrieve input from the host environment in blocks rather
3068 than on a character-by-character basis.  This is called @dfn{buffering}.
3069
3070 If you are writing programs that do interactive input and output using
3071 streams, you need to understand how buffering works when you design the
3072 user interface to your program.  Otherwise, you might find that output
3073 (such as progress or prompt messages) doesn't appear when you intended
3074 it to, or other unexpected behavior.
3075
3076 This section deals only with controlling when characters are transmitted
3077 between the stream and the file or device, and @emph{not} with how
3078 things like echoing, flow control, and the like are handled on specific
3079 classes of devices.  For information on common control operations on
3080 terminal devices, see @ref{Low-Level Terminal Interface}.
3081
3082 You can bypass the stream buffering facilities altogether by using the
3083 low-level input and output functions that operate on file descriptors
3084 instead.  @xref{Low-Level I/O}.
3085
3086 @menu
3087 * Buffering Concepts::          Terminology is defined here.
3088 * Flushing Buffers::            How to ensure that output buffers are flushed.
3089 * Controlling Buffering::       How to specify what kind of buffering to use.
3090 @end menu
3091
3092 @node Buffering Concepts
3093 @subsection Buffering Concepts
3094
3095 There are three different kinds of buffering strategies:
3096
3097 @itemize @bullet
3098 @item
3099 Characters written to or read from an @dfn{unbuffered} stream are
3100 transmitted individually to or from the file as soon as possible.
3101 @cindex unbuffered stream
3102
3103 @item
3104 Characters written to a @dfn{line buffered} stream are transmitted to
3105 the file in blocks when a newline character is encountered.
3106 @cindex line buffered stream
3107
3108 @item
3109 Characters written to or read from a @dfn{fully buffered} stream are
3110 transmitted to or from the file in blocks of arbitrary size.
3111 @cindex fully buffered stream
3112 @end itemize
3113
3114 Newly opened streams are normally fully buffered, with one exception: a
3115 stream connected to an interactive device such as a terminal is
3116 initially line buffered.  @xref{Controlling Buffering}, for information
3117 on how to select a different kind of buffering.  Usually the automatic
3118 selection gives you the most convenient kind of buffering for the file
3119 or device you open.
3120
3121 The use of line buffering for interactive devices implies that output
3122 messages ending in a newline will appear immediately---which is usually
3123 what you want.  Output that doesn't end in a newline might or might not
3124 show up immediately, so if you want them to appear immediately, you
3125 should flush buffered output explicitly with @code{fflush}, as described
3126 in @ref{Flushing Buffers}.
3127
3128 @node Flushing Buffers
3129 @subsection Flushing Buffers
3130
3131 @cindex flushing a stream
3132 @dfn{Flushing} output on a buffered stream means transmitting all
3133 accumulated characters to the file.  There are many circumstances when
3134 buffered output on a stream is flushed automatically:
3135
3136 @itemize @bullet
3137 @item
3138 When you try to do output and the output buffer is full.
3139
3140 @item
3141 When the stream is closed.  @xref{Closing Streams}.
3142
3143 @item
3144 When the program terminates by calling @code{exit}.
3145 @xref{Normal Termination}.
3146
3147 @item
3148 When a newline is written, if the stream is line buffered.
3149
3150 @item
3151 Whenever an input operation on @emph{any} stream actually reads data
3152 from its file.
3153 @end itemize
3154
3155 If you want to flush the buffered output at another time, call
3156 @code{fflush}, which is declared in the header file @file{stdio.h}.
3157 @pindex stdio.h
3158
3159 @comment stdio.h
3160 @comment ANSI
3161 @deftypefun int fflush (FILE *@var{stream})
3162 This function causes any buffered output on @var{stream} to be delivered
3163 to the file.  If @var{stream} is a null pointer, then
3164 @code{fflush} causes buffered output on @emph{all} open output streams
3165 to be flushed.
3166
3167 This function returns @code{EOF} if a write error occurs, or zero
3168 otherwise.
3169 @end deftypefun
3170
3171 @strong{Compatibility Note:} Some brain-damaged operating systems have
3172 been known to be so thoroughly fixated on line-oriented input and output
3173 that flushing a line buffered stream causes a newline to be written!
3174 Fortunately, this ``feature'' seems to be becoming less common.  You do
3175 not need to worry about this in the GNU system.
3176
3177
3178 @node Controlling Buffering
3179 @subsection Controlling Which Kind of Buffering
3180
3181 After opening a stream (but before any other operations have been
3182 performed on it), you can explicitly specify what kind of buffering you
3183 want it to have using the @code{setvbuf} function.
3184 @cindex buffering, controlling
3185
3186 The facilities listed in this section are declared in the header
3187 file @file{stdio.h}.
3188 @pindex stdio.h
3189
3190 @comment stdio.h
3191 @comment ANSI
3192 @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
3193 This function is used to specify that the stream @var{stream} should
3194 have the buffering mode @var{mode}, which can be either @code{_IOFBF}
3195 (for full buffering), @code{_IOLBF} (for line buffering), or
3196 @code{_IONBF} (for unbuffered input/output).
3197
3198 If you specify a null pointer as the @var{buf} argument, then @code{setvbuf}
3199 allocates a buffer itself using @code{malloc}.  This buffer will be freed
3200 when you close the stream.
3201
3202 Otherwise, @var{buf} should be a character array that can hold at least
3203 @var{size} characters.  You should not free the space for this array as
3204 long as the stream remains open and this array remains its buffer.  You
3205 should usually either allocate it statically, or @code{malloc}
3206 (@pxref{Unconstrained Allocation}) the buffer.  Using an automatic array
3207 is not a good idea unless you close the file before exiting the block
3208 that declares the array.
3209
3210 While the array remains a stream buffer, the stream I/O functions will
3211 use the buffer for their internal purposes.  You shouldn't try to access
3212 the values in the array directly while the stream is using it for
3213 buffering.
3214
3215 The @code{setvbuf} function returns zero on success, or a nonzero value
3216 if the value of @var{mode} is not valid or if the request could not
3217 be honored.
3218 @end deftypefun
3219
3220 @comment stdio.h
3221 @comment ANSI
3222 @deftypevr Macro int _IOFBF
3223 The value of this macro is an integer constant expression that can be
3224 used as the @var{mode} argument to the @code{setvbuf} function to
3225 specify that the stream should be fully buffered.
3226 @end deftypevr
3227
3228 @comment stdio.h
3229 @comment ANSI
3230 @deftypevr Macro int _IOLBF
3231 The value of this macro is an integer constant expression that can be
3232 used as the @var{mode} argument to the @code{setvbuf} function to
3233 specify that the stream should be line buffered.
3234 @end deftypevr
3235
3236 @comment stdio.h
3237 @comment ANSI
3238 @deftypevr Macro int _IONBF
3239 The value of this macro is an integer constant expression that can be
3240 used as the @var{mode} argument to the @code{setvbuf} function to
3241 specify that the stream should be unbuffered.
3242 @end deftypevr
3243
3244 @comment stdio.h
3245 @comment ANSI
3246 @deftypevr Macro int BUFSIZ
3247 The value of this macro is an integer constant expression that is good
3248 to use for the @var{size} argument to @code{setvbuf}.  This value is
3249 guaranteed to be at least @code{256}.
3250
3251 The value of @code{BUFSIZ} is chosen on each system so as to make stream
3252 I/O efficient.  So it is a good idea to use @code{BUFSIZ} as the size
3253 for the buffer when you call @code{setvbuf}.
3254
3255 Actually, you can get an even better value to use for the buffer size
3256 by means of the @code{fstat} system call: it is found in the
3257 @code{st_blksize} field of the file attributes.  @xref{Attribute Meanings}.
3258
3259 Sometimes people also use @code{BUFSIZ} as the allocation size of
3260 buffers used for related purposes, such as strings used to receive a
3261 line of input with @code{fgets} (@pxref{Character Input}).  There is no
3262 particular reason to use @code{BUFSIZ} for this instead of any other
3263 integer, except that it might lead to doing I/O in chunks of an
3264 efficient size.
3265 @end deftypevr
3266
3267 @comment stdio.h
3268 @comment ANSI
3269 @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
3270 If @var{buf} is a null pointer, the effect of this function is
3271 equivalent to calling @code{setvbuf} with a @var{mode} argument of
3272 @code{_IONBF}.  Otherwise, it is equivalent to calling @code{setvbuf}
3273 with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size}
3274 argument of @code{BUFSIZ}.
3275
3276 The @code{setbuf} function is provided for compatibility with old code;
3277 use @code{setvbuf} in all new programs.
3278 @end deftypefun
3279
3280 @comment stdio.h
3281 @comment BSD
3282 @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
3283 If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
3284 Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
3285 buffer.  The @var{size} argument specifies the length of @var{buf}.
3286
3287 This function is provided for compatibility with old BSD code.  Use
3288 @code{setvbuf} instead.
3289 @end deftypefun
3290
3291 @comment stdio.h
3292 @comment BSD
3293 @deftypefun void setlinebuf (FILE *@var{stream})
3294 This function makes @var{stream} be line buffered, and allocates the
3295 buffer for you.
3296
3297 This function is provided for compatibility with old BSD code.  Use
3298 @code{setvbuf} instead.
3299 @end deftypefun
3300
3301 @node Other Kinds of Streams
3302 @section Other Kinds of Streams
3303
3304 The GNU library provides ways for you to define additional kinds of
3305 streams that do not necessarily correspond to an open file.
3306
3307 One such type of stream takes input from or writes output to a string.
3308 These kinds of streams are used internally to implement the
3309 @code{sprintf} and @code{sscanf} functions.  You can also create such a
3310 stream explicitly, using the functions described in @ref{String Streams}.
3311
3312 More generally, you can define streams that do input/output to arbitrary
3313 objects using functions supplied by your program.  This protocol is
3314 discussed in @ref{Custom Streams}.
3315
3316 @strong{Portability Note:} The facilities described in this section are
3317 specific to GNU.  Other systems or C implementations might or might not
3318 provide equivalent functionality.
3319
3320 @menu
3321 * String Streams::              Streams that get data from or put data in
3322                                  a string or memory buffer.
3323 * Obstack Streams::             Streams that store data in an obstack.
3324 * Custom Streams::              Defining your own streams with an arbitrary
3325                                  input data source and/or output data sink.
3326 @end menu
3327
3328 @node String Streams
3329 @subsection String Streams
3330
3331 @cindex stream, for I/O to a string
3332 @cindex string stream
3333 The @code{fmemopen} and @code{open_memstream} functions allow you to do
3334 I/O to a string or memory buffer.  These facilities are declared in
3335 @file{stdio.h}.
3336 @pindex stdio.h
3337
3338 @comment stdio.h
3339 @comment GNU
3340 @deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
3341 This function opens a stream that allows the access specified by the
3342 @var{opentype} argument, that reads from or writes to the buffer specified
3343 by the argument @var{buf}.  This array must be at least @var{size} bytes long.
3344
3345 If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
3346 dynamically allocates (as with @code{malloc}; @pxref{Unconstrained
3347 Allocation}) an array @var{size} bytes long.  This is really only useful
3348 if you are going to write things to the buffer and then read them back
3349 in again, because you have no way of actually getting a pointer to the
3350 buffer (for this, try @code{open_memstream}, below).  The buffer is
3351 freed when the stream is open.
3352
3353 The argument @var{opentype} is the same as in @code{fopen}
3354 (@xref{Opening Streams}).  If the @var{opentype} specifies
3355 append mode, then the initial file position is set to the first null
3356 character in the buffer.  Otherwise the initial file position is at the
3357 beginning of the buffer.
3358
3359 When a stream open for writing is flushed or closed, a null character
3360 (zero byte) is written at the end of the buffer if it fits.  You
3361 should add an extra byte to the @var{size} argument to account for this.
3362 Attempts to write more than @var{size} bytes to the buffer result
3363 in an error.
3364
3365 For a stream open for reading, null characters (zero bytes) in the
3366 buffer do not count as ``end of file''.  Read operations indicate end of
3367 file only when the file position advances past @var{size} bytes.  So, if
3368 you want to read characters from a null-terminated string, you should
3369 supply the length of the string as the @var{size} argument.
3370 @end deftypefun
3371
3372 Here is an example of using @code{fmemopen} to create a stream for
3373 reading from a string:
3374
3375 @smallexample
3376 @include memopen.c.texi
3377 @end smallexample
3378
3379 This program produces the following output:
3380
3381 @smallexample
3382 Got f
3383 Got o
3384 Got o
3385 Got b
3386 Got a
3387 Got r
3388 @end smallexample
3389
3390 @comment stdio.h
3391 @comment GNU
3392 @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
3393 This function opens a stream for writing to a buffer.  The buffer is
3394 allocated dynamically (as with @code{malloc}; @pxref{Unconstrained
3395 Allocation}) and grown as necessary.
3396
3397 When the stream is closed with @code{fclose} or flushed with
3398 @code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
3399 contain the pointer to the buffer and its size.  The values thus stored
3400 remain valid only as long as no further output on the stream takes
3401 place.  If you do more output, you must flush the stream again to store
3402 new values before you use them again.
3403
3404 A null character is written at the end of the buffer.  This null character
3405 is @emph{not} included in the size value stored at @var{sizeloc}.
3406
3407 You can move the stream's file position with @code{fseek} (@pxref{File
3408 Positioning}).  Moving the file position past the end of the data
3409 already written fills the intervening space with zeroes.
3410 @end deftypefun
3411
3412 Here is an example of using @code{open_memstream}:
3413
3414 @smallexample
3415 @include memstrm.c.texi
3416 @end smallexample
3417
3418 This program produces the following output:
3419
3420 @smallexample
3421 buf = `hello', size = 5
3422 buf = `hello, world', size = 12
3423 @end smallexample
3424
3425 @c @group  Invalid outside @example.
3426 @node Obstack Streams
3427 @subsection Obstack Streams
3428
3429 You can open an output stream that puts it data in an obstack.
3430 @xref{Obstacks}.
3431
3432 @comment stdio.h
3433 @comment GNU
3434 @deftypefun {FILE *} open_obstack_stream (struct obstack *@var{obstack})
3435 This function opens a stream for writing data into the obstack @var{obstack}.
3436 This starts an object in the obstack and makes it grow as data is
3437 written (@pxref{Growing Objects}).
3438 @c @end group  Doubly invalid because not nested right.
3439
3440 Calling @code{fflush} on this stream updates the current size of the
3441 object to match the amount of data that has been written.  After a call
3442 to @code{fflush}, you can examine the object temporarily.
3443
3444 You can move the file position of an obstack stream with @code{fseek}
3445 (@pxref{File Positioning}).  Moving the file position past the end of
3446 the data written fills the intervening space with zeros.
3447
3448 To make the object permanent, update the obstack with @code{fflush}, and
3449 then use @code{obstack_finish} to finalize the object and get its address.
3450 The following write to the stream starts a new object in the obstack,
3451 and later writes add to that object until you do another @code{fflush}
3452 and @code{obstack_finish}.
3453
3454 But how do you find out how long the object is?  You can get the length
3455 in bytes by calling @code{obstack_object_size} (@pxref{Status of an
3456 Obstack}), or you can null-terminate the object like this:
3457
3458 @smallexample
3459 obstack_1grow (@var{obstack}, 0);
3460 @end smallexample
3461
3462 Whichever one you do, you must do it @emph{before} calling
3463 @code{obstack_finish}.  (You can do both if you wish.)
3464 @end deftypefun
3465
3466 Here is a sample function that uses @code{open_obstack_stream}:
3467
3468 @smallexample
3469 char *
3470 make_message_string (const char *a, int b)
3471 @{
3472   FILE *stream = open_obstack_stream (&message_obstack);
3473   output_task (stream);
3474   fprintf (stream, ": ");
3475   fprintf (stream, a, b);
3476   fprintf (stream, "\n");
3477   fclose (stream);
3478   obstack_1grow (&message_obstack, 0);
3479   return obstack_finish (&message_obstack);
3480 @}
3481 @end smallexample
3482
3483 @node Custom Streams
3484 @subsection Programming Your Own Custom Streams
3485 @cindex custom streams
3486 @cindex programming your own streams
3487
3488 This section describes how you can make a stream that gets input from an
3489 arbitrary data source or writes output to an arbitrary data sink
3490 programmed by you.  We call these @dfn{custom streams}.
3491
3492 @c !!! this does not talk at all about the higher-level hooks
3493
3494 @menu
3495 * Streams and Cookies::         The @dfn{cookie} records where to fetch or
3496                                  store data that is read or written.
3497 * Hook Functions::              How you should define the four @dfn{hook
3498                                  functions} that a custom stream needs.
3499 @end menu
3500
3501 @node Streams and Cookies
3502 @subsubsection Custom Streams and Cookies
3503 @cindex cookie, for custom stream
3504
3505 Inside every custom stream is a special object called the @dfn{cookie}.
3506 This is an object supplied by you which records where to fetch or store
3507 the data read or written.  It is up to you to define a data type to use
3508 for the cookie.  The stream functions in the library never refer
3509 directly to its contents, and they don't even know what the type is;
3510 they record its address with type @code{void *}.
3511
3512 To implement a custom stream, you must specify @emph{how} to fetch or
3513 store the data in the specified place.  You do this by defining
3514 @dfn{hook functions} to read, write, change ``file position'', and close
3515 the stream.  All four of these functions will be passed the stream's
3516 cookie so they can tell where to fetch or store the data.  The library
3517 functions don't know what's inside the cookie, but your functions will
3518 know.
3519
3520 When you create a custom stream, you must specify the cookie pointer,
3521 and also the four hook functions stored in a structure of type
3522 @code{cookie_io_functions_t}.
3523
3524 These facilities are declared in @file{stdio.h}.
3525 @pindex stdio.h
3526
3527 @comment stdio.h
3528 @comment GNU
3529 @deftp {Data Type} {cookie_io_functions_t}
3530 This is a structure type that holds the functions that define the
3531 communications protocol between the stream and its cookie.  It has
3532 the following members:
3533
3534 @table @code
3535 @item cookie_read_function_t *read
3536 This is the function that reads data from the cookie.  If the value is a
3537 null pointer instead of a function, then read operations on ths stream
3538 always return @code{EOF}.
3539
3540 @item cookie_write_function_t *write
3541 This is the function that writes data to the cookie.  If the value is a
3542 null pointer instead of a function, then data written to the stream is
3543 discarded.
3544
3545 @item cookie_seek_function_t *seek
3546 This is the function that performs the equivalent of file positioning on
3547 the cookie.  If the value is a null pointer instead of a function, calls
3548 to @code{fseek} on this stream can only seek to locations within the
3549 buffer; any attempt to seek outside the buffer will return an
3550 @code{ESPIPE} error.
3551
3552 @item cookie_close_function_t *close
3553 This function performs any appropriate cleanup on the cookie when
3554 closing the stream.  If the value is a null pointer instead of a
3555 function, nothing special is done to close the cookie when the stream is
3556 closed.
3557 @end table
3558 @end deftp
3559
3560 @comment stdio.h
3561 @comment GNU
3562 @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions})
3563 This function actually creates the stream for communicating with the
3564 @var{cookie} using the functions in the @var{io-functions} argument.
3565 The @var{opentype} argument is interpreted as for @code{fopen};
3566 see @ref{Opening Streams}.  (But note that the ``truncate on
3567 open'' option is ignored.)  The new stream is fully buffered.
3568
3569 The @code{fopencookie} function returns the newly created stream, or a null
3570 pointer in case of an error.
3571 @end deftypefun
3572
3573 @node Hook Functions
3574 @subsubsection Custom Stream Hook Functions
3575 @cindex hook functions (of custom streams)
3576
3577 Here are more details on how you should define the four hook functions
3578 that a custom stream needs.
3579
3580 You should define the function to read data from the cookie as:
3581
3582 @smallexample
3583 ssize_t @var{reader} (void *@var{cookie}, void *@var{buffer}, size_t @var{size})
3584 @end smallexample
3585
3586 This is very similar to the @code{read} function; see @ref{I/O
3587 Primitives}.  Your function should transfer up to @var{size} bytes into
3588 the @var{buffer}, and return the number of bytes read, or zero to
3589 indicate end-of-file.  You can return a value of @code{-1} to indicate
3590 an error.
3591
3592 You should define the function to write data to the cookie as:
3593
3594 @smallexample
3595 ssize_t @var{writer} (void *@var{cookie}, const void *@var{buffer}, size_t @var{size})
3596 @end smallexample
3597
3598 This is very similar to the @code{write} function; see @ref{I/O
3599 Primitives}.  Your function should transfer up to @var{size} bytes from
3600 the buffer, and return the number of bytes written.  You can return a
3601 value of @code{-1} to indicate an error.
3602
3603 You should define the function to perform seek operations on the cookie
3604 as:
3605
3606 @smallexample
3607 int @var{seeker} (void *@var{cookie}, fpos_t *@var{position}, int @var{whence})
3608 @end smallexample
3609
3610 For this function, the @var{position} and @var{whence} arguments are
3611 interpreted as for @code{fgetpos}; see @ref{Portable Positioning}.  In
3612 the GNU library, @code{fpos_t} is equivalent to @code{off_t} or
3613 @code{long int}, and simply represents the number of bytes from the
3614 beginning of the file.
3615
3616 After doing the seek operation, your function should store the resulting
3617 file position relative to the beginning of the file in @var{position}.
3618 Your function should return a value of @code{0} on success and @code{-1}
3619 to indicate an error.
3620
3621 You should define the function to do cleanup operations on the cookie
3622 appropriate for closing the stream as:
3623
3624 @smallexample
3625 int @var{cleaner} (void *@var{cookie})
3626 @end smallexample
3627
3628 Your function should return @code{-1} to indicate an error, and @code{0}
3629 otherwise.
3630
3631 @comment stdio.h
3632 @comment GNU
3633 @deftp {Data Type} cookie_read_function
3634 This is the data type that the read function for a custom stream should have.
3635 If you declare the function as shown above, this is the type it will have.
3636 @end deftp
3637
3638 @comment stdio.h
3639 @comment GNU
3640 @deftp {Data Type} cookie_write_function
3641 The data type of the write function for a custom stream.
3642 @end deftp
3643
3644 @comment stdio.h
3645 @comment GNU
3646 @deftp {Data Type} cookie_seek_function
3647 The data type of the seek function for a custom stream.
3648 @end deftp
3649
3650 @comment stdio.h
3651 @comment GNU
3652 @deftp {Data Type} cookie_close_function
3653 The data type of the close function for a custom stream.