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