Incorporated review comments from RMS.
[kopensolaris-gnu/glibc.git] / manual / stdio.texi
1 @node Input/Output on Streams
2 @chapter Input/Output on Streams
3 @pindex <stdio.h>
4
5 This chapter describes the functions for creating streams and performing
6 input and output operations on them.  As discussed in @ref{Input/Output
7 Overview}, a stream is a fairly abstract, high-level concept
8 representing a communications channel to a file, device, or process.
9
10 @strong{Incomplete:}  RMS suggests that a short example might be
11 useful here.
12
13 @menu
14 * Streams::                     About the data type representing a stream.
15 * Standard Streams::            Streams to the standard input and output 
16                                  devices are created for you.
17 * Opening and Closing Streams:: How to create a stream to talk to a file.
18 * Character Output::            Unformatted output by characters and lines.
19 * Character Input::             Unformatted input by characters and lines.
20 * Formatted Output::            @code{printf} and related functions.
21 * Customizing @code{printf}::   You can define new conversion specifiers for
22                                  @code{printf} and friends.
23 * Formatted Input::             @code{scanf} and related functions.
24 * Block Input/Output::          Input and output operations on blocks of data.
25 * End-Of-File and Errors::      How you can tell if an i/o error happens.
26 * File Positioning::            About random-access streams.
27 * Text and Binary Streams::     Some systems distinguish between text files
28                                  and binary files.
29 * Stream Buffering::            How to control buffering of streams.
30 * Temporary Files::             How to open a temporary file.
31 * Other Kinds of Streams::      How you can open additional kinds of
32                                  streams.
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 The @code{FILE} type is declared in the header file @file{<stdio.h>}.
48
49 @comment stdio.h
50 @comment ANSI
51 @deftp {Data Type} FILE
52 This is the data type is used to represent stream objects.  A
53 @code{FILE} object holds all of the internal state information about the
54 connection to the associated file, including such things as the file
55 position indicator and buffering information.  Each stream also has
56 error and end-of-file status indicators that can be tested with the
57 @code{ferror} and @code{feof} functions; @pxref{End-Of-File and Errors}.
58 @end deftp
59
60 @code{FILE} objects are allocated and managed internally by the
61 input/output library functions.  Don't try to create your own objects of
62 type @code{FILE}.  Instead, let the library do it.  Your programs should
63 deal only with pointers to these objects (that is, @code{FILE *} values)
64 rather than the objects themselves.
65
66
67 @node Standard Streams
68 @section Standard Streams
69
70 When the @code{main} function of your program is invoked, it already has
71 some predefined streams open and available for use.  These represent the
72 ``standard'' input and output channels that have been established for
73 the process.
74
75 These streams are declared in the header file @file{<stdio.h>}.
76
77 @comment stdio.h
78 @comment ANSI
79 @defvr {Macro} stdin
80 This macro expands into an expression of type @code{FILE *} that
81 represents the @dfn{standard input} stream, the normal source of input
82 for the program.
83 @end defvr
84 @cindex standard input
85
86 @comment stdio.h
87 @comment ANSI
88 @defvr {Macro} stdout
89 This macro expands into an expression of type @code{FILE *} that
90 represents the @dfn{standard output} stream, the destination for normal
91 output from the program.
92 @end defvr
93
94 @comment stdio.h
95 @comment ANSI
96 @defvr {Macro} stderr
97 This macro expands into an expression of type @code{FILE *} that
98 represents the @dfn{standard error} stream, the destination for error
99 and diagnostic messages issued by the program.
100 @end defvr
101
102 In the GNU system, you can specify what files or processes correspond to
103 these streams using the pipe and redirection facilities provided by the
104 shell.  (The primitives for implementating these facilities are
105 described in @ref{File System Interface}.)  Most other operating systems
106 provide similar mechanisms, but the details of how to use them can vary.
107
108 It is probably not a good idea to close any of these streams.
109
110
111 @node Opening and Closing Streams
112 @section Opening and Closing Streams
113
114 Opening a file with the @code{fopen} function creates a new stream and
115 establishes a connection between the stream and a file.  This may
116 involve creating a new file.  
117
118 When a stream is closed with @code{fclose}, the connection between the
119 stream and the file is removed.  After you have closed a stream, you
120 cannot perform any additional operations on it any more.
121
122 The functions in this section are declared in the header file
123 @file{<stdio.h>}.
124
125 @comment stdio.h
126 @comment ANSI
127 @deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype})
128 The @code{fopen} function opens the file named by the string
129 @var{filename}, and returns a pointer to a stream that is associated
130 with it.
131
132 The @var{opentype} argument is a string that controls how the file is
133 opened and specifies attributes of the resulting stream.  It must begin
134 with one of the following sequences of characters:
135
136 @table @code
137 @item "r"
138 Open existing file for reading only.
139
140 @item "w"
141 Open file for writing only.  If the file already exists, it is truncated
142 to zero length.  Otherwise a new file is created.
143
144 @item "a"
145 Open file for append access; that is, writing at the end of file only.
146 If the file already exists, its initial contents are unchanged and
147 output to the stream is appended to the end of the file.
148 Otherwise, a new, empty file is created.
149
150 @item "r+"
151 Open existing file for both reading and writing.  The initial contents
152 of the file are unchanged and the initial file position is at the
153 beginning of the file.
154
155 @item "w+"
156 Open file for both reading and writing.  If the file already exists, it
157 is truncated to zero length.  Otherwise, a new file is created.
158
159 @item "a+"
160 Open or create file for both reading and appending.  If the file exists,
161 its initial contents are unchanged.  Otherwise, a new file is
162 created.  The initial file position for reading might be at either
163 the beginning or end of the file, but output is always appended
164 to the end of the file.
165 @end table
166
167 Any of the above sequences can also be followed by a character @samp{b}
168 to indicate that a binary (rather than text) stream should be created;
169 @pxref{Text and Binary Streams}.  If both @samp{+} and @samp{b} are
170 specified, they can appear in either order.  For example, @code{"r+b"}
171 and @code{"rb+"} are equivalent; they both specify an existing binary
172 file being opened for both read and write access.
173
174 When a file is opened with the @samp{+} option for both reading and
175 writing, you must call either @code{fflush} (@pxref{Stream Buffering})
176 or a file positioning function such as @code{fseek} (@pxref{File
177 Positioning}) when switching back and forth between read and write
178 operations.  Otherwise, internal buffers might not be emptied properly.
179
180 Additional characters that follow these sequences specify other
181 implementation-specific file or stream attributes.
182
183 The GNU C Library defines only one additional attribute: if the
184 character @samp{x} is given, this specifies exclusive use of a new file.
185 This is equivalent to the @code{O_EXCL} option to the @code{open}
186 function (@pxref{File Status Flags}).  Any other characters are simply
187 ignored.
188
189 Other systems may define other character sequences to specify things
190 like a record size or access control specification.
191
192 If the open fails, @code{fopen} returns a null pointer.
193 @end deftypefun
194
195 You can have multiple streams (or file descriptors) pointing to the same
196 file open at the same time.  If you do only input, this works fine, but
197 you can get unpredictable results if you are writing to the file.  The
198 file locking facilities can be useful in this context; @pxref{File
199 Locks}.
200
201
202 @comment stdio.h
203 @comment ANSI
204 @defvr {Macro} FOPEN_MAX
205 The value of this macro is an integer constant expression that
206 represents the minimum number of streams that the implementation
207 guarantees can be open simultaneously.  The value of this constant is at
208 least eight, which includes the three standard streams @code{stdin},
209 @code{stdout}, and @code{stderr}.
210 @end defvr
211
212 @comment stdio.h
213 @comment ANSI
214 @deftypefun int fclose (FILE *@var{stream})
215 This function causes @var{stream} to be closed and the connection to
216 the corresponding file to be broken.  Any buffered output is written
217 and any buffered input is discarded.  The @code{fclose} function returns
218 a value of @code{0} if the file was closed successfully, and @code{EOF}
219 if an error was detected.
220 @end deftypefun
221
222 If the @code{main} function to your program returns, or if you call the
223 @code{exit} function (@pxref{Normal Program Termination}), all open
224 streams are automatically closed properly.  If your program terminates
225 in any other manner, such as by calling the @code{abort} function
226 (@pxref{Aborting a Program}) or from a fatal signal (@pxref{Signal
227 Handling}), open streams might not be closed properly.  Buffered output
228 may not be flushed and files may not be complete.  For more information
229 on buffering of streams, @pxref{Stream Buffering}.
230
231 @comment stdio.h
232 @comment ANSI
233 @deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
234 This function is like a combination of @code{fclose} and @code{fopen}.
235 It first closes the stream referred to by @var{stream}, ignoring any
236 errors that are detected in the process.  Then the file named by
237 @var{filename} is opened with mode @var{opentype} as for @code{fopen}, and
238 associated with the same stream object @var{stream}.  If the operation
239 fails, a null pointer is returned; otherwise, @code{freopen} returns
240 @var{stream}.
241 @end deftypefun
242
243
244 @node Character Output
245 @section Character Output
246
247 This section describes functions for performing character- and
248 line-oriented output.  Largely for historical compatibility, there are
249 several variants of these functions, but as a matter of style (and for
250 simplicity!) it's suggested that you stick with using @code{fputc} and
251 @code{fputs}, and perhaps @code{putc} and @code{putchar}.
252
253 These functions are declared in the header file @file{<stdio.h>}.
254
255 @comment stdio.h
256 @comment ANSI
257 @deftypefun int fputc (int @var{c}, FILE *@var{stream})
258 The @code{fputc} function converts the character @var{c} to type
259 @code{unsigned char}, and writes it to the stream @var{stream}.  
260 @code{EOF} is returned if a write error occurs; otherwise the
261 character @var{c} is returned.
262 @end deftypefun
263
264 @comment stdio.h
265 @comment ANSI
266 @deftypefun int putc (int @var{c}, FILE *@var{stream})
267 This is just like @code{fputc}, except that it is permissible (and
268 typical) for it to be implemented as a macro that evaluates the
269 @var{stream} argument more than once.  (Of course, @code{fputc} can be
270 implemented as a macro too, but only in such a way that it doesn't
271 evaluate its arguments more than once.)
272 @end deftypefun
273
274 @comment stdio.h
275 @comment ANSI
276 @deftypefun int putchar (int @var{c})
277 The @code{putchar} function is equivalent to @code{fputc} with
278 @code{stdout} as the value of the @var{stream} argument.
279 @end deftypefun
280
281 @comment stdio.h
282 @comment ANSI
283 @deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
284 The function @code{fputs} writes the string @var{s} to the stream
285 @var{stream}.  The terminating null character is not written.
286 This function does @emph{not} add a newline character, either.
287
288 This function returns @code{EOF} if a write error occurs, and otherwise
289 a non-negative value.
290 @end deftypefun
291
292 @comment stdio.h
293 @comment ANSI
294 @deftypefun int puts (const char *@var{s})
295 The @code{puts} function writes the string @var{s} to the stream
296 @code{stdout}.  The terminating null character is not written, but
297 a newline character is appended to the output; this differs from
298 @code{fputs}, which does not add a newline.
299 @end deftypefun
300
301 @comment stdio.h
302 @comment SVID
303 @deftypefun int putw (int @var{w}, FILE *@var{stream})
304 This function writes the word @var{w} (that is, an @code{int}) to
305 @var{stream}.  It's provided for compatibility with SVID.
306 @end deftypefun
307
308 @node Character Input
309 @section Character Input
310
311 This section describes functions for performing character- and
312 line-oriented input.  Again, there are several variants of these
313 functions, some of which are considered obsolete stylistically.
314 It's suggested that you stick with @code{fgetc}, @code{fgets}, and
315 maybe @code{ungetc}, @code{getc}, and @code{getchar}.
316
317 These functions are declared in the header file @file{<stdio.h>}.
318
319 @comment stdio.h
320 @comment ANSI
321 @deftypefun int fgetc (FILE *@var{stream})
322 This function reads the next character as an @code{unsigned char} from
323 the stream @var{stream} and returns its value, converted to an
324 @code{int}.  If an end-of-file condition or read error occurs,
325 @code{EOF} is returned instead.
326 @end deftypefun
327
328 @comment stdio.h
329 @comment ANSI
330 @deftypefun int getc (FILE *@var{stream})
331 This is just like @code{fgetc}, except that it is permissible (and typical)
332 for it to be implemented as a macro that evaluates the @var{stream}
333 argument more than once.
334 @end deftypefun
335
336 @comment stdio.h
337 @comment ANSI
338 @deftypefun int getchar (void)
339 The @code{getchar} function is equivalent to @code{fgetc} with @code{stdin}
340 as the value of the @var{stream} argument.
341 @end deftypefun
342
343 @comment stdio.h
344 @comment ANSI
345 @deftypefun int ungetc (int @var{c}, FILE *@var{stream})
346 The @code{ungetc} function is provided to support a limited form of
347 input lookahead.  The character @var{c} (which must not be @code{EOF})
348 is ``pushed back'' onto the input stream @var{stream}, where it can be
349 read back in again.
350
351 The character that you push back doesn't have to be the same as the last
352 character that was actually read from the stream.  In fact, it isn't
353 necessary to actually read any characters from the stream before
354 unreading them with @code{ungetc}!
355
356 The GNU C Library only supports one character of pushback.  Other
357 systems might let you push back multiple characters; in such
358 implementations, reading from the stream retrieves the characters in the
359 reverse order that they were pushed.
360
361 Pushing back characters doesn't alter the file; only the internal
362 buffering for the stream is affected.  If a file positioning function
363 (such as @code{fseek} or @code{rewind}; @pxref{File Positioning}) is
364 called, any unread pushed-back characters are discarded.
365
366 If the stream is at end-of-file when a character is pushed back, the
367 end-of-file indicator for the stream is cleared.
368 @end deftypefun
369
370 Here is an example showing the use of @code{getc} and @code{ungetc}
371 to skip over whitespace characters.  The first non-whitespace character
372 read is pushed back, so it can be seen again on the next read operation
373 on the stream.
374
375 @example
376 #include <stdio.h>
377
378 void skip_whitespace (FILE *stream)
379 @{
380   int c;
381   do @{
382     c = getc (stream);
383     if (c == EOF) return;
384   @} while (isspace (c));
385   ungetc (c, stream);
386 @}
387 @end example
388
389
390 @comment stdio.h
391 @comment ANSI
392 @deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
393 The @code{fgets} function reads characters from the stream @var{stream}
394 up to and including a newline character and stores them in the string
395 @var{s}.  At most, one less than @var{count} characters will be read;
396 since a null character is added to mark the end of the string,
397 @var{count} effectively specifies the minimum allocation size for the
398 string @var{s}.
399
400 In the event of an end-of-file condition, if no characters have yet been
401 read, then the contents of the array @var{s} are unchanged and a null
402 pointer is returned.  A null pointer is also returned if a read error
403 occurs.  Otherwise, the return value is the pointer @var{s}.
404 @end deftypefun
405
406 @comment stdio.h
407 @comment ANSI
408 @deftypefun {char *} gets (char *@var{s})
409 The function @code{gets} reads characters from the stream @code{stdin}
410 up to the next newline character, and stores them in the string @var{s}.
411 The newline character is discarded (note that this differs from the
412 behavior of @code{fgets}, which copies the newline character into the
413 string).
414
415 @strong{Warning:}  The @code{gets} function is @strong{very dangerous} 
416 because it provides no protection against overflowing the string @var{s}.
417 The GNU Library includes it for compatibility only.  You should 
418 @strong{always} use @code{fgets} instead.
419 @end deftypefun
420
421 @comment stdio.h
422 @comment SVID
423 @deftypefun int getw (FILE *@var{stream})
424 This function reads a word (that is, an @code{int}) from @var{stream}.
425 It's provided for compatibility with SVID.
426 @end deftypefun
427
428
429 @node Formatted Output
430 @section Formatted Output
431
432 @cindex format string, for @code{printf}
433 @cindex template, for @code{printf}
434 @cindex formatted output
435 The functions described in this section (@code{printf} and related
436 functions) provide a convenient way to perform formatted output.  You
437 call @code{printf} with a @dfn{format string} or @dfn{template} that
438 specifies how to print the values of the remaining arguments.
439
440 Unless your program is a filter that specifically performs line- or
441 character-oriented processing, using @code{printf} or one of the other
442 related functions described in this section is almost always the easiest
443 and most concise way to handle program output.  These functions are
444 especially useful for printing messages, tables of data, and the like.
445
446 @menu
447 * Formatted Output Basics::             Some examples to get you started.
448 * Output Conversion Syntax::            General syntax of conversion
449                                          specifications.
450 * Table of Output Conversions::         Summary of output conversions and
451                                          what they do.
452 * Integer Conversions::                 Details about formatting of integers.
453 * Floating-Point Conversions::          Details about formatting of
454                                          floating-point numbers.
455 * Other Output Conversions::            Details about formatting of strings,
456                                          characters, pointers, and the like.
457 * Formatted Output Functions::          Descriptions of the actual functions.
458 * Variable Arguments Output Functions:: More functions.
459 @end menu
460
461 @node Formatted Output Basics
462 @subsection Formatted Output Basics
463
464 The @code{printf} function can be used to print any number of arguments.
465 The format template string argument you supply in a call provides
466 information not only about the number of additional arguments, but also
467 about their types and what style should be used for printing them.
468
469 Ordinary characters in the template string are simply written to the
470 output stream as-is, while @dfn{conversion specifications} introduced by
471 a @samp{%} character in the template cause subsequent arguments to be
472 formatted and written to the output stream.  For example,
473 @cindex conversion specifications (printf)
474
475 @example
476 int pct = 37;
477 char filename[] = "foo.txt";
478 printf ("Processing of %s is %d%% finished.\nPlease be patient.\n",
479         filename, pct);
480 @end example
481
482 @noindent
483 produces output like
484
485 @example
486 Processing of foo.txt is 37% finished.
487 Please be patient.
488 @end example
489
490 This example shows the use of the @samp{%d} conversion to specify that
491 an @code{int} argument should be printed in decimal notation, the
492 @samp{%s} conversion to specify printing of a string argument, and
493 the @samp{%%} conversion to print a literal @samp{%} character.
494
495 There are also conversions for printing an integer argument as an
496 unsigned value in octal, decimal, or hexadecimal radix (@samp{%o},
497 @samp{%u}, or @samp{%x}, respectively); or as a character value
498 (@samp{%c}).
499
500 Floating-point numbers can be printed in normal, fixed-point notation
501 using the @samp{%f} conversion or in exponential notation using the
502 @samp{%e} conversion.  The @samp{%g} conversion uses either @samp{%e}
503 or @samp{%f} format, depending on what is more appropriate for the
504 magnitude of the particular number.
505
506 The syntax of conversion specifications actually permits you to put a
507 bunch of options between the @samp{%} and the character that indicates
508 which conversion to apply.  These options modify the ordinary behavior
509 of the conversion.  For example, most conversion specifications permit
510 you to specify a minimum field width and a flag indicating whether you
511 want the result left- or right-justified within the field.
512
513 The specific flags and modifiers that are permitted and their
514 interpretation vary depending on the particular conversion.  They're all
515 described in more detail in the following sections.  Don't worry if this
516 all seems excessively complicated at first; you can almost always get
517 reasonable free-format output without using any of the modifiers at all.
518 The modifiers are mostly used to make the output look ``prettier'' in
519 tables.
520
521 @node Output Conversion Syntax
522 @subsection Output Conversion Syntax
523
524 This section provides details about the precise syntax of conversion
525 specifications that can appear in a @code{printf} format template
526 string.
527
528 Characters in the format template string that are not part of a
529 conversion specification are printed as-is to the output stream.
530 Multibyte character sequences (@pxref{Extended Characters}) are permitted in
531 a format template string.
532
533 The conversion specifications in a @code{printf} format template have
534 the general form:
535
536 @example
537 % @var{flags} @var{width} . @var{precision} @var{type} @var{conversion}
538 @end example
539
540 For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-}
541 is a flag, @samp{10} specifies the field width, the precision is
542 @samp{8}, the letter @samp{l} is a type modifier, and @samp{d} specifies
543 the conversion style.  (What this particular type specifier says is to
544 print a @code{long int} argument in decimal notation, with a minimum of
545 8 digits left-justified in a field at least 10 characters wide.)
546
547 More specifically, output conversion specifications consist of an
548 initial @samp{%} character followed in sequence by:
549
550 @itemize @bullet
551 @item 
552 Zero or more @dfn{flag characters} that modify the normal behavior of
553 the conversion specification.
554 @cindex flag character (printf)
555
556 @item 
557 An optional decimal integer specifying the @dfn{minimum field width}.
558 If the normal conversion produces fewer characters than this, the field
559 is padded with spaces to the specified width.  This is a @emph{minimum}
560 value; if the normal conversion produces more characters than this, the
561 field is @emph{not} truncated.  Normally, the output is right-justified
562 within the field.
563 @cindex minimum field width (printf)
564
565 The GNU library's version of @code{printf} also allows you to specify a
566 field width of @samp{*}.  This means that the next argument in the
567 argument list (before the actual value to be printed) is used as the
568 field width.  The value must be an @code{int}.  Other versions of C may
569 not recognize this syntax.
570
571 @item 
572 An optional @dfn{precision} to specify the number of digits to be
573 written for the numeric conversions.  If the precision is specified, it
574 consists of a period (@samp{.}) followed optionally by a decimal integer
575 (which defaults to zero if omitted).
576 @cindex precision (printf)
577
578 The GNU library's version of @code{printf} also allows you to specify a
579 precision of @samp{*}.  This means that the next argument in the
580 argument list (before the actual value to be printed) is used as the
581 precision.  The value must be an @code{int}.  If you specify @samp{*}
582 for both the field width and precision, the field width argument precedes
583 the precision argument.  Other versions of C may not recognize this syntax.
584
585 @item
586 An optional @dfn{type modifier character}, which is used to specify the
587 data type of the corresponding argument if it differs from the default
588 type.  (For example, the integer conversions assume a type of @code{int},
589 but you can use the same conversions with a type modifier to print
590 @code{long int} or @code{short int} objects.)
591 @cindex type modifier character (printf)
592
593 @item
594 A character that specifies the conversion to be applied.
595 @end itemize
596
597 The exact options that are permitted and how they are interpreted vary 
598 between the different conversion specifiers.  See the descriptions of the
599 individual conversions for information about the particular options that
600 they use.
601
602 @node Table of Output Conversions
603 @subsection Table of Output Conversions
604
605 Here is a table summarizing what all the different conversions do:
606
607 @table @asis
608 @item @samp{%d}, @samp{%i}
609 Print an integer as a signed decimal number.  @xref{Integer
610 Conversions}, for details on all the options.
611
612 @item @samp{%o}
613 Print an integer as an unsigned octal number.  @xref{Integer
614 Conversions}, for details on all the options.
615
616 @item @samp{%u}
617 Print an integer as an unsigned decimal number.  @xref{Integer
618 Conversions}, for details on all the options.
619
620 @item @samp{%x}, @samp{%X}
621 Print an integer as an unsigned hexadecimal number.  @xref{Integer
622 Conversions}, for details on all the options.
623
624 @item @samp{%f}
625 Print a floating-point number in normal (fixed-point) notation.
626 @xref{Floating-Point Conversions}, for details on all the options.
627
628 @item @samp{%e}, @samp{%E}
629 Print a floating-point number in exponential notation.
630 @xref{Floating-Point Conversions}, for details on all the options.
631
632 @item @samp{%g}, @samp{%G}
633 Print a floating-point number in either normal or exponential notation,
634 whichever is more appropriate for its magnitude.  @xref{Floating-Point
635 Conversions}, for details on all the options.
636
637 @item @samp{%c}
638 Print a single character.  @xref{Other Output Conversions}.
639
640 @item @samp{%s}
641 Print a string).  @xref{Other Output Conversions}.
642
643 @item @samp{%p}
644 Print the value of a pointer.  @xref{Other Output Conversions}.
645
646 @item @samp{%n}
647 Get the number of characters printed so far.  @xref{Other Output Conversions}.
648
649 @item @samp{%%}
650 Print a literal @samp{%} character.  @xref{Other Output Conversions}.
651 @end table
652
653 @strong{Incomplete:} There also seems to be a @samp{Z} conversion for
654 printing a @code{size_t} value in decimal notation.  Is this something
655 we want to publicize?
656
657 If the syntax of a conversion specification is invalid, the behavior is
658 undefined.  If there aren't enough function arguments provided to supply
659 values for all the conversion specifications in the format template, or
660 if the arguments are not of the correct types, the behavior is also
661 undefined.  On the other hand, if you supply more arguments than
662 conversion specifications, the extra argument values are simply ignored;
663 but this is not really a good style to use.
664
665 @node Integer Conversions
666 @subsection Integer Conversions
667
668 This section describes the options for the @samp{%d}, @samp{%i},
669 @samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
670 specifications.  These conversions print integers in various formats.
671
672 The @samp{%d} and @samp{%i} conversion specifications both print an
673 @code{int} argument as a signed decimal number; while @samp{%o},
674 @samp{%u}, and @samp{%x} print the argument as an unsigned octal,
675 decimal, or hexadecimal number (respectively).  The @samp{%X} conversion
676 specification is just like @samp{%x} except that it uses the characters
677 @samp{ABCDEF} as digits instead of @samp{abcdef}.
678
679 The following flags can be provided:
680
681 @table @asis
682 @item @samp{-}
683 Left-justify the result in the field (instead of the normal
684 right-justification).
685
686 @item @samp{+}
687 For the signed @samp{%d} and @samp{%i} conversions, always include a
688 plus or minus sign in the result.
689
690 @item @samp{ }
691 For the signed @samp{%d} and @samp{%i} conversions, if the result
692 doesn't start with a plus or minus sign, prefix it with a space
693 character instead.  Since the @samp{+} flag ensures that the result
694 includes a sign, this flag is ignored if you supply both of them.
695
696 @item @samp{#}
697 For the @samp{%o} conversion, this forces the leading digit to be @samp{0},
698 as if by increasing the precision.  For @samp{%x} or @samp{%X}, this
699 prefixes a leading @samp{0x} or @samp{0X} (respectively) to the result.
700 This doesn't do anything useful for the @samp{%d}, @samp{%i}, or @samp{%u}
701 conversions.
702
703 @item @samp{0}
704 Pad the field with zeros instead of spaces.  The zeros are placed after
705 any indication of sign or base.  This flag is ignored if the @samp{-}
706 flag is also specified, or if a precision is specified.
707 @end table
708
709 If a precision is supplied, it specifies the minimum number of digits to
710 appear; leading zeros are produced if necessary.  The precision defaults
711 to @code{1}.  If you convert a value of zero with a precision of zero,
712 then no characters at all are produced.
713
714 Without a type modifier, the corresponding argument is treated as an
715 @code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
716 @code{unsigned int} (for the unsigned conversions @samp{%o}, @samp{%u},
717 @samp{%x}, and @samp{%X}).  Recall that since @code{printf} and friends
718 are variadic, optional @code{char} and @code{short} arguments are
719 already upgraded to @code{int} by the default argument promotions.
720
721 @table @samp
722 @item h
723 Specifies that the argument is a @code{short int} or @code{unsigned
724 short int}, as appropriate.  A @code{short} argument is converted to an
725 @code{int} or @code{unsigned int} by the default argument promotions
726 anyway, but the @samp{h} modifier says to convert it back to a
727 @code{short} again.
728
729 @item l
730 Specifies that the argument is a @code{long int} or @code{unsigned long
731 int}, as appropriate.  
732
733 @item L
734 Specifies that the argument is a @code{long long int}.  (This type is
735 an extension supported by the GNU C compiler.  On systems that don't
736 support extra-long integers, this is the same as @code{long int}.)
737 @end table
738
739 For example, using the format string:
740
741 @example
742 |%5d|%-5d|%+5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
743 @end example
744
745 @noindent
746 to print numbers using the different options for the @samp{%d}
747 conversion gives results like:
748
749 @example
750 |    0|0    |   +0|    0|00000|     |   00|0|
751 |    1|1    |   +1|    1|00001|    1|   01|1|
752 |   -1|-1   |   -1|   -1|-0001|   -1|  -01|-1|
753 |100000|100000|+100000| 100000|100000|100000|100000|100000|
754 @end example
755
756 In particular, notice what happens in the last case where the number
757 is too large to fit in the minimum field width specified.
758
759 Here are some more examples showing how unsigned integers print under
760 various format options, using the format string:
761
762 @example
763 "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
764 @end example
765
766 @example
767 |    0|    0|    0|    0|    0|  0x0|  0X0|0x00000000|
768 |    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
769 |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
770 @end example
771
772
773 @node Floating-Point Conversions
774 @subsection Floating-Point Conversions
775
776 This section discusses the conversion specifications for formatting
777 floating-point numbers: the @samp{%f}, @samp{%e}, @samp{%E},
778 @samp{%g}, and @samp{%G} conversions.
779
780 The @samp{%f} conversion prints its argument in fixed-point notation,
781 producing output of the form
782 [@code{-}]@var{ddd}@code{.}@var{ddd},
783 where the number of digits following the decimal point is controlled
784 by the precision.
785
786 The @samp{%e} conversion prints its argument in exponential notation,
787 producing output of the form
788 [@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}.
789 Again, the number of digits following the decimal point is controlled by
790 the precision.  The exponent always contains at least two digits.  The
791 @samp{%E} conversion is similar but the exponent is marked with the letter
792 @samp{E} instead of @samp{e}.
793
794 The @samp{%g} and @samp{%G} conversions print the argument in the style
795 of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
796 than -4 or greater than or equal to the precision.  Trailing zeros are
797 removed from the fractional portion of the result and a decimal-point
798 character appears only if it is followed by a digit.
799
800 The following flags can be used to modify the behavior:
801
802 @table @asis
803 @item @samp{-}
804 Left-justify the result in the field.  Normally the result is
805 right-justified.
806
807 @item @samp{+}
808 Always include a plus or minus sign in the result.
809
810 @item @samp{ }
811 If the result doesn't start with a plus or minus sign, prefix it with a
812 space instead.  Since the @samp{+} flag ensures that the result includes
813 a sign, this flag is ignored if you supply both of them.
814
815 @item @samp{#}
816 Specifies that the result should always include a decimal point, even
817 if no digits follow it.  For the @samp{%g} and @samp{%G} conversions,
818 this also forces trailing zeros after the decimal point to be left
819 in place where they would otherwise be removed.
820
821 @item @samp{0}
822 Pad the field with zeros instead of spaces; the zeros are placed
823 after any sign.  This flag is ignored if the @samp{-} flag is also
824 specified.
825 @end table
826
827 The precision specifies how many digits follow the decimal-point
828 character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions.  For
829 these conversions, the default is @code{6}.  If the precision is
830 explicitly @code{0}, this has the rather strange effect of suppressing
831 the decimal point character entirely!  For the @samp{%g} and @samp{%G}
832 conversions, the precision specifies how many significant digits to
833 print; if @code{0} or not specified, it is treated like a value of
834 @code{1}.
835
836 Without a type modifier, the floating-point conversions use an argument
837 of type @code{double}.  (By the default argument conversions, any
838 @code{float} arguments are automatically promoted to @code{double}.)
839 The following type modifier is supported:
840
841 @table @samp
842 @item L
843 An uppercase @samp{L} specifies that the argument is a @code{long
844 double}.
845 @end table
846
847 Here are some examples showing how numbers print using the various
848 floating-point conversions.  All of the numbers were printed using
849 the format string:
850
851 @example
852 "|%12.4f|%12.4e|%12.4g|\n"
853 @end example
854
855 Here is the output:
856
857 @example
858 |      0.0000|  0.0000e+00|           0|
859 |      1.0000|  1.0000e+00|           1|
860 |     -1.0000| -1.0000e+00|          -1|
861 |    100.0000|  1.0000e+02|         100|
862 |   1000.0000|  1.0000e+03|        1000|
863 |  10000.0000|  1.0000e+04|       1e+04|
864 |  12345.0000|  1.2345e+04|   1.234e+04|
865 | 100000.0000|  1.0000e+05|       1e+05|
866 | 123456.0000|  1.2346e+05|   1.234e+05|
867 @end example
868
869 Notice how the @samp{%g} conversion drops trailing zeros.
870
871 @node Other Output Conversions
872 @subsection Other Output Conversions
873
874 This section describes miscellaneous conversions for @code{printf}.
875
876 The @samp{%c} conversion prints a single character.  The @code{int}
877 argument is first converted to an @code{unsigned char}.  The @samp{-}
878 flag can be used to specify left-justification in the field, but no
879 other flags are defined, and no precision or type modifier can be given.
880
881 The @samp{%s} conversion prints a string.  The corresponding argument
882 must be of type @code{char *}.  A precision can be specified to indicate
883 the maximum number of characters to write; otherwise characters in the
884 string up to but not including the terminating null character are
885 written to the output stream.  The @samp{-} flag can be used to specify
886 left-justification in the field, but no other flags or type modifiers
887 are defined for this conversion.
888
889 If you accidentally pass a null pointer as the argument for a @samp{%s}
890 conversion, the GNU library will print it as @samp{(null)}.  This is more
891 because this is such a common program bug than because you ought to depend
892 on this behavior in normal use, however.
893
894 The @samp{%p} conversion prints a pointer value.  The corresponding
895 argument must be of type @code{void *}.
896
897 In the GNU system, non-null pointers are printed as unsigned integers,
898 as if a @samp{%#x} conversion were used.  Null pointers print as
899 @samp{(nil)}.  (Pointers might print differently in other systems.)
900
901 Again, you can supply the @samp{-} flag with the @samp{%p} conversion to
902 specify left-justification but no other flags, precision, or type
903 modifiers are defined.
904
905 The @samp{%n} conversion is unlike any of the other output conversions.
906 It uses an argument which must be a pointer to an @code{int}, but
907 instead of printing anything it stores the number of characters printed
908 so far by this call at that location.  The @samp{h} and @samp{l} type
909 modifiers are permitted to specify that the argument is of type
910 @code{short int *} or @code{long int *} instead of @code{int *}, but no
911 flags, field width, or precision are permitted.
912
913 For example,
914
915 @example
916 int nchar;
917 printf ("%d %s%n\n", 3, "bears", &nchar);
918 @end  example
919
920 @noindent
921 prints:
922
923 @example
924 3 bears
925 @end example
926
927 @noindent
928 and sets @code{nchar} to @code{7}.
929
930
931 The @samp{%%} conversion prints a literal @samp{%} character.  This
932 conversion doesn't use an argument, and no flags, field width,
933 precision, or type modifiers are permitted.
934
935
936 @node Formatted Output Functions
937 @subsection Formatted Output Functions
938
939 This section describes how to call @code{printf} and related functions.
940 Prototypes for these functions are in the header file @file{<stdio.h>}.
941
942 @comment stdio.h
943 @comment ANSI
944 @deftypefun int printf (const char *@var{template}, @dots{})
945 The @code{printf} function prints the optional arguments under the
946 control of the format template @var{template} to the stream
947 @code{stdout}.  It returns the number of characters printed, or a
948 negative value if there was an output error.
949 @end deftypefun
950
951 @comment stdio.h
952 @comment ANSI
953 @deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
954 This function is just like @code{printf}, except that the output is
955 written to the stream @var{stream} instead of @code{stdout}.
956 @end deftypefun
957
958 @comment stdio.h
959 @comment ANSI
960 @deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
961 This is like @code{printf}, except that the output is stored in the character
962 array @var{s} instead of written to a stream.  A null character is written
963 to mark the end of the string.
964
965 The @code{sprintf} function returns the number of characters stored in
966 the array @var{s}, not including the terminating null character.
967
968 The behavior of this function is undefined if copying takes place
969 between objects that overlap --- for example, if @var{s} is also given
970 as an argument to be printed under control of the @samp{%s} conversion.
971 @xref{Copying and Concatenation}.
972
973 @strong{Warning:} The @code{sprintf} function can be @strong{dangerous}
974 because it can potentially output more characters than will fit in the
975 allocation size of the string @var{s}.  Remember that the field width
976 given in a conversion specification is only a @emph{minimum} value.  The
977 @code{snprintf} function lets you specify the maximum number of
978 characters to produce.
979 @end deftypefun
980
981 @comment stdio.h
982 @comment GNU
983 @deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{})
984 The @code{snprintf} function is similar to @code{sprintf}, except that
985 the @var{size} argument specifies the maximum number of characters to
986 produce.  The trailing null character is counted towards this limit, so
987 the largest value you should specify is the allocation size of the array
988 @var{s}.
989 @end deftypefun
990
991 @strong{Incomplete:}  RMS suggests putting an example here.
992
993 @comment stdio.h
994 @comment GNU
995 @deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
996 This function is similar to @code{sprintf}, except that it dynamically
997 allocates a string (as with @code{malloc}; @pxref{Unconstrained
998 Allocation}) to hold the output, instead of putting the output in a
999 buffer you allocate in advance.  The @var{ptr} argument should be the
1000 address of a @code{char *} object, and @code{asprintf} stores a pointer
1001 to the newly allocated string at that location.
1002 @end deftypefun
1003
1004 @strong{Incomplete:}  RMS suggests putting an example here.
1005
1006 @node Variable Arguments Output Functions
1007 @subsection Variable Arguments Output Functions
1008
1009 The functions @code{vprintf} and friends are provided so that you can
1010 define your own variadic @code{printf}-like functions that make use of
1011 the same internals as the built-in formatted output functions.  Since
1012 the C language does not have an operator similar to the Lisp
1013 @code{apply} function that permits a function call (as opposed to a
1014 function definition) with a non-constant number of arguments, there's
1015 simply no way for one variadic function to pass the tail of its argument
1016 list to another variadic function; the second function has to be defined
1017 in such a way that it takes a @code{va_list} argument instead.
1018
1019 Before calling @code{vprintf} or the other functions listed in this
1020 section, you @emph{must} call @code{va_start} (@pxref{Variable Argument
1021 Facilities}) to initialize @var{ap}, and you @emph{may} call
1022 @code{va_arg} to skip over some of the initial arguments.  The
1023 @code{vprintf} function does not invoke the @code{va_end} macro, but
1024 further calls to @code{va_arg} with @var{ap} are not permitted once
1025 @code{vprintf} returns.
1026
1027 Prototypes for these functions are declared in @file{<stdio.h>}.
1028
1029 @comment stdio.h
1030 @comment ANSI
1031 @deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
1032 This function is similar to @code{printf} except that, instead of taking
1033 a variable number of arguments directly, it takes an argument list
1034 pointer @var{ap}.
1035
1036 @end deftypefun
1037
1038 @comment stdio.h
1039 @comment ANSI
1040 @deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
1041 This is the equivalent of @code{fprintf} with the variable argument list
1042 specified directly as for @code{vprintf}.
1043 @end deftypefun
1044
1045 @comment stdio.h
1046 @comment ANSI
1047 @deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
1048 This is the equivalent of @code{sprintf} with the variable argument list
1049 specified directly as for @code{vprintf}.
1050 @end deftypefun
1051
1052 @comment stdio.h
1053 @comment GNU
1054 @deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
1055 This is the equivalent of @code{snprintf} with the variable argument list
1056 specified directly as for @code{vprintf}.
1057 @end deftypefun
1058
1059 @comment stdio.h
1060 @comment GNU
1061 @deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
1062 The @code{vasprintf} function is the equivalent of @code{asprintf} with the
1063 variable argument list specified directly as for @code{vprintf}.
1064 @end deftypefun
1065
1066 Here's an example showing how you might use @code{vfprintf}.  This is a
1067 function that prints error messages to the stream @code{stderr}, along
1068 with a prefix indicating the name of the program.
1069
1070 @example
1071 #include <stdio.h>
1072 #include <stdarg.h>
1073
1074 void eprintf (char *template, ...)
1075 @{
1076   va_list ap;
1077   extern char *program_name;
1078
1079   fprintf (stderr, "%s: ", program_name);
1080   va_start (ap, count);
1081   vfprintf (stderr, template, ap);
1082   va_end (ap);
1083 @}
1084 @end example
1085
1086 @noindent
1087 You could call this function like:
1088
1089 @example
1090 eprintf ("The file %s does not exist.\n", filename);
1091 @end example
1092
1093 @node Customizing @code{printf}
1094 @section Customizing @code{printf}
1095
1096 The GNU C Library lets you define new conversion specifiers for 
1097 @code{printf} format templates.  To do this, you must include the
1098 header file @file{<printf.h>} in your program.
1099
1100 The way you do this is by registering the conversion with
1101 @code{register_printf_function}; @pxref{Registering New Conversions}.
1102 One of the arguments you pass to this function is a pointer to a handler
1103 function that produces the actual output; @pxref{Defining the Output Handler},
1104 for information on how to write this function.  
1105
1106 You can also install a function that just returns information about the
1107 number and type of arguments expected by the conversion specifier.
1108 @xref{Parsing a Format Template}, for information about this.
1109
1110 @menu
1111 * Registering New Conversions::
1112 * Conversion Specifier Options::
1113 * Defining the Output Handler::
1114 * Parsing a Format Template::
1115 * @code{printf} Extension Example::
1116 @end menu
1117
1118 @strong{Portability Note:} The ability to extend the syntax of
1119 @code{printf} format templates is a GNU extension.  ANSI standard C has
1120 nothing similar.
1121
1122 @node Registering New Conversions
1123 @subsection Registering New Conversions
1124
1125 The function to register a new conversion is
1126 @code{register_printf_function}, declared in @file{<printf.h>}.
1127
1128 @comment printf.h
1129 @comment GNU
1130 @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler_function}, printf_arginfo_function @var{arginfo_function})
1131 This function defines the conversion specifier character @var{spec}.
1132
1133 The @var{handler_function} is the function called by @code{printf} and
1134 friends when this conversion appears in a format template string.
1135 @xref{Defining the Output Handler}, for information about how to define
1136 a function to pass as this argument.  If you specify a null pointer, any
1137 existing handler function for @var{spec} is removed.
1138
1139 The @var{arginfo_function} is the function called by
1140 @code{parse_printf_format} when this conversion appears in a format
1141 template string.  @xref{Parsing a Format Template}, for information
1142 about this.
1143
1144 Normally, you install both functions for a conversion at the same time,
1145 but if you are never going to call @code{parse_printf_format}, you do
1146 not need to define an arginfo function.
1147
1148 The return value is @code{0} on success, and @code{-1} on failure.
1149
1150 You can redefine the standard output conversions, but this is probably
1151 not a good idea because of the potential for confusion.  Library routines
1152 written by other people could break if you do this.
1153 @end deftypefun
1154
1155 @node Conversion Specifier Options
1156 @subsection Conversion Specifier Options
1157
1158 Both the @var{handler_function} and @var{arginfo_function} arguments
1159 to @code{register_printf_function} accept an argument of type
1160 @code{struct print_info}, which contains information about the options
1161 appearing in an instance of the conversion specifier.  This data type
1162 is declared in the header file @file{<printf.h>}.
1163
1164 @comment printf.h
1165 @comment GNU
1166 @deftp {Data Type} {struct printf_info}
1167 This structure is used to pass information about the options appearing
1168 in an instance of a conversion specifier in a @code{printf} format
1169 template to the handler and arginfo functions for that specifier.  It
1170 contains the following members:
1171
1172 @table @code
1173 @item int prec
1174 This is the precision.  The value is @code{-1} if no precision was specified.
1175 If the precision was given as @samp{*}, the @code{printf_info} structure
1176 passed to the handler function will have the actual value retrieved from
1177 the argument list.  But the structure passed to the arginfo function will
1178 have a value of @code{INT_MIN}, since the actual value is not known.
1179
1180 @item int width
1181 This is the minimum field width.  The value is @code{0} if no width was
1182 specified.  If the field width was given as @samp{*}, the
1183 @code{printf_info} structure passed to the handler function will have
1184 the actual value retrieved from the argument list.  But the structure
1185 passed to the arginfo function will have a value of @code{INT_MIN},
1186 since the actual value is not known.
1187
1188 @item char spec
1189 This is the conversion specifier character.  It's stored in the structure
1190 so that you can register the same handler function for multiple characters,
1191 but still have a way to tell them apart when the handler function is called.
1192
1193 @item unsigned int is_long_double
1194 This is a boolean that is true if the @samp{L} type modifier was specified.
1195
1196 @item unsigned int is_short
1197 This is a boolean that is true if the @samp{h} type modifier was specified.
1198
1199 @item unsigned int is_long
1200 This is a boolean that is true if the @samp{l} type modifier was specified.
1201
1202 @item unsigned int alt
1203 This is a boolean that is true if the @samp{#} flag was specified.
1204
1205 @item unsigned int space
1206 This is a boolean that is true if the @samp{ } flag was specified.
1207
1208 @item unsigned int left
1209 This is a boolean that is true if the @samp{-} flag was specified.
1210
1211 @item unsigned int showsign
1212 This is a boolean that is true if the @samp{+} flag was specified.
1213
1214 @item char pad
1215 This is the character to use for padding the output to the minimum field
1216 width.  The value is @code{'0'} if the @samp{0} flag was specified, and
1217 @code{' '} otherwise.
1218 @end table
1219 @end deftp
1220
1221
1222 @node Defining the Output Handler
1223 @subsection Defining the Output Handler
1224
1225 Now let's look at how to define the handler and arginfo functions
1226 which are passed as arguments to @code{register_printf_function}.
1227
1228 @comment printf.h
1229 @comment GNU
1230 @deftp {Data Type} printf_function
1231 This type is used to describe handler functions for conversion specifiers.
1232
1233 You should define your handler functions with a prototype like:
1234
1235 @example
1236 int @var{function} (FILE *@var{stream}, const struct printf_info *@var{info},
1237                     va_list *@var{app})
1238 @end example
1239
1240 The @var{stream} argument passed to the handler function is the stream to
1241 which it should write output.
1242
1243 The @var{info} argument is a pointer to a structure that contains
1244 information about the various options that were included with the
1245 conversion in the format template string.  You should not modify this
1246 structure inside your handler function.
1247
1248 The @var{app} argument is used to pass the tail of the variable argument
1249 list containing the values to be printed to your handler.  Unlike most
1250 other functions that can be passed an explicit variable argument list,
1251 this is a @emph{pointer} to a @code{va_list}, rather than the
1252 @code{va_list} itself.  (Basically, passing a pointer here allows the
1253 function that calls your handler function to update its own @code{va_list}
1254 variable to account for the arguments that your handler processes.)
1255 @xref{Variable Argument Facilities}.
1256
1257 The return value from your handler function should be the number of
1258 argument values that it processes from the variable argument list.  You
1259 can also return a value of @code{-1} to indicate an error.
1260 @end deftp
1261
1262
1263 @node Parsing a Format Template
1264 @subsection Parsing a Format Template
1265
1266 You can use the function @code{parse_printf_format} to obtain information
1267 about the number and types of arguments that are expected by a format
1268 template.  This function is primarily intended for performing error checking
1269 on calls to @code{printf} and related functions from within applications
1270 such as interpreters.
1271
1272 @comment printf.h
1273 @comment GNU
1274 @deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
1275 This function returns information about the number and types of arguments
1276 expected by the @code{printf} format template @var{template}.  
1277
1278 The @var{n} argument specifies the maximum number of arguments.  The
1279 allocation size of the array @var{argtypes} should be at least this many
1280 elements.  The return value is the actual number of arguments expected,
1281 and the array is filled in with information about their types.  This
1282 information is encoded using the various @samp{PA_} macros, listed below.
1283 @end deftypefun
1284
1285 If you have are going to use @code{parse_printf_format} in your
1286 application, you should also define a function to pass as the
1287 @var{arginfo_function} argument for each new conversion you install with
1288 @code{register_printf_function}. 
1289
1290 @comment printf.h
1291 @comment GNU
1292 @deftp {Data Type} printf_arginfo_function
1293 This type is used to describe functions that return information about
1294 the number and type of arguments used by a conversion specifier.
1295
1296 You should define these functions with a prototype like:
1297
1298 @example
1299 int @var{function} (const struct printf_info *@var{info},
1300                     size_t @var{n}, int *@var{argtypes})
1301 @end example
1302
1303 The return value from the function should be the number of arguments
1304 the conversion expects, up to a maximum of @var{n}.  The function should
1305 also fill in the @var{argtypes} array with information about the types
1306 of each of these arguments.  This information is encoded using the
1307 various @samp{PA_} macros.
1308 @end deftp
1309
1310 The types of the arguments expected by a @code{printf} conversion are
1311 encoded by using one of these base types:
1312
1313 @comment printf.h
1314 @comment GNU
1315 @defvr {Macro} PA_INT
1316 This specifies that the base type is @code{int}.
1317 @end defvr
1318
1319 @comment printf.h
1320 @comment GNU
1321 @defvr {Macro} PA_CHAR
1322 This specifies that the base type is @code{int}, cast to @code{char}.
1323 @end defvr
1324
1325 @comment printf.h
1326 @comment GNU
1327 @defvr {Macro} PA_STRING
1328 This specifies that the base type is @code{char *}, a null-terminated string.
1329 @end defvr
1330
1331 @comment printf.h
1332 @comment GNU
1333 @defvr {Macro} PA_POINTER
1334 This specifies that the base type is @code{void *}, an arbitrary pointer.
1335 @end defvr
1336
1337 @comment printf.h
1338 @comment GNU
1339 @defvr {Macro} PA_FLOAT
1340 This specifies that the base type is @code{double}.
1341
1342 @strong{Incomplete:}  Should this be @code{float} instead?  How do you
1343 encode the type of @code{float *}?
1344 @end defvr
1345
1346 @comment printf.h
1347 @comment GNU
1348 @defvr {Macro} PA_LAST
1349 You can define additional base types for your own programs as offsets
1350 from @code{PA_LAST}.  For example, if you have data types @samp{foo}
1351 and @samp{bar} with their own specialized @code{printf} conversions,
1352 you could define encodings for these types as:
1353
1354 @example
1355 #define PA_FOO  PA_LAST
1356 #define PA_BAR  (PA_LAST + 1)
1357 @end example
1358 @end defvr
1359
1360 You can also specify type modifiers in the encoded type as a bit mask,
1361 using the following macros:
1362
1363 @comment printf.h
1364 @comment GNU
1365 @defvr {Macro} PA_FLAG_MASK
1366 This macro can be used to extract the type modifier flags from an encoded
1367 type.
1368 @end defvr
1369
1370 @comment printf.h
1371 @comment GNU
1372 @defvr {Macro} PA_FLAG_PTR
1373 If this bit is set, it indicates that the encoded type is a pointer to
1374 the base type, rather than an immediate value.
1375 For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.
1376 @end defvr
1377
1378 @comment printf.h
1379 @comment GNU
1380 @defvr {Macro} PA_FLAG_SHORT
1381 If this bit is set, it indicates that the base type is modified with
1382 @code{short}.  (This corresponds to the @samp{h} type modifier.)
1383 @end defvr
1384
1385 @comment printf.h
1386 @comment GNU
1387 @defvr {Macro} PA_FLAG_LONG
1388 If this bit is set, it indicates that the base type is modified with
1389 @code{long}.  (This corresponds to the @samp{l} type modifier.)
1390 @end defvr
1391
1392 @comment printf.h
1393 @comment GNU
1394 @defvr {Macro} PA_FLAG_LONGLONG
1395 If this bit is set, it indicates that the base type is modified with
1396 @code {long long}.  (This corresponds to the @samp{L} type modifier.)
1397 @end defvr
1398
1399 @comment printf.h
1400 @comment GNU
1401 @defvr {Macro} PA_FLAG_LONGDOUBLE
1402 This is a synonym for @code{PA_FLAG_LONGLONG}, used by convention with
1403 a base type of @code{PA_FLOAT} to indicate a type of @code{long double}.
1404 @end defvr
1405
1406 @node @code{printf} Extension Example
1407 @subsection @code{printf} Extension Example
1408
1409 Here is an example showing how to define a @code{printf} handler function.
1410 This program defines a data structure called a @code{Widget} and 
1411 defines the @samp{%W} conversion to print information about @code{Widget *}
1412 arguments, including the pointer value and the name stored in the data
1413 structure.  The @samp{%W} conversion supports the minimum field width and
1414 left-justification options, but ignores everything else.
1415
1416 @example
1417 #include <stdio.h>
1418 #include <printf.h>
1419 #include <stdarg.h>
1420
1421 typedef struct widget @{
1422     char *name;
1423     @dots{}
1424 @} Widget;
1425
1426
1427 int print_widget (FILE *stream, const struct printf_info *info,
1428                   va_list *app)
1429 @{
1430   Widget *w;
1431   char *buffer;
1432   int fill, i;
1433
1434   /* @r{Format the output into a string.} */
1435   w = va_arg (*app, Widget *);
1436   fill = info->width -
1437       asprintf (&buffer, "<Widget %p: %s>", w, w->name);
1438
1439   /* @r{Pad to the minimum field width and print to the stream.} */
1440   if (!info->left)
1441     for (i=0; i<fill; i++) fputc (' ', stream);
1442   fputs (buffer, stream);
1443   if (info->left)
1444     for (i=0; i<fill; i++) fputc (' ', stream);
1445
1446   /* @r{Clean up and return.} */
1447   free (buffer);
1448   return 1;
1449 @}
1450
1451
1452 void main (void)
1453 @{
1454
1455   /* @r{Make a widget to print.} */
1456   Widget mywidget;
1457   mywidget.name = "mywidget";
1458
1459   /* @r{Register the print function for widgets.} */
1460   register_printf_function ('W', print_widget, NULL);
1461
1462   /* @r{Now print the widget.} */
1463   printf ("|%W|\n", &mywidget);
1464   printf ("|%35W|\n", &mywidget);
1465   printf ("|%-35W|\n", &mywidget);
1466 @}
1467 @end example
1468
1469 The output produced by this program looks like:
1470
1471 @example
1472 |<Widget 0xffeffb7c: mywidget>|
1473 |      <Widget 0xffeffb7c: mywidget>|
1474 |<Widget 0xffeffb7c: mywidget>      |
1475 @end example
1476
1477 @node Formatted Input
1478 @section Formatted Input
1479
1480 @cindex formatted input
1481 @cindex format string, for @code{scanf}
1482 @cindex template, for @code{scanf}
1483 The functions described in this section (@code{scanf} and related
1484 functions) provide facilities for formatted input analogous to the
1485 formatted output facilities.  These functions provide a mechanism for
1486 reading arbitrary values under the control of a @dfn{format string} or
1487 @dfn{template}.
1488
1489 @menu
1490 * Formatted Input Basics::      Some basics to get you started.
1491 * Input Conversion Syntax::     Syntax of conversion specifications.
1492 * Table of Input Conversions::  Summary of input conversions and what they do.
1493 * Numeric Input Conversions::   Details of conversions for reading numbers.
1494 * String Input Conversions::    Details of conversions for reading strings.
1495 * Other Input Conversions::     Details of miscellaneous other conversions.
1496 * Formatted Input Functions::   Descriptions of the actual functions.
1497 @end menu
1498
1499 @node Formatted Input Basics
1500 @subsection Formatted Input Basics
1501
1502 Calls to @code{scanf} are superficially similar to calls to
1503 @code{printf} in that arbitrary arguments are read under the control of
1504 a format template string.  While the syntax of the conversion
1505 specifications in the template is very similar to that for
1506 @code{printf}, the interpretation of the template is oriented more
1507 towards free-format input and simple pattern matching, rather than
1508 fixed-field formatting.  For example, most @code{scanf} conversions skip
1509 over any amount of ``white space'' (including spaces, tabs, newlines) in
1510 the input file, and there is no concept of precision for the numeric
1511 input conversions as there is for the corresponding output conversions.
1512 Ordinary, non-whitespace characters in the template are expected to
1513 match characters in the input stream exactly, but a matching failure is
1514 distinct from an input error on the stream.
1515
1516 Another area of difference between @code{scanf} and @code{printf} is
1517 that you must remember to supply pointers rather than immediate values
1518 as the optional arguments to @code{scanf}; the values that are read are
1519 stored in the objects that the pointers point to.  Even experienced
1520 programmers tend to forget this occasionally, so if your program is
1521 getting strange errors that seem to be related to @code{scanf}, you
1522 might want to doublecheck this.
1523
1524 When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
1525 leaving the first non-matching character as the next character to be
1526 read from the stream.  The normal return value from @code{scanf} is the
1527 number of values that were assigned, so you can use this to determine if
1528 a matching error happened before all the expected values were read.
1529 @cindex matching failure, in @code{scanf}
1530
1531 The @code{scanf} function is typically used to do things like reading
1532 in the contents of tables.  For example, here is a function that uses
1533 @code{scanf} to initialize an array of @code{double}s:
1534
1535 @example
1536 void readarray (double *array, int n)
1537 @{
1538   int i;
1539   for (i=0; i<n; i++)
1540     if (scanf (" %lf", &(array[i])) != 1)
1541       input_failure ();
1542 @}
1543 @end example
1544
1545 The formatted input functions are not used as frequently as the
1546 formatted output functions.  Partly, this is because it takes some care
1547 to use them properly.  Another reason is that it is difficult to recover
1548 from a matching error.
1549
1550 If you are trying to read input that doesn't match a single, fixed
1551 pattern, you may be better off using a tool such as Bison to generate
1552 a parser, rather than using @code{scanf}.  For more information about
1553 this, see @cite{The Bison Reference Manual}.
1554
1555
1556 @node Input Conversion Syntax
1557 @subsection Input Conversion Syntax
1558
1559 A @code{scanf} format template is a string that contains ordinary
1560 multibyte characters and conversion specifications introduced by a
1561 @samp{%} character.
1562
1563 Any whitespace character (as defined by the @code{isspace} function;
1564 @pxref{Classification of Characters}) in the template causes any number
1565 of whitespace characters in the input stream to be read and discarded.
1566 The whitespace characters that are matched need not be exactly the same
1567 whitespace characters that appear in the format template.
1568
1569 Other characters in the format template that are not part of conversion
1570 specifications must match characters in the input stream exactly; if
1571 this is not the case, a matching failure occurs.
1572
1573 The conversion specifications in a @code{scanf} format template
1574 have the general form:
1575
1576 @example
1577 % @var{flags} @var{width} @var{type} @var{conversion}
1578 @end example
1579
1580 More specifically, input conversion specifications consist of an initial
1581 @samp{%} character followed in sequence by:
1582
1583 @itemize @bullet
1584 @item
1585 An optional @dfn{flag character} @samp{*}, which causes assignment to be
1586 suppressed.  If this flag appears, input is read from the stream and
1587 matched against the conversion specification in the usual way, but no
1588 optional argument is used, no assignment takes place, and the count
1589 of successful assignments is not incremented.
1590 @cindex flag character (scanf)
1591
1592 @item
1593 An optional decimal integer that specifies the @dfn{maximum field
1594 width}.  Reading of characters from the input stream stops either when
1595 this maximum is reached or when a non-matching character is found,
1596 whichever happens first.  Most conversions discard initial whitespace
1597 characters (those that don't are explicitly documented), and these
1598 discarded characters don't count towards the maximum field width.
1599 @cindex maximum field width (scanf)
1600
1601 @item
1602 An optional @dfn{type modifier character}.  For example, you can
1603 specify a type modifier of @samp{l} with integer conversions such as
1604 @samp{%d} to specify that the argument is a pointer to a @code{long int}
1605 rather than a pointer to an @code{int}.
1606 @cindex type modifier character (scanf)
1607
1608 @item
1609 A character that specifies the conversion to be applied.
1610 @end itemize
1611
1612 The exact options that are permitted and how they are interpreted vary 
1613 between the different conversion specifiers.  See the descriptions of the
1614 individual conversions for information about the particular options that
1615 they use.
1616
1617 @node Table of Input Conversions
1618 @subsection Table of Input Conversions
1619
1620 Here is a table that summarizes the various conversion specifications:
1621
1622 @table @asis
1623 @item @samp{%d}
1624 Matches an optionally signed integer in decimal radix; @pxref{Numeric
1625 Input Conversions}.
1626
1627 @item @samp{%i}
1628 Matches an optionally signed integer in any of the formats that the C
1629 language defines for specifying an integer constant.  @xref{Numeric
1630 Input Conversions}.
1631
1632 @item @samp{%o}
1633 Matches an unsigned integer in octal radix; @pxref{Numeric
1634 Input Conversions}.
1635
1636 @item @samp{%u}
1637 Matches an unsigned integer in decimal radix; @pxref{Numeric
1638 Input Conversions}.
1639
1640 @item @samp{%x}, @samp{%X}
1641 Matches an unsigned integer in hexadecimal radix; @pxref{Numeric
1642 Input Conversions}.
1643
1644 @item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
1645 Matches an optionally signed floating-point number; @pxref{Numeric Input
1646 Conversions}.
1647
1648 @item @samp{%s}
1649 Matches a string of non-whitespace characters.  @xref{String Input
1650 Conversions}.
1651
1652 @item @samp{%[}
1653 Matches a string of characters that belong to a set.  @xref{String Input
1654 Conversions}.
1655
1656 @item @samp{%c}
1657 Matches a string of one or more characters; the number of characters
1658 read is controlled by the maximum field width given for the conversion.
1659 @xref{String Input Conversions}.
1660
1661 @item @samp{%p}
1662 Matches a pointer value in the same implementation-defined format used
1663 by the @samp{%p} output conversion for @code{printf}.  @xref{Other Input
1664 Conversions}.
1665
1666 @item @samp{%n}
1667 This conversion doesn't read any characters; it produces the number of
1668 characters read so far by this call.  @xref{Other Input Conversions}.
1669
1670 @item @samp{%%}
1671 This matches a literal @samp{%} character in the input stream.  No
1672 corresponding argument is used.  @xref{Other Input Conversions}.
1673 @end table
1674
1675 If the syntax of a conversion specification is invalid, the behavior is
1676 undefined.  If there aren't enough function arguments provided to supply
1677 addresses for all the conversion specifications in the format template
1678 that perform assignments, or if the arguments are not of the correct
1679 types, the behavior is also undefined.  On the other hand, if there are
1680 extra arguments, their values are simply ignored.
1681
1682 @node Numeric Input Conversions
1683 @subsection Numeric Input Conversions
1684
1685 This section describes the @code{scanf} conversions for reading numeric
1686 values.
1687
1688 The @samp{%d} conversion matches an optionally signed integer in decimal
1689 radix.  The syntax that is recognized is the same as that for the
1690 @code{strtol} function (@pxref{Parsing of Integers}) with the value
1691 @code{10} for the @var{base} argument.
1692
1693 The @samp{%i} conversion matches an optionally signed integer in any of
1694 the formats that the C language defines for specifying an integer
1695 constant.  The syntax that is recognized is the same as that for the
1696 @code{strtol} function (@pxref{Parsing of Integers}) with the value
1697 @code{0} for the @var{base} argument.
1698
1699 For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
1700 could be read in as integers under the @samp{%i} conversion.  Each of
1701 these specifies a number with decimal value @code{10}.
1702
1703 The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned
1704 integers in octal, decimal, and hexadecimal radices, respectively.  The
1705 syntax that is recognized is the same as that for the @code{strtoul}
1706 function (@pxref{Parsing of Integers}) with the appropriate value
1707 (@code{8}, @code{10}, or @code{16}) for the @var{base} argument.
1708
1709 The @samp{%X} conversion is identical to the @samp{%x} conversion.  They
1710 both permit either uppercase or lowercase letters to be used as digits.
1711
1712 The default type of the corresponding argument for the @code{%d} and
1713 @code{%i} conversions is @code{int *}, and @code{unsigned int *} for the
1714 other integer conversions.  You can use the following type modifiers to
1715 specify other sizes of integer:
1716
1717 @table @samp
1718 @item h
1719 Specifies that the argument is a @code{short int *} or @code{unsigned
1720 short int *}.
1721
1722 @item l
1723 Specifies that the argument is a @code{long int *} or @code{unsigned
1724 long int *}.
1725
1726 @item L
1727 Specifies that the argument is a @code{long lont int *} or @code{unsigned long long int *}.  (The @code{long long} type is an extension supported by the
1728 GNU C compiler.  For systems that don't provide extra-long integers, this
1729 is the same as @code{long int}.)
1730 @end table
1731
1732 All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
1733 input conversions are interchangable.  They all match an optionally
1734 signed floating point number, in the same syntax as for the
1735 @code{strtod} function (@pxref{Parsing of Floats}).
1736
1737 For the floating-point input conversions, the default argument type is
1738 @code{float *}.  (This is different from the corresponding output
1739 conversions, where the default type is @code{double}; remember that
1740 @code{float} arguments to @code{printf} are converted to @code{double}
1741 by the default argument promotions, but @code{float *} arguments are
1742 not promoted to @code{double *}.)  You can specify other sizes of float
1743 using these type modifiers:
1744
1745 @table @samp
1746 @item l
1747 Specifies that the argument is of type @code{double *}.
1748
1749 @item L
1750 Specifies that the argument is of type @code{long double *}.
1751 @end table
1752
1753 @node String Input Conversions
1754 @subsection String Input Conversions
1755
1756 This section describes the @code{scanf} input conversions for reading
1757 string and character values: @samp{%s}, @samp{%[}, and @samp{%c}.  
1758
1759 The corresponding argument for all of these conversions should be of
1760 type @code{char *}.  Make sure that the allocation size of the array
1761 that the argument points to is large enough to hold all the characters
1762 and the null character which is added to mark the end of the string.
1763 You can specify a field width to limit the number of characters read.
1764
1765 The @samp{%c} conversion is the simplest.  It matches a fixed-sized
1766 string of characters.  The number of characters read is controlled by
1767 the maximum field width.  If you don't supply a field width, then only
1768 one character is read.  Note that this conversion doesn't append a null
1769 character to the end of the string it reads.  It also does not skip over
1770 initial whitespace characters.
1771
1772 The @samp{%s} conversion matches a string of non-whitespace characters.
1773 Unlike @samp{%c}, this conversion does skip over initial whitespace and
1774 does mark the end of the string with a null character.  If you do not
1775 specify a field width for @samp{%s}, then the number of characters read
1776 is limited only by where the next whitespace character appears.
1777
1778 For example, reading the input:
1779
1780 @example
1781  hello, world
1782 @end example
1783
1784 @noindent
1785 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
1786 reading the same input with the conversion @samp{%10s} produces
1787 @code{"hello,"}.
1788
1789 The @samp{%s} conversion effectively reads in characters that belong to
1790 the set of non-whitespace characters.  To read in characters that belong
1791 to an arbitrary set, you can use the @samp{%[} conversion.  The
1792 characters which make up the set are specified immediately following the
1793 @samp{[} character, up to a matching @samp{]} character.  As special
1794 cases:
1795
1796 @itemize @bullet
1797 @item 
1798 If a cirumflex character @samp{^} immediately follows the
1799 initial @samp{[}, then the set that is used for matching is the
1800 @emph{complement} of the set of characters that are explicitly listed.
1801
1802 @item 
1803 A literal @samp{]} character can be specified as the first character
1804 of the set.
1805
1806 @item 
1807 An embedded @samp{-} character (that is, one that is not the first or
1808 last character of the set) is used to specify a range of characters.
1809 @end itemize
1810
1811 The @samp{%[} conversion does not skip over initial whitespace
1812 characters.
1813
1814 Here are some examples of @samp{%[} conversions and what they mean.
1815
1816 @table @samp
1817 @item %[1234567890]
1818 Matches a string of digits.
1819
1820 @item %[][]
1821 Matches a string of square brackets.
1822
1823 @item %[^ \f\n\r\t\v]
1824 Matches a string that doesn't contain any of the standard whitespace
1825 characters.  This is slightly different from @samp{%s}, because if the
1826 input begins with a whitespace character, @samp{%[} will report a
1827 matching failure while @samp{%s} will simply discard the initial
1828 whitespace.
1829
1830 @item %[a-z] 
1831 Matches a string of lowercase characters.
1832 @end table
1833
1834 The @samp{%s} and @samp{%[} conversions are potentially
1835 @strong{dangerous} because they can overflow the allocation size of the
1836 argument string.  You should @strong{always} specify a maximum field
1837 width with the @samp{%s} and @samp{%[} conversions to prevent this from
1838 happening (but then you will probably get a matching error instead if
1839 the input string is too long).
1840
1841
1842 @node Other Input Conversions
1843 @subsection Other Input Conversions
1844
1845 This section describes the miscellaneous input conversions.
1846
1847 The @samp{%p} conversion is used to read a pointer value.  It recognizes
1848 the same syntax as is used by the @samp{%p} output conversion for
1849 @code{printf}.  The corresponding argument should be of type @code{void **};
1850 that is, the address of a pointer.
1851
1852 The resulting pointer value is not guaranteed to be valid if it was not
1853 originally written during the same program execution that reads it in.
1854
1855 The @samp{%n} conversion produces the number of characters read so far
1856 by this call.  The corresponding argument should be of type @code{int *}.
1857 This conversion works in the same way as the @samp{%n} conversion for
1858 @code{printf}; @pxref{Other Output Conversions}, for an example.
1859
1860 The @samp{%n} conversion is the only mechanism for determining the
1861 success of literal matches or conversions with suppressed assignments.
1862
1863 Finally, the @samp{%%} conversion matches a literal @samp{%} character
1864 in the input stream, without using an argument.  This conversion does
1865 not permit any flags, field width, or type modifier to be specified.
1866
1867 @node Formatted Input Functions
1868 @subsection Formatted Input Functions
1869
1870 Here are the descriptions of the functions for performing formatted
1871 input.
1872 Prototypes for these functions are in the header file @file{<stdio.h>}.
1873
1874 @comment stdio.h
1875 @comment ANSI
1876 @deftypefun int scanf (const char *@var{template}, @dots{})
1877 The @code{scanf} function reads formatted input from the stream
1878 @code{stdin} under the control of the format template @var{template}.
1879 The optional arguments are pointers to the places which receive the
1880 resulting values.
1881
1882 The return value is normally the number of successful assignments.  If
1883 an end-of-file condition is detected before any matches are performed
1884 (including matches against whitespace and literal characters in the
1885 template), then @code{EOF} is returned.
1886 @end deftypefun
1887
1888 @comment stdio.h
1889 @comment ANSI
1890 @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
1891 This function is just like @code{scanf}, except that the input is read
1892 from the stream @var{stream} instead of @code{stdin}.
1893 @end deftypefun
1894
1895 @comment stdio.h
1896 @comment ANSI
1897 @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
1898 This is like @code{scanf}, except that the characters are taken from the
1899 null-terminated string @var{s} instead of read from a stream.  Reaching
1900 the end of the string is treated as an end-of-file condition.
1901
1902 The behavior of this function is undefined if copying takes place
1903 between objects that overlap --- for example, if @var{s} is also given
1904 as an argument to receive a string read under control of the @samp{%s}
1905 conversion.
1906 @end deftypefun
1907
1908 @comment stdio.h
1909 @comment GNU
1910 @deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
1911 This function is similar to @code{scanf} except that, instead of taking
1912 a variable number of arguments directly, it takes an argument list
1913 pointer @var{ap}.  Before calling @code{vscanf}, you @emph{must} call
1914 @code{va_start} (@pxref{Variable Argument Facilities}) to initialize
1915 @var{ap}, and you @emph{may} call @code{va_arg} to skip over some of the
1916 initial arguments.  The @code{vscanf} function does not invoke the
1917 @code{va_end} macro, but further calls to @code{va_arg} with @var{ap}
1918 are not permitted once @code{vscanf} returns.
1919
1920 The @code{vscanf} function is typically used to do input in the same
1921 kinds of situations as where @code{vprintf} is used to do output.
1922 @xref{Formatted Output Functions}.
1923 @end deftypefun
1924
1925 @comment stdio.h
1926 @comment GNU
1927 @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
1928 This is the equivalent of @code{fscanf} with the variable argument list
1929 specified directly as for @code{vscanf}.
1930 @end deftypefun
1931
1932 @comment stdio.h
1933 @comment GNU
1934 @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
1935 This is the equivalent of @code{sscanf} with the variable argument list
1936 specified directly as for @code{vscanf}.
1937 @end deftypefun
1938
1939 @strong{Portability Note:} Of the functions listed in this section, only
1940 @code{scanf}, @code{fscanf}, and @code{sscanf} are included in ANSI C.
1941 The @code{vscanf}, @code{vfscanf}, and @code{vsscanf} functions are
1942 GNU extensions.
1943
1944 @node Block Input/Output
1945 @section Block Input/Output
1946
1947 This section describes how to do input and output operations on blocks
1948 of data.  You can use these functions to read and write binary data, as
1949 well as to read and write text in fixed-size blocks instead of by
1950 characters or lines.
1951 @cindex binary input/output
1952 @cindex block input/output
1953
1954 Binary files are typically used to read and write blocks of data in the
1955 same format as is used to represent the data in a running program.  In
1956 other words, arbitrary blocks of memory --- not just character or string
1957 objects --- can be written to a binary file, and meaningfully read in
1958 again under the same implementation.
1959
1960 Storing data in binary form is often considerably more efficient than
1961 using the formatted i/o functions.  Also, for floating-point numbers,
1962 the binary form avoids possible loss of precision in the conversion
1963 process.  On the other hand, binary files can't be examined or modified
1964 easily using many standard file utilities (such as text editors), and
1965 are not portable between different implementations of the language, or
1966 different kinds of computers.
1967
1968 These functions are declared in @file{<stdio.h>}.
1969
1970 @comment stdio.h
1971 @comment ANSI
1972 @deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1973 This function reads up to @var{count} objects of size @var{size} into
1974 the array @var{data}, from the stream @var{stream}.  It returns the
1975 number of objects actually read, which might be less than @var{count} if
1976 a read error or end-of-file occurs.  This function returns a value of
1977 zero (and doesn't read anything) if either @var{size} or @var{count} is
1978 zero.
1979 @end deftypefun
1980
1981 @comment stdio.h
1982 @comment ANSI
1983 @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1984 This function writes up to @var{count} objects of size @var{size} from
1985 the array @var{data}, to the stream @var{stream}.  The return value is
1986 the number of objects actually written, which is less than @var{count}
1987 only if a write error occurs.
1988 @end deftypefun
1989
1990
1991
1992 @node End-Of-File and Errors
1993 @section End-Of-File and Errors
1994
1995 Many of the functions described in this chapter return the value of the
1996 macro @code{EOF} to indicate unsuccessful completion of the operation.
1997 Since @code{EOF} is used to report both end-of-file and random errors,
1998 it's often better to use the @code{feof} function to check explicitly
1999 for end-of-file and @code{ferror} to check for errors.  These functions
2000 check indicators that are part of the internal state of the stream
2001 object, that are set if the appropriate condition was detected by a
2002 previous i/o operation on that stream.
2003
2004 These facilities are declared in the header file @file{<stdio.h>}.
2005
2006 @comment stdio.h
2007 @comment ANSI
2008 @defvr {Macro} EOF
2009 This macro expands to an integer constant expression that is returned
2010 by a number of functions to indicate an end-of-file condition, or some
2011 other error situation.  The value of this constant is always a negative
2012 number; in the GNU system, its value is @code{-1}.
2013 @end defvr
2014
2015 @comment stdio.h
2016 @comment ANSI
2017 @deftypefun void clearerr (FILE *@var{stream})
2018 This function resets the end-of-file and error indicators for the
2019 stream @var{stream}.
2020
2021 The file positioning functions (@pxref{File Positioning}) also reset the
2022 end-of-file indicator for the stream.
2023 @end deftypefun
2024
2025 @comment stdio.h
2026 @comment ANSI
2027 @deftypefun int feof (FILE *@var{stream})
2028 The @code{feof} function returns nonzero if and only if the end-of-file
2029 indicator for the stream @var{stream} is set.
2030 @end deftypefun
2031
2032 @comment stdio.h
2033 @comment ANSI
2034 @deftypefun int ferror (FILE *@var{stream})
2035 The @code{ferror} function returns nonzero if and only if the error
2036 indicator for the stream @var{stream} is set, indicating that an error
2037 has occurred on a previous operation on the stream.
2038 @end deftypefun
2039
2040 In addition to setting the error indicator associated with the stream,
2041 the functions that operate on streams also set @code{errno} in the same
2042 way as the corresponding low-level functions that operate on file
2043 descriptors.  For example, all of the functions that perform output to a
2044 stream --- such as @code{fputc}, @code{printf}, and @code{fflush} ---
2045 behave as if they were implemented in terms of @code{write}, and all of
2046 the @code{errno} error conditions defined for @code{write} are
2047 meaningful for these functions.
2048
2049 For more information about the functions that operate on file
2050 descriptors, @pxref{Low-Level Input/Output}.
2051
2052
2053 @node File Positioning
2054 @section File Positioning
2055
2056 You can use the functions in this section to inquire about or modify the
2057 file position indicator associated with a stream; @pxref{Input/Output
2058 Concepts}.  In the GNU system, the file position indicator is the number of
2059 bytes from the beginning of the file.
2060
2061 The functions and macros listed in this section are declared in the
2062 header file @file{<stdio.h>}.
2063
2064 @comment stdio.h
2065 @comment ANSI
2066 @deftypefun {long int} ftell (FILE *@var{stream})
2067 This function returns the current file position of the stream
2068 @var{stream}.
2069
2070 This function can fail if the stream doesn't support file positioning,
2071 or if the file position can't be represented in a @code{long int}, and
2072 possibly for other reasons as well.  If a failure occurs, a value of
2073 @code{-1} is returned.
2074 @end deftypefun
2075
2076 @comment stdio.h
2077 @comment ANSI
2078 @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
2079 The @code{fseek} function is used to change the file position of the
2080 stream @var{stream}.  The value of @var{whence} must be one of the
2081 constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
2082 indicate whether the @var{offset} is relative to the beginning of the
2083 file, the current file position, or the end of the file, respectively.
2084
2085 This function returns a value of zero if the operation was successful,
2086 and a nonzero value to indicate failure.  A successful call also clears
2087 any end-of-file condition on the @var{stream} and discards any characters
2088 that were ``pushed back'' by the use of @code{ungetc}.
2089 @end deftypefun
2090
2091 @strong{Portability Note:}  In systems that are not POSIX-compliant,
2092 @code{ftell} and @code{fseek} only work reliably on binary streams.
2093 @xref{Text and Binary Streams}.  
2094
2095 The following symbolic constants are defined for use as the @var{whence}
2096 argument to @code{fseek}.  They are also used with the @code{lseek}
2097 function (@pxref{Input and Output Primitives}) and to specify offsets
2098 for file locks (@pxref{Control Operations on Files}).
2099
2100 @comment stdio.h
2101 @comment ANSI
2102 @defvr {Macro} SEEK_SET
2103 This macro expands into an integer constant expression that can be used
2104 as the @var{whence} argument to the @code{fseek} function, to
2105 specify that the offset provided is relative to the beginning of the
2106 file.
2107 @end defvr
2108
2109 @comment stdio.h
2110 @comment ANSI
2111 @defvr {Macro} SEEK_CUR
2112 This macro expands into an integer constant expression that can be used
2113 as the @var{whence} argument to the @code{fseek} function, to
2114 specify that the offset provided is relative to the currrent file
2115 position.
2116 @end defvr
2117
2118 @comment stdio.h
2119 @comment ANSI
2120 @defvr {Macro} SEEK_END
2121 This macro expands into an integer constant expression that can be used
2122 as the @var{whence} argument to the @code{fseek} function, to
2123 specify that the offset provided is relative to the end of the file.
2124 @end defvr
2125
2126 @comment stdio.h
2127 @comment ANSI
2128 @deftypefun void rewind (FILE *@var{stream})
2129 The @code{rewind} function positions the stream @var{stream} at the
2130 begining of the file.  It is equivalent to calling @code{fseek} on the
2131 @var{stream} with an @var{offset} argument of @code{0L} and a
2132 @var{whence} argument of @code{SEEK_SET}, except that the return
2133 value is discarded and the error indicator for the stream is reset.
2134 @end deftypefun
2135
2136
2137 @node Text and Binary Streams
2138 @section Text and Binary Streams
2139
2140 The GNU system and other POSIX-compatible operating systems organize all
2141 files as uniform sequences of characters.  However, some other systems
2142 make a distinction between files containing text and files containing
2143 binary data, and the input and output facilities provided by ANSI C are
2144 general enough to support this distinction.  This section contains
2145 information you need to know if you are concerned about making your
2146 programs portable to non-POSIX systems.
2147
2148 @cindex text stream
2149 @cindex binary stream
2150 In ANSI C, a file can be opened as either a @dfn{text stream} or as a
2151 @dfn{binary stream}.  You indicate that you want a binary stream by
2152 specifying the @samp{b} modifier in the @var{opentype} argument to
2153 @code{fopen}; @pxref{Opening and Closing Streams}.  Without this option,
2154 @code{fopen} opens the file as a text stream.
2155
2156 There are three areas where the two kinds of streams differ:
2157
2158 @itemize @bullet
2159 @item
2160 A text stream is divided into @dfn{lines} which are terminated by
2161 newline (@code{'\n'}) characters, while a binary stream is simply a long
2162 series of characters.  A text stream must be able to handle lines up to
2163 254 characters long (including the terminating newline character).
2164 @cindex lines (in a file)
2165
2166 @item
2167 A text stream can (portably) consist only of printing
2168 characters, horizontal tab characters, and newlines; while any character
2169 object can be written to or read from a binary stream.
2170
2171 @item
2172 Space characters that are written immediately preceeding a newline
2173 character in a text stream may disappear when the file is read in again.
2174
2175 @item
2176 More generally, there need not be a one-to-one mapping between
2177 characters that are read from or written to a text stream, and the
2178 characters in the actual file.
2179 @end itemize
2180
2181 A consequence of this last point is that file positions for text streams
2182 may not be representable as a character offset from the beginning of the
2183 file.  On some systems, for example, the file position must encode both
2184 a record offset within the file, and a character offset within the
2185 record.
2186
2187 The specific restrictions that result from this are:
2188
2189 @itemize @bullet
2190 @item
2191 The @code{long int} value that @code{fseek} and @code{ftell} use to
2192 represent the file position indicator may not be able to encode a
2193 sufficient range of values to handle large files.
2194
2195 @item
2196 The only guaranteed property of the value returned from @code{ftell} on
2197 a text stream is that it can be used as the @var{offset} argument in a
2198 call to @code{fseek} to represent the same file position.
2199
2200 @item 
2201 In a call to @code{fseek} on a text stream, either the @var{offset} must
2202 either be zero; or @var{whence} must be @code{SEEK_SET} and the
2203 @var{offset} must be the result of an earlier call to @code{ftell} on
2204 the same @var{stream}.
2205
2206 @item
2207 A @var{whence} value of @code{SEEK_END} in a call to @code{fseek} may
2208 not work on binary streams.
2209
2210 @item
2211 The value of the file position indicator of a text stream is undefined
2212 while there are characters that have been pushed back with @code{ungetc}
2213 that haven't been read or discarded.  @xref{Character Input}.
2214 @end itemize
2215
2216 To get around the problems with @code{ftell} and @code{fseek}, you can
2217 use the functions @code{fgetpos} and @code{fsetpos} instead.  These
2218 functions represent the file position as a @code{fpos_t} object, with
2219 an implementation-dependent internal representation.
2220
2221 Prototypes for these functions are declared in the header file
2222 @file{<stdio.h>}.
2223
2224 @comment stdio.h
2225 @comment ANSI
2226 @deftp {Data Type} fpos_t
2227 This is the type of an object that can encode information about the
2228 file position of a stream, for use by the functions @code{fgetpos} and
2229 @code{fsetpos}.
2230
2231 In the GNU system, @code{fpos_t} is equivalent to @code{off_t} or
2232 @code{long int}.  In other systems, it might have a different internal
2233 representation.
2234 @end deftp
2235
2236 @comment stdio.h
2237 @comment ANSI
2238 @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
2239 This function stores the value of the file position indicator for the
2240 stream @var{stream} in the @code{fpos_t} object pointed to by
2241 @var{position}.  If successful, @code{fgetpos} returns zero; otherwise
2242 it returns a nonzero value and stores an implementation-defined positive
2243 value in @code{errno}.
2244 @end deftypefun
2245
2246 @comment stdio.h
2247 @comment ANSI
2248 @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t @var{position})
2249 This function sets the file position indicator for the stream @var{stream}
2250 to the position @var{position}, which must have been set by a previous
2251 call to @code{fgetpos} on the same stream.  If successful, @code{fsetpos}
2252 clears the end-of-file indicator on the stream, discards any characters
2253 that were ``pushed back'' by the use of @code{ungetc}, and returns a value
2254 of zero.  Otherwise, @code{fsetpos} returns a nonzero value and stores
2255 an implementation-defined positive value in @code{errno}.
2256 @end deftypefun
2257
2258 @node Stream Buffering
2259 @section Stream Buffering
2260
2261 @cindex buffering of streams
2262 Characters that are written to a stream are normally accumulated and
2263 transmitted asynchronously to the file in a block, instead of appearing
2264 as soon as they are output by the application program.  Similarly,
2265 streams often retrieve input from the host environment in blocks rather
2266 than on a character-by-character basis.  This is called @dfn{buffering}.
2267
2268 If you are writing programs that do interactive input and output using
2269 streams, you need to understand how buffering works when you design the
2270 user interface to your program.  Otherwise, you might find that output
2271 (such as progress or prompt messages) doesn't appear when you intended
2272 it to, or that input typed by the user is made available by lines
2273 instead of by single characters, or see other unexpected behavior.  
2274
2275 This section deals only with controlling when characters are transmitted
2276 between the stream and the file or device, and @emph{not} with how
2277 things like echoing, flow control, and the like are handled on specific
2278 classes of devices.  For information on common control operations on
2279 terminal devices, @pxref{Low-Level Terminal Interface}.
2280
2281 You can also bypass the stream buffering facilities altogether by using
2282 the low-level input and output functions that operate on file descriptors
2283 instead.  @xref{Low-Level Input/Output}.
2284
2285 @menu
2286 * Buffering Concepts::          Terminology is defined here.
2287 * Flushing Buffers::            How to ensure that output buffers are flushed.
2288 * Controlling Buffering::       How to specify what kind of buffering to use.
2289 @end menu
2290
2291 @node Buffering Concepts
2292 @subsection Buffering Concepts
2293
2294 There are three different kinds of buffering strategies:
2295
2296 @itemize @bullet
2297 @item
2298 Characters written to or read from an @dfn{unbuffered} stream are
2299 transmitted individually to or from the file as soon as possible.
2300 @cindex unbuffered stream
2301
2302 @item
2303 Characters written to or read from a @dfn{line buffered} stream are
2304 transmitted to or from the file in blocks when a newline character is
2305 encountered.
2306 @cindex line buffered stream
2307
2308 @item
2309 Characters written to or read from a @dfn{fully buffered} stream are
2310 transmitted to or from the file in blocks of arbitrary size.
2311 @cindex fully buffered stream
2312 @end itemize
2313
2314 @strong{Incomplete:}  What is the default buffering behavior in the 
2315 GNU system?
2316
2317 You can explicitly set the buffering strategy used by a stream.
2318
2319 When a stream corresponding to an interactive device (such as a
2320 terminal) is opened, its default behavior is to be either unbuffered or
2321 line buffered.
2322
2323 This means that when your program writes messages to an interactive
2324 device that end in a newline, they'll always show up immediately.
2325 Output that doesn't end in a newline might or might not show up
2326 immediately, and if it matters you should flush buffered output
2327 explicitly with @code{fflush}, as described in @ref{Flushing Buffers}.
2328
2329 For input, if an interactive stream is line-buffered, users of your
2330 program will probably be able to use whatever basic input editing
2331 facilities are normally provided by the host operating system (such as
2332 being able to correct typing mistakes with rubout or backspace), but
2333 you'll have to design your program so that it expects to look for
2334 newline characters to terminate input.  If an interactive stream is
2335 unbuffered, it might be appropriate for your program to provide its own
2336 input editing facilities.
2337
2338 @strong{Incomplete:}  I don't think changing the buffering on a stream
2339 in the GNU system messes with input modes on a terminal device, does it?
2340
2341 @node Flushing Buffers
2342 @subsection Flushing Buffers
2343
2344 @cindex flushing a stream
2345 @dfn{Flushing} output on a buffered stream causes any accumulated
2346 characters to be transmitted to the file.  You can flush
2347 buffers explicitly with the @code{fflush} function, but there are many
2348 circumstances when buffered output is flushed automatically:
2349
2350 @itemize @bullet
2351 @item
2352 Output buffers are flushed when they are full.
2353
2354 @item
2355 On a line buffered stream, writing a newline causes output on
2356 that stream to be flushed.  
2357
2358 @item
2359 Performing a read operation on an unbuffered stream (or on a line
2360 buffered stream when it needs to do actual input) causes accumulated
2361 output on all open streams to be flushed.
2362
2363 @item
2364 Closing a stream causes accumulated output on that stream to be flushed
2365 first.
2366
2367 @item
2368 On normal program exit, output is flushed as part of closing all open
2369 streams.
2370 @end itemize
2371
2372 The prototype for @code{fflush} is in the header file @file{<stdio.h>}.
2373
2374 @comment stdio.h
2375 @comment ANSI
2376 @deftypefun int fflush (FILE *@var{stream})
2377 This function causes any buffered output on @var{stream} to be delivered
2378 to the file.  If @var{stream} is a null pointer, then
2379 @code{fflush} causes buffered output on @emph{all} open output streams
2380 to be flushed.
2381
2382 This function returns @code{EOF} if a write error occurs, or zero
2383 otherwise.
2384 @end deftypefun
2385
2386 @strong{Compatibility Note:} Some brain-damaged operating systems have
2387 been known to be so thoroughly fixated on line-oriented input and output
2388 that flushing a line-buffered stream causes a newline to be written!
2389 Fortunately, this ``feature'' seems to be becoming less common.  You do
2390 not need to worry about this in the GNU system.
2391
2392
2393 @node Controlling Buffering
2394 @subsection Controlling Buffering
2395
2396 After opening a stream (but before any other operations have been
2397 performed on it), you can explicitly specify what kind of buffering you
2398 want it to have using the @code{setvbuf} function.
2399 @cindex buffering, specifying
2400
2401 Implementations are not required to actually support changes in the
2402 buffering mode, and requests to do so may simply fail.
2403
2404 @strong{Incomplete:} Does the GNU system support all the buffering modes
2405 on all kinds of files?  If not, what are the restrictions?
2406
2407 The facilities listed in this section are declared in the header
2408 file @file{<stdio.h>}.
2409
2410 @comment stdio.h
2411 @comment ANSI
2412 @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
2413 This function is used to specify that the stream @var{stream} should
2414 have the buffering mode @var{mode}, which can be either @code{_IOFBF}
2415 (for full buffering), @code{_IOLBF} (for line buffering), or
2416 @code{_IONBF} (for unbuffered input/output).
2417
2418 If you want a buffer for the stream to be allocated automatically, you
2419 can specify a null pointer as the @var{buf} argument.  Otherwise,
2420 @var{buf} should be a character array that can hold at least @var{size}
2421 characters.
2422
2423 The extent of the array you pass as the @var{buf} argument should be at
2424 least as great as the open stream; you should usually either allocate it
2425 statically, or @code{malloc} (@pxref{Unconstrained Allocation}) the
2426 buffer.  Using an automatic array is not a good idea unless you close
2427 the file before exiting the block that declares the array.
2428
2429 The contents of the array are indeterminate as long as the stream is
2430 open.  You shouldn't try to access the values in the array while you are
2431 using it for buffering.
2432
2433 The @code{setvbuf} function returns zero on success, or a nonzero value
2434 if the value of @var{mode} is not valid or if the request could not
2435 be honored.
2436 @end deftypefun
2437
2438 @comment stdio.h
2439 @comment ANSI
2440 @defvr {Macro} _IOFBF
2441 The value of this macro is an integer constant expression that can be
2442 used as the @var{mode} argument to the @code{setvbuf} function to
2443 specify that the stream should be fully buffered.
2444 @end defvr
2445
2446 @comment stdio.h
2447 @comment ANSI
2448 @defvr {Macro} _IOLBF
2449 The value of this macro is an integer constant expression that can be
2450 used as the @var{mode} argument to the @code{setvbuf} function to
2451 specify that the stream should be line buffered.
2452 @end defvr
2453
2454 @comment stdio.h
2455 @comment ANSI
2456 @defvr {Macro} _IONBF
2457 The value of this macro is an integer constant expression that can be
2458 used as the @var{mode} argument to the @code{setvbuf} function to
2459 specify that the stream should be unbuffered.
2460 @end defvr
2461
2462 @comment stdio.h
2463 @comment ANSI
2464 @defvr {Macro} BUFSIZ
2465 The value of this macro is an integer constant expression that is an
2466 appropriate (but implementation-defined) value for the @var{size}
2467 argument to @code{setvbuf}.  This value is guaranteed to be at least
2468 @code{256}.
2469
2470 Sometimes people also use @code{BUFSIZ} as the allocation size of
2471 buffers used for related purposes, such as strings used to receive a
2472 line of input with @code{fgets} (@pxref{Character Input}).
2473 @end defvr
2474
2475 @comment stdio.h
2476 @comment ANSI
2477 @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
2478 If @var{buf} is a null pointer, the effect of this function is
2479 equivalent to calling @code{setvbuf} with a @var{mode} argument of
2480 @code{_IONBF}.  Otherwise, it is equivalent to calling @code{setvbuf}
2481 with a @var{mode} of @code{_IOFBF} and a @var{size} argument of
2482 @code{BUFSIZ}.
2483
2484 The @code{setbuf} function is provided for compatibility with old code;
2485 using @code{setvbuf} instead is a more modern style.
2486 @end deftypefun
2487
2488 @comment stdio.h
2489 @comment BSD
2490 @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
2491 If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
2492 Otherwise, it makes @var{stream} fully buffered using that array as the
2493 buffer.  The @var{size} argument specifies the length of the array.
2494
2495 This function is provided for compatibility with old BSD code.  Use
2496 @code{setvbuf} instead.
2497 @end deftypefun
2498
2499 @comment stdio.h
2500 @comment BSD
2501 @deftypefun void setlinebuf (FILE *@var{stream})
2502 This function makes @var{stream} be line-buffered, using an
2503 automatically-allocated buffer.
2504
2505 This function is provided for compatibility with old BSD code.  Use
2506 @code{setvbuf} instead.
2507 @end deftypefun
2508
2509
2510 @node Temporary Files
2511 @section Temporary Files
2512
2513 If you need to use a temporary file in your program, you can use the
2514 @code{tmpfile} function to do this.  Or, you can use the @code{tmpnam}
2515 function to get the name of a temporary file and then open it in the
2516 usual way with @code{fopen}.
2517
2518 These facilities are declared in the header file @file{<stdio.h>}.
2519
2520 @comment stdio.h
2521 @comment ANSI
2522 @deftypefun {FILE *} tmpfile (void)
2523 This function creates a temporary binary file for update mode, as if by
2524 calling @code{fopen} with mode @code{"wb+"}.  The file is removed 
2525 automatically when it is closed or when the program terminates normally
2526 (but not if the program terminates abnormally).
2527 @end deftypefun
2528
2529
2530 @comment stdio.h
2531 @comment ANSI
2532 @deftypefun {char *} tmpnam (char *@var{result})
2533 This function constructs and returns a file name that is a valid file
2534 name and that does not name any existing file.  If the @var{result}
2535 argument is a null pointer, the return value is a pointer to an internal
2536 static string, which might be modified by subsequent calls.  Otherwise,
2537 the @var{result} argument should be a pointer to an array of at least
2538 @code{L_tmpnam} characters, and the result is written into that array.
2539 @end deftypefun
2540
2541 @comment stdio.h
2542 @comment ANSI
2543 @defvr {Macro} L_tmpnam
2544 The value of this macro is an integer constant expression that represents
2545 the minimum allocation size of a string large enough to hold the
2546 file name generated by the @code{tmpnam} function.
2547 @end defvr
2548
2549 @comment stdio.h
2550 @comment ANSI
2551 @defvr {Macro} TMP_MAX
2552 The value of this macro is an integer constant expression that represents
2553 the minimum number of unique file names that can be generated by
2554 the @code{tmpnam} function.  The value of this macro is guaranteed to
2555 be at least @code{25}.
2556 @end defvr
2557
2558 @comment stdio.h
2559 @comment SVID
2560 @deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix})
2561 This function generates a unique temporary filename.  If @var{prefix} is
2562 not a null pointer, up to five characters of this string will be used as
2563 a prefix for the file name.
2564
2565 The directory prefix for the temporary file name is determined by testing
2566 each of the following, in sequence.  The directory must exist and be
2567 writable.
2568
2569 @itemize @bullet
2570 @item The environment variable @code{TMPDIR}, if it is defined.
2571
2572 @item The @var{dir} argument, if it is not a null pointer.
2573
2574 @item The value of the @code{P_tmpdir} macro.
2575
2576 @item The directory @file{/tmp}.
2577 @end itemize
2578 @end deftypefun
2579 @cindex TMPDIR environment variable
2580
2581 @comment stdio.h
2582 @comment SVID
2583 @defvr Macro P_tmpdir
2584 The value of this macro is the file name prefix identifying
2585 the default directory for temporary files.  It is used by @code{tempnam}.
2586 @end defvr
2587
2588
2589 @node Other Kinds of Streams
2590 @section Other Kinds of Streams
2591
2592 The GNU Library provides ways for you to define additional kinds of
2593 streams that do not necessarily correspond to an open file.
2594
2595 One such type of stream takes input from or writes output to a string.
2596 These kinds of streams are used internally to implement the
2597 @code{sprintf} and @code{sscanf} functions.  You can also create such a
2598 stream explicitly, using the functions described in @ref{String Streams}.
2599
2600 More generally, you can define streams that do input/output to arbitrary
2601 objects using a function protocol.  This protocol is discussed in 
2602 @ref{Generalized Streams}.
2603
2604 @strong{Portability Note:} The facilities described in this section are
2605 specific to GNU.  Other systems or C implementations might or might not
2606 provide equivalent functionality.
2607
2608 @menu
2609 * String Streams::
2610 * Generalized Streams::
2611 @end menu
2612
2613 @node String Streams
2614 @subsection String Streams
2615 @cindex stream, for i/o to a string
2616 @cindex string stream
2617 The @code{fmemopen} and @code{open_memstream} functions allow you to do
2618 i/o to a string or memory buffer.  These facilities are declared in
2619 @file{<stdio.h>}.
2620
2621 @comment stdio.h
2622 @comment GNU
2623 @deftypefun {FILE *} fmemopen (void *@var{a}, size_t @var{size}, const char *@var{opentype})
2624 This function opens a stream that allows the access specified by the
2625 @var{opentype} argument, that reads from or writes to the buffer specified
2626 by the argument @var{a}.  This array must be at least @var{size} bytes long.
2627
2628 @ignore
2629 @strong{Incomplete:}  This seems useless since the stream does not
2630 support file positioning.
2631
2632 If you specify a null pointer as the @var{a} argument, @code{fmemopen}
2633 will dynamically allocate (as with @code{malloc}; @pxref{Unconstrained
2634 Allocation}) an array @var{size} bytes long.  This is really only useful
2635 if you are going to write things to the buffer and then read them back
2636 in again, because you have no way of actually getting a pointer to the
2637 buffer.  The buffer is freed when the stream is open.
2638 @end ignore
2639
2640 If the @var{opentype} specifies append mode, then the initial file
2641 position is set to the first null character in the buffer.  Otherwise
2642 the initial file position is at the beginning of the buffer.  The newly
2643 created stream does not support file positioning operations.
2644
2645 When a stream open for writing is flushed or closed, a null character
2646 (zero byte) is written at the end of the buffer if it will fit.  You
2647 should add an extra byte to the @var{size} argument to account for this.
2648 Attempts to write more than @var{size} bytes to the buffer result
2649 in an error.
2650
2651 For a stream open for reading, null characters (zero bytes) in the
2652 buffer are @emph{not} significant.  Read operations return end-of-file
2653 only when the file position advances past @var{size} bytes.  So, if you
2654 want to read characters from a null-terminated string, you should supply
2655 the length of the string as the @var{size} argument.
2656 @end deftypefun
2657
2658 Here is an example of using @code{fmemopen} to create a stream for
2659 reading from a string:
2660
2661 @example
2662 #include <stdio.h>
2663
2664 static char buffer[] = "foobar";
2665
2666 void main (void)
2667 @{
2668   int ch;
2669   FILE *stream;
2670
2671   stream = fmemopen (buffer, strlen(buffer), "r");
2672   while ((ch = fgetc (stream)) != EOF)
2673     printf ("Got %c\n", ch);
2674   fclose (stream);
2675 @}
2676 @end example
2677
2678 This program produces the following output:
2679
2680 @example
2681 Got f
2682 Got o
2683 Got o
2684 Got b
2685 Got a
2686 Got r
2687 @end example
2688
2689 @comment stdio.h
2690 @comment GNU
2691 @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t @var{sizeloc})
2692 This function opens a stream for writing to a buffer.  The buffer is
2693 allocated dynamically (as with @code{malloc}; @pxref{Unconstrained
2694 Allocation}) and grown as necessary.
2695
2696 When the stream is closed with @code{fclose} or flushed with
2697 @code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
2698 contain the pointer to the buffer and its size.  If you do an
2699 @code{fflush} and then further output operations on the stream, you can
2700 no longer depend on these pointers being accurate.  You must flush or
2701 close the stream again to update them.
2702
2703 A null character is written at the end of the buffer.  This null character
2704 is @emph{not} included in the size value stored at @var{sizeloc}.
2705 @end deftypefun
2706
2707 Here is an example of using @code{open_memstream}:
2708
2709 @example
2710 #include <stdio.h>
2711
2712 void main (void)
2713 @{
2714   char *bp;
2715   size_t size;
2716   FILE *stream;
2717
2718   stream = open_memstream (&bp, &size);
2719   fprintf (stream, "hello");
2720   fflush (stream);
2721   printf ("buf = %s, size = %d\n", bp, size);
2722   fprintf (stream, ", world");
2723   fclose (stream);
2724   printf ("buf = %s, size = %d\n", bp, size);
2725 @}
2726 @end example
2727
2728 This program produces the following output:
2729
2730 @example
2731 buf = hello, size = 5
2732 buf = hello, world, size = 12
2733 @end example
2734
2735 @node Generalized Streams
2736 @subsection Generalized Streams
2737
2738 This section describes how you can make a stream that gets input from an
2739 arbitrary data source or writes output to an arbitrary data sink.  We
2740 refer to this source or sink as a @dfn{cookie}.  The cookie is specified
2741 as a pointer value (a @code{void *}), but the cookie can point to any
2742 kind of object that you want to use to keep track of state information
2743 for the stream.
2744 @cindex cookie, for generalized streams
2745 @cindex generalized streams
2746
2747 The protocol for transferring data to or from the cookie is defined by
2748 a set of functions.  You provide appropriate definitions for these 
2749 functions, and store them in an @code{__io_functions} data structure.
2750
2751 These facilities are declared in @file{<stdio.h>}.
2752
2753 @comment stdio.h
2754 @comment GNU
2755 @deftp {Data Type} __io_functions
2756 This is a structure type that holds the functions that define the 
2757 communications protocol between the stream and its cookie.  It has
2758 the following members:
2759
2760 @table @code
2761 @item __io_read *__read
2762 This is the function that reads data from the cookie.  If the value is a
2763 null pointer, then read operations will always return @code{EOF}.
2764
2765 @item __io_write *__write
2766 This is the function that writes data to the cookie.  If the value is a
2767 null pointer, then data written to the stream is discarded.
2768
2769 @item __io_seek *__seek
2770 This is the function that performs the equivalent of file positioning
2771 on the cookie.  If the value is a null pointer, calls to @code{fseek}
2772 on this stream return an @code{ESPIPE} error.
2773
2774 @item __io_close *__close
2775 This function performs any appropriate cleanup on the cookie when closing
2776 the stream.  If the value is a null pointer, nothing special is done
2777 to close the cookie when the stream is closed.
2778 @end table
2779 @end deftp
2780
2781 Here are more details on how you should define the individual functions
2782 stored in this structure.
2783
2784 @comment stdio.h
2785 @comment GNU
2786 @deftp {Data Type} __io_read
2787 You should define the function to read data from the cookie as:
2788
2789 @example
2790 int @var{function} (void *@var{cookie}, void *@var{buffer}, size_t @var{size})
2791 @end example
2792
2793 This is very similar to the @code{read} function; @pxref{Input and
2794 Output Primitives}.  Your function should transfer up to @var{size}
2795 bytes into the @var{buffer}, and return the number of bytes read.
2796 You can return a value of @code{-1} to indicate an error.
2797 @end deftp
2798
2799 @comment stdio.h
2800 @comment GNU
2801 @deftp {Data Type} __io_write
2802 You should define the function to write data to the cookie as:
2803
2804 @example
2805 int @var{function} (void *@var{cookie}, const void *@var{buffer}, size_t @var{size})
2806 @end example
2807
2808 This is very similar to the @code{write} function; @pxref{Input and
2809 Output Primitives}.  Your function should transfer up to @var{size}
2810 bytes from the buffer, and return the number of bytes written.  You can
2811 return a value of @code{-1} to indicate an error.
2812 @end deftp
2813
2814 @comment stdio.h
2815 @comment GNU
2816 @deftp {Data Type} __io_seek
2817 You should define the function to perform seek operations on the cookie as:
2818
2819 @example
2820 int @var{function} (void *@var{cookie}, fpos_t *@var{position}, int @var{whence})
2821 @end example
2822
2823 For this function, the @code{position} and @code{whence} arguments are
2824 interpreted as for @code{fgetpos}; @pxref{Text and Binary Streams}.
2825 Remember that in the GNU system, @code{fpos_t} is equivalent to
2826 @code{off_t} or @code{long int}, and simply represents the number of
2827 bytes from the beginning of the file.
2828
2829 After doing the seek operation, your function should store the resulting 
2830 file position relative to the beginning of the file in @var{position}.
2831 Your function should return a value of @code{0} on success and @code{-1}
2832 to indicate an error.
2833 @end deftp
2834
2835 @comment stdio.h
2836 @comment GNU
2837 @deftp {Data Type} __io_close
2838 You should define the function to do cleanup operations on the cookie
2839 appropriate for closing the stream as:
2840
2841 @example
2842 int @var{function} (void *@var{cookie})
2843 @end example
2844
2845 Your function should return @code{-1} to indicate an error, and @code{0}
2846 otherwise.
2847 @end deftp
2848
2849 @comment stdio.h
2850 @comment GNU
2851 @deftypevar __io_functions __default_io_functions
2852 This is the default set of functions used internally for streams associated
2853 with file descriptors.  Their cookie argument is treated as an @code{int *},
2854 pointing to a location containing the file descriptor.
2855
2856 @strong{Incomplete:}  Why should we publicize this?
2857 @end deftypevar
2858
2859 @comment stdio.h
2860 @comment GNU
2861 @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, __io_functions @var{io_functions})
2862 This function actually creates the stream for communicating with the
2863 @var{cookie} using the functions in the @var{io_functions} argument.
2864 The @var{opentype} argument is interpreted as for @code{fopen};
2865 @pxref{Opening and Closing Streams}.  (But note that the ``truncate on
2866 open'' option is ignored.)
2867
2868 @strong{Incomplete:} What is the default buffering mode for the newly
2869 created stream?
2870
2871 The @code{fopencookie} function returns the newly created stream, or a null
2872 pointer in case of an error.
2873 @end deftypefun
2874
2875 @strong{Incomplete:}  Roland says:
2876
2877 @quotation
2878 There is another set of functions one can give a stream, the
2879 input-room and output-room functions.  These functions must
2880 understand stdio internals.  To describe how to use these
2881 functions, you also need to document lots of how stdio works
2882 internally (which isn't relevant for other uses of stdio).
2883 Perhaps I can write an interface spec from which you can write
2884 good documentation.  But it's pretty complex and deals with lots
2885 of nitty-gritty details.  I think it might be better to let this
2886 wait until the rest of the manual is more done and polished.
2887 @end quotation
2888
2889 @strong{Incomplete:}  This section could use an example.