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