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