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