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