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