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