(_hurd_sig_post): __sig_post renamed to __msg_sig_post.
[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{0}
1061 Pad the field with zeros instead of spaces.  The zeros are placed after
1062 any indication of sign or base.  This flag is ignored if the @samp{-}
1063 flag is also specified, or if a precision is specified.
1064 @end table
1065
1066 If a precision is supplied, it specifies the minimum number of digits to
1067 appear; leading zeros are produced if necessary.  If you don't specify a
1068 precision, the number is printed with as many digits as it needs.  If
1069 you convert a value of zero with an explicit precision of zero, then no
1070 characters at all are produced.
1071
1072 Without a type modifier, the corresponding argument is treated as an
1073 @code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
1074 @code{unsigned int} (for the unsigned conversions @samp{%o}, @samp{%u},
1075 @samp{%x}, and @samp{%X}).  Recall that since @code{printf} and friends
1076 are variadic, any @code{char} and @code{short} arguments are
1077 automatically converted to @code{int} by the default argument
1078 promotions.  For arguments of other integer types, you can use these
1079 modifiers:
1080
1081 @table @samp
1082 @item h
1083 Specifies that the argument is a @code{short int} or @code{unsigned
1084 short int}, as appropriate.  A @code{short} argument is converted to an
1085 @code{int} or @code{unsigned int} by the default argument promotions
1086 anyway, but the @samp{h} modifier says to convert it back to a
1087 @code{short} again.
1088
1089 @item l
1090 Specifies that the argument is a @code{long int} or @code{unsigned long
1091 int}, as appropriate.  Two @samp{l} characters is like the @samp{L}
1092 modifier, below.
1093
1094 @item L
1095 @itemx ll
1096 @itemx q
1097 Specifies that the argument is a @code{long long int}.  (This type is
1098 an extension supported by the GNU C compiler.  On systems that don't
1099 support extra-long integers, this is the same as @code{long int}.)
1100
1101 The @samp{q} modifier is another name for the same thing, which comes
1102 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
1103 @code{int}.
1104
1105 @item Z
1106 Specifies that the argument is a @code{size_t}.  This is a GNU extension.
1107 @end table
1108
1109 Here is an example.  Using the template string:
1110
1111 @smallexample
1112 "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
1113 @end smallexample
1114
1115 @noindent
1116 to print numbers using the different options for the @samp{%d}
1117 conversion gives results like:
1118
1119 @smallexample
1120 |    0|0    |   +0|+0   |    0|00000|     |   00|0|
1121 |    1|1    |   +1|+1   |    1|00001|    1|   01|1|
1122 |   -1|-1   |   -1|-1   |   -1|-0001|   -1|  -01|-1|
1123 |100000|100000|+100000| 100000|100000|100000|100000|100000|
1124 @end smallexample
1125
1126 In particular, notice what happens in the last case where the number
1127 is too large to fit in the minimum field width specified.
1128
1129 Here are some more examples showing how unsigned integers print under
1130 various format options, using the template string:
1131
1132 @smallexample
1133 "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
1134 @end smallexample
1135
1136 @smallexample
1137 |    0|    0|    0|    0|    0|  0x0|  0X0|0x00000000|
1138 |    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
1139 |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
1140 @end smallexample
1141
1142
1143 @node Floating-Point Conversions
1144 @subsection Floating-Point Conversions
1145
1146 This section discusses the conversion specifications for floating-point
1147 numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G}
1148 conversions.
1149
1150 The @samp{%f} conversion prints its argument in fixed-point notation,
1151 producing output of the form
1152 @w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
1153 where the number of digits following the decimal point is controlled
1154 by the precision you specify.
1155
1156 The @samp{%e} conversion prints its argument in exponential notation,
1157 producing output of the form
1158 @w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}.
1159 Again, the number of digits following the decimal point is controlled by
1160 the precision.  The exponent always contains at least two digits.  The
1161 @samp{%E} conversion is similar but the exponent is marked with the letter
1162 @samp{E} instead of @samp{e}.
1163
1164 The @samp{%g} and @samp{%G} conversions print the argument in the style
1165 of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
1166 than -4 or greater than or equal to the precision; otherwise they use the
1167 @samp{%f} style.  Trailing zeros are removed from the fractional portion
1168 of the result and a decimal-point character appears only if it is
1169 followed by a digit.
1170
1171 The following flags can be used to modify the behavior:
1172
1173 @comment We use @asis instead of @samp so we can have ` ' as an item.
1174 @table @asis
1175 @item @samp{-}
1176 Left-justify the result in the field.  Normally the result is
1177 right-justified.
1178
1179 @item @samp{+}
1180 Always include a plus or minus sign in the result.
1181
1182 @item @samp{ }
1183 If the result doesn't start with a plus or minus sign, prefix it with a
1184 space instead.  Since the @samp{+} flag ensures that the result includes
1185 a sign, this flag is ignored if you supply both of them.
1186
1187 @item @samp{#}
1188 Specifies that the result should always include a decimal point, even
1189 if no digits follow it.  For the @samp{%g} and @samp{%G} conversions,
1190 this also forces trailing zeros after the decimal point to be left
1191 in place where they would otherwise be removed.
1192
1193 @item @samp{0}
1194 Pad the field with zeros instead of spaces; the zeros are placed
1195 after any sign.  This flag is ignored if the @samp{-} flag is also
1196 specified.
1197 @end table
1198
1199 The precision specifies how many digits follow the decimal-point
1200 character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions.  For
1201 these conversions, the default precision is @code{6}.  If the precision
1202 is explicitly @code{0}, this suppresses the decimal point character
1203 entirely.  For the @samp{%g} and @samp{%G} conversions, the precision
1204 specifies how many significant digits to print.  Significant digits are
1205 the first digit before the decimal point, and all the digits after it.
1206 If the precision @code{0} or not specified for @samp{%g} or @samp{%G},
1207 it is treated like a value of @code{1}.  If the value being printed
1208 cannot be expressed accurately in the specified number of digits, the
1209 value is rounded to the nearest number that fits.
1210
1211 Without a type modifier, the floating-point conversions use an argument
1212 of type @code{double}.  (By the default argument promotions, any
1213 @code{float} arguments are automatically converted to @code{double}.)
1214 The following type modifier is supported:
1215
1216 @table @samp
1217 @item L
1218 An uppercase @samp{L} specifies that the argument is a @code{long
1219 double}.
1220 @end table
1221
1222 Here are some examples showing how numbers print using the various
1223 floating-point conversions.  All of the numbers were printed using
1224 this template string:
1225
1226 @smallexample
1227 "|%12.4f|%12.4e|%12.4g|\n"
1228 @end smallexample
1229
1230 Here is the output:
1231
1232 @smallexample
1233 |      0.0000|  0.0000e+00|           0|
1234 |      1.0000|  1.0000e+00|           1|
1235 |     -1.0000| -1.0000e+00|          -1|
1236 |    100.0000|  1.0000e+02|         100|
1237 |   1000.0000|  1.0000e+03|        1000|
1238 |  10000.0000|  1.0000e+04|       1e+04|
1239 |  12345.0000|  1.2345e+04|   1.234e+04|
1240 | 100000.0000|  1.0000e+05|       1e+05|
1241 | 123456.0000|  1.2346e+05|   1.234e+05|
1242 @end smallexample
1243
1244 Notice how the @samp{%g} conversion drops trailing zeros.
1245
1246 @node Other Output Conversions
1247 @subsection Other Output Conversions
1248
1249 This section describes miscellaneous conversions for @code{printf}.
1250
1251 The @samp{%c} conversion prints a single character.  The @code{int}
1252 argument is first converted to an @code{unsigned char}.  The @samp{-}
1253 flag can be used to specify left-justification in the field, but no
1254 other flags are defined, and no precision or type modifier can be given.
1255 For example:
1256
1257 @smallexample
1258 printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
1259 @end smallexample
1260
1261 @noindent
1262 prints @samp{hello}.
1263
1264 The @samp{%s} conversion prints a string.  The corresponding argument
1265 must be of type @code{char *} (or @code{const char *}).  A precision can
1266 be specified to indicate the maximum number of characters to write;
1267 otherwise characters in the string up to but not including the
1268 terminating null character are written to the output stream.  The
1269 @samp{-} flag can be used to specify left-justification in the field,
1270 but no other flags or type modifiers are defined for this conversion.
1271 For example:
1272
1273 @smallexample
1274 printf ("%3s%-6s", "no", "where");
1275 @end smallexample
1276
1277 @noindent
1278 prints @samp{ nowhere }.
1279
1280 If you accidentally pass a null pointer as the argument for a @samp{%s}
1281 conversion, the GNU library prints it as @samp{(null)}.  We think this
1282 is more useful than crashing.  But it's not good practice to pass a null
1283 argument intentionally.
1284
1285 The @samp{%m} conversion prints the string corresponding to the error
1286 code in @code{errno}.  @xref{Error Messages}.  Thus:
1287
1288 @smallexample
1289 fprintf (stderr, "can't open `%s': %m\n", filename);
1290 @end smallexample
1291
1292 @noindent
1293 is equivalent to:
1294
1295 @smallexample
1296 fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
1297 @end smallexample
1298
1299 @noindent
1300 The @samp{%m} conversion is a GNU C library extension.
1301
1302 The @samp{%p} conversion prints a pointer value.  The corresponding
1303 argument must be of type @code{void *}.  In practice, you can use any
1304 type of pointer.
1305
1306 In the GNU system, non-null pointers are printed as unsigned integers,
1307 as if a @samp{%#x} conversion were used.  Null pointers print as
1308 @samp{(nil)}.  (Pointers might print differently in other systems.)
1309
1310 For example:
1311
1312 @smallexample
1313 printf ("%p", "testing");
1314 @end smallexample
1315
1316 @noindent
1317 prints @samp{0x} followed by a hexadecimal number---the address of the
1318 string constant @code{"testing"}.  It does not print the word
1319 @samp{testing}.
1320
1321 You can supply the @samp{-} flag with the @samp{%p} conversion to
1322 specify left-justification, but no other flags, precision, or type
1323 modifiers are defined.
1324
1325 The @samp{%n} conversion is unlike any of the other output conversions.
1326 It uses an argument which must be a pointer to an @code{int}, but
1327 instead of printing anything it stores the number of characters printed
1328 so far by this call at that location.  The @samp{h} and @samp{l} type
1329 modifiers are permitted to specify that the argument is of type
1330 @code{short int *} or @code{long int *} instead of @code{int *}, but no
1331 flags, field width, or precision are permitted.
1332
1333 For example,
1334
1335 @smallexample
1336 int nchar;
1337 printf ("%d %s%n\n", 3, "bears", &nchar);
1338 @end smallexample
1339
1340 @noindent
1341 prints:
1342
1343 @smallexample
1344 3 bears
1345 @end smallexample
1346
1347 @noindent
1348 and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven 
1349 characters.
1350
1351
1352 The @samp{%%} conversion prints a literal @samp{%} character.  This
1353 conversion doesn't use an argument, and no flags, field width,
1354 precision, or type modifiers are permitted.
1355
1356
1357 @node Formatted Output Functions
1358 @subsection Formatted Output Functions
1359
1360 This section describes how to call @code{printf} and related functions.
1361 Prototypes for these functions are in the header file @file{stdio.h}.
1362 Because these functions take a variable number of arguments, you
1363 @emph{must} declare prototypes for them before using them.  Of course,
1364 the easiest way to make sure you have all the right prototypes is to
1365 just include @file{stdio.h}.
1366 @pindex stdio.h
1367
1368 @comment stdio.h
1369 @comment ANSI
1370 @deftypefun int printf (const char *@var{template}, @dots{})
1371 The @code{printf} function prints the optional arguments under the
1372 control of the template string @var{template} to the stream
1373 @code{stdout}.  It returns the number of characters printed, or a
1374 negative value if there was an output error.
1375 @end deftypefun
1376
1377 @comment stdio.h
1378 @comment ANSI
1379 @deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
1380 This function is just like @code{printf}, except that the output is
1381 written to the stream @var{stream} instead of @code{stdout}.
1382 @end deftypefun
1383
1384 @comment stdio.h
1385 @comment ANSI
1386 @deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
1387 This is like @code{printf}, except that the output is stored in the character
1388 array @var{s} instead of written to a stream.  A null character is written
1389 to mark the end of the string.
1390
1391 The @code{sprintf} function returns the number of characters stored in
1392 the array @var{s}, not including the terminating null character.
1393
1394 The behavior of this function is undefined if copying takes place
1395 between objects that overlap---for example, if @var{s} is also given
1396 as an argument to be printed under control of the @samp{%s} conversion.
1397 @xref{Copying and Concatenation}.
1398
1399 @strong{Warning:} The @code{sprintf} function can be @strong{dangerous}
1400 because it can potentially output more characters than can fit in the
1401 allocation size of the string @var{s}.  Remember that the field width
1402 given in a conversion specification is only a @emph{minimum} value.
1403
1404 To avoid this problem, you can use @code{snprintf} or @code{asprintf},
1405 described below.
1406 @end deftypefun
1407
1408 @comment stdio.h
1409 @comment GNU
1410 @deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{})
1411 The @code{snprintf} function is similar to @code{sprintf}, except that
1412 the @var{size} argument specifies the maximum number of characters to
1413 produce.  The trailing null character is counted towards this limit, so
1414 you should allocate at least @var{size} characters for the string @var{s}.
1415
1416 The return value is the number of characters stored, not including the
1417 terminating null.  If this value equals @code{@var{size} - 1}, then
1418 there was not enough space in @var{s} for all the output.  You should
1419 try again with a bigger output string.  Here is an example of doing
1420 this:
1421
1422 @smallexample
1423 @group
1424 /* @r{Construct a message describing the value of a variable}
1425    @r{whose name is @var{name} and whose value is @var{value}.} */
1426 char *
1427 make_message (char *name, char *value)
1428 @{
1429   /* @r{Guess we need no more than 100 chars of space.} */
1430   int size = 100;
1431   char *buffer = (char *) xmalloc (size);
1432 @end group
1433 @group
1434   while (1)
1435     @{
1436       /* @r{Try to print in the allocated space.} */
1437       int nchars = snprintf (buffer, size,
1438                              "value of %s is %s",
1439                              name, value);
1440       /* @r{If that worked, return the string.} */
1441       if (nchars < size)
1442         return buffer;
1443       /* @r{Else try again with twice as much space.} */
1444       size *= 2;
1445       buffer = (char *) xrealloc (size, buffer);
1446     @}
1447 @}
1448 @end group
1449 @end smallexample
1450
1451 In practice, it is often easier just to use @code{asprintf}, below.
1452 @end deftypefun
1453
1454 @node Dynamic Output
1455 @subsection Dynamically Allocating Formatted Output
1456
1457 The functions in this section do formatted output and place the results
1458 in dynamically allocated memory.
1459
1460 @comment stdio.h
1461 @comment GNU
1462 @deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
1463 This function is similar to @code{sprintf}, except that it dynamically
1464 allocates a string (as with @code{malloc}; @pxref{Unconstrained
1465 Allocation}) to hold the output, instead of putting the output in a
1466 buffer you allocate in advance.  The @var{ptr} argument should be the
1467 address of a @code{char *} object, and @code{asprintf} stores a pointer
1468 to the newly allocated string at that location.
1469
1470 Here is how to use @code{asprintf} to get the same result as the
1471 @code{snprintf} example, but more easily:
1472
1473 @smallexample
1474 /* @r{Construct a message describing the value of a variable}
1475    @r{whose name is @var{name} and whose value is @var{value}.} */
1476 char *
1477 make_message (char *name, char *value)
1478 @{
1479   char *result;
1480   asprintf (&result, "value of %s is %s", name, value);
1481   return result;
1482 @}
1483 @end smallexample
1484 @end deftypefun
1485
1486 @comment stdio.h
1487 @comment GNU
1488 @deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
1489 This function is similar to @code{asprintf}, except that it uses the
1490 obstack @var{obstack} to allocate the space.  @xref{Obstacks}.
1491
1492 The characters are written onto the end of the current object.
1493 To get at them, you must finish the object with @code{obstack_finish}
1494 (@pxref{Growing Objects}).@refill
1495 @end deftypefun
1496
1497 @node Variable Arguments Output
1498 @subsection Variable Arguments Output Functions
1499
1500 The functions @code{vprintf} and friends are provided so that you can
1501 define your own variadic @code{printf}-like functions that make use of
1502 the same internals as the built-in formatted output functions.
1503
1504 The most natural way to define such functions would be to use a language
1505 construct to say, ``Call @code{printf} and pass this template plus all
1506 of my arguments after the first five.''  But there is no way to do this
1507 in C, and it would be hard to provide a way, since at the C language
1508 level there is no way to tell how many arguments your function received.
1509
1510 Since that method is impossible, we provide alternative functions, the
1511 @code{vprintf} series, which lets you pass a @code{va_list} to describe
1512 ``all of my arguments after the first five.''
1513
1514 When it is sufficient to define a macro rather than a real function, 
1515 the GNU C compiler provides a way to do this much more easily with macros.
1516 For example:
1517
1518 @smallexample
1519 #define myprintf(a, b, c, d, e, rest...) printf (mytemplate , ## rest...)
1520 @end smallexample
1521
1522 @noindent
1523 @xref{Macro Varargs, , Macros with Variable Numbers of Arguments,
1524 gcc.info, Using GNU CC}, for details.  But this is limited to macros,
1525 and does not apply to real functions at all.
1526
1527 Before calling @code{vprintf} or the other functions listed in this
1528 section, you @emph{must} call @code{va_start} (@pxref{Variadic
1529 Functions}) to initialize a pointer to the variable arguments.  Then you
1530 can call @code{va_arg} to fetch the arguments that you want to handle
1531 yourself.  This advances the pointer past those arguments.
1532
1533 Once your @code{va_list} pointer is pointing at the argument of your
1534 choice, you are ready to call @code{vprintf}.  That argument and all
1535 subsequent arguments that were passed to your function are used by
1536 @code{vprintf} along with the template that you specified separately.
1537
1538 In some other systems, the @code{va_list} pointer may become invalid
1539 after the call to @code{vprintf}, so you must not use @code{va_arg}
1540 after you call @code{vprintf}.  Instead, you should call @code{va_end}
1541 to retire the pointer from service.  However, you can safely call
1542 @code{va_start} on another pointer variable and begin fetching the
1543 arguments again through that pointer.  Calling @code{vprintf} does not
1544 destroy the argument list of your function, merely the particular
1545 pointer that you passed to it.
1546
1547 GNU C does not have such restrictions.  You can safely continue to fetch
1548 arguments from a @code{va_list} pointer after passing it to
1549 @code{vprintf}, and @code{va_end} is a no-op.  (Note, however, that
1550 subsequent @code{va_arg} calls will fetch the same arguments which
1551 @code{vprintf} previously used.)
1552
1553 Prototypes for these functions are declared in @file{stdio.h}.
1554 @pindex stdio.h
1555
1556 @comment stdio.h
1557 @comment ANSI
1558 @deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
1559 This function is similar to @code{printf} except that, instead of taking
1560 a variable number of arguments directly, it takes an argument list
1561 pointer @var{ap}.
1562 @end deftypefun
1563
1564 @comment stdio.h
1565 @comment ANSI
1566 @deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
1567 This is the equivalent of @code{fprintf} with the variable argument list
1568 specified directly as for @code{vprintf}.
1569 @end deftypefun
1570
1571 @comment stdio.h
1572 @comment ANSI
1573 @deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
1574 This is the equivalent of @code{sprintf} with the variable argument list
1575 specified directly as for @code{vprintf}.
1576 @end deftypefun
1577
1578 @comment stdio.h
1579 @comment GNU
1580 @deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
1581 This is the equivalent of @code{snprintf} with the variable argument list
1582 specified directly as for @code{vprintf}.
1583 @end deftypefun
1584
1585 @comment stdio.h
1586 @comment GNU
1587 @deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
1588 The @code{vasprintf} function is the equivalent of @code{asprintf} with the
1589 variable argument list specified directly as for @code{vprintf}.
1590 @end deftypefun
1591
1592 @comment stdio.h
1593 @comment GNU
1594 @deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
1595 The @code{obstack_vprintf} function is the equivalent of
1596 @code{obstack_printf} with the variable argument list specified directly
1597 as for @code{vprintf}.@refill
1598 @end deftypefun
1599
1600 Here's an example showing how you might use @code{vfprintf}.  This is a
1601 function that prints error messages to the stream @code{stderr}, along
1602 with a prefix indicating the name of the program
1603 (@pxref{Error Messages}, for a description of 
1604 @code{program_invocation_short_name}).
1605
1606 @smallexample
1607 @group
1608 #include <stdio.h>
1609 #include <stdarg.h>
1610
1611 void
1612 eprintf (const char *template, ...)
1613 @{
1614   va_list ap;
1615   extern char *program_invocation_short_name;
1616
1617   fprintf (stderr, "%s: ", program_invocation_short_name);
1618   va_start (ap, count);
1619   vfprintf (stderr, template, ap);
1620   va_end (ap);
1621 @}
1622 @end group
1623 @end smallexample
1624
1625 @noindent
1626 You could call @code{eprintf} like this:
1627
1628 @smallexample
1629 eprintf ("file `%s' does not exist\n", filename);
1630 @end smallexample
1631
1632 In GNU C, there is a special construct you can use to let the compiler
1633 know that a function uses a @code{printf}-style format string.  Then it
1634 can check the number and types of arguments in each call to the
1635 function, and warn you when they do not match the format string.
1636 For example, take this declaration of @code{eprintf}:
1637
1638 @smallexample
1639 void eprintf (const char *template, ...)
1640         __attribute__ ((format (printf, 1, 2)));
1641 @end smallexample
1642
1643 @noindent
1644 This tells the compiler that @code{eprintf} uses a format string like
1645 @code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input});
1646 the format string appears as the first argument;
1647 and the arguments to satisfy the format begin with the second.
1648 @xref{Function Attributes, , Declaring Attributes of Functions,
1649 gcc.info, Using GNU CC}, for more information.
1650
1651 @node Parsing a Template String
1652 @subsection Parsing a Template String
1653 @cindex parsing a template string
1654
1655 You can use the function @code{parse_printf_format} to obtain
1656 information about the number and types of arguments that are expected by
1657 a given template string.  This function permits interpreters that
1658 provide interfaces to @code{printf} to avoid passing along invalid
1659 arguments from the user's program, which could cause a crash.
1660
1661 All the symbols described in this section are declared in the header
1662 file @file{printf.h}.
1663
1664 @comment printf.h
1665 @comment GNU
1666 @deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
1667 This function returns information about the number and types of
1668 arguments expected by the @code{printf} template string @var{template}.
1669 The information is stored in the array @var{argtypes}; each element of
1670 this array describes one argument.  This information is encoded using
1671 the various @samp{PA_} macros, listed below.
1672
1673 The @var{n} argument specifies the number of elements in the array
1674 @var{argtypes}.  This is the most elements that
1675 @code{parse_printf_format} will try to write.
1676
1677 @code{parse_printf_format} returns the total number of arguments required
1678 by @var{template}.  If this number is greater than @var{n}, then the
1679 information returned describes only the first @var{n} arguments.  If you
1680 want information about more than that many arguments, allocate a bigger
1681 array and call @code{parse_printf_format} again.
1682 @end deftypefun
1683
1684 The argument types are encoded as a combination of a basic type and
1685 modifier flag bits.
1686
1687 @comment printf.h
1688 @comment GNU
1689 @deftypevr Macro int PA_FLAG_MASK
1690 This macro is a bitmask for the type modifier flag bits.  You can write
1691 the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the
1692 flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to
1693 extract just the basic type code.
1694 @end deftypevr
1695
1696 Here are symbolic constants that represent the basic types; they stand
1697 for integer values.
1698
1699 @table @code
1700 @comment printf.h
1701 @comment GNU
1702 @item PA_INT
1703 @vindex PA_INT
1704 This specifies that the base type is @code{int}.
1705
1706 @comment printf.h
1707 @comment GNU
1708 @item PA_CHAR
1709 @vindex PA_CHAR
1710 This specifies that the base type is @code{int}, cast to @code{char}.
1711
1712 @comment printf.h
1713 @comment GNU
1714 @item PA_STRING
1715 @vindex PA_STRING
1716 This specifies that the base type is @code{char *}, a null-terminated string.
1717
1718 @comment printf.h
1719 @comment GNU
1720 @item PA_POINTER
1721 @vindex PA_POINTER
1722 This specifies that the base type is @code{void *}, an arbitrary pointer.
1723
1724 @comment printf.h
1725 @comment GNU
1726 @item PA_FLOAT
1727 @vindex PA_FLOAT
1728 This specifies that the base type is @code{float}.
1729
1730 @comment printf.h
1731 @comment GNU
1732 @item PA_DOUBLE
1733 @vindex PA_DOUBLE
1734 This specifies that the base type is @code{double}.
1735
1736 @comment printf.h
1737 @comment GNU
1738 @item PA_LAST
1739 @vindex PA_LAST
1740 You can define additional base types for your own programs as offsets
1741 from @code{PA_LAST}.  For example, if you have data types @samp{foo}
1742 and @samp{bar} with their own specialized @code{printf} conversions,
1743 you could define encodings for these types as:
1744
1745 @smallexample
1746 #define PA_FOO  PA_LAST
1747 #define PA_BAR  (PA_LAST + 1)
1748 @end smallexample
1749 @end table
1750
1751 Here are the flag bits that modify a basic type.  They are combined with
1752 the code for the basic type using inclusive-or.
1753
1754 @table @code
1755 @comment printf.h
1756 @comment GNU
1757 @item PA_FLAG_PTR
1758 @vindex PA_FLAG_PTR
1759 If this bit is set, it indicates that the encoded type is a pointer to
1760 the base type, rather than an immediate value.
1761 For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.
1762
1763 @comment printf.h
1764 @comment GNU
1765 @item PA_FLAG_SHORT
1766 @vindex PA_FLAG_SHORT
1767 If this bit is set, it indicates that the base type is modified with
1768 @code{short}.  (This corresponds to the @samp{h} type modifier.)
1769
1770 @comment printf.h
1771 @comment GNU
1772 @item PA_FLAG_LONG
1773 @vindex PA_FLAG_LONG
1774 If this bit is set, it indicates that the base type is modified with
1775 @code{long}.  (This corresponds to the @samp{l} type modifier.)
1776
1777 @comment printf.h
1778 @comment GNU
1779 @item PA_FLAG_LONG_LONG
1780 @vindex PA_FLAG_LONG_LONG
1781 If this bit is set, it indicates that the base type is modified with
1782 @code{long long}.  (This corresponds to the @samp{L} type modifier.)
1783
1784 @comment printf.h
1785 @comment GNU
1786 @item PA_FLAG_LONG_DOUBLE
1787 @vindex PA_FLAG_LONG_DOUBLE
1788 This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with
1789 a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
1790 @end table
1791
1792 @ifinfo
1793 For an example of using these facilitles, see @ref{Example of Parsing}.
1794 @end ifinfo
1795
1796 @node Example of Parsing
1797 @subsection Example of Parsing a Template String
1798
1799 Here is an example of decoding argument types for a format string.  We
1800 assume this is part of an interpreter which contains arguments of type
1801 @code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
1802 perhaps others which are not valid here).
1803
1804 @smallexample
1805 /* @r{Test whether the @var{nargs} specified objects}
1806    @r{in the vector @var{args} are valid}
1807    @r{for the format string @var{format}:}
1808    @r{if so, return 1.}
1809    @r{If not, return 0 after printing an error message.}  */
1810
1811 int
1812 validate_args (char *format, int nargs, OBJECT *args)
1813 @{
1814   int *argtypes;
1815   int nwanted;
1816
1817   /* @r{Get the information about the arguments.}
1818      @r{Each conversion specification must be at least two characters}
1819      @r{long, so there cannot be more specifications than half the}
1820      @r{length of the string.}  */
1821
1822   argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
1823   nwanted = parse_printf_format (string, nelts, argtypes);
1824
1825   /* @r{Check the number of arguments.}  */
1826   if (nwanted > nargs)
1827     @{
1828       error ("too few arguments (at least %d required)", nwanted);
1829       return 0;
1830     @}
1831     
1832   /* @r{Check the C type wanted for each argument}
1833      @r{and see if the object given is suitable.}  */
1834   for (i = 0; i < nwanted; i++)
1835     @{
1836       int wanted;
1837
1838       if (argtypes[i] & PA_FLAG_PTR)
1839         wanted = STRUCTURE;
1840       else
1841         switch (argtypes[i] & ~PA_FLAG_MASK)
1842           @{
1843           case PA_INT:
1844           case PA_FLOAT:
1845           case PA_DOUBLE:
1846             wanted = NUMBER;
1847             break;
1848           case PA_CHAR:
1849             wanted = CHAR;
1850             break;
1851           case PA_STRING:
1852             wanted = STRING;
1853             break;
1854           case PA_POINTER:
1855             wanted = STRUCTURE;
1856             break;
1857           @}
1858       if (TYPE (args[i]) != wanted)
1859         @{
1860           error ("type mismatch for arg number %d", i);
1861           return 0;
1862         @}
1863     @}
1864   return 1;
1865 @}
1866 @end smallexample
1867
1868 @node Customizing Printf
1869 @section Customizing @code{printf}
1870 @cindex customizing @code{printf}
1871 @cindex defining new @code{printf} conversions
1872 @cindex extending @code{printf}
1873
1874 The GNU C library lets you define your own custom conversion specifiers
1875 for @code{printf} template strings, to teach @code{printf} clever ways
1876 to print the important data structures of your program.
1877
1878 The way you do this is by registering the conversion with the function
1879 @code{register_printf_function}; see @ref{Registering New Conversions}.
1880 One of the arguments you pass to this function is a pointer to a handler
1881 function that produces the actual output; see @ref{Defining the Output
1882 Handler}, for information on how to write this function.
1883
1884 You can also install a function that just returns information about the
1885 number and type of arguments expected by the conversion specifier.
1886 @xref{Parsing a Template String}, for information about this.
1887
1888 The facilities of this section are declared in the header file
1889 @file{printf.h}.
1890
1891 @menu
1892 * Registering New Conversions::         Using @code{register_printf_function} 
1893                                          to register a new output conversion.
1894 * Conversion Specifier Options::        The handler must be able to get
1895                                          the options specified in the
1896                                          template when it is called. 
1897 * Defining the Output Handler::         Defining the handler and arginfo
1898                                          functions that are passed as arguments
1899                                          to @code{register_printf_function}.  
1900 * Printf Extension Example::            How to define a @code{printf}
1901                                          handler function. 
1902 @end menu
1903
1904 @strong{Portability Note:} The ability to extend the syntax of
1905 @code{printf} template strings is a GNU extension.  ANSI standard C has
1906 nothing similar.
1907
1908 @node Registering New Conversions
1909 @subsection Registering New Conversions
1910
1911 The function to register a new output conversion is
1912 @code{register_printf_function}, declared in @file{printf.h}.
1913 @pindex printf.h
1914
1915 @comment printf.h
1916 @comment GNU
1917 @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function})
1918 This function defines the conversion specifier character @var{spec}.
1919 Thus, if @var{spec} is @code{'z'}, it defines the conversion @samp{%z}.
1920 You can redefine the built-in conversions like @samp{%s}, but flag
1921 characters like @samp{#} and type modifiers like @samp{l} can never be
1922 used as conversions; calling @code{register_printf_function} for those
1923 characters has no effect.
1924
1925 The @var{handler-function} is the function called by @code{printf} and
1926 friends when this conversion appears in a template string.
1927 @xref{Defining the Output Handler}, for information about how to define
1928 a function to pass as this argument.  If you specify a null pointer, any
1929 existing handler function for @var{spec} is removed.
1930
1931 The @var{arginfo-function} is the function called by
1932 @code{parse_printf_format} when this conversion appears in a
1933 template string.  @xref{Parsing a Template String}, for information
1934 about this.
1935
1936 Normally, you install both functions for a conversion at the same time,
1937 but if you are never going to call @code{parse_printf_format}, you do
1938 not need to define an arginfo function.
1939
1940 The return value is @code{0} on success, and @code{-1} on failure
1941 (which occurs if @var{spec} is out of range).
1942
1943 You can redefine the standard output conversions, but this is probably
1944 not a good idea because of the potential for confusion.  Library routines
1945 written by other people could break if you do this.
1946 @end deftypefun
1947
1948 @node Conversion Specifier Options
1949 @subsection Conversion Specifier Options
1950
1951 If you define a meaning for @samp{%q}, what if the template contains
1952 @samp{%+23q} or @samp{%-#q}?  To implement a sensible meaning for these,
1953 the handler when called needs to be able to get the options specified in
1954 the template.
1955
1956 Both the @var{handler-function} and @var{arginfo-function} arguments
1957 to @code{register_printf_function} accept an argument that points to a
1958 @code{struct printf_info}, which contains information about the options
1959 appearing in an instance of the conversion specifier.  This data type
1960 is declared in the header file @file{printf.h}.
1961 @pindex printf.h
1962
1963 @comment printf.h
1964 @comment GNU
1965 @deftp {Type} {struct printf_info}
1966 This structure is used to pass information about the options appearing
1967 in an instance of a conversion specifier in a @code{printf} template
1968 string to the handler and arginfo functions for that specifier.  It
1969 contains the following members:
1970
1971 @table @code
1972 @item int prec
1973 This is the precision specified.  The value is @code{-1} if no precision
1974 was specified.  If the precision was given as @samp{*}, the
1975 @code{printf_info} structure passed to the handler function contains the
1976 actual value retrieved from the argument list.  But the structure passed
1977 to the arginfo function contains a value of @code{INT_MIN}, since the
1978 actual value is not known.
1979
1980 @item int width
1981 This is the minimum field width specified.  The value is @code{0} if no
1982 width was specified.  If the field width was given as @samp{*}, the
1983 @code{printf_info} structure passed to the handler function contains the
1984 actual value retrieved from the argument list.  But the structure passed
1985 to the arginfo function contains a value of @code{INT_MIN}, since the
1986 actual value is not known.
1987
1988 @item char spec
1989 This is the conversion specifier character specified.  It's stored in
1990 the structure so that you can register the same handler function for
1991 multiple characters, but still have a way to tell them apart when the
1992 handler function is called.
1993
1994 @item unsigned int is_long_double
1995 This is a boolean that is true if the @samp{L}, @samp{ll}, or @samp{q}
1996 type modifier was specified.  For integer conversions, this indicates
1997 @code{long long int}, as opposed to @code{long double} for floating
1998 point conversions.
1999
2000 @item unsigned int is_short
2001 This is a boolean that is true if the @samp{h} type modifier was specified.
2002
2003 @item unsigned int is_long
2004 This is a boolean that is true if the @samp{l} type modifier was specified.
2005
2006 @item unsigned int alt
2007 This is a boolean that is true if the @samp{#} flag was specified.
2008
2009 @item unsigned int space
2010 This is a boolean that is true if the @samp{ } flag was specified.
2011
2012 @item unsigned int left
2013 This is a boolean that is true if the @samp{-} flag was specified.
2014
2015 @item unsigned int showsign
2016 This is a boolean that is true if the @samp{+} flag was specified.
2017
2018 @item char pad
2019 This is the character to use for padding the output to the minimum field
2020 width.  The value is @code{'0'} if the @samp{0} flag was specified, and
2021 @code{' '} otherwise.
2022 @end table
2023 @end deftp
2024
2025
2026 @node Defining the Output Handler
2027 @subsection Defining the Output Handler
2028
2029 Now let's look at how to define the handler and arginfo functions
2030 which are passed as arguments to @code{register_printf_function}.
2031
2032 You should define your handler functions with a prototype like:
2033
2034 @smallexample
2035 int @var{function} (FILE *stream, const struct printf_info *info,
2036                     va_list *ap_pointer)
2037 @end smallexample
2038
2039 The @code{stream} argument passed to the handler function is the stream to
2040 which it should write output.
2041
2042 The @code{info} argument is a pointer to a structure that contains
2043 information about the various options that were included with the
2044 conversion in the template string.  You should not modify this structure
2045 inside your handler function.  @xref{Conversion Specifier Options}, for
2046 a description of this data structure.
2047
2048 The @code{ap_pointer} argument is used to pass the tail of the variable
2049 argument list containing the values to be printed to your handler.
2050 Unlike most other functions that can be passed an explicit variable
2051 argument list, this is a @emph{pointer} to a @code{va_list}, rather than
2052 the @code{va_list} itself.  Thus, you should fetch arguments by
2053 means of @code{va_arg (@var{type}, *ap_pointer)}.
2054
2055 (Passing a pointer here allows the function that calls your handler
2056 function to update its own @code{va_list} variable to account for the
2057 arguments that your handler processes.  @xref{Variadic Functions}.)
2058
2059 Your handler function should return a value just like @code{printf}
2060 does: it should return the number of characters it has written, or a
2061 negative value to indicate an error.
2062
2063 @comment printf.h
2064 @comment GNU
2065 @deftp {Data Type} printf_function
2066 This is the data type that a handler function should have.
2067 @end deftp
2068
2069 If you are going to use @w{@code{parse_printf_format}} in your
2070 application, you should also define a function to pass as the
2071 @var{arginfo-function} argument for each new conversion you install with
2072 @code{register_printf_function}. 
2073
2074 You should define these functions with a prototype like:
2075
2076 @smallexample
2077 int @var{function} (const struct printf_info *info,
2078                     size_t n, int *argtypes)
2079 @end smallexample
2080
2081 The return value from the function should be the number of arguments the
2082 conversion expects.  The function should also fill in no more than
2083 @var{n} elements of the @var{argtypes} array with information about the
2084 types of each of these arguments.  This information is encoded using the
2085 various @samp{PA_} macros.  (You will notice that this is the same
2086 calling convention @code{parse_printf_format} itself uses.)
2087
2088 @comment printf.h
2089 @comment GNU
2090 @deftp {Data Type} printf_arginfo_function
2091 This type is used to describe functions that return information about
2092 the number and type of arguments used by a conversion specifier.
2093 @end deftp
2094
2095 @node Printf Extension Example
2096 @subsection @code{printf} Extension Example
2097
2098 Here is an example showing how to define a @code{printf} handler function.
2099 This program defines a data structure called a @code{Widget} and 
2100 defines the @samp{%W} conversion to print information about @w{@code{Widget *}}
2101 arguments, including the pointer value and the name stored in the data
2102 structure.  The @samp{%W} conversion supports the minimum field width and
2103 left-justification options, but ignores everything else.
2104
2105 @smallexample
2106 @include rprintf.c.texi
2107 @end smallexample
2108
2109 The output produced by this program looks like:
2110
2111 @smallexample
2112 |<Widget 0xffeffb7c: mywidget>|
2113 |      <Widget 0xffeffb7c: mywidget>|
2114 |<Widget 0xffeffb7c: mywidget>      |
2115 @end smallexample
2116
2117 @node Formatted Input
2118 @section Formatted Input
2119
2120 @cindex formatted input from a stream
2121 @cindex reading from a stream, formatted
2122 @cindex format string, for @code{scanf}
2123 @cindex template, for @code{scanf}
2124 The functions described in this section (@code{scanf} and related
2125 functions) provide facilities for formatted input analogous to the
2126 formatted output facilities.  These functions provide a mechanism for
2127 reading arbitrary values under the control of a @dfn{format string} or
2128 @dfn{template string}.
2129
2130 @menu
2131 * Formatted Input Basics::      Some basics to get you started.
2132 * Input Conversion Syntax::     Syntax of conversion specifications.
2133 * Table of Input Conversions::  Summary of input conversions and what they do.
2134 * Numeric Input Conversions::   Details of conversions for reading numbers.
2135 * String Input Conversions::    Details of conversions for reading strings.
2136 * Dynamic String Input::        String conversions that @code{malloc} the buffer.
2137 * Other Input Conversions::     Details of miscellaneous other conversions.
2138 * Formatted Input Functions::   Descriptions of the actual functions.
2139 * Variable Arguments Input::    @code{vscanf} and friends.
2140 @end menu
2141
2142 @node Formatted Input Basics
2143 @subsection Formatted Input Basics
2144
2145 Calls to @code{scanf} are superficially similar to calls to
2146 @code{printf} in that arbitrary arguments are read under the control of
2147 a template string.  While the syntax of the conversion specifications in
2148 the template is very similar to that for @code{printf}, the
2149 interpretation of the template is oriented more towards free-format
2150 input and simple pattern matching, rather than fixed-field formatting.
2151 For example, most @code{scanf} conversions skip over any amount of
2152 ``white space'' (including spaces, tabs, and newlines) in the input
2153 file, and there is no concept of precision for the numeric input
2154 conversions as there is for the corresponding output conversions.
2155 Ordinarily, non-whitespace characters in the template are expected to
2156 match characters in the input stream exactly, but a matching failure is
2157 distinct from an input error on the stream.
2158 @cindex conversion specifications (@code{scanf})
2159
2160 Another area of difference between @code{scanf} and @code{printf} is
2161 that you must remember to supply pointers rather than immediate values
2162 as the optional arguments to @code{scanf}; the values that are read are
2163 stored in the objects that the pointers point to.  Even experienced
2164 programmers tend to forget this occasionally, so if your program is
2165 getting strange errors that seem to be related to @code{scanf}, you
2166 might want to double-check this.
2167
2168 When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
2169 leaving the first non-matching character as the next character to be
2170 read from the stream.  The normal return value from @code{scanf} is the
2171 number of values that were assigned, so you can use this to determine if
2172 a matching error happened before all the expected values were read.
2173 @cindex matching failure, in @code{scanf}
2174
2175 The @code{scanf} function is typically used for things like reading in
2176 the contents of tables.  For example, here is a function that uses
2177 @code{scanf} to initialize an array of @code{double}:
2178
2179 @smallexample
2180 void
2181 readarray (double *array, int n)
2182 @{
2183   int i;
2184   for (i=0; i<n; i++)
2185     if (scanf (" %lf", &(array[i])) != 1)
2186       invalid_input_error ();
2187 @}
2188 @end smallexample
2189
2190 The formatted input functions are not used as frequently as the
2191 formatted output functions.  Partly, this is because it takes some care
2192 to use them properly.  Another reason is that it is difficult to recover
2193 from a matching error.
2194
2195 If you are trying to read input that doesn't match a single, fixed
2196 pattern, you may be better off using a tool such as Flex to generate a
2197 lexical scanner, or Bison to generate a parser, rather than using
2198 @code{scanf}.  For more information about these tools, see @ref{, , ,
2199 flex.info, Flex: The Lexical Scanner Generator}, and @ref{, , ,
2200 bison.info, The Bison Reference Manual}.
2201
2202 @node Input Conversion Syntax
2203 @subsection Input Conversion Syntax
2204
2205 A @code{scanf} template string is a string that contains ordinary
2206 multibyte characters interspersed with conversion specifications that
2207 start with @samp{%}.
2208
2209 Any whitespace character (as defined by the @code{isspace} function;
2210 @pxref{Classification of Characters}) in the template causes any number
2211 of whitespace characters in the input stream to be read and discarded.
2212 The whitespace characters that are matched need not be exactly the same
2213 whitespace characters that appear in the template string.  For example,
2214 write @samp{ , } in the template to recognize a comma with optional
2215 whitespace before and after.
2216
2217 Other characters in the template string that are not part of conversion
2218 specifications must match characters in the input stream exactly; if
2219 this is not the case, a matching failure occurs.
2220
2221 The conversion specifications in a @code{scanf} template string
2222 have the general form:
2223
2224 @smallexample
2225 % @var{flags} @var{width} @var{type} @var{conversion}
2226 @end smallexample
2227
2228 In more detail, an input conversion specification consists of an initial
2229 @samp{%} character followed in sequence by:
2230
2231 @itemize @bullet
2232 @item
2233 An optional @dfn{flag character} @samp{*}, which says to ignore the text
2234 read for this specification.  When @code{scanf} finds a conversion
2235 specification that uses this flag, it reads input as directed by the
2236 rest of the conversion specification, but it discards this input, does
2237 not use a pointer argument, and does not increment the count of
2238 successful assignments.
2239 @cindex flag character (@code{scanf})
2240
2241 @item
2242 An optional flag character @samp{a} (valid with string conversions only)
2243 which requests allocation of a buffer long enough to store the string in.
2244 (This is a GNU extension.)
2245 @xref{Dynamic String Input}.
2246
2247 @item
2248 An optional decimal integer that specifies the @dfn{maximum field
2249 width}.  Reading of characters from the input stream stops either when
2250 this maximum is reached or when a non-matching character is found,
2251 whichever happens first.  Most conversions discard initial whitespace
2252 characters (those that don't are explicitly documented), and these
2253 discarded characters don't count towards the maximum field width.
2254 String input conversions store a null character to mark the end of the
2255 input; the maximum field width does not include this terminator.
2256 @cindex maximum field width (@code{scanf})
2257
2258 @item
2259 An optional @dfn{type modifier character}.  For example, you can
2260 specify a type modifier of @samp{l} with integer conversions such as
2261 @samp{%d} to specify that the argument is a pointer to a @code{long int}
2262 rather than a pointer to an @code{int}.
2263 @cindex type modifier character (@code{scanf})
2264
2265 @item
2266 A character that specifies the conversion to be applied.
2267 @end itemize
2268
2269 The exact options that are permitted and how they are interpreted vary 
2270 between the different conversion specifiers.  See the descriptions of the
2271 individual conversions for information about the particular options that
2272 they allow.
2273
2274 With the @samp{-Wformat} option, the GNU C compiler checks calls to
2275 @code{scanf} and related functions.  It examines the format string and
2276 verifies that the correct number and types of arguments are supplied.
2277 There is also a GNU C syntax to tell the compiler that a function you
2278 write uses a @code{scanf}-style format string.  
2279 @xref{Function Attributes, , Declaring Attributes of Functions,
2280 gcc.info, Using GNU CC}, for more information.
2281
2282 @node Table of Input Conversions
2283 @subsection Table of Input Conversions
2284 @cindex input conversions, for @code{scanf}
2285
2286 Here is a table that summarizes the various conversion specifications:
2287
2288 @table @asis
2289 @item @samp{%d}
2290 Matches an optionally signed integer written in decimal.  @xref{Numeric
2291 Input Conversions}.
2292
2293 @item @samp{%i}
2294 Matches an optionally signed integer in any of the formats that the C
2295 language defines for specifying an integer constant.  @xref{Numeric
2296 Input Conversions}.
2297
2298 @item @samp{%o}
2299 Matches an unsigned integer written in octal radix.
2300 @xref{Numeric Input Conversions}.
2301
2302 @item @samp{%u}
2303 Matches an unsigned integer written in decimal radix.
2304 @xref{Numeric Input Conversions}.
2305
2306 @item @samp{%x}, @samp{%X}
2307 Matches an unsigned integer written in hexadecimal radix.
2308 @xref{Numeric Input Conversions}.
2309
2310 @item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
2311 Matches an optionally signed floating-point number.  @xref{Numeric Input
2312 Conversions}.
2313
2314 @item @samp{%s}
2315 Matches a string containing only non-whitespace characters.
2316 @xref{String Input Conversions}.
2317
2318 @item @samp{%[}
2319 Matches a string of characters that belong to a specified set.
2320 @xref{String Input Conversions}.
2321
2322 @item @samp{%c}
2323 Matches a string of one or more characters; the number of characters
2324 read is controlled by the maximum field width given for the conversion.
2325 @xref{String Input Conversions}.
2326
2327 @item @samp{%p}
2328 Matches a pointer value in the same implementation-defined format used
2329 by the @samp{%p} output conversion for @code{printf}.  @xref{Other Input
2330 Conversions}.
2331
2332 @item @samp{%n}
2333 This conversion doesn't read any characters; it records the number of
2334 characters read so far by this call.  @xref{Other Input Conversions}.
2335
2336 @item @samp{%%}
2337 This matches a literal @samp{%} character in the input stream.  No
2338 corresponding argument is used.  @xref{Other Input Conversions}.
2339 @end table
2340
2341 If the syntax of a conversion specification is invalid, the behavior is
2342 undefined.  If there aren't enough function arguments provided to supply
2343 addresses for all the conversion specifications in the template strings
2344 that perform assignments, or if the arguments are not of the correct
2345 types, the behavior is also undefined.  On the other hand, extra
2346 arguments are simply ignored.
2347
2348 @node Numeric Input Conversions
2349 @subsection Numeric Input Conversions
2350
2351 This section describes the @code{scanf} conversions for reading numeric
2352 values.
2353
2354 The @samp{%d} conversion matches an optionally signed integer in decimal
2355 radix.  The syntax that is recognized is the same as that for the
2356 @code{strtol} function (@pxref{Parsing of Integers}) with the value
2357 @code{10} for the @var{base} argument.
2358
2359 The @samp{%i} conversion matches an optionally signed integer in any of
2360 the formats that the C language defines for specifying an integer
2361 constant.  The syntax that is recognized is the same as that for the
2362 @code{strtol} function (@pxref{Parsing of Integers}) with the value
2363 @code{0} for the @var{base} argument.  (You can print integers in this
2364 syntax with @code{printf} by using the @samp{#} flag character with the
2365 @samp{%x}, @samp{%o}, or @samp{%d} conversion.  @xref{Integer Conversions}.)
2366
2367 For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
2368 could be read in as integers under the @samp{%i} conversion.  Each of
2369 these specifies a number with decimal value @code{10}.
2370
2371 The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned
2372 integers in octal, decimal, and hexadecimal radices, respectively.  The
2373 syntax that is recognized is the same as that for the @code{strtoul}
2374 function (@pxref{Parsing of Integers}) with the appropriate value
2375 (@code{8}, @code{10}, or @code{16}) for the @var{base} argument.
2376
2377 The @samp{%X} conversion is identical to the @samp{%x} conversion.  They
2378 both permit either uppercase or lowercase letters to be used as digits.
2379
2380 The default type of the corresponding argument for the @code{%d} and
2381 @code{%i} conversions is @code{int *}, and @code{unsigned int *} for the
2382 other integer conversions.  You can use the following type modifiers to
2383 specify other sizes of integer:
2384
2385 @table @samp
2386 @item h
2387 Specifies that the argument is a @code{short int *} or @code{unsigned
2388 short int *}.
2389
2390 @item l
2391 Specifies that the argument is a @code{long int *} or @code{unsigned
2392 long int *}.  Two @samp{l} characters is like the @samp{L} modifier, below.
2393
2394 @need 100
2395 @item ll
2396 @itemx L
2397 @itemx q
2398 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
2399 GNU C compiler.  For systems that don't provide extra-long integers, this
2400 is the same as @code{long int}.)
2401
2402 The @samp{q} modifier is another name for the same thing, which comes
2403 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
2404 @code{int}.
2405 @end table
2406
2407 All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
2408 input conversions are interchangeable.  They all match an optionally
2409 signed floating point number, in the same syntax as for the
2410 @code{strtod} function (@pxref{Parsing of Floats}).
2411
2412 For the floating-point input conversions, the default argument type is
2413 @code{float *}.  (This is different from the corresponding output
2414 conversions, where the default type is @code{double}; remember that
2415 @code{float} arguments to @code{printf} are converted to @code{double}
2416 by the default argument promotions, but @code{float *} arguments are
2417 not promoted to @code{double *}.)  You can specify other sizes of float
2418 using these type modifiers:
2419
2420 @table @samp
2421 @item l
2422 Specifies that the argument is of type @code{double *}.
2423
2424 @item L
2425 Specifies that the argument is of type @code{long double *}.
2426 @end table
2427
2428 @node String Input Conversions
2429 @subsection String Input Conversions
2430
2431 This section describes the @code{scanf} input conversions for reading
2432 string and character values: @samp{%s}, @samp{%[}, and @samp{%c}.  
2433
2434 You have two options for how to receive the input from these
2435 conversions:
2436
2437 @itemize @bullet
2438 @item
2439 Provide a buffer to store it in.  This is the default.  You
2440 should provide an argument of type @code{char *}.
2441
2442 @strong{Warning:} To make a robust program, you must make sure that the
2443 input (plus its terminating null) cannot possibly exceed the size of the
2444 buffer you provide.  In general, the only way to do this is to specify a
2445 maximum field width one less than the buffer size.  @strong{If you
2446 provide the buffer, always specify a maximum field width to prevent
2447 overflow.}
2448
2449 @item
2450 Ask @code{scanf} to allocate a big enough buffer, by specifying the
2451 @samp{a} flag character.  This is a GNU extension.  You should provide
2452 an argument of type @code{char **} for the buffer address to be stored
2453 in.  @xref{Dynamic String Input}.
2454 @end itemize
2455
2456 The @samp{%c} conversion is the simplest: it matches a fixed number of
2457 characters, always.  The maximum field with says how many characters to
2458 read; if you don't specify the maximum, the default is 1.  This
2459 conversion doesn't append a null character to the end of the text it
2460 reads.  It also does not skip over initial whitespace characters.  It
2461 reads precisely the next @var{n} characters, and fails if it cannot get
2462 that many.  Since there is always a maximum field width with @samp{%c}
2463 (whether specified, or 1 by default), you can always prevent overflow by
2464 making the buffer long enough.
2465
2466 The @samp{%s} conversion matches a string of non-whitespace characters.
2467 It skips and discards initial whitespace, but stops when it encounters
2468 more whitespace after having read something.  It stores a null character
2469 at the end of the text that it reads.
2470
2471 For example, reading the input:
2472
2473 @smallexample
2474  hello, world
2475 @end smallexample
2476
2477 @noindent
2478 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
2479 reading the same input with the conversion @samp{%10s} produces
2480 @code{"hello,"}.
2481
2482 @strong{Warning:} If you do not specify a field width for @samp{%s},
2483 then the number of characters read is limited only by where the next
2484 whitespace character appears.  This almost certainly means that invalid
2485 input can make your program crash---which is a bug.
2486
2487 To read in characters that belong to an arbitrary set of your choice,
2488 use the @samp{%[} conversion.  You specify the set between the @samp{[}
2489 character and a following @samp{]} character, using the same syntax used
2490 in regular expressions.  As special cases:
2491
2492 @itemize @bullet
2493 @item 
2494 A literal @samp{]} character can be specified as the first character
2495 of the set.
2496
2497 @item 
2498 An embedded @samp{-} character (that is, one that is not the first or
2499 last character of the set) is used to specify a range of characters.
2500
2501 @item 
2502 If a caret character @samp{^} immediately follows the initial @samp{[},
2503 then the set of allowed input characters is the everything @emph{except}
2504 the characters listed.
2505 @end itemize
2506
2507 The @samp{%[} conversion does not skip over initial whitespace
2508 characters.
2509
2510 Here are some examples of @samp{%[} conversions and what they mean:
2511
2512 @table @samp
2513 @item %25[1234567890]
2514 Matches a string of up to 25 digits.
2515
2516 @item %25[][]
2517 Matches a string of up to 25 square brackets.
2518
2519 @item %25[^ \f\n\r\t\v]
2520 Matches a string up to 25 characters long that doesn't contain any of
2521 the standard whitespace characters.  This is slightly different from
2522 @samp{%s}, because if the input begins with a whitespace character,
2523 @samp{%[} reports a matching failure while @samp{%s} simply discards the
2524 initial whitespace.
2525
2526 @item %25[a-z] 
2527 Matches up to 25 lowercase characters.
2528 @end table
2529
2530 One more reminder: the @samp{%s} and @samp{%[} conversions are
2531 @strong{dangerous} if you don't specify a maximum width or use the
2532 @samp{a} flag, because input too long would overflow whatever buffer you
2533 have provided for it.  No matter how long your buffer is, a user could
2534 supply input that is longer.  A well-written program reports invalid
2535 input with a comprehensible error message, not with a crash.
2536
2537 @node Dynamic String Input
2538 @subsection Dynamically Allocating String Conversions
2539
2540 A GNU extension to formatted input lets you safely read a string with no
2541 maximum size.  Using this feature, you don't supply a buffer; instead,
2542 @code{scanf} allocates a buffer big enough to hold the data and gives
2543 you its address.  To use this feature, write @samp{a} as a flag
2544 character, as in @samp{%as} or @samp{%a[0-9a-z]}.
2545
2546 The pointer argument you supply for where to store the input should have
2547 type @code{char **}.  The @code{scanf} function allocates a buffer and
2548 stores its address in the word that the argument points to.  You should
2549 free the buffer with @code{free} when you no longer need it.
2550
2551 Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]}
2552 conversion specification to read a ``variable assignment'' of the form
2553 @samp{@var{variable} = @var{value}}.
2554
2555 @smallexample
2556 @{
2557   char *variable, *value;
2558
2559   if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
2560                  &variable, &value))
2561     @{
2562       invalid_input_error ();
2563       return 0;
2564     @}
2565
2566   @dots{}
2567 @}
2568 @end smallexample
2569
2570 @node Other Input Conversions
2571 @subsection Other Input Conversions
2572
2573 This section describes the miscellaneous input conversions.
2574
2575 The @samp{%p} conversion is used to read a pointer value.  It recognizes
2576 the same syntax as is used by the @samp{%p} output conversion for
2577 @code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
2578 number just as the @samp{%x} conversion accepts.  The corresponding
2579 argument should be of type @code{void **}; that is, the address of a
2580 place to store a pointer.
2581
2582 The resulting pointer value is not guaranteed to be valid if it was not
2583 originally written during the same program execution that reads it in.
2584
2585 The @samp{%n} conversion produces the number of characters read so far
2586 by this call.  The corresponding argument should be of type @code{int *}.
2587 This conversion works in the same way as the @samp{%n} conversion for
2588 @code{printf}; see @ref{Other Output Conversions}, for an example.
2589
2590 The @samp{%n} conversion is the only mechanism for determining the
2591 success of literal matches or conversions with suppressed assignments.
2592 If the @samp{%n} follows the locus of a matching failure, then no value
2593 is stored for it since @code{scanf} returns before processing the
2594 @samp{%n}.  If you store @code{-1} in that argument slot before calling
2595 @code{scanf}, the presence of @code{-1} after @code{scanf} indicates an
2596 error occurred before the @samp{%n} was reached.
2597
2598 Finally, the @samp{%%} conversion matches a literal @samp{%} character
2599 in the input stream, without using an argument.  This conversion does
2600 not permit any flags, field width, or type modifier to be specified.
2601
2602 @node Formatted Input Functions
2603 @subsection Formatted Input Functions
2604
2605 Here are the descriptions of the functions for performing formatted
2606 input.
2607 Prototypes for these functions are in the header file @file{stdio.h}.
2608 @pindex stdio.h
2609
2610 @comment stdio.h
2611 @comment ANSI
2612 @deftypefun int scanf (const char *@var{template}, @dots{})
2613 The @code{scanf} function reads formatted input from the stream
2614 @code{stdin} under the control of the template string @var{template}.
2615 The optional arguments are pointers to the places which receive the
2616 resulting values.
2617
2618 The return value is normally the number of successful assignments.  If
2619 an end-of-file condition is detected before any matches are performed
2620 (including matches against whitespace and literal characters in the
2621 template), then @code{EOF} is returned.
2622 @end deftypefun
2623
2624 @comment stdio.h
2625 @comment ANSI
2626 @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
2627 This function is just like @code{scanf}, except that the input is read
2628 from the stream @var{stream} instead of @code{stdin}.
2629 @end deftypefun
2630
2631 @comment stdio.h
2632 @comment ANSI
2633 @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
2634 This is like @code{scanf}, except that the characters are taken from the
2635 null-terminated string @var{s} instead of from a stream.  Reaching the
2636 end of the string is treated as an end-of-file condition.
2637
2638 The behavior of this function is undefined if copying takes place
2639 between objects that overlap---for example, if @var{s} is also given
2640 as an argument to receive a string read under control of the @samp{%s}
2641 conversion.
2642 @end deftypefun
2643
2644 @node Variable Arguments Input
2645 @subsection Variable Arguments Input Functions
2646
2647 The functions @code{vscanf} and friends are provided so that you can
2648 define your own variadic @code{scanf}-like functions that make use of
2649 the same internals as the built-in formatted output functions.
2650 These functions are analogous to the @code{vprintf} series of output
2651 functions.  @xref{Variable Arguments Output}, for important
2652 information on how to use them.
2653
2654 @strong{Portability Note:} The functions listed in this section are GNU
2655 extensions.
2656
2657 @comment stdio.h
2658 @comment GNU
2659 @deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
2660 This function is similar to @code{scanf} except that, instead of taking
2661 a variable number of arguments directly, it takes an argument list
2662 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
2663 @end deftypefun
2664
2665 @comment stdio.h
2666 @comment GNU
2667 @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
2668 This is the equivalent of @code{fscanf} with the variable argument list
2669 specified directly as for @code{vscanf}.
2670 @end deftypefun
2671
2672 @comment stdio.h
2673 @comment GNU
2674 @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
2675 This is the equivalent of @code{sscanf} with the variable argument list
2676 specified directly as for @code{vscanf}.
2677 @end deftypefun
2678
2679 In GNU C, there is a special construct you can use to let the compiler
2680 know that a function uses a @code{scanf}-style format string.  Then it
2681 can check the number and types of arguments in each call to the
2682 function, and warn you when they do not match the format string.
2683 @xref{Function Attributes, , Declaring Attributes of Functions,
2684 gcc.info, Using GNU CC}, for details.
2685
2686 @node EOF and Errors
2687 @section End-Of-File and Errors
2688
2689 @cindex end of file, on a stream
2690 Many of the functions described in this chapter return the value of the
2691 macro @code{EOF} to indicate unsuccessful completion of the operation.
2692 Since @code{EOF} is used to report both end of file and random errors,
2693 it's often better to use the @code{feof} function to check explicitly
2694 for end of file and @code{ferror} to check for errors.  These functions
2695 check indicators that are part of the internal state of the stream
2696 object, indicators set if the appropriate condition was detected by a
2697 previous I/O operation on that stream.
2698
2699 These symbols are declared in the header file @file{stdio.h}.
2700 @pindex stdio.h
2701
2702 @comment stdio.h
2703 @comment ANSI
2704 @deftypevr Macro int EOF
2705 This macro is an integer value that is returned by a number of functions
2706 to indicate an end-of-file condition, or some other error situation.
2707 With the GNU library, @code{EOF} is @code{-1}.  In other libraries, its
2708 value may be some other negative number.
2709 @end deftypevr
2710
2711 @comment stdio.h
2712 @comment ANSI
2713 @deftypefun void clearerr (FILE *@var{stream})
2714 This function clears the end-of-file and error indicators for the
2715 stream @var{stream}.
2716
2717 The file positioning functions (@pxref{File Positioning}) also clear the
2718 end-of-file indicator for the stream.
2719 @end deftypefun
2720
2721 @comment stdio.h
2722 @comment ANSI
2723 @deftypefun int feof (FILE *@var{stream})
2724 The @code{feof} function returns nonzero if and only if the end-of-file
2725 indicator for the stream @var{stream} is set.
2726 @end deftypefun
2727
2728 @comment stdio.h
2729 @comment ANSI
2730 @deftypefun int ferror (FILE *@var{stream})
2731 The @code{ferror} function returns nonzero if and only if the error
2732 indicator for the stream @var{stream} is set, indicating that an error
2733 has occurred on a previous operation on the stream.
2734 @end deftypefun
2735
2736 In addition to setting the error indicator associated with the stream,
2737 the functions that operate on streams also set @code{errno} in the same
2738 way as the corresponding low-level functions that operate on file
2739 descriptors.  For example, all of the functions that perform output to a
2740 stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are
2741 implemented in terms of @code{write}, and all of the @code{errno} error
2742 conditions defined for @code{write} are meaningful for these functions.
2743 For more information about the descriptor-level I/O functions, see
2744 @ref{Low-Level I/O}.
2745
2746 @node Binary Streams
2747 @section Text and Binary Streams
2748
2749 The GNU system and other POSIX-compatible operating systems organize all
2750 files as uniform sequences of characters.  However, some other systems
2751 make a distinction between files containing text and files containing
2752 binary data, and the input and output facilities of ANSI C provide for
2753 this distinction.  This section tells you how to write programs portable
2754 to such systems.
2755
2756 @cindex text stream
2757 @cindex binary stream
2758 When you open a stream, you can specify either a @dfn{text stream} or a
2759 @dfn{binary stream}.  You indicate that you want a binary stream by
2760 specifying the @samp{b} modifier in the @var{opentype} argument to
2761 @code{fopen}; see @ref{Opening Streams}.  Without this
2762 option, @code{fopen} opens the file as a text stream.
2763
2764 Text and binary streams differ in several ways:
2765
2766 @itemize @bullet
2767 @item
2768 The data read from a text stream is divided into @dfn{lines} which are
2769 terminated by newline (@code{'\n'}) characters, while a binary stream is
2770 simply a long series of characters.  A text stream might on some systems
2771 fail to handle lines more than 254 characters long (including the
2772 terminating newline character).
2773 @cindex lines (in a text file)
2774
2775 @item
2776 On some systems, text files can contain only printing characters,
2777 horizontal tab characters, and newlines, and so text streams may not
2778 support other characters.  However, binary streams can handle any
2779 character value.
2780
2781 @item
2782 Space characters that are written immediately preceding a newline
2783 character in a text stream may disappear when the file is read in again.
2784
2785 @item
2786 More generally, there need not be a one-to-one mapping between
2787 characters that are read from or written to a text stream, and the
2788 characters in the actual file.
2789 @end itemize
2790
2791 Since a binary stream is always more capable and more predictable than a
2792 text stream, you might wonder what purpose text streams serve.  Why not
2793 simply always use binary streams?  The answer is that on these operating
2794 systems, text and binary streams use different file formats, and the
2795 only way to read or write ``an ordinary file of text'' that can work
2796 with other text-oriented programs is through a text stream.
2797
2798 In the GNU library, and on all POSIX systems, there is no difference
2799 between text streams and binary streams.  When you open a stream, you
2800 get the same kind of stream regardless of whether you ask for binary.
2801 This stream can handle any file content, and has none of the
2802 restrictions that text streams sometimes have.
2803
2804 @node File Positioning
2805 @section File Positioning
2806 @cindex file positioning on a stream
2807 @cindex positioning a stream
2808 @cindex seeking on a stream
2809
2810 The @dfn{file position} of a stream describes where in the file the
2811 stream is currently reading or writing.  I/O on the stream advances the
2812 file position through the file.  In the GNU system, the file position is
2813 represented as an integer, which counts the number of bytes from the
2814 beginning of the file.  @xref{File Position}.
2815
2816 During I/O to an ordinary disk file, you can change the file position
2817 whenever you wish, so as to read or write any portion of the file.  Some
2818 other kinds of files may also permit this.  Files which support changing
2819 the file position are sometimes referred to as @dfn{random-access}
2820 files.
2821
2822 You can use the functions in this section to examine or modify the file
2823 position indicator associated with a stream.  The symbols listed below
2824 are declared in the header file @file{stdio.h}.
2825 @pindex stdio.h
2826
2827 @comment stdio.h
2828 @comment ANSI
2829 @deftypefun {long int} ftell (FILE *@var{stream})
2830 This function returns the current file position of the stream
2831 @var{stream}.
2832
2833 This function can fail if the stream doesn't support file positioning,
2834 or if the file position can't be represented in a @code{long int}, and
2835 possibly for other reasons as well.  If a failure occurs, a value of
2836 @code{-1} is returned.
2837 @end deftypefun
2838
2839 @comment stdio.h
2840 @comment ANSI
2841 @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
2842 The @code{fseek} function is used to change the file position of the
2843 stream @var{stream}.  The value of @var{whence} must be one of the
2844 constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
2845 indicate whether the @var{offset} is relative to the beginning of the
2846 file, the current file position, or the end of the file, respectively.
2847
2848 This function returns a value of zero if the operation was successful,
2849 and a nonzero value to indicate failure.  A successful call also clears
2850 the end-of-file indicator of @var{stream} and discards any characters
2851 that were ``pushed back'' by the use of @code{ungetc}.
2852
2853 @code{fseek} either flushes any buffered output before setting the file
2854 position or else remembers it so it will be written later in its proper
2855 place in the file.
2856 @end deftypefun
2857
2858 @strong{Portability Note:} In non-POSIX systems, @code{ftell} and
2859 @code{fseek} might work reliably only on binary streams.  @xref{Binary
2860 Streams}.
2861
2862 The following symbolic constants are defined for use as the @var{whence}
2863 argument to @code{fseek}.  They are also used with the @code{lseek}
2864 function (@pxref{I/O Primitives}) and to specify offsets for file locks
2865 (@pxref{Control Operations}).
2866
2867 @comment stdio.h
2868 @comment ANSI
2869 @deftypevr Macro int SEEK_SET
2870 This is an integer constant which, when used as the @var{whence}
2871 argument to the @code{fseek} function, specifies that the offset
2872 provided is relative to the beginning of the file.
2873 @end deftypevr
2874
2875 @comment stdio.h
2876 @comment ANSI
2877 @deftypevr Macro int SEEK_CUR
2878 This is an integer constant which, when used as the @var{whence}
2879 argument to the @code{fseek} function, specifies that the offset
2880 provided is relative to the current file position.
2881 @end deftypevr
2882
2883 @comment stdio.h
2884 @comment ANSI
2885 @deftypevr Macro int SEEK_END
2886 This is an integer constant which, when used as the @var{whence}
2887 argument to the @code{fseek} function, specifies that the offset
2888 provided is relative to the end of the file.
2889 @end deftypevr
2890
2891 @comment stdio.h
2892 @comment ANSI
2893 @deftypefun void rewind (FILE *@var{stream})
2894 The @code{rewind} function positions the stream @var{stream} at the
2895 begining of the file.  It is equivalent to calling @code{fseek} on the
2896 @var{stream} with an @var{offset} argument of @code{0L} and a
2897 @var{whence} argument of @code{SEEK_SET}, except that the return
2898 value is discarded and the error indicator for the stream is reset.
2899 @end deftypefun
2900
2901 These three aliases for the @samp{SEEK_@dots{}} constants exist for the
2902 sake of compatibility with older BSD systems.  They are defined in two
2903 different header files: @file{fcntl.h} and @file{sys/file.h}.
2904
2905 @table @code
2906 @comment sys/file.h
2907 @comment BSD
2908 @item L_SET
2909 @vindex L_SET
2910 An alias for @code{SEEK_SET}.
2911
2912 @comment sys/file.h
2913 @comment BSD
2914 @item L_INCR
2915 @vindex L_INCR
2916 An alias for @code{SEEK_CUR}.
2917
2918 @comment sys/file.h
2919 @comment BSD
2920 @item L_XTND
2921 @vindex L_XTND
2922 An alias for @code{SEEK_END}.
2923 @end table
2924
2925 @node Portable Positioning
2926 @section Portable File-Position Functions
2927
2928 On the GNU system, the file position is truly a character count.  You
2929 can specify any character count value as an argument to @code{fseek} and
2930 get reliable results for any random access file.  However, some ANSI C
2931 systems do not represent file positions in this way.
2932
2933 On some systems where text streams truly differ from binary streams, it
2934 is impossible to represent the file position of a text stream as a count
2935 of characters from the beginning of the file.  For example, the file
2936 position on some systems must encode both a record offset within the
2937 file, and a character offset within the record.
2938
2939 As a consequence, if you want your programs to be portable to these
2940 systems, you must observe certain rules:
2941
2942 @itemize @bullet
2943 @item
2944 The value returned from @code{ftell} on a text stream has no predictable
2945 relationship to the number of characters you have read so far.  The only
2946 thing you can rely on is that you can use it subsequently as the
2947 @var{offset} argument to @code{fseek} to move back to the same file
2948 position.
2949
2950 @item 
2951 In a call to @code{fseek} on a text stream, either the @var{offset} must
2952 either be zero; or @var{whence} must be @code{SEEK_SET} and the
2953 @var{offset} must be the result of an earlier call to @code{ftell} on
2954 the same stream.
2955
2956 @item
2957 The value of the file position indicator of a text stream is undefined
2958 while there are characters that have been pushed back with @code{ungetc}
2959 that haven't been read or discarded.  @xref{Unreading}.
2960 @end itemize
2961
2962 But even if you observe these rules, you may still have trouble for long
2963 files, because @code{ftell} and @code{fseek} use a @code{long int} value
2964 to represent the file position.  This type may not have room to encode
2965 all the file positions in a large file.
2966
2967 So if you do want to support systems with peculiar encodings for the
2968 file positions, it is better to use the functions @code{fgetpos} and
2969 @code{fsetpos} instead.  These functions represent the file position
2970 using the data type @code{fpos_t}, whose internal representation varies
2971 from system to system.
2972
2973 These symbols are declared in the header file @file{stdio.h}.
2974 @pindex stdio.h
2975
2976 @comment stdio.h
2977 @comment ANSI
2978 @deftp {Data Type} fpos_t
2979 This is the type of an object that can encode information about the
2980 file position of a stream, for use by the functions @code{fgetpos} and
2981 @code{fsetpos}.
2982
2983 In the GNU system, @code{fpos_t} is equivalent to @code{off_t} or
2984 @code{long int}.  In other systems, it might have a different internal
2985 representation.
2986 @end deftp
2987
2988 @comment stdio.h
2989 @comment ANSI
2990 @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
2991 This function stores the value of the file position indicator for the
2992 stream @var{stream} in the @code{fpos_t} object pointed to by
2993 @var{position}.  If successful, @code{fgetpos} returns zero; otherwise
2994 it returns a nonzero value and stores an implementation-defined positive
2995 value in @code{errno}.
2996 @end deftypefun
2997
2998 @comment stdio.h
2999 @comment ANSI
3000 @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t @var{position})
3001 This function sets the file position indicator for the stream @var{stream}
3002 to the position @var{position}, which must have been set by a previous
3003 call to @code{fgetpos} on the same stream.  If successful, @code{fsetpos}
3004 clears the end-of-file indicator on the stream, discards any characters
3005 that were ``pushed back'' by the use of @code{ungetc}, and returns a value
3006 of zero.  Otherwise, @code{fsetpos} returns a nonzero value and stores
3007 an implementation-defined positive value in @code{errno}.
3008 @end deftypefun
3009
3010 @node Stream Buffering
3011 @section Stream Buffering
3012
3013 @cindex buffering of streams
3014 Characters that are written to a stream are normally accumulated and
3015 transmitted asynchronously to the file in a block, instead of appearing
3016 as soon as they are output by the application program.  Similarly,
3017 streams often retrieve input from the host environment in blocks rather
3018 than on a character-by-character basis.  This is called @dfn{buffering}.
3019
3020 If you are writing programs that do interactive input and output using
3021 streams, you need to understand how buffering works when you design the
3022 user interface to your program.  Otherwise, you might find that output
3023 (such as progress or prompt messages) doesn't appear when you intended
3024 it to, or other unexpected behavior.
3025
3026 This section deals only with controlling when characters are transmitted
3027 between the stream and the file or device, and @emph{not} with how
3028 things like echoing, flow control, and the like are handled on specific
3029 classes of devices.  For information on common control operations on
3030 terminal devices, see @ref{Low-Level Terminal Interface}.
3031
3032 You can bypass the stream buffering facilities altogether by using the
3033 low-level input and output functions that operate on file descriptors
3034 instead.  @xref{Low-Level I/O}.
3035
3036 @menu
3037 * Buffering Concepts::          Terminology is defined here.
3038 * Flushing Buffers::            How to ensure that output buffers are flushed.
3039 * Controlling Buffering::       How to specify what kind of buffering to use.
3040 @end menu
3041
3042 @node Buffering Concepts
3043 @subsection Buffering Concepts
3044
3045 There are three different kinds of buffering strategies:
3046
3047 @itemize @bullet
3048 @item
3049 Characters written to or read from an @dfn{unbuffered} stream are
3050 transmitted individually to or from the file as soon as possible.
3051 @cindex unbuffered stream
3052
3053 @item
3054 Characters written to a @dfn{line buffered} stream are transmitted to
3055 the file in blocks when a newline character is encountered.
3056 @cindex line buffered stream
3057
3058 @item
3059 Characters written to or read from a @dfn{fully buffered} stream are
3060 transmitted to or from the file in blocks of arbitrary size.
3061 @cindex fully buffered stream
3062 @end itemize
3063
3064 Newly opened streams are normally fully buffered, with one exception: a
3065 stream connected to an interactive device such as a terminal is
3066 initially line buffered.  @xref{Controlling Buffering}, for information
3067 on how to select a different kind of buffering.  Usually the automatic
3068 selection gives you the most convenient kind of buffering for the file
3069 or device you open.
3070
3071 The use of line buffering for interactive devices implies that output
3072 messages ending in a newline will appear immediately---which is usually
3073 what you want.  Output that doesn't end in a newline might or might not
3074 show up immediately, so if you want them to appear immediately, you
3075 should flush buffered output explicitly with @code{fflush}, as described
3076 in @ref{Flushing Buffers}.
3077
3078 @node Flushing Buffers
3079 @subsection Flushing Buffers
3080
3081 @cindex flushing a stream
3082 @dfn{Flushing} output on a buffered stream means transmitting all
3083 accumulated characters to the file.  There are many circumstances when
3084 buffered output on a stream is flushed automatically:
3085
3086 @itemize @bullet
3087 @item
3088 When you try to do output and the output buffer is full.
3089
3090 @item
3091 When the stream is closed.  @xref{Closing Streams}.
3092
3093 @item 
3094 When the program terminates by calling @code{exit}.
3095 @xref{Normal Termination}.
3096
3097 @item
3098 When a newline is written, if the stream is line buffered.
3099
3100 @item
3101 Whenever an input operation on @emph{any} stream actually reads data
3102 from its file.
3103 @end itemize
3104
3105 If you want to flush the buffered output at another time, call
3106 @code{fflush}, which is declared in the header file @file{stdio.h}.
3107 @pindex stdio.h
3108
3109 @comment stdio.h
3110 @comment ANSI
3111 @deftypefun int fflush (FILE *@var{stream})
3112 This function causes any buffered output on @var{stream} to be delivered
3113 to the file.  If @var{stream} is a null pointer, then
3114 @code{fflush} causes buffered output on @emph{all} open output streams
3115 to be flushed.
3116
3117 This function returns @code{EOF} if a write error occurs, or zero
3118 otherwise.
3119 @end deftypefun
3120
3121 @strong{Compatibility Note:} Some brain-damaged operating systems have
3122 been known to be so thoroughly fixated on line-oriented input and output
3123 that flushing a line buffered stream causes a newline to be written!
3124 Fortunately, this ``feature'' seems to be becoming less common.  You do
3125 not need to worry about this in the GNU system.
3126
3127
3128 @node Controlling Buffering
3129 @subsection Controlling Which Kind of Buffering
3130
3131 After opening a stream (but before any other operations have been
3132 performed on it), you can explicitly specify what kind of buffering you
3133 want it to have using the @code{setvbuf} function.
3134 @cindex buffering, controlling
3135
3136 The facilities listed in this section are declared in the header
3137 file @file{stdio.h}.
3138 @pindex stdio.h
3139
3140 @comment stdio.h
3141 @comment ANSI
3142 @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
3143 This function is used to specify that the stream @var{stream} should
3144 have the buffering mode @var{mode}, which can be either @code{_IOFBF}
3145 (for full buffering), @code{_IOLBF} (for line buffering), or
3146 @code{_IONBF} (for unbuffered input/output).
3147
3148 If you specify a null pointer as the @var{buf} argument, then @code{setvbuf}
3149 allocates a buffer itself using @code{malloc}.  This buffer will be freed
3150 when you close the stream.
3151
3152 Otherwise, @var{buf} should be a character array that can hold at least
3153 @var{size} characters.  You should not free the space for this array as
3154 long as the stream remains open and this array remains its buffer.  You
3155 should usually either allocate it statically, or @code{malloc}
3156 (@pxref{Unconstrained Allocation}) the buffer.  Using an automatic array
3157 is not a good idea unless you close the file before exiting the block
3158 that declares the array.
3159
3160 While the array remains a stream buffer, the stream I/O functions will
3161 use the buffer for their internal purposes.  You shouldn't try to access
3162 the values in the array directly while the stream is using it for
3163 buffering.
3164
3165 The @code{setvbuf} function returns zero on success, or a nonzero value
3166 if the value of @var{mode} is not valid or if the request could not
3167 be honored.
3168 @end deftypefun
3169
3170 @comment stdio.h
3171 @comment ANSI
3172 @deftypevr Macro int _IOFBF
3173 The value of this macro is an integer constant expression that can be
3174 used as the @var{mode} argument to the @code{setvbuf} function to
3175 specify that the stream should be fully buffered.
3176 @end deftypevr
3177
3178 @comment stdio.h
3179 @comment ANSI
3180 @deftypevr Macro int _IOLBF
3181 The value of this macro is an integer constant expression that can be
3182 used as the @var{mode} argument to the @code{setvbuf} function to
3183 specify that the stream should be line buffered.
3184 @end deftypevr
3185
3186 @comment stdio.h
3187 @comment ANSI
3188 @deftypevr Macro int _IONBF
3189 The value of this macro is an integer constant expression that can be
3190 used as the @var{mode} argument to the @code{setvbuf} function to
3191 specify that the stream should be unbuffered.
3192 @end deftypevr
3193
3194 @comment stdio.h
3195 @comment ANSI
3196 @deftypevr Macro int BUFSIZ
3197 The value of this macro is an integer constant expression that is good
3198 to use for the @var{size} argument to @code{setvbuf}.  This value is
3199 guaranteed to be at least @code{256}.
3200
3201 The value of @code{BUFSIZ} is chosen on each system so as to make stream
3202 I/O efficient.  So it is a good idea to use @code{BUFSIZ} as the size 
3203 for the buffer when you call @code{setvbuf}.
3204
3205 Actually, you can get an even better value to use for the buffer size
3206 by means of the @code{fstat} system call: it is found in the
3207 @code{st_blksize} field of the file attributes.  @xref{Attribute Meanings}.
3208
3209 Sometimes people also use @code{BUFSIZ} as the allocation size of
3210 buffers used for related purposes, such as strings used to receive a
3211 line of input with @code{fgets} (@pxref{Character Input}).  There is no
3212 particular reason to use @code{BUFSIZ} for this instead of any other
3213 integer, except that it might lead to doing I/O in chunks of an
3214 efficient size.
3215 @end deftypevr
3216
3217 @comment stdio.h
3218 @comment ANSI
3219 @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
3220 If @var{buf} is a null pointer, the effect of this function is
3221 equivalent to calling @code{setvbuf} with a @var{mode} argument of
3222 @code{_IONBF}.  Otherwise, it is equivalent to calling @code{setvbuf}
3223 with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size}
3224 argument of @code{BUFSIZ}.
3225
3226 The @code{setbuf} function is provided for compatibility with old code;
3227 use @code{setvbuf} in all new programs.
3228 @end deftypefun
3229
3230 @comment stdio.h
3231 @comment BSD
3232 @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
3233 If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
3234 Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
3235 buffer.  The @var{size} argument specifies the length of @var{buf}.
3236
3237 This function is provided for compatibility with old BSD code.  Use
3238 @code{setvbuf} instead.
3239 @end deftypefun
3240
3241 @comment stdio.h
3242 @comment BSD
3243 @deftypefun void setlinebuf (FILE *@var{stream})
3244 This function makes @var{stream} be line buffered, and allocates the
3245 buffer for you.
3246
3247 This function is provided for compatibility with old BSD code.  Use
3248 @code{setvbuf} instead.
3249 @end deftypefun
3250
3251 @node Other Kinds of Streams
3252 @section Other Kinds of Streams
3253
3254 The GNU library provides ways for you to define additional kinds of
3255 streams that do not necessarily correspond to an open file.
3256
3257 One such type of stream takes input from or writes output to a string.
3258 These kinds of streams are used internally to implement the
3259 @code{sprintf} and @code{sscanf} functions.  You can also create such a
3260 stream explicitly, using the functions described in @ref{String Streams}.
3261
3262 More generally, you can define streams that do input/output to arbitrary
3263 objects using functions supplied by your program.  This protocol is
3264 discussed in @ref{Custom Streams}.
3265
3266 @strong{Portability Note:} The facilities described in this section are
3267 specific to GNU.  Other systems or C implementations might or might not
3268 provide equivalent functionality.
3269
3270 @menu
3271 * String Streams::              Streams that get data from or put data in 
3272                                  a string or memory buffer.
3273 * Obstack Streams::             Streams that store data in an obstack.
3274 * Custom Streams::              Defining your own streams with an arbitrary
3275                                  input data source and/or output data sink.
3276 @end menu
3277
3278 @node String Streams
3279 @subsection String Streams
3280
3281 @cindex stream, for I/O to a string
3282 @cindex string stream
3283 The @code{fmemopen} and @code{open_memstream} functions allow you to do
3284 I/O to a string or memory buffer.  These facilities are declared in
3285 @file{stdio.h}.
3286 @pindex stdio.h
3287
3288 @comment stdio.h
3289 @comment GNU
3290 @deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
3291 This function opens a stream that allows the access specified by the
3292 @var{opentype} argument, that reads from or writes to the buffer specified
3293 by the argument @var{buf}.  This array must be at least @var{size} bytes long.
3294
3295 If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
3296 dynamically allocates (as with @code{malloc}; @pxref{Unconstrained
3297 Allocation}) an array @var{size} bytes long.  This is really only useful
3298 if you are going to write things to the buffer and then read them back
3299 in again, because you have no way of actually getting a pointer to the
3300 buffer (for this, try @code{open_memstream}, below).  The buffer is
3301 freed when the stream is open.
3302
3303 The argument @var{opentype} is the same as in @code{fopen}
3304 (@xref{Opening Streams}).  If the @var{opentype} specifies
3305 append mode, then the initial file position is set to the first null
3306 character in the buffer.  Otherwise the initial file position is at the
3307 beginning of the buffer.
3308
3309 When a stream open for writing is flushed or closed, a null character
3310 (zero byte) is written at the end of the buffer if it fits.  You
3311 should add an extra byte to the @var{size} argument to account for this.
3312 Attempts to write more than @var{size} bytes to the buffer result
3313 in an error.
3314
3315 For a stream open for reading, null characters (zero bytes) in the
3316 buffer do not count as ``end of file''.  Read operations indicate end of
3317 file only when the file position advances past @var{size} bytes.  So, if
3318 you want to read characters from a null-terminated string, you should
3319 supply the length of the string as the @var{size} argument.
3320 @end deftypefun
3321
3322 Here is an example of using @code{fmemopen} to create a stream for
3323 reading from a string:
3324
3325 @smallexample
3326 @include memopen.c.texi
3327 @end smallexample
3328
3329 This program produces the following output:
3330
3331 @smallexample
3332 Got f
3333 Got o
3334 Got o
3335 Got b
3336 Got a
3337 Got r
3338 @end smallexample
3339
3340 @comment stdio.h
3341 @comment GNU
3342 @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
3343 This function opens a stream for writing to a buffer.  The buffer is
3344 allocated dynamically (as with @code{malloc}; @pxref{Unconstrained
3345 Allocation}) and grown as necessary.
3346
3347 When the stream is closed with @code{fclose} or flushed with
3348 @code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
3349 contain the pointer to the buffer and its size.  The values thus stored
3350 remain valid only as long as no further output on the stream takes
3351 place.  If you do more output, you must flush the stream again to store
3352 new values before you use them again.
3353
3354 A null character is written at the end of the buffer.  This null character
3355 is @emph{not} included in the size value stored at @var{sizeloc}.
3356
3357 You can move the stream's file position with @code{fseek} (@pxref{File
3358 Positioning}).  Moving the file position past the end of the data
3359 already written fills the intervening space with zeroes.
3360 @end deftypefun
3361
3362 Here is an example of using @code{open_memstream}:
3363
3364 @smallexample
3365 @include memstrm.c.texi
3366 @end smallexample
3367
3368 This program produces the following output:
3369
3370 @smallexample
3371 buf = `hello', size = 5
3372 buf = `hello, world', size = 12
3373 @end smallexample
3374
3375 @c @group  Invalid outside @example.
3376 @node Obstack Streams
3377 @subsection Obstack Streams
3378
3379 You can open an output stream that puts it data in an obstack.
3380 @xref{Obstacks}.
3381
3382 @comment stdio.h
3383 @comment GNU
3384 @deftypefun {FILE *} open_obstack_stream (struct obstack *@var{obstack})
3385 This function opens a stream for writing data into the obstack @var{obstack}.
3386 This starts an object in the obstack and makes it grow as data is
3387 written (@pxref{Growing Objects}).
3388 @c @end group  Doubly invalid because not nested right.
3389
3390 Calling @code{fflush} on this stream updates the current size of the
3391 object to match the amount of data that has been written.  After a call
3392 to @code{fflush}, you can examine the object temporarily.
3393
3394 You can move the file position of an obstack stream with @code{fseek}
3395 (@pxref{File Positioning}).  Moving the file position past the end of
3396 the data written fills the intervening space with zeros.
3397
3398 To make the object permanent, update the obstack with @code{fflush}, and
3399 then use @code{obstack_finish} to finalize the object and get its address.
3400 The following write to the stream starts a new object in the obstack,
3401 and later writes add to that object until you do another @code{fflush}
3402 and @code{obstack_finish}.
3403
3404 But how do you find out how long the object is?  You can get the length
3405 in bytes by calling @code{obstack_object_size} (@pxref{Status of an
3406 Obstack}), or you can null-terminate the object like this:
3407
3408 @smallexample
3409 obstack_1grow (@var{obstack}, 0);
3410 @end smallexample
3411
3412 Whichever one you do, you must do it @emph{before} calling
3413 @code{obstack_finish}.  (You can do both if you wish.)
3414 @end deftypefun
3415
3416 Here is a sample function that uses @code{open_obstack_stream}:
3417
3418 @smallexample
3419 char *
3420 make_message_string (const char *a, int b)
3421 @{
3422   FILE *stream = open_obstack_stream (&message_obstack);
3423   output_task (stream);
3424   fprintf (stream, ": ");
3425   fprintf (stream, a, b);
3426   fprintf (stream, "\n");
3427   fclose (stream);
3428   obstack_1grow (&message_obstack, 0);
3429   return obstack_finish (&message_obstack);
3430 @}
3431 @end smallexample
3432
3433 @node Custom Streams
3434 @subsection Programming Your Own Custom Streams
3435 @cindex custom streams
3436 @cindex programming your own streams
3437
3438 This section describes how you can make a stream that gets input from an
3439 arbitrary data source or writes output to an arbitrary data sink
3440 programmed by you.  We call these @dfn{custom streams}.
3441
3442 @c !!! this does not talk at all about the higher-level hooks
3443
3444 @menu
3445 * Streams and Cookies::         The @dfn{cookie} records where to fetch or
3446                                  store data that is read or written. 
3447 * Hook Functions::              How you should define the four @dfn{hook
3448                                  functions} that a custom stream needs. 
3449 @end menu
3450
3451 @node Streams and Cookies
3452 @subsubsection Custom Streams and Cookies
3453 @cindex cookie, for custom stream
3454
3455 Inside every custom stream is a special object called the @dfn{cookie}.
3456 This is an object supplied by you which records where to fetch or store
3457 the data read or written.  It is up to you to define a data type to use
3458 for the cookie.  The stream functions in the library never refer
3459 directly to its contents, and they don't even know what the type is;
3460 they record its address with type @code{void *}.
3461
3462 To implement a custom stream, you must specify @emph{how} to fetch or
3463 store the data in the specified place.  You do this by defining
3464 @dfn{hook functions} to read, write, change ``file position'', and close
3465 the stream.  All four of these functions will be passed the stream's
3466 cookie so they can tell where to fetch or store the data.  The library
3467 functions don't know what's inside the cookie, but your functions will
3468 know.
3469
3470 When you create a custom stream, you must specify the cookie pointer,
3471 and also the four hook functions stored in a structure of type 
3472 @code{cookie_io_functions_t}.
3473
3474 These facilities are declared in @file{stdio.h}.
3475 @pindex stdio.h
3476
3477 @comment stdio.h
3478 @comment GNU
3479 @deftp {Data Type} {cookie_io_functions_t}
3480 This is a structure type that holds the functions that define the 
3481 communications protocol between the stream and its cookie.  It has
3482 the following members:
3483
3484 @table @code
3485 @item cookie_read_function_t *read
3486 This is the function that reads data from the cookie.  If the value is a
3487 null pointer instead of a function, then read operations on ths stream
3488 always return @code{EOF}.
3489
3490 @item cookie_write_function_t *write
3491 This is the function that writes data to the cookie.  If the value is a
3492 null pointer instead of a function, then data written to the stream is
3493 discarded.
3494
3495 @item cookie_seek_function_t *seek
3496 This is the function that performs the equivalent of file positioning on
3497 the cookie.  If the value is a null pointer instead of a function, calls
3498 to @code{fseek} on this stream can only seek to locations within the
3499 buffer; any attempt to seek outside the buffer will return an
3500 @code{ESPIPE} error.
3501
3502 @item cookie_close_function_t *close
3503 This function performs any appropriate cleanup on the cookie when
3504 closing the stream.  If the value is a null pointer instead of a
3505 function, nothing special is done to close the cookie when the stream is
3506 closed.
3507 @end table
3508 @end deftp
3509
3510 @comment stdio.h
3511 @comment GNU
3512 @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions})
3513 This function actually creates the stream for communicating with the
3514 @var{cookie} using the functions in the @var{io-functions} argument.
3515 The @var{opentype} argument is interpreted as for @code{fopen};
3516 see @ref{Opening Streams}.  (But note that the ``truncate on
3517 open'' option is ignored.)  The new stream is fully buffered.
3518
3519 The @code{fopencookie} function returns the newly created stream, or a null
3520 pointer in case of an error.
3521 @end deftypefun
3522
3523 @node Hook Functions
3524 @subsubsection Custom Stream Hook Functions
3525 @cindex hook functions (of custom streams)
3526
3527 Here are more details on how you should define the four hook functions
3528 that a custom stream needs.
3529
3530 You should define the function to read data from the cookie as:
3531
3532 @smallexample
3533 ssize_t @var{reader} (void *@var{cookie}, void *@var{buffer}, size_t @var{size})
3534 @end smallexample
3535
3536 This is very similar to the @code{read} function; see @ref{I/O
3537 Primitives}.  Your function should transfer up to @var{size} bytes into
3538 the @var{buffer}, and return the number of bytes read, or zero to
3539 indicate end-of-file.  You can return a value of @code{-1} to indicate
3540 an error.
3541
3542 You should define the function to write data to the cookie as:
3543
3544 @smallexample
3545 ssize_t @var{writer} (void *@var{cookie}, const void *@var{buffer}, size_t @var{size})
3546 @end smallexample
3547
3548 This is very similar to the @code{write} function; see @ref{I/O
3549 Primitives}.  Your function should transfer up to @var{size} bytes from
3550 the buffer, and return the number of bytes written.  You can return a
3551 value of @code{-1} to indicate an error.
3552
3553 You should define the function to perform seek operations on the cookie
3554 as:
3555
3556 @smallexample
3557 int @var{seeker} (void *@var{cookie}, fpos_t *@var{position}, int @var{whence})
3558 @end smallexample
3559
3560 For this function, the @var{position} and @var{whence} arguments are
3561 interpreted as for @code{fgetpos}; see @ref{Portable Positioning}.  In
3562 the GNU library, @code{fpos_t} is equivalent to @code{off_t} or
3563 @code{long int}, and simply represents the number of bytes from the
3564 beginning of the file.
3565
3566 After doing the seek operation, your function should store the resulting 
3567 file position relative to the beginning of the file in @var{position}.
3568 Your function should return a value of @code{0} on success and @code{-1}
3569 to indicate an error.
3570
3571 You should define the function to do cleanup operations on the cookie
3572 appropriate for closing the stream as:
3573
3574 @smallexample
3575 int @var{cleaner} (void *@var{cookie})
3576 @end smallexample
3577
3578 Your function should return @code{-1} to indicate an error, and @code{0}
3579 otherwise.
3580
3581 @comment stdio.h
3582 @comment GNU
3583 @deftp {Data Type} cookie_read_function
3584 This is the data type that the read function for a custom stream should have.
3585 If you declare the function as shown above, this is the type it will have.
3586 @end deftp
3587
3588 @comment stdio.h
3589 @comment GNU
3590 @deftp {Data Type} cookie_write_function
3591 The data type of the write function for a custom stream.
3592 @end deftp
3593
3594 @comment stdio.h
3595 @comment GNU
3596 @deftp {Data Type} cookie_seek_function
3597 The data type of the seek function for a custom stream.
3598 @end deftp
3599
3600 @comment stdio.h
3601 @comment GNU
3602 @deftp {Data Type} cookie_close_function
3603 The data type of the close function for a custom stream.
3604 @end deftp
3605
3606 @ignore
3607 Roland says:
3608
3609 @quotation
3610 There is another set of functions one can give a stream, the
3611 input-room and output-room functions.  These functions must
3612 understand stdio internals.  To describe how to use these
3613 functions, you also need to document lots of how stdio works
3614 internally (which isn't relevant for other uses of stdio).
3615 Perhaps I can write an interface spec from which you can write
3616 good documentation.  But it's pretty complex and deals with lots
3617 of nitty-gritty details.  I think it might be better to let this
3618 wait until the rest of the manual is more done and polished.
3619 @end quotation
3620 @end ignore
3621
3622 @c ??? This section could use an example.