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