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