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 * Streams and Threads:: Issues with streams in threaded programs.
21 * Streams and I18N:: Streams in internationalized applications.
22 * Simple Output:: Unformatted output by characters and lines.
23 * Character Input:: Unformatted input by characters and words.
24 * Line Input:: Reading a line or a record from a stream.
25 * Unreading:: Peeking ahead/pushing back input just read.
26 * Block Input/Output:: Input and output operations on blocks of data.
27 * Formatted Output:: @code{printf} and related functions.
28 * Customizing Printf:: You can define new conversion specifiers for
29 @code{printf} and friends.
30 * Formatted Input:: @code{scanf} and related functions.
31 * EOF and Errors:: How you can tell if an I/O error happens.
32 * Error Recovery:: What you can do about errors.
33 * Binary Streams:: Some systems distinguish between text files
35 * File Positioning:: About random-access streams.
36 * Portable Positioning:: Random access on peculiar ISO C systems.
37 * Stream Buffering:: How to control buffering of streams.
38 * Other Kinds of Streams:: Streams that do not necessarily correspond
40 * Formatted Messages:: Print strictly formatted messages.
46 For historical reasons, the type of the C data structure that represents
47 a stream is called @code{FILE} rather than ``stream''. Since most of
48 the library functions deal with objects of type @code{FILE *}, sometimes
49 the term @dfn{file pointer} is also used to mean ``stream''. This leads
50 to unfortunate confusion over terminology in many books on C. This
51 manual, however, is careful to use the terms ``file'' and ``stream''
52 only in the technical sense.
56 The @code{FILE} type is declared in the header file @file{stdio.h}.
60 @deftp {Data Type} FILE
61 This is the data type used to represent stream objects. A @code{FILE}
62 object holds all of the internal state information about the connection
63 to the associated file, including such things as the file position
64 indicator and buffering information. Each stream also has error and
65 end-of-file status indicators that can be tested with the @code{ferror}
66 and @code{feof} functions; see @ref{EOF and Errors}.
69 @code{FILE} objects are allocated and managed internally by the
70 input/output library functions. Don't try to create your own objects of
71 type @code{FILE}; let the library do it. Your programs should
72 deal only with pointers to these objects (that is, @code{FILE *} values)
73 rather than the objects themselves.
74 @c !!! should say that FILE's have "No user-serviceable parts inside."
76 @node Standard Streams
77 @section Standard Streams
78 @cindex standard streams
79 @cindex streams, standard
81 When the @code{main} function of your program is invoked, it already has
82 three predefined streams open and available for use. These represent
83 the ``standard'' input and output channels that have been established
86 These streams are declared in the header file @file{stdio.h}.
91 @deftypevar {FILE *} stdin
92 The @dfn{standard input} stream, which is the normal source of input for the
95 @cindex standard input stream
99 @deftypevar {FILE *} stdout
100 The @dfn{standard output} stream, which is used for normal output from
103 @cindex standard output stream
107 @deftypevar {FILE *} stderr
108 The @dfn{standard error} stream, which is used for error messages and
109 diagnostics issued by the program.
111 @cindex standard error stream
113 In the GNU system, you can specify what files or processes correspond to
114 these streams using the pipe and redirection facilities provided by the
115 shell. (The primitives shells use to implement these facilities are
116 described in @ref{File System Interface}.) Most other operating systems
117 provide similar mechanisms, but the details of how to use them can vary.
119 In the GNU C library, @code{stdin}, @code{stdout}, and @code{stderr} are
120 normal variables which you can set just like any others. For example,
121 to redirect the standard output to a file, you could do:
125 stdout = fopen ("standard-output-file", "w");
128 Note however, that in other systems @code{stdin}, @code{stdout}, and
129 @code{stderr} are macros that you cannot assign to in the normal way.
130 But you can use @code{freopen} to get the effect of closing one and
131 reopening it. @xref{Opening Streams}.
133 The three streams @code{stdin}, @code{stdout}, and @code{stderr} are not
134 unoriented at program start (@pxref{Streams and I18N}).
136 @node Opening Streams
137 @section Opening Streams
139 @cindex opening a stream
140 Opening a file with the @code{fopen} function creates a new stream and
141 establishes a connection between the stream and a file. This may
142 involve creating a new file.
145 Everything described in this section is declared in the header file
150 @deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype})
151 The @code{fopen} function opens a stream for I/O to the file
152 @var{filename}, and returns a pointer to the stream.
154 The @var{opentype} argument is a string that controls how the file is
155 opened and specifies attributes of the resulting stream. It must begin
156 with one of the following sequences of characters:
160 Open an existing file for reading only.
163 Open the file for writing only. If the file already exists, it is
164 truncated to zero length. Otherwise a new file is created.
167 Open a file for append access; that is, writing at the end of file only.
168 If the file already exists, its initial contents are unchanged and
169 output to the stream is appended to the end of the file.
170 Otherwise, a new, empty file is created.
173 Open an existing file for both reading and writing. The initial contents
174 of the file are unchanged and the initial file position is at the
175 beginning of the file.
178 Open a file for both reading and writing. If the file already exists, it
179 is truncated to zero length. Otherwise, a new file is created.
182 Open or create file for both reading and appending. If the file exists,
183 its initial contents are unchanged. Otherwise, a new file is created.
184 The initial file position for reading is at the beginning of the file,
185 but output is always appended to the end of the file.
188 As you can see, @samp{+} requests a stream that can do both input and
189 output. When using such a stream, you must call @code{fflush}
190 (@pxref{Stream Buffering}) or a file positioning function such as
191 @code{fseek} (@pxref{File Positioning}) when switching from reading
192 to writing or vice versa. Otherwise, internal buffers might not be
195 Additional characters may appear after these to specify flags for the
196 call. Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is
197 the only part you are guaranteed will be understood by all systems.
199 The GNU C library defines one additional character for use in
200 @var{opentype}: the character @samp{x} insists on creating a new
201 file---if a file @var{filename} already exists, @code{fopen} fails
202 rather than opening it. If you use @samp{x} you are guaranteed that
203 you will not clobber an existing file. This is equivalent to the
204 @code{O_EXCL} option to the @code{open} function (@pxref{Opening and
207 The character @samp{b} in @var{opentype} has a standard meaning; it
208 requests a binary stream rather than a text stream. But this makes no
209 difference in POSIX systems (including the GNU system). If both
210 @samp{+} and @samp{b} are specified, they can appear in either order.
211 @xref{Binary Streams}.
213 @cindex stream orientation
214 @cindex orientation, stream
215 If the @var{opentype} string contains the sequence
216 @code{,ccs=@var{STRING}} then @var{STRING} is taken as the name of a
217 coded character set and @code{fopen} will mark the stream as
218 wide-oriented which appropriate conversion functions in place to convert
219 from and to the character set @var{STRING} is place. Any other stream
220 is opened initially unoriented and the orientation is decided with the
221 first file operation. If the first operation is a wide character
222 operation, the stream is not only marked as wide-oriented, also the
223 conversion functions to convert to the coded character set used for the
224 current locale are loaded. This will not change anymore from this point
225 on even if the locale selected for the @code{LC_CTYPE} category is
228 Any other characters in @var{opentype} are simply ignored. They may be
229 meaningful in other systems.
231 If the open fails, @code{fopen} returns a null pointer.
233 When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
234 32 bit machine this function is in fact @code{fopen64} since the LFS
235 interface replaces transparently the old interface.
238 You can have multiple streams (or file descriptors) pointing to the same
239 file open at the same time. If you do only input, this works
240 straightforwardly, but you must be careful if any output streams are
241 included. @xref{Stream/Descriptor Precautions}. This is equally true
242 whether the streams are in one program (not usual) or in several
243 programs (which can easily happen). It may be advantageous to use the
244 file locking facilities to avoid simultaneous access. @xref{File
249 @deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype})
250 This function is similar to @code{fopen} but the stream it returns a
251 pointer for is opened using @code{open64}. Therefore this stream can be
252 used even on files larger then @math{2^31} bytes on 32 bit machines.
254 Please note that the return type is still @code{FILE *}. There is no
255 special @code{FILE} type for the LFS interface.
257 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
258 bits machine this function is available under the name @code{fopen}
259 and so transparently replaces the old interface.
264 @deftypevr Macro int FOPEN_MAX
265 The value of this macro is an integer constant expression that
266 represents the minimum number of streams that the implementation
267 guarantees can be open simultaneously. You might be able to open more
268 than this many streams, but that is not guaranteed. The value of this
269 constant is at least eight, which includes the three standard streams
270 @code{stdin}, @code{stdout}, and @code{stderr}. In POSIX.1 systems this
271 value is determined by the @code{OPEN_MAX} parameter; @pxref{General
272 Limits}. In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE}
273 resource limit; @pxref{Limits on Resources}.
278 @deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
279 This function is like a combination of @code{fclose} and @code{fopen}.
280 It first closes the stream referred to by @var{stream}, ignoring any
281 errors that are detected in the process. (Because errors are ignored,
282 you should not use @code{freopen} on an output stream if you have
283 actually done any output using the stream.) Then the file named by
284 @var{filename} is opened with mode @var{opentype} as for @code{fopen},
285 and associated with the same stream object @var{stream}.
287 If the operation fails, a null pointer is returned; otherwise,
288 @code{freopen} returns @var{stream}.
290 @code{freopen} has traditionally been used to connect a standard stream
291 such as @code{stdin} with a file of your own choice. This is useful in
292 programs in which use of a standard stream for certain purposes is
293 hard-coded. In the GNU C library, you can simply close the standard
294 streams and open new ones with @code{fopen}. But other systems lack
295 this ability, so using @code{freopen} is more portable.
297 When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
298 32 bit machine this function is in fact @code{freopen64} since the LFS
299 interface replaces transparently the old interface.
304 @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
305 This function is similar to @code{freopen}. The only difference is that
306 on 32 bit machine the stream returned is able to read beyond the
307 @math{2^31} bytes limits imposed by the normal interface. It should be
308 noted that the stream pointed to by @var{stream} need not be opened
309 using @code{fopen64} or @code{freopen64} since its mode is not important
312 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
313 bits machine this function is available under the name @code{freopen}
314 and so transparently replaces the old interface.
317 In some situations it is useful to know whether a given stream is
318 available for reading or writing. This information is normally not
319 available and would have to be remembered separately. Solaris
320 introduced a few functions to get this information from the stream
321 descriptor and these functions are also available in the GNU C library.
325 @deftypefun int __freadable (FILE *@var{stream})
326 The @code{__freadable} function determines whether the stream
327 @var{stream} was opened to allow reading. In this case the return value
328 is nonzero. For write-only streams the function returns zero.
330 This function is declared in @file{stdio_ext.h}.
335 @deftypefun int __fwritable (FILE *@var{stream})
336 The @code{__fwritable} function determines whether the stream
337 @var{stream} was opened to allow writing. In this case the return value
338 is nonzero. For read-only streams the function returns zero.
340 This function is declared in @file{stdio_ext.h}.
343 For slightly different kind of problems there are two more functions.
344 They provide even finer-grained information.
348 @deftypefun int __freading (FILE *@var{stream})
349 The @code{__freading} function determines whether the stream
350 @var{stream} was last read from or whether it is opened read-only. In
351 this case the return value is nonzero, otherwise it is zero.
352 Determining whether a stream opened for reading and writing was last
353 used for writing allows to draw conclusions about the content about the
354 buffer, among other things.
356 This function is declared in @file{stdio_ext.h}.
361 @deftypefun int __fwriting (FILE *@var{stream})
362 The @code{__fwriting} function determines whether the stream
363 @var{stream} was last written to or whether it is opened write-only. In
364 this case the return value is nonzero, otherwise it is zero.
366 This function is declared in @file{stdio_ext.h}.
370 @node Closing Streams
371 @section Closing Streams
373 @cindex closing a stream
374 When a stream is closed with @code{fclose}, the connection between the
375 stream and the file is canceled. After you have closed a stream, you
376 cannot perform any additional operations on it.
380 @deftypefun int fclose (FILE *@var{stream})
381 This function causes @var{stream} to be closed and the connection to
382 the corresponding file to be broken. Any buffered output is written
383 and any buffered input is discarded. The @code{fclose} function returns
384 a value of @code{0} if the file was closed successfully, and @code{EOF}
385 if an error was detected.
387 It is important to check for errors when you call @code{fclose} to close
388 an output stream, because real, everyday errors can be detected at this
389 time. For example, when @code{fclose} writes the remaining buffered
390 output, it might get an error because the disk is full. Even if you
391 know the buffer is empty, errors can still occur when closing a file if
394 The function @code{fclose} is declared in @file{stdio.h}.
397 To close all streams currently available the GNU C Library provides
402 @deftypefun int fcloseall (void)
403 This function causes all open streams of the process to be closed and
404 the connection to corresponding files to be broken. All buffered data
405 is written and any buffered input is discarded. The @code{fcloseall}
406 function returns a value of @code{0} if all the files were closed
407 successfully, and @code{EOF} if an error was detected.
409 This function should be used only in special situations, e.g., when an
410 error occurred and the program must be aborted. Normally each single
411 stream should be closed separately so that problems with individual
412 streams can be identified. It is also problematic since the standard
413 streams (@pxref{Standard Streams}) will also be closed.
415 The function @code{fcloseall} is declared in @file{stdio.h}.
418 If the @code{main} function to your program returns, or if you call the
419 @code{exit} function (@pxref{Normal Termination}), all open streams are
420 automatically closed properly. If your program terminates in any other
421 manner, such as by calling the @code{abort} function (@pxref{Aborting a
422 Program}) or from a fatal signal (@pxref{Signal Handling}), open streams
423 might not be closed properly. Buffered output might not be flushed and
424 files may be incomplete. For more information on buffering of streams,
425 see @ref{Stream Buffering}.
427 @node Streams and Threads
428 @section Streams and Threads
431 @cindex multi-threaded application
432 Streams can be used in multi-threaded applications in the same way they
433 are used in single-threaded applications. But the programmer must be
434 aware of the possible complications. It is important to know about
435 these also if the program one writes never use threads since the design
436 and implementation of many stream functions is heavily influenced by the
437 requirements added by multi-threaded programming.
439 The POSIX standard requires that by default the stream operations are
440 atomic. I.e., issuing two stream operations for the same stream in two
441 threads at the same time will cause the operations to be executed as if
442 they were issued sequentially. The buffer operations performed while
443 reading or writing are protected from other uses of the same stream. To
444 do this each stream has an internal lock object which has to be
445 (implicitly) acquired before any work can be done.
447 But there are situations where this is not enough and there are also
448 situations where this is not wanted. The implicit locking is not enough
449 if the program requires more than one stream function call to happen
450 atomically. One example would be if an output line a program wants to
451 generate is created by several function calls. The functions by
452 themselves would ensure only atomicity of their own operation, but not
453 atomicity over all the function calls. For this it is necessary to
454 perform the stream locking in the application code.
458 @deftypefun void flockfile (FILE *@var{stream})
459 The @code{flockfile} function acquires the internal locking object
460 associated with the stream @var{stream}. This ensures that no other
461 thread can explicitly through @code{flockfile}/@code{ftrylockfile} or
462 implicit through a call of a stream function lock the stream. The
463 thread will block until the lock is acquired. An explicit call to
464 @code{funlockfile} has to be used to release the lock.
469 @deftypefun int ftrylockfile (FILE *@var{stream})
470 The @code{ftrylockfile} function tries to acquire the internal locking
471 object associated with the stream @var{stream} just like
472 @code{flockfile}. But unlike @code{flockfile} this function does not
473 block if the lock is not available. @code{ftrylockfile} returns zero if
474 the lock was successfully acquired. Otherwise the stream is locked by
480 @deftypefun void funlockfile (FILE *@var{stream})
481 The @code{funlockfile} function releases the internal locking object of
482 the stream @var{stream}. The stream must have been locked before by a
483 call to @code{flockfile} or a successful call of @code{ftrylockfile}.
484 The implicit locking performed by the stream operations do not count.
485 The @code{funlockfile} function does not return an error status and the
486 behavior of a call for a stream which is not locked by the current
490 The following example shows how the functions above can be used to
491 generate an output line atomically even in multi-threaded applications
492 (yes, the same job could be done with one @code{fprintf} call but it is
493 sometimes not possible):
500 fputs ("This is test number ", fp);
501 fprintf (fp, "%d\n", test);
506 Without the explicit locking it would be possible for another thread to
507 use the stream @var{fp} after the @code{fputs} call return and before
508 @code{fprintf} was called with the result that the number does not
509 follow the word @samp{number}.
511 From this description it might already be clear that the locking objects
512 in streams are no simple mutexes. Since locking the same stream twice
513 in the same thread is allowed the locking objects must be equivalent to
514 recursive mutexes. These mutexes keep track of the owner and the number
515 of times the lock is acquired. The same number of @code{funlockfile}
516 calls by the same threads is necessary to unlock the stream completely.
524 fputs ("in foo\n", fp);
525 /* @r{This is very wrong!!!} */
530 It is important here that the @code{funlockfile} function is only called
531 if the @code{ftrylockfile} function succeeded in locking the stream. It
532 is therefore always wrong to ignore the result of @code{ftrylockfile}.
533 And it makes no sense since otherwise one would use @code{flockfile}.
534 The result of code like that above is that either @code{funlockfile}
535 tries to free a stream that hasn't been locked by the current thread or it
536 frees the stream prematurely. The code should look like this:
542 if (ftrylockfile (fp) == 0)
544 fputs ("in foo\n", fp);
550 Now that we covered why it is necessary to have these locking it is
551 necessary to talk about situations when locking is unwanted and what can
552 be done. The locking operations (explicit or implicit) don't come for
553 free. Even if a lock is not taken the cost is not zero. The operations
554 which have to be performed require memory operations that are safe in
555 multi-processor environments. With the many local caches involved in
556 such systems this is quite costly. So it is best to avoid the locking
557 completely if it is not needed -- because the code in question is never
558 used in a context where two or more threads may use a stream at a time.
559 This can be determined most of the time for application code; for
560 library code which can be used in many contexts one should default to be
561 conservative and use locking.
563 There are two basic mechanisms to avoid locking. The first is to use
564 the @code{_unlocked} variants of the stream operations. The POSIX
565 standard defines quite a few of those and the GNU library adds a few
566 more. These variants of the functions behave just like the functions
567 with the name without the suffix except that they do not lock the
568 stream. Using these functions is very desirable since they are
569 potentially much faster. This is not only because the locking
570 operation itself is avoided. More importantly, functions like
571 @code{putc} and @code{getc} are very simple and traditionally (before the
572 introduction of threads) were implemented as macros which are very fast
573 if the buffer is not empty. With the addition of locking requirements
574 these functions are no longer implemented as macros since they would
575 expand to too much code.
576 But these macros are still available with the same functionality under the new
577 names @code{putc_unlocked} and @code{getc_unlocked}. This possibly huge
578 difference of speed also suggests the use of the @code{_unlocked}
579 functions even if locking is required. The difference is that the
580 locking then has to be performed in the program:
584 foo (FILE *fp, char *buf)
588 putc_unlocked (*buf++, fp);
593 If in this example the @code{putc} function would be used and the
594 explicit locking would be missing the @code{putc} function would have to
595 acquire the lock in every call, potentially many times depending on when
596 the loop terminates. Writing it the way illustrated above allows the
597 @code{putc_unlocked} macro to be used which means no locking and direct
598 manipulation of the buffer of the stream.
600 A second way to avoid locking is by using a non-standard function which
601 was introduced in Solaris and is available in the GNU C library as well.
605 @deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type})
607 The @code{__fsetlocking} function can be used to select whether the
608 stream operations will implicitly acquire the locking object of the
609 stream @var{stream}. By default this is done but it can be disabled and
610 reinstated using this function. There are three values defined for the
611 @var{type} parameter.
614 @item FSETLOCKING_INTERNAL
615 The stream @code{stream} will from now on use the default internal
616 locking. Every stream operation with exception of the @code{_unlocked}
617 variants will implicitly lock the stream.
619 @item FSETLOCKING_BYCALLER
620 After the @code{__fsetlocking} function returns the user is responsible
621 for locking the stream. None of the stream operations will implicitly
622 do this anymore until the state is set back to
623 @code{FSETLOCKING_INTERNAL}.
625 @item FSETLOCKING_QUERY
626 @code{__fsetlocking} only queries the current locking state of the
627 stream. The return value will be @code{FSETLOCKING_INTERNAL} or
628 @code{FSETLOCKING_BYCALLER} depending on the state.
631 The return value of @code{__fsetlocking} is either
632 @code{FSETLOCKING_INTERNAL} or @code{FSETLOCKING_BYCALLER} depending on
633 the state of the stream before the call.
635 This function and the values for the @var{type} parameter are declared
636 in @file{stdio_ext.h}.
639 This function is especially useful when program code has to be used
640 which is written without knowledge about the @code{_unlocked} functions
641 (or if the programmer was too lazy to use them).
643 @node Streams and I18N
644 @section Streams in Internationalized Applications
646 @w{ISO C90} introduced the new type @code{wchar_t} to allow handling
647 larger character sets. What was missing was a possibility to output
648 strings of @code{wchar_t} directly. One had to convert them into
649 multibyte strings using @code{mbstowcs} (there was no @code{mbsrtowcs}
650 yet) and then use the normal stream functions. While this is doable it
651 is very cumbersome since performing the conversions is not trivial and
652 greatly increases program complexity and size.
654 The Unix standard early on (I think in XPG4.2) introduced two additional
655 format specifiers for the @code{printf} and @code{scanf} families of
656 functions. Printing and reading of single wide characters was made
657 possible using the @code{%C} specifier and wide character strings can be
658 handled with @code{%S}. These modifiers behave just like @code{%c} and
659 @code{%s} only that they expect the corresponding argument to have the
660 wide character type and that the wide character and string are
661 transformed into/from multibyte strings before being used.
663 This was a beginning but it is still not good enough. Not always is it
664 desirable to use @code{printf} and @code{scanf}. The other, smaller and
665 faster functions cannot handle wide characters. Second, it is not
666 possible to have a format string for @code{printf} and @code{scanf}
667 consisting of wide characters. The result is that format strings would
668 have to be generated if they have to contain non-basic characters.
672 In the @w{Amendment 1} to @w{ISO C90} a whole new set of functions was
673 added to solve the problem. Most of the stream functions got a
674 counterpart which take a wide character or wide character string instead
675 of a character or string respectively. The new functions operate on the
676 same streams (like @code{stdout}). This is different from the model of
677 the C++ runtime library where separate streams for wide and normal I/O
680 @cindex orientation, stream
681 @cindex stream orientation
682 Being able to use the same stream for wide and normal operations comes
683 with a restriction: a stream can be used either for wide operations or
684 for normal operations. Once it is decided there is no way back. Only a
685 call to @code{freopen} or @code{freopen64} can reset the
686 @dfn{orientation}. The orientation can be decided in three ways:
690 If any of the normal character functions is used (this includes the
691 @code{fread} and @code{fwrite} functions) the stream is marked as not
695 If any of the wide character functions is used the stream is marked as
699 The @code{fwide} function can be used to set the orientation either way.
702 It is important to never mix the use of wide and not wide operations on
703 a stream. There are no diagnostics issued. The application behavior
704 will simply be strange or the application will simply crash. The
705 @code{fwide} function can help avoiding this.
709 @deftypefun int fwide (FILE *@var{stream}, int @var{mode})
711 The @code{fwide} function can be used to set and query the state of the
712 orientation of the stream @var{stream}. If the @var{mode} parameter has
713 a positive value the streams get wide oriented, for negative values
714 narrow oriented. It is not possible to overwrite previous orientations
715 with @code{fwide}. I.e., if the stream @var{stream} was already
716 oriented before the call nothing is done.
718 If @var{mode} is zero the current orientation state is queried and
721 The @code{fwide} function returns a negative value, zero, or a positive
722 value if the stream is narrow, not at all, or wide oriented
725 This function was introduced in @w{Amendment 1} to @w{ISO C90} and is
726 declared in @file{wchar.h}.
729 It is generally a good idea to orient a stream as early as possible.
730 This can prevent surprise especially for the standard streams
731 @code{stdin}, @code{stdout}, and @code{stderr}. If some library
732 function in some situations uses one of these streams and this use
733 orients the stream in a different way the rest of the application
734 expects it one might end up with hard to reproduce errors. Remember
735 that no errors are signal if the streams are used incorrectly. Leaving
736 a stream unoriented after creation is normally only necessary for
737 library functions which create streams which can be used in different
740 When writing code which uses streams and which can be used in different
741 contexts it is important to query the orientation of the stream before
742 using it (unless the rules of the library interface demand a specific
743 orientation). The following little, silly function illustrates this.
749 if (fwide (fp, 0) > 0)
750 /* @r{Positive return value means wide orientation.} */
757 Note that in this case the function @code{print_f} decides about the
758 orientation of the stream if it was unoriented before (will not happen
759 if the advise above is followed).
761 The encoding used for the @code{wchar_t} values is unspecified and the
762 user must not make any assumptions about it. For I/O of @code{wchar_t}
763 values this means that it is impossible to write these values directly
764 to the stream. This is not what follows from the @w{ISO C} locale model
765 either. What happens instead is that the bytes read from or written to
766 the underlying media are first converted into the internal encoding
767 chosen by the implementation for @code{wchar_t}. The external encoding
768 is determined by the @code{LC_CTYPE} category of the current locale or
769 by the @samp{ccs} part of the mode specification given to @code{fopen},
770 @code{fopen64}, @code{freopen}, or @code{freopen64}. How and when the
771 conversion happens is unspecified and it happens invisible to the user.
773 Since a stream is created in the unoriented state it has at that point
774 no conversion associated with it. The conversion which will be used is
775 determined by the @code{LC_CTYPE} category selected at the time the
776 stream is oriented. If the locales are changed at the runtime this
777 might produce surprising results unless one pays attention. This is
778 just another good reason to orient the stream explicitly as soon as
779 possible, perhaps with a call to @code{fwide}.
782 @section Simple Output by Characters or Lines
784 @cindex writing to a stream, by characters
785 This section describes functions for performing character- and
786 line-oriented output.
788 These narrow streams functions are declared in the header file
789 @file{stdio.h} and the wide stream functions in @file{wchar.h}.
795 @deftypefun int fputc (int @var{c}, FILE *@var{stream})
796 The @code{fputc} function converts the character @var{c} to type
797 @code{unsigned char}, and writes it to the stream @var{stream}.
798 @code{EOF} is returned if a write error occurs; otherwise the
799 character @var{c} is returned.
804 @deftypefun wint_t fputwc (wchar_t @var{wc}, FILE *@var{stream})
805 The @code{fputwc} function writes the wide character @var{wc} to the
806 stream @var{stream}. @code{WEOF} is returned if a write error occurs;
807 otherwise the character @var{wc} is returned.
812 @deftypefun int fputc_unlocked (int @var{c}, FILE *@var{stream})
813 The @code{fputc_unlocked} function is equivalent to the @code{fputc}
814 function except that it does not implicitly lock the stream.
819 @deftypefun wint_t fputwc_unlocked (wint_t @var{wc}, FILE *@var{stream})
820 The @code{fputwc_unlocked} function is equivalent to the @code{fputwc}
821 function except that it does not implicitly lock the stream.
823 This function is a GNU extension.
828 @deftypefun int putc (int @var{c}, FILE *@var{stream})
829 This is just like @code{fputc}, except that most systems implement it as
830 a macro, making it faster. One consequence is that it may evaluate the
831 @var{stream} argument more than once, which is an exception to the
832 general rule for macros. @code{putc} is usually the best function to
833 use for writing a single character.
838 @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream})
839 This is just like @code{fputwc}, except that it can be implement as
840 a macro, making it faster. One consequence is that it may evaluate the
841 @var{stream} argument more than once, which is an exception to the
842 general rule for macros. @code{putwc} is usually the best function to
843 use for writing a single wide character.
848 @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})
849 The @code{putc_unlocked} function is equivalent to the @code{putc}
850 function except that it does not implicitly lock the stream.
855 @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
856 The @code{putwc_unlocked} function is equivalent to the @code{putwc}
857 function except that it does not implicitly lock the stream.
859 This function is a GNU extension.
864 @deftypefun int putchar (int @var{c})
865 The @code{putchar} function is equivalent to @code{putc} with
866 @code{stdout} as the value of the @var{stream} argument.
871 @deftypefun wint_t putwchar (wchar_t @var{wc})
872 The @code{putwchar} function is equivalent to @code{putwc} with
873 @code{stdout} as the value of the @var{stream} argument.
878 @deftypefun int putchar_unlocked (int @var{c})
879 The @code{putchar_unlocked} function is equivalent to the @code{putchar}
880 function except that it does not implicitly lock the stream.
885 @deftypefun wint_t putwchar_unlocked (wchar_t @var{wc})
886 The @code{putwchar_unlocked} function is equivalent to the @code{putwchar}
887 function except that it does not implicitly lock the stream.
889 This function is a GNU extension.
894 @deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
895 The function @code{fputs} writes the string @var{s} to the stream
896 @var{stream}. The terminating null character is not written.
897 This function does @emph{not} add a newline character, either.
898 It outputs only the characters in the string.
900 This function returns @code{EOF} if a write error occurs, and otherwise
901 a non-negative value.
906 fputs ("Are ", stdout);
907 fputs ("you ", stdout);
908 fputs ("hungry?\n", stdout);
912 outputs the text @samp{Are you hungry?} followed by a newline.
917 @deftypefun int fputws (const wchar_t *@var{ws}, FILE *@var{stream})
918 The function @code{fputws} writes the wide character string @var{ws} to
919 the stream @var{stream}. The terminating null character is not written.
920 This function does @emph{not} add a newline character, either. It
921 outputs only the characters in the string.
923 This function returns @code{WEOF} if a write error occurs, and otherwise
924 a non-negative value.
929 @deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream})
930 The @code{fputs_unlocked} function is equivalent to the @code{fputs}
931 function except that it does not implicitly lock the stream.
933 This function is a GNU extension.
938 @deftypefun int fputws_unlocked (const wchar_t *@var{ws}, FILE *@var{stream})
939 The @code{fputws_unlocked} function is equivalent to the @code{fputws}
940 function except that it does not implicitly lock the stream.
942 This function is a GNU extension.
947 @deftypefun int puts (const char *@var{s})
948 The @code{puts} function writes the string @var{s} to the stream
949 @code{stdout} followed by a newline. The terminating null character of
950 the string is not written. (Note that @code{fputs} does @emph{not}
951 write a newline as this function does.)
953 @code{puts} is the most convenient function for printing simple
954 messages. For example:
957 puts ("This is a message.");
961 outputs the text @samp{This is a message.} followed by a newline.
966 @deftypefun int putw (int @var{w}, FILE *@var{stream})
967 This function writes the word @var{w} (that is, an @code{int}) to
968 @var{stream}. It is provided for compatibility with SVID, but we
969 recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
972 @node Character Input
973 @section Character Input
975 @cindex reading from a stream, by characters
976 This section describes functions for performing character-oriented
977 input. These narrow streams functions are declared in the header file
978 @file{stdio.h} and the wide character functions are declared in
983 These functions return an @code{int} or @code{wint_t} value (for narrow
984 and wide stream functions respectively) that is either a character of
985 input, or the special value @code{EOF}/@code{WEOF} (usually -1). For
986 the narrow stream functions it is important to store the result of these
987 functions in a variable of type @code{int} instead of @code{char}, even
988 when you plan to use it only as a character. Storing @code{EOF} in a
989 @code{char} variable truncates its value to the size of a character, so
990 that it is no longer distinguishable from the valid character
991 @samp{(char) -1}. So always use an @code{int} for the result of
992 @code{getc} and friends, and check for @code{EOF} after the call; once
993 you've verified that the result is not @code{EOF}, you can be sure that
994 it will fit in a @samp{char} variable without loss of information.
998 @deftypefun int fgetc (FILE *@var{stream})
999 This function reads the next character as an @code{unsigned char} from
1000 the stream @var{stream} and returns its value, converted to an
1001 @code{int}. If an end-of-file condition or read error occurs,
1002 @code{EOF} is returned instead.
1007 @deftypefun wint_t fgetwc (FILE *@var{stream})
1008 This function reads the next wide character from the stream @var{stream}
1009 and returns its value. If an end-of-file condition or read error
1010 occurs, @code{WEOF} is returned instead.
1015 @deftypefun int fgetc_unlocked (FILE *@var{stream})
1016 The @code{fgetc_unlocked} function is equivalent to the @code{fgetc}
1017 function except that it does not implicitly lock the stream.
1022 @deftypefun wint_t fgetwc_unlocked (FILE *@var{stream})
1023 The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc}
1024 function except that it does not implicitly lock the stream.
1026 This function is a GNU extension.
1031 @deftypefun int getc (FILE *@var{stream})
1032 This is just like @code{fgetc}, except that it is permissible (and
1033 typical) for it to be implemented as a macro that evaluates the
1034 @var{stream} argument more than once. @code{getc} is often highly
1035 optimized, so it is usually the best function to use to read a single
1041 @deftypefun wint_t getwc (FILE *@var{stream})
1042 This is just like @code{fgetwc}, except that it is permissible for it to
1043 be implemented as a macro that evaluates the @var{stream} argument more
1044 than once. @code{getwc} can be highly optimized, so it is usually the
1045 best function to use to read a single wide character.
1050 @deftypefun int getc_unlocked (FILE *@var{stream})
1051 The @code{getc_unlocked} function is equivalent to the @code{getc}
1052 function except that it does not implicitly lock the stream.
1057 @deftypefun wint_t getwc_unlocked (FILE *@var{stream})
1058 The @code{getwc_unlocked} function is equivalent to the @code{getwc}
1059 function except that it does not implicitly lock the stream.
1061 This function is a GNU extension.
1066 @deftypefun int getchar (void)
1067 The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
1068 as the value of the @var{stream} argument.
1073 @deftypefun wint_t getwchar (void)
1074 The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin}
1075 as the value of the @var{stream} argument.
1080 @deftypefun int getchar_unlocked (void)
1081 The @code{getchar_unlocked} function is equivalent to the @code{getchar}
1082 function except that it does not implicitly lock the stream.
1087 @deftypefun wint_t getwchar_unlocked (void)
1088 The @code{getwchar_unlocked} function is equivalent to the @code{getwchar}
1089 function except that it does not implicitly lock the stream.
1091 This function is a GNU extension.
1094 Here is an example of a function that does input using @code{fgetc}. It
1095 would work just as well using @code{getc} instead, or using
1096 @code{getchar ()} instead of @w{@code{fgetc (stdin)}}. The code would
1097 also work the same for the wide character stream functions.
1101 y_or_n_p (const char *question)
1103 fputs (question, stdout);
1107 /* @r{Write a space to separate answer from question.} */
1108 fputc (' ', stdout);
1109 /* @r{Read the first character of the line.}
1110 @r{This should be the answer character, but might not be.} */
1111 c = tolower (fgetc (stdin));
1113 /* @r{Discard rest of input line.} */
1114 while (c != '\n' && c != EOF)
1116 /* @r{Obey the answer if it was valid.} */
1121 /* @r{Answer was invalid: ask for valid answer.} */
1122 fputs ("Please answer y or n:", stdout);
1129 @deftypefun int getw (FILE *@var{stream})
1130 This function reads a word (that is, an @code{int}) from @var{stream}.
1131 It's provided for compatibility with SVID. We recommend you use
1132 @code{fread} instead (@pxref{Block Input/Output}). Unlike @code{getc},
1133 any @code{int} value could be a valid result. @code{getw} returns
1134 @code{EOF} when it encounters end-of-file or an error, but there is no
1135 way to distinguish this from an input word with value -1.
1139 @section Line-Oriented Input
1141 Since many programs interpret input on the basis of lines, it is
1142 convenient to have functions to read a line of text from a stream.
1144 Standard C has functions to do this, but they aren't very safe: null
1145 characters and even (for @code{gets}) long lines can confuse them. So
1146 the GNU library provides the nonstandard @code{getline} function that
1147 makes it easy to read lines reliably.
1149 Another GNU extension, @code{getdelim}, generalizes @code{getline}. It
1150 reads a delimited record, defined as everything through the next
1151 occurrence of a specified delimiter character.
1153 All these functions are declared in @file{stdio.h}.
1157 @deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
1158 This function reads an entire line from @var{stream}, storing the text
1159 (including the newline and a terminating null character) in a buffer
1160 and storing the buffer address in @code{*@var{lineptr}}.
1162 Before calling @code{getline}, you should place in @code{*@var{lineptr}}
1163 the address of a buffer @code{*@var{n}} bytes long, allocated with
1164 @code{malloc}. If this buffer is long enough to hold the line,
1165 @code{getline} stores the line in this buffer. Otherwise,
1166 @code{getline} makes the buffer bigger using @code{realloc}, storing the
1167 new buffer address back in @code{*@var{lineptr}} and the increased size
1168 back in @code{*@var{n}}.
1169 @xref{Unconstrained Allocation}.
1171 If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}}
1172 to zero, before the call, then @code{getline} allocates the initial
1173 buffer for you by calling @code{malloc}.
1175 In either case, when @code{getline} returns, @code{*@var{lineptr}} is
1176 a @code{char *} which points to the text of the line.
1178 When @code{getline} is successful, it returns the number of characters
1179 read (including the newline, but not including the terminating null).
1180 This value enables you to distinguish null characters that are part of
1181 the line from the null character inserted as a terminator.
1183 This function is a GNU extension, but it is the recommended way to read
1184 lines from a stream. The alternative standard functions are unreliable.
1186 If an error occurs or end of file is reached without any bytes read,
1187 @code{getline} returns @code{-1}.
1192 @deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream})
1193 This function is like @code{getline} except that the character which
1194 tells it to stop reading is not necessarily newline. The argument
1195 @var{delimiter} specifies the delimiter character; @code{getdelim} keeps
1196 reading until it sees that character (or end of file).
1198 The text is stored in @var{lineptr}, including the delimiter character
1199 and a terminating null. Like @code{getline}, @code{getdelim} makes
1200 @var{lineptr} bigger if it isn't big enough.
1202 @code{getline} is in fact implemented in terms of @code{getdelim}, just
1207 getline (char **lineptr, size_t *n, FILE *stream)
1209 return getdelim (lineptr, n, '\n', stream);
1216 @deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
1217 The @code{fgets} function reads characters from the stream @var{stream}
1218 up to and including a newline character and stores them in the string
1219 @var{s}, adding a null character to mark the end of the string. You
1220 must supply @var{count} characters worth of space in @var{s}, but the
1221 number of characters read is at most @var{count} @minus{} 1. The extra
1222 character space is used to hold the null character at the end of the
1225 If the system is already at end of file when you call @code{fgets}, then
1226 the contents of the array @var{s} are unchanged and a null pointer is
1227 returned. A null pointer is also returned if a read error occurs.
1228 Otherwise, the return value is the pointer @var{s}.
1230 @strong{Warning:} If the input data has a null character, you can't tell.
1231 So don't use @code{fgets} unless you know the data cannot contain a null.
1232 Don't use it to read files edited by the user because, if the user inserts
1233 a null character, you should either handle it properly or print a clear
1234 error message. We recommend using @code{getline} instead of @code{fgets}.
1239 @deftypefun {wchar_t *} fgetws (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
1240 The @code{fgetws} function reads wide characters from the stream
1241 @var{stream} up to and including a newline character and stores them in
1242 the string @var{ws}, adding a null wide character to mark the end of the
1243 string. You must supply @var{count} wide characters worth of space in
1244 @var{ws}, but the number of characters read is at most @var{count}
1245 @minus{} 1. The extra character space is used to hold the null wide
1246 character at the end of the string.
1248 If the system is already at end of file when you call @code{fgetws}, then
1249 the contents of the array @var{ws} are unchanged and a null pointer is
1250 returned. A null pointer is also returned if a read error occurs.
1251 Otherwise, the return value is the pointer @var{ws}.
1253 @strong{Warning:} If the input data has a null wide character (which are
1254 null bytes in the input stream), you can't tell. So don't use
1255 @code{fgetws} unless you know the data cannot contain a null. Don't use
1256 it to read files edited by the user because, if the user inserts a null
1257 character, you should either handle it properly or print a clear error
1259 @comment XXX We need getwline!!!
1264 @deftypefun {char *} fgets_unlocked (char *@var{s}, int @var{count}, FILE *@var{stream})
1265 The @code{fgets_unlocked} function is equivalent to the @code{fgets}
1266 function except that it does not implicitly lock the stream.
1268 This function is a GNU extension.
1273 @deftypefun {wchar_t *} fgetws_unlocked (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
1274 The @code{fgetws_unlocked} function is equivalent to the @code{fgetws}
1275 function except that it does not implicitly lock the stream.
1277 This function is a GNU extension.
1282 @deftypefn {Deprecated function} {char *} gets (char *@var{s})
1283 The function @code{gets} reads characters from the stream @code{stdin}
1284 up to the next newline character, and stores them in the string @var{s}.
1285 The newline character is discarded (note that this differs from the
1286 behavior of @code{fgets}, which copies the newline character into the
1287 string). If @code{gets} encounters a read error or end-of-file, it
1288 returns a null pointer; otherwise it returns @var{s}.
1290 @strong{Warning:} The @code{gets} function is @strong{very dangerous}
1291 because it provides no protection against overflowing the string
1292 @var{s}. The GNU library includes it for compatibility only. You
1293 should @strong{always} use @code{fgets} or @code{getline} instead. To
1294 remind you of this, the linker (if using GNU @code{ld}) will issue a
1295 warning whenever you use @code{gets}.
1300 @cindex peeking at input
1301 @cindex unreading characters
1302 @cindex pushing input back
1304 In parser programs it is often useful to examine the next character in
1305 the input stream without removing it from the stream. This is called
1306 ``peeking ahead'' at the input because your program gets a glimpse of
1307 the input it will read next.
1309 Using stream I/O, you can peek ahead at input by first reading it and
1310 then @dfn{unreading} it (also called @dfn{pushing it back} on the stream).
1311 Unreading a character makes it available to be input again from the stream,
1312 by the next call to @code{fgetc} or other input function on that stream.
1315 * Unreading Idea:: An explanation of unreading with pictures.
1316 * How Unread:: How to call @code{ungetc} to do unreading.
1319 @node Unreading Idea
1320 @subsection What Unreading Means
1322 Here is a pictorial explanation of unreading. Suppose you have a
1323 stream reading a file that contains just six characters, the letters
1324 @samp{foobar}. Suppose you have read three characters so far. The
1325 situation looks like this:
1333 so the next input character will be @samp{b}.
1335 @c @group Invalid outside @example
1336 If instead of reading @samp{b} you unread the letter @samp{o}, you get a
1337 situation like this:
1347 so that the next input characters will be @samp{o} and @samp{b}.
1351 If you unread @samp{9} instead of @samp{o}, you get this situation:
1361 so that the next input characters will be @samp{9} and @samp{b}.
1365 @subsection Using @code{ungetc} To Do Unreading
1367 The function to unread a character is called @code{ungetc}, because it
1368 reverses the action of @code{getc}.
1372 @deftypefun int ungetc (int @var{c}, FILE *@var{stream})
1373 The @code{ungetc} function pushes back the character @var{c} onto the
1374 input stream @var{stream}. So the next input from @var{stream} will
1375 read @var{c} before anything else.
1377 If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
1378 @code{EOF}. This lets you call @code{ungetc} with the return value of
1379 @code{getc} without needing to check for an error from @code{getc}.
1381 The character that you push back doesn't have to be the same as the last
1382 character that was actually read from the stream. In fact, it isn't
1383 necessary to actually read any characters from the stream before
1384 unreading them with @code{ungetc}! But that is a strange way to write a
1385 program; usually @code{ungetc} is used only to unread a character that
1386 was just read from the same stream. The GNU C library supports this
1387 even on files opened in binary mode, but other systems might not.
1389 The GNU C library only supports one character of pushback---in other
1390 words, it does not work to call @code{ungetc} twice without doing input
1391 in between. Other systems might let you push back multiple characters;
1392 then reading from the stream retrieves the characters in the reverse
1393 order that they were pushed.
1395 Pushing back characters doesn't alter the file; only the internal
1396 buffering for the stream is affected. If a file positioning function
1397 (such as @code{fseek}, @code{fseeko} or @code{rewind}; @pxref{File
1398 Positioning}) is called, any pending pushed-back characters are
1401 Unreading a character on a stream that is at end of file clears the
1402 end-of-file indicator for the stream, because it makes the character of
1403 input available. After you read that character, trying to read again
1404 will encounter end of file.
1409 @deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream})
1410 The @code{ungetwc} function behaves just like @code{ungetc} just that it
1411 pushes back a wide character.
1414 Here is an example showing the use of @code{getc} and @code{ungetc} to
1415 skip over whitespace characters. When this function reaches a
1416 non-whitespace character, it unreads that character to be seen again on
1417 the next read operation on the stream.
1424 skip_whitespace (FILE *stream)
1428 /* @r{No need to check for @code{EOF} because it is not}
1429 @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.} */
1431 while (isspace (c));
1436 @node Block Input/Output
1437 @section Block Input/Output
1439 This section describes how to do input and output operations on blocks
1440 of data. You can use these functions to read and write binary data, as
1441 well as to read and write text in fixed-size blocks instead of by
1442 characters or lines.
1443 @cindex binary I/O to a stream
1444 @cindex block I/O to a stream
1445 @cindex reading from a stream, by blocks
1446 @cindex writing to a stream, by blocks
1448 Binary files are typically used to read and write blocks of data in the
1449 same format as is used to represent the data in a running program. In
1450 other words, arbitrary blocks of memory---not just character or string
1451 objects---can be written to a binary file, and meaningfully read in
1452 again by the same program.
1454 Storing data in binary form is often considerably more efficient than
1455 using the formatted I/O functions. Also, for floating-point numbers,
1456 the binary form avoids possible loss of precision in the conversion
1457 process. On the other hand, binary files can't be examined or modified
1458 easily using many standard file utilities (such as text editors), and
1459 are not portable between different implementations of the language, or
1460 different kinds of computers.
1462 These functions are declared in @file{stdio.h}.
1467 @deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1468 This function reads up to @var{count} objects of size @var{size} into
1469 the array @var{data}, from the stream @var{stream}. It returns the
1470 number of objects actually read, which might be less than @var{count} if
1471 a read error occurs or the end of the file is reached. This function
1472 returns a value of zero (and doesn't read anything) if either @var{size}
1473 or @var{count} is zero.
1475 If @code{fread} encounters end of file in the middle of an object, it
1476 returns the number of complete objects read, and discards the partial
1477 object. Therefore, the stream remains at the actual end of the file.
1482 @deftypefun size_t fread_unlocked (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1483 The @code{fread_unlocked} function is equivalent to the @code{fread}
1484 function except that it does not implicitly lock the stream.
1486 This function is a GNU extension.
1491 @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1492 This function writes up to @var{count} objects of size @var{size} from
1493 the array @var{data}, to the stream @var{stream}. The return value is
1494 normally @var{count}, if the call succeeds. Any other value indicates
1495 some sort of error, such as running out of space.
1500 @deftypefun size_t fwrite_unlocked (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1501 The @code{fwrite_unlocked} function is equivalent to the @code{fwrite}
1502 function except that it does not implicitly lock the stream.
1504 This function is a GNU extension.
1507 @node Formatted Output
1508 @section Formatted Output
1510 @cindex format string, for @code{printf}
1511 @cindex template, for @code{printf}
1512 @cindex formatted output to a stream
1513 @cindex writing to a stream, formatted
1514 The functions described in this section (@code{printf} and related
1515 functions) provide a convenient way to perform formatted output. You
1516 call @code{printf} with a @dfn{format string} or @dfn{template string}
1517 that specifies how to format the values of the remaining arguments.
1519 Unless your program is a filter that specifically performs line- or
1520 character-oriented processing, using @code{printf} or one of the other
1521 related functions described in this section is usually the easiest and
1522 most concise way to perform output. These functions are especially
1523 useful for printing error messages, tables of data, and the like.
1526 * Formatted Output Basics:: Some examples to get you started.
1527 * Output Conversion Syntax:: General syntax of conversion
1529 * Table of Output Conversions:: Summary of output conversions and
1531 * Integer Conversions:: Details about formatting of integers.
1532 * Floating-Point Conversions:: Details about formatting of
1533 floating-point numbers.
1534 * Other Output Conversions:: Details about formatting of strings,
1535 characters, pointers, and the like.
1536 * Formatted Output Functions:: Descriptions of the actual functions.
1537 * Dynamic Output:: Functions that allocate memory for the output.
1538 * Variable Arguments Output:: @code{vprintf} and friends.
1539 * Parsing a Template String:: What kinds of args does a given template
1541 * Example of Parsing:: Sample program using @code{parse_printf_format}.
1544 @node Formatted Output Basics
1545 @subsection Formatted Output Basics
1547 The @code{printf} function can be used to print any number of arguments.
1548 The template string argument you supply in a call provides
1549 information not only about the number of additional arguments, but also
1550 about their types and what style should be used for printing them.
1552 Ordinary characters in the template string are simply written to the
1553 output stream as-is, while @dfn{conversion specifications} introduced by
1554 a @samp{%} character in the template cause subsequent arguments to be
1555 formatted and written to the output stream. For example,
1556 @cindex conversion specifications (@code{printf})
1560 char filename[] = "foo.txt";
1561 printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
1566 produces output like
1569 Processing of `foo.txt' is 37% finished.
1573 This example shows the use of the @samp{%d} conversion to specify that
1574 an @code{int} argument should be printed in decimal notation, the
1575 @samp{%s} conversion to specify printing of a string argument, and
1576 the @samp{%%} conversion to print a literal @samp{%} character.
1578 There are also conversions for printing an integer argument as an
1579 unsigned value in octal, decimal, or hexadecimal radix (@samp{%o},
1580 @samp{%u}, or @samp{%x}, respectively); or as a character value
1583 Floating-point numbers can be printed in normal, fixed-point notation
1584 using the @samp{%f} conversion or in exponential notation using the
1585 @samp{%e} conversion. The @samp{%g} conversion uses either @samp{%e}
1586 or @samp{%f} format, depending on what is more appropriate for the
1587 magnitude of the particular number.
1589 You can control formatting more precisely by writing @dfn{modifiers}
1590 between the @samp{%} and the character that indicates which conversion
1591 to apply. These slightly alter the ordinary behavior of the conversion.
1592 For example, most conversion specifications permit you to specify a
1593 minimum field width and a flag indicating whether you want the result
1594 left- or right-justified within the field.
1596 The specific flags and modifiers that are permitted and their
1597 interpretation vary depending on the particular conversion. They're all
1598 described in more detail in the following sections. Don't worry if this
1599 all seems excessively complicated at first; you can almost always get
1600 reasonable free-format output without using any of the modifiers at all.
1601 The modifiers are mostly used to make the output look ``prettier'' in
1604 @node Output Conversion Syntax
1605 @subsection Output Conversion Syntax
1607 This section provides details about the precise syntax of conversion
1608 specifications that can appear in a @code{printf} template
1611 Characters in the template string that are not part of a conversion
1612 specification are printed as-is to the output stream. Multibyte
1613 character sequences (@pxref{Character Set Handling}) are permitted in a
1616 The conversion specifications in a @code{printf} template string have
1620 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion}
1627 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} . @r{*} @r{[} @var{param-no} @r{$]} @var{type} @var{conversion}
1630 For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-}
1631 is a flag, @samp{10} specifies the field width, the precision is
1632 @samp{8}, the letter @samp{l} is a type modifier, and @samp{d} specifies
1633 the conversion style. (This particular type specifier says to
1634 print a @code{long int} argument in decimal notation, with a minimum of
1635 8 digits left-justified in a field at least 10 characters wide.)
1637 In more detail, output conversion specifications consist of an
1638 initial @samp{%} character followed in sequence by:
1642 An optional specification of the parameter used for this format.
1643 Normally the parameters to the @code{printf} function are assigned to the
1644 formats in the order of appearance in the format string. But in some
1645 situations (such as message translation) this is not desirable and this
1646 extension allows an explicit parameter to be specified.
1648 The @var{param-no} parts of the format must be integers in the range of
1649 1 to the maximum number of arguments present to the function call. Some
1650 implementations limit this number to a certainly upper bound. The exact
1651 limit can be retrieved by the following constant.
1653 @defvr Macro NL_ARGMAX
1654 The value of @code{NL_ARGMAX} is the maximum value allowed for the
1655 specification of an positional parameter in a @code{printf} call. The
1656 actual value in effect at runtime can be retrieved by using
1657 @code{sysconf} using the @code{_SC_NL_ARGMAX} parameter @pxref{Sysconf
1660 Some system have a quite low limit such as @math{9} for @w{System V}
1661 systems. The GNU C library has no real limit.
1664 If any of the formats has a specification for the parameter position all
1665 of them in the format string shall have one. Otherwise the behavior is
1669 Zero or more @dfn{flag characters} that modify the normal behavior of
1670 the conversion specification.
1671 @cindex flag character (@code{printf})
1674 An optional decimal integer specifying the @dfn{minimum field width}.
1675 If the normal conversion produces fewer characters than this, the field
1676 is padded with spaces to the specified width. This is a @emph{minimum}
1677 value; if the normal conversion produces more characters than this, the
1678 field is @emph{not} truncated. Normally, the output is right-justified
1680 @cindex minimum field width (@code{printf})
1682 You can also specify a field width of @samp{*}. This means that the
1683 next argument in the argument list (before the actual value to be
1684 printed) is used as the field width. The value must be an @code{int}.
1685 If the value is negative, this means to set the @samp{-} flag (see
1686 below) and to use the absolute value as the field width.
1689 An optional @dfn{precision} to specify the number of digits to be
1690 written for the numeric conversions. If the precision is specified, it
1691 consists of a period (@samp{.}) followed optionally by a decimal integer
1692 (which defaults to zero if omitted).
1693 @cindex precision (@code{printf})
1695 You can also specify a precision of @samp{*}. This means that the next
1696 argument in the argument list (before the actual value to be printed) is
1697 used as the precision. The value must be an @code{int}, and is ignored
1698 if it is negative. If you specify @samp{*} for both the field width and
1699 precision, the field width argument precedes the precision argument.
1700 Other C library versions may not recognize this syntax.
1703 An optional @dfn{type modifier character}, which is used to specify the
1704 data type of the corresponding argument if it differs from the default
1705 type. (For example, the integer conversions assume a type of @code{int},
1706 but you can specify @samp{h}, @samp{l}, or @samp{L} for other integer
1708 @cindex type modifier character (@code{printf})
1711 A character that specifies the conversion to be applied.
1714 The exact options that are permitted and how they are interpreted vary
1715 between the different conversion specifiers. See the descriptions of the
1716 individual conversions for information about the particular options that
1719 With the @samp{-Wformat} option, the GNU C compiler checks calls to
1720 @code{printf} and related functions. It examines the format string and
1721 verifies that the correct number and types of arguments are supplied.
1722 There is also a GNU C syntax to tell the compiler that a function you
1723 write uses a @code{printf}-style format string.
1724 @xref{Function Attributes, , Declaring Attributes of Functions,
1725 gcc.info, Using GNU CC}, for more information.
1727 @node Table of Output Conversions
1728 @subsection Table of Output Conversions
1729 @cindex output conversions, for @code{printf}
1731 Here is a table summarizing what all the different conversions do:
1734 @item @samp{%d}, @samp{%i}
1735 Print an integer as a signed decimal number. @xref{Integer
1736 Conversions}, for details. @samp{%d} and @samp{%i} are synonymous for
1737 output, but are different when used with @code{scanf} for input
1738 (@pxref{Table of Input Conversions}).
1741 Print an integer as an unsigned octal number. @xref{Integer
1742 Conversions}, for details.
1745 Print an integer as an unsigned decimal number. @xref{Integer
1746 Conversions}, for details.
1748 @item @samp{%x}, @samp{%X}
1749 Print an integer as an unsigned hexadecimal number. @samp{%x} uses
1750 lower-case letters and @samp{%X} uses upper-case. @xref{Integer
1751 Conversions}, for details.
1754 Print a floating-point number in normal (fixed-point) notation.
1755 @xref{Floating-Point Conversions}, for details.
1757 @item @samp{%e}, @samp{%E}
1758 Print a floating-point number in exponential notation. @samp{%e} uses
1759 lower-case letters and @samp{%E} uses upper-case. @xref{Floating-Point
1760 Conversions}, for details.
1762 @item @samp{%g}, @samp{%G}
1763 Print a floating-point number in either normal or exponential notation,
1764 whichever is more appropriate for its magnitude. @samp{%g} uses
1765 lower-case letters and @samp{%G} uses upper-case. @xref{Floating-Point
1766 Conversions}, for details.
1768 @item @samp{%a}, @samp{%A}
1769 Print a floating-point number in a hexadecimal fractional notation which
1770 the exponent to base 2 represented in decimal digits. @samp{%a} uses
1771 lower-case letters and @samp{%A} uses upper-case. @xref{Floating-Point
1772 Conversions}, for details.
1775 Print a single character. @xref{Other Output Conversions}.
1778 This is an alias for @samp{%lc} which is supported for compatibility
1779 with the Unix standard.
1782 Print a string. @xref{Other Output Conversions}.
1785 This is an alias for @samp{%ls} which is supported for compatibility
1786 with the Unix standard.
1789 Print the value of a pointer. @xref{Other Output Conversions}.
1792 Get the number of characters printed so far. @xref{Other Output Conversions}.
1793 Note that this conversion specification never produces any output.
1796 Print the string corresponding to the value of @code{errno}.
1797 (This is a GNU extension.)
1798 @xref{Other Output Conversions}.
1801 Print a literal @samp{%} character. @xref{Other Output Conversions}.
1804 If the syntax of a conversion specification is invalid, unpredictable
1805 things will happen, so don't do this. If there aren't enough function
1806 arguments provided to supply values for all the conversion
1807 specifications in the template string, or if the arguments are not of
1808 the correct types, the results are unpredictable. If you supply more
1809 arguments than conversion specifications, the extra argument values are
1810 simply ignored; this is sometimes useful.
1812 @node Integer Conversions
1813 @subsection Integer Conversions
1815 This section describes the options for the @samp{%d}, @samp{%i},
1816 @samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
1817 specifications. These conversions print integers in various formats.
1819 The @samp{%d} and @samp{%i} conversion specifications both print an
1820 @code{int} argument as a signed decimal number; while @samp{%o},
1821 @samp{%u}, and @samp{%x} print the argument as an unsigned octal,
1822 decimal, or hexadecimal number (respectively). The @samp{%X} conversion
1823 specification is just like @samp{%x} except that it uses the characters
1824 @samp{ABCDEF} as digits instead of @samp{abcdef}.
1826 The following flags are meaningful:
1830 Left-justify the result in the field (instead of the normal
1831 right-justification).
1834 For the signed @samp{%d} and @samp{%i} conversions, print a
1835 plus sign if the value is positive.
1838 For the signed @samp{%d} and @samp{%i} conversions, if the result
1839 doesn't start with a plus or minus sign, prefix it with a space
1840 character instead. Since the @samp{+} flag ensures that the result
1841 includes a sign, this flag is ignored if you supply both of them.
1844 For the @samp{%o} conversion, this forces the leading digit to be
1845 @samp{0}, as if by increasing the precision. For @samp{%x} or
1846 @samp{%X}, this prefixes a leading @samp{0x} or @samp{0X} (respectively)
1847 to the result. This doesn't do anything useful for the @samp{%d},
1848 @samp{%i}, or @samp{%u} conversions. Using this flag produces output
1849 which can be parsed by the @code{strtoul} function (@pxref{Parsing of
1850 Integers}) and @code{scanf} with the @samp{%i} conversion
1851 (@pxref{Numeric Input Conversions}).
1854 Separate the digits into groups as specified by the locale specified for
1855 the @code{LC_NUMERIC} category; @pxref{General Numeric}. This flag is a
1859 Pad the field with zeros instead of spaces. The zeros are placed after
1860 any indication of sign or base. This flag is ignored if the @samp{-}
1861 flag is also specified, or if a precision is specified.
1864 If a precision is supplied, it specifies the minimum number of digits to
1865 appear; leading zeros are produced if necessary. If you don't specify a
1866 precision, the number is printed with as many digits as it needs. If
1867 you convert a value of zero with an explicit precision of zero, then no
1868 characters at all are produced.
1870 Without a type modifier, the corresponding argument is treated as an
1871 @code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
1872 @code{unsigned int} (for the unsigned conversions @samp{%o}, @samp{%u},
1873 @samp{%x}, and @samp{%X}). Recall that since @code{printf} and friends
1874 are variadic, any @code{char} and @code{short} arguments are
1875 automatically converted to @code{int} by the default argument
1876 promotions. For arguments of other integer types, you can use these
1881 Specifies that the argument is a @code{signed char} or @code{unsigned
1882 char}, as appropriate. A @code{char} argument is converted to an
1883 @code{int} or @code{unsigned int} by the default argument promotions
1884 anyway, but the @samp{h} modifier says to convert it back to a
1887 This modifier was introduced in @w{ISO C99}.
1890 Specifies that the argument is a @code{short int} or @code{unsigned
1891 short int}, as appropriate. A @code{short} argument is converted to an
1892 @code{int} or @code{unsigned int} by the default argument promotions
1893 anyway, but the @samp{h} modifier says to convert it back to a
1897 Specifies that the argument is a @code{intmax_t} or @code{uintmax_t}, as
1900 This modifier was introduced in @w{ISO C99}.
1903 Specifies that the argument is a @code{long int} or @code{unsigned long
1904 int}, as appropriate. Two @samp{l} characters is like the @samp{L}
1907 If used with @samp{%c} or @samp{%s} the corresponding parameter is
1908 considered as a wide character or wide character string respectively.
1909 This use of @samp{l} was introduced in @w{Amendment 1} to @w{ISO C90}.
1914 Specifies that the argument is a @code{long long int}. (This type is
1915 an extension supported by the GNU C compiler. On systems that don't
1916 support extra-long integers, this is the same as @code{long int}.)
1918 The @samp{q} modifier is another name for the same thing, which comes
1919 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
1923 Specifies that the argument is a @code{ptrdiff_t}.
1925 This modifier was introduced in @w{ISO C99}.
1929 Specifies that the argument is a @code{size_t}.
1931 @samp{z} was introduced in @w{ISO C99}. @samp{Z} is a GNU extension
1932 predating this addition and should not be used in new code.
1935 Here is an example. Using the template string:
1938 "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
1942 to print numbers using the different options for the @samp{%d}
1943 conversion gives results like:
1946 | 0|0 | +0|+0 | 0|00000| | 00|0|
1947 | 1|1 | +1|+1 | 1|00001| 1| 01|1|
1948 | -1|-1 | -1|-1 | -1|-0001| -1| -01|-1|
1949 |100000|100000|+100000|+100000| 100000|100000|100000|100000|100000|
1952 In particular, notice what happens in the last case where the number
1953 is too large to fit in the minimum field width specified.
1955 Here are some more examples showing how unsigned integers print under
1956 various format options, using the template string:
1959 "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
1963 | 0| 0| 0| 0| 0| 0| 0| 00000000|
1964 | 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001|
1965 |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
1969 @node Floating-Point Conversions
1970 @subsection Floating-Point Conversions
1972 This section discusses the conversion specifications for floating-point
1973 numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G}
1976 The @samp{%f} conversion prints its argument in fixed-point notation,
1977 producing output of the form
1978 @w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
1979 where the number of digits following the decimal point is controlled
1980 by the precision you specify.
1982 The @samp{%e} conversion prints its argument in exponential notation,
1983 producing output of the form
1984 @w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}.
1985 Again, the number of digits following the decimal point is controlled by
1986 the precision. The exponent always contains at least two digits. The
1987 @samp{%E} conversion is similar but the exponent is marked with the letter
1988 @samp{E} instead of @samp{e}.
1990 The @samp{%g} and @samp{%G} conversions print the argument in the style
1991 of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
1992 than -4 or greater than or equal to the precision; otherwise they use
1993 the @samp{%f} style. A precision of @code{0}, is taken as 1.
1994 Trailing zeros are removed from the fractional portion of the result and
1995 a decimal-point character appears only if it is followed by a digit.
1997 The @samp{%a} and @samp{%A} conversions are meant for representing
1998 floating-point numbers exactly in textual form so that they can be
1999 exchanged as texts between different programs and/or machines. The
2000 numbers are represented is the form
2001 @w{[@code{-}]@code{0x}@var{h}@code{.}@var{hhh}@code{p}[@code{+}|@code{-}]@var{dd}}.
2002 At the left of the decimal-point character exactly one digit is print.
2003 This character is only @code{0} if the number is denormalized.
2004 Otherwise the value is unspecified; it is implementation dependent how many
2005 bits are used. The number of hexadecimal digits on the right side of
2006 the decimal-point character is equal to the precision. If the precision
2007 is zero it is determined to be large enough to provide an exact
2008 representation of the number (or it is large enough to distinguish two
2009 adjacent values if the @code{FLT_RADIX} is not a power of 2,
2010 @pxref{Floating Point Parameters}). For the @samp{%a} conversion
2011 lower-case characters are used to represent the hexadecimal number and
2012 the prefix and exponent sign are printed as @code{0x} and @code{p}
2013 respectively. Otherwise upper-case characters are used and @code{0X}
2014 and @code{P} are used for the representation of prefix and exponent
2015 string. The exponent to the base of two is printed as a decimal number
2016 using at least one digit but at most as many digits as necessary to
2017 represent the value exactly.
2019 If the value to be printed represents infinity or a NaN, the output is
2020 @w{[@code{-}]@code{inf}} or @code{nan} respectively if the conversion
2021 specifier is @samp{%a}, @samp{%e}, @samp{%f}, or @samp{%g} and it is
2022 @w{[@code{-}]@code{INF}} or @code{NAN} respectively if the conversion is
2023 @samp{%A}, @samp{%E}, or @samp{%G}.
2025 The following flags can be used to modify the behavior:
2027 @comment We use @asis instead of @samp so we can have ` ' as an item.
2030 Left-justify the result in the field. Normally the result is
2034 Always include a plus or minus sign in the result.
2037 If the result doesn't start with a plus or minus sign, prefix it with a
2038 space instead. Since the @samp{+} flag ensures that the result includes
2039 a sign, this flag is ignored if you supply both of them.
2042 Specifies that the result should always include a decimal point, even
2043 if no digits follow it. For the @samp{%g} and @samp{%G} conversions,
2044 this also forces trailing zeros after the decimal point to be left
2045 in place where they would otherwise be removed.
2048 Separate the digits of the integer part of the result into groups as
2049 specified by the locale specified for the @code{LC_NUMERIC} category;
2050 @pxref{General Numeric}. This flag is a GNU extension.
2053 Pad the field with zeros instead of spaces; the zeros are placed
2054 after any sign. This flag is ignored if the @samp{-} flag is also
2058 The precision specifies how many digits follow the decimal-point
2059 character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions. For
2060 these conversions, the default precision is @code{6}. If the precision
2061 is explicitly @code{0}, this suppresses the decimal point character
2062 entirely. For the @samp{%g} and @samp{%G} conversions, the precision
2063 specifies how many significant digits to print. Significant digits are
2064 the first digit before the decimal point, and all the digits after it.
2065 If the precision is @code{0} or not specified for @samp{%g} or @samp{%G},
2066 it is treated like a value of @code{1}. If the value being printed
2067 cannot be expressed accurately in the specified number of digits, the
2068 value is rounded to the nearest number that fits.
2070 Without a type modifier, the floating-point conversions use an argument
2071 of type @code{double}. (By the default argument promotions, any
2072 @code{float} arguments are automatically converted to @code{double}.)
2073 The following type modifier is supported:
2077 An uppercase @samp{L} specifies that the argument is a @code{long
2081 Here are some examples showing how numbers print using the various
2082 floating-point conversions. All of the numbers were printed using
2083 this template string:
2086 "|%13.4a|%13.4f|%13.4e|%13.4g|\n"
2092 | 0x0.0000p+0| 0.0000| 0.0000e+00| 0|
2093 | 0x1.0000p-1| 0.5000| 5.0000e-01| 0.5|
2094 | 0x1.0000p+0| 1.0000| 1.0000e+00| 1|
2095 | -0x1.0000p+0| -1.0000| -1.0000e+00| -1|
2096 | 0x1.9000p+6| 100.0000| 1.0000e+02| 100|
2097 | 0x1.f400p+9| 1000.0000| 1.0000e+03| 1000|
2098 | 0x1.3880p+13| 10000.0000| 1.0000e+04| 1e+04|
2099 | 0x1.81c8p+13| 12345.0000| 1.2345e+04| 1.234e+04|
2100 | 0x1.86a0p+16| 100000.0000| 1.0000e+05| 1e+05|
2101 | 0x1.e240p+16| 123456.0000| 1.2346e+05| 1.235e+05|
2104 Notice how the @samp{%g} conversion drops trailing zeros.
2106 @node Other Output Conversions
2107 @subsection Other Output Conversions
2109 This section describes miscellaneous conversions for @code{printf}.
2111 The @samp{%c} conversion prints a single character. In case there is no
2112 @samp{l} modifier the @code{int} argument is first converted to an
2113 @code{unsigned char}. Then, if used in a wide stream function, the
2114 character is converted into the corresponding wide character. The
2115 @samp{-} flag can be used to specify left-justification in the field,
2116 but no other flags are defined, and no precision or type modifier can be
2120 printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
2124 prints @samp{hello}.
2126 If there is a @samp{l} modifier present the argument is expected to be
2127 of type @code{wint_t}. If used in a multibyte function the wide
2128 character is converted into a multibyte character before being added to
2129 the output. In this case more than one output byte can be produced.
2131 The @samp{%s} conversion prints a string. If no @samp{l} modifier is
2132 present the corresponding argument must be of type @code{char *} (or
2133 @code{const char *}). If used in a wide stream function the string is
2134 first converted in a wide character string. A precision can be
2135 specified to indicate the maximum number of characters to write;
2136 otherwise characters in the string up to but not including the
2137 terminating null character are written to the output stream. The
2138 @samp{-} flag can be used to specify left-justification in the field,
2139 but no other flags or type modifiers are defined for this conversion.
2143 printf ("%3s%-6s", "no", "where");
2147 prints @samp{ nowhere }.
2149 If there is a @samp{l} modifier present the argument is expected to be of type @code{wchar_t} (or @code{const wchar_t *}).
2151 If you accidentally pass a null pointer as the argument for a @samp{%s}
2152 conversion, the GNU library prints it as @samp{(null)}. We think this
2153 is more useful than crashing. But it's not good practice to pass a null
2154 argument intentionally.
2156 The @samp{%m} conversion prints the string corresponding to the error
2157 code in @code{errno}. @xref{Error Messages}. Thus:
2160 fprintf (stderr, "can't open `%s': %m\n", filename);
2167 fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
2171 The @samp{%m} conversion is a GNU C library extension.
2173 The @samp{%p} conversion prints a pointer value. The corresponding
2174 argument must be of type @code{void *}. In practice, you can use any
2177 In the GNU system, non-null pointers are printed as unsigned integers,
2178 as if a @samp{%#x} conversion were used. Null pointers print as
2179 @samp{(nil)}. (Pointers might print differently in other systems.)
2184 printf ("%p", "testing");
2188 prints @samp{0x} followed by a hexadecimal number---the address of the
2189 string constant @code{"testing"}. It does not print the word
2192 You can supply the @samp{-} flag with the @samp{%p} conversion to
2193 specify left-justification, but no other flags, precision, or type
2194 modifiers are defined.
2196 The @samp{%n} conversion is unlike any of the other output conversions.
2197 It uses an argument which must be a pointer to an @code{int}, but
2198 instead of printing anything it stores the number of characters printed
2199 so far by this call at that location. The @samp{h} and @samp{l} type
2200 modifiers are permitted to specify that the argument is of type
2201 @code{short int *} or @code{long int *} instead of @code{int *}, but no
2202 flags, field width, or precision are permitted.
2208 printf ("%d %s%n\n", 3, "bears", &nchar);
2219 and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven
2223 The @samp{%%} conversion prints a literal @samp{%} character. This
2224 conversion doesn't use an argument, and no flags, field width,
2225 precision, or type modifiers are permitted.
2228 @node Formatted Output Functions
2229 @subsection Formatted Output Functions
2231 This section describes how to call @code{printf} and related functions.
2232 Prototypes for these functions are in the header file @file{stdio.h}.
2233 Because these functions take a variable number of arguments, you
2234 @emph{must} declare prototypes for them before using them. Of course,
2235 the easiest way to make sure you have all the right prototypes is to
2236 just include @file{stdio.h}.
2241 @deftypefun int printf (const char *@var{template}, @dots{})
2242 The @code{printf} function prints the optional arguments under the
2243 control of the template string @var{template} to the stream
2244 @code{stdout}. It returns the number of characters printed, or a
2245 negative value if there was an output error.
2250 @deftypefun int wprintf (const wchar_t *@var{template}, @dots{})
2251 The @code{wprintf} function prints the optional arguments under the
2252 control of the wide template string @var{template} to the stream
2253 @code{stdout}. It returns the number of wide characters printed, or a
2254 negative value if there was an output error.
2259 @deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
2260 This function is just like @code{printf}, except that the output is
2261 written to the stream @var{stream} instead of @code{stdout}.
2266 @deftypefun int fwprintf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
2267 This function is just like @code{wprintf}, except that the output is
2268 written to the stream @var{stream} instead of @code{stdout}.
2273 @deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
2274 This is like @code{printf}, except that the output is stored in the character
2275 array @var{s} instead of written to a stream. A null character is written
2276 to mark the end of the string.
2278 The @code{sprintf} function returns the number of characters stored in
2279 the array @var{s}, not including the terminating null character.
2281 The behavior of this function is undefined if copying takes place
2282 between objects that overlap---for example, if @var{s} is also given
2283 as an argument to be printed under control of the @samp{%s} conversion.
2284 @xref{Copying and Concatenation}.
2286 @strong{Warning:} The @code{sprintf} function can be @strong{dangerous}
2287 because it can potentially output more characters than can fit in the
2288 allocation size of the string @var{s}. Remember that the field width
2289 given in a conversion specification is only a @emph{minimum} value.
2291 To avoid this problem, you can use @code{snprintf} or @code{asprintf},
2297 @deftypefun int swprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, @dots{})
2298 This is like @code{wprintf}, except that the output is stored in the
2299 wide character array @var{ws} instead of written to a stream. A null
2300 wide character is written to mark the end of the string. The @var{size}
2301 argument specifies the maximum number of characters to produce. The
2302 trailing null character is counted towards this limit, so you should
2303 allocate at least @var{size} wide characters for the string @var{ws}.
2305 The return value is the number of characters generated for the given
2306 input, excluding the trailing null. If not all output fits into the
2307 provided buffer a negative value is returned. You should try again with
2308 a bigger output string. @emph{Note:} this is different from how
2309 @code{snprintf} handles this situation.
2311 Note that the corresponding narrow stream function takes fewer
2312 parameters. @code{swprintf} in fact corresponds to the @code{snprintf}
2313 function. Since the @code{sprintf} function can be dangerous and should
2314 be avoided the @w{ISO C} committee refused to make the same mistake
2315 again and decided to not define an function exactly corresponding to
2321 @deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{})
2322 The @code{snprintf} function is similar to @code{sprintf}, except that
2323 the @var{size} argument specifies the maximum number of characters to
2324 produce. The trailing null character is counted towards this limit, so
2325 you should allocate at least @var{size} characters for the string @var{s}.
2327 The return value is the number of characters which would be generated
2328 for the given input, excluding the trailing null. If this value is
2329 greater or equal to @var{size}, not all characters from the result have
2330 been stored in @var{s}. You should try again with a bigger output
2331 string. Here is an example of doing this:
2335 /* @r{Construct a message describing the value of a variable}
2336 @r{whose name is @var{name} and whose value is @var{value}.} */
2338 make_message (char *name, char *value)
2340 /* @r{Guess we need no more than 100 chars of space.} */
2342 char *buffer = (char *) xmalloc (size);
2349 /* @r{Try to print in the allocated space.} */
2350 nchars = snprintf (buffer, size, "value of %s is %s",
2356 /* @r{Reallocate buffer now that we know
2357 how much space is needed.} */
2359 buffer = (char *) xrealloc (buffer, size);
2362 /* @r{Try again.} */
2363 snprintf (buffer, size, "value of %s is %s",
2366 /* @r{The last call worked, return the string.} */
2372 In practice, it is often easier just to use @code{asprintf}, below.
2374 @strong{Attention:} In versions of the GNU C library prior to 2.1 the
2375 return value is the number of characters stored, not including the
2376 terminating null; unless there was not enough space in @var{s} to
2377 store the result in which case @code{-1} is returned. This was
2378 changed in order to comply with the @w{ISO C99} standard.
2381 @node Dynamic Output
2382 @subsection Dynamically Allocating Formatted Output
2384 The functions in this section do formatted output and place the results
2385 in dynamically allocated memory.
2389 @deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
2390 This function is similar to @code{sprintf}, except that it dynamically
2391 allocates a string (as with @code{malloc}; @pxref{Unconstrained
2392 Allocation}) to hold the output, instead of putting the output in a
2393 buffer you allocate in advance. The @var{ptr} argument should be the
2394 address of a @code{char *} object, and a successful call to
2395 @code{asprintf} stores a pointer to the newly allocated string at that
2398 The return value is the number of characters allocated for the buffer, or
2399 less than zero if an error occurred. Usually this means that the buffer
2400 could not be allocated.
2402 Here is how to use @code{asprintf} to get the same result as the
2403 @code{snprintf} example, but more easily:
2406 /* @r{Construct a message describing the value of a variable}
2407 @r{whose name is @var{name} and whose value is @var{value}.} */
2409 make_message (char *name, char *value)
2412 if (asprintf (&result, "value of %s is %s", name, value) < 0)
2421 @deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
2422 This function is similar to @code{asprintf}, except that it uses the
2423 obstack @var{obstack} to allocate the space. @xref{Obstacks}.
2425 The characters are written onto the end of the current object.
2426 To get at them, you must finish the object with @code{obstack_finish}
2427 (@pxref{Growing Objects}).@refill
2430 @node Variable Arguments Output
2431 @subsection Variable Arguments Output Functions
2433 The functions @code{vprintf} and friends are provided so that you can
2434 define your own variadic @code{printf}-like functions that make use of
2435 the same internals as the built-in formatted output functions.
2437 The most natural way to define such functions would be to use a language
2438 construct to say, ``Call @code{printf} and pass this template plus all
2439 of my arguments after the first five.'' But there is no way to do this
2440 in C, and it would be hard to provide a way, since at the C language
2441 level there is no way to tell how many arguments your function received.
2443 Since that method is impossible, we provide alternative functions, the
2444 @code{vprintf} series, which lets you pass a @code{va_list} to describe
2445 ``all of my arguments after the first five.''
2447 When it is sufficient to define a macro rather than a real function,
2448 the GNU C compiler provides a way to do this much more easily with macros.
2452 #define myprintf(a, b, c, d, e, rest...) \
2453 printf (mytemplate , ## rest)
2457 @xref{Variadic Macros,,, cpp, The C preprocessor}, for details.
2458 But this is limited to macros, and does not apply to real functions at all.
2460 Before calling @code{vprintf} or the other functions listed in this
2461 section, you @emph{must} call @code{va_start} (@pxref{Variadic
2462 Functions}) to initialize a pointer to the variable arguments. Then you
2463 can call @code{va_arg} to fetch the arguments that you want to handle
2464 yourself. This advances the pointer past those arguments.
2466 Once your @code{va_list} pointer is pointing at the argument of your
2467 choice, you are ready to call @code{vprintf}. That argument and all
2468 subsequent arguments that were passed to your function are used by
2469 @code{vprintf} along with the template that you specified separately.
2471 In some other systems, the @code{va_list} pointer may become invalid
2472 after the call to @code{vprintf}, so you must not use @code{va_arg}
2473 after you call @code{vprintf}. Instead, you should call @code{va_end}
2474 to retire the pointer from service. However, you can safely call
2475 @code{va_start} on another pointer variable and begin fetching the
2476 arguments again through that pointer. Calling @code{vprintf} does not
2477 destroy the argument list of your function, merely the particular
2478 pointer that you passed to it.
2480 GNU C does not have such restrictions. You can safely continue to fetch
2481 arguments from a @code{va_list} pointer after passing it to
2482 @code{vprintf}, and @code{va_end} is a no-op. (Note, however, that
2483 subsequent @code{va_arg} calls will fetch the same arguments which
2484 @code{vprintf} previously used.)
2486 Prototypes for these functions are declared in @file{stdio.h}.
2491 @deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
2492 This function is similar to @code{printf} except that, instead of taking
2493 a variable number of arguments directly, it takes an argument list
2499 @deftypefun int vwprintf (const wchar_t *@var{template}, va_list @var{ap})
2500 This function is similar to @code{wprintf} except that, instead of taking
2501 a variable number of arguments directly, it takes an argument list
2507 @deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
2508 This is the equivalent of @code{fprintf} with the variable argument list
2509 specified directly as for @code{vprintf}.
2514 @deftypefun int vfwprintf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
2515 This is the equivalent of @code{fwprintf} with the variable argument list
2516 specified directly as for @code{vwprintf}.
2521 @deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
2522 This is the equivalent of @code{sprintf} with the variable argument list
2523 specified directly as for @code{vprintf}.
2528 @deftypefun int vswprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap})
2529 This is the equivalent of @code{swprintf} with the variable argument list
2530 specified directly as for @code{vwprintf}.
2535 @deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
2536 This is the equivalent of @code{snprintf} with the variable argument list
2537 specified directly as for @code{vprintf}.
2542 @deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
2543 The @code{vasprintf} function is the equivalent of @code{asprintf} with the
2544 variable argument list specified directly as for @code{vprintf}.
2549 @deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
2550 The @code{obstack_vprintf} function is the equivalent of
2551 @code{obstack_printf} with the variable argument list specified directly
2552 as for @code{vprintf}.@refill
2555 Here's an example showing how you might use @code{vfprintf}. This is a
2556 function that prints error messages to the stream @code{stderr}, along
2557 with a prefix indicating the name of the program
2558 (@pxref{Error Messages}, for a description of
2559 @code{program_invocation_short_name}).
2567 eprintf (const char *template, ...)
2570 extern char *program_invocation_short_name;
2572 fprintf (stderr, "%s: ", program_invocation_short_name);
2573 va_start (ap, template);
2574 vfprintf (stderr, template, ap);
2581 You could call @code{eprintf} like this:
2584 eprintf ("file `%s' does not exist\n", filename);
2587 In GNU C, there is a special construct you can use to let the compiler
2588 know that a function uses a @code{printf}-style format string. Then it
2589 can check the number and types of arguments in each call to the
2590 function, and warn you when they do not match the format string.
2591 For example, take this declaration of @code{eprintf}:
2594 void eprintf (const char *template, ...)
2595 __attribute__ ((format (printf, 1, 2)));
2599 This tells the compiler that @code{eprintf} uses a format string like
2600 @code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input});
2601 the format string appears as the first argument;
2602 and the arguments to satisfy the format begin with the second.
2603 @xref{Function Attributes, , Declaring Attributes of Functions,
2604 gcc.info, Using GNU CC}, for more information.
2606 @node Parsing a Template String
2607 @subsection Parsing a Template String
2608 @cindex parsing a template string
2610 You can use the function @code{parse_printf_format} to obtain
2611 information about the number and types of arguments that are expected by
2612 a given template string. This function permits interpreters that
2613 provide interfaces to @code{printf} to avoid passing along invalid
2614 arguments from the user's program, which could cause a crash.
2616 All the symbols described in this section are declared in the header
2617 file @file{printf.h}.
2621 @deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
2622 This function returns information about the number and types of
2623 arguments expected by the @code{printf} template string @var{template}.
2624 The information is stored in the array @var{argtypes}; each element of
2625 this array describes one argument. This information is encoded using
2626 the various @samp{PA_} macros, listed below.
2628 The argument @var{n} specifies the number of elements in the array
2629 @var{argtypes}. This is the maximum number of elements that
2630 @code{parse_printf_format} will try to write.
2632 @code{parse_printf_format} returns the total number of arguments required
2633 by @var{template}. If this number is greater than @var{n}, then the
2634 information returned describes only the first @var{n} arguments. If you
2635 want information about additional arguments, allocate a bigger
2636 array and call @code{parse_printf_format} again.
2639 The argument types are encoded as a combination of a basic type and
2644 @deftypevr Macro int PA_FLAG_MASK
2645 This macro is a bitmask for the type modifier flag bits. You can write
2646 the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the
2647 flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to
2648 extract just the basic type code.
2651 Here are symbolic constants that represent the basic types; they stand
2658 This specifies that the base type is @code{int}.
2663 This specifies that the base type is @code{int}, cast to @code{char}.
2668 This specifies that the base type is @code{char *}, a null-terminated string.
2673 This specifies that the base type is @code{void *}, an arbitrary pointer.
2678 This specifies that the base type is @code{float}.
2683 This specifies that the base type is @code{double}.
2688 You can define additional base types for your own programs as offsets
2689 from @code{PA_LAST}. For example, if you have data types @samp{foo}
2690 and @samp{bar} with their own specialized @code{printf} conversions,
2691 you could define encodings for these types as:
2694 #define PA_FOO PA_LAST
2695 #define PA_BAR (PA_LAST + 1)
2699 Here are the flag bits that modify a basic type. They are combined with
2700 the code for the basic type using inclusive-or.
2706 If this bit is set, it indicates that the encoded type is a pointer to
2707 the base type, rather than an immediate value.
2708 For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.
2713 If this bit is set, it indicates that the base type is modified with
2714 @code{short}. (This corresponds to the @samp{h} type modifier.)
2719 If this bit is set, it indicates that the base type is modified with
2720 @code{long}. (This corresponds to the @samp{l} type modifier.)
2724 @item PA_FLAG_LONG_LONG
2725 If this bit is set, it indicates that the base type is modified with
2726 @code{long long}. (This corresponds to the @samp{L} type modifier.)
2730 @item PA_FLAG_LONG_DOUBLE
2731 This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with
2732 a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
2736 For an example of using these facilities, see @ref{Example of Parsing}.
2739 @node Example of Parsing
2740 @subsection Example of Parsing a Template String
2742 Here is an example of decoding argument types for a format string. We
2743 assume this is part of an interpreter which contains arguments of type
2744 @code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
2745 perhaps others which are not valid here).
2748 /* @r{Test whether the @var{nargs} specified objects}
2749 @r{in the vector @var{args} are valid}
2750 @r{for the format string @var{format}:}
2751 @r{if so, return 1.}
2752 @r{If not, return 0 after printing an error message.} */
2755 validate_args (char *format, int nargs, OBJECT *args)
2760 /* @r{Get the information about the arguments.}
2761 @r{Each conversion specification must be at least two characters}
2762 @r{long, so there cannot be more specifications than half the}
2763 @r{length of the string.} */
2765 argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
2766 nwanted = parse_printf_format (string, nelts, argtypes);
2768 /* @r{Check the number of arguments.} */
2769 if (nwanted > nargs)
2771 error ("too few arguments (at least %d required)", nwanted);
2775 /* @r{Check the C type wanted for each argument}
2776 @r{and see if the object given is suitable.} */
2777 for (i = 0; i < nwanted; i++)
2781 if (argtypes[i] & PA_FLAG_PTR)
2784 switch (argtypes[i] & ~PA_FLAG_MASK)
2801 if (TYPE (args[i]) != wanted)
2803 error ("type mismatch for arg number %d", i);
2811 @node Customizing Printf
2812 @section Customizing @code{printf}
2813 @cindex customizing @code{printf}
2814 @cindex defining new @code{printf} conversions
2815 @cindex extending @code{printf}
2817 The GNU C library lets you define your own custom conversion specifiers
2818 for @code{printf} template strings, to teach @code{printf} clever ways
2819 to print the important data structures of your program.
2821 The way you do this is by registering the conversion with the function
2822 @code{register_printf_function}; see @ref{Registering New Conversions}.
2823 One of the arguments you pass to this function is a pointer to a handler
2824 function that produces the actual output; see @ref{Defining the Output
2825 Handler}, for information on how to write this function.
2827 You can also install a function that just returns information about the
2828 number and type of arguments expected by the conversion specifier.
2829 @xref{Parsing a Template String}, for information about this.
2831 The facilities of this section are declared in the header file
2835 * Registering New Conversions:: Using @code{register_printf_function}
2836 to register a new output conversion.
2837 * Conversion Specifier Options:: The handler must be able to get
2838 the options specified in the
2839 template when it is called.
2840 * Defining the Output Handler:: Defining the handler and arginfo
2841 functions that are passed as arguments
2842 to @code{register_printf_function}.
2843 * Printf Extension Example:: How to define a @code{printf}
2845 * Predefined Printf Handlers:: Predefined @code{printf} handlers.
2848 @strong{Portability Note:} The ability to extend the syntax of
2849 @code{printf} template strings is a GNU extension. ISO standard C has
2852 @node Registering New Conversions
2853 @subsection Registering New Conversions
2855 The function to register a new output conversion is
2856 @code{register_printf_function}, declared in @file{printf.h}.
2861 @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function})
2862 This function defines the conversion specifier character @var{spec}.
2863 Thus, if @var{spec} is @code{'Y'}, it defines the conversion @samp{%Y}.
2864 You can redefine the built-in conversions like @samp{%s}, but flag
2865 characters like @samp{#} and type modifiers like @samp{l} can never be
2866 used as conversions; calling @code{register_printf_function} for those
2867 characters has no effect. It is advisable not to use lowercase letters,
2868 since the ISO C standard warns that additional lowercase letters may be
2869 standardized in future editions of the standard.
2871 The @var{handler-function} is the function called by @code{printf} and
2872 friends when this conversion appears in a template string.
2873 @xref{Defining the Output Handler}, for information about how to define
2874 a function to pass as this argument. If you specify a null pointer, any
2875 existing handler function for @var{spec} is removed.
2877 The @var{arginfo-function} is the function called by
2878 @code{parse_printf_format} when this conversion appears in a
2879 template string. @xref{Parsing a Template String}, for information
2882 @c The following is not true anymore. The `parse_printf_format' function
2883 @c is now also called from `vfprintf' via `parse_one_spec'.
2884 @c --drepper@gnu, 1996/11/14
2886 @c Normally, you install both functions for a conversion at the same time,
2887 @c but if you are never going to call @code{parse_printf_format}, you do
2888 @c not need to define an arginfo function.
2890 @strong{Attention:} In the GNU C library versions before 2.0 the
2891 @var{arginfo-function} function did not need to be installed unless
2892 the user used the @code{parse_printf_format} function. This has changed.
2893 Now a call to any of the @code{printf} functions will call this
2894 function when this format specifier appears in the format string.
2896 The return value is @code{0} on success, and @code{-1} on failure
2897 (which occurs if @var{spec} is out of range).
2899 You can redefine the standard output conversions, but this is probably
2900 not a good idea because of the potential for confusion. Library routines
2901 written by other people could break if you do this.
2904 @node Conversion Specifier Options
2905 @subsection Conversion Specifier Options
2907 If you define a meaning for @samp{%A}, what if the template contains
2908 @samp{%+23A} or @samp{%-#A}? To implement a sensible meaning for these,
2909 the handler when called needs to be able to get the options specified in
2912 Both the @var{handler-function} and @var{arginfo-function} accept an
2913 argument that points to a @code{struct printf_info}, which contains
2914 information about the options appearing in an instance of the conversion
2915 specifier. This data type is declared in the header file
2921 @deftp {Type} {struct printf_info}
2922 This structure is used to pass information about the options appearing
2923 in an instance of a conversion specifier in a @code{printf} template
2924 string to the handler and arginfo functions for that specifier. It
2925 contains the following members:
2929 This is the precision specified. The value is @code{-1} if no precision
2930 was specified. If the precision was given as @samp{*}, the
2931 @code{printf_info} structure passed to the handler function contains the
2932 actual value retrieved from the argument list. But the structure passed
2933 to the arginfo function contains a value of @code{INT_MIN}, since the
2934 actual value is not known.
2937 This is the minimum field width specified. The value is @code{0} if no
2938 width was specified. If the field width was given as @samp{*}, the
2939 @code{printf_info} structure passed to the handler function contains the
2940 actual value retrieved from the argument list. But the structure passed
2941 to the arginfo function contains a value of @code{INT_MIN}, since the
2942 actual value is not known.
2945 This is the conversion specifier character specified. It's stored in
2946 the structure so that you can register the same handler function for
2947 multiple characters, but still have a way to tell them apart when the
2948 handler function is called.
2950 @item unsigned int is_long_double
2951 This is a boolean that is true if the @samp{L}, @samp{ll}, or @samp{q}
2952 type modifier was specified. For integer conversions, this indicates
2953 @code{long long int}, as opposed to @code{long double} for floating
2956 @item unsigned int is_char
2957 This is a boolean that is true if the @samp{hh} type modifier was specified.
2959 @item unsigned int is_short
2960 This is a boolean that is true if the @samp{h} type modifier was specified.
2962 @item unsigned int is_long
2963 This is a boolean that is true if the @samp{l} type modifier was specified.
2965 @item unsigned int alt
2966 This is a boolean that is true if the @samp{#} flag was specified.
2968 @item unsigned int space
2969 This is a boolean that is true if the @samp{ } flag was specified.
2971 @item unsigned int left
2972 This is a boolean that is true if the @samp{-} flag was specified.
2974 @item unsigned int showsign
2975 This is a boolean that is true if the @samp{+} flag was specified.
2977 @item unsigned int group
2978 This is a boolean that is true if the @samp{'} flag was specified.
2980 @item unsigned int extra
2981 This flag has a special meaning depending on the context. It could
2982 be used freely by the user-defined handlers but when called from
2983 the @code{printf} function this variable always contains the value
2986 @item unsigned int wide
2987 This flag is set if the stream is wide oriented.
2990 This is the character to use for padding the output to the minimum field
2991 width. The value is @code{'0'} if the @samp{0} flag was specified, and
2992 @code{' '} otherwise.
2997 @node Defining the Output Handler
2998 @subsection Defining the Output Handler
3000 Now let's look at how to define the handler and arginfo functions
3001 which are passed as arguments to @code{register_printf_function}.
3003 @strong{Compatibility Note:} The interface changed in GNU libc
3004 version 2.0. Previously the third argument was of type
3007 You should define your handler functions with a prototype like:
3010 int @var{function} (FILE *stream, const struct printf_info *info,
3011 const void *const *args)
3014 The @var{stream} argument passed to the handler function is the stream to
3015 which it should write output.
3017 The @var{info} argument is a pointer to a structure that contains
3018 information about the various options that were included with the
3019 conversion in the template string. You should not modify this structure
3020 inside your handler function. @xref{Conversion Specifier Options}, for
3021 a description of this data structure.
3023 @c The following changes some time back. --drepper@gnu, 1996/11/14
3025 @c The @code{ap_pointer} argument is used to pass the tail of the variable
3026 @c argument list containing the values to be printed to your handler.
3027 @c Unlike most other functions that can be passed an explicit variable
3028 @c argument list, this is a @emph{pointer} to a @code{va_list}, rather than
3029 @c the @code{va_list} itself. Thus, you should fetch arguments by
3030 @c means of @code{va_arg (*ap_pointer, @var{type})}.
3032 @c (Passing a pointer here allows the function that calls your handler
3033 @c function to update its own @code{va_list} variable to account for the
3034 @c arguments that your handler processes. @xref{Variadic Functions}.)
3036 The @var{args} is a vector of pointers to the arguments data.
3037 The number of arguments was determined by calling the argument
3038 information function provided by the user.
3040 Your handler function should return a value just like @code{printf}
3041 does: it should return the number of characters it has written, or a
3042 negative value to indicate an error.
3046 @deftp {Data Type} printf_function
3047 This is the data type that a handler function should have.
3050 If you are going to use @w{@code{parse_printf_format}} in your
3051 application, you must also define a function to pass as the
3052 @var{arginfo-function} argument for each new conversion you install with
3053 @code{register_printf_function}.
3055 You have to define these functions with a prototype like:
3058 int @var{function} (const struct printf_info *info,
3059 size_t n, int *argtypes)
3062 The return value from the function should be the number of arguments the
3063 conversion expects. The function should also fill in no more than
3064 @var{n} elements of the @var{argtypes} array with information about the
3065 types of each of these arguments. This information is encoded using the
3066 various @samp{PA_} macros. (You will notice that this is the same
3067 calling convention @code{parse_printf_format} itself uses.)
3071 @deftp {Data Type} printf_arginfo_function
3072 This type is used to describe functions that return information about
3073 the number and type of arguments used by a conversion specifier.
3076 @node Printf Extension Example
3077 @subsection @code{printf} Extension Example
3079 Here is an example showing how to define a @code{printf} handler function.
3080 This program defines a data structure called a @code{Widget} and
3081 defines the @samp{%W} conversion to print information about @w{@code{Widget *}}
3082 arguments, including the pointer value and the name stored in the data
3083 structure. The @samp{%W} conversion supports the minimum field width and
3084 left-justification options, but ignores everything else.
3087 @include rprintf.c.texi
3090 The output produced by this program looks like:
3093 |<Widget 0xffeffb7c: mywidget>|
3094 | <Widget 0xffeffb7c: mywidget>|
3095 |<Widget 0xffeffb7c: mywidget> |
3098 @node Predefined Printf Handlers
3099 @subsection Predefined @code{printf} Handlers
3101 The GNU libc also contains a concrete and useful application of the
3102 @code{printf} handler extension. There are two functions available
3103 which implement a special way to print floating-point numbers.
3107 @deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args})
3108 Print a given floating point number as for the format @code{%f} except
3109 that there is a postfix character indicating the divisor for the
3110 number to make this less than 1000. There are two possible divisors:
3111 powers of 1024 or powers of 1000. Which one is used depends on the
3112 format character specified while registered this handler. If the
3113 character is of lower case, 1024 is used. For upper case characters,
3116 The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes,
3117 etc. The full table is:
3120 @multitable @hsep @vsep {' '} {2^10 (1024)} {zetta} {Upper} {10^24 (1000)}
3121 @item low @tab Multiplier @tab From @tab Upper @tab Multiplier
3122 @item ' ' @tab 1 @tab @tab ' ' @tab 1
3123 @item k @tab 2^10 (1024) @tab kilo @tab K @tab 10^3 (1000)
3124 @item m @tab 2^20 @tab mega @tab M @tab 10^6
3125 @item g @tab 2^30 @tab giga @tab G @tab 10^9
3126 @item t @tab 2^40 @tab tera @tab T @tab 10^12
3127 @item p @tab 2^50 @tab peta @tab P @tab 10^15
3128 @item e @tab 2^60 @tab exa @tab E @tab 10^18
3129 @item z @tab 2^70 @tab zetta @tab Z @tab 10^21
3130 @item y @tab 2^80 @tab yotta @tab Y @tab 10^24
3135 \hbox to\hsize{\hfil\vbox{\offinterlineskip
3137 \halign{\strut#& \vrule#\tabskip=1em plus2em& {\tt#}\hfil& \vrule#& #\hfil& \vrule#& #\hfil& \vrule#& {\tt#}\hfil& \vrule#& #\hfil& \vrule#\tabskip=0pt\cr
3139 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
3140 && \omit low && Multiplier && From && \omit Upper && Multiplier &\cr
3141 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
3143 && {\tt\char32} && 1 && && {\tt\char32} && 1 &\cr
3144 && k && $2^{10} = 1024$ && kilo && K && $10^3 = 1000$ &\cr
3145 && m && $2^{20}$ && mega && M && $10^6$ &\cr
3146 && g && $2^{30}$ && giga && G && $10^9$ &\cr
3147 && t && $2^{40}$ && tera && T && $10^{12}$ &\cr
3148 && p && $2^{50}$ && peta && P && $10^{15}$ &\cr
3149 && e && $2^{60}$ && exa && E && $10^{18}$ &\cr
3150 && z && $2^{70}$ && zetta && Z && $10^{21}$ &\cr
3151 && y && $2^{80}$ && yotta && Y && $10^{24}$ &\cr
3152 \noalign{\hrule}}}\hfil}
3156 The default precision is 3, i.e., 1024 is printed with a lower-case
3157 format character as if it were @code{%.3fk} and will yield @code{1.000k}.
3160 Due to the requirements of @code{register_printf_function} we must also
3161 provide the function which returns information about the arguments.
3165 @deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes})
3166 This function will return in @var{argtypes} the information about the
3167 used parameters in the way the @code{vfprintf} implementation expects
3168 it. The format always takes one argument.
3171 To use these functions both functions must be registered with a call like
3174 register_printf_function ('B', printf_size, printf_size_info);
3177 Here we register the functions to print numbers as powers of 1000 since
3178 the format character @code{'B'} is an upper-case character. If we
3179 would additionally use @code{'b'} in a line like
3182 register_printf_function ('b', printf_size, printf_size_info);
3186 we could also print using a power of 1024. Please note that all that is
3187 different in these two lines is the format specifier. The
3188 @code{printf_size} function knows about the difference between lower and upper
3189 case format specifiers.
3191 The use of @code{'B'} and @code{'b'} is no coincidence. Rather it is
3192 the preferred way to use this functionality since it is available on
3193 some other systems which also use format specifiers.
3195 @node Formatted Input
3196 @section Formatted Input
3198 @cindex formatted input from a stream
3199 @cindex reading from a stream, formatted
3200 @cindex format string, for @code{scanf}
3201 @cindex template, for @code{scanf}
3202 The functions described in this section (@code{scanf} and related
3203 functions) provide facilities for formatted input analogous to the
3204 formatted output facilities. These functions provide a mechanism for
3205 reading arbitrary values under the control of a @dfn{format string} or
3206 @dfn{template string}.
3209 * Formatted Input Basics:: Some basics to get you started.
3210 * Input Conversion Syntax:: Syntax of conversion specifications.
3211 * Table of Input Conversions:: Summary of input conversions and what they do.
3212 * Numeric Input Conversions:: Details of conversions for reading numbers.
3213 * String Input Conversions:: Details of conversions for reading strings.
3214 * Dynamic String Input:: String conversions that @code{malloc} the buffer.
3215 * Other Input Conversions:: Details of miscellaneous other conversions.
3216 * Formatted Input Functions:: Descriptions of the actual functions.
3217 * Variable Arguments Input:: @code{vscanf} and friends.
3220 @node Formatted Input Basics
3221 @subsection Formatted Input Basics
3223 Calls to @code{scanf} are superficially similar to calls to
3224 @code{printf} in that arbitrary arguments are read under the control of
3225 a template string. While the syntax of the conversion specifications in
3226 the template is very similar to that for @code{printf}, the
3227 interpretation of the template is oriented more towards free-format
3228 input and simple pattern matching, rather than fixed-field formatting.
3229 For example, most @code{scanf} conversions skip over any amount of
3230 ``white space'' (including spaces, tabs, and newlines) in the input
3231 file, and there is no concept of precision for the numeric input
3232 conversions as there is for the corresponding output conversions.
3233 Ordinarily, non-whitespace characters in the template are expected to
3234 match characters in the input stream exactly, but a matching failure is
3235 distinct from an input error on the stream.
3236 @cindex conversion specifications (@code{scanf})
3238 Another area of difference between @code{scanf} and @code{printf} is
3239 that you must remember to supply pointers rather than immediate values
3240 as the optional arguments to @code{scanf}; the values that are read are
3241 stored in the objects that the pointers point to. Even experienced
3242 programmers tend to forget this occasionally, so if your program is
3243 getting strange errors that seem to be related to @code{scanf}, you
3244 might want to double-check this.
3246 When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
3247 leaving the first non-matching character as the next character to be
3248 read from the stream. The normal return value from @code{scanf} is the
3249 number of values that were assigned, so you can use this to determine if
3250 a matching error happened before all the expected values were read.
3251 @cindex matching failure, in @code{scanf}
3253 The @code{scanf} function is typically used for things like reading in
3254 the contents of tables. For example, here is a function that uses
3255 @code{scanf} to initialize an array of @code{double}:
3259 readarray (double *array, int n)
3263 if (scanf (" %lf", &(array[i])) != 1)
3264 invalid_input_error ();
3268 The formatted input functions are not used as frequently as the
3269 formatted output functions. Partly, this is because it takes some care
3270 to use them properly. Another reason is that it is difficult to recover
3271 from a matching error.
3273 If you are trying to read input that doesn't match a single, fixed
3274 pattern, you may be better off using a tool such as Flex to generate a
3275 lexical scanner, or Bison to generate a parser, rather than using
3276 @code{scanf}. For more information about these tools, see @ref{Top, , ,
3277 flex.info, Flex: The Lexical Scanner Generator}, and @ref{Top, , ,
3278 bison.info, The Bison Reference Manual}.
3280 @node Input Conversion Syntax
3281 @subsection Input Conversion Syntax
3283 A @code{scanf} template string is a string that contains ordinary
3284 multibyte characters interspersed with conversion specifications that
3285 start with @samp{%}.
3287 Any whitespace character (as defined by the @code{isspace} function;
3288 @pxref{Classification of Characters}) in the template causes any number
3289 of whitespace characters in the input stream to be read and discarded.
3290 The whitespace characters that are matched need not be exactly the same
3291 whitespace characters that appear in the template string. For example,
3292 write @samp{ , } in the template to recognize a comma with optional
3293 whitespace before and after.
3295 Other characters in the template string that are not part of conversion
3296 specifications must match characters in the input stream exactly; if
3297 this is not the case, a matching failure occurs.
3299 The conversion specifications in a @code{scanf} template string
3300 have the general form:
3303 % @var{flags} @var{width} @var{type} @var{conversion}
3306 In more detail, an input conversion specification consists of an initial
3307 @samp{%} character followed in sequence by:
3311 An optional @dfn{flag character} @samp{*}, which says to ignore the text
3312 read for this specification. When @code{scanf} finds a conversion
3313 specification that uses this flag, it reads input as directed by the
3314 rest of the conversion specification, but it discards this input, does
3315 not use a pointer argument, and does not increment the count of
3316 successful assignments.
3317 @cindex flag character (@code{scanf})
3320 An optional flag character @samp{a} (valid with string conversions only)
3321 which requests allocation of a buffer long enough to store the string in.
3322 (This is a GNU extension.)
3323 @xref{Dynamic String Input}.
3326 An optional decimal integer that specifies the @dfn{maximum field
3327 width}. Reading of characters from the input stream stops either when
3328 this maximum is reached or when a non-matching character is found,
3329 whichever happens first. Most conversions discard initial whitespace
3330 characters (those that don't are explicitly documented), and these
3331 discarded characters don't count towards the maximum field width.
3332 String input conversions store a null character to mark the end of the
3333 input; the maximum field width does not include this terminator.
3334 @cindex maximum field width (@code{scanf})
3337 An optional @dfn{type modifier character}. For example, you can
3338 specify a type modifier of @samp{l} with integer conversions such as
3339 @samp{%d} to specify that the argument is a pointer to a @code{long int}
3340 rather than a pointer to an @code{int}.
3341 @cindex type modifier character (@code{scanf})
3344 A character that specifies the conversion to be applied.
3347 The exact options that are permitted and how they are interpreted vary
3348 between the different conversion specifiers. See the descriptions of the
3349 individual conversions for information about the particular options that
3352 With the @samp{-Wformat} option, the GNU C compiler checks calls to
3353 @code{scanf} and related functions. It examines the format string and
3354 verifies that the correct number and types of arguments are supplied.
3355 There is also a GNU C syntax to tell the compiler that a function you
3356 write uses a @code{scanf}-style format string.
3357 @xref{Function Attributes, , Declaring Attributes of Functions,
3358 gcc.info, Using GNU CC}, for more information.
3360 @node Table of Input Conversions
3361 @subsection Table of Input Conversions
3362 @cindex input conversions, for @code{scanf}
3364 Here is a table that summarizes the various conversion specifications:
3368 Matches an optionally signed integer written in decimal. @xref{Numeric
3372 Matches an optionally signed integer in any of the formats that the C
3373 language defines for specifying an integer constant. @xref{Numeric
3377 Matches an unsigned integer written in octal radix.
3378 @xref{Numeric Input Conversions}.
3381 Matches an unsigned integer written in decimal radix.
3382 @xref{Numeric Input Conversions}.
3384 @item @samp{%x}, @samp{%X}
3385 Matches an unsigned integer written in hexadecimal radix.
3386 @xref{Numeric Input Conversions}.
3388 @item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
3389 Matches an optionally signed floating-point number. @xref{Numeric Input
3394 Matches a string containing only non-whitespace characters.
3395 @xref{String Input Conversions}. The presence of the @samp{l} modifier
3396 determines whether the output is stored as a wide character string or a
3397 multibyte string. If @samp{%s} is used in a wide character function the
3398 string is converted as with multiple calls to @code{wcrtomb} into a
3399 multibyte string. This means that the buffer must provide room for
3400 @code{MB_CUR_MAX} bytes for each wide character read. In case
3401 @samp{%ls} is used in a multibyte function the result is converted into
3402 wide characters as with multiple calls of @code{mbrtowc} before being
3403 stored in the user provided buffer.
3406 This is an alias for @samp{%ls} which is supported for compatibility
3407 with the Unix standard.
3410 Matches a string of characters that belong to a specified set.
3411 @xref{String Input Conversions}. The presence of the @samp{l} modifier
3412 determines whether the output is stored as a wide character string or a
3413 multibyte string. If @samp{%[} is used in a wide character function the
3414 string is converted as with multiple calls to @code{wcrtomb} into a
3415 multibyte string. This means that the buffer must provide room for
3416 @code{MB_CUR_MAX} bytes for each wide character read. In case
3417 @samp{%l[} is used in a multibyte function the result is converted into
3418 wide characters as with multiple calls of @code{mbrtowc} before being
3419 stored in the user provided buffer.
3422 Matches a string of one or more characters; the number of characters
3423 read is controlled by the maximum field width given for the conversion.
3424 @xref{String Input Conversions}.
3426 If the @samp{%c} is used in a wide stream function the read value is
3427 converted from a wide character to the corresponding multibyte character
3428 before storing it. Note that this conversion can produce more than one
3429 byte of output and therefore the provided buffer be large enough for up
3430 to @code{MB_CUR_MAX} bytes for each character. If @samp{%lc} is used in
3431 a multibyte function the input is treated as a multibyte sequence (and
3432 not bytes) and the result is converted as with calls to @code{mbrtowc}.
3435 This is an alias for @samp{%lc} which is supported for compatibility
3436 with the Unix standard.
3439 Matches a pointer value in the same implementation-defined format used
3440 by the @samp{%p} output conversion for @code{printf}. @xref{Other Input
3444 This conversion doesn't read any characters; it records the number of
3445 characters read so far by this call. @xref{Other Input Conversions}.
3448 This matches a literal @samp{%} character in the input stream. No
3449 corresponding argument is used. @xref{Other Input Conversions}.
3452 If the syntax of a conversion specification is invalid, the behavior is
3453 undefined. If there aren't enough function arguments provided to supply
3454 addresses for all the conversion specifications in the template strings
3455 that perform assignments, or if the arguments are not of the correct
3456 types, the behavior is also undefined. On the other hand, extra
3457 arguments are simply ignored.
3459 @node Numeric Input Conversions
3460 @subsection Numeric Input Conversions
3462 This section describes the @code{scanf} conversions for reading numeric
3465 The @samp{%d} conversion matches an optionally signed integer in decimal
3466 radix. The syntax that is recognized is the same as that for the
3467 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3468 @code{10} for the @var{base} argument.
3470 The @samp{%i} conversion matches an optionally signed integer in any of
3471 the formats that the C language defines for specifying an integer
3472 constant. The syntax that is recognized is the same as that for the
3473 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3474 @code{0} for the @var{base} argument. (You can print integers in this
3475 syntax with @code{printf} by using the @samp{#} flag character with the
3476 @samp{%x}, @samp{%o}, or @samp{%d} conversion. @xref{Integer Conversions}.)
3478 For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
3479 could be read in as integers under the @samp{%i} conversion. Each of
3480 these specifies a number with decimal value @code{10}.
3482 The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned
3483 integers in octal, decimal, and hexadecimal radices, respectively. The
3484 syntax that is recognized is the same as that for the @code{strtoul}
3485 function (@pxref{Parsing of Integers}) with the appropriate value
3486 (@code{8}, @code{10}, or @code{16}) for the @var{base} argument.
3488 The @samp{%X} conversion is identical to the @samp{%x} conversion. They
3489 both permit either uppercase or lowercase letters to be used as digits.
3491 The default type of the corresponding argument for the @code{%d} and
3492 @code{%i} conversions is @code{int *}, and @code{unsigned int *} for the
3493 other integer conversions. You can use the following type modifiers to
3494 specify other sizes of integer:
3498 Specifies that the argument is a @code{signed char *} or @code{unsigned
3501 This modifier was introduced in @w{ISO C99}.
3504 Specifies that the argument is a @code{short int *} or @code{unsigned
3508 Specifies that the argument is a @code{intmax_t *} or @code{uintmax_t *}.
3510 This modifier was introduced in @w{ISO C99}.
3513 Specifies that the argument is a @code{long int *} or @code{unsigned
3514 long int *}. Two @samp{l} characters is like the @samp{L} modifier, below.
3516 If used with @samp{%c} or @samp{%s} the corresponding parameter is
3517 considered as a pointer to a wide character or wide character string
3518 respectively. This use of @samp{l} was introduced in @w{Amendment 1} to
3525 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
3526 GNU C compiler. For systems that don't provide extra-long integers, this
3527 is the same as @code{long int}.)
3529 The @samp{q} modifier is another name for the same thing, which comes
3530 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
3534 Specifies that the argument is a @code{ptrdiff_t *}.
3536 This modifier was introduced in @w{ISO C99}.
3539 Specifies that the argument is a @code{size_t *}.
3541 This modifier was introduced in @w{ISO C99}.
3544 All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
3545 input conversions are interchangeable. They all match an optionally
3546 signed floating point number, in the same syntax as for the
3547 @code{strtod} function (@pxref{Parsing of Floats}).
3549 For the floating-point input conversions, the default argument type is
3550 @code{float *}. (This is different from the corresponding output
3551 conversions, where the default type is @code{double}; remember that
3552 @code{float} arguments to @code{printf} are converted to @code{double}
3553 by the default argument promotions, but @code{float *} arguments are
3554 not promoted to @code{double *}.) You can specify other sizes of float
3555 using these type modifiers:
3559 Specifies that the argument is of type @code{double *}.
3562 Specifies that the argument is of type @code{long double *}.
3565 For all the above number parsing formats there is an additional optional
3566 flag @samp{'}. When this flag is given the @code{scanf} function
3567 expects the number represented in the input string to be formatted
3568 according to the grouping rules of the currently selected locale
3569 (@pxref{General Numeric}).
3571 If the @code{"C"} or @code{"POSIX"} locale is selected there is no
3572 difference. But for a locale which specifies values for the appropriate
3573 fields in the locale the input must have the correct form in the input.
3574 Otherwise the longest prefix with a correct form is processed.
3576 @node String Input Conversions
3577 @subsection String Input Conversions
3579 This section describes the @code{scanf} input conversions for reading
3580 string and character values: @samp{%s}, @samp{%S}, @samp{%[}, @samp{%c},
3583 You have two options for how to receive the input from these
3588 Provide a buffer to store it in. This is the default. You should
3589 provide an argument of type @code{char *} or @code{wchar_t *} (the
3590 latter of the @samp{l} modifier is present).
3592 @strong{Warning:} To make a robust program, you must make sure that the
3593 input (plus its terminating null) cannot possibly exceed the size of the
3594 buffer you provide. In general, the only way to do this is to specify a
3595 maximum field width one less than the buffer size. @strong{If you
3596 provide the buffer, always specify a maximum field width to prevent
3600 Ask @code{scanf} to allocate a big enough buffer, by specifying the
3601 @samp{a} flag character. This is a GNU extension. You should provide
3602 an argument of type @code{char **} for the buffer address to be stored
3603 in. @xref{Dynamic String Input}.
3606 The @samp{%c} conversion is the simplest: it matches a fixed number of
3607 characters, always. The maximum field width says how many characters to
3608 read; if you don't specify the maximum, the default is 1. This
3609 conversion doesn't append a null character to the end of the text it
3610 reads. It also does not skip over initial whitespace characters. It
3611 reads precisely the next @var{n} characters, and fails if it cannot get
3612 that many. Since there is always a maximum field width with @samp{%c}
3613 (whether specified, or 1 by default), you can always prevent overflow by
3614 making the buffer long enough.
3615 @comment Is character == byte here??? --drepper
3617 If the format is @samp{%lc} or @samp{%C} the function stores wide
3618 characters which are converted using the conversion determined at the
3619 time the stream was opened from the external byte stream. The number of
3620 bytes read from the medium is limited by @code{MB_CUR_LEN * @var{n}} but
3621 at most @var{n} wide character get stored in the output string.
3623 The @samp{%s} conversion matches a string of non-whitespace characters.
3624 It skips and discards initial whitespace, but stops when it encounters
3625 more whitespace after having read something. It stores a null character
3626 at the end of the text that it reads.
3628 For example, reading the input:
3635 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
3636 reading the same input with the conversion @samp{%10s} produces
3639 @strong{Warning:} If you do not specify a field width for @samp{%s},
3640 then the number of characters read is limited only by where the next
3641 whitespace character appears. This almost certainly means that invalid
3642 input can make your program crash---which is a bug.
3644 The @samp{%ls} and @samp{%S} format are handled just like @samp{%s}
3645 except that the external byte sequence is converted using the conversion
3646 associated with the stream to wide characters with their own encoding.
3647 A width or precision specified with the format do not directly determine
3648 how many bytes are read from the stream since they measure wide
3649 characters. But an upper limit can be computed by multiplying the value
3650 of the width or precision by @code{MB_CUR_MAX}.
3652 To read in characters that belong to an arbitrary set of your choice,
3653 use the @samp{%[} conversion. You specify the set between the @samp{[}
3654 character and a following @samp{]} character, using the same syntax used
3655 in regular expressions. As special cases:
3659 A literal @samp{]} character can be specified as the first character
3663 An embedded @samp{-} character (that is, one that is not the first or
3664 last character of the set) is used to specify a range of characters.
3667 If a caret character @samp{^} immediately follows the initial @samp{[},
3668 then the set of allowed input characters is the everything @emph{except}
3669 the characters listed.
3672 The @samp{%[} conversion does not skip over initial whitespace
3675 Here are some examples of @samp{%[} conversions and what they mean:
3678 @item %25[1234567890]
3679 Matches a string of up to 25 digits.
3682 Matches a string of up to 25 square brackets.
3684 @item %25[^ \f\n\r\t\v]
3685 Matches a string up to 25 characters long that doesn't contain any of
3686 the standard whitespace characters. This is slightly different from
3687 @samp{%s}, because if the input begins with a whitespace character,
3688 @samp{%[} reports a matching failure while @samp{%s} simply discards the
3692 Matches up to 25 lowercase characters.
3695 As for @samp{%c} and @samp{%s} the @samp{%[} format is also modified to
3696 produce wide characters if the @samp{l} modifier is present. All what
3697 is said about @samp{%ls} above is true for @samp{%l[}.
3699 One more reminder: the @samp{%s} and @samp{%[} conversions are
3700 @strong{dangerous} if you don't specify a maximum width or use the
3701 @samp{a} flag, because input too long would overflow whatever buffer you
3702 have provided for it. No matter how long your buffer is, a user could
3703 supply input that is longer. A well-written program reports invalid
3704 input with a comprehensible error message, not with a crash.
3706 @node Dynamic String Input
3707 @subsection Dynamically Allocating String Conversions
3709 A GNU extension to formatted input lets you safely read a string with no
3710 maximum size. Using this feature, you don't supply a buffer; instead,
3711 @code{scanf} allocates a buffer big enough to hold the data and gives
3712 you its address. To use this feature, write @samp{a} as a flag
3713 character, as in @samp{%as} or @samp{%a[0-9a-z]}.
3715 The pointer argument you supply for where to store the input should have
3716 type @code{char **}. The @code{scanf} function allocates a buffer and
3717 stores its address in the word that the argument points to. You should
3718 free the buffer with @code{free} when you no longer need it.
3720 Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]}
3721 conversion specification to read a ``variable assignment'' of the form
3722 @samp{@var{variable} = @var{value}}.
3726 char *variable, *value;
3728 if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
3731 invalid_input_error ();
3739 @node Other Input Conversions
3740 @subsection Other Input Conversions
3742 This section describes the miscellaneous input conversions.
3744 The @samp{%p} conversion is used to read a pointer value. It recognizes
3745 the same syntax used by the @samp{%p} output conversion for
3746 @code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
3747 number just as the @samp{%x} conversion accepts. The corresponding
3748 argument should be of type @code{void **}; that is, the address of a
3749 place to store a pointer.
3751 The resulting pointer value is not guaranteed to be valid if it was not
3752 originally written during the same program execution that reads it in.
3754 The @samp{%n} conversion produces the number of characters read so far
3755 by this call. The corresponding argument should be of type @code{int *}.
3756 This conversion works in the same way as the @samp{%n} conversion for
3757 @code{printf}; see @ref{Other Output Conversions}, for an example.
3759 The @samp{%n} conversion is the only mechanism for determining the
3760 success of literal matches or conversions with suppressed assignments.
3761 If the @samp{%n} follows the locus of a matching failure, then no value
3762 is stored for it since @code{scanf} returns before processing the
3763 @samp{%n}. If you store @code{-1} in that argument slot before calling
3764 @code{scanf}, the presence of @code{-1} after @code{scanf} indicates an
3765 error occurred before the @samp{%n} was reached.
3767 Finally, the @samp{%%} conversion matches a literal @samp{%} character
3768 in the input stream, without using an argument. This conversion does
3769 not permit any flags, field width, or type modifier to be specified.
3771 @node Formatted Input Functions
3772 @subsection Formatted Input Functions
3774 Here are the descriptions of the functions for performing formatted
3776 Prototypes for these functions are in the header file @file{stdio.h}.
3781 @deftypefun int scanf (const char *@var{template}, @dots{})
3782 The @code{scanf} function reads formatted input from the stream
3783 @code{stdin} under the control of the template string @var{template}.
3784 The optional arguments are pointers to the places which receive the
3787 The return value is normally the number of successful assignments. If
3788 an end-of-file condition is detected before any matches are performed,
3789 including matches against whitespace and literal characters in the
3790 template, then @code{EOF} is returned.
3795 @deftypefun int wscanf (const wchar_t *@var{template}, @dots{})
3796 The @code{wscanf} function reads formatted input from the stream
3797 @code{stdin} under the control of the template string @var{template}.
3798 The optional arguments are pointers to the places which receive the
3801 The return value is normally the number of successful assignments. If
3802 an end-of-file condition is detected before any matches are performed,
3803 including matches against whitespace and literal characters in the
3804 template, then @code{WEOF} is returned.
3809 @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
3810 This function is just like @code{scanf}, except that the input is read
3811 from the stream @var{stream} instead of @code{stdin}.
3816 @deftypefun int fwscanf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
3817 This function is just like @code{wscanf}, except that the input is read
3818 from the stream @var{stream} instead of @code{stdin}.
3823 @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
3824 This is like @code{scanf}, except that the characters are taken from the
3825 null-terminated string @var{s} instead of from a stream. Reaching the
3826 end of the string is treated as an end-of-file condition.
3828 The behavior of this function is undefined if copying takes place
3829 between objects that overlap---for example, if @var{s} is also given
3830 as an argument to receive a string read under control of the @samp{%s},
3831 @samp{%S}, or @samp{%[} conversion.
3836 @deftypefun int swscanf (const wchar_t *@var{ws}, const char *@var{template}, @dots{})
3837 This is like @code{wscanf}, except that the characters are taken from the
3838 null-terminated string @var{ws} instead of from a stream. Reaching the
3839 end of the string is treated as an end-of-file condition.
3841 The behavior of this function is undefined if copying takes place
3842 between objects that overlap---for example, if @var{ws} is also given as
3843 an argument to receive a string read under control of the @samp{%s},
3844 @samp{%S}, or @samp{%[} conversion.
3847 @node Variable Arguments Input
3848 @subsection Variable Arguments Input Functions
3850 The functions @code{vscanf} and friends are provided so that you can
3851 define your own variadic @code{scanf}-like functions that make use of
3852 the same internals as the built-in formatted output functions.
3853 These functions are analogous to the @code{vprintf} series of output
3854 functions. @xref{Variable Arguments Output}, for important
3855 information on how to use them.
3857 @strong{Portability Note:} The functions listed in this section were
3858 introduced in @w{ISO C99} and were before available as GNU extensions.
3862 @deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
3863 This function is similar to @code{scanf}, but instead of taking
3864 a variable number of arguments directly, it takes an argument list
3865 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
3870 @deftypefun int vwscanf (const wchar_t *@var{template}, va_list @var{ap})
3871 This function is similar to @code{wscanf}, but instead of taking
3872 a variable number of arguments directly, it takes an argument list
3873 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
3878 @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
3879 This is the equivalent of @code{fscanf} with the variable argument list
3880 specified directly as for @code{vscanf}.
3885 @deftypefun int vfwscanf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
3886 This is the equivalent of @code{fwscanf} with the variable argument list
3887 specified directly as for @code{vwscanf}.
3892 @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
3893 This is the equivalent of @code{sscanf} with the variable argument list
3894 specified directly as for @code{vscanf}.
3899 @deftypefun int vswscanf (const wchar_t *@var{s}, const wchar_t *@var{template}, va_list @var{ap})
3900 This is the equivalent of @code{swscanf} with the variable argument list
3901 specified directly as for @code{vwscanf}.
3904 In GNU C, there is a special construct you can use to let the compiler
3905 know that a function uses a @code{scanf}-style format string. Then it
3906 can check the number and types of arguments in each call to the
3907 function, and warn you when they do not match the format string.
3908 For details, see @ref{Function Attributes, , Declaring Attributes of Functions,
3909 gcc.info, Using GNU CC}.
3911 @node EOF and Errors
3912 @section End-Of-File and Errors
3914 @cindex end of file, on a stream
3915 Many of the functions described in this chapter return the value of the
3916 macro @code{EOF} to indicate unsuccessful completion of the operation.
3917 Since @code{EOF} is used to report both end of file and random errors,
3918 it's often better to use the @code{feof} function to check explicitly
3919 for end of file and @code{ferror} to check for errors. These functions
3920 check indicators that are part of the internal state of the stream
3921 object, indicators set if the appropriate condition was detected by a
3922 previous I/O operation on that stream.
3926 @deftypevr Macro int EOF
3927 This macro is an integer value that is returned by a number of narrow
3928 stream functions to indicate an end-of-file condition, or some other
3929 error situation. With the GNU library, @code{EOF} is @code{-1}. In
3930 other libraries, its value may be some other negative number.
3932 This symbol is declared in @file{stdio.h}.
3937 @deftypevr Macro int WEOF
3938 This macro is an integer value that is returned by a number of wide
3939 stream functions to indicate an end-of-file condition, or some other
3940 error situation. With the GNU library, @code{WEOF} is @code{-1}. In
3941 other libraries, its value may be some other negative number.
3943 This symbol is declared in @file{wchar.h}.
3948 @deftypefun int feof (FILE *@var{stream})
3949 The @code{feof} function returns nonzero if and only if the end-of-file
3950 indicator for the stream @var{stream} is set.
3952 This symbol is declared in @file{stdio.h}.
3957 @deftypefun int feof_unlocked (FILE *@var{stream})
3958 The @code{feof_unlocked} function is equivalent to the @code{feof}
3959 function except that it does not implicitly lock the stream.
3961 This function is a GNU extension.
3963 This symbol is declared in @file{stdio.h}.
3968 @deftypefun int ferror (FILE *@var{stream})
3969 The @code{ferror} function returns nonzero if and only if the error
3970 indicator for the stream @var{stream} is set, indicating that an error
3971 has occurred on a previous operation on the stream.
3973 This symbol is declared in @file{stdio.h}.
3978 @deftypefun int ferror_unlocked (FILE *@var{stream})
3979 The @code{ferror_unlocked} function is equivalent to the @code{ferror}
3980 function except that it does not implicitly lock the stream.
3982 This function is a GNU extension.
3984 This symbol is declared in @file{stdio.h}.
3987 In addition to setting the error indicator associated with the stream,
3988 the functions that operate on streams also set @code{errno} in the same
3989 way as the corresponding low-level functions that operate on file
3990 descriptors. For example, all of the functions that perform output to a
3991 stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are
3992 implemented in terms of @code{write}, and all of the @code{errno} error
3993 conditions defined for @code{write} are meaningful for these functions.
3994 For more information about the descriptor-level I/O functions, see
3995 @ref{Low-Level I/O}.
3997 @node Error Recovery
3998 @section Recovering from errors
4000 You may explicitly clear the error and EOF flags with the @code{clearerr}
4005 @deftypefun void clearerr (FILE *@var{stream})
4006 This function clears the end-of-file and error indicators for the
4007 stream @var{stream}.
4009 The file positioning functions (@pxref{File Positioning}) also clear the
4010 end-of-file indicator for the stream.
4015 @deftypefun void clearerr_unlocked (FILE *@var{stream})
4016 The @code{clearerr_unlocked} function is equivalent to the @code{clearerr}
4017 function except that it does not implicitly lock the stream.
4019 This function is a GNU extension.
4022 Note that it is @emph{not} correct to just clear the error flag and retry
4023 a failed stream operation. After a failed write, any number of
4024 characters since the last buffer flush may have been committed to the
4025 file, while some buffered data may have been discarded. Merely retrying
4026 can thus cause lost or repeated data.
4028 A failed read may leave the file pointer in an inappropriate position for
4029 a second try. In both cases, you should seek to a known position before
4032 Most errors that can happen are not recoverable --- a second try will
4033 always fail again in the same way. So usually it is best to give up and
4034 report the error to the user, rather than install complicated recovery
4037 One important exception is @code{EINTR} (@pxref{Interrupted Primitives}).
4038 Many stream I/O implementations will treat it as an ordinary error, which
4039 can be quite inconvenient. You can avoid this hassle by installing all
4040 signals with the @code{SA_RESTART} flag.
4042 For similar reasons, setting nonblocking I/O on a stream's file
4043 descriptor is not usually advisable.
4045 @node Binary Streams
4046 @section Text and Binary Streams
4048 The GNU system and other POSIX-compatible operating systems organize all
4049 files as uniform sequences of characters. However, some other systems
4050 make a distinction between files containing text and files containing
4051 binary data, and the input and output facilities of @w{ISO C} provide for
4052 this distinction. This section tells you how to write programs portable
4056 @cindex binary stream
4057 When you open a stream, you can specify either a @dfn{text stream} or a
4058 @dfn{binary stream}. You indicate that you want a binary stream by
4059 specifying the @samp{b} modifier in the @var{opentype} argument to
4060 @code{fopen}; see @ref{Opening Streams}. Without this
4061 option, @code{fopen} opens the file as a text stream.
4063 Text and binary streams differ in several ways:
4067 The data read from a text stream is divided into @dfn{lines} which are
4068 terminated by newline (@code{'\n'}) characters, while a binary stream is
4069 simply a long series of characters. A text stream might on some systems
4070 fail to handle lines more than 254 characters long (including the
4071 terminating newline character).
4072 @cindex lines (in a text file)
4075 On some systems, text files can contain only printing characters,
4076 horizontal tab characters, and newlines, and so text streams may not
4077 support other characters. However, binary streams can handle any
4081 Space characters that are written immediately preceding a newline
4082 character in a text stream may disappear when the file is read in again.
4085 More generally, there need not be a one-to-one mapping between
4086 characters that are read from or written to a text stream, and the
4087 characters in the actual file.
4090 Since a binary stream is always more capable and more predictable than a
4091 text stream, you might wonder what purpose text streams serve. Why not
4092 simply always use binary streams? The answer is that on these operating
4093 systems, text and binary streams use different file formats, and the
4094 only way to read or write ``an ordinary file of text'' that can work
4095 with other text-oriented programs is through a text stream.
4097 In the GNU library, and on all POSIX systems, there is no difference
4098 between text streams and binary streams. When you open a stream, you
4099 get the same kind of stream regardless of whether you ask for binary.
4100 This stream can handle any file content, and has none of the
4101 restrictions that text streams sometimes have.
4103 @node File Positioning
4104 @section File Positioning
4105 @cindex file positioning on a stream
4106 @cindex positioning a stream
4107 @cindex seeking on a stream
4109 The @dfn{file position} of a stream describes where in the file the
4110 stream is currently reading or writing. I/O on the stream advances the
4111 file position through the file. In the GNU system, the file position is
4112 represented as an integer, which counts the number of bytes from the
4113 beginning of the file. @xref{File Position}.
4115 During I/O to an ordinary disk file, you can change the file position
4116 whenever you wish, so as to read or write any portion of the file. Some
4117 other kinds of files may also permit this. Files which support changing
4118 the file position are sometimes referred to as @dfn{random-access}
4121 You can use the functions in this section to examine or modify the file
4122 position indicator associated with a stream. The symbols listed below
4123 are declared in the header file @file{stdio.h}.
4128 @deftypefun {long int} ftell (FILE *@var{stream})
4129 This function returns the current file position of the stream
4132 This function can fail if the stream doesn't support file positioning,
4133 or if the file position can't be represented in a @code{long int}, and
4134 possibly for other reasons as well. If a failure occurs, a value of
4135 @code{-1} is returned.
4140 @deftypefun off_t ftello (FILE *@var{stream})
4141 The @code{ftello} function is similar to @code{ftell}, except that it
4142 returns a value of type @code{off_t}. Systems which support this type
4143 use it to describe all file positions, unlike the POSIX specification
4144 which uses a long int. The two are not necessarily the same size.
4145 Therefore, using ftell can lead to problems if the implementation is
4146 written on top of a POSIX compliant low-level I/O implementation, and using
4147 @code{ftello} is preferable whenever it is available.
4149 If this function fails it returns @code{(off_t) -1}. This can happen due
4150 to missing support for file positioning or internal errors. Otherwise
4151 the return value is the current file position.
4153 The function is an extension defined in the Unix Single Specification
4156 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4157 32 bit system this function is in fact @code{ftello64}. I.e., the
4158 LFS interface transparently replaces the old interface.
4163 @deftypefun off64_t ftello64 (FILE *@var{stream})
4164 This function is similar to @code{ftello} with the only difference that
4165 the return value is of type @code{off64_t}. This also requires that the
4166 stream @var{stream} was opened using either @code{fopen64},
4167 @code{freopen64}, or @code{tmpfile64} since otherwise the underlying
4168 file operations to position the file pointer beyond the @math{2^31}
4169 bytes limit might fail.
4171 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4172 bits machine this function is available under the name @code{ftello}
4173 and so transparently replaces the old interface.
4178 @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
4179 The @code{fseek} function is used to change the file position of the
4180 stream @var{stream}. The value of @var{whence} must be one of the
4181 constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
4182 indicate whether the @var{offset} is relative to the beginning of the
4183 file, the current file position, or the end of the file, respectively.
4185 This function returns a value of zero if the operation was successful,
4186 and a nonzero value to indicate failure. A successful call also clears
4187 the end-of-file indicator of @var{stream} and discards any characters
4188 that were ``pushed back'' by the use of @code{ungetc}.
4190 @code{fseek} either flushes any buffered output before setting the file
4191 position or else remembers it so it will be written later in its proper
4197 @deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence})
4198 This function is similar to @code{fseek} but it corrects a problem with
4199 @code{fseek} in a system with POSIX types. Using a value of type
4200 @code{long int} for the offset is not compatible with POSIX.
4201 @code{fseeko} uses the correct type @code{off_t} for the @var{offset}
4204 For this reason it is a good idea to prefer @code{ftello} whenever it is
4205 available since its functionality is (if different at all) closer the
4206 underlying definition.
4208 The functionality and return value is the same as for @code{fseek}.
4210 The function is an extension defined in the Unix Single Specification
4213 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4214 32 bit system this function is in fact @code{fseeko64}. I.e., the
4215 LFS interface transparently replaces the old interface.
4220 @deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence})
4221 This function is similar to @code{fseeko} with the only difference that
4222 the @var{offset} parameter is of type @code{off64_t}. This also
4223 requires that the stream @var{stream} was opened using either
4224 @code{fopen64}, @code{freopen64}, or @code{tmpfile64} since otherwise
4225 the underlying file operations to position the file pointer beyond the
4226 @math{2^31} bytes limit might fail.
4228 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4229 bits machine this function is available under the name @code{fseeko}
4230 and so transparently replaces the old interface.
4233 @strong{Portability Note:} In non-POSIX systems, @code{ftell},
4234 @code{ftello}, @code{fseek} and @code{fseeko} might work reliably only
4235 on binary streams. @xref{Binary Streams}.
4237 The following symbolic constants are defined for use as the @var{whence}
4238 argument to @code{fseek}. They are also used with the @code{lseek}
4239 function (@pxref{I/O Primitives}) and to specify offsets for file locks
4240 (@pxref{Control Operations}).
4244 @deftypevr Macro int SEEK_SET
4245 This is an integer constant which, when used as the @var{whence}
4246 argument to the @code{fseek} or @code{fseeko} function, specifies that
4247 the offset provided is relative to the beginning of the file.
4252 @deftypevr Macro int SEEK_CUR
4253 This is an integer constant which, when used as the @var{whence}
4254 argument to the @code{fseek} or @code{fseeko} function, specifies that
4255 the offset provided is relative to the current file position.
4260 @deftypevr Macro int SEEK_END
4261 This is an integer constant which, when used as the @var{whence}
4262 argument to the @code{fseek} or @code{fseeko} function, specifies that
4263 the offset provided is relative to the end of the file.
4268 @deftypefun void rewind (FILE *@var{stream})
4269 The @code{rewind} function positions the stream @var{stream} at the
4270 beginning of the file. It is equivalent to calling @code{fseek} or
4271 @code{fseeko} on the @var{stream} with an @var{offset} argument of
4272 @code{0L} and a @var{whence} argument of @code{SEEK_SET}, except that
4273 the return value is discarded and the error indicator for the stream is
4277 These three aliases for the @samp{SEEK_@dots{}} constants exist for the
4278 sake of compatibility with older BSD systems. They are defined in two
4279 different header files: @file{fcntl.h} and @file{sys/file.h}.
4286 An alias for @code{SEEK_SET}.
4292 An alias for @code{SEEK_CUR}.
4298 An alias for @code{SEEK_END}.
4301 @node Portable Positioning
4302 @section Portable File-Position Functions
4304 On the GNU system, the file position is truly a character count. You
4305 can specify any character count value as an argument to @code{fseek} or
4306 @code{fseeko} and get reliable results for any random access file.
4307 However, some @w{ISO C} systems do not represent file positions in this
4310 On some systems where text streams truly differ from binary streams, it
4311 is impossible to represent the file position of a text stream as a count
4312 of characters from the beginning of the file. For example, the file
4313 position on some systems must encode both a record offset within the
4314 file, and a character offset within the record.
4316 As a consequence, if you want your programs to be portable to these
4317 systems, you must observe certain rules:
4321 The value returned from @code{ftell} on a text stream has no predictable
4322 relationship to the number of characters you have read so far. The only
4323 thing you can rely on is that you can use it subsequently as the
4324 @var{offset} argument to @code{fseek} or @code{fseeko} to move back to
4325 the same file position.
4328 In a call to @code{fseek} or @code{fseeko} on a text stream, either the
4329 @var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and
4330 the @var{offset} must be the result of an earlier call to @code{ftell}
4334 The value of the file position indicator of a text stream is undefined
4335 while there are characters that have been pushed back with @code{ungetc}
4336 that haven't been read or discarded. @xref{Unreading}.
4339 But even if you observe these rules, you may still have trouble for long
4340 files, because @code{ftell} and @code{fseek} use a @code{long int} value
4341 to represent the file position. This type may not have room to encode
4342 all the file positions in a large file. Using the @code{ftello} and
4343 @code{fseeko} functions might help here since the @code{off_t} type is
4344 expected to be able to hold all file position values but this still does
4345 not help to handle additional information which must be associated with
4348 So if you do want to support systems with peculiar encodings for the
4349 file positions, it is better to use the functions @code{fgetpos} and
4350 @code{fsetpos} instead. These functions represent the file position
4351 using the data type @code{fpos_t}, whose internal representation varies
4352 from system to system.
4354 These symbols are declared in the header file @file{stdio.h}.
4359 @deftp {Data Type} fpos_t
4360 This is the type of an object that can encode information about the
4361 file position of a stream, for use by the functions @code{fgetpos} and
4364 In the GNU system, @code{fpos_t} is an opaque data structure that
4365 contains internal data to represent file offset and conversion state
4366 information. In other systems, it might have a different internal
4369 When compiling with @code{_FILE_OFFSET_BITS == 64} on a 32 bit machine
4370 this type is in fact equivalent to @code{fpos64_t} since the LFS
4371 interface transparently replaces the old interface.
4376 @deftp {Data Type} fpos64_t
4377 This is the type of an object that can encode information about the
4378 file position of a stream, for use by the functions @code{fgetpos64} and
4381 In the GNU system, @code{fpos64_t} is an opaque data structure that
4382 contains internal data to represent file offset and conversion state
4383 information. In other systems, it might have a different internal
4389 @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
4390 This function stores the value of the file position indicator for the
4391 stream @var{stream} in the @code{fpos_t} object pointed to by
4392 @var{position}. If successful, @code{fgetpos} returns zero; otherwise
4393 it returns a nonzero value and stores an implementation-defined positive
4394 value in @code{errno}.
4396 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4397 32 bit system the function is in fact @code{fgetpos64}. I.e., the LFS
4398 interface transparently replaces the old interface.
4403 @deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position})
4404 This function is similar to @code{fgetpos} but the file position is
4405 returned in a variable of type @code{fpos64_t} to which @var{position}
4408 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4409 bits machine this function is available under the name @code{fgetpos}
4410 and so transparently replaces the old interface.
4415 @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position})
4416 This function sets the file position indicator for the stream @var{stream}
4417 to the position @var{position}, which must have been set by a previous
4418 call to @code{fgetpos} on the same stream. If successful, @code{fsetpos}
4419 clears the end-of-file indicator on the stream, discards any characters
4420 that were ``pushed back'' by the use of @code{ungetc}, and returns a value
4421 of zero. Otherwise, @code{fsetpos} returns a nonzero value and stores
4422 an implementation-defined positive value in @code{errno}.
4424 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4425 32 bit system the function is in fact @code{fsetpos64}. I.e., the LFS
4426 interface transparently replaces the old interface.
4431 @deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position})
4432 This function is similar to @code{fsetpos} but the file position used
4433 for positioning is provided in a variable of type @code{fpos64_t} to
4434 which @var{position} points.
4436 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4437 bits machine this function is available under the name @code{fsetpos}
4438 and so transparently replaces the old interface.
4441 @node Stream Buffering
4442 @section Stream Buffering
4444 @cindex buffering of streams
4445 Characters that are written to a stream are normally accumulated and
4446 transmitted asynchronously to the file in a block, instead of appearing
4447 as soon as they are output by the application program. Similarly,
4448 streams often retrieve input from the host environment in blocks rather
4449 than on a character-by-character basis. This is called @dfn{buffering}.
4451 If you are writing programs that do interactive input and output using
4452 streams, you need to understand how buffering works when you design the
4453 user interface to your program. Otherwise, you might find that output
4454 (such as progress or prompt messages) doesn't appear when you intended
4455 it to, or displays some other unexpected behavior.
4457 This section deals only with controlling when characters are transmitted
4458 between the stream and the file or device, and @emph{not} with how
4459 things like echoing, flow control, and the like are handled on specific
4460 classes of devices. For information on common control operations on
4461 terminal devices, see @ref{Low-Level Terminal Interface}.
4463 You can bypass the stream buffering facilities altogether by using the
4464 low-level input and output functions that operate on file descriptors
4465 instead. @xref{Low-Level I/O}.
4468 * Buffering Concepts:: Terminology is defined here.
4469 * Flushing Buffers:: How to ensure that output buffers are flushed.
4470 * Controlling Buffering:: How to specify what kind of buffering to use.
4473 @node Buffering Concepts
4474 @subsection Buffering Concepts
4476 There are three different kinds of buffering strategies:
4480 Characters written to or read from an @dfn{unbuffered} stream are
4481 transmitted individually to or from the file as soon as possible.
4482 @cindex unbuffered stream
4485 Characters written to a @dfn{line buffered} stream are transmitted to
4486 the file in blocks when a newline character is encountered.
4487 @cindex line buffered stream
4490 Characters written to or read from a @dfn{fully buffered} stream are
4491 transmitted to or from the file in blocks of arbitrary size.
4492 @cindex fully buffered stream
4495 Newly opened streams are normally fully buffered, with one exception: a
4496 stream connected to an interactive device such as a terminal is
4497 initially line buffered. @xref{Controlling Buffering}, for information
4498 on how to select a different kind of buffering. Usually the automatic
4499 selection gives you the most convenient kind of buffering for the file
4502 The use of line buffering for interactive devices implies that output
4503 messages ending in a newline will appear immediately---which is usually
4504 what you want. Output that doesn't end in a newline might or might not
4505 show up immediately, so if you want them to appear immediately, you
4506 should flush buffered output explicitly with @code{fflush}, as described
4507 in @ref{Flushing Buffers}.
4509 @node Flushing Buffers
4510 @subsection Flushing Buffers
4512 @cindex flushing a stream
4513 @dfn{Flushing} output on a buffered stream means transmitting all
4514 accumulated characters to the file. There are many circumstances when
4515 buffered output on a stream is flushed automatically:
4519 When you try to do output and the output buffer is full.
4522 When the stream is closed. @xref{Closing Streams}.
4525 When the program terminates by calling @code{exit}.
4526 @xref{Normal Termination}.
4529 When a newline is written, if the stream is line buffered.
4532 Whenever an input operation on @emph{any} stream actually reads data
4536 If you want to flush the buffered output at another time, call
4537 @code{fflush}, which is declared in the header file @file{stdio.h}.
4542 @deftypefun int fflush (FILE *@var{stream})
4543 This function causes any buffered output on @var{stream} to be delivered
4544 to the file. If @var{stream} is a null pointer, then
4545 @code{fflush} causes buffered output on @emph{all} open output streams
4548 This function returns @code{EOF} if a write error occurs, or zero
4554 @deftypefun int fflush_unlocked (FILE *@var{stream})
4555 The @code{fflush_unlocked} function is equivalent to the @code{fflush}
4556 function except that it does not implicitly lock the stream.
4559 The @code{fflush} function can be used to flush all streams currently
4560 opened. While this is useful in some situations it does often more than
4561 necessary since it might be done in situations when terminal input is
4562 required and the program wants to be sure that all output is visible on
4563 the terminal. But this means that only line buffered streams have to be
4564 flushed. Solaris introduced a function especially for this. It was
4565 always available in the GNU C library in some form but never officially
4568 @comment stdio_ext.h
4570 @deftypefun void _flushlbf (void)
4571 The @code{_flushlbf} function flushes all line buffered streams
4574 This function is declared in the @file{stdio_ext.h} header.
4577 @strong{Compatibility Note:} Some brain-damaged operating systems have
4578 been known to be so thoroughly fixated on line-oriented input and output
4579 that flushing a line buffered stream causes a newline to be written!
4580 Fortunately, this ``feature'' seems to be becoming less common. You do
4581 not need to worry about this in the GNU system.
4583 In some situations it might be useful to not flush the output pending
4584 for a stream but instead simply forget it. If transmission is costly
4585 and the output is not needed anymore this is valid reasoning. In this
4586 situation a non-standard function introduced in Solaris and available in
4587 the GNU C library can be used.
4589 @comment stdio_ext.h
4591 @deftypefun void __fpurge (FILE *@var{stream})
4592 The @code{__fpurge} function causes the buffer of the stream
4593 @var{stream} to be emptied. If the stream is currently in read mode all
4594 input in the buffer is lost. If the stream is in output mode the
4595 buffered output is not written to the device (or whatever other
4596 underlying storage) and the buffer the cleared.
4598 This function is declared in @file{stdio_ext.h}.
4601 @node Controlling Buffering
4602 @subsection Controlling Which Kind of Buffering
4604 After opening a stream (but before any other operations have been
4605 performed on it), you can explicitly specify what kind of buffering you
4606 want it to have using the @code{setvbuf} function.
4607 @cindex buffering, controlling
4609 The facilities listed in this section are declared in the header
4610 file @file{stdio.h}.
4615 @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
4616 This function is used to specify that the stream @var{stream} should
4617 have the buffering mode @var{mode}, which can be either @code{_IOFBF}
4618 (for full buffering), @code{_IOLBF} (for line buffering), or
4619 @code{_IONBF} (for unbuffered input/output).
4621 If you specify a null pointer as the @var{buf} argument, then @code{setvbuf}
4622 allocates a buffer itself using @code{malloc}. This buffer will be freed
4623 when you close the stream.
4625 Otherwise, @var{buf} should be a character array that can hold at least
4626 @var{size} characters. You should not free the space for this array as
4627 long as the stream remains open and this array remains its buffer. You
4628 should usually either allocate it statically, or @code{malloc}
4629 (@pxref{Unconstrained Allocation}) the buffer. Using an automatic array
4630 is not a good idea unless you close the file before exiting the block
4631 that declares the array.
4633 While the array remains a stream buffer, the stream I/O functions will
4634 use the buffer for their internal purposes. You shouldn't try to access
4635 the values in the array directly while the stream is using it for
4638 The @code{setvbuf} function returns zero on success, or a nonzero value
4639 if the value of @var{mode} is not valid or if the request could not
4645 @deftypevr Macro int _IOFBF
4646 The value of this macro is an integer constant expression that can be
4647 used as the @var{mode} argument to the @code{setvbuf} function to
4648 specify that the stream should be fully buffered.
4653 @deftypevr Macro int _IOLBF
4654 The value of this macro is an integer constant expression that can be
4655 used as the @var{mode} argument to the @code{setvbuf} function to
4656 specify that the stream should be line buffered.
4661 @deftypevr Macro int _IONBF
4662 The value of this macro is an integer constant expression that can be
4663 used as the @var{mode} argument to the @code{setvbuf} function to
4664 specify that the stream should be unbuffered.
4669 @deftypevr Macro int BUFSIZ
4670 The value of this macro is an integer constant expression that is good
4671 to use for the @var{size} argument to @code{setvbuf}. This value is
4672 guaranteed to be at least @code{256}.
4674 The value of @code{BUFSIZ} is chosen on each system so as to make stream
4675 I/O efficient. So it is a good idea to use @code{BUFSIZ} as the size
4676 for the buffer when you call @code{setvbuf}.
4678 Actually, you can get an even better value to use for the buffer size
4679 by means of the @code{fstat} system call: it is found in the
4680 @code{st_blksize} field of the file attributes. @xref{Attribute Meanings}.
4682 Sometimes people also use @code{BUFSIZ} as the allocation size of
4683 buffers used for related purposes, such as strings used to receive a
4684 line of input with @code{fgets} (@pxref{Character Input}). There is no
4685 particular reason to use @code{BUFSIZ} for this instead of any other
4686 integer, except that it might lead to doing I/O in chunks of an
4692 @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
4693 If @var{buf} is a null pointer, the effect of this function is
4694 equivalent to calling @code{setvbuf} with a @var{mode} argument of
4695 @code{_IONBF}. Otherwise, it is equivalent to calling @code{setvbuf}
4696 with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size}
4697 argument of @code{BUFSIZ}.
4699 The @code{setbuf} function is provided for compatibility with old code;
4700 use @code{setvbuf} in all new programs.
4705 @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
4706 If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
4707 Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
4708 buffer. The @var{size} argument specifies the length of @var{buf}.
4710 This function is provided for compatibility with old BSD code. Use
4711 @code{setvbuf} instead.
4716 @deftypefun void setlinebuf (FILE *@var{stream})
4717 This function makes @var{stream} be line buffered, and allocates the
4720 This function is provided for compatibility with old BSD code. Use
4721 @code{setvbuf} instead.
4724 It is possible to query whether a given stream is line buffered or not
4725 using a non-standard function introduced in Solaris and available in the
4728 @comment stdio_ext.h
4730 @deftypefun int __flbf (FILE *@var{stream})
4731 The @code{__flbf} function will return a nonzero value in case the
4732 stream @var{stream} is line buffered. Otherwise the return value is
4735 This function is declared in the @file{stdio_ext.h} header.
4738 Two more extensions allow to determine the size of the buffer and how
4739 much of it is used. These functions were also introduced in Solaris.
4741 @comment stdio_ext.h
4743 @deftypefun size_t __fbufsize (FILE *@var{stream})
4744 The @code{__fbufsize} function return the size of the buffer in the
4745 stream @var{stream}. This value can be used to optimize the use of the
4748 This function is declared in the @file{stdio_ext.h} header.
4751 @comment stdio_ext.h
4753 @deftypefun size_t __fpending (FILE *@var{stream}) The @code{__fpending}
4754 function returns the number of bytes currently in the output buffer.
4755 For wide-oriented stream the measuring unit is wide characters. This
4756 function should not be used on buffers in read mode or opened read-only.
4758 This function is declared in the @file{stdio_ext.h} header.
4761 @node Other Kinds of Streams
4762 @section Other Kinds of Streams
4764 The GNU library provides ways for you to define additional kinds of
4765 streams that do not necessarily correspond to an open file.
4767 One such type of stream takes input from or writes output to a string.
4768 These kinds of streams are used internally to implement the
4769 @code{sprintf} and @code{sscanf} functions. You can also create such a
4770 stream explicitly, using the functions described in @ref{String Streams}.
4772 More generally, you can define streams that do input/output to arbitrary
4773 objects using functions supplied by your program. This protocol is
4774 discussed in @ref{Custom Streams}.
4776 @strong{Portability Note:} The facilities described in this section are
4777 specific to GNU. Other systems or C implementations might or might not
4778 provide equivalent functionality.
4781 * String Streams:: Streams that get data from or put data in
4782 a string or memory buffer.
4783 * Custom Streams:: Defining your own streams with an arbitrary
4784 input data source and/or output data sink.
4787 @node String Streams
4788 @subsection String Streams
4790 @cindex stream, for I/O to a string
4791 @cindex string stream
4792 The @code{fmemopen} and @code{open_memstream} functions allow you to do
4793 I/O to a string or memory buffer. These facilities are declared in
4799 @deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
4800 This function opens a stream that allows the access specified by the
4801 @var{opentype} argument, that reads from or writes to the buffer specified
4802 by the argument @var{buf}. This array must be at least @var{size} bytes long.
4804 If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
4805 dynamically allocates an array @var{size} bytes long (as with @code{malloc};
4806 @pxref{Unconstrained Allocation}). This is really only useful
4807 if you are going to write things to the buffer and then read them back
4808 in again, because you have no way of actually getting a pointer to the
4809 buffer (for this, try @code{open_memstream}, below). The buffer is
4810 freed when the stream is closed.
4812 The argument @var{opentype} is the same as in @code{fopen}
4813 (@pxref{Opening Streams}). If the @var{opentype} specifies
4814 append mode, then the initial file position is set to the first null
4815 character in the buffer. Otherwise the initial file position is at the
4816 beginning of the buffer.
4818 When a stream open for writing is flushed or closed, a null character
4819 (zero byte) is written at the end of the buffer if it fits. You
4820 should add an extra byte to the @var{size} argument to account for this.
4821 Attempts to write more than @var{size} bytes to the buffer result
4824 For a stream open for reading, null characters (zero bytes) in the
4825 buffer do not count as ``end of file''. Read operations indicate end of
4826 file only when the file position advances past @var{size} bytes. So, if
4827 you want to read characters from a null-terminated string, you should
4828 supply the length of the string as the @var{size} argument.
4831 Here is an example of using @code{fmemopen} to create a stream for
4832 reading from a string:
4835 @include memopen.c.texi
4838 This program produces the following output:
4851 @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
4852 This function opens a stream for writing to a buffer. The buffer is
4853 allocated dynamically and grown as necessary, using @code{malloc}.
4854 After you've closed the stream, this buffer is your responsibility to
4855 clean up using @code{free} or @code{realloc}. @xref{Unconstrained Allocation}.
4857 When the stream is closed with @code{fclose} or flushed with
4858 @code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
4859 contain the pointer to the buffer and its size. The values thus stored
4860 remain valid only as long as no further output on the stream takes
4861 place. If you do more output, you must flush the stream again to store
4862 new values before you use them again.
4864 A null character is written at the end of the buffer. This null character
4865 is @emph{not} included in the size value stored at @var{sizeloc}.
4867 You can move the stream's file position with @code{fseek} or
4868 @code{fseeko} (@pxref{File Positioning}). Moving the file position past
4869 the end of the data already written fills the intervening space with
4873 Here is an example of using @code{open_memstream}:
4876 @include memstrm.c.texi
4879 This program produces the following output:
4882 buf = `hello', size = 5
4883 buf = `hello, world', size = 12
4886 @node Custom Streams
4887 @subsection Programming Your Own Custom Streams
4888 @cindex custom streams
4889 @cindex programming your own streams
4891 This section describes how you can make a stream that gets input from an
4892 arbitrary data source or writes output to an arbitrary data sink
4893 programmed by you. We call these @dfn{custom streams}. The functions
4894 and types described here are all GNU extensions.
4896 @c !!! this does not talk at all about the higher-level hooks
4899 * Streams and Cookies:: The @dfn{cookie} records where to fetch or
4900 store data that is read or written.
4901 * Hook Functions:: How you should define the four @dfn{hook
4902 functions} that a custom stream needs.
4905 @node Streams and Cookies
4906 @subsubsection Custom Streams and Cookies
4907 @cindex cookie, for custom stream
4909 Inside every custom stream is a special object called the @dfn{cookie}.
4910 This is an object supplied by you which records where to fetch or store
4911 the data read or written. It is up to you to define a data type to use
4912 for the cookie. The stream functions in the library never refer
4913 directly to its contents, and they don't even know what the type is;
4914 they record its address with type @code{void *}.
4916 To implement a custom stream, you must specify @emph{how} to fetch or
4917 store the data in the specified place. You do this by defining
4918 @dfn{hook functions} to read, write, change ``file position'', and close
4919 the stream. All four of these functions will be passed the stream's
4920 cookie so they can tell where to fetch or store the data. The library
4921 functions don't know what's inside the cookie, but your functions will
4924 When you create a custom stream, you must specify the cookie pointer,
4925 and also the four hook functions stored in a structure of type
4926 @code{cookie_io_functions_t}.
4928 These facilities are declared in @file{stdio.h}.
4933 @deftp {Data Type} {cookie_io_functions_t}
4934 This is a structure type that holds the functions that define the
4935 communications protocol between the stream and its cookie. It has
4936 the following members:
4939 @item cookie_read_function_t *read
4940 This is the function that reads data from the cookie. If the value is a
4941 null pointer instead of a function, then read operations on this stream
4942 always return @code{EOF}.
4944 @item cookie_write_function_t *write
4945 This is the function that writes data to the cookie. If the value is a
4946 null pointer instead of a function, then data written to the stream is
4949 @item cookie_seek_function_t *seek
4950 This is the function that performs the equivalent of file positioning on
4951 the cookie. If the value is a null pointer instead of a function, calls
4952 to @code{fseek} or @code{fseeko} on this stream can only seek to
4953 locations within the buffer; any attempt to seek outside the buffer will
4954 return an @code{ESPIPE} error.
4956 @item cookie_close_function_t *close
4957 This function performs any appropriate cleanup on the cookie when
4958 closing the stream. If the value is a null pointer instead of a
4959 function, nothing special is done to close the cookie when the stream is
4966 @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions})
4967 This function actually creates the stream for communicating with the
4968 @var{cookie} using the functions in the @var{io-functions} argument.
4969 The @var{opentype} argument is interpreted as for @code{fopen};
4970 see @ref{Opening Streams}. (But note that the ``truncate on
4971 open'' option is ignored.) The new stream is fully buffered.
4973 The @code{fopencookie} function returns the newly created stream, or a null
4974 pointer in case of an error.
4977 @node Hook Functions
4978 @subsubsection Custom Stream Hook Functions
4979 @cindex hook functions (of custom streams)
4981 Here are more details on how you should define the four hook functions
4982 that a custom stream needs.
4984 You should define the function to read data from the cookie as:
4987 ssize_t @var{reader} (void *@var{cookie}, char *@var{buffer}, size_t @var{size})
4990 This is very similar to the @code{read} function; see @ref{I/O
4991 Primitives}. Your function should transfer up to @var{size} bytes into
4992 the @var{buffer}, and return the number of bytes read, or zero to
4993 indicate end-of-file. You can return a value of @code{-1} to indicate
4996 You should define the function to write data to the cookie as:
4999 ssize_t @var{writer} (void *@var{cookie}, const char *@var{buffer}, size_t @var{size})
5002 This is very similar to the @code{write} function; see @ref{I/O
5003 Primitives}. Your function should transfer up to @var{size} bytes from
5004 the buffer, and return the number of bytes written. You can return a
5005 value of @code{-1} to indicate an error.
5007 You should define the function to perform seek operations on the cookie
5011 int @var{seeker} (void *@var{cookie}, off64_t *@var{position}, int @var{whence})
5014 For this function, the @var{position} and @var{whence} arguments are
5015 interpreted as for @code{fgetpos}; see @ref{Portable Positioning}.
5017 After doing the seek operation, your function should store the resulting
5018 file position relative to the beginning of the file in @var{position}.
5019 Your function should return a value of @code{0} on success and @code{-1}
5020 to indicate an error.
5022 You should define the function to do cleanup operations on the cookie
5023 appropriate for closing the stream as:
5026 int @var{cleaner} (void *@var{cookie})
5029 Your function should return @code{-1} to indicate an error, and @code{0}
5034 @deftp {Data Type} cookie_read_function
5035 This is the data type that the read function for a custom stream should have.
5036 If you declare the function as shown above, this is the type it will have.
5041 @deftp {Data Type} cookie_write_function
5042 The data type of the write function for a custom stream.
5047 @deftp {Data Type} cookie_seek_function
5048 The data type of the seek function for a custom stream.
5053 @deftp {Data Type} cookie_close_function
5054 The data type of the close function for a custom stream.
5061 There is another set of functions one can give a stream, the
5062 input-room and output-room functions. These functions must
5063 understand stdio internals. To describe how to use these
5064 functions, you also need to document lots of how stdio works
5065 internally (which isn't relevant for other uses of stdio).
5066 Perhaps I can write an interface spec from which you can write
5067 good documentation. But it's pretty complex and deals with lots
5068 of nitty-gritty details. I think it might be better to let this
5069 wait until the rest of the manual is more done and polished.
5073 @c ??? This section could use an example.
5076 @node Formatted Messages
5077 @section Formatted Messages
5078 @cindex formatted messages
5080 On systems which are based on System V messages of programs (especially
5081 the system tools) are printed in a strict form using the @code{fmtmsg}
5082 function. The uniformity sometimes helps the user to interpret messages
5083 and the strictness tests of the @code{fmtmsg} function ensure that the
5084 programmer follows some minimal requirements.
5087 * Printing Formatted Messages:: The @code{fmtmsg} function.
5088 * Adding Severity Classes:: Add more severity classes.
5089 * Example:: How to use @code{fmtmsg} and @code{addseverity}.
5093 @node Printing Formatted Messages
5094 @subsection Printing Formatted Messages
5096 Messages can be printed to standard error and/or to the console. To
5097 select the destination the programmer can use the following two values,
5098 bitwise OR combined if wanted, for the @var{classification} parameter of
5103 Display the message in standard error.
5105 Display the message on the system console.
5108 The erroneous piece of the system can be signalled by exactly one of the
5109 following values which also is bitwise ORed with the
5110 @var{classification} parameter to @code{fmtmsg}:
5114 The source of the condition is some hardware.
5116 The source of the condition is some software.
5118 The source of the condition is some firmware.
5121 A third component of the @var{classification} parameter to @code{fmtmsg}
5122 can describe the part of the system which detects the problem. This is
5123 done by using exactly one of the following values:
5127 The erroneous condition is detected by the application.
5129 The erroneous condition is detected by a utility.
5131 The erroneous condition is detected by the operating system.
5134 A last component of @var{classification} can signal the results of this
5135 message. Exactly one of the following values can be used:
5139 It is a recoverable error.
5141 It is a non-recoverable error.
5146 @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})
5147 Display a message described by its parameters on the device(s) specified
5148 in the @var{classification} parameter. The @var{label} parameter
5149 identifies the source of the message. The string should consist of two
5150 colon separated parts where the first part has not more than 10 and the
5151 second part not more than 14 characters. The @var{text} parameter
5152 describes the condition of the error, the @var{action} parameter possible
5153 steps to recover from the error and the @var{tag} parameter is a
5154 reference to the online documentation where more information can be
5155 found. It should contain the @var{label} value and a unique
5156 identification number.
5158 Each of the parameters can be a special value which means this value
5159 is to be omitted. The symbolic names for these values are:
5163 Ignore @var{label} parameter.
5165 Ignore @var{severity} parameter.
5167 Ignore @var{classification} parameter. This implies that nothing is
5170 Ignore @var{text} parameter.
5172 Ignore @var{action} parameter.
5174 Ignore @var{tag} parameter.
5177 There is another way certain fields can be omitted from the output to
5178 standard error. This is described below in the description of
5179 environment variables influencing the behavior.
5181 The @var{severity} parameter can have one of the values in the following
5183 @cindex severity class
5187 Nothing is printed, this value is the same as @code{MM_NULLSEV}.
5189 This value is printed as @code{HALT}.
5191 This value is printed as @code{ERROR}.
5193 This value is printed as @code{WARNING}.
5195 This value is printed as @code{INFO}.
5198 The numeric value of these five macros are between @code{0} and
5199 @code{4}. Using the environment variable @code{SEV_LEVEL} or using the
5200 @code{addseverity} function one can add more severity levels with their
5201 corresponding string to print. This is described below
5202 (@pxref{Adding Severity Classes}).
5205 If no parameter is ignored the output looks like this:
5208 @var{label}: @var{severity-string}: @var{text}
5209 TO FIX: @var{action} @var{tag}
5212 The colons, new line characters and the @code{TO FIX} string are
5213 inserted if necessary, i.e., if the corresponding parameter is not
5216 This function is specified in the X/Open Portability Guide. It is also
5217 available on all systems derived from System V.
5219 The function returns the value @code{MM_OK} if no error occurred. If
5220 only the printing to standard error failed, it returns @code{MM_NOMSG}.
5221 If printing to the console fails, it returns @code{MM_NOCON}. If
5222 nothing is printed @code{MM_NOTOK} is returned. Among situations where
5223 all outputs fail this last value is also returned if a parameter value
5227 There are two environment variables which influence the behavior of
5228 @code{fmtmsg}. The first is @code{MSGVERB}. It is used to control the
5229 output actually happening on standard error (@emph{not} the console
5230 output). Each of the five fields can explicitly be enabled. To do
5231 this the user has to put the @code{MSGVERB} variable with a format like
5232 the following in the environment before calling the @code{fmtmsg} function
5236 MSGVERB=@var{keyword}[:@var{keyword}[:@dots{}]]
5239 Valid @var{keyword}s are @code{label}, @code{severity}, @code{text},
5240 @code{action}, and @code{tag}. If the environment variable is not given
5241 or is the empty string, a not supported keyword is given or the value is
5242 somehow else invalid, no part of the message is masked out.
5244 The second environment variable which influences the behavior of
5245 @code{fmtmsg} is @code{SEV_LEVEL}. This variable and the change in the
5246 behavior of @code{fmtmsg} is not specified in the X/Open Portability
5247 Guide. It is available in System V systems, though. It can be used to
5248 introduce new severity levels. By default, only the five severity levels
5249 described above are available. Any other numeric value would make
5250 @code{fmtmsg} print nothing.
5252 If the user puts @code{SEV_LEVEL} with a format like
5255 SEV_LEVEL=[@var{description}[:@var{description}[:@dots{}]]]
5259 in the environment of the process before the first call to
5260 @code{fmtmsg}, where @var{description} has a value of the form
5263 @var{severity-keyword},@var{level},@var{printstring}
5266 The @var{severity-keyword} part is not used by @code{fmtmsg} but it has
5267 to be present. The @var{level} part is a string representation of a
5268 number. The numeric value must be a number greater than 4. This value
5269 must be used in the @var{severity} parameter of @code{fmtmsg} to select
5270 this class. It is not possible to overwrite any of the predefined
5271 classes. The @var{printstring} is the string printed when a message of
5272 this class is processed by @code{fmtmsg} (see above, @code{fmtsmg} does
5273 not print the numeric value but instead the string representation).
5276 @node Adding Severity Classes
5277 @subsection Adding Severity Classes
5278 @cindex severity class
5280 There is another possibility to introduce severity classes besides using
5281 the environment variable @code{SEV_LEVEL}. This simplifies the task of
5282 introducing new classes in a running program. One could use the
5283 @code{setenv} or @code{putenv} function to set the environment variable,
5284 but this is toilsome.
5286 @deftypefun int addseverity (int @var{severity}, const char *@var{string})
5287 This function allows the introduction of new severity classes which can be
5288 addressed by the @var{severity} parameter of the @code{fmtmsg} function.
5289 The @var{severity} parameter of @code{addseverity} must match the value
5290 for the parameter with the same name of @code{fmtmsg}, and @var{string}
5291 is the string printed in the actual messages instead of the numeric
5294 If @var{string} is @code{NULL} the severity class with the numeric value
5295 according to @var{severity} is removed.
5297 It is not possible to overwrite or remove one of the default severity
5298 classes. All calls to @code{addseverity} with @var{severity} set to one
5299 of the values for the default classes will fail.
5301 The return value is @code{MM_OK} if the task was successfully performed.
5302 If the return value is @code{MM_NOTOK} something went wrong. This could
5303 mean that no more memory is available or a class is not available when
5304 it has to be removed.
5306 This function is not specified in the X/Open Portability Guide although
5307 the @code{fmtsmg} function is. It is available on System V systems.
5312 @subsection How to use @code{fmtmsg} and @code{addseverity}
5314 Here is a simple example program to illustrate the use of the both
5315 functions described in this section.
5318 @include fmtmsgexpl.c.texi
5321 The second call to @code{fmtmsg} illustrates a use of this function as
5322 it usually occurs on System V systems, which heavily use this function.
5323 It seems worthwhile to give a short explanation here of how this system
5324 works on System V. The value of the
5325 @var{label} field (@code{UX:cat}) says that the error occurred in the
5326 Unix program @code{cat}. The explanation of the error follows and the
5327 value for the @var{action} parameter is @code{"refer to manual"}. One
5328 could be more specific here, if necessary. The @var{tag} field contains,
5329 as proposed above, the value of the string given for the @var{label}
5330 parameter, and additionally a unique ID (@code{001} in this case). For
5331 a GNU environment this string could contain a reference to the
5332 corresponding node in the Info page for the program.
5335 Running this program without specifying the @code{MSGVERB} and
5336 @code{SEV_LEVEL} function produces the following output:
5339 UX:cat: NOTE2: invalid syntax
5340 TO FIX: refer to manual UX:cat:001
5343 We see the different fields of the message and how the extra glue (the
5344 colons and the @code{TO FIX} string) are printed. But only one of the
5345 three calls to @code{fmtmsg} produced output. The first call does not
5346 print anything because the @var{label} parameter is not in the correct
5347 form. The string must contain two fields, separated by a colon
5348 (@pxref{Printing Formatted Messages}). The third @code{fmtmsg} call
5349 produced no output since the class with the numeric value @code{6} is
5350 not defined. Although a class with numeric value @code{5} is also not
5351 defined by default, the call to @code{addseverity} introduces it and
5352 the second call to @code{fmtmsg} produces the above output.
5354 When we change the environment of the program to contain
5355 @code{SEV_LEVEL=XXX,6,NOTE} when running it we get a different result:
5358 UX:cat: NOTE2: invalid syntax
5359 TO FIX: refer to manual UX:cat:001
5360 label:foo: NOTE: text
5364 Now the third call to @code{fmtmsg} produced some output and we see how
5365 the string @code{NOTE} from the environment variable appears in the
5368 Now we can reduce the output by specifying which fields we are
5369 interested in. If we additionally set the environment variable
5370 @code{MSGVERB} to the value @code{severity:label:action} we get the
5375 TO FIX: refer to manual
5381 I.e., the output produced by the @var{text} and the @var{tag} parameters
5382 to @code{fmtmsg} vanished. Please also note that now there is no colon
5383 after the @code{NOTE} and @code{NOTE2} strings in the output. This is
5384 not necessary since there is no more output on this line because the text