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