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