fixed cross ref
[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.  Write the
1420 expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the flag
1421 bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to extract
1422 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{double}.
1456
1457 @strong{Incomplete:}  Should this be @code{float} instead?  How do you
1458 encode the type of @code{float *}?
1459 @end deftypevr
1460
1461 @comment printf.h
1462 @comment GNU
1463 @deftypevr Macro int PA_LAST
1464 You can define additional base types for your own programs as offsets
1465 from @code{PA_LAST}.  For example, if you have data types @samp{foo}
1466 and @samp{bar} with their own specialized @code{printf} conversions,
1467 you could define encodings for these types as:
1468
1469 @example
1470 #define PA_FOO  PA_LAST
1471 #define PA_BAR  (PA_LAST + 1)
1472 @end example
1473 @end deftypevr
1474
1475 Here are the flag bits that modify a basic type.  They are combined with
1476 the code for the basic type using inclusive-or.
1477
1478 @comment printf.h
1479 @comment GNU
1480 @deftypevr Macro int PA_FLAG_PTR
1481 If this bit is set, it indicates that the encoded type is a pointer to
1482 the base type, rather than an immediate value.
1483 For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.
1484 @end deftypevr
1485
1486 @comment printf.h
1487 @comment GNU
1488 @deftypevr Macro int PA_FLAG_SHORT
1489 If this bit is set, it indicates that the base type is modified with
1490 @code{short}.  (This corresponds to the @samp{h} type modifier.)
1491 @end deftypevr
1492
1493 @comment printf.h
1494 @comment GNU
1495 @deftypevr Macro int PA_FLAG_LONG
1496 If this bit is set, it indicates that the base type is modified with
1497 @code{long}.  (This corresponds to the @samp{l} type modifier.)
1498 @end deftypevr
1499
1500 @comment printf.h
1501 @comment GNU
1502 @deftypevr Macro int PA_FLAG_LONGLONG
1503 If this bit is set, it indicates that the base type is modified with
1504 @code{long long}.  (This corresponds to the @samp{L} type modifier.)
1505 @end deftypevr
1506
1507 @comment printf.h
1508 @comment GNU
1509 @deftypevr Macro int PA_FLAG_LONGDOUBLE
1510 This is a synonym for @code{PA_FLAG_LONGLONG}, used by convention with
1511 a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
1512 @end deftypevr
1513
1514 @strong{Incomplete:} Should have an example here from a fictional
1515 interpreter, showing how one might validate a list of args and then
1516 call @code{vprintf}.
1517
1518 @node Customizing Printf
1519 @section Customizing Printf
1520 @cindex customizing @code{printf}
1521 @cindex defining new @code{printf} conversions
1522 @cindex extending @code{printf}
1523
1524 The GNU C library lets you define your own custom conversion specifiers
1525 for @code{printf} template strings, to teach @code{printf} clever ways
1526 to print the important data structures of your program.
1527
1528 The way you do this is by registering the conversion with
1529 @code{register_printf_function}; see @ref{Registering New Conversions}.
1530 One of the arguments you pass to this function is a pointer to a handler
1531 function that produces the actual output; see @ref{Defining the Output
1532 Handler}, for information on how to write this function.
1533
1534 You can also install a function that just returns information about the
1535 number and type of arguments expected by the conversion specifier.
1536 @xref{Parsing a Template String}, for information about this.
1537
1538 The facilities of this section are declared in the header file
1539 @file{printf.h}.
1540
1541 @menu
1542 * Registering New Conversions::
1543 * Conversion Specifier Options::
1544 * Defining the Output Handler::
1545 * Printf Extension Example::
1546 @end menu
1547
1548 @strong{Portability Note:} The ability to extend the syntax of
1549 @code{printf} template strings is a GNU extension.  ANSI standard C has
1550 nothing similar.
1551
1552 @node Registering New Conversions
1553 @subsection Registering New Conversions
1554
1555 The function to register a new output conversion is
1556 @code{register_printf_function}, declared in @file{printf.h}.
1557 @pindex printf.h
1558
1559 @comment printf.h
1560 @comment GNU
1561 @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler_function}, printf_arginfo_function @var{arginfo_function})
1562 This function defines the conversion specifier character @var{spec}.
1563 Thus, if @var{spec} is @code{'q'}, it defines the conversion @samp{%q}.
1564
1565 The @var{handler_function} is the function called by @code{printf} and
1566 friends when this conversion appears in a template string.
1567 @xref{Defining the Output Handler}, for information about how to define
1568 a function to pass as this argument.  If you specify a null pointer, any
1569 existing handler function for @var{spec} is removed.
1570
1571 The @var{arginfo_function} is the function called by
1572 @code{parse_printf_format} when this conversion appears in a
1573 template string.  @xref{Parsing a Template String}, for information
1574 about this.
1575
1576 Normally, you install both functions for a conversion at the same time,
1577 but if you are never going to call @code{parse_printf_format}, you do
1578 not need to define an arginfo function.
1579
1580 The return value is @code{0} on success, and @code{-1} on failure
1581 (which occurs if @var{spec} is out of range).
1582
1583 You can redefine the standard output conversions, but this is probably
1584 not a good idea because of the potential for confusion.  Library routines
1585 written by other people could break if you do this.
1586 @end deftypefun
1587
1588 @node Conversion Specifier Options
1589 @subsection Conversion Specifier Options
1590
1591 If you define a meaning for @samp{%q}, what if the template contains
1592 @samp{%+Sq} or @samp{%-#q}?  To implement a sensible meaning for these,
1593 the handler when called needs to be able to get the options specified in
1594 the template.
1595
1596 Both the @var{handler_function} and @var{arginfo_function} arguments
1597 to @code{register_printf_function} accept an argument of type
1598 @code{struct print_info}, which contains information about the options
1599 appearing in an instance of the conversion specifier.  This data type
1600 is declared in the header file @file{printf.h}.
1601 @pindex printf.h
1602
1603 @comment printf.h
1604 @comment GNU
1605 @deftp {struct Type} printf_info
1606 This structure is used to pass information about the options appearing
1607 in an instance of a conversion specifier in a @code{printf} template
1608 string to the handler and arginfo functions for that specifier.  It
1609 contains the following members:
1610
1611 @table @code
1612 @item int prec
1613 This is the precision specified.  The value is @code{-1} if no precision
1614 was specified.  If the precision was given as @samp{*}, the
1615 @code{printf_info} structure passed to the handler function contains the
1616 actual value retrieved from the argument list.  But the structure passed
1617 to the arginfo function contains a value of @code{INT_MIN}, since the
1618 actual value is not known.
1619
1620 @item int width
1621 This is the minimum field width specified.  The value is @code{0} if no
1622 width was specified.  If the field width was given as @samp{*}, the
1623 @code{printf_info} structure passed to the handler function contains the
1624 actual value retrieved from the argument list.  But the structure passed
1625 to the arginfo function contains a value of @code{INT_MIN}, since the
1626 actual value is not known.
1627
1628 @item char spec
1629 This is the conversion specifier character specified.  It's stored in
1630 the structure so that you can register the same handler function for
1631 multiple characters, but still have a way to tell them apart when the
1632 handler function is called.
1633
1634 @item unsigned int is_long_double
1635 This is a boolean that is true if the @samp{L} type modifier was specified.
1636
1637 @item unsigned int is_short
1638 This is a boolean that is true if the @samp{h} type modifier was specified.
1639
1640 @item unsigned int is_long
1641 This is a boolean that is true if the @samp{l} type modifier was specified.
1642
1643 @item unsigned int alt
1644 This is a boolean that is true if the @samp{#} flag was specified.
1645
1646 @item unsigned int space
1647 This is a boolean that is true if the @samp{ } flag was specified.
1648
1649 @item unsigned int left
1650 This is a boolean that is true if the @samp{-} flag was specified.
1651
1652 @item unsigned int showsign
1653 This is a boolean that is true if the @samp{+} flag was specified.
1654
1655 @item char pad
1656 This is the character to use for padding the output to the minimum field
1657 width.  The value is @code{'0'} if the @samp{0} flag was specified, and
1658 @code{' '} otherwise.
1659 @end table
1660 @end deftp
1661
1662
1663 @node Defining the Output Handler
1664 @subsection Defining the Output Handler
1665
1666 Now let's look at how to define the handler and arginfo functions
1667 which are passed as arguments to @code{register_printf_function}.
1668
1669 You should define your handler functions with a prototype like:
1670
1671 @example
1672 int @var{function} (FILE *stream, const struct printf_info *info,
1673                     va_list *ap_pointer)
1674 @end example
1675
1676 The @code{stream} argument passed to the handler function is the stream to
1677 which it should write output.
1678
1679 The @code{info} argument is a pointer to a structure that contains
1680 information about the various options that were included with the
1681 conversion in the template string.  You should not modify this structure
1682 inside your handler function.  @xref{Conversion Specifier Options}, for
1683 a description of this data structure.
1684
1685 The @code{ap_pointer} argument is used to pass the tail of the variable
1686 argument list containing the values to be printed to your handler.
1687 Unlike most other functions that can be passed an explicit variable
1688 argument list, this is a @emph{pointer} to a @code{va_list}, rather than
1689 the @code{va_list} itself.  Thus, you should fetch arguments by
1690 means of @code{va_arg (@var{type}, *ap_pointer)}.
1691
1692 (Passing a pointer here allows the function that calls your handler
1693 function to update its own @code{va_list} variable to account for the
1694 arguments that your handler processes.  @xref{Variable Argument
1695 Facilities}.)
1696
1697 The return value from your handler function should be the number of
1698 argument values that it processes from the variable argument list.  You
1699 can also return a value of @code{-1} to indicate an error.
1700
1701 @comment printf.h
1702 @comment GNU
1703 @deftp {Data Type} printf_function
1704 This is the data type that a handler function should have.
1705 @end deftp
1706
1707 If you are going to use @code{parse_printf_format} in your
1708 application, you should also define a function to pass as the
1709 @var{arginfo_function} argument for each new conversion you install with
1710 @code{register_printf_function}. 
1711
1712 You should define these functions with a prototype like:
1713
1714 @example
1715 int @var{function} (const struct printf_info *info,
1716                     size_t n, int *argtypes)
1717 @end example
1718
1719 The return value from the function should be the number of arguments
1720 the conversion expects, up to a maximum of @var{n}.  The function should
1721 also fill in the @var{argtypes} array with information about the types
1722 of each of these arguments.  This information is encoded using the
1723 various @samp{PA_} macros.
1724
1725 @comment printf.h
1726 @comment GNU
1727 @deftp {Data Type} printf_arginfo_function
1728 This type is used to describe functions that return information about
1729 the number and type of arguments used by a conversion specifier.
1730 @end deftp
1731
1732 @node Printf Extension Example
1733 @subsection Printf Extension Example
1734
1735 Here is an example showing how to define a @code{printf} handler function.
1736 This program defines a data structure called a @code{Widget} and 
1737 defines the @samp{%W} conversion to print information about @code{Widget *}
1738 arguments, including the pointer value and the name stored in the data
1739 structure.  The @samp{%W} conversion supports the minimum field width and
1740 left-justification options, but ignores everything else.
1741
1742 @example
1743 #include <stdio.h>
1744 #include <printf.h>
1745 #include <stdarg.h>
1746
1747 struct widget 
1748 @{
1749   char *name;
1750   @dots{}
1751 @};
1752
1753 int
1754 print_widget (FILE *stream, const struct printf_info *info,
1755               va_list *app)
1756 @{
1757   struct widget *w;
1758   char *buffer;
1759   int padding_amount, i;
1760
1761   /* @r{Fetch the widget to be printed.} */
1762   w = va_arg (*app, struct widget *);
1763   /* @r{Format the output into a string.} */
1764   padding_amount
1765     = (info->width -
1766        asprintf (&buffer, "<Widget %p: %s>", w, w->name));
1767
1768   /* @r{Pad to the minimum field width and print to the stream.} */
1769   if (!info->left)
1770     for (i = 0; i < padding_amount; i++) fputc (' ', stream);
1771   fputs (buffer, stream);
1772   if (info->left)
1773     for (i = 0; i < padding_amount; i++) fputc (' ', stream);
1774
1775   /* @r{Clean up and return.} */
1776   free (buffer);
1777   return 1;
1778 @}
1779
1780 void
1781 main (void)
1782 @{
1783   /* @r{Make a widget to print.} */
1784   struct widget mywidget;
1785   mywidget.name = "mywidget";
1786
1787   /* @r{Register the print function for widgets.} */
1788   register_printf_function ('W', print_widget, NULL);
1789
1790   /* @r{Now print the widget.} */
1791   printf ("|%W|\n", &mywidget);
1792   printf ("|%35W|\n", &mywidget);
1793   printf ("|%-35W|\n", &mywidget);
1794 @}
1795 @end example
1796
1797 The output produced by this program looks like:
1798
1799 @example
1800 |<Widget 0xffeffb7c: mywidget>|
1801 |      <Widget 0xffeffb7c: mywidget>|
1802 |<Widget 0xffeffb7c: mywidget>      |
1803 @end example
1804
1805 @node Formatted Input
1806 @section Formatted Input
1807
1808 @cindex formatted input from a stream
1809 @cindex reading from a stream, formatted
1810 @cindex format string, for @code{scanf}
1811 @cindex template, for @code{scanf}
1812 The functions described in this section (@code{scanf} and related
1813 functions) provide facilities for formatted input analogous to the
1814 formatted output facilities.  These functions provide a mechanism for
1815 reading arbitrary values under the control of a @dfn{format string} or
1816 @dfn{template string}.
1817
1818 @menu
1819 * Formatted Input Basics::      Some basics to get you started.
1820 * Input Conversion Syntax::     Syntax of conversion specifications.
1821 * Table of Input Conversions::  Summary of input conversions and what they do.
1822 * Numeric Input Conversions::   Details of conversions for reading numbers.
1823 * String Input Conversions::    Details of conversions for reading strings.
1824 * Other Input Conversions::     Details of miscellaneous other conversions.
1825 * Formatted Input Functions::   Descriptions of the actual functions.
1826 * Variable Arguments Input Functions::   @code{vscanf} and friends.
1827 @end menu
1828
1829 @node Formatted Input Basics
1830 @subsection Formatted Input Basics
1831
1832 Calls to @code{scanf} are superficially similar to calls to
1833 @code{printf} in that arbitrary arguments are read under the control of
1834 a template string.  While the syntax of the conversion
1835 specifications in the template is very similar to that for
1836 @code{printf}, the interpretation of the template is oriented more
1837 towards free-format input and simple pattern matching, rather than
1838 fixed-field formatting.  For example, most @code{scanf} conversions skip
1839 over any amount of ``white space'' (including spaces, tabs, newlines) in
1840 the input file, and there is no concept of precision for the numeric
1841 input conversions as there is for the corresponding output conversions.
1842 Ordinary, non-whitespace characters in the template are expected to
1843 match characters in the input stream exactly, but a matching failure is
1844 distinct from an input error on the stream.
1845 @cindex conversion specifications (@code{scanf})
1846
1847 Another area of difference between @code{scanf} and @code{printf} is
1848 that you must remember to supply pointers rather than immediate values
1849 as the optional arguments to @code{scanf}; the values that are read are
1850 stored in the objects that the pointers point to.  Even experienced
1851 programmers tend to forget this occasionally, so if your program is
1852 getting strange errors that seem to be related to @code{scanf}, you
1853 might want to doublecheck this.
1854
1855 When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
1856 leaving the first non-matching character as the next character to be
1857 read from the stream.  The normal return value from @code{scanf} is the
1858 number of values that were assigned, so you can use this to determine if
1859 a matching error happened before all the expected values were read.
1860 @cindex matching failure, in @code{scanf}
1861
1862 The @code{scanf} function is typically used to do things like reading
1863 in the contents of tables.  For example, here is a function that uses
1864 @code{scanf} to initialize an array of @code{double}s:
1865
1866 @example
1867 void
1868 readarray (double *array, int n)
1869 @{
1870   int i;
1871   for (i=0; i<n; i++)
1872     if (scanf (" %lf", &(array[i])) != 1)
1873       input_failure ();
1874 @}
1875 @end example
1876
1877 The formatted input functions are not used as frequently as the
1878 formatted output functions.  Partly, this is because it takes some care
1879 to use them properly.  Another reason is that it is difficult to recover
1880 from a matching error.
1881
1882 If you are trying to read input that doesn't match a single, fixed
1883 pattern, you may be better off using a tool such as Bison to generate
1884 a parser, rather than using @code{scanf}.  For more information about
1885 this, see @cite{The Bison Reference Manual}.
1886 @c ??? Don't use @cite, use @xref with five args.
1887
1888 @node Input Conversion Syntax
1889 @subsection Input Conversion Syntax
1890
1891 A @code{scanf} template string is a string that contains ordinary
1892 multibyte characters and conversion specifications introduced by a
1893 @samp{%} character.
1894
1895 Any whitespace character (as defined by the @code{isspace} function;
1896 @pxref{Classification of Characters}) in the template causes any number
1897 of whitespace characters in the input stream to be read and discarded.
1898 The whitespace characters that are matched need not be exactly the same
1899 whitespace characters that appear in the template string.  For example,
1900 write @samp{ , } in the template to recognize a comma with optional
1901 whitespace before and after.
1902
1903 Other characters in the template string that are not part of conversion
1904 specifications must match characters in the input stream exactly; if
1905 this is not the case, a matching failure occurs.
1906
1907 The conversion specifications in a @code{scanf} template string
1908 have the general form:
1909
1910 @example
1911 % @var{flags} @var{width} @var{type} @var{conversion}
1912 @end example
1913
1914 More specifically, input conversion specifications consist of an initial
1915 @samp{%} character followed in sequence by:
1916
1917 @itemize @bullet
1918 @item
1919 An optional @dfn{flag character} @samp{*}, which causes assignment to be
1920 suppressed.  If this flag appears, input is read from the stream and
1921 matched against the conversion specification in the usual way, but no
1922 optional pointer argument is used, no assignment takes place, and the
1923 count of successful assignments is not incremented.
1924 @cindex flag character (@code{scanf})
1925
1926 @item
1927 An optional decimal integer that specifies the @dfn{maximum field
1928 width}.  Reading of characters from the input stream stops either when
1929 this maximum is reached or when a non-matching character is found,
1930 whichever happens first.  Most conversions discard initial whitespace
1931 characters (those that don't are explicitly documented), and these
1932 discarded characters don't count towards the maximum field width.
1933 Most input conversions store a null character to mark the end of the
1934 input; the maximum field width does not include this terminator.
1935 @cindex maximum field width (@code{scanf})
1936
1937 @item
1938 An optional @dfn{type modifier character}.  For example, you can
1939 specify a type modifier of @samp{l} with integer conversions such as
1940 @samp{%d} to specify that the argument is a pointer to a @code{long int}
1941 rather than a pointer to an @code{int}.
1942 @cindex type modifier character (@code{scanf})
1943
1944 @item
1945 A character that specifies the conversion to be applied.
1946 @end itemize
1947
1948 The exact options that are permitted and how they are interpreted vary 
1949 between the different conversion specifiers.  See the descriptions of the
1950 individual conversions for information about the particular options that
1951 they use.
1952
1953 @node Table of Input Conversions
1954 @subsection Table of Input Conversions
1955 @cindex input conversions, for @code{scanf}
1956
1957 Here is a table that summarizes the various conversion specifications:
1958
1959 @table @asis
1960 @item @samp{%d}
1961 Matches an optionally signed integer written in decimal.  @xref{Numeric
1962 Input Conversions}.
1963
1964 @item @samp{%i}
1965 Matches an optionally signed integer in any of the formats that the C
1966 language defines for specifying an integer constant.  @xref{Numeric
1967 Input Conversions}.
1968
1969 @item @samp{%o}
1970 Matches an unsigned integer in octal radix.  @xref{Numeric
1971 Input Conversions}.
1972
1973 @item @samp{%u}
1974 Matches an unsigned integer in decimal radix.  @xref{Numeric
1975 Input Conversions}.
1976
1977 @item @samp{%x}, @samp{%X}
1978 Matches an unsigned integer in hexadecimal radix.  @xref{Numeric
1979 Input Conversions}.
1980
1981 @item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
1982 Matches an optionally signed floating-point number.  @xref{Numeric Input
1983 Conversions}.
1984
1985 @item @samp{%s}
1986 Matches a string of non-whitespace characters.  @xref{String Input
1987 Conversions}.
1988
1989 @item @samp{%[}
1990 Matches a string of characters that belong to a specified set.
1991 @xref{String Input Conversions}.
1992
1993 @item @samp{%c}
1994 Matches a string of one or more characters; the number of characters
1995 read is controlled by the maximum field width given for the conversion.
1996 @xref{String Input Conversions}.
1997
1998 @item @samp{%p}
1999 Matches a pointer value in the same implementation-defined format used
2000 by the @samp{%p} output conversion for @code{printf}.  @xref{Other Input
2001 Conversions}.
2002
2003 @item @samp{%n}
2004 This conversion doesn't read any characters; it records the number of
2005 characters read so far by this call.  @xref{Other Input Conversions}.
2006
2007 @item @samp{%%}
2008 This matches a literal @samp{%} character in the input stream.  No
2009 corresponding argument is used.  @xref{Other Input Conversions}.
2010 @end table
2011
2012 If the syntax of a conversion specification is invalid, the behavior is
2013 undefined.  If there aren't enough function arguments provided to supply
2014 addresses for all the conversion specifications in the template strings
2015 that perform assignments, or if the arguments are not of the correct
2016 types, the behavior is also undefined.  On the other hand, if there are
2017 extra arguments, their values are simply ignored.
2018
2019 @node Numeric Input Conversions
2020 @subsection Numeric Input Conversions
2021
2022 This section describes the @code{scanf} conversions for reading numeric
2023 values.
2024
2025 The @samp{%d} conversion matches an optionally signed integer in decimal
2026 radix.  The syntax that is recognized is the same as that for the
2027 @code{strtol} function (@pxref{Parsing of Integers}) with the value
2028 @code{10} for the @var{base} argument.
2029
2030 The @samp{%i} conversion matches an optionally signed integer in any of
2031 the formats that the C language defines for specifying an integer
2032 constant.  The syntax that is recognized is the same as that for the
2033 @code{strtol} function (@pxref{Parsing of Integers}) with the value
2034 @code{0} for the @var{base} argument.
2035
2036 For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
2037 could be read in as integers under the @samp{%i} conversion.  Each of
2038 these specifies a number with decimal value @code{10}.
2039
2040 The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned
2041 integers in octal, decimal, and hexadecimal radices, respectively.  The
2042 syntax that is recognized is the same as that for the @code{strtoul}
2043 function (@pxref{Parsing of Integers}) with the appropriate value
2044 (@code{8}, @code{10}, or @code{16}) for the @var{base} argument.
2045
2046 The @samp{%X} conversion is identical to the @samp{%x} conversion.  They
2047 both permit either uppercase or lowercase letters to be used as digits.
2048
2049 The default type of the corresponding argument for the @code{%d} and
2050 @code{%i} conversions is @code{int *}, and @code{unsigned int *} for the
2051 other integer conversions.  You can use the following type modifiers to
2052 specify other sizes of integer:
2053
2054 @table @samp
2055 @item h
2056 Specifies that the argument is a @code{short int *} or @code{unsigned
2057 short int *}.
2058
2059 @item l
2060 Specifies that the argument is a @code{long int *} or @code{unsigned
2061 long int *}.
2062
2063 @item L
2064 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
2065 GNU C compiler.  For systems that don't provide extra-long integers, this
2066 is the same as @code{long int}.)
2067 @end table
2068
2069 All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
2070 input conversions are interchangable.  They all match an optionally
2071 signed floating point number, in the same syntax as for the
2072 @code{strtod} function (@pxref{Parsing of Floats}).
2073
2074 For the floating-point input conversions, the default argument type is
2075 @code{float *}.  (This is different from the corresponding output
2076 conversions, where the default type is @code{double}; remember that
2077 @code{float} arguments to @code{printf} are converted to @code{double}
2078 by the default argument promotions, but @code{float *} arguments are
2079 not promoted to @code{double *}.)  You can specify other sizes of float
2080 using these type modifiers:
2081
2082 @table @samp
2083 @item l
2084 Specifies that the argument is of type @code{double *}.
2085
2086 @item L
2087 Specifies that the argument is of type @code{long double *}.
2088 @end table
2089
2090 @node String Input Conversions
2091 @subsection String Input Conversions
2092
2093 This section describes the @code{scanf} input conversions for reading
2094 string and character values: @samp{%s}, @samp{%[}, and @samp{%c}.  
2095 The corresponding argument for all of these conversions should be of
2096 type @code{char *}.
2097
2098 @strong{Warning:} the argument points to an array of characters where
2099 the input is stored.  To make a robust program, you must make sure that
2100 the input (including terminating null) cannot possibly exceed the size
2101 of this array.  In general, the only way to do this is to specify a
2102 maximum field width equal to the size you have allocated (minus one, to
2103 leave room for the terminating null).  @strong{Always specify a field
2104 width to limit the number of characters read.}
2105
2106 The @samp{%c} conversion is the simplest.  It matches a fixed-sized
2107 string of characters.  The number of characters read is controlled by
2108 the maximum field width.  If you don't supply a field width, then only
2109 one character is read.  Note that this conversion doesn't append a null
2110 character to the end of the string it reads.  It also does not skip over
2111 initial whitespace characters.
2112
2113 The @samp{%s} conversion matches a string of non-whitespace characters.
2114 Unlike @samp{%c}, this conversion does skip over initial whitespace and
2115 does mark the end of the string with a null character.
2116
2117 @strong{Warning:} If you do not specify a field width for @samp{%s},
2118 then the number of characters read is limited only by where the next
2119 whitespace character appears.  This almost certainly means your program
2120 will crash if given invalid input.
2121
2122 For example, reading the input:
2123
2124 @example
2125  hello, world
2126 @end example
2127
2128 @noindent
2129 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
2130 reading the same input with the conversion @samp{%10s} produces
2131 @code{"hello,"}.
2132
2133 The @samp{%s} conversion effectively reads in characters that belong to
2134 the set of non-whitespace characters.  To read in characters that belong
2135 to an arbitrary set, you can use the @samp{%[} conversion.  The
2136 characters which make up the set are specified immediately following the
2137 @samp{[} character, up to a matching @samp{]} character.  As special
2138 cases:
2139
2140 @itemize @bullet
2141 @item 
2142 If a caret character @samp{^} immediately follows the
2143 initial @samp{[}, then the set that is used for matching is the
2144 @emph{complement} of the set of characters that are explicitly listed.
2145
2146 @item 
2147 A literal @samp{]} character can be specified as the first character
2148 of the set.
2149
2150 @item 
2151 An embedded @samp{-} character (that is, one that is not the first or
2152 last character of the set) is used to specify a range of characters.
2153 @end itemize
2154
2155 The @samp{%[} conversion does not skip over initial whitespace
2156 characters.
2157
2158 Here are some examples of @samp{%[} conversions and what they mean.
2159
2160 @table @samp
2161 @item %25[1234567890]
2162 Matches a string of up to 25 digits.
2163
2164 @item %25[][]
2165 Matches a string of up to 25 square brackets.
2166
2167 @item %25[^ \f\n\r\t\v]
2168 Matches a string up to 25 characters long that doesn't contain any of
2169 the standard whitespace characters.  This is slightly different from
2170 @samp{%s}, because if the input begins with a whitespace character,
2171 @samp{%[} reports a matching failure while @samp{%s} simply discards the
2172 initial whitespace.
2173
2174 @item %[a-z] 
2175 Matches a string of lowercase characters.
2176 @end table
2177
2178 One more reminder: the @samp{%s} and @samp{%[} conversions are
2179 potentially @strong{dangerous} if you don't specify a maximum width,
2180 because input too long would overflow whatever buffer you have provided
2181 for it.  No matter how long your buffer is, a user could supply input
2182 that is longer.  Don't assume that the input will be short enough to
2183 fit; a well-written program reports invalid input with a comprehensible
2184 error message, not with a crash.
2185
2186 So make your programs clean---@strong{always} specify a maximum field
2187 width with the @samp{%s} and @samp{%[} conversions.  Then you will
2188 probably get a matching error instead if the input string is too long,
2189 and you can detect this and report it properly.
2190
2191
2192 @node Other Input Conversions
2193 @subsection Other Input Conversions
2194
2195 This section describes the miscellaneous input conversions.
2196
2197 The @samp{%p} conversion is used to read a pointer value.  It recognizes
2198 the same syntax as is used by the @samp{%p} output conversion for
2199 @code{printf}.  The corresponding argument should be of type @code{void **};
2200 that is, the address of a place to store a pointer.
2201
2202 The resulting pointer value is not guaranteed to be valid if it was not
2203 originally written during the same program execution that reads it in.
2204
2205 The @samp{%n} conversion produces the number of characters read so far
2206 by this call.  The corresponding argument should be of type @code{int *}.
2207 This conversion works in the same way as the @samp{%n} conversion for
2208 @code{printf}; see @ref{Other Output Conversions}, for an example.
2209
2210 The @samp{%n} conversion is the only mechanism for determining the
2211 success of literal matches or conversions with suppressed assignments.
2212 If the @samp{%n} follows the locus of a matching failure, then no value
2213 is stored for it since @code{scanf} returns before processing the
2214 @samp{%n}.  If you store @code{-1} in that argument slot before calling
2215 @code{scanf}, the presence of @code{-1} after @code{scanf} indicates an
2216 error before the @samp{%n} was reached.
2217
2218 Finally, the @samp{%%} conversion matches a literal @samp{%} character
2219 in the input stream, without using an argument.  This conversion does
2220 not permit any flags, field width, or type modifier to be specified.
2221
2222 @node Formatted Input Functions
2223 @subsection Formatted Input Functions
2224
2225 Here are the descriptions of the functions for performing formatted
2226 input.
2227 Prototypes for these functions are in the header file @file{stdio.h}.
2228 @pindex stdio.h
2229
2230 @comment stdio.h
2231 @comment ANSI
2232 @deftypefun int scanf (const char *@var{template}, @dots{})
2233 The @code{scanf} function reads formatted input from the stream
2234 @code{stdin} under the control of the template string @var{template}.
2235 The optional arguments are pointers to the places which receive the
2236 resulting values.
2237
2238 The return value is normally the number of successful assignments.  If
2239 an end-of-file condition is detected before any matches are performed
2240 (including matches against whitespace and literal characters in the
2241 template), then @code{EOF} is returned.
2242 @end deftypefun
2243
2244 @comment stdio.h
2245 @comment ANSI
2246 @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
2247 This function is just like @code{scanf}, except that the input is read
2248 from the stream @var{stream} instead of @code{stdin}.
2249 @end deftypefun
2250
2251 @comment stdio.h
2252 @comment ANSI
2253 @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
2254 This is like @code{scanf}, except that the characters are taken from the
2255 null-terminated string @var{s} instead of from a stream.  Reaching the
2256 end of the string is treated as an end-of-file condition.
2257
2258 The behavior of this function is undefined if copying takes place
2259 between objects that overlap---for example, if @var{s} is also given
2260 as an argument to receive a string read under control of the @samp{%s}
2261 conversion.
2262 @end deftypefun
2263
2264 @node Variable Arguments Input Functions
2265 @subsection Variable Arguments Input Functions
2266
2267 The functions @code{vscanf} and friends are provided so that you can
2268 define your own variadic @code{scanf}-like functions that make use of
2269 the same internals as the built-in formatted output functions.
2270 These functions are analogous to the @code{vprintf} series of output
2271 functions.  @xref{Variable Arguments Output Functions}, for important
2272 information on how to use them.
2273
2274 @strong{Portability Note:} The functions listed in this section are GNU
2275 extensions.
2276
2277 @comment stdio.h
2278 @comment GNU
2279 @deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
2280 This function is similar to @code{scanf} except that, instead of taking
2281 a variable number of arguments directly, it takes an argument list
2282 pointer @var{ap} of type @code{va_list} (@pxref{Variable Argument
2283 Facilities}).
2284 @end deftypefun
2285
2286 @comment stdio.h
2287 @comment GNU
2288 @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
2289 This is the equivalent of @code{fscanf} with the variable argument list
2290 specified directly as for @code{vscanf}.
2291 @end deftypefun
2292
2293 @comment stdio.h
2294 @comment GNU
2295 @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
2296 This is the equivalent of @code{sscanf} with the variable argument list
2297 specified directly as for @code{vscanf}.
2298 @end deftypefun
2299
2300 @node Block Input/Output
2301 @section Block Input/Output
2302
2303 This section describes how to do input and output operations on blocks
2304 of data.  You can use these functions to read and write binary data, as
2305 well as to read and write text in fixed-size blocks instead of by
2306 characters or lines.
2307 @cindex binary I/O to a stream
2308 @cindex block I/O to a stream
2309 @cindex reading from a stream, by blocks
2310 @cindex writing to a stream, by blocks
2311
2312 Binary files are typically used to read and write blocks of data in the
2313 same format as is used to represent the data in a running program.  In
2314 other words, arbitrary blocks of memory---not just character or string
2315 objects---can be written to a binary file, and meaningfully read in
2316 again by the same program.
2317
2318 Storing data in binary form is often considerably more efficient than
2319 using the formatted I/O functions.  Also, for floating-point numbers,
2320 the binary form avoids possible loss of precision in the conversion
2321 process.  On the other hand, binary files can't be examined or modified
2322 easily using many standard file utilities (such as text editors), and
2323 are not portable between different implementations of the language, or
2324 different kinds of computers.
2325
2326 These functions are declared in @file{stdio.h}.
2327 @pindex stdio.h
2328
2329 @comment stdio.h
2330 @comment ANSI
2331 @deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
2332 This function reads up to @var{count} objects of size @var{size} into
2333 the array @var{data}, from the stream @var{stream}.  It returns the
2334 number of objects actually read, which might be less than @var{count} if
2335 a read error or end-of-file occurs.  This function returns a value of
2336 zero (and doesn't read anything) if either @var{size} or @var{count} is
2337 zero.
2338
2339 @c ??? What happens for EOF in middle of an object?
2340 @c ??? Does this always read an integral number of objects?
2341 @end deftypefun
2342
2343 @comment stdio.h
2344 @comment ANSI
2345 @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
2346 This function writes up to @var{count} objects of size @var{size} from
2347 the array @var{data}, to the stream @var{stream}.  The return value is
2348 the number of objects actually written, which is less than @var{count}
2349 only if a write error occurs.
2350
2351 @c ??? What happens if medium is full in the middle of an object?
2352 @c ??? Does it write an incomplete object?
2353 @c ??? Can that happen in any other case?
2354 @end deftypefun
2355
2356
2357 @node End-Of-File and Errors
2358 @section End-Of-File and Errors
2359
2360 @cindex end-of-file, on a stream
2361 Many of the functions described in this chapter return the value of the
2362 macro @code{EOF} to indicate unsuccessful completion of the operation.
2363 Since @code{EOF} is used to report both end-of-file and random errors,
2364 it's often better to use the @code{feof} function to check explicitly
2365 for end-of-file and @code{ferror} to check for errors.  These functions
2366 check indicators that are part of the internal state of the stream
2367 object, indicators set if the appropriate condition was detected by a
2368 previous I/O operation on that stream.
2369
2370 These symbols are declared in the header file @file{stdio.h}.
2371 @pindex stdio.h
2372
2373 @comment stdio.h
2374 @comment ANSI
2375 @deftypevr Macro int EOF
2376 This macro is an integer value that is returned
2377 by a number of functions to indicate an end-of-file condition, or some
2378 other error situation.  With the GNU library, @code{EOF} is @code{-1}.
2379 In other libraries, its value may be some other negative number.
2380 @end deftypevr
2381
2382 @comment stdio.h
2383 @comment ANSI
2384 @deftypefun void clearerr (FILE *@var{stream})
2385 This function clears the end-of-file and error indicators for the
2386 stream @var{stream}.
2387
2388 The file positioning functions (@pxref{File Positioning}) also clear the
2389 end-of-file indicator for the stream.
2390 @end deftypefun
2391
2392 @comment stdio.h
2393 @comment ANSI
2394 @deftypefun int feof (FILE *@var{stream})
2395 The @code{feof} function returns nonzero if and only if the end-of-file
2396 indicator for the stream @var{stream} is set.
2397 @end deftypefun
2398
2399 @comment stdio.h
2400 @comment ANSI
2401 @deftypefun int ferror (FILE *@var{stream})
2402 The @code{ferror} function returns nonzero if and only if the error
2403 indicator for the stream @var{stream} is set, indicating that an error
2404 has occurred on a previous operation on the stream.
2405 @end deftypefun
2406
2407 In addition to setting the error indicator associated with the stream,
2408 the functions that operate on streams also set @code{errno} in the same
2409 way as the corresponding low-level functions that operate on file
2410 descriptors.  For example, all of the functions that perform output to a
2411 stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are
2412 implemented in terms of @code{write}, and all of the @code{errno} error
2413 conditions defined for @code{write} are meaningful for these functions.
2414 For more information about the descriptor-level I/O functions, see
2415 @ref{Low-Level Input/Output}.
2416
2417 @node Text and Binary Streams
2418 @section Text and Binary Streams
2419
2420 The GNU system and other POSIX-compatible operating systems organize all
2421 files as uniform sequences of characters.  However, some other systems
2422 make a distinction between files containing text and files containing
2423 binary data, and the input and output facilities of ANSI C provide for
2424 this distinction.  This section tells you how to write programs portable
2425 to such systems.
2426
2427 @cindex text stream
2428 @cindex binary stream
2429 When you open a stream, you can specify either a @dfn{text stream} or a
2430 @dfn{binary stream}.  You indicate that you want a binary stream by
2431 specifying the @samp{b} modifier in the @var{opentype} argument to
2432 @code{fopen}; see @ref{Opening and Closing Streams}.  Without this
2433 option, @code{fopen} opens the file as a text stream.
2434
2435 Text and binary streams differ in several ways:
2436
2437 @itemize @bullet
2438 @item
2439 The data read from a text stream is divided into @dfn{lines} which are
2440 terminated by newline (@code{'\n'}) characters, while a binary stream is
2441 simply a long series of characters.  A text stream might on some systems
2442 fail to handle lines more than 254 characters long (including the
2443 terminating newline character).
2444 @cindex lines (in a text file)
2445
2446 @item
2447 On some systems, text files can contain only printing characters,
2448 horizontal tab characters, and newlines, and so text streams may not
2449 support other characters.  However, binary streams can handle any
2450 character value.
2451
2452 @item
2453 Space characters that are written immediately preceeding a newline
2454 character in a text stream may disappear when the file is read in again.
2455
2456 @item
2457 More generally, there need not be a one-to-one mapping between
2458 characters that are read from or written to a text stream, and the
2459 characters in the actual file.
2460 @end itemize
2461
2462 Since a binary stream is always more capable and more predictable than a
2463 text stream, you might wonder what purpose text streams serve.  Why not
2464 simply always use binary streams?  The answer is that on these operating
2465 systems, text and binary streams use different file formats, and the
2466 only way to read or write ``an ordinary file of text'' that can work
2467 with other text-oriented programs is through a text stream.
2468
2469 @c ??? Roland, is this true?
2470 On POSIX systems, there is no difference between text streams and binary
2471 streams.  When you open a stream, you get the same kind of stream
2472 regardless of whether you ask for binary.  This stream can handle any
2473 file content, and has none of the restrictions that text streams
2474 sometimes have.
2475
2476 @node File Positioning
2477 @section File Positioning
2478 @cindex file positioning on a stream
2479 @cindex positioning a stream
2480 @cindex seeking on a stream
2481
2482 The @dfn{file position} of a stream describes where in the file the
2483 stream is currently reading or writing.  I/O on the stream advances the
2484 file position through the file.  In the GNU system, the file position is
2485 represented as an integer, which counts the number of bytes from the
2486 beginning of the file.  @xref{File Position}.
2487
2488 During I/O to an ordinary disk file, you can change the file position
2489 whenever you wish, so as to read or write any portion of the file.  Some
2490 other kinds of files may also permit this.  Files which support changing
2491 the file position are sometimes referred to as @dfn{random-access}
2492 files.
2493
2494 You can use the functions in this section to examine or modify the file
2495 position indicator associated with a stream.  The symbols listed below
2496 are declared in the header file @file{stdio.h}.
2497 @pindex stdio.h
2498
2499 @comment stdio.h
2500 @comment ANSI
2501 @deftypefun {long int} ftell (FILE *@var{stream})
2502 This function returns the current file position of the stream
2503 @var{stream}.
2504
2505 This function can fail if the stream doesn't support file positioning,
2506 or if the file position can't be represented in a @code{long int}, and
2507 possibly for other reasons as well.  If a failure occurs, a value of
2508 @code{-1} is returned.
2509 @end deftypefun
2510
2511 @comment stdio.h
2512 @comment ANSI
2513 @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
2514 The @code{fseek} function is used to change the file position of the
2515 stream @var{stream}.  The value of @var{whence} must be one of the
2516 constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
2517 indicate whether the @var{offset} is relative to the beginning of the
2518 file, the current file position, or the end of the file, respectively.
2519
2520 This function returns a value of zero if the operation was successful,
2521 and a nonzero value to indicate failure.  A successful call also clears
2522 the end-of-file indicator of @var{stream} and discards any characters
2523 that were ``pushed back'' by the use of @code{ungetc}.
2524
2525 @code{fseek} either flushes any buffered output before setting the file
2526 position or else remembers it so it will be written later in its proper
2527 place in the file.
2528 @end deftypefun
2529
2530 @strong{Portability Note:} In non-POSIX systems, @code{ftell} and
2531 @code{fseek} might work reliably only on binary streams.  @xref{Text and
2532 Binary Streams}.
2533
2534 The following symbolic constants are defined for use as the @var{whence}
2535 argument to @code{fseek}.  They are also used with the @code{lseek}
2536 function (@pxref{I/O Primitives}) and to specify offsets for file locks
2537 (@pxref{Control Operations}).
2538
2539 @comment stdio.h
2540 @comment ANSI
2541 @deftypevr Macro int SEEK_SET
2542 This is an integer constant which, when used as the @var{whence}
2543 argument to the @code{fseek} function, specifies that the offset
2544 provided is relative to the beginning of the file.
2545 @end deftypevr
2546
2547 @comment stdio.h
2548 @comment ANSI
2549 @deftypevr Macro int SEEK_CUR
2550 This is an integer constant which, when used as the @var{whence}
2551 argument to the @code{fseek} function, specifies that the offset
2552 provided is relative to the currrent file position.
2553 @end deftypevr
2554
2555 @comment stdio.h
2556 @comment ANSI
2557 @deftypevr Macro int SEEK_END
2558 This is an integer constant which, when used as the @var{whence}
2559 argument to the @code{fseek} function, specifies that the offset
2560 provided is relative to the end of the file.
2561 @end deftypevr
2562
2563 @comment stdio.h
2564 @comment ANSI
2565 @deftypefun void rewind (FILE *@var{stream})
2566 The @code{rewind} function positions the stream @var{stream} at the
2567 begining of the file.  It is equivalent to calling @code{fseek} on the
2568 @var{stream} with an @var{offset} argument of @code{0L} and a
2569 @var{whence} argument of @code{SEEK_SET}, except that the return
2570 value is discarded and the error indicator for the stream is reset.
2571 @end deftypefun
2572
2573 @node Portable Positioning
2574 @section Portable File-Position Functions
2575
2576 On the GNU system, the file position is truly a character count.  You
2577 can specify any character count value as an argument to @code{fseek} and
2578 get reliable results for any random access file.  However, some ANSI C
2579 systems do not represent file positions in this way.
2580
2581 On some systems where text streams truly differ from binary streams, it
2582 is impossible to represent the file position of a text stream as a count
2583 of characters from the beginning of the file.  For example, the file
2584 position on some systems must encode both a record offset within the
2585 file, and a character offset within the record.
2586
2587 As a consequence, if you want your programs to be portable to these
2588 systems, you must observe certain rules:
2589
2590 @itemize @bullet
2591 @item
2592 The value returned from @code{ftell} on a text stream has no predictable
2593 relationship to the number of characters you have read so far.  The only
2594 thing you can rely on is that you can use it subsequently as the
2595 @var{offset} argument to @code{fseek} to move back to the same file
2596 position.
2597
2598 @item 
2599 In a call to @code{fseek} on a text stream, either the @var{offset} must
2600 either be zero; or @var{whence} must be @code{SEEK_SET} and the
2601 @var{offset} must be the result of an earlier call to @code{ftell} on
2602 the same stream.
2603
2604 @item
2605 The value of the file position indicator of a text stream is undefined
2606 while there are characters that have been pushed back with @code{ungetc}
2607 that haven't been read or discarded.  @xref{Unreading}.
2608 @end itemize
2609
2610 But even if you observe these rules, you may still have trouble for long
2611 files, because @code{ftell} and @code{fseek} use a @code{long int} value
2612 to represent the file position.  This type may not have room to encode
2613 all the file positions in a large file.
2614
2615 So if you do want to support systems with peculiar encodings for the
2616 file positions, it is better to use the functions @code{fgetpos} and
2617 @code{fsetpos} instead.  These functions represent the file position
2618 using the data type @code{fpos_t}, whose internal representation varies
2619 from system to system.
2620
2621 These symbols are declared in the header file @file{stdio.h}.
2622 @pindex stdio.h
2623
2624 @comment stdio.h
2625 @comment ANSI
2626 @deftp {Data Type} fpos_t
2627 This is the type of an object that can encode information about the
2628 file position of a stream, for use by the functions @code{fgetpos} and
2629 @code{fsetpos}.
2630
2631 In the GNU system, @code{fpos_t} is equivalent to @code{off_t} or
2632 @code{long int}.  In other systems, it might have a different internal
2633 representation.
2634 @end deftp
2635
2636 @comment stdio.h
2637 @comment ANSI
2638 @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
2639 This function stores the value of the file position indicator for the
2640 stream @var{stream} in the @code{fpos_t} object pointed to by
2641 @var{position}.  If successful, @code{fgetpos} returns zero; otherwise
2642 it returns a nonzero value and stores an implementation-defined positive
2643 value in @code{errno}.
2644 @end deftypefun
2645
2646 @comment stdio.h
2647 @comment ANSI
2648 @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t @var{position})
2649 This function sets the file position indicator for the stream @var{stream}
2650 to the position @var{position}, which must have been set by a previous
2651 call to @code{fgetpos} on the same stream.  If successful, @code{fsetpos}
2652 clears the end-of-file indicator on the stream, discards any characters
2653 that were ``pushed back'' by the use of @code{ungetc}, and returns a value
2654 of zero.  Otherwise, @code{fsetpos} returns a nonzero value and stores
2655 an implementation-defined positive value in @code{errno}.
2656 @end deftypefun
2657
2658 @node Stream Buffering
2659 @section Stream Buffering
2660
2661 @cindex buffering of streams
2662 Characters that are written to a stream are normally accumulated and
2663 transmitted asynchronously to the file in a block, instead of appearing
2664 as soon as they are output by the application program.  Similarly,
2665 streams often retrieve input from the host environment in blocks rather
2666 than on a character-by-character basis.  This is called @dfn{buffering}.
2667
2668 If you are writing programs that do interactive input and output using
2669 streams, you need to understand how buffering works when you design the
2670 user interface to your program.  Otherwise, you might find that output
2671 (such as progress or prompt messages) doesn't appear when you intended
2672 it to, or that input typed by the user is made available by lines
2673 instead of by single characters, or other unexpected behavior.  
2674
2675 This section deals only with controlling when characters are transmitted
2676 between the stream and the file or device, and @emph{not} with how
2677 things like echoing, flow control, and the like are handled on specific
2678 classes of devices.  For information on common control operations on
2679 terminal devices, see @ref{Low-Level Terminal Interface}.
2680
2681 You can bypass the stream buffering facilities altogether by using the
2682 low-level input and output functions that operate on file descriptors
2683 instead.  @xref{Low-Level Input/Output}.
2684
2685 @menu
2686 * Buffering Concepts::          Terminology is defined here.
2687 * Flushing Buffers::            How to ensure that output buffers are flushed.
2688 * Controlling Buffering::       How to specify what kind of buffering to use.
2689 @end menu
2690
2691 @node Buffering Concepts
2692 @subsection Buffering Concepts
2693
2694 There are three different kinds of buffering strategies:
2695
2696 @itemize @bullet
2697 @item
2698 Characters written to or read from an @dfn{unbuffered} stream are
2699 transmitted individually to or from the file as soon as possible.
2700 @cindex unbuffered stream
2701
2702 @item
2703 Characters written to or read from a @dfn{line buffered} stream are
2704 transmitted to or from the file in blocks when a newline character is
2705 encountered.
2706 @cindex line buffered stream
2707
2708 @item
2709 Characters written to or read from a @dfn{fully buffered} stream are
2710 transmitted to or from the file in blocks of arbitrary size.
2711 @cindex fully buffered stream
2712 @end itemize
2713
2714 @strong{Incomplete:}  What is the default buffering behavior in the 
2715 GNU system?
2716
2717 You can explicitly set the buffering strategy used by a stream.
2718
2719 When a stream corresponding to an interactive device (such as a
2720 terminal) is opened, its default behavior is to be either unbuffered or
2721 line buffered.
2722
2723 This means that when your program writes messages to an interactive
2724 device that end in a newline, they'll always show up immediately.
2725 Output that doesn't end in a newline might or might not show up
2726 immediately, and if it matters you should flush buffered output
2727 explicitly with @code{fflush}, as described in @ref{Flushing Buffers}.
2728
2729 For input, if an interactive stream is line-buffered, users of your
2730 program will probably be able to use whatever basic input editing
2731 facilities are normally provided by the host operating system (such as
2732 being able to correct typing mistakes with rubout or backspace), but
2733 you'll have to design your program so that it expects to look for
2734 newline characters to terminate input.  If an interactive stream is
2735 unbuffered, it might be appropriate for your program to provide its own
2736 input editing facilities.
2737
2738 @strong{Incomplete:}  I don't think changing the buffering on a stream
2739 in the GNU system messes with input modes on a terminal device, does it?
2740
2741 @node Flushing Buffers
2742 @subsection Flushing Buffers
2743
2744 @cindex flushing a stream
2745 @dfn{Flushing} output on a buffered stream means transmitting all
2746 accumulated characters to the file.  There are many circumstances when
2747 buffered output on a stream is flushed automatically:
2748
2749 @itemize @bullet
2750 @item
2751 When you try to do output and the output buffer is full.
2752
2753 @item
2754 When the stream is closed.
2755
2756 @item 
2757 When the program terminates by calling @code{exit}.
2758 @c ??? xref here.
2759
2760 @item
2761 When a newline is written, if the stream is line-buffered.
2762
2763 @item
2764 Whenever an input operation on @emph{any} stream actually reads data
2765 from the file.
2766 @end itemize
2767
2768 If you want to flush the buffered output at another time, call
2769 @code{fflush}, which is declared in the header file @file{stdio.h}.
2770 @pindex stdio.h
2771
2772 @comment stdio.h
2773 @comment ANSI
2774 @deftypefun int fflush (FILE *@var{stream})
2775 This function causes any buffered output on @var{stream} to be delivered
2776 to the file.  If @var{stream} is a null pointer, then
2777 @code{fflush} causes buffered output on @emph{all} open output streams
2778 to be flushed.
2779
2780 This function returns @code{EOF} if a write error occurs, or zero
2781 otherwise.
2782 @end deftypefun
2783
2784 @strong{Compatibility Note:} Some brain-damaged operating systems have
2785 been known to be so thoroughly fixated on line-oriented input and output
2786 that flushing a line-buffered stream causes a newline to be written!
2787 Fortunately, this ``feature'' seems to be becoming less common.  You do
2788 not need to worry about this in the GNU system.
2789
2790
2791 @node Specifying Which Kind of Buffering
2792 @subsection Specifying Which Kind of Buffering
2793
2794 After opening a stream (but before any other operations have been
2795 performed on it), you can explicitly specify what kind of buffering you
2796 want it to have using the @code{setvbuf} function.
2797 @cindex buffering, controlling
2798
2799 The facilities listed in this section are declared in the header
2800 file @file{stdio.h}.
2801 @pindex stdio.h
2802
2803 @comment stdio.h
2804 @comment ANSI
2805 @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
2806 This function is used to specify that the stream @var{stream} should
2807 have the buffering mode @var{mode}, which can be either @code{_IOFBF}
2808 (for full buffering), @code{_IOLBF} (for line buffering), or
2809 @code{_IONBF} (for unbuffered input/output).
2810
2811 If you specify a null pointer as the @var{buf} argument, then @code{setvbuf}
2812 allocates a buffer itself using @code{malloc}.  This buffer will be freed
2813 when you close the stream.
2814
2815 Otherwise, @var{buf} should be a character array that can hold at least
2816 @var{size} characters.  You should not free the space for this array as
2817 long as the stream remains open and this array remains its buffer.  You
2818 should usually either allocate it statically, or @code{malloc}
2819 (@pxref{Unconstrained Allocation}) the buffer.  Using an automatic array
2820 is not a good idea unless you close the file before exiting the block
2821 that declares the array.
2822
2823 While the array remains a stream buffer, the stream I/O functions will
2824 use the buffer for their internal purposes.  You shouldn't try to access
2825 the values in the array directly while the stream is using it for
2826 buffering.
2827
2828 The @code{setvbuf} function returns zero on success, or a nonzero value
2829 if the value of @var{mode} is not valid or if the request could not
2830 be honored.
2831 @end deftypefun
2832
2833 @comment stdio.h
2834 @comment ANSI
2835 @deftypevr Macro int _IOFBF
2836 The value of this macro is an integer constant expression that can be
2837 used as the @var{mode} argument to the @code{setvbuf} function to
2838 specify that the stream should be fully buffered.
2839 @end deftypevr
2840
2841 @comment stdio.h
2842 @comment ANSI
2843 @deftypevr Macro int _IOLBF
2844 The value of this macro is an integer constant expression that can be
2845 used as the @var{mode} argument to the @code{setvbuf} function to
2846 specify that the stream should be line buffered.
2847 @end deftypevr
2848
2849 @comment stdio.h
2850 @comment ANSI
2851 @deftypevr Macro int _IONBF
2852 The value of this macro is an integer constant expression that can be
2853 used as the @var{mode} argument to the @code{setvbuf} function to
2854 specify that the stream should be unbuffered.
2855 @end deftypevr
2856
2857 @comment stdio.h
2858 @comment ANSI
2859 @deftypevr Macro int BUFSIZ
2860 The value of this macro is an integer constant expression that is good
2861 to use for the @var{size} argument to @code{setvbuf}.  This value is
2862 guaranteed to be at least @code{256}.
2863
2864 The value of @code{BUFSIZ} is chosen on each system so as to make stream
2865 I/O efficient.  So it is a good idea to use @code{BUFSIZ} as the size 
2866 for the buffer when you call @code{setvbuf}.
2867
2868 Actually, you can get an even better valuse to use for the buffer size
2869 by means of the @code {fstat} system call: it is found in the
2870 @code{st_blksize} field of the file attributes.  @xref{Attribute
2871 Meanings}.
2872
2873 Sometimes people also use @code{BUFSIZ} as the allocation size of
2874 buffers used for related purposes, such as strings used to receive a
2875 line of input with @code{fgets} (@pxref{Character Input}).  There is no
2876 particular reason to use @code{BUFSIZ} for this instead of any other
2877 integer, except that it might lead to doing I/O in chunks of an
2878 efficient size.
2879 @end deftypevr
2880
2881 @comment stdio.h
2882 @comment ANSI
2883 @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
2884 If @var{buf} is a null pointer, the effect of this function is
2885 equivalent to calling @code{setvbuf} with a @var{mode} argument of
2886 @code{_IONBF}.  Otherwise, it is equivalent to calling @code{setvbuf}
2887 with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size}
2888 argument of @code{BUFSIZ}.
2889
2890 The @code{setbuf} function is provided for compatibility with old code;
2891 use @code{setvbuf} in all new programs.
2892 @end deftypefun
2893
2894 @comment stdio.h
2895 @comment BSD
2896 @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
2897 If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
2898 Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
2899 buffer.  The @var{size} argument specifies the length of @var{buf}.
2900
2901 This function is provided for compatibility with old BSD code.  Use
2902 @code{setvbuf} instead.
2903 @end deftypefun
2904
2905 @comment stdio.h
2906 @comment BSD
2907 @deftypefun void setlinebuf (FILE *@var{stream})
2908 This function makes @var{stream} be line-buffered, and allocates the
2909 buffer for you.
2910
2911 This function is provided for compatibility with old BSD code.  Use
2912 @code{setvbuf} instead.
2913 @end deftypefun
2914
2915
2916 @node Temporary Files
2917 @section Temporary Files
2918
2919 If you need to use a temporary file in your program, you can use the
2920 @code{tmpfile} function to open it.  Or you can use the @code{tmpnam}
2921 function make a name for a temporary file and then open it in the usual
2922 way with @code{fopen}.
2923
2924 These facilities are declared in the header file @file{stdio.h}.
2925 @pindex stdio.h
2926
2927 @comment stdio.h
2928 @comment ANSI
2929 @deftypefun {FILE *} tmpfile (void)
2930 This function creates a temporary binary file for update mode, as if by
2931 calling @code{fopen} with mode @code{"wb+"}.  The file is deleted
2932 automatically when it is closed or when the program terminates.  (On
2933 some other ANSI C systems the file may fail to be deleted if the program
2934 terminates abnormally).
2935 @end deftypefun
2936
2937 @comment stdio.h
2938 @comment ANSI
2939 @deftypefun {char *} tmpnam (char *@var{result})
2940 This function constructs and returns a file name that is a valid file
2941 name and that does not name any existing file.  If the @var{result}
2942 argument is a null pointer, the return value is a pointer to an internal
2943 static string, which might be modified by subsequent calls.  Otherwise,
2944 the @var{result} argument should be a pointer to an array of at least
2945 @code{L_tmpnam} characters, and the result is written into that array.
2946
2947 It is possible for @code{tmpnam} to fail if you call it too many times.
2948 This is because the fixed length of a temporary file name gives room for
2949 only a finite number of different names.  If @code{tmpnam} fails, it
2950 returns a null pointer.
2951 @end deftypefun
2952
2953 @comment stdio.h
2954 @comment ANSI
2955 @deftypevr Macro int L_tmpnam
2956 The value of this macro is an integer constant expression that represents
2957 the minimum allocation size of a string large enough to hold the
2958 file name generated by the @code{tmpnam} function.
2959 @end deftypevr
2960
2961 @comment stdio.h
2962 @comment ANSI
2963 @deftypevr Macro int TMP_MAX
2964 The macro @code{TMP_MAX} is a lower bound for how many temporary names
2965 you can create with @code{tmpnam}.  You can rely on being able to call
2966 @code{tmpnam} at least this many times before it might fail saying you
2967 have made too many temporary file names.
2968
2969 With the GNU library, you can create a very large number of temporary
2970 file names---if you actually create the files, you will probably run out
2971 of disk space before you run out of names.  Some other systems have a
2972 fixed, small limit on the number of temporary files.  The limit is never
2973 less than @code{25}.
2974 @end deftypevr
2975
2976 @comment stdio.h
2977 @comment SVID
2978 @deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix})
2979 This function generates a unique temporary filename.  If @var{prefix} is
2980 not a null pointer, up to five characters of this string are used as
2981 a prefix for the file name.
2982
2983 The directory prefix for the temporary file name is determined by testing
2984 each of the following, in sequence.  The directory must exist and be
2985 writable.
2986
2987 @itemize @bullet
2988 @item
2989 The environment variable @code{TMPDIR}, if it is defined.
2990
2991 @item
2992 The @var{dir} argument, if it is not a null pointer.
2993
2994 @item
2995 The value of the @code{P_tmpdir} macro.
2996
2997 @item
2998 The directory @file{/tmp}.
2999 @end itemize
3000
3001 This function is defined for SVID compatibility.
3002 @c ??? Add xref to the node for feature test macros.
3003 @end deftypefun
3004 @cindex TMPDIR environment variable
3005
3006 @comment stdio.h
3007 @comment SVID
3008 @deftypevr {SVID Macro} {char *} P_tmpdir
3009 This macro is the name of the default directory for temporary files.
3010 @end deftypevr
3011
3012 @node Other Kinds of Streams
3013 @section Other Kinds of Streams
3014
3015 The GNU library provides ways for you to define additional kinds of
3016 streams that do not necessarily correspond to an open file.
3017
3018 One such type of stream takes input from or writes output to a string.
3019 These kinds of streams are used internally to implement the
3020 @code{sprintf} and @code{sscanf} functions.  You can also create such a
3021 stream explicitly, using the functions described in @ref{String Streams}.
3022
3023 More generally, you can define streams that do input/output to arbitrary
3024 objects using functions supplied by your program.  This protocol is
3025 discussed in @ref{Custom Streams}.
3026
3027 @strong{Portability Note:} The facilities described in this section are
3028 specific to GNU.  Other systems or C implementations might or might not
3029 provide equivalent functionality.
3030
3031 @menu
3032 * String Streams::
3033 * Custom Streams::
3034 @end menu
3035
3036 @node String Streams
3037 @subsection String Streams
3038 @cindex stream, for I/O to a string
3039 @cindex string stream
3040 The @code{fmemopen} and @code{open_memstream} functions allow you to do
3041 I/O to a string or memory buffer.  These facilities are declared in
3042 @file{stdio.h}.
3043 @pindex stdio.h
3044
3045 @comment stdio.h
3046 @comment GNU
3047 @deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
3048 This function opens a stream that allows the access specified by the
3049 @var{opentype} argument, that reads from or writes to the buffer specified
3050 by the argument @var{buf}.  This array must be at least @var{size} bytes long.
3051
3052 @ignore
3053 @strong{Incomplete:}  This seems useless since the stream does not
3054 support file positioning.
3055
3056 If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
3057 dynamically allocates (as with @code{malloc}; @pxref{Unconstrained
3058 Allocation}) an array @var{size} bytes long.  This is really only useful
3059 if you are going to write things to the buffer and then read them back
3060 in again, because you have no way of actually getting a pointer to the
3061 buffer.  The buffer is freed when the stream is open.
3062 @end ignore
3063
3064 The argument @var{opentype} is the same as in @code{fopen}
3065 (@xref{Opening and Closing Streams}).  If the @var{opentype} specifies
3066 append mode, then the initial file position is set to the first null
3067 character in the buffer.  Otherwise the initial file position is at the
3068 beginning of the buffer.
3069
3070 When a stream open for writing is flushed or closed, a null character
3071 (zero byte) is written at the end of the buffer if it fits.  You
3072 should add an extra byte to the @var{size} argument to account for this.
3073 Attempts to write more than @var{size} bytes to the buffer result
3074 in an error.
3075
3076 For a stream open for reading, null characters (zero bytes) in the
3077 buffer do not count as end-of-file.  Read operations return end-of-file
3078 only when the file position advances past @var{size} bytes.  So, if you
3079 want to read characters from a null-terminated string, you should supply
3080 the length of the string as the @var{size} argument.
3081 @end deftypefun
3082
3083 Here is an example of using @code{fmemopen} to create a stream for
3084 reading from a string:
3085
3086 @example
3087 #include <stdio.h>
3088
3089 static char buffer[] = "foobar";
3090
3091 void
3092 main (void)
3093 @{
3094   int ch;
3095   FILE *stream;
3096
3097   stream = fmemopen (buffer, strlen(buffer), "r");
3098   while ((ch = fgetc (stream)) != EOF)
3099     printf ("Got %c\n", ch);
3100   fclose (stream);
3101 @}
3102 @end example
3103
3104 This program produces the following output:
3105
3106 @example
3107 Got f
3108 Got o
3109 Got o
3110 Got b
3111 Got a
3112 Got r
3113 @end example
3114
3115 @comment stdio.h
3116 @comment GNU
3117 @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t @var{sizeloc})
3118 This function opens a stream for writing to a buffer.  The buffer is
3119 allocated dynamically (as with @code{malloc}; @pxref{Unconstrained
3120 Allocation}) and grown as necessary.
3121
3122 When the stream is closed with @code{fclose} or flushed with
3123 @code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
3124 contain the pointer to the buffer and its size.  The values thus stored
3125 remain valid only as long as no further output on the stream takes
3126 place.  If you do more output, you must flush or close the stream again
3127 to store new values before you use them again.
3128
3129 A null character is written at the end of the buffer.  This null character
3130 is @emph{not} included in the size value stored at @var{sizeloc}.
3131 @end deftypefun
3132
3133 Here is an example of using @code{open_memstream}:
3134
3135 @example
3136 #include <stdio.h>
3137
3138 void
3139 main (void)
3140 @{
3141   char *bp;
3142   size_t size;
3143   FILE *stream;
3144
3145   stream = open_memstream (&bp, &size);
3146   fprintf (stream, "hello");
3147   fflush (stream);
3148   printf ("buf = `%s', size = %d\n", bp, size);
3149   fprintf (stream, ", world");
3150   fclose (stream);
3151   printf ("buf = `%s', size = %d\n", bp, size);
3152 @}
3153 @end example
3154
3155 This program produces the following output:
3156
3157 @example
3158 buf = `hello', size = 5
3159 buf = `hello, world', size = 12
3160 @end example
3161
3162 @node Custom Streams
3163 @subsection Programming Your Own Custom Streams
3164 @cindex custom streams
3165 @cindex programming your own streams
3166
3167 This section describes how you can make a stream that gets input from an
3168 arbitrary data source or writes output to an arbitrary data sink
3169 programmed by you.  We call these @dfn{custom streams}.
3170
3171 @menu
3172 * Streams and Cookies::
3173 * Hook Functions::
3174 @end menu
3175
3176 @node Streams and Cookies
3177 @subsubsection Custom Streams and Cookies
3178 @cindex cookie, for custom stream
3179
3180 Inside every custom stream is a special object called the @dfn{cookie}.
3181 This is an object supplied by you which records where to fetch or store
3182 the data read or written.  It is up to you to define a data type to use
3183 for the cookie.  The stream functions in the library they never refer
3184 directly to its contents, and they don't even know what the type is;
3185 they record its address with type @code{void *}.
3186
3187 To implement custom stream, you must specify @emph{how} to fetch or
3188 store the data in the specified place.  You do this by defining
3189 @dfn{hook functions} to read, write, change ``file position'', and close
3190 the stream.  All four of these functions will be passed the stream's
3191 cookie so they can tell where to fetch or store the data.  The library
3192 functions don't know what's inside the cookie, but your functions will
3193 know.
3194
3195 When you create a custom stream, you must specify the cookie pointer,
3196 and also the four hook functions stored in a structure of type 
3197 @code{__io_functions}.
3198
3199 These facilities are declared in @file{stdio.h}.
3200 @pindex stdio.h
3201
3202 @comment stdio.h
3203 @comment GNU
3204 @deftp {Data Type} __io_functions
3205 This is a structure type that holds the functions that define the 
3206 communications protocol between the stream and its cookie.  It has
3207 the following members:
3208
3209 @table @code
3210 @item __io_read *__read
3211 This is the function that reads data from the cookie.  If the value is a
3212 null pointer instead of a function, then read operations on ths stream
3213 always return @code{EOF}.
3214
3215 @item __io_write *__write
3216 This is the function that writes data to the cookie.  If the value is a
3217 null pointer instead of a function, then data written to the stream is
3218 discarded.
3219
3220 @item __io_seek *__seek
3221 This is the function that performs the equivalent of file positioning on
3222 the cookie.  If the value is a null pointer instead of a function, calls
3223 to @code{fseek} on this stream return an @code{ESPIPE} error.
3224
3225 @item __io_close *__close
3226 This function performs any appropriate cleanup on the cookie when
3227 closing the stream.  If the value is a null pointer instead of a
3228 function, nothing special is done to close the cookie when the stream is
3229 closed.
3230 @end table
3231 @end deftp
3232
3233 @comment stdio.h
3234 @comment GNU
3235 @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, __io_functions @var{io_functions})
3236 This function actually creates the stream for communicating with the
3237 @var{cookie} using the functions in the @var{io_functions} argument.
3238 The @var{opentype} argument is interpreted as for @code{fopen};
3239 see @ref{Opening and Closing Streams}.  (But note that the ``truncate on
3240 open'' option is ignored.)
3241
3242 @strong{Incomplete:} What is the default buffering mode for the newly
3243 created stream?
3244
3245 The @code{fopencookie} function returns the newly created stream, or a null
3246 pointer in case of an error.
3247 @end deftypefun
3248
3249 @node Hook Functions
3250 @subsection Custom Stream Hook Functions
3251 @cindex hook functions (of custom streams)
3252
3253 Here are more details on how you should define the four hook functions
3254 that a custom stream needs.
3255
3256 You should define the function to read data from the cookie as:
3257
3258 @example
3259 int @var{function} (void *@var{cookie}, void *@var{buffer}, size_t @var{size})
3260 @end example
3261
3262 This is very similar to the @code{read} function; see @ref{I/O
3263 Primitives}.  Your function should transfer up to @var{size} bytes into
3264 the @var{buffer}, and return the number of bytes read.  You can return a
3265 value of @code{-1} to indicate an error.  You should define the function
3266 to write data to the cookie as:
3267
3268 @example
3269 int @var{function} (void *@var{cookie}, const void *@var{buffer}, size_t @var{size})
3270 @end example
3271
3272 This is very similar to the @code{write} function; see @ref{I/O
3273 Primitives}.  Your function should transfer up to @var{size} bytes from
3274 the buffer, and return the number of bytes written.  You can return a
3275 value of @code{-1} to indicate an error.  You should define the function
3276 to perform seek operations on the cookie as:
3277
3278 @example
3279 int @var{function} (void *@var{cookie}, fpos_t *@var{position}, int @var{whence})
3280 @end example
3281
3282 For this function, the @code{position} and @code{whence} arguments are
3283 interpreted as for @code{fgetpos}; see @ref{Text and Binary Streams}.
3284 Remember that in the GNU system, @code{fpos_t} is equivalent to
3285 @code{off_t} or @code{long int}, and simply represents the number of
3286 bytes from the beginning of the file.
3287
3288 After doing the seek operation, your function should store the resulting 
3289 file position relative to the beginning of the file in @var{position}.
3290 Your function should return a value of @code{0} on success and @code{-1}
3291 to indicate an error.
3292
3293 You should define the function to do cleanup operations on the cookie
3294 appropriate for closing the stream as:
3295
3296 @example
3297 int @var{function} (void *@var{cookie})
3298 @end example
3299
3300 Your function should return @code{-1} to indicate an error, and @code{0}
3301 otherwise.
3302
3303 @comment stdio.h
3304 @comment GNU
3305 @deftp {Data Type} __io_read
3306 This is the data type that the read function for a custom stream should have.
3307 If you declare the function as shown above, this is the type it will have.
3308 @end deftp
3309
3310 @comment stdio.h
3311 @comment GNU
3312 @deftp {Data Type} __io_write
3313 The data type of the write function for a custom stream.
3314 @end deftp
3315
3316 @comment stdio.h
3317 @comment GNU
3318 @deftp {Data Type} __io_seek
3319 The data type of the seek function for a custom stream.
3320 @end deftp
3321
3322 @comment stdio.h
3323 @comment GNU
3324 @deftp {Data Type} __io_close
3325 The data type of the close function for a custom stream.
3326 @end deftp
3327
3328 @strong{Incomplete:}  Roland says:
3329
3330 @quotation
3331 There is another set of functions one can give a stream, the
3332 input-room and output-room functions.  These functions must
3333 understand stdio internals.  To describe how to use these
3334 functions, you also need to document lots of how stdio works
3335 internally (which isn't relevant for other uses of stdio).
3336 Perhaps I can write an interface spec from which you can write
3337 good documentation.  But it's pretty complex and deals with lots
3338 of nitty-gritty details.  I think it might be better to let this
3339 wait until the rest of the manual is more done and polished.
3340 @end quotation
3341
3342 @strong{Incomplete:}  This section could use an example.