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