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