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