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