1 @node I/O on Streams, Low-Level I/O, I/O Overview, Top
2 @c %MENU% High-level, portable I/O facilities
3 @chapter Input/Output on Streams
6 \hyphenation{which-ever}
9 This chapter describes the functions for creating streams and performing
10 input and output operations on them. As discussed in @ref{I/O
11 Overview}, a stream is a fairly abstract, high-level concept
12 representing a communications channel to a file, device, or process.
15 * Streams:: About the data type representing a stream.
16 * Standard Streams:: Streams to the standard input and output
17 devices are created for you.
18 * Opening Streams:: How to create a stream to talk to a file.
19 * Closing Streams:: Close a stream when you are finished with it.
20 * Simple Output:: Unformatted output by characters and lines.
21 * Character Input:: Unformatted input by characters and words.
22 * Line Input:: Reading a line or a record from a stream.
23 * Unreading:: Peeking ahead/pushing back input just read.
24 * Block Input/Output:: Input and output operations on blocks of data.
25 * Formatted Output:: @code{printf} and related functions.
26 * Customizing Printf:: You can define new conversion specifiers for
27 @code{printf} and friends.
28 * Formatted Input:: @code{scanf} and related functions.
29 * EOF and Errors:: How you can tell if an I/O error happens.
30 * Binary Streams:: Some systems distinguish between text files
32 * File Positioning:: About random-access streams.
33 * Portable Positioning:: Random access on peculiar ISO C systems.
34 * Stream Buffering:: How to control buffering of streams.
35 * Other Kinds of Streams:: Streams that do not necessarily correspond
37 * Formatted Messages:: Print strictly formatted messages.
43 For historical reasons, the type of the C data structure that represents
44 a stream is called @code{FILE} rather than ``stream''. Since most of
45 the library functions deal with objects of type @code{FILE *}, sometimes
46 the term @dfn{file pointer} is also used to mean ``stream''. This leads
47 to unfortunate confusion over terminology in many books on C. This
48 manual, however, is careful to use the terms ``file'' and ``stream''
49 only in the technical sense.
53 The @code{FILE} type is declared in the header file @file{stdio.h}.
57 @deftp {Data Type} FILE
58 This is the data type used to represent stream objects. A @code{FILE}
59 object holds all of the internal state information about the connection
60 to the associated file, including such things as the file position
61 indicator and buffering information. Each stream also has error and
62 end-of-file status indicators that can be tested with the @code{ferror}
63 and @code{feof} functions; see @ref{EOF and Errors}.
66 @code{FILE} objects are allocated and managed internally by the
67 input/output library functions. Don't try to create your own objects of
68 type @code{FILE}; let the library do it. Your programs should
69 deal only with pointers to these objects (that is, @code{FILE *} values)
70 rather than the objects themselves.
71 @c !!! should say that FILE's have "No user-serviceable parts inside."
73 @node Standard Streams
74 @section Standard Streams
75 @cindex standard streams
76 @cindex streams, standard
78 When the @code{main} function of your program is invoked, it already has
79 three predefined streams open and available for use. These represent
80 the ``standard'' input and output channels that have been established
83 These streams are declared in the header file @file{stdio.h}.
88 @deftypevar {FILE *} stdin
89 The @dfn{standard input} stream, which is the normal source of input for the
92 @cindex standard input stream
96 @deftypevar {FILE *} stdout
97 The @dfn{standard output} stream, which is used for normal output from
100 @cindex standard output stream
104 @deftypevar {FILE *} stderr
105 The @dfn{standard error} stream, which is used for error messages and
106 diagnostics issued by the program.
108 @cindex standard error stream
110 In the GNU system, you can specify what files or processes correspond to
111 these streams using the pipe and redirection facilities provided by the
112 shell. (The primitives shells use to implement these facilities are
113 described in @ref{File System Interface}.) Most other operating systems
114 provide similar mechanisms, but the details of how to use them can vary.
116 In the GNU C library, @code{stdin}, @code{stdout}, and @code{stderr} are
117 normal variables which you can set just like any others. For example, to redirect
118 the standard output to a file, you could do:
122 stdout = fopen ("standard-output-file", "w");
125 Note however, that in other systems @code{stdin}, @code{stdout}, and
126 @code{stderr} are macros that you cannot assign to in the normal way.
127 But you can use @code{freopen} to get the effect of closing one and
128 reopening it. @xref{Opening Streams}.
130 @node Opening Streams
131 @section Opening Streams
133 @cindex opening a stream
134 Opening a file with the @code{fopen} function creates a new stream and
135 establishes a connection between the stream and a file. This may
136 involve creating a new file.
139 Everything described in this section is declared in the header file
144 @deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype})
145 The @code{fopen} function opens a stream for I/O to the file
146 @var{filename}, and returns a pointer to the stream.
148 The @var{opentype} argument is a string that controls how the file is
149 opened and specifies attributes of the resulting stream. It must begin
150 with one of the following sequences of characters:
154 Open an existing file for reading only.
157 Open the file for writing only. If the file already exists, it is
158 truncated to zero length. Otherwise a new file is created.
161 Open a file for append access; that is, writing at the end of file only.
162 If the file already exists, its initial contents are unchanged and
163 output to the stream is appended to the end of the file.
164 Otherwise, a new, empty file is created.
167 Open an existing file for both reading and writing. The initial contents
168 of the file are unchanged and the initial file position is at the
169 beginning of the file.
172 Open a file for both reading and writing. If the file already exists, it
173 is truncated to zero length. Otherwise, a new file is created.
176 Open or create file for both reading and appending. If the file exists,
177 its initial contents are unchanged. Otherwise, a new file is created.
178 The initial file position for reading is at the beginning of the file,
179 but output is always appended to the end of the file.
182 As you can see, @samp{+} requests a stream that can do both input and
183 output. The ISO standard says that when using such a stream, you must
184 call @code{fflush} (@pxref{Stream Buffering}) or a file positioning
185 function such as @code{fseek} (@pxref{File Positioning}) when switching
186 from reading to writing or vice versa. Otherwise, internal buffers
187 might not be emptied properly. The GNU C library does not have this
188 limitation; you can do arbitrary reading and writing operations on a
189 stream in whatever order.
191 Additional characters may appear after these to specify flags for the
192 call. Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is
193 the only part you are guaranteed will be understood by all systems.
195 The GNU C library defines one additional character for use in
196 @var{opentype}: the character @samp{x} insists on creating a new
197 file---if a file @var{filename} already exists, @code{fopen} fails
198 rather than opening it. If you use @samp{x} you are guaranteed that
199 you will not clobber an existing file. This is equivalent to the
200 @code{O_EXCL} option to the @code{open} function (@pxref{Opening and
203 The character @samp{b} in @var{opentype} has a standard meaning; it
204 requests a binary stream rather than a text stream. But this makes no
205 difference in POSIX systems (including the GNU system). If both
206 @samp{+} and @samp{b} are specified, they can appear in either order.
207 @xref{Binary Streams}.
209 Any other characters in @var{opentype} are simply ignored. They may be
210 meaningful in other systems.
212 If the open fails, @code{fopen} returns a null pointer.
214 When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
215 32 bit machine this function is in fact @code{fopen64} since the LFS
216 interface replaces transparently the old interface.
219 You can have multiple streams (or file descriptors) pointing to the same
220 file open at the same time. If you do only input, this works
221 straightforwardly, but you must be careful if any output streams are
222 included. @xref{Stream/Descriptor Precautions}. This is equally true
223 whether the streams are in one program (not usual) or in several
224 programs (which can easily happen). It may be advantageous to use the
225 file locking facilities to avoid simultaneous access. @xref{File
230 @deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype})
231 This function is similar to @code{fopen} but the stream it returns a
232 pointer for is opened using @code{open64}. Therefore this stream can be
233 used even on files larger then @math{2^31} bytes on 32 bit machines.
235 Please note that the return type is still @code{FILE *}. There is no
236 special @code{FILE} type for the LFS interface.
238 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
239 bits machine this function is available under the name @code{fopen}
240 and so transparently replaces the old interface.
245 @deftypevr Macro int FOPEN_MAX
246 The value of this macro is an integer constant expression that
247 represents the minimum number of streams that the implementation
248 guarantees can be open simultaneously. You might be able to open more
249 than this many streams, but that is not guaranteed. The value of this
250 constant is at least eight, which includes the three standard streams
251 @code{stdin}, @code{stdout}, and @code{stderr}. In POSIX.1 systems this
252 value is determined by the @code{OPEN_MAX} parameter; @pxref{General
253 Limits}. In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE}
254 resource limit; @pxref{Limits on Resources}.
259 @deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
260 This function is like a combination of @code{fclose} and @code{fopen}.
261 It first closes the stream referred to by @var{stream}, ignoring any
262 errors that are detected in the process. (Because errors are ignored,
263 you should not use @code{freopen} on an output stream if you have
264 actually done any output using the stream.) Then the file named by
265 @var{filename} is opened with mode @var{opentype} as for @code{fopen},
266 and associated with the same stream object @var{stream}.
268 If the operation fails, a null pointer is returned; otherwise,
269 @code{freopen} returns @var{stream}.
271 @code{freopen} has traditionally been used to connect a standard stream
272 such as @code{stdin} with a file of your own choice. This is useful in
273 programs in which use of a standard stream for certain purposes is
274 hard-coded. In the GNU C library, you can simply close the standard
275 streams and open new ones with @code{fopen}. But other systems lack
276 this ability, so using @code{freopen} is more portable.
278 When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
279 32 bit machine this function is in fact @code{freopen64} since the LFS
280 interface replaces transparently the old interface.
285 @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
286 This function is similar to @code{freopen}. The only difference is that
287 on 32 bit machine the stream returned is able to read beyond the
288 @math{2^31} bytes limits imposed by the normal interface. It should be
289 noted that the stream pointed to by @var{stream} need not be opened
290 using @code{fopen64} or @code{freopen64} since its mode is not important
293 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
294 bits machine this function is available under the name @code{freopen}
295 and so transparently replaces the old interface.
299 @node Closing Streams
300 @section Closing Streams
302 @cindex closing a stream
303 When a stream is closed with @code{fclose}, the connection between the
304 stream and the file is cancelled. After you have closed a stream, you
305 cannot perform any additional operations on it.
309 @deftypefun int fclose (FILE *@var{stream})
310 This function causes @var{stream} to be closed and the connection to
311 the corresponding file to be broken. Any buffered output is written
312 and any buffered input is discarded. The @code{fclose} function returns
313 a value of @code{0} if the file was closed successfully, and @code{EOF}
314 if an error was detected.
316 It is important to check for errors when you call @code{fclose} to close
317 an output stream, because real, everyday errors can be detected at this
318 time. For example, when @code{fclose} writes the remaining buffered
319 output, it might get an error because the disk is full. Even if you
320 know the buffer is empty, errors can still occur when closing a file if
323 The function @code{fclose} is declared in @file{stdio.h}.
326 To close all streams currently available the GNU C Library provides
331 @deftypefun int fcloseall (void)
332 This function causes all open streams of the process to be closed and
333 the connection to corresponding files to be broken. All buffered data
334 is written and any buffered input is discarded. The @code{fcloseall}
335 function returns a value of @code{0} if all the files were closed
336 successfully, and @code{EOF} if an error was detected.
338 This function should be used only in special situations, e.g., when an
339 error occurred and the program must be aborted. Normally each single
340 stream should be closed separately so that problems with individual
341 streams can be identified. It is also problematic since the standard
342 streams (@pxref{Standard Streams}) will also be closed.
344 The function @code{fcloseall} is declared in @file{stdio.h}.
347 If the @code{main} function to your program returns, or if you call the
348 @code{exit} function (@pxref{Normal Termination}), all open streams are
349 automatically closed properly. If your program terminates in any other
350 manner, such as by calling the @code{abort} function (@pxref{Aborting a
351 Program}) or from a fatal signal (@pxref{Signal Handling}), open streams
352 might not be closed properly. Buffered output might not be flushed and
353 files may be incomplete. For more information on buffering of streams,
354 see @ref{Stream Buffering}.
357 @section Simple Output by Characters or Lines
359 @cindex writing to a stream, by characters
360 This section describes functions for performing character- and
361 line-oriented output.
363 These functions are declared in the header file @file{stdio.h}.
368 @deftypefun int fputc (int @var{c}, FILE *@var{stream})
369 The @code{fputc} function converts the character @var{c} to type
370 @code{unsigned char}, and writes it to the stream @var{stream}.
371 @code{EOF} is returned if a write error occurs; otherwise the
372 character @var{c} is returned.
377 @deftypefun int putc (int @var{c}, FILE *@var{stream})
378 This is just like @code{fputc}, except that most systems implement it as
379 a macro, making it faster. One consequence is that it may evaluate the
380 @var{stream} argument more than once, which is an exception to the
381 general rule for macros. @code{putc} is usually the best function to
382 use for writing a single character.
387 @deftypefun int putchar (int @var{c})
388 The @code{putchar} function is equivalent to @code{putc} with
389 @code{stdout} as the value of the @var{stream} argument.
394 @deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
395 The function @code{fputs} writes the string @var{s} to the stream
396 @var{stream}. The terminating null character is not written.
397 This function does @emph{not} add a newline character, either.
398 It outputs only the characters in the string.
400 This function returns @code{EOF} if a write error occurs, and otherwise
401 a non-negative value.
406 fputs ("Are ", stdout);
407 fputs ("you ", stdout);
408 fputs ("hungry?\n", stdout);
412 outputs the text @samp{Are you hungry?} followed by a newline.
417 @deftypefun int puts (const char *@var{s})
418 The @code{puts} function writes the string @var{s} to the stream
419 @code{stdout} followed by a newline. The terminating null character of
420 the string is not written. (Note that @code{fputs} does @emph{not}
421 write a newline as this function does.)
423 @code{puts} is the most convenient function for printing simple
424 messages. For example:
427 puts ("This is a message.");
431 outputs the text @samp{This is a message.} followed by a newline.
436 @deftypefun int putw (int @var{w}, FILE *@var{stream})
437 This function writes the word @var{w} (that is, an @code{int}) to
438 @var{stream}. It is provided for compatibility with SVID, but we
439 recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
442 @node Character Input
443 @section Character Input
445 @cindex reading from a stream, by characters
446 This section describes functions for performing character-oriented input.
447 These functions are declared in the header file @file{stdio.h}.
450 These functions return an @code{int} value that is either a character of
451 input, or the special value @code{EOF} (usually -1). It is important to
452 store the result of these functions in a variable of type @code{int}
453 instead of @code{char}, even when you plan to use it only as a
454 character. Storing @code{EOF} in a @code{char} variable truncates its
455 value to the size of a character, so that it is no longer
456 distinguishable from the valid character @samp{(char) -1}. So always
457 use an @code{int} for the result of @code{getc} and friends, and check
458 for @code{EOF} after the call; once you've verified that the result is
459 not @code{EOF}, you can be sure that it will fit in a @samp{char}
460 variable without loss of information.
464 @deftypefun int fgetc (FILE *@var{stream})
465 This function reads the next character as an @code{unsigned char} from
466 the stream @var{stream} and returns its value, converted to an
467 @code{int}. If an end-of-file condition or read error occurs,
468 @code{EOF} is returned instead.
473 @deftypefun int getc (FILE *@var{stream})
474 This is just like @code{fgetc}, except that it is permissible (and
475 typical) for it to be implemented as a macro that evaluates the
476 @var{stream} argument more than once. @code{getc} is often highly
477 optimized, so it is usually the best function to use to read a single
483 @deftypefun int getchar (void)
484 The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
485 as the value of the @var{stream} argument.
488 Here is an example of a function that does input using @code{fgetc}. It
489 would work just as well using @code{getc} instead, or using
490 @code{getchar ()} instead of @w{@code{fgetc (stdin)}}.
494 y_or_n_p (const char *question)
496 fputs (question, stdout);
500 /* @r{Write a space to separate answer from question.} */
502 /* @r{Read the first character of the line.}
503 @r{This should be the answer character, but might not be.} */
504 c = tolower (fgetc (stdin));
506 /* @r{Discard rest of input line.} */
507 while (c != '\n' && c != EOF)
509 /* @r{Obey the answer if it was valid.} */
514 /* @r{Answer was invalid: ask for valid answer.} */
515 fputs ("Please answer y or n:", stdout);
522 @deftypefun int getw (FILE *@var{stream})
523 This function reads a word (that is, an @code{int}) from @var{stream}.
524 It's provided for compatibility with SVID. We recommend you use
525 @code{fread} instead (@pxref{Block Input/Output}). Unlike @code{getc},
526 any @code{int} value could be a valid result. @code{getw} returns
527 @code{EOF} when it encounters end-of-file or an error, but there is no
528 way to distinguish this from an input word with value -1.
532 @section Line-Oriented Input
534 Since many programs interpret input on the basis of lines, it's
535 convenient to have functions to read a line of text from a stream.
537 Standard C has functions to do this, but they aren't very safe: null
538 characters and even (for @code{gets}) long lines can confuse them. So
539 the GNU library provides the nonstandard @code{getline} function that
540 makes it easy to read lines reliably.
542 Another GNU extension, @code{getdelim}, generalizes @code{getline}. It
543 reads a delimited record, defined as everything through the next
544 occurrence of a specified delimiter character.
546 All these functions are declared in @file{stdio.h}.
550 @deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
551 This function reads an entire line from @var{stream}, storing the text
552 (including the newline and a terminating null character) in a buffer
553 and storing the buffer address in @code{*@var{lineptr}}.
555 Before calling @code{getline}, you should place in @code{*@var{lineptr}}
556 the address of a buffer @code{*@var{n}} bytes long, allocated with
557 @code{malloc}. If this buffer is long enough to hold the line,
558 @code{getline} stores the line in this buffer. Otherwise,
559 @code{getline} makes the buffer bigger using @code{realloc}, storing the
560 new buffer address back in @code{*@var{lineptr}} and the increased size
561 back in @code{*@var{n}}.
562 @xref{Unconstrained Allocation}.
564 If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}}
565 to zero, before the call, then @code{getline} allocates the initial
566 buffer for you by calling @code{malloc}.
568 In either case, when @code{getline} returns, @code{*@var{lineptr}} is
569 a @code{char *} which points to the text of the line.
571 When @code{getline} is successful, it returns the number of characters
572 read (including the newline, but not including the terminating null).
573 This value enables you to distinguish null characters that are part of
574 the line from the null character inserted as a terminator.
576 This function is a GNU extension, but it is the recommended way to read
577 lines from a stream. The alternative standard functions are unreliable.
579 If an error occurs or end of file is reached, @code{getline} returns
585 @deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream})
586 This function is like @code{getline} except that the character which
587 tells it to stop reading is not necessarily newline. The argument
588 @var{delimiter} specifies the delimiter character; @code{getdelim} keeps
589 reading until it sees that character (or end of file).
591 The text is stored in @var{lineptr}, including the delimiter character
592 and a terminating null. Like @code{getline}, @code{getdelim} makes
593 @var{lineptr} bigger if it isn't big enough.
595 @code{getline} is in fact implemented in terms of @code{getdelim}, just
600 getline (char **lineptr, size_t *n, FILE *stream)
602 return getdelim (lineptr, n, '\n', stream);
609 @deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
610 The @code{fgets} function reads characters from the stream @var{stream}
611 up to and including a newline character and stores them in the string
612 @var{s}, adding a null character to mark the end of the string. You
613 must supply @var{count} characters worth of space in @var{s}, but the
614 number of characters read is at most @var{count} @minus{} 1. The extra
615 character space is used to hold the null character at the end of the
618 If the system is already at end of file when you call @code{fgets}, then
619 the contents of the array @var{s} are unchanged and a null pointer is
620 returned. A null pointer is also returned if a read error occurs.
621 Otherwise, the return value is the pointer @var{s}.
623 @strong{Warning:} If the input data has a null character, you can't tell.
624 So don't use @code{fgets} unless you know the data cannot contain a null.
625 Don't use it to read files edited by the user because, if the user inserts
626 a null character, you should either handle it properly or print a clear
627 error message. We recommend using @code{getline} instead of @code{fgets}.
632 @deftypefn {Deprecated function} {char *} gets (char *@var{s})
633 The function @code{gets} reads characters from the stream @code{stdin}
634 up to the next newline character, and stores them in the string @var{s}.
635 The newline character is discarded (note that this differs from the
636 behavior of @code{fgets}, which copies the newline character into the
637 string). If @code{gets} encounters a read error or end-of-file, it
638 returns a null pointer; otherwise it returns @var{s}.
640 @strong{Warning:} The @code{gets} function is @strong{very dangerous}
641 because it provides no protection against overflowing the string
642 @var{s}. The GNU library includes it for compatibility only. You
643 should @strong{always} use @code{fgets} or @code{getline} instead. To
644 remind you of this, the linker (if using GNU @code{ld}) will issue a
645 warning whenever you use @code{gets}.
650 @cindex peeking at input
651 @cindex unreading characters
652 @cindex pushing input back
654 In parser programs it is often useful to examine the next character in
655 the input stream without removing it from the stream. This is called
656 ``peeking ahead'' at the input because your program gets a glimpse of
657 the input it will read next.
659 Using stream I/O, you can peek ahead at input by first reading it and
660 then @dfn{unreading} it (also called @dfn{pushing it back} on the stream).
661 Unreading a character makes it available to be input again from the stream,
662 by the next call to @code{fgetc} or other input function on that stream.
665 * Unreading Idea:: An explanation of unreading with pictures.
666 * How Unread:: How to call @code{ungetc} to do unreading.
670 @subsection What Unreading Means
672 Here is a pictorial explanation of unreading. Suppose you have a
673 stream reading a file that contains just six characters, the letters
674 @samp{foobar}. Suppose you have read three characters so far. The
675 situation looks like this:
683 so the next input character will be @samp{b}.
685 @c @group Invalid outside @example
686 If instead of reading @samp{b} you unread the letter @samp{o}, you get a
697 so that the next input characters will be @samp{o} and @samp{b}.
701 If you unread @samp{9} instead of @samp{o}, you get this situation:
711 so that the next input characters will be @samp{9} and @samp{b}.
715 @subsection Using @code{ungetc} To Do Unreading
717 The function to unread a character is called @code{ungetc}, because it
718 reverses the action of @code{getc}.
722 @deftypefun int ungetc (int @var{c}, FILE *@var{stream})
723 The @code{ungetc} function pushes back the character @var{c} onto the
724 input stream @var{stream}. So the next input from @var{stream} will
725 read @var{c} before anything else.
727 If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
728 @code{EOF}. This lets you call @code{ungetc} with the return value of
729 @code{getc} without needing to check for an error from @code{getc}.
731 The character that you push back doesn't have to be the same as the last
732 character that was actually read from the stream. In fact, it isn't
733 necessary to actually read any characters from the stream before
734 unreading them with @code{ungetc}! But that is a strange way to write
735 a program; usually @code{ungetc} is used only to unread a character
736 that was just read from the same stream.
738 The GNU C library only supports one character of pushback---in other
739 words, it does not work to call @code{ungetc} twice without doing input
740 in between. Other systems might let you push back multiple characters;
741 then reading from the stream retrieves the characters in the reverse
742 order that they were pushed.
744 Pushing back characters doesn't alter the file; only the internal
745 buffering for the stream is affected. If a file positioning function
746 (such as @code{fseek}, @code{fseeko} or @code{rewind}; @pxref{File
747 Positioning}) is called, any pending pushed-back characters are
750 Unreading a character on a stream that is at end of file clears the
751 end-of-file indicator for the stream, because it makes the character of
752 input available. After you read that character, trying to read again
753 will encounter end of file.
756 Here is an example showing the use of @code{getc} and @code{ungetc} to
757 skip over whitespace characters. When this function reaches a
758 non-whitespace character, it unreads that character to be seen again on
759 the next read operation on the stream.
766 skip_whitespace (FILE *stream)
770 /* @r{No need to check for @code{EOF} because it is not}
771 @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.} */
778 @node Block Input/Output
779 @section Block Input/Output
781 This section describes how to do input and output operations on blocks
782 of data. You can use these functions to read and write binary data, as
783 well as to read and write text in fixed-size blocks instead of by
785 @cindex binary I/O to a stream
786 @cindex block I/O to a stream
787 @cindex reading from a stream, by blocks
788 @cindex writing to a stream, by blocks
790 Binary files are typically used to read and write blocks of data in the
791 same format as is used to represent the data in a running program. In
792 other words, arbitrary blocks of memory---not just character or string
793 objects---can be written to a binary file, and meaningfully read in
794 again by the same program.
796 Storing data in binary form is often considerably more efficient than
797 using the formatted I/O functions. Also, for floating-point numbers,
798 the binary form avoids possible loss of precision in the conversion
799 process. On the other hand, binary files can't be examined or modified
800 easily using many standard file utilities (such as text editors), and
801 are not portable between different implementations of the language, or
802 different kinds of computers.
804 These functions are declared in @file{stdio.h}.
809 @deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
810 This function reads up to @var{count} objects of size @var{size} into
811 the array @var{data}, from the stream @var{stream}. It returns the
812 number of objects actually read, which might be less than @var{count} if
813 a read error occurs or the end of the file is reached. This function
814 returns a value of zero (and doesn't read anything) if either @var{size}
815 or @var{count} is zero.
817 If @code{fread} encounters end of file in the middle of an object, it
818 returns the number of complete objects read, and discards the partial
819 object. Therefore, the stream remains at the actual end of the file.
824 @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
825 This function writes up to @var{count} objects of size @var{size} from
826 the array @var{data}, to the stream @var{stream}. The return value is
827 normally @var{count}, if the call succeeds. Any other value indicates
828 some sort of error, such as running out of space.
831 @node Formatted Output
832 @section Formatted Output
834 @cindex format string, for @code{printf}
835 @cindex template, for @code{printf}
836 @cindex formatted output to a stream
837 @cindex writing to a stream, formatted
838 The functions described in this section (@code{printf} and related
839 functions) provide a convenient way to perform formatted output. You
840 call @code{printf} with a @dfn{format string} or @dfn{template string}
841 that specifies how to format the values of the remaining arguments.
843 Unless your program is a filter that specifically performs line- or
844 character-oriented processing, using @code{printf} or one of the other
845 related functions described in this section is usually the easiest and
846 most concise way to perform output. These functions are especially
847 useful for printing error messages, tables of data, and the like.
850 * Formatted Output Basics:: Some examples to get you started.
851 * Output Conversion Syntax:: General syntax of conversion
853 * Table of Output Conversions:: Summary of output conversions and
855 * Integer Conversions:: Details about formatting of integers.
856 * Floating-Point Conversions:: Details about formatting of
857 floating-point numbers.
858 * Other Output Conversions:: Details about formatting of strings,
859 characters, pointers, and the like.
860 * Formatted Output Functions:: Descriptions of the actual functions.
861 * Dynamic Output:: Functions that allocate memory for the output.
862 * Variable Arguments Output:: @code{vprintf} and friends.
863 * Parsing a Template String:: What kinds of args does a given template
865 * Example of Parsing:: Sample program using @code{parse_printf_format}.
868 @node Formatted Output Basics
869 @subsection Formatted Output Basics
871 The @code{printf} function can be used to print any number of arguments.
872 The template string argument you supply in a call provides
873 information not only about the number of additional arguments, but also
874 about their types and what style should be used for printing them.
876 Ordinary characters in the template string are simply written to the
877 output stream as-is, while @dfn{conversion specifications} introduced by
878 a @samp{%} character in the template cause subsequent arguments to be
879 formatted and written to the output stream. For example,
880 @cindex conversion specifications (@code{printf})
884 char filename[] = "foo.txt";
885 printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
893 Processing of `foo.txt' is 37% finished.
897 This example shows the use of the @samp{%d} conversion to specify that
898 an @code{int} argument should be printed in decimal notation, the
899 @samp{%s} conversion to specify printing of a string argument, and
900 the @samp{%%} conversion to print a literal @samp{%} character.
902 There are also conversions for printing an integer argument as an
903 unsigned value in octal, decimal, or hexadecimal radix (@samp{%o},
904 @samp{%u}, or @samp{%x}, respectively); or as a character value
907 Floating-point numbers can be printed in normal, fixed-point notation
908 using the @samp{%f} conversion or in exponential notation using the
909 @samp{%e} conversion. The @samp{%g} conversion uses either @samp{%e}
910 or @samp{%f} format, depending on what is more appropriate for the
911 magnitude of the particular number.
913 You can control formatting more precisely by writing @dfn{modifiers}
914 between the @samp{%} and the character that indicates which conversion
915 to apply. These slightly alter the ordinary behavior of the conversion.
916 For example, most conversion specifications permit you to specify a
917 minimum field width and a flag indicating whether you want the result
918 left- or right-justified within the field.
920 The specific flags and modifiers that are permitted and their
921 interpretation vary depending on the particular conversion. They're all
922 described in more detail in the following sections. Don't worry if this
923 all seems excessively complicated at first; you can almost always get
924 reasonable free-format output without using any of the modifiers at all.
925 The modifiers are mostly used to make the output look ``prettier'' in
928 @node Output Conversion Syntax
929 @subsection Output Conversion Syntax
931 This section provides details about the precise syntax of conversion
932 specifications that can appear in a @code{printf} template
935 Characters in the template string that are not part of a conversion
936 specification are printed as-is to the output stream. Multibyte
937 character sequences (@pxref{Character Set Handling}) are permitted in a
940 The conversion specifications in a @code{printf} template string have
944 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion}
947 For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-}
948 is a flag, @samp{10} specifies the field width, the precision is
949 @samp{8}, the letter @samp{l} is a type modifier, and @samp{d} specifies
950 the conversion style. (This particular type specifier says to
951 print a @code{long int} argument in decimal notation, with a minimum of
952 8 digits left-justified in a field at least 10 characters wide.)
954 In more detail, output conversion specifications consist of an
955 initial @samp{%} character followed in sequence by:
959 An optional specification of the parameter used for this format.
960 Normally the parameters to the @code{printf} function a assigned to the
961 formats in the order of appearance in the format string. But in some
962 situations (such as message translation) this is not desirable and this
963 extension allows to specify and explicit parameter to be used.
965 The @var{param-no} part of the format must be an integer in the range of
966 1 to the maximum number of arguments present to the function call. Some
967 implementations limit this number to a certainly upper bound. The exact
968 limit can be retrieved by the following constant.
970 @defvr Macro NL_ARGMAX
971 The value of @code{ARGMAX} is the maximum value allowed for the
972 specification of an positional parameter in a @code{printf} call. The
973 actual value in effect at runtime can be retrieved by using
974 @code{sysconf} using the @code{_SC_NL_ARGMAX} parameter @pxref{Sysconf
977 Some system have a quite low limit such as @math{9} for @w{System V}
978 systems. The GNU C library has no real limit.
981 If any of the formats has a specification for the parameter position all
982 of them in the format string shall have one. Otherwise the behaviour is
986 Zero or more @dfn{flag characters} that modify the normal behavior of
987 the conversion specification.
988 @cindex flag character (@code{printf})
991 An optional decimal integer specifying the @dfn{minimum field width}.
992 If the normal conversion produces fewer characters than this, the field
993 is padded with spaces to the specified width. This is a @emph{minimum}
994 value; if the normal conversion produces more characters than this, the
995 field is @emph{not} truncated. Normally, the output is right-justified
997 @cindex minimum field width (@code{printf})
999 You can also specify a field width of @samp{*}. This means that the
1000 next argument in the argument list (before the actual value to be
1001 printed) is used as the field width. The value must be an @code{int}.
1002 If the value is negative, this means to set the @samp{-} flag (see
1003 below) and to use the absolute value as the field width.
1006 An optional @dfn{precision} to specify the number of digits to be
1007 written for the numeric conversions. If the precision is specified, it
1008 consists of a period (@samp{.}) followed optionally by a decimal integer
1009 (which defaults to zero if omitted).
1010 @cindex precision (@code{printf})
1012 You can also specify a precision of @samp{*}. This means that the next
1013 argument in the argument list (before the actual value to be printed) is
1014 used as the precision. The value must be an @code{int}, and is ignored
1015 if it is negative. If you specify @samp{*} for both the field width and
1016 precision, the field width argument precedes the precision argument.
1017 Other C library versions may not recognize this syntax.
1020 An optional @dfn{type modifier character}, which is used to specify the
1021 data type of the corresponding argument if it differs from the default
1022 type. (For example, the integer conversions assume a type of @code{int},
1023 but you can specify @samp{h}, @samp{l}, or @samp{L} for other integer
1025 @cindex type modifier character (@code{printf})
1028 A character that specifies the conversion to be applied.
1031 The exact options that are permitted and how they are interpreted vary
1032 between the different conversion specifiers. See the descriptions of the
1033 individual conversions for information about the particular options that
1036 With the @samp{-Wformat} option, the GNU C compiler checks calls to
1037 @code{printf} and related functions. It examines the format string and
1038 verifies that the correct number and types of arguments are supplied.
1039 There is also a GNU C syntax to tell the compiler that a function you
1040 write uses a @code{printf}-style format string.
1041 @xref{Function Attributes, , Declaring Attributes of Functions,
1042 gcc.info, Using GNU CC}, for more information.
1044 @node Table of Output Conversions
1045 @subsection Table of Output Conversions
1046 @cindex output conversions, for @code{printf}
1048 Here is a table summarizing what all the different conversions do:
1051 @item @samp{%d}, @samp{%i}
1052 Print an integer as a signed decimal number. @xref{Integer
1053 Conversions}, for details. @samp{%d} and @samp{%i} are synonymous for
1054 output, but are different when used with @code{scanf} for input
1055 (@pxref{Table of Input Conversions}).
1058 Print an integer as an unsigned octal number. @xref{Integer
1059 Conversions}, for details.
1062 Print an integer as an unsigned decimal number. @xref{Integer
1063 Conversions}, for details.
1065 @item @samp{%x}, @samp{%X}
1066 Print an integer as an unsigned hexadecimal number. @samp{%x} uses
1067 lower-case letters and @samp{%X} uses upper-case. @xref{Integer
1068 Conversions}, for details.
1071 Print a floating-point number in normal (fixed-point) notation.
1072 @xref{Floating-Point Conversions}, for details.
1074 @item @samp{%e}, @samp{%E}
1075 Print a floating-point number in exponential notation. @samp{%e} uses
1076 lower-case letters and @samp{%E} uses upper-case. @xref{Floating-Point
1077 Conversions}, for details.
1079 @item @samp{%g}, @samp{%G}
1080 Print a floating-point number in either normal or exponential notation,
1081 whichever is more appropriate for its magnitude. @samp{%g} uses
1082 lower-case letters and @samp{%G} uses upper-case. @xref{Floating-Point
1083 Conversions}, for details.
1085 @item @samp{%a}, @samp{%A}
1086 Print a floating-point number in a hexadecimal fractional notation which
1087 the exponent to base 2 represented in decimal digits. @samp{%a} uses
1088 lower-case letters and @samp{%A} uses upper-case. @xref{Floating-Point
1089 Conversions}, for details.
1092 Print a single character. @xref{Other Output Conversions}.
1095 Print a string. @xref{Other Output Conversions}.
1098 Print the value of a pointer. @xref{Other Output Conversions}.
1101 Get the number of characters printed so far. @xref{Other Output Conversions}.
1102 Note that this conversion specification never produces any output.
1105 Print the string corresponding to the value of @code{errno}.
1106 (This is a GNU extension.)
1107 @xref{Other Output Conversions}.
1110 Print a literal @samp{%} character. @xref{Other Output Conversions}.
1113 If the syntax of a conversion specification is invalid, unpredictable
1114 things will happen, so don't do this. If there aren't enough function
1115 arguments provided to supply values for all the conversion
1116 specifications in the template string, or if the arguments are not of
1117 the correct types, the results are unpredictable. If you supply more
1118 arguments than conversion specifications, the extra argument values are
1119 simply ignored; this is sometimes useful.
1121 @node Integer Conversions
1122 @subsection Integer Conversions
1124 This section describes the options for the @samp{%d}, @samp{%i},
1125 @samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
1126 specifications. These conversions print integers in various formats.
1128 The @samp{%d} and @samp{%i} conversion specifications both print an
1129 @code{int} argument as a signed decimal number; while @samp{%o},
1130 @samp{%u}, and @samp{%x} print the argument as an unsigned octal,
1131 decimal, or hexadecimal number (respectively). The @samp{%X} conversion
1132 specification is just like @samp{%x} except that it uses the characters
1133 @samp{ABCDEF} as digits instead of @samp{abcdef}.
1135 The following flags are meaningful:
1139 Left-justify the result in the field (instead of the normal
1140 right-justification).
1143 For the signed @samp{%d} and @samp{%i} conversions, print a
1144 plus sign if the value is positive.
1147 For the signed @samp{%d} and @samp{%i} conversions, if the result
1148 doesn't start with a plus or minus sign, prefix it with a space
1149 character instead. Since the @samp{+} flag ensures that the result
1150 includes a sign, this flag is ignored if you supply both of them.
1153 For the @samp{%o} conversion, this forces the leading digit to be
1154 @samp{0}, as if by increasing the precision. For @samp{%x} or
1155 @samp{%X}, this prefixes a leading @samp{0x} or @samp{0X} (respectively)
1156 to the result. This doesn't do anything useful for the @samp{%d},
1157 @samp{%i}, or @samp{%u} conversions. Using this flag produces output
1158 which can be parsed by the @code{strtoul} function (@pxref{Parsing of
1159 Integers}) and @code{scanf} with the @samp{%i} conversion
1160 (@pxref{Numeric Input Conversions}).
1163 Separate the digits into groups as specified by the locale specified for
1164 the @code{LC_NUMERIC} category; @pxref{General Numeric}. This flag is a
1168 Pad the field with zeros instead of spaces. The zeros are placed after
1169 any indication of sign or base. This flag is ignored if the @samp{-}
1170 flag is also specified, or if a precision is specified.
1173 If a precision is supplied, it specifies the minimum number of digits to
1174 appear; leading zeros are produced if necessary. If you don't specify a
1175 precision, the number is printed with as many digits as it needs. If
1176 you convert a value of zero with an explicit precision of zero, then no
1177 characters at all are produced.
1179 Without a type modifier, the corresponding argument is treated as an
1180 @code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
1181 @code{unsigned int} (for the unsigned conversions @samp{%o}, @samp{%u},
1182 @samp{%x}, and @samp{%X}). Recall that since @code{printf} and friends
1183 are variadic, any @code{char} and @code{short} arguments are
1184 automatically converted to @code{int} by the default argument
1185 promotions. For arguments of other integer types, you can use these
1190 Specifies that the argument is a @code{signed char} or @code{unsigned
1191 char}, as appropriate. A @code{char} argument is converted to an
1192 @code{int} or @code{unsigned int} by the default argument promotions
1193 anyway, but the @samp{h} modifier says to convert it back to a
1196 This modifier was introduced in @w{ISO C 9x}.
1199 Specifies that the argument is a @code{short int} or @code{unsigned
1200 short int}, as appropriate. A @code{short} argument is converted to an
1201 @code{int} or @code{unsigned int} by the default argument promotions
1202 anyway, but the @samp{h} modifier says to convert it back to a
1206 Specifies that the argument is a @code{intmax_t} or @code{uintmax_t}, as
1209 This modifier was introduced in @w{ISO C 9x}.
1212 Specifies that the argument is a @code{long int} or @code{unsigned long
1213 int}, as appropriate. Two @samp{l} characters is like the @samp{L}
1219 Specifies that the argument is a @code{long long int}. (This type is
1220 an extension supported by the GNU C compiler. On systems that don't
1221 support extra-long integers, this is the same as @code{long int}.)
1223 The @samp{q} modifier is another name for the same thing, which comes
1224 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
1228 Specifies that the argument is a @code{ptrdiff_t}.
1230 This modifier was introduced in @w{ISO C 9x}.
1234 Specifies that the argument is a @code{size_t}.
1236 @samp{z} was introduced in @w{ISO C 9x}. @samp{Z} is a GNU extension
1237 predating this addition and should not be used in new code.
1240 Here is an example. Using the template string:
1243 "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
1247 to print numbers using the different options for the @samp{%d}
1248 conversion gives results like:
1251 | 0|0 | +0|+0 | 0|00000| | 00|0|
1252 | 1|1 | +1|+1 | 1|00001| 1| 01|1|
1253 | -1|-1 | -1|-1 | -1|-0001| -1| -01|-1|
1254 |100000|100000|+100000| 100000|100000|100000|100000|100000|
1257 In particular, notice what happens in the last case where the number
1258 is too large to fit in the minimum field width specified.
1260 Here are some more examples showing how unsigned integers print under
1261 various format options, using the template string:
1264 "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
1268 | 0| 0| 0| 0| 0| 0x0| 0X0|0x00000000|
1269 | 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001|
1270 |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
1274 @node Floating-Point Conversions
1275 @subsection Floating-Point Conversions
1277 This section discusses the conversion specifications for floating-point
1278 numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G}
1281 The @samp{%f} conversion prints its argument in fixed-point notation,
1282 producing output of the form
1283 @w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
1284 where the number of digits following the decimal point is controlled
1285 by the precision you specify.
1287 The @samp{%e} conversion prints its argument in exponential notation,
1288 producing output of the form
1289 @w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}.
1290 Again, the number of digits following the decimal point is controlled by
1291 the precision. The exponent always contains at least two digits. The
1292 @samp{%E} conversion is similar but the exponent is marked with the letter
1293 @samp{E} instead of @samp{e}.
1295 The @samp{%g} and @samp{%G} conversions print the argument in the style
1296 of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
1297 than -4 or greater than or equal to the precision; otherwise they use the
1298 @samp{%f} style. Trailing zeros are removed from the fractional portion
1299 of the result and a decimal-point character appears only if it is
1300 followed by a digit.
1302 The @samp{%a} and @samp{%A} conversions are meant for representing
1303 floating-point numbers exactly in textual form so that they can be
1304 exchanged as texts between different programs and/or machines. The
1305 numbers are represented is the form
1306 @w{[@code{-}]@code{0x}@var{h}@code{.}@var{hhh}@code{p}[@code{+}|@code{-}]@var{dd}}.
1307 At the left of the decimal-point character exactly one digit is print.
1308 This character is only @code{0} if the number is denormalized.
1309 Otherwise the value is unspecified; it is implemention dependent how many
1310 bits are used. The number of hexadecimal digits on the right side of
1311 the decimal-point character is equal to the precision. If the precision
1312 is zero it is determined to be large enough to provide an exact
1313 representation of the number (or it is large enough to distinguish two
1314 adjacent values if the @code{FLT_RADIX} is not a power of 2,
1315 @pxref{Floating Point Parameters}). For the @samp{%a} conversion
1316 lower-case characters are used to represent the hexadecimal number and
1317 the prefix and exponent sign are printed as @code{0x} and @code{p}
1318 respectively. Otherwise upper-case characters are used and @code{0X}
1319 and @code{P} are used for the representation of prefix and exponent
1320 string. The exponent to the base of two is printed as a decimal number
1321 using at least one digit but at most as many digits as necessary to
1322 represent the value exactly.
1324 If the value to be printed represents infinity or a NaN, the output is
1325 @w{[@code{-}]@code{inf}} or @code{nan} respectively if the conversion
1326 specifier is @samp{%a}, @samp{%e}, @samp{%f}, or @samp{%g} and it is
1327 @w{[@code{-}]@code{INF}} or @code{NAN} respectively if the conversion is
1328 @samp{%A}, @samp{%E}, or @samp{%G}.
1330 The following flags can be used to modify the behavior:
1332 @comment We use @asis instead of @samp so we can have ` ' as an item.
1335 Left-justify the result in the field. Normally the result is
1339 Always include a plus or minus sign in the result.
1342 If the result doesn't start with a plus or minus sign, prefix it with a
1343 space instead. Since the @samp{+} flag ensures that the result includes
1344 a sign, this flag is ignored if you supply both of them.
1347 Specifies that the result should always include a decimal point, even
1348 if no digits follow it. For the @samp{%g} and @samp{%G} conversions,
1349 this also forces trailing zeros after the decimal point to be left
1350 in place where they would otherwise be removed.
1353 Separate the digits of the integer part of the result into groups as
1354 specified by the locale specified for the @code{LC_NUMERIC} category;
1355 @pxref{General Numeric}. This flag is a GNU extension.
1358 Pad the field with zeros instead of spaces; the zeros are placed
1359 after any sign. This flag is ignored if the @samp{-} flag is also
1363 The precision specifies how many digits follow the decimal-point
1364 character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions. For
1365 these conversions, the default precision is @code{6}. If the precision
1366 is explicitly @code{0}, this suppresses the decimal point character
1367 entirely. For the @samp{%g} and @samp{%G} conversions, the precision
1368 specifies how many significant digits to print. Significant digits are
1369 the first digit before the decimal point, and all the digits after it.
1370 If the precision is @code{0} or not specified for @samp{%g} or @samp{%G},
1371 it is treated like a value of @code{1}. If the value being printed
1372 cannot be expressed accurately in the specified number of digits, the
1373 value is rounded to the nearest number that fits.
1375 Without a type modifier, the floating-point conversions use an argument
1376 of type @code{double}. (By the default argument promotions, any
1377 @code{float} arguments are automatically converted to @code{double}.)
1378 The following type modifier is supported:
1382 An uppercase @samp{L} specifies that the argument is a @code{long
1386 Here are some examples showing how numbers print using the various
1387 floating-point conversions. All of the numbers were printed using
1388 this template string:
1391 "|%13.4a|%13.4f|%13.4e|%13.4g|\n"
1397 | 0x0.0000p+0| 0.0000| 0.0000e+00| 0|
1398 | 0x1.0000p-1| 0.5000| 5.0000e-01| 0.5|
1399 | 0x1.0000p+0| 1.0000| 1.0000e+00| 1|
1400 | -0x1.0000p+0| -1.0000| -1.0000e+00| -1|
1401 | 0x1.9000p+6| 100.0000| 1.0000e+02| 100|
1402 | 0x1.f400p+9| 1000.0000| 1.0000e+03| 1000|
1403 | 0x1.3880p+13| 10000.0000| 1.0000e+04| 1e+04|
1404 | 0x1.81c8p+13| 12345.0000| 1.2345e+04| 1.234e+04|
1405 | 0x1.86a0p+16| 100000.0000| 1.0000e+05| 1e+05|
1406 | 0x1.e240p+16| 123456.0000| 1.2346e+05| 1.235e+05|
1409 Notice how the @samp{%g} conversion drops trailing zeros.
1411 @node Other Output Conversions
1412 @subsection Other Output Conversions
1414 This section describes miscellaneous conversions for @code{printf}.
1416 The @samp{%c} conversion prints a single character. The @code{int}
1417 argument is first converted to an @code{unsigned char}. The @samp{-}
1418 flag can be used to specify left-justification in the field, but no
1419 other flags are defined, and no precision or type modifier can be given.
1423 printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
1427 prints @samp{hello}.
1429 The @samp{%s} conversion prints a string. The corresponding argument
1430 must be of type @code{char *} (or @code{const char *}). A precision can
1431 be specified to indicate the maximum number of characters to write;
1432 otherwise characters in the string up to but not including the
1433 terminating null character are written to the output stream. The
1434 @samp{-} flag can be used to specify left-justification in the field,
1435 but no other flags or type modifiers are defined for this conversion.
1439 printf ("%3s%-6s", "no", "where");
1443 prints @samp{ nowhere }.
1445 If you accidentally pass a null pointer as the argument for a @samp{%s}
1446 conversion, the GNU library prints it as @samp{(null)}. We think this
1447 is more useful than crashing. But it's not good practice to pass a null
1448 argument intentionally.
1450 The @samp{%m} conversion prints the string corresponding to the error
1451 code in @code{errno}. @xref{Error Messages}. Thus:
1454 fprintf (stderr, "can't open `%s': %m\n", filename);
1461 fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
1465 The @samp{%m} conversion is a GNU C library extension.
1467 The @samp{%p} conversion prints a pointer value. The corresponding
1468 argument must be of type @code{void *}. In practice, you can use any
1471 In the GNU system, non-null pointers are printed as unsigned integers,
1472 as if a @samp{%#x} conversion were used. Null pointers print as
1473 @samp{(nil)}. (Pointers might print differently in other systems.)
1478 printf ("%p", "testing");
1482 prints @samp{0x} followed by a hexadecimal number---the address of the
1483 string constant @code{"testing"}. It does not print the word
1486 You can supply the @samp{-} flag with the @samp{%p} conversion to
1487 specify left-justification, but no other flags, precision, or type
1488 modifiers are defined.
1490 The @samp{%n} conversion is unlike any of the other output conversions.
1491 It uses an argument which must be a pointer to an @code{int}, but
1492 instead of printing anything it stores the number of characters printed
1493 so far by this call at that location. The @samp{h} and @samp{l} type
1494 modifiers are permitted to specify that the argument is of type
1495 @code{short int *} or @code{long int *} instead of @code{int *}, but no
1496 flags, field width, or precision are permitted.
1502 printf ("%d %s%n\n", 3, "bears", &nchar);
1513 and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven
1517 The @samp{%%} conversion prints a literal @samp{%} character. This
1518 conversion doesn't use an argument, and no flags, field width,
1519 precision, or type modifiers are permitted.
1522 @node Formatted Output Functions
1523 @subsection Formatted Output Functions
1525 This section describes how to call @code{printf} and related functions.
1526 Prototypes for these functions are in the header file @file{stdio.h}.
1527 Because these functions take a variable number of arguments, you
1528 @emph{must} declare prototypes for them before using them. Of course,
1529 the easiest way to make sure you have all the right prototypes is to
1530 just include @file{stdio.h}.
1535 @deftypefun int printf (const char *@var{template}, @dots{})
1536 The @code{printf} function prints the optional arguments under the
1537 control of the template string @var{template} to the stream
1538 @code{stdout}. It returns the number of characters printed, or a
1539 negative value if there was an output error.
1544 @deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
1545 This function is just like @code{printf}, except that the output is
1546 written to the stream @var{stream} instead of @code{stdout}.
1551 @deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
1552 This is like @code{printf}, except that the output is stored in the character
1553 array @var{s} instead of written to a stream. A null character is written
1554 to mark the end of the string.
1556 The @code{sprintf} function returns the number of characters stored in
1557 the array @var{s}, not including the terminating null character.
1559 The behavior of this function is undefined if copying takes place
1560 between objects that overlap---for example, if @var{s} is also given
1561 as an argument to be printed under control of the @samp{%s} conversion.
1562 @xref{Copying and Concatenation}.
1564 @strong{Warning:} The @code{sprintf} function can be @strong{dangerous}
1565 because it can potentially output more characters than can fit in the
1566 allocation size of the string @var{s}. Remember that the field width
1567 given in a conversion specification is only a @emph{minimum} value.
1569 To avoid this problem, you can use @code{snprintf} or @code{asprintf},
1575 @deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{})
1576 The @code{snprintf} function is similar to @code{sprintf}, except that
1577 the @var{size} argument specifies the maximum number of characters to
1578 produce. The trailing null character is counted towards this limit, so
1579 you should allocate at least @var{size} characters for the string @var{s}.
1581 The return value is the number of characters which would be generated
1582 for the given input, excluding the trailing null. If this value is
1583 greater or equal to @var{size}, not all characters from the result have
1584 been stored in @var{s}. You should try again with a bigger output
1585 string. Here is an example of doing this:
1589 /* @r{Construct a message describing the value of a variable}
1590 @r{whose name is @var{name} and whose value is @var{value}.} */
1592 make_message (char *name, char *value)
1594 /* @r{Guess we need no more than 100 chars of space.} */
1596 char *buffer = (char *) xmalloc (size);
1600 /* @r{Try to print in the allocated space.} */
1601 nchars = snprintf (buffer, size, "value of %s is %s",
1607 /* @r{Reallocate buffer now that we know
1608 how much space is needed.} */
1609 buffer = (char *) xrealloc (buffer, nchars + 1);
1611 /* @r{Try again.} */
1612 snprintf (buffer, size, "value of %s is %s",
1615 /* @r{The last call worked, return the string.} */
1621 In practice, it is often easier just to use @code{asprintf}, below.
1623 @strong{Attention:} In the GNU C library version 2.0 the return value
1624 is the number of characters stored, not including the terminating null.
1625 If this value equals @code{@var{size} - 1}, then there was not enough
1626 space in @var{s} for all the output. This change was necessary with
1627 the adoption of snprintf by ISO C9x.
1630 @node Dynamic Output
1631 @subsection Dynamically Allocating Formatted Output
1633 The functions in this section do formatted output and place the results
1634 in dynamically allocated memory.
1638 @deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
1639 This function is similar to @code{sprintf}, except that it dynamically
1640 allocates a string (as with @code{malloc}; @pxref{Unconstrained
1641 Allocation}) to hold the output, instead of putting the output in a
1642 buffer you allocate in advance. The @var{ptr} argument should be the
1643 address of a @code{char *} object, and @code{asprintf} stores a pointer
1644 to the newly allocated string at that location.
1646 Here is how to use @code{asprintf} to get the same result as the
1647 @code{snprintf} example, but more easily:
1650 /* @r{Construct a message describing the value of a variable}
1651 @r{whose name is @var{name} and whose value is @var{value}.} */
1653 make_message (char *name, char *value)
1656 asprintf (&result, "value of %s is %s", name, value);
1664 @deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
1665 This function is similar to @code{asprintf}, except that it uses the
1666 obstack @var{obstack} to allocate the space. @xref{Obstacks}.
1668 The characters are written onto the end of the current object.
1669 To get at them, you must finish the object with @code{obstack_finish}
1670 (@pxref{Growing Objects}).@refill
1673 @node Variable Arguments Output
1674 @subsection Variable Arguments Output Functions
1676 The functions @code{vprintf} and friends are provided so that you can
1677 define your own variadic @code{printf}-like functions that make use of
1678 the same internals as the built-in formatted output functions.
1680 The most natural way to define such functions would be to use a language
1681 construct to say, ``Call @code{printf} and pass this template plus all
1682 of my arguments after the first five.'' But there is no way to do this
1683 in C, and it would be hard to provide a way, since at the C language
1684 level there is no way to tell how many arguments your function received.
1686 Since that method is impossible, we provide alternative functions, the
1687 @code{vprintf} series, which lets you pass a @code{va_list} to describe
1688 ``all of my arguments after the first five.''
1690 When it is sufficient to define a macro rather than a real function,
1691 the GNU C compiler provides a way to do this much more easily with macros.
1695 #define myprintf(a, b, c, d, e, rest...) \
1696 printf (mytemplate , ## rest...)
1700 @xref{Macro Varargs, , Macros with Variable Numbers of Arguments,
1701 gcc.info, Using GNU CC}, for details. But this is limited to macros,
1702 and does not apply to real functions at all.
1704 Before calling @code{vprintf} or the other functions listed in this
1705 section, you @emph{must} call @code{va_start} (@pxref{Variadic
1706 Functions}) to initialize a pointer to the variable arguments. Then you
1707 can call @code{va_arg} to fetch the arguments that you want to handle
1708 yourself. This advances the pointer past those arguments.
1710 Once your @code{va_list} pointer is pointing at the argument of your
1711 choice, you are ready to call @code{vprintf}. That argument and all
1712 subsequent arguments that were passed to your function are used by
1713 @code{vprintf} along with the template that you specified separately.
1715 In some other systems, the @code{va_list} pointer may become invalid
1716 after the call to @code{vprintf}, so you must not use @code{va_arg}
1717 after you call @code{vprintf}. Instead, you should call @code{va_end}
1718 to retire the pointer from service. However, you can safely call
1719 @code{va_start} on another pointer variable and begin fetching the
1720 arguments again through that pointer. Calling @code{vprintf} does not
1721 destroy the argument list of your function, merely the particular
1722 pointer that you passed to it.
1724 GNU C does not have such restrictions. You can safely continue to fetch
1725 arguments from a @code{va_list} pointer after passing it to
1726 @code{vprintf}, and @code{va_end} is a no-op. (Note, however, that
1727 subsequent @code{va_arg} calls will fetch the same arguments which
1728 @code{vprintf} previously used.)
1730 Prototypes for these functions are declared in @file{stdio.h}.
1735 @deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
1736 This function is similar to @code{printf} except that, instead of taking
1737 a variable number of arguments directly, it takes an argument list
1743 @deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
1744 This is the equivalent of @code{fprintf} with the variable argument list
1745 specified directly as for @code{vprintf}.
1750 @deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
1751 This is the equivalent of @code{sprintf} with the variable argument list
1752 specified directly as for @code{vprintf}.
1757 @deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
1758 This is the equivalent of @code{snprintf} with the variable argument list
1759 specified directly as for @code{vprintf}.
1764 @deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
1765 The @code{vasprintf} function is the equivalent of @code{asprintf} with the
1766 variable argument list specified directly as for @code{vprintf}.
1771 @deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
1772 The @code{obstack_vprintf} function is the equivalent of
1773 @code{obstack_printf} with the variable argument list specified directly
1774 as for @code{vprintf}.@refill
1777 Here's an example showing how you might use @code{vfprintf}. This is a
1778 function that prints error messages to the stream @code{stderr}, along
1779 with a prefix indicating the name of the program
1780 (@pxref{Error Messages}, for a description of
1781 @code{program_invocation_short_name}).
1789 eprintf (const char *template, ...)
1792 extern char *program_invocation_short_name;
1794 fprintf (stderr, "%s: ", program_invocation_short_name);
1795 va_start (ap, template);
1796 vfprintf (stderr, template, ap);
1803 You could call @code{eprintf} like this:
1806 eprintf ("file `%s' does not exist\n", filename);
1809 In GNU C, there is a special construct you can use to let the compiler
1810 know that a function uses a @code{printf}-style format string. Then it
1811 can check the number and types of arguments in each call to the
1812 function, and warn you when they do not match the format string.
1813 For example, take this declaration of @code{eprintf}:
1816 void eprintf (const char *template, ...)
1817 __attribute__ ((format (printf, 1, 2)));
1821 This tells the compiler that @code{eprintf} uses a format string like
1822 @code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input});
1823 the format string appears as the first argument;
1824 and the arguments to satisfy the format begin with the second.
1825 @xref{Function Attributes, , Declaring Attributes of Functions,
1826 gcc.info, Using GNU CC}, for more information.
1828 @node Parsing a Template String
1829 @subsection Parsing a Template String
1830 @cindex parsing a template string
1832 You can use the function @code{parse_printf_format} to obtain
1833 information about the number and types of arguments that are expected by
1834 a given template string. This function permits interpreters that
1835 provide interfaces to @code{printf} to avoid passing along invalid
1836 arguments from the user's program, which could cause a crash.
1838 All the symbols described in this section are declared in the header
1839 file @file{printf.h}.
1843 @deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
1844 This function returns information about the number and types of
1845 arguments expected by the @code{printf} template string @var{template}.
1846 The information is stored in the array @var{argtypes}; each element of
1847 this array describes one argument. This information is encoded using
1848 the various @samp{PA_} macros, listed below.
1850 The @var{n} argument specifies the number of elements in the array
1851 @var{argtypes}. This is the most elements that
1852 @code{parse_printf_format} will try to write.
1854 @code{parse_printf_format} returns the total number of arguments required
1855 by @var{template}. If this number is greater than @var{n}, then the
1856 information returned describes only the first @var{n} arguments. If you
1857 want information about more than that many arguments, allocate a bigger
1858 array and call @code{parse_printf_format} again.
1861 The argument types are encoded as a combination of a basic type and
1866 @deftypevr Macro int PA_FLAG_MASK
1867 This macro is a bitmask for the type modifier flag bits. You can write
1868 the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the
1869 flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to
1870 extract just the basic type code.
1873 Here are symbolic constants that represent the basic types; they stand
1880 This specifies that the base type is @code{int}.
1885 This specifies that the base type is @code{int}, cast to @code{char}.
1890 This specifies that the base type is @code{char *}, a null-terminated string.
1895 This specifies that the base type is @code{void *}, an arbitrary pointer.
1900 This specifies that the base type is @code{float}.
1905 This specifies that the base type is @code{double}.
1910 You can define additional base types for your own programs as offsets
1911 from @code{PA_LAST}. For example, if you have data types @samp{foo}
1912 and @samp{bar} with their own specialized @code{printf} conversions,
1913 you could define encodings for these types as:
1916 #define PA_FOO PA_LAST
1917 #define PA_BAR (PA_LAST + 1)
1921 Here are the flag bits that modify a basic type. They are combined with
1922 the code for the basic type using inclusive-or.
1928 If this bit is set, it indicates that the encoded type is a pointer to
1929 the base type, rather than an immediate value.
1930 For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.
1935 If this bit is set, it indicates that the base type is modified with
1936 @code{short}. (This corresponds to the @samp{h} type modifier.)
1941 If this bit is set, it indicates that the base type is modified with
1942 @code{long}. (This corresponds to the @samp{l} type modifier.)
1946 @item PA_FLAG_LONG_LONG
1947 If this bit is set, it indicates that the base type is modified with
1948 @code{long long}. (This corresponds to the @samp{L} type modifier.)
1952 @item PA_FLAG_LONG_DOUBLE
1953 This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with
1954 a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
1958 For an example of using these facilities, see @ref{Example of Parsing}.
1961 @node Example of Parsing
1962 @subsection Example of Parsing a Template String
1964 Here is an example of decoding argument types for a format string. We
1965 assume this is part of an interpreter which contains arguments of type
1966 @code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
1967 perhaps others which are not valid here).
1970 /* @r{Test whether the @var{nargs} specified objects}
1971 @r{in the vector @var{args} are valid}
1972 @r{for the format string @var{format}:}
1973 @r{if so, return 1.}
1974 @r{If not, return 0 after printing an error message.} */
1977 validate_args (char *format, int nargs, OBJECT *args)
1982 /* @r{Get the information about the arguments.}
1983 @r{Each conversion specification must be at least two characters}
1984 @r{long, so there cannot be more specifications than half the}
1985 @r{length of the string.} */
1987 argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
1988 nwanted = parse_printf_format (string, nelts, argtypes);
1990 /* @r{Check the number of arguments.} */
1991 if (nwanted > nargs)
1993 error ("too few arguments (at least %d required)", nwanted);
1997 /* @r{Check the C type wanted for each argument}
1998 @r{and see if the object given is suitable.} */
1999 for (i = 0; i < nwanted; i++)
2003 if (argtypes[i] & PA_FLAG_PTR)
2006 switch (argtypes[i] & ~PA_FLAG_MASK)
2023 if (TYPE (args[i]) != wanted)
2025 error ("type mismatch for arg number %d", i);
2033 @node Customizing Printf
2034 @section Customizing @code{printf}
2035 @cindex customizing @code{printf}
2036 @cindex defining new @code{printf} conversions
2037 @cindex extending @code{printf}
2039 The GNU C library lets you define your own custom conversion specifiers
2040 for @code{printf} template strings, to teach @code{printf} clever ways
2041 to print the important data structures of your program.
2043 The way you do this is by registering the conversion with the function
2044 @code{register_printf_function}; see @ref{Registering New Conversions}.
2045 One of the arguments you pass to this function is a pointer to a handler
2046 function that produces the actual output; see @ref{Defining the Output
2047 Handler}, for information on how to write this function.
2049 You can also install a function that just returns information about the
2050 number and type of arguments expected by the conversion specifier.
2051 @xref{Parsing a Template String}, for information about this.
2053 The facilities of this section are declared in the header file
2057 * Registering New Conversions:: Using @code{register_printf_function}
2058 to register a new output conversion.
2059 * Conversion Specifier Options:: The handler must be able to get
2060 the options specified in the
2061 template when it is called.
2062 * Defining the Output Handler:: Defining the handler and arginfo
2063 functions that are passed as arguments
2064 to @code{register_printf_function}.
2065 * Printf Extension Example:: How to define a @code{printf}
2067 * Predefined Printf Handlers:: Predefined @code{printf} handlers.
2070 @strong{Portability Note:} The ability to extend the syntax of
2071 @code{printf} template strings is a GNU extension. ISO standard C has
2074 @node Registering New Conversions
2075 @subsection Registering New Conversions
2077 The function to register a new output conversion is
2078 @code{register_printf_function}, declared in @file{printf.h}.
2083 @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function})
2084 This function defines the conversion specifier character @var{spec}.
2085 Thus, if @var{spec} is @code{'z'}, it defines the conversion @samp{%z}.
2086 You can redefine the built-in conversions like @samp{%s}, but flag
2087 characters like @samp{#} and type modifiers like @samp{l} can never be
2088 used as conversions; calling @code{register_printf_function} for those
2089 characters has no effect.
2091 The @var{handler-function} is the function called by @code{printf} and
2092 friends when this conversion appears in a template string.
2093 @xref{Defining the Output Handler}, for information about how to define
2094 a function to pass as this argument. If you specify a null pointer, any
2095 existing handler function for @var{spec} is removed.
2097 The @var{arginfo-function} is the function called by
2098 @code{parse_printf_format} when this conversion appears in a
2099 template string. @xref{Parsing a Template String}, for information
2102 @c The following is not true anymore. The `parse_printf_format' function
2103 @c is now also called from `vfprintf' via `parse_one_spec'.
2104 @c --drepper@gnu, 1996/11/14
2106 @c Normally, you install both functions for a conversion at the same time,
2107 @c but if you are never going to call @code{parse_printf_format}, you do
2108 @c not need to define an arginfo function.
2110 @strong{Attention:} In the GNU C library version before 2.0 the
2111 @var{arginfo-function} function did not need to be installed unless
2112 the user uses the @code{parse_printf_format} function. This changed.
2113 Now a call to any of the @code{printf} functions will call this
2114 function when this format specifier appears in the format string.
2116 The return value is @code{0} on success, and @code{-1} on failure
2117 (which occurs if @var{spec} is out of range).
2119 You can redefine the standard output conversions, but this is probably
2120 not a good idea because of the potential for confusion. Library routines
2121 written by other people could break if you do this.
2124 @node Conversion Specifier Options
2125 @subsection Conversion Specifier Options
2127 If you define a meaning for @samp{%A}, what if the template contains
2128 @samp{%+23A} or @samp{%-#A}? To implement a sensible meaning for these,
2129 the handler when called needs to be able to get the options specified in
2132 Both the @var{handler-function} and @var{arginfo-function} accept an
2133 argument that points to a @code{struct printf_info}, which contains
2134 information about the options appearing in an instance of the conversion
2135 specifier. This data type is declared in the header file
2141 @deftp {Type} {struct printf_info}
2142 This structure is used to pass information about the options appearing
2143 in an instance of a conversion specifier in a @code{printf} template
2144 string to the handler and arginfo functions for that specifier. It
2145 contains the following members:
2149 This is the precision specified. The value is @code{-1} if no precision
2150 was specified. If the precision was given as @samp{*}, the
2151 @code{printf_info} structure passed to the handler function contains the
2152 actual value retrieved from the argument list. But the structure passed
2153 to the arginfo function contains a value of @code{INT_MIN}, since the
2154 actual value is not known.
2157 This is the minimum field width specified. The value is @code{0} if no
2158 width was specified. If the field width was given as @samp{*}, the
2159 @code{printf_info} structure passed to the handler function contains the
2160 actual value retrieved from the argument list. But the structure passed
2161 to the arginfo function contains a value of @code{INT_MIN}, since the
2162 actual value is not known.
2165 This is the conversion specifier character specified. It's stored in
2166 the structure so that you can register the same handler function for
2167 multiple characters, but still have a way to tell them apart when the
2168 handler function is called.
2170 @item unsigned int is_long_double
2171 This is a boolean that is true if the @samp{L}, @samp{ll}, or @samp{q}
2172 type modifier was specified. For integer conversions, this indicates
2173 @code{long long int}, as opposed to @code{long double} for floating
2176 @item unsigned int is_char
2177 This is a boolean that is true if the @samp{hh} type modifier was specified.
2179 @item unsigned int is_short
2180 This is a boolean that is true if the @samp{h} type modifier was specified.
2182 @item unsigned int is_long
2183 This is a boolean that is true if the @samp{l} type modifier was specified.
2185 @item unsigned int alt
2186 This is a boolean that is true if the @samp{#} flag was specified.
2188 @item unsigned int space
2189 This is a boolean that is true if the @samp{ } flag was specified.
2191 @item unsigned int left
2192 This is a boolean that is true if the @samp{-} flag was specified.
2194 @item unsigned int showsign
2195 This is a boolean that is true if the @samp{+} flag was specified.
2197 @item unsigned int group
2198 This is a boolean that is true if the @samp{'} flag was specified.
2200 @item unsigned int extra
2201 This flag has a special meaning depending on the context. It could
2202 be used freely by the user-defined handlers but when called from
2203 the @code{printf} function this variable always contains the value
2206 @item unsigned int wide
2207 This flag is set if the stream is wide oriented.
2210 This is the character to use for padding the output to the minimum field
2211 width. The value is @code{'0'} if the @samp{0} flag was specified, and
2212 @code{' '} otherwise.
2217 @node Defining the Output Handler
2218 @subsection Defining the Output Handler
2220 Now let's look at how to define the handler and arginfo functions
2221 which are passed as arguments to @code{register_printf_function}.
2223 @strong{Compatibility Note:} The interface changed in the GNU libc
2224 version 2.0. Previously the third argument was of type
2227 You should define your handler functions with a prototype like:
2230 int @var{function} (FILE *stream, const struct printf_info *info,
2231 const void *const *args)
2234 The @var{stream} argument passed to the handler function is the stream to
2235 which it should write output.
2237 The @var{info} argument is a pointer to a structure that contains
2238 information about the various options that were included with the
2239 conversion in the template string. You should not modify this structure
2240 inside your handler function. @xref{Conversion Specifier Options}, for
2241 a description of this data structure.
2243 @c The following changes some time back. --drepper@gnu, 1996/11/14
2245 @c The @code{ap_pointer} argument is used to pass the tail of the variable
2246 @c argument list containing the values to be printed to your handler.
2247 @c Unlike most other functions that can be passed an explicit variable
2248 @c argument list, this is a @emph{pointer} to a @code{va_list}, rather than
2249 @c the @code{va_list} itself. Thus, you should fetch arguments by
2250 @c means of @code{va_arg (*ap_pointer, @var{type})}.
2252 @c (Passing a pointer here allows the function that calls your handler
2253 @c function to update its own @code{va_list} variable to account for the
2254 @c arguments that your handler processes. @xref{Variadic Functions}.)
2256 The @var{args} is a vector of pointers to the arguments data.
2257 The number of arguments were determined by calling the argument
2258 information function provided by the user.
2260 Your handler function should return a value just like @code{printf}
2261 does: it should return the number of characters it has written, or a
2262 negative value to indicate an error.
2266 @deftp {Data Type} printf_function
2267 This is the data type that a handler function should have.
2270 If you are going to use @w{@code{parse_printf_format}} in your
2271 application, you must also define a function to pass as the
2272 @var{arginfo-function} argument for each new conversion you install with
2273 @code{register_printf_function}.
2275 You have to define these functions with a prototype like:
2278 int @var{function} (const struct printf_info *info,
2279 size_t n, int *argtypes)
2282 The return value from the function should be the number of arguments the
2283 conversion expects. The function should also fill in no more than
2284 @var{n} elements of the @var{argtypes} array with information about the
2285 types of each of these arguments. This information is encoded using the
2286 various @samp{PA_} macros. (You will notice that this is the same
2287 calling convention @code{parse_printf_format} itself uses.)
2291 @deftp {Data Type} printf_arginfo_function
2292 This type is used to describe functions that return information about
2293 the number and type of arguments used by a conversion specifier.
2296 @node Printf Extension Example
2297 @subsection @code{printf} Extension Example
2299 Here is an example showing how to define a @code{printf} handler function.
2300 This program defines a data structure called a @code{Widget} and
2301 defines the @samp{%W} conversion to print information about @w{@code{Widget *}}
2302 arguments, including the pointer value and the name stored in the data
2303 structure. The @samp{%W} conversion supports the minimum field width and
2304 left-justification options, but ignores everything else.
2307 @include rprintf.c.texi
2310 The output produced by this program looks like:
2313 |<Widget 0xffeffb7c: mywidget>|
2314 | <Widget 0xffeffb7c: mywidget>|
2315 |<Widget 0xffeffb7c: mywidget> |
2318 @node Predefined Printf Handlers
2319 @subsection Predefined @code{printf} Handlers
2321 The GNU libc also contains a concrete and useful application of the
2322 @code{printf} handler extension. There are two functions available
2323 which implement a special way to print floating-point numbers.
2327 @deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args})
2328 Print a given floating point number as for the format @code{%f} except
2329 that there is a postfix character indicating the divisor for the
2330 number to make this less than 1000. There are two possible divisors:
2331 powers of 1024 or powers to 1000. Which one is used depends on the
2332 format character specified while registered this handler. If the
2333 character is of lower case, 1024 is used. For upper case characters,
2336 The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes,
2337 etc. The full table is:
2340 @multitable @hsep @vsep {' '} {2^10 (1024)} {zetta} {Upper} {10^24 (1000)}
2341 @item low @tab Multiplier @tab From @tab Upper @tab Multiplier
2342 @item ' ' @tab 1 @tab @tab ' ' @tab 1
2343 @item k @tab 2^10 (1024) @tab kilo @tab K @tab 10^3 (1000)
2344 @item m @tab 2^20 @tab mega @tab M @tab 10^6
2345 @item g @tab 2^30 @tab giga @tab G @tab 10^9
2346 @item t @tab 2^40 @tab tera @tab T @tab 10^12
2347 @item p @tab 2^50 @tab peta @tab P @tab 10^15
2348 @item e @tab 2^60 @tab exa @tab E @tab 10^18
2349 @item z @tab 2^70 @tab zetta @tab Z @tab 10^21
2350 @item y @tab 2^80 @tab yotta @tab Y @tab 10^24
2355 \hbox to\hsize{\hfil\vbox{\offinterlineskip
2357 \halign{\strut#& \vrule#\tabskip=1em plus2em& {\tt#}\hfil& \vrule#& #\hfil& \vrule#& #\hfil& \vrule#& {\tt#}\hfil& \vrule#& #\hfil& \vrule#\tabskip=0pt\cr
2359 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
2360 && \omit low && Multiplier && From && \omit Upper && Multiplier &\cr
2361 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
2363 && {\tt\char32} && 1 && && {\tt\char32} && 1 &\cr
2364 && k && $2^{10} = 1024$ && kilo && K && $10^3 = 1000$ &\cr
2365 && m && $2^{20}$ && mega && M && $10^6$ &\cr
2366 && g && $2^{30}$ && giga && G && $10^9$ &\cr
2367 && t && $2^{40}$ && tera && T && $10^{12}$ &\cr
2368 && p && $2^{50}$ && peta && P && $10^{15}$ &\cr
2369 && e && $2^{60}$ && exa && E && $10^{18}$ &\cr
2370 && z && $2^{70}$ && zetta && Z && $10^{21}$ &\cr
2371 && y && $2^{80}$ && yotta && Y && $10^{24}$ &\cr
2372 \noalign{\hrule}}}\hfil}
2376 The default precision is 3, i.e., 1024 is printed with a lower-case
2377 format character as if it were @code{%.3fk} and will yield @code{1.000k}.
2380 Due to the requirements of @code{register_printf_function} we must also
2381 provide the function which return information about the arguments.
2385 @deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes})
2386 This function will return in @var{argtypes} the information about the
2387 used parameters in the way the @code{vfprintf} implementation expects
2388 it. The format always takes one argument.
2391 To use these functions both functions must be registered with a call like
2394 register_printf_function ('B', printf_size, printf_size_info);
2397 Here we register the functions to print numbers as powers of 1000 since
2398 the format character @code{'B'} is an upper-case character. If we
2399 would additionally use @code{'b'} in a line like
2402 register_printf_function ('b', printf_size, printf_size_info);
2406 we could also print using power of 1024. Please note that all what is
2407 different in these both lines in the format specifier. The
2408 @code{printf_size} function knows about the difference of low and upper
2409 case format specifiers.
2411 The use of @code{'B'} and @code{'b'} is no coincidence. Rather it is
2412 the preferred way to use this functionality since it is available on
2413 some other systems also available using the format specifiers.
2415 @node Formatted Input
2416 @section Formatted Input
2418 @cindex formatted input from a stream
2419 @cindex reading from a stream, formatted
2420 @cindex format string, for @code{scanf}
2421 @cindex template, for @code{scanf}
2422 The functions described in this section (@code{scanf} and related
2423 functions) provide facilities for formatted input analogous to the
2424 formatted output facilities. These functions provide a mechanism for
2425 reading arbitrary values under the control of a @dfn{format string} or
2426 @dfn{template string}.
2429 * Formatted Input Basics:: Some basics to get you started.
2430 * Input Conversion Syntax:: Syntax of conversion specifications.
2431 * Table of Input Conversions:: Summary of input conversions and what they do.
2432 * Numeric Input Conversions:: Details of conversions for reading numbers.
2433 * String Input Conversions:: Details of conversions for reading strings.
2434 * Dynamic String Input:: String conversions that @code{malloc} the buffer.
2435 * Other Input Conversions:: Details of miscellaneous other conversions.
2436 * Formatted Input Functions:: Descriptions of the actual functions.
2437 * Variable Arguments Input:: @code{vscanf} and friends.
2440 @node Formatted Input Basics
2441 @subsection Formatted Input Basics
2443 Calls to @code{scanf} are superficially similar to calls to
2444 @code{printf} in that arbitrary arguments are read under the control of
2445 a template string. While the syntax of the conversion specifications in
2446 the template is very similar to that for @code{printf}, the
2447 interpretation of the template is oriented more towards free-format
2448 input and simple pattern matching, rather than fixed-field formatting.
2449 For example, most @code{scanf} conversions skip over any amount of
2450 ``white space'' (including spaces, tabs, and newlines) in the input
2451 file, and there is no concept of precision for the numeric input
2452 conversions as there is for the corresponding output conversions.
2453 Ordinarily, non-whitespace characters in the template are expected to
2454 match characters in the input stream exactly, but a matching failure is
2455 distinct from an input error on the stream.
2456 @cindex conversion specifications (@code{scanf})
2458 Another area of difference between @code{scanf} and @code{printf} is
2459 that you must remember to supply pointers rather than immediate values
2460 as the optional arguments to @code{scanf}; the values that are read are
2461 stored in the objects that the pointers point to. Even experienced
2462 programmers tend to forget this occasionally, so if your program is
2463 getting strange errors that seem to be related to @code{scanf}, you
2464 might want to double-check this.
2466 When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
2467 leaving the first non-matching character as the next character to be
2468 read from the stream. The normal return value from @code{scanf} is the
2469 number of values that were assigned, so you can use this to determine if
2470 a matching error happened before all the expected values were read.
2471 @cindex matching failure, in @code{scanf}
2473 The @code{scanf} function is typically used for things like reading in
2474 the contents of tables. For example, here is a function that uses
2475 @code{scanf} to initialize an array of @code{double}:
2479 readarray (double *array, int n)
2483 if (scanf (" %lf", &(array[i])) != 1)
2484 invalid_input_error ();
2488 The formatted input functions are not used as frequently as the
2489 formatted output functions. Partly, this is because it takes some care
2490 to use them properly. Another reason is that it is difficult to recover
2491 from a matching error.
2493 If you are trying to read input that doesn't match a single, fixed
2494 pattern, you may be better off using a tool such as Flex to generate a
2495 lexical scanner, or Bison to generate a parser, rather than using
2496 @code{scanf}. For more information about these tools, see @ref{, , ,
2497 flex.info, Flex: The Lexical Scanner Generator}, and @ref{, , ,
2498 bison.info, The Bison Reference Manual}.
2500 @node Input Conversion Syntax
2501 @subsection Input Conversion Syntax
2503 A @code{scanf} template string is a string that contains ordinary
2504 multibyte characters interspersed with conversion specifications that
2505 start with @samp{%}.
2507 Any whitespace character (as defined by the @code{isspace} function;
2508 @pxref{Classification of Characters}) in the template causes any number
2509 of whitespace characters in the input stream to be read and discarded.
2510 The whitespace characters that are matched need not be exactly the same
2511 whitespace characters that appear in the template string. For example,
2512 write @samp{ , } in the template to recognize a comma with optional
2513 whitespace before and after.
2515 Other characters in the template string that are not part of conversion
2516 specifications must match characters in the input stream exactly; if
2517 this is not the case, a matching failure occurs.
2519 The conversion specifications in a @code{scanf} template string
2520 have the general form:
2523 % @var{flags} @var{width} @var{type} @var{conversion}
2526 In more detail, an input conversion specification consists of an initial
2527 @samp{%} character followed in sequence by:
2531 An optional @dfn{flag character} @samp{*}, which says to ignore the text
2532 read for this specification. When @code{scanf} finds a conversion
2533 specification that uses this flag, it reads input as directed by the
2534 rest of the conversion specification, but it discards this input, does
2535 not use a pointer argument, and does not increment the count of
2536 successful assignments.
2537 @cindex flag character (@code{scanf})
2540 An optional flag character @samp{a} (valid with string conversions only)
2541 which requests allocation of a buffer long enough to store the string in.
2542 (This is a GNU extension.)
2543 @xref{Dynamic String Input}.
2546 An optional decimal integer that specifies the @dfn{maximum field
2547 width}. Reading of characters from the input stream stops either when
2548 this maximum is reached or when a non-matching character is found,
2549 whichever happens first. Most conversions discard initial whitespace
2550 characters (those that don't are explicitly documented), and these
2551 discarded characters don't count towards the maximum field width.
2552 String input conversions store a null character to mark the end of the
2553 input; the maximum field width does not include this terminator.
2554 @cindex maximum field width (@code{scanf})
2557 An optional @dfn{type modifier character}. For example, you can
2558 specify a type modifier of @samp{l} with integer conversions such as
2559 @samp{%d} to specify that the argument is a pointer to a @code{long int}
2560 rather than a pointer to an @code{int}.
2561 @cindex type modifier character (@code{scanf})
2564 A character that specifies the conversion to be applied.
2567 The exact options that are permitted and how they are interpreted vary
2568 between the different conversion specifiers. See the descriptions of the
2569 individual conversions for information about the particular options that
2572 With the @samp{-Wformat} option, the GNU C compiler checks calls to
2573 @code{scanf} and related functions. It examines the format string and
2574 verifies that the correct number and types of arguments are supplied.
2575 There is also a GNU C syntax to tell the compiler that a function you
2576 write uses a @code{scanf}-style format string.
2577 @xref{Function Attributes, , Declaring Attributes of Functions,
2578 gcc.info, Using GNU CC}, for more information.
2580 @node Table of Input Conversions
2581 @subsection Table of Input Conversions
2582 @cindex input conversions, for @code{scanf}
2584 Here is a table that summarizes the various conversion specifications:
2588 Matches an optionally signed integer written in decimal. @xref{Numeric
2592 Matches an optionally signed integer in any of the formats that the C
2593 language defines for specifying an integer constant. @xref{Numeric
2597 Matches an unsigned integer written in octal radix.
2598 @xref{Numeric Input Conversions}.
2601 Matches an unsigned integer written in decimal radix.
2602 @xref{Numeric Input Conversions}.
2604 @item @samp{%x}, @samp{%X}
2605 Matches an unsigned integer written in hexadecimal radix.
2606 @xref{Numeric Input Conversions}.
2608 @item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
2609 Matches an optionally signed floating-point number. @xref{Numeric Input
2613 Matches a string containing only non-whitespace characters.
2614 @xref{String Input Conversions}.
2617 Matches a string of characters that belong to a specified set.
2618 @xref{String Input Conversions}.
2621 Matches a string of one or more characters; the number of characters
2622 read is controlled by the maximum field width given for the conversion.
2623 @xref{String Input Conversions}.
2626 Matches a pointer value in the same implementation-defined format used
2627 by the @samp{%p} output conversion for @code{printf}. @xref{Other Input
2631 This conversion doesn't read any characters; it records the number of
2632 characters read so far by this call. @xref{Other Input Conversions}.
2635 This matches a literal @samp{%} character in the input stream. No
2636 corresponding argument is used. @xref{Other Input Conversions}.
2639 If the syntax of a conversion specification is invalid, the behavior is
2640 undefined. If there aren't enough function arguments provided to supply
2641 addresses for all the conversion specifications in the template strings
2642 that perform assignments, or if the arguments are not of the correct
2643 types, the behavior is also undefined. On the other hand, extra
2644 arguments are simply ignored.
2646 @node Numeric Input Conversions
2647 @subsection Numeric Input Conversions
2649 This section describes the @code{scanf} conversions for reading numeric
2652 The @samp{%d} conversion matches an optionally signed integer in decimal
2653 radix. The syntax that is recognized is the same as that for the
2654 @code{strtol} function (@pxref{Parsing of Integers}) with the value
2655 @code{10} for the @var{base} argument.
2657 The @samp{%i} conversion matches an optionally signed integer in any of
2658 the formats that the C language defines for specifying an integer
2659 constant. The syntax that is recognized is the same as that for the
2660 @code{strtol} function (@pxref{Parsing of Integers}) with the value
2661 @code{0} for the @var{base} argument. (You can print integers in this
2662 syntax with @code{printf} by using the @samp{#} flag character with the
2663 @samp{%x}, @samp{%o}, or @samp{%d} conversion. @xref{Integer Conversions}.)
2665 For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
2666 could be read in as integers under the @samp{%i} conversion. Each of
2667 these specifies a number with decimal value @code{10}.
2669 The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned
2670 integers in octal, decimal, and hexadecimal radices, respectively. The
2671 syntax that is recognized is the same as that for the @code{strtoul}
2672 function (@pxref{Parsing of Integers}) with the appropriate value
2673 (@code{8}, @code{10}, or @code{16}) for the @var{base} argument.
2675 The @samp{%X} conversion is identical to the @samp{%x} conversion. They
2676 both permit either uppercase or lowercase letters to be used as digits.
2678 The default type of the corresponding argument for the @code{%d} and
2679 @code{%i} conversions is @code{int *}, and @code{unsigned int *} for the
2680 other integer conversions. You can use the following type modifiers to
2681 specify other sizes of integer:
2685 Specifies that the argument is a @code{signed char *} or @code{unsigned
2688 This modifier was introduced in @w{ISO C 9x}.
2691 Specifies that the argument is a @code{short int *} or @code{unsigned
2695 Specifies that the argument is a @code{intmax_t *} or @code{uintmax_t *}.
2697 This modifier was introduced in @w{ISO C 9x}.
2700 Specifies that the argument is a @code{long int *} or @code{unsigned
2701 long int *}. Two @samp{l} characters is like the @samp{L} modifier, below.
2707 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
2708 GNU C compiler. For systems that don't provide extra-long integers, this
2709 is the same as @code{long int}.)
2711 The @samp{q} modifier is another name for the same thing, which comes
2712 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
2716 Specifies that the argument is a @code{ptrdiff_t *}.
2718 This modifier was introduced in @w{ISO C 9x}.
2721 Specifies that the argument is a @code{size_t *}.
2723 This modifier was introduced in @w{ISO C 9x}.
2726 All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
2727 input conversions are interchangeable. They all match an optionally
2728 signed floating point number, in the same syntax as for the
2729 @code{strtod} function (@pxref{Parsing of Floats}).
2731 For the floating-point input conversions, the default argument type is
2732 @code{float *}. (This is different from the corresponding output
2733 conversions, where the default type is @code{double}; remember that
2734 @code{float} arguments to @code{printf} are converted to @code{double}
2735 by the default argument promotions, but @code{float *} arguments are
2736 not promoted to @code{double *}.) You can specify other sizes of float
2737 using these type modifiers:
2741 Specifies that the argument is of type @code{double *}.
2744 Specifies that the argument is of type @code{long double *}.
2747 For all the above number parsing formats there is an additional optional
2748 flag @samp{'}. When this flag is given the @code{scanf} function
2749 expects the number represented in the input string to be formatted
2750 according to the grouping rules of the currently selected locale
2751 (@pxref{General Numeric}).
2753 If the @code{"C"} or @code{"POSIX"} locale is selected there is no
2754 difference. But for a locale which specifies values for the appropriate
2755 fields in the locale the input must have the correct form in the input.
2756 Otherwise the longest prefix with a correct form is processed.
2758 @node String Input Conversions
2759 @subsection String Input Conversions
2761 This section describes the @code{scanf} input conversions for reading
2762 string and character values: @samp{%s}, @samp{%[}, and @samp{%c}.
2764 You have two options for how to receive the input from these
2769 Provide a buffer to store it in. This is the default. You
2770 should provide an argument of type @code{char *}.
2772 @strong{Warning:} To make a robust program, you must make sure that the
2773 input (plus its terminating null) cannot possibly exceed the size of the
2774 buffer you provide. In general, the only way to do this is to specify a
2775 maximum field width one less than the buffer size. @strong{If you
2776 provide the buffer, always specify a maximum field width to prevent
2780 Ask @code{scanf} to allocate a big enough buffer, by specifying the
2781 @samp{a} flag character. This is a GNU extension. You should provide
2782 an argument of type @code{char **} for the buffer address to be stored
2783 in. @xref{Dynamic String Input}.
2786 The @samp{%c} conversion is the simplest: it matches a fixed number of
2787 characters, always. The maximum field with says how many characters to
2788 read; if you don't specify the maximum, the default is 1. This
2789 conversion doesn't append a null character to the end of the text it
2790 reads. It also does not skip over initial whitespace characters. It
2791 reads precisely the next @var{n} characters, and fails if it cannot get
2792 that many. Since there is always a maximum field width with @samp{%c}
2793 (whether specified, or 1 by default), you can always prevent overflow by
2794 making the buffer long enough.
2796 The @samp{%s} conversion matches a string of non-whitespace characters.
2797 It skips and discards initial whitespace, but stops when it encounters
2798 more whitespace after having read something. It stores a null character
2799 at the end of the text that it reads.
2801 For example, reading the input:
2808 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
2809 reading the same input with the conversion @samp{%10s} produces
2812 @strong{Warning:} If you do not specify a field width for @samp{%s},
2813 then the number of characters read is limited only by where the next
2814 whitespace character appears. This almost certainly means that invalid
2815 input can make your program crash---which is a bug.
2817 To read in characters that belong to an arbitrary set of your choice,
2818 use the @samp{%[} conversion. You specify the set between the @samp{[}
2819 character and a following @samp{]} character, using the same syntax used
2820 in regular expressions. As special cases:
2824 A literal @samp{]} character can be specified as the first character
2828 An embedded @samp{-} character (that is, one that is not the first or
2829 last character of the set) is used to specify a range of characters.
2832 If a caret character @samp{^} immediately follows the initial @samp{[},
2833 then the set of allowed input characters is the everything @emph{except}
2834 the characters listed.
2837 The @samp{%[} conversion does not skip over initial whitespace
2840 Here are some examples of @samp{%[} conversions and what they mean:
2843 @item %25[1234567890]
2844 Matches a string of up to 25 digits.
2847 Matches a string of up to 25 square brackets.
2849 @item %25[^ \f\n\r\t\v]
2850 Matches a string up to 25 characters long that doesn't contain any of
2851 the standard whitespace characters. This is slightly different from
2852 @samp{%s}, because if the input begins with a whitespace character,
2853 @samp{%[} reports a matching failure while @samp{%s} simply discards the
2857 Matches up to 25 lowercase characters.
2860 One more reminder: the @samp{%s} and @samp{%[} conversions are
2861 @strong{dangerous} if you don't specify a maximum width or use the
2862 @samp{a} flag, because input too long would overflow whatever buffer you
2863 have provided for it. No matter how long your buffer is, a user could
2864 supply input that is longer. A well-written program reports invalid
2865 input with a comprehensible error message, not with a crash.
2867 @node Dynamic String Input
2868 @subsection Dynamically Allocating String Conversions
2870 A GNU extension to formatted input lets you safely read a string with no
2871 maximum size. Using this feature, you don't supply a buffer; instead,
2872 @code{scanf} allocates a buffer big enough to hold the data and gives
2873 you its address. To use this feature, write @samp{a} as a flag
2874 character, as in @samp{%as} or @samp{%a[0-9a-z]}.
2876 The pointer argument you supply for where to store the input should have
2877 type @code{char **}. The @code{scanf} function allocates a buffer and
2878 stores its address in the word that the argument points to. You should
2879 free the buffer with @code{free} when you no longer need it.
2881 Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]}
2882 conversion specification to read a ``variable assignment'' of the form
2883 @samp{@var{variable} = @var{value}}.
2887 char *variable, *value;
2889 if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
2892 invalid_input_error ();
2900 @node Other Input Conversions
2901 @subsection Other Input Conversions
2903 This section describes the miscellaneous input conversions.
2905 The @samp{%p} conversion is used to read a pointer value. It recognizes
2906 the same syntax as is used by the @samp{%p} output conversion for
2907 @code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
2908 number just as the @samp{%x} conversion accepts. The corresponding
2909 argument should be of type @code{void **}; that is, the address of a
2910 place to store a pointer.
2912 The resulting pointer value is not guaranteed to be valid if it was not
2913 originally written during the same program execution that reads it in.
2915 The @samp{%n} conversion produces the number of characters read so far
2916 by this call. The corresponding argument should be of type @code{int *}.
2917 This conversion works in the same way as the @samp{%n} conversion for
2918 @code{printf}; see @ref{Other Output Conversions}, for an example.
2920 The @samp{%n} conversion is the only mechanism for determining the
2921 success of literal matches or conversions with suppressed assignments.
2922 If the @samp{%n} follows the locus of a matching failure, then no value
2923 is stored for it since @code{scanf} returns before processing the
2924 @samp{%n}. If you store @code{-1} in that argument slot before calling
2925 @code{scanf}, the presence of @code{-1} after @code{scanf} indicates an
2926 error occurred before the @samp{%n} was reached.
2928 Finally, the @samp{%%} conversion matches a literal @samp{%} character
2929 in the input stream, without using an argument. This conversion does
2930 not permit any flags, field width, or type modifier to be specified.
2932 @node Formatted Input Functions
2933 @subsection Formatted Input Functions
2935 Here are the descriptions of the functions for performing formatted
2937 Prototypes for these functions are in the header file @file{stdio.h}.
2942 @deftypefun int scanf (const char *@var{template}, @dots{})
2943 The @code{scanf} function reads formatted input from the stream
2944 @code{stdin} under the control of the template string @var{template}.
2945 The optional arguments are pointers to the places which receive the
2948 The return value is normally the number of successful assignments. If
2949 an end-of-file condition is detected before any matches are performed
2950 (including matches against whitespace and literal characters in the
2951 template), then @code{EOF} is returned.
2956 @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
2957 This function is just like @code{scanf}, except that the input is read
2958 from the stream @var{stream} instead of @code{stdin}.
2963 @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
2964 This is like @code{scanf}, except that the characters are taken from the
2965 null-terminated string @var{s} instead of from a stream. Reaching the
2966 end of the string is treated as an end-of-file condition.
2968 The behavior of this function is undefined if copying takes place
2969 between objects that overlap---for example, if @var{s} is also given
2970 as an argument to receive a string read under control of the @samp{%s}
2974 @node Variable Arguments Input
2975 @subsection Variable Arguments Input Functions
2977 The functions @code{vscanf} and friends are provided so that you can
2978 define your own variadic @code{scanf}-like functions that make use of
2979 the same internals as the built-in formatted output functions.
2980 These functions are analogous to the @code{vprintf} series of output
2981 functions. @xref{Variable Arguments Output}, for important
2982 information on how to use them.
2984 @strong{Portability Note:} The functions listed in this section are GNU
2989 @deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
2990 This function is similar to @code{scanf} except that, instead of taking
2991 a variable number of arguments directly, it takes an argument list
2992 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
2997 @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
2998 This is the equivalent of @code{fscanf} with the variable argument list
2999 specified directly as for @code{vscanf}.
3004 @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
3005 This is the equivalent of @code{sscanf} with the variable argument list
3006 specified directly as for @code{vscanf}.
3009 In GNU C, there is a special construct you can use to let the compiler
3010 know that a function uses a @code{scanf}-style format string. Then it
3011 can check the number and types of arguments in each call to the
3012 function, and warn you when they do not match the format string.
3013 @xref{Function Attributes, , Declaring Attributes of Functions,
3014 gcc.info, Using GNU CC}, for details.
3016 @node EOF and Errors
3017 @section End-Of-File and Errors
3019 @cindex end of file, on a stream
3020 Many of the functions described in this chapter return the value of the
3021 macro @code{EOF} to indicate unsuccessful completion of the operation.
3022 Since @code{EOF} is used to report both end of file and random errors,
3023 it's often better to use the @code{feof} function to check explicitly
3024 for end of file and @code{ferror} to check for errors. These functions
3025 check indicators that are part of the internal state of the stream
3026 object, indicators set if the appropriate condition was detected by a
3027 previous I/O operation on that stream.
3029 These symbols are declared in the header file @file{stdio.h}.
3034 @deftypevr Macro int EOF
3035 This macro is an integer value that is returned by a number of functions
3036 to indicate an end-of-file condition, or some other error situation.
3037 With the GNU library, @code{EOF} is @code{-1}. In other libraries, its
3038 value may be some other negative number.
3043 @deftypefun void clearerr (FILE *@var{stream})
3044 This function clears the end-of-file and error indicators for the
3045 stream @var{stream}.
3047 The file positioning functions (@pxref{File Positioning}) also clear the
3048 end-of-file indicator for the stream.
3053 @deftypefun int feof (FILE *@var{stream})
3054 The @code{feof} function returns nonzero if and only if the end-of-file
3055 indicator for the stream @var{stream} is set.
3060 @deftypefun int ferror (FILE *@var{stream})
3061 The @code{ferror} function returns nonzero if and only if the error
3062 indicator for the stream @var{stream} is set, indicating that an error
3063 has occurred on a previous operation on the stream.
3066 In addition to setting the error indicator associated with the stream,
3067 the functions that operate on streams also set @code{errno} in the same
3068 way as the corresponding low-level functions that operate on file
3069 descriptors. For example, all of the functions that perform output to a
3070 stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are
3071 implemented in terms of @code{write}, and all of the @code{errno} error
3072 conditions defined for @code{write} are meaningful for these functions.
3073 For more information about the descriptor-level I/O functions, see
3074 @ref{Low-Level I/O}.
3076 @node Binary Streams
3077 @section Text and Binary Streams
3079 The GNU system and other POSIX-compatible operating systems organize all
3080 files as uniform sequences of characters. However, some other systems
3081 make a distinction between files containing text and files containing
3082 binary data, and the input and output facilities of @w{ISO C} provide for
3083 this distinction. This section tells you how to write programs portable
3087 @cindex binary stream
3088 When you open a stream, you can specify either a @dfn{text stream} or a
3089 @dfn{binary stream}. You indicate that you want a binary stream by
3090 specifying the @samp{b} modifier in the @var{opentype} argument to
3091 @code{fopen}; see @ref{Opening Streams}. Without this
3092 option, @code{fopen} opens the file as a text stream.
3094 Text and binary streams differ in several ways:
3098 The data read from a text stream is divided into @dfn{lines} which are
3099 terminated by newline (@code{'\n'}) characters, while a binary stream is
3100 simply a long series of characters. A text stream might on some systems
3101 fail to handle lines more than 254 characters long (including the
3102 terminating newline character).
3103 @cindex lines (in a text file)
3106 On some systems, text files can contain only printing characters,
3107 horizontal tab characters, and newlines, and so text streams may not
3108 support other characters. However, binary streams can handle any
3112 Space characters that are written immediately preceding a newline
3113 character in a text stream may disappear when the file is read in again.
3116 More generally, there need not be a one-to-one mapping between
3117 characters that are read from or written to a text stream, and the
3118 characters in the actual file.
3121 Since a binary stream is always more capable and more predictable than a
3122 text stream, you might wonder what purpose text streams serve. Why not
3123 simply always use binary streams? The answer is that on these operating
3124 systems, text and binary streams use different file formats, and the
3125 only way to read or write ``an ordinary file of text'' that can work
3126 with other text-oriented programs is through a text stream.
3128 In the GNU library, and on all POSIX systems, there is no difference
3129 between text streams and binary streams. When you open a stream, you
3130 get the same kind of stream regardless of whether you ask for binary.
3131 This stream can handle any file content, and has none of the
3132 restrictions that text streams sometimes have.
3134 @node File Positioning
3135 @section File Positioning
3136 @cindex file positioning on a stream
3137 @cindex positioning a stream
3138 @cindex seeking on a stream
3140 The @dfn{file position} of a stream describes where in the file the
3141 stream is currently reading or writing. I/O on the stream advances the
3142 file position through the file. In the GNU system, the file position is
3143 represented as an integer, which counts the number of bytes from the
3144 beginning of the file. @xref{File Position}.
3146 During I/O to an ordinary disk file, you can change the file position
3147 whenever you wish, so as to read or write any portion of the file. Some
3148 other kinds of files may also permit this. Files which support changing
3149 the file position are sometimes referred to as @dfn{random-access}
3152 You can use the functions in this section to examine or modify the file
3153 position indicator associated with a stream. The symbols listed below
3154 are declared in the header file @file{stdio.h}.
3159 @deftypefun {long int} ftell (FILE *@var{stream})
3160 This function returns the current file position of the stream
3163 This function can fail if the stream doesn't support file positioning,
3164 or if the file position can't be represented in a @code{long int}, and
3165 possibly for other reasons as well. If a failure occurs, a value of
3166 @code{-1} is returned.
3171 @deftypefun off_t ftello (FILE *@var{stream})
3172 The @code{ftello} function is similar to @code{ftell} only it corrects a
3173 problem which the POSIX type system. In this type system all file
3174 positions are described using values of type @code{off_t} which is not
3175 necessarily of the same size as @code{long int}. Therefore using
3176 @code{ftell} can lead to problems if the implementation is written on
3177 top of a POSIX compliant lowlevel I/O implementation.
3179 Therefore it is a good idea to prefer @code{ftello} whenever it is
3180 available since its functionality is (if different at all) closer the
3181 underlying definition.
3183 If this function fails it return @code{(off_t) -1}. This can happen due
3184 to missing support for file positioning or internal errors. Otherwise
3185 the return value is the current file position.
3187 The function is an extension defined in the Unix Single Specification
3190 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
3191 32 bit system this function is in fact @code{ftello64}. I.e., the
3192 LFS interface transparently replaces the old interface.
3197 @deftypefun off64_t ftello64 (FILE *@var{stream})
3198 This function is similar to @code{ftello} with the only difference that
3199 the return value is of type @code{off64_t}. This also requires that the
3200 stream @var{stream} was opened using either @code{fopen64},
3201 @code{freopen64}, or @code{tmpfile64} since otherwise the underlying
3202 file operations to position the file pointer beyond the @math{2^31}
3203 bytes limit might fail.
3205 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
3206 bits machine this function is available under the name @code{ftello}
3207 and so transparently replaces the old interface.
3212 @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
3213 The @code{fseek} function is used to change the file position of the
3214 stream @var{stream}. The value of @var{whence} must be one of the
3215 constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
3216 indicate whether the @var{offset} is relative to the beginning of the
3217 file, the current file position, or the end of the file, respectively.
3219 This function returns a value of zero if the operation was successful,
3220 and a nonzero value to indicate failure. A successful call also clears
3221 the end-of-file indicator of @var{stream} and discards any characters
3222 that were ``pushed back'' by the use of @code{ungetc}.
3224 @code{fseek} either flushes any buffered output before setting the file
3225 position or else remembers it so it will be written later in its proper
3231 @deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence})
3232 This function is similar to @code{fseek} but it corrects a problem with
3233 @code{fseek} in a system with POSIX types. Using a value of type
3234 @code{long int} for the offset is not compatible with POSIX.
3235 @code{fseeko} uses the correct type @code{off_t} for the @var{offset}
3238 For this reason it is a good idea to prefer @code{ftello} whenever it is
3239 available since its functionality is (if different at all) closer the
3240 underlying definition.
3242 The functionality and return value is the same as for @code{fseek}.
3244 The function is an extension defined in the Unix Single Specification
3247 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
3248 32 bit system this function is in fact @code{fseeko64}. I.e., the
3249 LFS interface transparently replaces the old interface.
3254 @deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence})
3255 This function is similar to @code{fseeko} with the only difference that
3256 the @var{offset} parameter is of type @code{off64_t}. This also
3257 requires that the stream @var{stream} was opened using either
3258 @code{fopen64}, @code{freopen64}, or @code{tmpfile64} since otherwise
3259 the underlying file operations to position the file pointer beyond the
3260 @math{2^31} bytes limit might fail.
3262 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
3263 bits machine this function is available under the name @code{fseeko}
3264 and so transparently replaces the old interface.
3267 @strong{Portability Note:} In non-POSIX systems, @code{ftell},
3268 @code{ftello}, @code{fseek} and @code{fseeko} might work reliably only
3269 on binary streams. @xref{Binary Streams}.
3271 The following symbolic constants are defined for use as the @var{whence}
3272 argument to @code{fseek}. They are also used with the @code{lseek}
3273 function (@pxref{I/O Primitives}) and to specify offsets for file locks
3274 (@pxref{Control Operations}).
3278 @deftypevr Macro int SEEK_SET
3279 This is an integer constant which, when used as the @var{whence}
3280 argument to the @code{fseek} or @code{fseeko} function, specifies that
3281 the offset provided is relative to the beginning of the file.
3286 @deftypevr Macro int SEEK_CUR
3287 This is an integer constant which, when used as the @var{whence}
3288 argument to the @code{fseek} or @code{fseeko} function, specifies that
3289 the offset provided is relative to the current file position.
3294 @deftypevr Macro int SEEK_END
3295 This is an integer constant which, when used as the @var{whence}
3296 argument to the @code{fseek} or @code{fseeko} function, specifies that
3297 the offset provided is relative to the end of the file.
3302 @deftypefun void rewind (FILE *@var{stream})
3303 The @code{rewind} function positions the stream @var{stream} at the
3304 beginning of the file. It is equivalent to calling @code{fseek} or
3305 @code{fseeko} on the @var{stream} with an @var{offset} argument of
3306 @code{0L} and a @var{whence} argument of @code{SEEK_SET}, except that
3307 the return value is discarded and the error indicator for the stream is
3311 These three aliases for the @samp{SEEK_@dots{}} constants exist for the
3312 sake of compatibility with older BSD systems. They are defined in two
3313 different header files: @file{fcntl.h} and @file{sys/file.h}.
3320 An alias for @code{SEEK_SET}.
3326 An alias for @code{SEEK_CUR}.
3332 An alias for @code{SEEK_END}.
3335 @node Portable Positioning
3336 @section Portable File-Position Functions
3338 On the GNU system, the file position is truly a character count. You
3339 can specify any character count value as an argument to @code{fseek} or
3340 @code{fseeko} and get reliable results for any random access file.
3341 However, some @w{ISO C} systems do not represent file positions in this
3344 On some systems where text streams truly differ from binary streams, it
3345 is impossible to represent the file position of a text stream as a count
3346 of characters from the beginning of the file. For example, the file
3347 position on some systems must encode both a record offset within the
3348 file, and a character offset within the record.
3350 As a consequence, if you want your programs to be portable to these
3351 systems, you must observe certain rules:
3355 The value returned from @code{ftell} on a text stream has no predictable
3356 relationship to the number of characters you have read so far. The only
3357 thing you can rely on is that you can use it subsequently as the
3358 @var{offset} argument to @code{fseek} or @code{fseeko} to move back to
3359 the same file position.
3362 In a call to @code{fseek} or @code{fseeko} on a text stream, either the
3363 @var{offset} must either be zero; or @var{whence} must be
3364 @code{SEEK_SET} and the @var{offset} must be the result of an earlier
3365 call to @code{ftell} on the same stream.
3368 The value of the file position indicator of a text stream is undefined
3369 while there are characters that have been pushed back with @code{ungetc}
3370 that haven't been read or discarded. @xref{Unreading}.
3373 But even if you observe these rules, you may still have trouble for long
3374 files, because @code{ftell} and @code{fseek} use a @code{long int} value
3375 to represent the file position. This type may not have room to encode
3376 all the file positions in a large file. Using the @code{ftello} and
3377 @code{fseeko} functions might help here since the @code{off_t} type is
3378 expected to be able to hold all file position values but this still does
3379 not help to handle additional information which must be associated with
3382 So if you do want to support systems with peculiar encodings for the
3383 file positions, it is better to use the functions @code{fgetpos} and
3384 @code{fsetpos} instead. These functions represent the file position
3385 using the data type @code{fpos_t}, whose internal representation varies
3386 from system to system.
3388 These symbols are declared in the header file @file{stdio.h}.
3393 @deftp {Data Type} fpos_t
3394 This is the type of an object that can encode information about the
3395 file position of a stream, for use by the functions @code{fgetpos} and
3398 In the GNU system, @code{fpos_t} is equivalent to @code{off_t} or
3399 @code{long int}. In other systems, it might have a different internal
3402 When compiling with @code{_FILE_OFFSET_BITS == 64} on a 32 bit machine
3403 this type is in fact equivalent to @code{off64_t} since the LFS
3404 interface transparently replaced the old interface.
3409 @deftp {Data Type} fpos64_t
3410 This is the type of an object that can encode information about the
3411 file position of a stream, for use by the functions @code{fgetpos64} and
3414 In the GNU system, @code{fpos64_t} is equivalent to @code{off64_t} or
3415 @code{long long int}. In other systems, it might have a different internal
3421 @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
3422 This function stores the value of the file position indicator for the
3423 stream @var{stream} in the @code{fpos_t} object pointed to by
3424 @var{position}. If successful, @code{fgetpos} returns zero; otherwise
3425 it returns a nonzero value and stores an implementation-defined positive
3426 value in @code{errno}.
3428 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
3429 32 bit system the function is in fact @code{fgetpos64}. I.e., the LFS
3430 interface transparently replaced the old interface.
3435 @deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position})
3436 This function is similar to @code{fgetpos} but the file position is
3437 returned in a variable of type @code{fpos64_t} to which @var{position}
3440 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
3441 bits machine this function is available under the name @code{fgetpos}
3442 and so transparently replaces the old interface.
3447 @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position})
3448 This function sets the file position indicator for the stream @var{stream}
3449 to the position @var{position}, which must have been set by a previous
3450 call to @code{fgetpos} on the same stream. If successful, @code{fsetpos}
3451 clears the end-of-file indicator on the stream, discards any characters
3452 that were ``pushed back'' by the use of @code{ungetc}, and returns a value
3453 of zero. Otherwise, @code{fsetpos} returns a nonzero value and stores
3454 an implementation-defined positive value in @code{errno}.
3456 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
3457 32 bit system the function is in fact @code{fsetpos64}. I.e., the LFS
3458 interface transparently replaced the old interface.
3463 @deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position})
3464 This function is similar to @code{fsetpos} but the file position used
3465 for positioning is provided in a variable of type @code{fpos64_t} to
3466 which @var{position} points.
3468 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
3469 bits machine this function is available under the name @code{fsetpos}
3470 and so transparently replaces the old interface.
3473 @node Stream Buffering
3474 @section Stream Buffering
3476 @cindex buffering of streams
3477 Characters that are written to a stream are normally accumulated and
3478 transmitted asynchronously to the file in a block, instead of appearing
3479 as soon as they are output by the application program. Similarly,
3480 streams often retrieve input from the host environment in blocks rather
3481 than on a character-by-character basis. This is called @dfn{buffering}.
3483 If you are writing programs that do interactive input and output using
3484 streams, you need to understand how buffering works when you design the
3485 user interface to your program. Otherwise, you might find that output
3486 (such as progress or prompt messages) doesn't appear when you intended
3487 it to, or other unexpected behavior.
3489 This section deals only with controlling when characters are transmitted
3490 between the stream and the file or device, and @emph{not} with how
3491 things like echoing, flow control, and the like are handled on specific
3492 classes of devices. For information on common control operations on
3493 terminal devices, see @ref{Low-Level Terminal Interface}.
3495 You can bypass the stream buffering facilities altogether by using the
3496 low-level input and output functions that operate on file descriptors
3497 instead. @xref{Low-Level I/O}.
3500 * Buffering Concepts:: Terminology is defined here.
3501 * Flushing Buffers:: How to ensure that output buffers are flushed.
3502 * Controlling Buffering:: How to specify what kind of buffering to use.
3505 @node Buffering Concepts
3506 @subsection Buffering Concepts
3508 There are three different kinds of buffering strategies:
3512 Characters written to or read from an @dfn{unbuffered} stream are
3513 transmitted individually to or from the file as soon as possible.
3514 @cindex unbuffered stream
3517 Characters written to a @dfn{line buffered} stream are transmitted to
3518 the file in blocks when a newline character is encountered.
3519 @cindex line buffered stream
3522 Characters written to or read from a @dfn{fully buffered} stream are
3523 transmitted to or from the file in blocks of arbitrary size.
3524 @cindex fully buffered stream
3527 Newly opened streams are normally fully buffered, with one exception: a
3528 stream connected to an interactive device such as a terminal is
3529 initially line buffered. @xref{Controlling Buffering}, for information
3530 on how to select a different kind of buffering. Usually the automatic
3531 selection gives you the most convenient kind of buffering for the file
3534 The use of line buffering for interactive devices implies that output
3535 messages ending in a newline will appear immediately---which is usually
3536 what you want. Output that doesn't end in a newline might or might not
3537 show up immediately, so if you want them to appear immediately, you
3538 should flush buffered output explicitly with @code{fflush}, as described
3539 in @ref{Flushing Buffers}.
3541 @node Flushing Buffers
3542 @subsection Flushing Buffers
3544 @cindex flushing a stream
3545 @dfn{Flushing} output on a buffered stream means transmitting all
3546 accumulated characters to the file. There are many circumstances when
3547 buffered output on a stream is flushed automatically:
3551 When you try to do output and the output buffer is full.
3554 When the stream is closed. @xref{Closing Streams}.
3557 When the program terminates by calling @code{exit}.
3558 @xref{Normal Termination}.
3561 When a newline is written, if the stream is line buffered.
3564 Whenever an input operation on @emph{any} stream actually reads data
3568 If you want to flush the buffered output at another time, call
3569 @code{fflush}, which is declared in the header file @file{stdio.h}.
3574 @deftypefun int fflush (FILE *@var{stream})
3575 This function causes any buffered output on @var{stream} to be delivered
3576 to the file. If @var{stream} is a null pointer, then
3577 @code{fflush} causes buffered output on @emph{all} open output streams
3580 This function returns @code{EOF} if a write error occurs, or zero
3584 @strong{Compatibility Note:} Some brain-damaged operating systems have
3585 been known to be so thoroughly fixated on line-oriented input and output
3586 that flushing a line buffered stream causes a newline to be written!
3587 Fortunately, this ``feature'' seems to be becoming less common. You do
3588 not need to worry about this in the GNU system.
3591 @node Controlling Buffering
3592 @subsection Controlling Which Kind of Buffering
3594 After opening a stream (but before any other operations have been
3595 performed on it), you can explicitly specify what kind of buffering you
3596 want it to have using the @code{setvbuf} function.
3597 @cindex buffering, controlling
3599 The facilities listed in this section are declared in the header
3600 file @file{stdio.h}.
3605 @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
3606 This function is used to specify that the stream @var{stream} should
3607 have the buffering mode @var{mode}, which can be either @code{_IOFBF}
3608 (for full buffering), @code{_IOLBF} (for line buffering), or
3609 @code{_IONBF} (for unbuffered input/output).
3611 If you specify a null pointer as the @var{buf} argument, then @code{setvbuf}
3612 allocates a buffer itself using @code{malloc}. This buffer will be freed
3613 when you close the stream.
3615 Otherwise, @var{buf} should be a character array that can hold at least
3616 @var{size} characters. You should not free the space for this array as
3617 long as the stream remains open and this array remains its buffer. You
3618 should usually either allocate it statically, or @code{malloc}
3619 (@pxref{Unconstrained Allocation}) the buffer. Using an automatic array
3620 is not a good idea unless you close the file before exiting the block
3621 that declares the array.
3623 While the array remains a stream buffer, the stream I/O functions will
3624 use the buffer for their internal purposes. You shouldn't try to access
3625 the values in the array directly while the stream is using it for
3628 The @code{setvbuf} function returns zero on success, or a nonzero value
3629 if the value of @var{mode} is not valid or if the request could not
3635 @deftypevr Macro int _IOFBF
3636 The value of this macro is an integer constant expression that can be
3637 used as the @var{mode} argument to the @code{setvbuf} function to
3638 specify that the stream should be fully buffered.
3643 @deftypevr Macro int _IOLBF
3644 The value of this macro is an integer constant expression that can be
3645 used as the @var{mode} argument to the @code{setvbuf} function to
3646 specify that the stream should be line buffered.
3651 @deftypevr Macro int _IONBF
3652 The value of this macro is an integer constant expression that can be
3653 used as the @var{mode} argument to the @code{setvbuf} function to
3654 specify that the stream should be unbuffered.
3659 @deftypevr Macro int BUFSIZ
3660 The value of this macro is an integer constant expression that is good
3661 to use for the @var{size} argument to @code{setvbuf}. This value is
3662 guaranteed to be at least @code{256}.
3664 The value of @code{BUFSIZ} is chosen on each system so as to make stream
3665 I/O efficient. So it is a good idea to use @code{BUFSIZ} as the size
3666 for the buffer when you call @code{setvbuf}.
3668 Actually, you can get an even better value to use for the buffer size
3669 by means of the @code{fstat} system call: it is found in the
3670 @code{st_blksize} field of the file attributes. @xref{Attribute Meanings}.
3672 Sometimes people also use @code{BUFSIZ} as the allocation size of
3673 buffers used for related purposes, such as strings used to receive a
3674 line of input with @code{fgets} (@pxref{Character Input}). There is no
3675 particular reason to use @code{BUFSIZ} for this instead of any other
3676 integer, except that it might lead to doing I/O in chunks of an
3682 @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
3683 If @var{buf} is a null pointer, the effect of this function is
3684 equivalent to calling @code{setvbuf} with a @var{mode} argument of
3685 @code{_IONBF}. Otherwise, it is equivalent to calling @code{setvbuf}
3686 with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size}
3687 argument of @code{BUFSIZ}.
3689 The @code{setbuf} function is provided for compatibility with old code;
3690 use @code{setvbuf} in all new programs.
3695 @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
3696 If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
3697 Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
3698 buffer. The @var{size} argument specifies the length of @var{buf}.
3700 This function is provided for compatibility with old BSD code. Use
3701 @code{setvbuf} instead.
3706 @deftypefun void setlinebuf (FILE *@var{stream})
3707 This function makes @var{stream} be line buffered, and allocates the
3710 This function is provided for compatibility with old BSD code. Use
3711 @code{setvbuf} instead.
3714 @node Other Kinds of Streams
3715 @section Other Kinds of Streams
3717 The GNU library provides ways for you to define additional kinds of
3718 streams that do not necessarily correspond to an open file.
3720 One such type of stream takes input from or writes output to a string.
3721 These kinds of streams are used internally to implement the
3722 @code{sprintf} and @code{sscanf} functions. You can also create such a
3723 stream explicitly, using the functions described in @ref{String Streams}.
3725 More generally, you can define streams that do input/output to arbitrary
3726 objects using functions supplied by your program. This protocol is
3727 discussed in @ref{Custom Streams}.
3729 @strong{Portability Note:} The facilities described in this section are
3730 specific to GNU. Other systems or C implementations might or might not
3731 provide equivalent functionality.
3734 * String Streams:: Streams that get data from or put data in
3735 a string or memory buffer.
3736 * Obstack Streams:: Streams that store data in an obstack.
3737 * Custom Streams:: Defining your own streams with an arbitrary
3738 input data source and/or output data sink.
3741 @node String Streams
3742 @subsection String Streams
3744 @cindex stream, for I/O to a string
3745 @cindex string stream
3746 The @code{fmemopen} and @code{open_memstream} functions allow you to do
3747 I/O to a string or memory buffer. These facilities are declared in
3753 @deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
3754 This function opens a stream that allows the access specified by the
3755 @var{opentype} argument, that reads from or writes to the buffer specified
3756 by the argument @var{buf}. This array must be at least @var{size} bytes long.
3758 If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
3759 dynamically allocates (as with @code{malloc}; @pxref{Unconstrained
3760 Allocation}) an array @var{size} bytes long. This is really only useful
3761 if you are going to write things to the buffer and then read them back
3762 in again, because you have no way of actually getting a pointer to the
3763 buffer (for this, try @code{open_memstream}, below). The buffer is
3764 freed when the stream is open.
3766 The argument @var{opentype} is the same as in @code{fopen}
3767 (@pxref{Opening Streams}). If the @var{opentype} specifies
3768 append mode, then the initial file position is set to the first null
3769 character in the buffer. Otherwise the initial file position is at the
3770 beginning of the buffer.
3772 When a stream open for writing is flushed or closed, a null character
3773 (zero byte) is written at the end of the buffer if it fits. You
3774 should add an extra byte to the @var{size} argument to account for this.
3775 Attempts to write more than @var{size} bytes to the buffer result
3778 For a stream open for reading, null characters (zero bytes) in the
3779 buffer do not count as ``end of file''. Read operations indicate end of
3780 file only when the file position advances past @var{size} bytes. So, if
3781 you want to read characters from a null-terminated string, you should
3782 supply the length of the string as the @var{size} argument.
3785 Here is an example of using @code{fmemopen} to create a stream for
3786 reading from a string:
3789 @include memopen.c.texi
3792 This program produces the following output:
3805 @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
3806 This function opens a stream for writing to a buffer. The buffer is
3807 allocated dynamically (as with @code{malloc}; @pxref{Unconstrained
3808 Allocation}) and grown as necessary.
3810 When the stream is closed with @code{fclose} or flushed with
3811 @code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
3812 contain the pointer to the buffer and its size. The values thus stored
3813 remain valid only as long as no further output on the stream takes
3814 place. If you do more output, you must flush the stream again to store
3815 new values before you use them again.
3817 A null character is written at the end of the buffer. This null character
3818 is @emph{not} included in the size value stored at @var{sizeloc}.
3820 You can move the stream's file position with @code{fseek} or
3821 @code{fseeko} (@pxref{File Positioning}). Moving the file position past
3822 the end of the data already written fills the intervening space with
3826 Here is an example of using @code{open_memstream}:
3829 @include memstrm.c.texi
3832 This program produces the following output:
3835 buf = `hello', size = 5
3836 buf = `hello, world', size = 12
3839 @c @group Invalid outside @example.
3840 @node Obstack Streams
3841 @subsection Obstack Streams
3843 You can open an output stream that puts it data in an obstack.
3848 @deftypefun {FILE *} open_obstack_stream (struct obstack *@var{obstack})
3849 This function opens a stream for writing data into the obstack @var{obstack}.
3850 This starts an object in the obstack and makes it grow as data is
3851 written (@pxref{Growing Objects}).
3852 @c @end group Doubly invalid because not nested right.
3854 Calling @code{fflush} on this stream updates the current size of the
3855 object to match the amount of data that has been written. After a call
3856 to @code{fflush}, you can examine the object temporarily.
3858 You can move the file position of an obstack stream with @code{fseek} or
3859 @code{fseeko} (@pxref{File Positioning}). Moving the file position past
3860 the end of the data written fills the intervening space with zeros.
3862 To make the object permanent, update the obstack with @code{fflush}, and
3863 then use @code{obstack_finish} to finalize the object and get its address.
3864 The following write to the stream starts a new object in the obstack,
3865 and later writes add to that object until you do another @code{fflush}
3866 and @code{obstack_finish}.
3868 But how do you find out how long the object is? You can get the length
3869 in bytes by calling @code{obstack_object_size} (@pxref{Status of an
3870 Obstack}), or you can null-terminate the object like this:
3873 obstack_1grow (@var{obstack}, 0);
3876 Whichever one you do, you must do it @emph{before} calling
3877 @code{obstack_finish}. (You can do both if you wish.)
3880 Here is a sample function that uses @code{open_obstack_stream}:
3884 make_message_string (const char *a, int b)
3886 FILE *stream = open_obstack_stream (&message_obstack);
3887 output_task (stream);
3888 fprintf (stream, ": ");
3889 fprintf (stream, a, b);
3890 fprintf (stream, "\n");
3892 obstack_1grow (&message_obstack, 0);
3893 return obstack_finish (&message_obstack);
3897 @node Custom Streams
3898 @subsection Programming Your Own Custom Streams
3899 @cindex custom streams
3900 @cindex programming your own streams
3902 This section describes how you can make a stream that gets input from an
3903 arbitrary data source or writes output to an arbitrary data sink
3904 programmed by you. We call these @dfn{custom streams}.
3906 @c !!! this does not talk at all about the higher-level hooks
3909 * Streams and Cookies:: The @dfn{cookie} records where to fetch or
3910 store data that is read or written.
3911 * Hook Functions:: How you should define the four @dfn{hook
3912 functions} that a custom stream needs.
3915 @node Streams and Cookies
3916 @subsubsection Custom Streams and Cookies
3917 @cindex cookie, for custom stream
3919 Inside every custom stream is a special object called the @dfn{cookie}.
3920 This is an object supplied by you which records where to fetch or store
3921 the data read or written. It is up to you to define a data type to use
3922 for the cookie. The stream functions in the library never refer
3923 directly to its contents, and they don't even know what the type is;
3924 they record its address with type @code{void *}.
3926 To implement a custom stream, you must specify @emph{how} to fetch or
3927 store the data in the specified place. You do this by defining
3928 @dfn{hook functions} to read, write, change ``file position'', and close
3929 the stream. All four of these functions will be passed the stream's
3930 cookie so they can tell where to fetch or store the data. The library
3931 functions don't know what's inside the cookie, but your functions will
3934 When you create a custom stream, you must specify the cookie pointer,
3935 and also the four hook functions stored in a structure of type
3936 @code{cookie_io_functions_t}.
3938 These facilities are declared in @file{stdio.h}.
3943 @deftp {Data Type} {cookie_io_functions_t}
3944 This is a structure type that holds the functions that define the
3945 communications protocol between the stream and its cookie. It has
3946 the following members:
3949 @item cookie_read_function_t *read
3950 This is the function that reads data from the cookie. If the value is a
3951 null pointer instead of a function, then read operations on this stream
3952 always return @code{EOF}.
3954 @item cookie_write_function_t *write
3955 This is the function that writes data to the cookie. If the value is a
3956 null pointer instead of a function, then data written to the stream is
3959 @item cookie_seek_function_t *seek
3960 This is the function that performs the equivalent of file positioning on
3961 the cookie. If the value is a null pointer instead of a function, calls
3962 to @code{fseek} or @code{fseeko} on this stream can only seek to
3963 locations within the buffer; any attempt to seek outside the buffer will
3964 return an @code{ESPIPE} error.
3966 @item cookie_close_function_t *close
3967 This function performs any appropriate cleanup on the cookie when
3968 closing the stream. If the value is a null pointer instead of a
3969 function, nothing special is done to close the cookie when the stream is
3976 @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions})
3977 This function actually creates the stream for communicating with the
3978 @var{cookie} using the functions in the @var{io-functions} argument.
3979 The @var{opentype} argument is interpreted as for @code{fopen};
3980 see @ref{Opening Streams}. (But note that the ``truncate on
3981 open'' option is ignored.) The new stream is fully buffered.
3983 The @code{fopencookie} function returns the newly created stream, or a null
3984 pointer in case of an error.
3987 @node Hook Functions
3988 @subsubsection Custom Stream Hook Functions
3989 @cindex hook functions (of custom streams)
3991 Here are more details on how you should define the four hook functions
3992 that a custom stream needs.
3994 You should define the function to read data from the cookie as:
3997 ssize_t @var{reader} (void *@var{cookie}, void *@var{buffer}, size_t @var{size})
4000 This is very similar to the @code{read} function; see @ref{I/O
4001 Primitives}. Your function should transfer up to @var{size} bytes into
4002 the @var{buffer}, and return the number of bytes read, or zero to
4003 indicate end-of-file. You can return a value of @code{-1} to indicate
4006 You should define the function to write data to the cookie as:
4009 ssize_t @var{writer} (void *@var{cookie}, const void *@var{buffer}, size_t @var{size})
4012 This is very similar to the @code{write} function; see @ref{I/O
4013 Primitives}. Your function should transfer up to @var{size} bytes from
4014 the buffer, and return the number of bytes written. You can return a
4015 value of @code{-1} to indicate an error.
4017 You should define the function to perform seek operations on the cookie
4021 int @var{seeker} (void *@var{cookie}, fpos_t *@var{position}, int @var{whence})
4024 For this function, the @var{position} and @var{whence} arguments are
4025 interpreted as for @code{fgetpos}; see @ref{Portable Positioning}. In
4026 the GNU library, @code{fpos_t} is equivalent to @code{off_t} or
4027 @code{long int}, and simply represents the number of bytes from the
4028 beginning of the file.
4030 After doing the seek operation, your function should store the resulting
4031 file position relative to the beginning of the file in @var{position}.
4032 Your function should return a value of @code{0} on success and @code{-1}
4033 to indicate an error.
4035 You should define the function to do cleanup operations on the cookie
4036 appropriate for closing the stream as:
4039 int @var{cleaner} (void *@var{cookie})
4042 Your function should return @code{-1} to indicate an error, and @code{0}
4047 @deftp {Data Type} cookie_read_function
4048 This is the data type that the read function for a custom stream should have.
4049 If you declare the function as shown above, this is the type it will have.
4054 @deftp {Data Type} cookie_write_function
4055 The data type of the write function for a custom stream.
4060 @deftp {Data Type} cookie_seek_function
4061 The data type of the seek function for a custom stream.
4066 @deftp {Data Type} cookie_close_function
4067 The data type of the close function for a custom stream.
4074 There is another set of functions one can give a stream, the
4075 input-room and output-room functions. These functions must
4076 understand stdio internals. To describe how to use these
4077 functions, you also need to document lots of how stdio works
4078 internally (which isn't relevant for other uses of stdio).
4079 Perhaps I can write an interface spec from which you can write
4080 good documentation. But it's pretty complex and deals with lots
4081 of nitty-gritty details. I think it might be better to let this
4082 wait until the rest of the manual is more done and polished.
4086 @c ??? This section could use an example.
4089 @node Formatted Messages
4090 @section Formatted Messages
4091 @cindex formatted messages
4093 On systems which are based on System V messages of programs (especially
4094 the system tools) are printed in a strict form using the @code{fmtmsg}
4095 function. The uniformity sometimes helps the user to interpret messages
4096 and the strictness tests of the @code{fmtmsg} function ensure that the
4097 programmer follows some minimal requirements.
4100 * Printing Formatted Messages:: The @code{fmtmsg} function.
4101 * Adding Severity Classes:: Add more severity classes.
4102 * Example:: How to use @code{fmtmsg} and @code{addseverity}.
4106 @node Printing Formatted Messages
4107 @subsection Printing Formatted Messages
4109 Messages can be printed to standard error and/or to the console. To
4110 select the destination the programmer can use the following two values,
4111 bitwise OR combined if wanted, for the @var{classification} parameter of
4116 Display the message in standard error.
4118 Display the message on the system console.
4121 The erroneous piece of the system can be signalled by exactly one of the
4122 following values which also is bitwise ORed with the
4123 @var{classification} parameter to @code{fmtmsg}:
4127 The source of the condition is some hardware.
4129 The source of the condition is some software.
4131 The source of the condition is some firmware.
4134 A third component of the @var{classification} parameter to @code{fmtmsg}
4135 can describe the part of the system which detects the problem. This is
4136 done by using exactly one of the following values:
4140 The erroneous condition is detected by the application.
4142 The erroneous condition is detected by a utility.
4144 The erroneous condition is detected by the operating system.
4147 A last component of @var{classification} can signal the results of this
4148 message. Exactly one of the following values can be used:
4152 It is a recoverable error.
4154 It is a non-recoverable error.
4159 @deftypefun int fmtmsg (long int @var{classification}, const char *@var{label}, int @var{severity}, const char *@var{text}, const char *@var{action}, const char *@var{tag})
4160 Display a message described by its parameters on the device(s) specified
4161 in the @var{classification} parameter. The @var{label} parameter
4162 identifies the source of the message. The string should consist of two
4163 colon separated parts where the first part has not more than 10 and the
4164 second part not more the 14 characters. The @var{text} parameter
4165 describes the condition of the error, the @var{action} parameter possible
4166 steps to recover from the error and the @var{tag} parameter is a
4167 reference to the online documentation where more information can be
4168 found. It should contain the @var{label} value and a unique
4169 identification number.
4171 Each of the parameters can be a special value which means this value
4172 is to be omitted. The symbolic names for these values are:
4176 Ignore @var{label} parameter.
4178 Ignore @var{severity} parameter.
4180 Ignore @var{classification} parameter. This implies that nothing is
4183 Ignore @var{text} parameter.
4185 Ignore @var{action} parameter.
4187 Ignore @var{tag} parameter.
4190 There is another way certain fields can be omitted from the output to
4191 standard error. This is described below in the description of
4192 environment variables influencing the behaviour.
4194 The @var{severity} parameter can have one of the values in the following
4196 @cindex severity class
4200 Nothing is printed, this value is the same as @code{MM_NULLSEV}.
4202 This value is printed as @code{HALT}.
4204 This value is printed as @code{ERROR}.
4206 This value is printed as @code{WARNING}.
4208 This value is printed as @code{INFO}.
4211 The numeric value of these five macros are between @code{0} and
4212 @code{4}. Using the environment variable @code{SEV_LEVEL} or using the
4213 @code{addseverity} function one can add more severity levels with their
4214 corresponding string to print. This is described below
4215 (@pxref{Adding Severity Classes}).
4218 If no parameter is ignored the output looks like this:
4221 @var{label}: @var{severity-string}: @var{text}
4222 TO FIX: @var{action} @var{tag}
4225 The colons, new line characters and the @code{TO FIX} string are
4226 inserted if necessary, i.e., if the corresponding parameter is not
4229 This function is specified in the X/Open Portability Guide. It is also
4230 available on all system derived from System V.
4232 The function returns the value @code{MM_OK} if no error occurred. If
4233 only the printing to standard error failed, it returns @code{MM_NOMSG}.
4234 If printing to the console fails, it returns @code{MM_NOCON}. If
4235 nothing is printed @code{MM_NOTOK} is returned. Among situations where
4236 all outputs fail this last value is also returned if a parameter value
4240 There are two environment variables which influence the behaviour of
4241 @code{fmtmsg}. The first is @code{MSGVERB}. It is used to control the
4242 output actually happening on standard error (@emph{not} the console
4243 output). Each of the five fields can explicitely be enabled. To do
4244 this the user has to put the @code{MSGVERB} variable with a format like
4245 the following in the environment before calling the @code{fmtmsg} function
4249 MSGVERB=@var{keyword}[:@var{keyword}[:...]]
4252 Valid @var{keyword}s are @code{label}, @code{severity}, @code{text},
4253 @code{action}, and @code{tag}. If the environment variable is not given
4254 or is the empty string, a not supported keyword is given or the value is
4255 somehow else invalid, no part of the message is masked out.
4257 The second environment variable which influences the behaviour of
4258 @code{fmtmsg} is @code{SEV_LEVEL}. This variable and the change in the
4259 behaviour of @code{fmtmsg} is not specified in the X/Open Portability
4260 Guide. It is available in System V systems, though. It can be used to
4261 introduce new severity levels. By default, only the five severity levels
4262 described above are available. Any other numeric value would make
4263 @code{fmtmsg} print nothing.
4265 If the user puts @code{SEV_LEVEL} with a format like
4268 SEV_LEVEL=[@var{description}[:@var{description}[:...]]]
4272 in the environment of the process before the first call to
4273 @code{fmtmsg}, where @var{description} has a value of the form
4276 @var{severity-keyword},@var{level},@var{printstring}
4279 The @var{severity-keyword} part is not used by @code{fmtmsg} but it has
4280 to be present. The @var{level} part is a string representation of a
4281 number. The numeric value must be a number greater than 4. This value
4282 must be used in the @var{severity} parameter of @code{fmtmsg} to select
4283 this class. It is not possible to overwrite any of the predefined
4284 classes. The @var{printstring} is the string printed when a message of
4285 this class is processed by @code{fmtmsg} (see above, @code{fmtsmg} does
4286 not print the numeric value but instead the string representation).
4289 @node Adding Severity Classes
4290 @subsection Adding Severity Classes
4291 @cindex severity class
4293 There is another possibility to introduce severity classes beside using
4294 the environment variable @code{SEV_LEVEL}. This simplifies the task of
4295 introducing new classes in a running program. One could use the
4296 @code{setenv} or @code{putenv} function to set the environment variable,
4297 but this is toilsome.
4299 @deftypefun int addseverity (int @var{severity}, const char *@var{string})
4300 This function allows to introduce new severity classes which can be
4301 addressed by the @var{severity} parameter of the @code{fmtmsg} function.
4302 The @var{severity} parameter of @code{addseverity} must match the value
4303 for the parameter with the same name of @code{fmtmsg} and @var{string}
4304 is the string printed in the actual messages instead of the numeric
4307 If @var{string} is @code{NULL} the severity class with the numeric value
4308 according to @var{severity} is removed.
4310 It is not possible to overwrite or remove one of the default severity
4311 classes. All calls to @code{addseverity} with @var{severity} set to one
4312 of the values for the default classes will fail.
4314 The return value is @code{MM_OK} if the task was successfully performed.
4315 If the return value is @code{MM_NOTOK} something went wrong. This could
4316 mean that no more memory is available or a class is not available when
4317 it has to be removed.
4319 This function is not specified in the X/Open Portability Guide although
4320 the @code{fmtsmg} function is. It is available on System V systems.
4325 @subsection How to use @code{fmtmsg} and @code{addseverity}
4327 Here is a simple example program to illustrate the use of the both
4328 functions described in this section.
4331 @include fmtmsgexpl.c.texi
4334 The second call to @code{fmtmsg} illustrates a use of this function how
4335 it usually happens on System V systems which heavily use this function.
4336 It might be worth a thought to follow the scheme used in System V
4337 systems so we give a short explanation here. The value of the
4338 @var{label} field (@code{UX:cat}) says that the error occured in the
4339 Unix program @code{cat}. The explanation of the error follows and the
4340 value for the @var{action} parameter is @code{"refer to manual"}. One
4341 could me more specific here, if needed. The @var{tag} field contains,
4342 as proposed above, the value of the string given for the @var{label}
4343 parameter, and additionally a unique ID (@code{001} in this case). For
4344 a GNU environment this string could contain a reference to the
4345 corresponding node in the Info page for the program.
4348 Running this program without specifying the @code{MSGVERB} and
4349 @code{SEV_LEVEL} function produces the following output:
4352 UX:cat: NOTE2: invalid syntax
4353 TO FIX: refer to manual UX:cat:001
4356 We see the different fields of the message and how the extra glue (the
4357 colons and the @code{TO FIX} string) are printed. But only one of the
4358 three calls to @code{fmtmsg} produced output. The first call does not
4359 print anything because the @var{label} parameter is not in the correct
4360 form. The string must contain two fields, separated by a colon
4361 (@pxref{Printing Formatted Messages}). The third @code{fmtmsg} call
4362 produced no output since the class with the numeric value @code{6} is
4363 not defined. Although a class with numeric value @code{5} is also not
4364 defined by default, the call the @code{addseverity} introduces it and
4365 the second call to @code{fmtmsg} produces the above output.
4367 When we change the environment of the program to contain
4368 @code{SEV_LEVEL=XXX,6,NOTE} when running it we get a different result:
4371 UX:cat: NOTE2: invalid syntax
4372 TO FIX: refer to manual UX:cat:001
4373 label:foo: NOTE: text
4377 Now the third call the @code{fmtmsg} produced some output and we see how
4378 the string @code{NOTE} from the environment variable appears in the
4381 Now we can reduce the output by specifying in which fields we are
4382 interested in. If we additionally set the environment variable
4383 @code{MSGVERB} to the value @code{severity:label:action} we get the
4388 TO FIX: refer to manual
4394 I.e., the output produced by the @var{text} and the @var{tag} parameters
4395 to @code{fmtmsg} vanished. Please also note that now there is no colon
4396 after the @code{NOTE} and @code{NOTE2} strings in the output. This is
4397 not necessary since there is no more output on this line since the text