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