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