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. The ISO standard says that when using such a stream, you must
190 call @code{fflush} (@pxref{Stream Buffering}) or a file positioning
191 function such as @code{fseek} (@pxref{File Positioning}) when switching
192 from reading to writing or vice versa. Otherwise, internal buffers
193 might not be emptied properly. The GNU C library does not have this
194 limitation; you can do arbitrary reading and writing operations on a
195 stream in whatever order.
197 Additional characters may appear after these to specify flags for the
198 call. Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is
199 the only part you are guaranteed will be understood by all systems.
201 The GNU C library defines one additional character for use in
202 @var{opentype}: the character @samp{x} insists on creating a new
203 file---if a file @var{filename} already exists, @code{fopen} fails
204 rather than opening it. If you use @samp{x} you are guaranteed that
205 you will not clobber an existing file. This is equivalent to the
206 @code{O_EXCL} option to the @code{open} function (@pxref{Opening and
209 The character @samp{b} in @var{opentype} has a standard meaning; it
210 requests a binary stream rather than a text stream. But this makes no
211 difference in POSIX systems (including the GNU system). If both
212 @samp{+} and @samp{b} are specified, they can appear in either order.
213 @xref{Binary Streams}.
215 @cindex stream orientation
216 @cindex orientation, stream
217 If the @var{opentype} string contains the sequence
218 @code{,ccs=@var{STRING}} then @var{STRING} is taken as the name of a
219 coded character set and @code{fopen} will mark the stream as
220 wide-oriented which appropriate conversion functions in place to convert
221 from and to the character set @var{STRING} is place. Any other stream
222 is opened initially unoriented and the orientation is decided with the
223 first file operation. If the first operation is a wide character
224 operation, the stream is not only marked as wide-oriented, also the
225 conversion functions to convert to the coded character set used for the
226 current locale are loaded. This will not change anymore from this point
227 on even if the locale selected for the @code{LC_CTYPE} category is
230 Any other characters in @var{opentype} are simply ignored. They may be
231 meaningful in other systems.
233 If the open fails, @code{fopen} returns a null pointer.
235 When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
236 32 bit machine this function is in fact @code{fopen64} since the LFS
237 interface replaces transparently the old interface.
240 You can have multiple streams (or file descriptors) pointing to the same
241 file open at the same time. If you do only input, this works
242 straightforwardly, but you must be careful if any output streams are
243 included. @xref{Stream/Descriptor Precautions}. This is equally true
244 whether the streams are in one program (not usual) or in several
245 programs (which can easily happen). It may be advantageous to use the
246 file locking facilities to avoid simultaneous access. @xref{File
251 @deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype})
252 This function is similar to @code{fopen} but the stream it returns a
253 pointer for is opened using @code{open64}. Therefore this stream can be
254 used even on files larger then @math{2^31} bytes on 32 bit machines.
256 Please note that the return type is still @code{FILE *}. There is no
257 special @code{FILE} type for the LFS interface.
259 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
260 bits machine this function is available under the name @code{fopen}
261 and so transparently replaces the old interface.
266 @deftypevr Macro int FOPEN_MAX
267 The value of this macro is an integer constant expression that
268 represents the minimum number of streams that the implementation
269 guarantees can be open simultaneously. You might be able to open more
270 than this many streams, but that is not guaranteed. The value of this
271 constant is at least eight, which includes the three standard streams
272 @code{stdin}, @code{stdout}, and @code{stderr}. In POSIX.1 systems this
273 value is determined by the @code{OPEN_MAX} parameter; @pxref{General
274 Limits}. In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE}
275 resource limit; @pxref{Limits on Resources}.
280 @deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
281 This function is like a combination of @code{fclose} and @code{fopen}.
282 It first closes the stream referred to by @var{stream}, ignoring any
283 errors that are detected in the process. (Because errors are ignored,
284 you should not use @code{freopen} on an output stream if you have
285 actually done any output using the stream.) Then the file named by
286 @var{filename} is opened with mode @var{opentype} as for @code{fopen},
287 and associated with the same stream object @var{stream}.
289 If the operation fails, a null pointer is returned; otherwise,
290 @code{freopen} returns @var{stream}.
292 @code{freopen} has traditionally been used to connect a standard stream
293 such as @code{stdin} with a file of your own choice. This is useful in
294 programs in which use of a standard stream for certain purposes is
295 hard-coded. In the GNU C library, you can simply close the standard
296 streams and open new ones with @code{fopen}. But other systems lack
297 this ability, so using @code{freopen} is more portable.
299 When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
300 32 bit machine this function is in fact @code{freopen64} since the LFS
301 interface replaces transparently the old interface.
306 @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
307 This function is similar to @code{freopen}. The only difference is that
308 on 32 bit machine the stream returned is able to read beyond the
309 @math{2^31} bytes limits imposed by the normal interface. It should be
310 noted that the stream pointed to by @var{stream} need not be opened
311 using @code{fopen64} or @code{freopen64} since its mode is not important
314 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
315 bits machine this function is available under the name @code{freopen}
316 and so transparently replaces the old interface.
319 In some situations it is useful to know whether a given stream is
320 available for reading or writing. This information is normally not
321 available and would have to be remembered separately. Solaris
322 introduced a few functions to get this information from the stream
323 descriptor and these functions are also available in the GNU C library.
327 @deftypefun int __freadable (FILE *@var{stream})
328 The @code{__freadable} function determines whether the stream
329 @var{stream} was opened to allow reading. In this case the return value
330 is nonzero. For write-only streams the function returns zero.
332 This function is declared in @file{stdio_ext.h}.
337 @deftypefun int __fwritable (FILE *@var{stream})
338 The @code{__fwritable} function determines whether the stream
339 @var{stream} was opened to allow writing. In this case the return value
340 is nonzero. For read-only streams the function returns zero.
342 This function is declared in @file{stdio_ext.h}.
345 For slightly different kind of problems there are two more functions.
346 They provide even finer-grained information.
350 @deftypefun int __freading (FILE *@var{stream})
351 The @code{__freading} function determines whether the stream
352 @var{stream} was last read from or whether it is opened read-only. In
353 this case the return value is nonzero, otherwise it is zero.
354 Determining whether a stream opened for reading and writing was last
355 used for writing allows to draw conclusions about the content about the
356 buffer, among other things.
358 This function is declared in @file{stdio_ext.h}.
363 @deftypefun int __fwriting (FILE *@var{stream})
364 The @code{__fwriting} function determines whether the stream
365 @var{stream} was last written to or whether it is opened write-only. In
366 this case the return value is nonzero, otherwise it is zero.
368 This function is declared in @file{stdio_ext.h}.
372 @node Closing Streams
373 @section Closing Streams
375 @cindex closing a stream
376 When a stream is closed with @code{fclose}, the connection between the
377 stream and the file is canceled. After you have closed a stream, you
378 cannot perform any additional operations on it.
382 @deftypefun int fclose (FILE *@var{stream})
383 This function causes @var{stream} to be closed and the connection to
384 the corresponding file to be broken. Any buffered output is written
385 and any buffered input is discarded. The @code{fclose} function returns
386 a value of @code{0} if the file was closed successfully, and @code{EOF}
387 if an error was detected.
389 It is important to check for errors when you call @code{fclose} to close
390 an output stream, because real, everyday errors can be detected at this
391 time. For example, when @code{fclose} writes the remaining buffered
392 output, it might get an error because the disk is full. Even if you
393 know the buffer is empty, errors can still occur when closing a file if
396 The function @code{fclose} is declared in @file{stdio.h}.
399 To close all streams currently available the GNU C Library provides
404 @deftypefun int fcloseall (void)
405 This function causes all open streams of the process to be closed and
406 the connection to corresponding files to be broken. All buffered data
407 is written and any buffered input is discarded. The @code{fcloseall}
408 function returns a value of @code{0} if all the files were closed
409 successfully, and @code{EOF} if an error was detected.
411 This function should be used only in special situations, e.g., when an
412 error occurred and the program must be aborted. Normally each single
413 stream should be closed separately so that problems with individual
414 streams can be identified. It is also problematic since the standard
415 streams (@pxref{Standard Streams}) will also be closed.
417 The function @code{fcloseall} is declared in @file{stdio.h}.
420 If the @code{main} function to your program returns, or if you call the
421 @code{exit} function (@pxref{Normal Termination}), all open streams are
422 automatically closed properly. If your program terminates in any other
423 manner, such as by calling the @code{abort} function (@pxref{Aborting a
424 Program}) or from a fatal signal (@pxref{Signal Handling}), open streams
425 might not be closed properly. Buffered output might not be flushed and
426 files may be incomplete. For more information on buffering of streams,
427 see @ref{Stream Buffering}.
429 @node Streams and Threads
430 @section Streams and Threads
433 @cindex multi-threaded application
434 Streams can be used in multi-threaded applications in the same way they
435 are used in single-threaded applications. But the programmer must be
436 aware of a the possible complications. It is important to know about
437 these also if the program one writes never use threads since the design
438 and implementation of many stream functions is heavily influenced by the
439 requirements added by multi-threaded programming.
441 The POSIX standard requires that by default the stream operations are
442 atomic. I.e., issuing two stream operations for the same stream in two
443 threads at the same time will cause the operations to be executed as if
444 they were issued sequentially. The buffer operations performed while
445 reading or writing are protected from other uses of the same stream. To
446 do this each stream has an internal lock object which has to be
447 (implicitly) acquired before any work can be done.
449 But there are situations where this is not enough and there are also
450 situations where this is not wanted. The implicit locking is not enough
451 if the program requires more than one stream function call to happen
452 atomically. One example would be if an output line a program wants to
453 generate is created by several function calls. The functions by
454 themselves would ensure only atomicity of their own operation, but not
455 atomicity over all the function calls. For this it is necessary to
456 perform the stream locking in the application code.
460 @deftypefun void flockfile (FILE *@var{stream})
461 The @code{flockfile} function acquires the internal locking object
462 associated with the stream @var{stream}. This ensures that no other
463 thread can explicitly through @code{flockfile}/@code{ftrylockfile} or
464 implicit through a call of a stream function lock the stream. The
465 thread will block until the lock is acquired. An explicit call to
466 @code{funlockfile} has to be used to release the lock.
471 @deftypefun int ftrylockfile (FILE *@var{stream})
472 The @code{ftrylockfile} function tries to acquire the internal locking
473 object associated with the stream @var{stream} just like
474 @code{flockfile}. But unlike @code{flockfile} this function does not
475 block if the lock is not available. @code{ftrylockfile} returns zero if
476 the lock was successfully acquired. Otherwise the stream is locked by
482 @deftypefun void funlockfile (FILE *@var{stream})
483 The @code{funlockfile} function releases the internal locking object of
484 the stream @var{stream}. The stream must have been locked before by a
485 call to @code{flockfile} or a successful call of @code{ftrylockfile}.
486 The implicit locking performed by the stream operations do not count.
487 The @code{funlockfile} function does not return an error status and the
488 behavior of a call for a stream which is not locked by the current
492 The following example shows how the functions above can be used to
493 generate an output line atomically even in multi-threaded applications
494 (yes, the same job could be done with one @code{fprintf} call but it is
495 sometimes not possible):
502 fputs ("This is test number ", fp);
503 fprintf (fp, "%d\n", test);
508 Without the explicit locking it would be possible for another thread to
509 use the stream @var{fp} after the @code{fputs} call return and before
510 @code{fprintf} was called with the result that the number does not
511 follow the word @samp{number}.
513 From this description it might already be clear that the locking objects
514 in streams are no simple mutexes. Since locking the same stream twice
515 in the same thread is allowed the locking objects must be equivalent to
516 recursive mutexes. These mutexes keep track of the owner and the number
517 of times the lock is acquired. The same number of @code{funlockfile}
518 calls by the same threads is necessary to unlock the stream completely.
526 fputs ("in foo\n", fp);
527 /* @r{This is very wrong!!!} */
532 It is important here that the @code{funlockfile} function is only called
533 if the @code{ftrylockfile} function succeeded in locking the stream. It
534 is therefore always wrong to ignore the result of @code{ftrylockfile}.
535 And it makes no sense since otherwise one would use @code{flockfile}.
536 The result of code like that above is that either @code{funlockfile}
537 tries to free a stream that hasn't been locked by the current thread or it
538 frees the stream prematurely. The code should look like this:
544 if (ftrylockfile (fp) == 0)
546 fputs ("in foo\n", fp);
552 Now that we covered why it is necessary to have these locking it is
553 necessary to talk about situations when locking is unwanted and what can
554 be done. The locking operations (explicit or implicit) don't come for
555 free. Even if a lock is not taken the cost is not zero. The operations
556 which have to be performed require memory operations that are safe in
557 multi-processor environments. With the many local caches involved in
558 such systems this is quite costly. So it is best to avoid the locking
559 completely if it is not needed -- because the code in question is never
560 used in a context where two or more threads may use a stream at a time.
561 This can be determined most of the time for application code; for
562 library code which can be used in many contexts one should default to be
563 conservative and use locking.
565 There are two basic mechanisms to avoid locking. The first is to use
566 the @code{_unlocked} variants of the stream operations. The POSIX
567 standard defines quite a few of those and the GNU library adds a few
568 more. These variants of the functions behave just like the functions
569 with the name without the suffix except that they do not lock the
570 stream. Using these functions is very desirable since they are
571 potentially much faster. This is not only because the locking
572 operation itself is avoided. More importantly, functions like
573 @code{putc} and @code{getc} are very simple and traditionally (before the
574 introduction of threads) were implemented as macros which are very fast
575 if the buffer is not empty. With the addition of locking requirements
576 these functions are no longer implemented as macros since they would
577 would expand to too much code.
578 But these macros are still available with the same functionality under the new
579 names @code{putc_unlocked} and @code{getc_unlocked}. This possibly huge
580 difference of speed also suggests the use of the @code{_unlocked}
581 functions even if locking is required. The difference is that the
582 locking then has to be performed in the program:
586 foo (FILE *fp, char *buf)
590 putc_unlocked (*buf++, fp);
595 If in this example the @code{putc} function would be used and the
596 explicit locking would be missing the @code{putc} function would have to
597 acquire the lock in every call, potentially many times depending on when
598 the loop terminates. Writing it the way illustrated above allows the
599 @code{putc_unlocked} macro to be used which means no locking and direct
600 manipulation of the buffer of the stream.
602 A second way to avoid locking is by using a non-standard function which
603 was introduced in Solaris and is available in the GNU C library as well.
607 @deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type})
609 The @code{__fsetlocking} function can be used to select whether the
610 stream operations will implicitly acquire the locking object of the
611 stream @var{stream}. By default this is done but it can be disabled and
612 reinstated using this function. There are three values defined for the
613 @var{type} parameter.
616 @item FSETLOCKING_INTERNAL
617 The stream @code{stream} will from now on use the default internal
618 locking. Every stream operation with exception of the @code{_unlocked}
619 variants will implicitly lock the stream.
621 @item FSETLOCKING_BYCALLER
622 After the @code{__fsetlocking} function returns the user is responsible
623 for locking the stream. None of the stream operations will implicitly
624 do this anymore until the state is set back to
625 @code{FSETLOCKING_INTERNAL}.
627 @item FSETLOCKING_QUERY
628 @code{__fsetlocking} only queries the current locking state of the
629 stream. The return value will be @code{FSETLOCKING_INTERNAL} or
630 @code{FSETLOCKING_BYCALLER} depending on the state.
633 The return value of @code{__fsetlocking} is either
634 @code{FSETLOCKING_INTERNAL} or @code{FSETLOCKING_BYCALLER} depending on
635 the state of the stream before the call.
637 This function and the values for the @var{type} parameter are declared
638 in @file{stdio_ext.h}.
641 This function is especially useful when program code has to be used
642 which is written without knowledge about the @code{_unlocked} functions
643 (or if the programmer was too lazy to use them).
645 @node Streams and I18N
646 @section Streams in Internationalized Applications
648 @w{ISO C90} introduced the new type @code{wchar_t} to allow handling
649 larger character sets. What was missing was a possibility to output
650 strings of @code{wchar_t} directly. One had to convert them into
651 multibyte strings using @code{mbstowcs} (there was no @code{mbsrtowcs}
652 yet) and then use the normal stream functions. While this is doable it
653 is very cumbersome since performing the conversions is not trivial and
654 greatly increases program complexity and size.
656 The Unix standard early on (I think in XPG4.2) introduced two additional
657 format specifiers for the @code{printf} and @code{scanf} families of
658 functions. Printing and reading of single wide characters was made
659 possible using the @code{%C} specifier and wide character strings can be
660 handled with @code{%S}. These modifiers behave just like @code{%c} and
661 @code{%s} only that they expect the corresponding argument to have the
662 wide character type and that the wide character and string are
663 transformed into/from multibyte strings before being used.
665 This was a beginning but it is still not good enough. Not always is it
666 desirable to use @code{printf} and @code{scanf}. The other, smaller and
667 faster functions cannot handle wide characters. Second, it is not
668 possible to have a format string for @code{printf} and @code{scanf}
669 consisting of wide characters. The result is that format strings would
670 have to be generated if they have to contain non-basic characters.
674 In the @w{Amendment 1} to @w{ISO C90} a whole new set of functions was
675 added to solve the problem. Most of the stream functions got a
676 counterpart which take a wide character or wide character string instead
677 of a character or string respectively. The new functions operate on the
678 same streams (like @code{stdout}). This is different from the model of
679 the C++ runtime library where separate streams for wide and normal I/O
682 @cindex orientation, stream
683 @cindex stream orientation
684 Being able to use the same stream for wide and normal operations comes
685 with a restriction: a stream can be used either for wide operations or
686 for normal operations. Once it is decided there is no way back. Only a
687 call to @code{freopen} or @code{freopen64} can reset the
688 @dfn{orientation}. The orientation can be decided in three ways:
692 If any of the normal character functions is used (this includes the
693 @code{fread} and @code{fwrite} functions) the stream is marked as not
697 If any of the wide character functions is used the stream is marked as
701 The @code{fwide} function can be used to set the orientation either way.
704 It is important to never mix the use of wide and not wide operations on
705 a stream. There are no diagnostics issued. The application behavior
706 will simply be strange or the application will simply crash. The
707 @code{fwide} function can help avoiding this.
711 @deftypefun int fwide (FILE *@var{stream}, int @var{mode})
713 The @code{fwide} function can be used to set and query the state of the
714 orientation of the stream @var{stream}. If the @var{mode} parameter has
715 a positive value the streams get wide oriented, for negative values
716 narrow oriented. It is not possible to overwrite previous orientations
717 with @code{fwide}. I.e., if the stream @var{stream} was already
718 oriented before the call nothing is done.
720 If @var{mode} is zero the current orientation state is queried and
723 The @code{fwide} function returns a negative value, zero, or a positive
724 value if the stream is narrow, not at all, or wide oriented
727 This function was introduced in @w{Amendment 1} to @w{ISO C90} and is
728 declared in @file{wchar.h}.
731 It is generally a good idea to orient a stream as early as possible.
732 This can prevent surprise especially for the standard streams
733 @code{stdin}, @code{stdout}, and @code{stderr}. If some library
734 function in some situations uses one of these streams and this use
735 orients the stream in a different way the rest of the application
736 expects it one might end up with hard to reproduce errors. Remember
737 that no errors are signal if the streams are used incorrectly. Leaving
738 a stream unoriented after creation is normally only necessary for
739 library functions which create streams which can be used in different
742 When writing code which uses streams and which can be used in different
743 contexts it is important to query the orientation of the stream before
744 using it (unless the rules of the library interface demand a specific
745 orientation). The following little, silly function illustrates this.
751 if (fwide (fp, 0) > 0)
752 /* @r{Positive return value means wide orientation.} */
759 Note that in this case the function @code{print_f} decides about the
760 orientation of the stream if it was unoriented before (will not happen
761 if the advise above is followed).
763 The encoding used for the @code{wchar_t} values is unspecified and the
764 user must not make any assumptions about it. For I/O of @code{wchar_t}
765 values this means that it is impossible to write these values directly
766 to the stream. This is not what follows from the @w{ISO C} locale model
767 either. What happens instead is that the bytes read from or written to
768 the underlying media are first converted into the internal encoding
769 chosen by the implementation for @code{wchar_t}. The external encoding
770 is determined by the @code{LC_CTYPE} category of the current locale or
771 by the @samp{ccs} part of the mode specification given to @code{fopen},
772 @code{fopen64}, @code{freopen}, or @code{freopen64}. How and when the
773 conversion happens is unspecified and it happens invisible to the user.
775 Since a stream is created in the unoriented state it has at that point
776 no conversion associated with it. The conversion which will be used is
777 determined by the @code{LC_CTYPE} category selected at the time the
778 stream is oriented. If the locales are changed at the runtime this
779 might produce surprising results unless one pays attention. This is
780 just another good reason to orient the stream explicitly as soon as
781 possible, perhaps with a call to @code{fwide}.
784 @section Simple Output by Characters or Lines
786 @cindex writing to a stream, by characters
787 This section describes functions for performing character- and
788 line-oriented output.
790 These narrow streams functions are declared in the header file
791 @file{stdio.h} and the wide stream functions in @file{wchar.h}.
797 @deftypefun int fputc (int @var{c}, FILE *@var{stream})
798 The @code{fputc} function converts the character @var{c} to type
799 @code{unsigned char}, and writes it to the stream @var{stream}.
800 @code{EOF} is returned if a write error occurs; otherwise the
801 character @var{c} is returned.
806 @deftypefun wint_t fputwc (wchar_t @var{wc}, FILE *@var{stream})
807 The @code{fputwc} function writes the wide character @var{wc} to the
808 stream @var{stream}. @code{WEOF} is returned if a write error occurs;
809 otherwise the character @var{wc} is returned.
814 @deftypefun int fputc_unlocked (int @var{c}, FILE *@var{stream})
815 The @code{fputc_unlocked} function is equivalent to the @code{fputc}
816 function except that it does not implicitly lock the stream.
821 @deftypefun wint_t fputwc_unlocked (wint_t @var{wc}, FILE *@var{stream})
822 The @code{fputwc_unlocked} function is equivalent to the @code{fputwc}
823 function except that it does not implicitly lock the stream.
825 This function is a GNU extension.
830 @deftypefun int putc (int @var{c}, FILE *@var{stream})
831 This is just like @code{fputc}, except that most systems implement it as
832 a macro, making it faster. One consequence is that it may evaluate the
833 @var{stream} argument more than once, which is an exception to the
834 general rule for macros. @code{putc} is usually the best function to
835 use for writing a single character.
840 @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream})
841 This is just like @code{fputwc}, except that it can be implement as
842 a macro, making it faster. One consequence is that it may evaluate the
843 @var{stream} argument more than once, which is an exception to the
844 general rule for macros. @code{putwc} is usually the best function to
845 use for writing a single wide character.
850 @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})
851 The @code{putc_unlocked} function is equivalent to the @code{putc}
852 function except that it does not implicitly lock the stream.
857 @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
858 The @code{putwc_unlocked} function is equivalent to the @code{putwc}
859 function except that it does not implicitly lock the stream.
861 This function is a GNU extension.
866 @deftypefun int putchar (int @var{c})
867 The @code{putchar} function is equivalent to @code{putc} with
868 @code{stdout} as the value of the @var{stream} argument.
873 @deftypefun wint_t putwchar (wchar_t @var{wc})
874 The @code{putwchar} function is equivalent to @code{putwc} with
875 @code{stdout} as the value of the @var{stream} argument.
880 @deftypefun int putchar_unlocked (int @var{c})
881 The @code{putchar_unlocked} function is equivalent to the @code{putchar}
882 function except that it does not implicitly lock the stream.
887 @deftypefun wint_t putwchar_unlocked (wchar_t @var{wc})
888 The @code{putwchar_unlocked} function is equivalent to the @code{putwchar}
889 function except that it does not implicitly lock the stream.
891 This function is a GNU extension.
896 @deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
897 The function @code{fputs} writes the string @var{s} to the stream
898 @var{stream}. The terminating null character is not written.
899 This function does @emph{not} add a newline character, either.
900 It outputs only the characters in the string.
902 This function returns @code{EOF} if a write error occurs, and otherwise
903 a non-negative value.
908 fputs ("Are ", stdout);
909 fputs ("you ", stdout);
910 fputs ("hungry?\n", stdout);
914 outputs the text @samp{Are you hungry?} followed by a newline.
919 @deftypefun int fputws (const wchar_t *@var{ws}, FILE *@var{stream})
920 The function @code{fputws} writes the wide character string @var{ws} to
921 the stream @var{stream}. The terminating null character is not written.
922 This function does @emph{not} add a newline character, either. It
923 outputs only the characters in the string.
925 This function returns @code{WEOF} if a write error occurs, and otherwise
926 a non-negative value.
931 @deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream})
932 The @code{fputs_unlocked} function is equivalent to the @code{fputs}
933 function except that it does not implicitly lock the stream.
935 This function is a GNU extension.
940 @deftypefun int fputws_unlocked (const wchar_t *@var{ws}, FILE *@var{stream})
941 The @code{fputws_unlocked} function is equivalent to the @code{fputws}
942 function except that it does not implicitly lock the stream.
944 This function is a GNU extension.
949 @deftypefun int puts (const char *@var{s})
950 The @code{puts} function writes the string @var{s} to the stream
951 @code{stdout} followed by a newline. The terminating null character of
952 the string is not written. (Note that @code{fputs} does @emph{not}
953 write a newline as this function does.)
955 @code{puts} is the most convenient function for printing simple
956 messages. For example:
959 puts ("This is a message.");
963 outputs the text @samp{This is a message.} followed by a newline.
968 @deftypefun int putw (int @var{w}, FILE *@var{stream})
969 This function writes the word @var{w} (that is, an @code{int}) to
970 @var{stream}. It is provided for compatibility with SVID, but we
971 recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
974 @node Character Input
975 @section Character Input
977 @cindex reading from a stream, by characters
978 This section describes functions for performing character-oriented
979 input. These narrow streams functions are declared in the header file
980 @file{stdio.h} and the wide character functions are declared in
985 These functions return an @code{int} or @code{wint_t} value (for narrow
986 and wide stream functions respectively) that is either a character of
987 input, or the special value @code{EOF}/@code{WEOF} (usually -1). For
988 the narrow stream functions it is important to store the result of these
989 functions in a variable of type @code{int} instead of @code{char}, even
990 when you plan to use it only as a character. Storing @code{EOF} in a
991 @code{char} variable truncates its value to the size of a character, so
992 that it is no longer distinguishable from the valid character
993 @samp{(char) -1}. So always use an @code{int} for the result of
994 @code{getc} and friends, and check for @code{EOF} after the call; once
995 you've verified that the result is not @code{EOF}, you can be sure that
996 it will fit in a @samp{char} variable without loss of information.
1000 @deftypefun int fgetc (FILE *@var{stream})
1001 This function reads the next character as an @code{unsigned char} from
1002 the stream @var{stream} and returns its value, converted to an
1003 @code{int}. If an end-of-file condition or read error occurs,
1004 @code{EOF} is returned instead.
1009 @deftypefun wint_t fgetwc (FILE *@var{stream})
1010 This function reads the next wide character from the stream @var{stream}
1011 and returns its value. If an end-of-file condition or read error
1012 occurs, @code{WEOF} is returned instead.
1017 @deftypefun int fgetc_unlocked (FILE *@var{stream})
1018 The @code{fgetc_unlocked} function is equivalent to the @code{fgetc}
1019 function except that it does not implicitly lock the stream.
1024 @deftypefun wint_t fgetwc_unlocked (FILE *@var{stream})
1025 The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc}
1026 function except that it does not implicitly lock the stream.
1028 This function is a GNU extension.
1033 @deftypefun int getc (FILE *@var{stream})
1034 This is just like @code{fgetc}, except that it is permissible (and
1035 typical) for it to be implemented as a macro that evaluates the
1036 @var{stream} argument more than once. @code{getc} is often highly
1037 optimized, so it is usually the best function to use to read a single
1043 @deftypefun wint_t getwc (FILE *@var{stream})
1044 This is just like @code{fgetwc}, except that it is permissible for it to
1045 be implemented as a macro that evaluates the @var{stream} argument more
1046 than once. @code{getwc} can be highly optimized, so it is usually the
1047 best function to use to read a single wide character.
1052 @deftypefun int getc_unlocked (FILE *@var{stream})
1053 The @code{getc_unlocked} function is equivalent to the @code{getc}
1054 function except that it does not implicitly lock the stream.
1059 @deftypefun wint_t getwc_unlocked (FILE *@var{stream})
1060 The @code{getwc_unlocked} function is equivalent to the @code{getwc}
1061 function except that it does not implicitly lock the stream.
1063 This function is a GNU extension.
1068 @deftypefun int getchar (void)
1069 The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
1070 as the value of the @var{stream} argument.
1075 @deftypefun wint_t getwchar (void)
1076 The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin}
1077 as the value of the @var{stream} argument.
1082 @deftypefun int getchar_unlocked (void)
1083 The @code{getchar_unlocked} function is equivalent to the @code{getchar}
1084 function except that it does not implicitly lock the stream.
1089 @deftypefun wint_t getwchar_unlocked (void)
1090 The @code{getwchar_unlocked} function is equivalent to the @code{getwchar}
1091 function except that it does not implicitly lock the stream.
1093 This function is a GNU extension.
1096 Here is an example of a function that does input using @code{fgetc}. It
1097 would work just as well using @code{getc} instead, or using
1098 @code{getchar ()} instead of @w{@code{fgetc (stdin)}}. The code would
1099 also work the same for the wide character stream functions.
1103 y_or_n_p (const char *question)
1105 fputs (question, stdout);
1109 /* @r{Write a space to separate answer from question.} */
1110 fputc (' ', stdout);
1111 /* @r{Read the first character of the line.}
1112 @r{This should be the answer character, but might not be.} */
1113 c = tolower (fgetc (stdin));
1115 /* @r{Discard rest of input line.} */
1116 while (c != '\n' && c != EOF)
1118 /* @r{Obey the answer if it was valid.} */
1123 /* @r{Answer was invalid: ask for valid answer.} */
1124 fputs ("Please answer y or n:", stdout);
1131 @deftypefun int getw (FILE *@var{stream})
1132 This function reads a word (that is, an @code{int}) from @var{stream}.
1133 It's provided for compatibility with SVID. We recommend you use
1134 @code{fread} instead (@pxref{Block Input/Output}). Unlike @code{getc},
1135 any @code{int} value could be a valid result. @code{getw} returns
1136 @code{EOF} when it encounters end-of-file or an error, but there is no
1137 way to distinguish this from an input word with value -1.
1141 @section Line-Oriented Input
1143 Since many programs interpret input on the basis of lines, it is
1144 convenient to have functions to read a line of text from a stream.
1146 Standard C has functions to do this, but they aren't very safe: null
1147 characters and even (for @code{gets}) long lines can confuse them. So
1148 the GNU library provides the nonstandard @code{getline} function that
1149 makes it easy to read lines reliably.
1151 Another GNU extension, @code{getdelim}, generalizes @code{getline}. It
1152 reads a delimited record, defined as everything through the next
1153 occurrence of a specified delimiter character.
1155 All these functions are declared in @file{stdio.h}.
1159 @deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
1160 This function reads an entire line from @var{stream}, storing the text
1161 (including the newline and a terminating null character) in a buffer
1162 and storing the buffer address in @code{*@var{lineptr}}.
1164 Before calling @code{getline}, you should place in @code{*@var{lineptr}}
1165 the address of a buffer @code{*@var{n}} bytes long, allocated with
1166 @code{malloc}. If this buffer is long enough to hold the line,
1167 @code{getline} stores the line in this buffer. Otherwise,
1168 @code{getline} makes the buffer bigger using @code{realloc}, storing the
1169 new buffer address back in @code{*@var{lineptr}} and the increased size
1170 back in @code{*@var{n}}.
1171 @xref{Unconstrained Allocation}.
1173 If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}}
1174 to zero, before the call, then @code{getline} allocates the initial
1175 buffer for you by calling @code{malloc}.
1177 In either case, when @code{getline} returns, @code{*@var{lineptr}} is
1178 a @code{char *} which points to the text of the line.
1180 When @code{getline} is successful, it returns the number of characters
1181 read (including the newline, but not including the terminating null).
1182 This value enables you to distinguish null characters that are part of
1183 the line from the null character inserted as a terminator.
1185 This function is a GNU extension, but it is the recommended way to read
1186 lines from a stream. The alternative standard functions are unreliable.
1188 If an error occurs or end of file is reached without any bytes read,
1189 @code{getline} returns @code{-1}.
1194 @deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream})
1195 This function is like @code{getline} except that the character which
1196 tells it to stop reading is not necessarily newline. The argument
1197 @var{delimiter} specifies the delimiter character; @code{getdelim} keeps
1198 reading until it sees that character (or end of file).
1200 The text is stored in @var{lineptr}, including the delimiter character
1201 and a terminating null. Like @code{getline}, @code{getdelim} makes
1202 @var{lineptr} bigger if it isn't big enough.
1204 @code{getline} is in fact implemented in terms of @code{getdelim}, just
1209 getline (char **lineptr, size_t *n, FILE *stream)
1211 return getdelim (lineptr, n, '\n', stream);
1218 @deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
1219 The @code{fgets} function reads characters from the stream @var{stream}
1220 up to and including a newline character and stores them in the string
1221 @var{s}, adding a null character to mark the end of the string. You
1222 must supply @var{count} characters worth of space in @var{s}, but the
1223 number of characters read is at most @var{count} @minus{} 1. The extra
1224 character space is used to hold the null character at the end of the
1227 If the system is already at end of file when you call @code{fgets}, then
1228 the contents of the array @var{s} are unchanged and a null pointer is
1229 returned. A null pointer is also returned if a read error occurs.
1230 Otherwise, the return value is the pointer @var{s}.
1232 @strong{Warning:} If the input data has a null character, you can't tell.
1233 So don't use @code{fgets} unless you know the data cannot contain a null.
1234 Don't use it to read files edited by the user because, if the user inserts
1235 a null character, you should either handle it properly or print a clear
1236 error message. We recommend using @code{getline} instead of @code{fgets}.
1241 @deftypefun {wchar_t *} fgetws (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
1242 The @code{fgetws} function reads wide characters from the stream
1243 @var{stream} up to and including a newline character and stores them in
1244 the string @var{ws}, adding a null wide character to mark the end of the
1245 string. You must supply @var{count} wide characters worth of space in
1246 @var{ws}, but the number of characters read is at most @var{count}
1247 @minus{} 1. The extra character space is used to hold the null wide
1248 character at the end of the string.
1250 If the system is already at end of file when you call @code{fgetws}, then
1251 the contents of the array @var{ws} are unchanged and a null pointer is
1252 returned. A null pointer is also returned if a read error occurs.
1253 Otherwise, the return value is the pointer @var{ws}.
1255 @strong{Warning:} If the input data has a null wide character (which are
1256 null bytes in the input stream), you can't tell. So don't use
1257 @code{fgetws} unless you know the data cannot contain a null. Don't use
1258 it to read files edited by the user because, if the user inserts a null
1259 character, you should either handle it properly or print a clear error
1261 @comment XXX We need getwline!!!
1266 @deftypefun {char *} fgets_unlocked (char *@var{s}, int @var{count}, FILE *@var{stream})
1267 The @code{fgets_unlocked} function is equivalent to the @code{fgets}
1268 function except that it does not implicitly lock the stream.
1270 This function is a GNU extension.
1275 @deftypefun {wchar_t *} fgetws_unlocked (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
1276 The @code{fgetws_unlocked} function is equivalent to the @code{fgetws}
1277 function except that it does not implicitly lock the stream.
1279 This function is a GNU extension.
1284 @deftypefn {Deprecated function} {char *} gets (char *@var{s})
1285 The function @code{gets} reads characters from the stream @code{stdin}
1286 up to the next newline character, and stores them in the string @var{s}.
1287 The newline character is discarded (note that this differs from the
1288 behavior of @code{fgets}, which copies the newline character into the
1289 string). If @code{gets} encounters a read error or end-of-file, it
1290 returns a null pointer; otherwise it returns @var{s}.
1292 @strong{Warning:} The @code{gets} function is @strong{very dangerous}
1293 because it provides no protection against overflowing the string
1294 @var{s}. The GNU library includes it for compatibility only. You
1295 should @strong{always} use @code{fgets} or @code{getline} instead. To
1296 remind you of this, the linker (if using GNU @code{ld}) will issue a
1297 warning whenever you use @code{gets}.
1302 @cindex peeking at input
1303 @cindex unreading characters
1304 @cindex pushing input back
1306 In parser programs it is often useful to examine the next character in
1307 the input stream without removing it from the stream. This is called
1308 ``peeking ahead'' at the input because your program gets a glimpse of
1309 the input it will read next.
1311 Using stream I/O, you can peek ahead at input by first reading it and
1312 then @dfn{unreading} it (also called @dfn{pushing it back} on the stream).
1313 Unreading a character makes it available to be input again from the stream,
1314 by the next call to @code{fgetc} or other input function on that stream.
1317 * Unreading Idea:: An explanation of unreading with pictures.
1318 * How Unread:: How to call @code{ungetc} to do unreading.
1321 @node Unreading Idea
1322 @subsection What Unreading Means
1324 Here is a pictorial explanation of unreading. Suppose you have a
1325 stream reading a file that contains just six characters, the letters
1326 @samp{foobar}. Suppose you have read three characters so far. The
1327 situation looks like this:
1335 so the next input character will be @samp{b}.
1337 @c @group Invalid outside @example
1338 If instead of reading @samp{b} you unread the letter @samp{o}, you get a
1339 situation like this:
1349 so that the next input characters will be @samp{o} and @samp{b}.
1353 If you unread @samp{9} instead of @samp{o}, you get this situation:
1363 so that the next input characters will be @samp{9} and @samp{b}.
1367 @subsection Using @code{ungetc} To Do Unreading
1369 The function to unread a character is called @code{ungetc}, because it
1370 reverses the action of @code{getc}.
1374 @deftypefun int ungetc (int @var{c}, FILE *@var{stream})
1375 The @code{ungetc} function pushes back the character @var{c} onto the
1376 input stream @var{stream}. So the next input from @var{stream} will
1377 read @var{c} before anything else.
1379 If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
1380 @code{EOF}. This lets you call @code{ungetc} with the return value of
1381 @code{getc} without needing to check for an error from @code{getc}.
1383 The character that you push back doesn't have to be the same as the last
1384 character that was actually read from the stream. In fact, it isn't
1385 necessary to actually read any characters from the stream before
1386 unreading them with @code{ungetc}! But that is a strange way to write a
1387 program; usually @code{ungetc} is used only to unread a character that
1388 was just read from the same stream. The GNU C library supports this
1389 even on files opened in binary mode, but other systems might not.
1391 The GNU C library only supports one character of pushback---in other
1392 words, it does not work to call @code{ungetc} twice without doing input
1393 in between. Other systems might let you push back multiple characters;
1394 then reading from the stream retrieves the characters in the reverse
1395 order that they were pushed.
1397 Pushing back characters doesn't alter the file; only the internal
1398 buffering for the stream is affected. If a file positioning function
1399 (such as @code{fseek}, @code{fseeko} or @code{rewind}; @pxref{File
1400 Positioning}) is called, any pending pushed-back characters are
1403 Unreading a character on a stream that is at end of file clears the
1404 end-of-file indicator for the stream, because it makes the character of
1405 input available. After you read that character, trying to read again
1406 will encounter end of file.
1411 @deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream})
1412 The @code{ungetwc} function behaves just like @code{ungetc} just that it
1413 pushes back a wide character.
1416 Here is an example showing the use of @code{getc} and @code{ungetc} to
1417 skip over whitespace characters. When this function reaches a
1418 non-whitespace character, it unreads that character to be seen again on
1419 the next read operation on the stream.
1426 skip_whitespace (FILE *stream)
1430 /* @r{No need to check for @code{EOF} because it is not}
1431 @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.} */
1433 while (isspace (c));
1438 @node Block Input/Output
1439 @section Block Input/Output
1441 This section describes how to do input and output operations on blocks
1442 of data. You can use these functions to read and write binary data, as
1443 well as to read and write text in fixed-size blocks instead of by
1444 characters or lines.
1445 @cindex binary I/O to a stream
1446 @cindex block I/O to a stream
1447 @cindex reading from a stream, by blocks
1448 @cindex writing to a stream, by blocks
1450 Binary files are typically used to read and write blocks of data in the
1451 same format as is used to represent the data in a running program. In
1452 other words, arbitrary blocks of memory---not just character or string
1453 objects---can be written to a binary file, and meaningfully read in
1454 again by the same program.
1456 Storing data in binary form is often considerably more efficient than
1457 using the formatted I/O functions. Also, for floating-point numbers,
1458 the binary form avoids possible loss of precision in the conversion
1459 process. On the other hand, binary files can't be examined or modified
1460 easily using many standard file utilities (such as text editors), and
1461 are not portable between different implementations of the language, or
1462 different kinds of computers.
1464 These functions are declared in @file{stdio.h}.
1469 @deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1470 This function reads up to @var{count} objects of size @var{size} into
1471 the array @var{data}, from the stream @var{stream}. It returns the
1472 number of objects actually read, which might be less than @var{count} if
1473 a read error occurs or the end of the file is reached. This function
1474 returns a value of zero (and doesn't read anything) if either @var{size}
1475 or @var{count} is zero.
1477 If @code{fread} encounters end of file in the middle of an object, it
1478 returns the number of complete objects read, and discards the partial
1479 object. Therefore, the stream remains at the actual end of the file.
1484 @deftypefun size_t fread_unlocked (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1485 The @code{fread_unlocked} function is equivalent to the @code{fread}
1486 function except that it does not implicitly lock the stream.
1488 This function is a GNU extension.
1493 @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1494 This function writes up to @var{count} objects of size @var{size} from
1495 the array @var{data}, to the stream @var{stream}. The return value is
1496 normally @var{count}, if the call succeeds. Any other value indicates
1497 some sort of error, such as running out of space.
1502 @deftypefun size_t fwrite_unlocked (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1503 The @code{fwrite_unlocked} function is equivalent to the @code{fwrite}
1504 function except that it does not implicitly lock the stream.
1506 This function is a GNU extension.
1509 @node Formatted Output
1510 @section Formatted Output
1512 @cindex format string, for @code{printf}
1513 @cindex template, for @code{printf}
1514 @cindex formatted output to a stream
1515 @cindex writing to a stream, formatted
1516 The functions described in this section (@code{printf} and related
1517 functions) provide a convenient way to perform formatted output. You
1518 call @code{printf} with a @dfn{format string} or @dfn{template string}
1519 that specifies how to format the values of the remaining arguments.
1521 Unless your program is a filter that specifically performs line- or
1522 character-oriented processing, using @code{printf} or one of the other
1523 related functions described in this section is usually the easiest and
1524 most concise way to perform output. These functions are especially
1525 useful for printing error messages, tables of data, and the like.
1528 * Formatted Output Basics:: Some examples to get you started.
1529 * Output Conversion Syntax:: General syntax of conversion
1531 * Table of Output Conversions:: Summary of output conversions and
1533 * Integer Conversions:: Details about formatting of integers.
1534 * Floating-Point Conversions:: Details about formatting of
1535 floating-point numbers.
1536 * Other Output Conversions:: Details about formatting of strings,
1537 characters, pointers, and the like.
1538 * Formatted Output Functions:: Descriptions of the actual functions.
1539 * Dynamic Output:: Functions that allocate memory for the output.
1540 * Variable Arguments Output:: @code{vprintf} and friends.
1541 * Parsing a Template String:: What kinds of args does a given template
1543 * Example of Parsing:: Sample program using @code{parse_printf_format}.
1546 @node Formatted Output Basics
1547 @subsection Formatted Output Basics
1549 The @code{printf} function can be used to print any number of arguments.
1550 The template string argument you supply in a call provides
1551 information not only about the number of additional arguments, but also
1552 about their types and what style should be used for printing them.
1554 Ordinary characters in the template string are simply written to the
1555 output stream as-is, while @dfn{conversion specifications} introduced by
1556 a @samp{%} character in the template cause subsequent arguments to be
1557 formatted and written to the output stream. For example,
1558 @cindex conversion specifications (@code{printf})
1562 char filename[] = "foo.txt";
1563 printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
1568 produces output like
1571 Processing of `foo.txt' is 37% finished.
1575 This example shows the use of the @samp{%d} conversion to specify that
1576 an @code{int} argument should be printed in decimal notation, the
1577 @samp{%s} conversion to specify printing of a string argument, and
1578 the @samp{%%} conversion to print a literal @samp{%} character.
1580 There are also conversions for printing an integer argument as an
1581 unsigned value in octal, decimal, or hexadecimal radix (@samp{%o},
1582 @samp{%u}, or @samp{%x}, respectively); or as a character value
1585 Floating-point numbers can be printed in normal, fixed-point notation
1586 using the @samp{%f} conversion or in exponential notation using the
1587 @samp{%e} conversion. The @samp{%g} conversion uses either @samp{%e}
1588 or @samp{%f} format, depending on what is more appropriate for the
1589 magnitude of the particular number.
1591 You can control formatting more precisely by writing @dfn{modifiers}
1592 between the @samp{%} and the character that indicates which conversion
1593 to apply. These slightly alter the ordinary behavior of the conversion.
1594 For example, most conversion specifications permit you to specify a
1595 minimum field width and a flag indicating whether you want the result
1596 left- or right-justified within the field.
1598 The specific flags and modifiers that are permitted and their
1599 interpretation vary depending on the particular conversion. They're all
1600 described in more detail in the following sections. Don't worry if this
1601 all seems excessively complicated at first; you can almost always get
1602 reasonable free-format output without using any of the modifiers at all.
1603 The modifiers are mostly used to make the output look ``prettier'' in
1606 @node Output Conversion Syntax
1607 @subsection Output Conversion Syntax
1609 This section provides details about the precise syntax of conversion
1610 specifications that can appear in a @code{printf} template
1613 Characters in the template string that are not part of a conversion
1614 specification are printed as-is to the output stream. Multibyte
1615 character sequences (@pxref{Character Set Handling}) are permitted in a
1618 The conversion specifications in a @code{printf} template string have
1622 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion}
1629 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} . @r{*} @r{[} @var{param-no} @r{$]} @var{type} @var{conversion}
1632 For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-}
1633 is a flag, @samp{10} specifies the field width, the precision is
1634 @samp{8}, the letter @samp{l} is a type modifier, and @samp{d} specifies
1635 the conversion style. (This particular type specifier says to
1636 print a @code{long int} argument in decimal notation, with a minimum of
1637 8 digits left-justified in a field at least 10 characters wide.)
1639 In more detail, output conversion specifications consist of an
1640 initial @samp{%} character followed in sequence by:
1644 An optional specification of the parameter used for this format.
1645 Normally the parameters to the @code{printf} function are assigned to the
1646 formats in the order of appearance in the format string. But in some
1647 situations (such as message translation) this is not desirable and this
1648 extension allows an explicit parameter to be specified.
1650 The @var{param-no} parts of the format must be integers in the range of
1651 1 to the maximum number of arguments present to the function call. Some
1652 implementations limit this number to a certainly upper bound. The exact
1653 limit can be retrieved by the following constant.
1655 @defvr Macro NL_ARGMAX
1656 The value of @code{NL_ARGMAX} is the maximum value allowed for the
1657 specification of an positional parameter in a @code{printf} call. The
1658 actual value in effect at runtime can be retrieved by using
1659 @code{sysconf} using the @code{_SC_NL_ARGMAX} parameter @pxref{Sysconf
1662 Some system have a quite low limit such as @math{9} for @w{System V}
1663 systems. The GNU C library has no real limit.
1666 If any of the formats has a specification for the parameter position all
1667 of them in the format string shall have one. Otherwise the behavior is
1671 Zero or more @dfn{flag characters} that modify the normal behavior of
1672 the conversion specification.
1673 @cindex flag character (@code{printf})
1676 An optional decimal integer specifying the @dfn{minimum field width}.
1677 If the normal conversion produces fewer characters than this, the field
1678 is padded with spaces to the specified width. This is a @emph{minimum}
1679 value; if the normal conversion produces more characters than this, the
1680 field is @emph{not} truncated. Normally, the output is right-justified
1682 @cindex minimum field width (@code{printf})
1684 You can also specify a field width of @samp{*}. This means that the
1685 next argument in the argument list (before the actual value to be
1686 printed) is used as the field width. The value must be an @code{int}.
1687 If the value is negative, this means to set the @samp{-} flag (see
1688 below) and to use the absolute value as the field width.
1691 An optional @dfn{precision} to specify the number of digits to be
1692 written for the numeric conversions. If the precision is specified, it
1693 consists of a period (@samp{.}) followed optionally by a decimal integer
1694 (which defaults to zero if omitted).
1695 @cindex precision (@code{printf})
1697 You can also specify a precision of @samp{*}. This means that the next
1698 argument in the argument list (before the actual value to be printed) is
1699 used as the precision. The value must be an @code{int}, and is ignored
1700 if it is negative. If you specify @samp{*} for both the field width and
1701 precision, the field width argument precedes the precision argument.
1702 Other C library versions may not recognize this syntax.
1705 An optional @dfn{type modifier character}, which is used to specify the
1706 data type of the corresponding argument if it differs from the default
1707 type. (For example, the integer conversions assume a type of @code{int},
1708 but you can specify @samp{h}, @samp{l}, or @samp{L} for other integer
1710 @cindex type modifier character (@code{printf})
1713 A character that specifies the conversion to be applied.
1716 The exact options that are permitted and how they are interpreted vary
1717 between the different conversion specifiers. See the descriptions of the
1718 individual conversions for information about the particular options that
1721 With the @samp{-Wformat} option, the GNU C compiler checks calls to
1722 @code{printf} and related functions. It examines the format string and
1723 verifies that the correct number and types of arguments are supplied.
1724 There is also a GNU C syntax to tell the compiler that a function you
1725 write uses a @code{printf}-style format string.
1726 @xref{Function Attributes, , Declaring Attributes of Functions,
1727 gcc.info, Using GNU CC}, for more information.
1729 @node Table of Output Conversions
1730 @subsection Table of Output Conversions
1731 @cindex output conversions, for @code{printf}
1733 Here is a table summarizing what all the different conversions do:
1736 @item @samp{%d}, @samp{%i}
1737 Print an integer as a signed decimal number. @xref{Integer
1738 Conversions}, for details. @samp{%d} and @samp{%i} are synonymous for
1739 output, but are different when used with @code{scanf} for input
1740 (@pxref{Table of Input Conversions}).
1743 Print an integer as an unsigned octal number. @xref{Integer
1744 Conversions}, for details.
1747 Print an integer as an unsigned decimal number. @xref{Integer
1748 Conversions}, for details.
1750 @item @samp{%x}, @samp{%X}
1751 Print an integer as an unsigned hexadecimal number. @samp{%x} uses
1752 lower-case letters and @samp{%X} uses upper-case. @xref{Integer
1753 Conversions}, for details.
1756 Print a floating-point number in normal (fixed-point) notation.
1757 @xref{Floating-Point Conversions}, for details.
1759 @item @samp{%e}, @samp{%E}
1760 Print a floating-point number in exponential notation. @samp{%e} uses
1761 lower-case letters and @samp{%E} uses upper-case. @xref{Floating-Point
1762 Conversions}, for details.
1764 @item @samp{%g}, @samp{%G}
1765 Print a floating-point number in either normal or exponential notation,
1766 whichever is more appropriate for its magnitude. @samp{%g} uses
1767 lower-case letters and @samp{%G} uses upper-case. @xref{Floating-Point
1768 Conversions}, for details.
1770 @item @samp{%a}, @samp{%A}
1771 Print a floating-point number in a hexadecimal fractional notation which
1772 the exponent to base 2 represented in decimal digits. @samp{%a} uses
1773 lower-case letters and @samp{%A} uses upper-case. @xref{Floating-Point
1774 Conversions}, for details.
1777 Print a single character. @xref{Other Output Conversions}.
1780 This is an alias for @samp{%lc} which is supported for compatibility
1781 with the Unix standard.
1784 Print a string. @xref{Other Output Conversions}.
1787 This is an alias for @samp{%ls} which is supported for compatibility
1788 with the Unix standard.
1791 Print the value of a pointer. @xref{Other Output Conversions}.
1794 Get the number of characters printed so far. @xref{Other Output Conversions}.
1795 Note that this conversion specification never produces any output.
1798 Print the string corresponding to the value of @code{errno}.
1799 (This is a GNU extension.)
1800 @xref{Other Output Conversions}.
1803 Print a literal @samp{%} character. @xref{Other Output Conversions}.
1806 If the syntax of a conversion specification is invalid, unpredictable
1807 things will happen, so don't do this. If there aren't enough function
1808 arguments provided to supply values for all the conversion
1809 specifications in the template string, or if the arguments are not of
1810 the correct types, the results are unpredictable. If you supply more
1811 arguments than conversion specifications, the extra argument values are
1812 simply ignored; this is sometimes useful.
1814 @node Integer Conversions
1815 @subsection Integer Conversions
1817 This section describes the options for the @samp{%d}, @samp{%i},
1818 @samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
1819 specifications. These conversions print integers in various formats.
1821 The @samp{%d} and @samp{%i} conversion specifications both print an
1822 @code{int} argument as a signed decimal number; while @samp{%o},
1823 @samp{%u}, and @samp{%x} print the argument as an unsigned octal,
1824 decimal, or hexadecimal number (respectively). The @samp{%X} conversion
1825 specification is just like @samp{%x} except that it uses the characters
1826 @samp{ABCDEF} as digits instead of @samp{abcdef}.
1828 The following flags are meaningful:
1832 Left-justify the result in the field (instead of the normal
1833 right-justification).
1836 For the signed @samp{%d} and @samp{%i} conversions, print a
1837 plus sign if the value is positive.
1840 For the signed @samp{%d} and @samp{%i} conversions, if the result
1841 doesn't start with a plus or minus sign, prefix it with a space
1842 character instead. Since the @samp{+} flag ensures that the result
1843 includes a sign, this flag is ignored if you supply both of them.
1846 For the @samp{%o} conversion, this forces the leading digit to be
1847 @samp{0}, as if by increasing the precision. For @samp{%x} or
1848 @samp{%X}, this prefixes a leading @samp{0x} or @samp{0X} (respectively)
1849 to the result. This doesn't do anything useful for the @samp{%d},
1850 @samp{%i}, or @samp{%u} conversions. Using this flag produces output
1851 which can be parsed by the @code{strtoul} function (@pxref{Parsing of
1852 Integers}) and @code{scanf} with the @samp{%i} conversion
1853 (@pxref{Numeric Input Conversions}).
1856 Separate the digits into groups as specified by the locale specified for
1857 the @code{LC_NUMERIC} category; @pxref{General Numeric}. This flag is a
1861 Pad the field with zeros instead of spaces. The zeros are placed after
1862 any indication of sign or base. This flag is ignored if the @samp{-}
1863 flag is also specified, or if a precision is specified.
1866 If a precision is supplied, it specifies the minimum number of digits to
1867 appear; leading zeros are produced if necessary. If you don't specify a
1868 precision, the number is printed with as many digits as it needs. If
1869 you convert a value of zero with an explicit precision of zero, then no
1870 characters at all are produced.
1872 Without a type modifier, the corresponding argument is treated as an
1873 @code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
1874 @code{unsigned int} (for the unsigned conversions @samp{%o}, @samp{%u},
1875 @samp{%x}, and @samp{%X}). Recall that since @code{printf} and friends
1876 are variadic, any @code{char} and @code{short} arguments are
1877 automatically converted to @code{int} by the default argument
1878 promotions. For arguments of other integer types, you can use these
1883 Specifies that the argument is a @code{signed char} or @code{unsigned
1884 char}, as appropriate. A @code{char} argument is converted to an
1885 @code{int} or @code{unsigned int} by the default argument promotions
1886 anyway, but the @samp{h} modifier says to convert it back to a
1889 This modifier was introduced in @w{ISO C99}.
1892 Specifies that the argument is a @code{short int} or @code{unsigned
1893 short int}, as appropriate. A @code{short} argument is converted to an
1894 @code{int} or @code{unsigned int} by the default argument promotions
1895 anyway, but the @samp{h} modifier says to convert it back to a
1899 Specifies that the argument is a @code{intmax_t} or @code{uintmax_t}, as
1902 This modifier was introduced in @w{ISO C99}.
1905 Specifies that the argument is a @code{long int} or @code{unsigned long
1906 int}, as appropriate. Two @samp{l} characters is like the @samp{L}
1909 If used with @samp{%c} or @samp{%s} the corresponding parameter is
1910 considered as a wide character or wide character string respectively.
1911 This use of @samp{l} was introduced in @w{Amendment 1} to @w{ISO C90}.
1916 Specifies that the argument is a @code{long long int}. (This type is
1917 an extension supported by the GNU C compiler. On systems that don't
1918 support extra-long integers, this is the same as @code{long int}.)
1920 The @samp{q} modifier is another name for the same thing, which comes
1921 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
1925 Specifies that the argument is a @code{ptrdiff_t}.
1927 This modifier was introduced in @w{ISO C99}.
1931 Specifies that the argument is a @code{size_t}.
1933 @samp{z} was introduced in @w{ISO C99}. @samp{Z} is a GNU extension
1934 predating this addition and should not be used in new code.
1937 Here is an example. Using the template string:
1940 "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
1944 to print numbers using the different options for the @samp{%d}
1945 conversion gives results like:
1948 | 0|0 | +0|+0 | 0|00000| | 00|0|
1949 | 1|1 | +1|+1 | 1|00001| 1| 01|1|
1950 | -1|-1 | -1|-1 | -1|-0001| -1| -01|-1|
1951 |100000|100000|+100000|+100000| 100000|100000|100000|100000|100000|
1954 In particular, notice what happens in the last case where the number
1955 is too large to fit in the minimum field width specified.
1957 Here are some more examples showing how unsigned integers print under
1958 various format options, using the template string:
1961 "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
1965 | 0| 0| 0| 0| 0| 0| 0| 00000000|
1966 | 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001|
1967 |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
1971 @node Floating-Point Conversions
1972 @subsection Floating-Point Conversions
1974 This section discusses the conversion specifications for floating-point
1975 numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G}
1978 The @samp{%f} conversion prints its argument in fixed-point notation,
1979 producing output of the form
1980 @w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
1981 where the number of digits following the decimal point is controlled
1982 by the precision you specify.
1984 The @samp{%e} conversion prints its argument in exponential notation,
1985 producing output of the form
1986 @w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}.
1987 Again, the number of digits following the decimal point is controlled by
1988 the precision. The exponent always contains at least two digits. The
1989 @samp{%E} conversion is similar but the exponent is marked with the letter
1990 @samp{E} instead of @samp{e}.
1992 The @samp{%g} and @samp{%G} conversions print the argument in the style
1993 of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
1994 than -4 or greater than or equal to the precision; otherwise they use
1995 the @samp{%f} style. A precision of @code{0}, is taken as 1. is
1996 Trailing zeros are removed from the fractional portion of the result and
1997 a decimal-point character appears only if it is followed by a digit.
1999 The @samp{%a} and @samp{%A} conversions are meant for representing
2000 floating-point numbers exactly in textual form so that they can be
2001 exchanged as texts between different programs and/or machines. The
2002 numbers are represented is the form
2003 @w{[@code{-}]@code{0x}@var{h}@code{.}@var{hhh}@code{p}[@code{+}|@code{-}]@var{dd}}.
2004 At the left of the decimal-point character exactly one digit is print.
2005 This character is only @code{0} if the number is denormalized.
2006 Otherwise the value is unspecified; it is implementation dependent how many
2007 bits are used. The number of hexadecimal digits on the right side of
2008 the decimal-point character is equal to the precision. If the precision
2009 is zero it is determined to be large enough to provide an exact
2010 representation of the number (or it is large enough to distinguish two
2011 adjacent values if the @code{FLT_RADIX} is not a power of 2,
2012 @pxref{Floating Point Parameters}). For the @samp{%a} conversion
2013 lower-case characters are used to represent the hexadecimal number and
2014 the prefix and exponent sign are printed as @code{0x} and @code{p}
2015 respectively. Otherwise upper-case characters are used and @code{0X}
2016 and @code{P} are used for the representation of prefix and exponent
2017 string. The exponent to the base of two is printed as a decimal number
2018 using at least one digit but at most as many digits as necessary to
2019 represent the value exactly.
2021 If the value to be printed represents infinity or a NaN, the output is
2022 @w{[@code{-}]@code{inf}} or @code{nan} respectively if the conversion
2023 specifier is @samp{%a}, @samp{%e}, @samp{%f}, or @samp{%g} and it is
2024 @w{[@code{-}]@code{INF}} or @code{NAN} respectively if the conversion is
2025 @samp{%A}, @samp{%E}, or @samp{%G}.
2027 The following flags can be used to modify the behavior:
2029 @comment We use @asis instead of @samp so we can have ` ' as an item.
2032 Left-justify the result in the field. Normally the result is
2036 Always include a plus or minus sign in the result.
2039 If the result doesn't start with a plus or minus sign, prefix it with a
2040 space instead. Since the @samp{+} flag ensures that the result includes
2041 a sign, this flag is ignored if you supply both of them.
2044 Specifies that the result should always include a decimal point, even
2045 if no digits follow it. For the @samp{%g} and @samp{%G} conversions,
2046 this also forces trailing zeros after the decimal point to be left
2047 in place where they would otherwise be removed.
2050 Separate the digits of the integer part of the result into groups as
2051 specified by the locale specified for the @code{LC_NUMERIC} category;
2052 @pxref{General Numeric}. This flag is a GNU extension.
2055 Pad the field with zeros instead of spaces; the zeros are placed
2056 after any sign. This flag is ignored if the @samp{-} flag is also
2060 The precision specifies how many digits follow the decimal-point
2061 character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions. For
2062 these conversions, the default precision is @code{6}. If the precision
2063 is explicitly @code{0}, this suppresses the decimal point character
2064 entirely. For the @samp{%g} and @samp{%G} conversions, the precision
2065 specifies how many significant digits to print. Significant digits are
2066 the first digit before the decimal point, and all the digits after it.
2067 If the precision is @code{0} or not specified for @samp{%g} or @samp{%G},
2068 it is treated like a value of @code{1}. If the value being printed
2069 cannot be expressed accurately in the specified number of digits, the
2070 value is rounded to the nearest number that fits.
2072 Without a type modifier, the floating-point conversions use an argument
2073 of type @code{double}. (By the default argument promotions, any
2074 @code{float} arguments are automatically converted to @code{double}.)
2075 The following type modifier is supported:
2079 An uppercase @samp{L} specifies that the argument is a @code{long
2083 Here are some examples showing how numbers print using the various
2084 floating-point conversions. All of the numbers were printed using
2085 this template string:
2088 "|%13.4a|%13.4f|%13.4e|%13.4g|\n"
2094 | 0x0.0000p+0| 0.0000| 0.0000e+00| 0|
2095 | 0x1.0000p-1| 0.5000| 5.0000e-01| 0.5|
2096 | 0x1.0000p+0| 1.0000| 1.0000e+00| 1|
2097 | -0x1.0000p+0| -1.0000| -1.0000e+00| -1|
2098 | 0x1.9000p+6| 100.0000| 1.0000e+02| 100|
2099 | 0x1.f400p+9| 1000.0000| 1.0000e+03| 1000|
2100 | 0x1.3880p+13| 10000.0000| 1.0000e+04| 1e+04|
2101 | 0x1.81c8p+13| 12345.0000| 1.2345e+04| 1.234e+04|
2102 | 0x1.86a0p+16| 100000.0000| 1.0000e+05| 1e+05|
2103 | 0x1.e240p+16| 123456.0000| 1.2346e+05| 1.235e+05|
2106 Notice how the @samp{%g} conversion drops trailing zeros.
2108 @node Other Output Conversions
2109 @subsection Other Output Conversions
2111 This section describes miscellaneous conversions for @code{printf}.
2113 The @samp{%c} conversion prints a single character. In case there is no
2114 @samp{l} modifier the @code{int} argument is first converted to an
2115 @code{unsigned char}. Then, if used in a wide stream function, the
2116 character is converted into the corresponding wide character. The
2117 @samp{-} flag can be used to specify left-justification in the field,
2118 but no other flags are defined, and no precision or type modifier can be
2122 printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
2126 prints @samp{hello}.
2128 If there is a @samp{l} modifier present the argument is expected to be
2129 of type @code{wint_t}. If used in a multibyte function the wide
2130 character is converted into a multibyte character before being added to
2131 the output. In this case more than one output byte can be produced.
2133 The @samp{%s} conversion prints a string. If no @samp{l} modifier is
2134 present the corresponding argument must be of type @code{char *} (or
2135 @code{const char *}). If used in a wide stream function the string is
2136 first converted in a wide character string. A precision can be
2137 specified to indicate the maximum number of characters to write;
2138 otherwise characters in the string up to but not including the
2139 terminating null character are written to the output stream. The
2140 @samp{-} flag can be used to specify left-justification in the field,
2141 but no other flags or type modifiers are defined for this conversion.
2145 printf ("%3s%-6s", "no", "where");
2149 prints @samp{ nowhere }.
2151 If there is a @samp{l} modifier present the argument is expected to be of type @code{wchar_t} (or @code{const wchar_t *}).
2153 If you accidentally pass a null pointer as the argument for a @samp{%s}
2154 conversion, the GNU library prints it as @samp{(null)}. We think this
2155 is more useful than crashing. But it's not good practice to pass a null
2156 argument intentionally.
2158 The @samp{%m} conversion prints the string corresponding to the error
2159 code in @code{errno}. @xref{Error Messages}. Thus:
2162 fprintf (stderr, "can't open `%s': %m\n", filename);
2169 fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
2173 The @samp{%m} conversion is a GNU C library extension.
2175 The @samp{%p} conversion prints a pointer value. The corresponding
2176 argument must be of type @code{void *}. In practice, you can use any
2179 In the GNU system, non-null pointers are printed as unsigned integers,
2180 as if a @samp{%#x} conversion were used. Null pointers print as
2181 @samp{(nil)}. (Pointers might print differently in other systems.)
2186 printf ("%p", "testing");
2190 prints @samp{0x} followed by a hexadecimal number---the address of the
2191 string constant @code{"testing"}. It does not print the word
2194 You can supply the @samp{-} flag with the @samp{%p} conversion to
2195 specify left-justification, but no other flags, precision, or type
2196 modifiers are defined.
2198 The @samp{%n} conversion is unlike any of the other output conversions.
2199 It uses an argument which must be a pointer to an @code{int}, but
2200 instead of printing anything it stores the number of characters printed
2201 so far by this call at that location. The @samp{h} and @samp{l} type
2202 modifiers are permitted to specify that the argument is of type
2203 @code{short int *} or @code{long int *} instead of @code{int *}, but no
2204 flags, field width, or precision are permitted.
2210 printf ("%d %s%n\n", 3, "bears", &nchar);
2221 and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven
2225 The @samp{%%} conversion prints a literal @samp{%} character. This
2226 conversion doesn't use an argument, and no flags, field width,
2227 precision, or type modifiers are permitted.
2230 @node Formatted Output Functions
2231 @subsection Formatted Output Functions
2233 This section describes how to call @code{printf} and related functions.
2234 Prototypes for these functions are in the header file @file{stdio.h}.
2235 Because these functions take a variable number of arguments, you
2236 @emph{must} declare prototypes for them before using them. Of course,
2237 the easiest way to make sure you have all the right prototypes is to
2238 just include @file{stdio.h}.
2243 @deftypefun int printf (const char *@var{template}, @dots{})
2244 The @code{printf} function prints the optional arguments under the
2245 control of the template string @var{template} to the stream
2246 @code{stdout}. It returns the number of characters printed, or a
2247 negative value if there was an output error.
2252 @deftypefun int wprintf (const wchar_t *@var{template}, @dots{})
2253 The @code{wprintf} function prints the optional arguments under the
2254 control of the wide template string @var{template} to the stream
2255 @code{stdout}. It returns the number of wide characters printed, or a
2256 negative value if there was an output error.
2261 @deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
2262 This function is just like @code{printf}, except that the output is
2263 written to the stream @var{stream} instead of @code{stdout}.
2268 @deftypefun int fwprintf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
2269 This function is just like @code{wprintf}, except that the output is
2270 written to the stream @var{stream} instead of @code{stdout}.
2275 @deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
2276 This is like @code{printf}, except that the output is stored in the character
2277 array @var{s} instead of written to a stream. A null character is written
2278 to mark the end of the string.
2280 The @code{sprintf} function returns the number of characters stored in
2281 the array @var{s}, not including the terminating null character.
2283 The behavior of this function is undefined if copying takes place
2284 between objects that overlap---for example, if @var{s} is also given
2285 as an argument to be printed under control of the @samp{%s} conversion.
2286 @xref{Copying and Concatenation}.
2288 @strong{Warning:} The @code{sprintf} function can be @strong{dangerous}
2289 because it can potentially output more characters than can fit in the
2290 allocation size of the string @var{s}. Remember that the field width
2291 given in a conversion specification is only a @emph{minimum} value.
2293 To avoid this problem, you can use @code{snprintf} or @code{asprintf},
2299 @deftypefun int swprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, @dots{})
2300 This is like @code{wprintf}, except that the output is stored in the
2301 wide character array @var{ws} instead of written to a stream. A null
2302 wide character is written to mark the end of the string. The @var{size}
2303 argument specifies the maximum number of characters to produce. The
2304 trailing null character is counted towards this limit, so you should
2305 allocate at least @var{size} wide characters for the string @var{ws}.
2307 The return value is the number of characters generated for the given
2308 input, excluding the trailing null. If not all output fits into the
2309 provided buffer a negative value is returned. You should try again with
2310 a bigger output string. @emph{Note:} this is different from how
2311 @code{snprintf} handles this situation.
2313 Note that the corresponding narrow stream function takes fewer
2314 parameters. @code{swprintf} in fact corresponds to the @code{snprintf}
2315 function. Since the @code{sprintf} function can be dangerous and should
2316 be avoided the @w{ISO C} committee refused to make the same mistake
2317 again and decided to not define an function exactly corresponding to
2323 @deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{})
2324 The @code{snprintf} function is similar to @code{sprintf}, except that
2325 the @var{size} argument specifies the maximum number of characters to
2326 produce. The trailing null character is counted towards this limit, so
2327 you should allocate at least @var{size} characters for the string @var{s}.
2329 The return value is the number of characters which would be generated
2330 for the given input, excluding the trailing null. If this value is
2331 greater or equal to @var{size}, not all characters from the result have
2332 been stored in @var{s}. You should try again with a bigger output
2333 string. Here is an example of doing this:
2337 /* @r{Construct a message describing the value of a variable}
2338 @r{whose name is @var{name} and whose value is @var{value}.} */
2340 make_message (char *name, char *value)
2342 /* @r{Guess we need no more than 100 chars of space.} */
2344 char *buffer = (char *) xmalloc (size);
2351 /* @r{Try to print in the allocated space.} */
2352 nchars = snprintf (buffer, size, "value of %s is %s",
2358 /* @r{Reallocate buffer now that we know
2359 how much space is needed.} */
2360 buffer = (char *) xrealloc (buffer, nchars + 1);
2363 /* @r{Try again.} */
2364 snprintf (buffer, size, "value of %s is %s",
2367 /* @r{The last call worked, return the string.} */
2373 In practice, it is often easier just to use @code{asprintf}, below.
2375 @strong{Attention:} In versions of the GNU C library prior to 2.1 the
2376 return value is the number of characters stored, not including the
2377 terminating null; unless there was not enough space in @var{s} to
2378 store the result in which case @code{-1} is returned. This was
2379 changed in order to comply with the @w{ISO C99} standard.
2382 @node Dynamic Output
2383 @subsection Dynamically Allocating Formatted Output
2385 The functions in this section do formatted output and place the results
2386 in dynamically allocated memory.
2390 @deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
2391 This function is similar to @code{sprintf}, except that it dynamically
2392 allocates a string (as with @code{malloc}; @pxref{Unconstrained
2393 Allocation}) to hold the output, instead of putting the output in a
2394 buffer you allocate in advance. The @var{ptr} argument should be the
2395 address of a @code{char *} object, and @code{asprintf} stores a pointer
2396 to the newly allocated string at that location.
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{Macro Varargs, , Macros with Variable Numbers of Arguments,
2458 gcc.info, Using GNU CC}, for details. But this is limited to macros,
2459 and does not apply to real functions at all.
2461 Before calling @code{vprintf} or the other functions listed in this
2462 section, you @emph{must} call @code{va_start} (@pxref{Variadic
2463 Functions}) to initialize a pointer to the variable arguments. Then you
2464 can call @code{va_arg} to fetch the arguments that you want to handle
2465 yourself. This advances the pointer past those arguments.
2467 Once your @code{va_list} pointer is pointing at the argument of your
2468 choice, you are ready to call @code{vprintf}. That argument and all
2469 subsequent arguments that were passed to your function are used by
2470 @code{vprintf} along with the template that you specified separately.
2472 In some other systems, the @code{va_list} pointer may become invalid
2473 after the call to @code{vprintf}, so you must not use @code{va_arg}
2474 after you call @code{vprintf}. Instead, you should call @code{va_end}
2475 to retire the pointer from service. However, you can safely call
2476 @code{va_start} on another pointer variable and begin fetching the
2477 arguments again through that pointer. Calling @code{vprintf} does not
2478 destroy the argument list of your function, merely the particular
2479 pointer that you passed to it.
2481 GNU C does not have such restrictions. You can safely continue to fetch
2482 arguments from a @code{va_list} pointer after passing it to
2483 @code{vprintf}, and @code{va_end} is a no-op. (Note, however, that
2484 subsequent @code{va_arg} calls will fetch the same arguments which
2485 @code{vprintf} previously used.)
2487 Prototypes for these functions are declared in @file{stdio.h}.
2492 @deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
2493 This function is similar to @code{printf} except that, instead of taking
2494 a variable number of arguments directly, it takes an argument list
2500 @deftypefun int vwprintf (const wchar_t *@var{template}, va_list @var{ap})
2501 This function is similar to @code{wprintf} except that, instead of taking
2502 a variable number of arguments directly, it takes an argument list
2508 @deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
2509 This is the equivalent of @code{fprintf} with the variable argument list
2510 specified directly as for @code{vprintf}.
2515 @deftypefun int vfwprintf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
2516 This is the equivalent of @code{fwprintf} with the variable argument list
2517 specified directly as for @code{vwprintf}.
2522 @deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
2523 This is the equivalent of @code{sprintf} with the variable argument list
2524 specified directly as for @code{vprintf}.
2529 @deftypefun int vswprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap})
2530 This is the equivalent of @code{swprintf} with the variable argument list
2531 specified directly as for @code{vwprintf}.
2536 @deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
2537 This is the equivalent of @code{snprintf} with the variable argument list
2538 specified directly as for @code{vprintf}.
2543 @deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
2544 The @code{vasprintf} function is the equivalent of @code{asprintf} with the
2545 variable argument list specified directly as for @code{vprintf}.
2550 @deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
2551 The @code{obstack_vprintf} function is the equivalent of
2552 @code{obstack_printf} with the variable argument list specified directly
2553 as for @code{vprintf}.@refill
2556 Here's an example showing how you might use @code{vfprintf}. This is a
2557 function that prints error messages to the stream @code{stderr}, along
2558 with a prefix indicating the name of the program
2559 (@pxref{Error Messages}, for a description of
2560 @code{program_invocation_short_name}).
2568 eprintf (const char *template, ...)
2571 extern char *program_invocation_short_name;
2573 fprintf (stderr, "%s: ", program_invocation_short_name);
2574 va_start (ap, template);
2575 vfprintf (stderr, template, ap);
2582 You could call @code{eprintf} like this:
2585 eprintf ("file `%s' does not exist\n", filename);
2588 In GNU C, there is a special construct you can use to let the compiler
2589 know that a function uses a @code{printf}-style format string. Then it
2590 can check the number and types of arguments in each call to the
2591 function, and warn you when they do not match the format string.
2592 For example, take this declaration of @code{eprintf}:
2595 void eprintf (const char *template, ...)
2596 __attribute__ ((format (printf, 1, 2)));
2600 This tells the compiler that @code{eprintf} uses a format string like
2601 @code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input});
2602 the format string appears as the first argument;
2603 and the arguments to satisfy the format begin with the second.
2604 @xref{Function Attributes, , Declaring Attributes of Functions,
2605 gcc.info, Using GNU CC}, for more information.
2607 @node Parsing a Template String
2608 @subsection Parsing a Template String
2609 @cindex parsing a template string
2611 You can use the function @code{parse_printf_format} to obtain
2612 information about the number and types of arguments that are expected by
2613 a given template string. This function permits interpreters that
2614 provide interfaces to @code{printf} to avoid passing along invalid
2615 arguments from the user's program, which could cause a crash.
2617 All the symbols described in this section are declared in the header
2618 file @file{printf.h}.
2622 @deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
2623 This function returns information about the number and types of
2624 arguments expected by the @code{printf} template string @var{template}.
2625 The information is stored in the array @var{argtypes}; each element of
2626 this array describes one argument. This information is encoded using
2627 the various @samp{PA_} macros, listed below.
2629 The argument @var{n} specifies the number of elements in the array
2630 @var{argtypes}. This is the maximum number of elements that
2631 @code{parse_printf_format} will try to write.
2633 @code{parse_printf_format} returns the total number of arguments required
2634 by @var{template}. If this number is greater than @var{n}, then the
2635 information returned describes only the first @var{n} arguments. If you
2636 want information about additional arguments, allocate a bigger
2637 array and call @code{parse_printf_format} again.
2640 The argument types are encoded as a combination of a basic type and
2645 @deftypevr Macro int PA_FLAG_MASK
2646 This macro is a bitmask for the type modifier flag bits. You can write
2647 the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the
2648 flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to
2649 extract just the basic type code.
2652 Here are symbolic constants that represent the basic types; they stand
2659 This specifies that the base type is @code{int}.
2664 This specifies that the base type is @code{int}, cast to @code{char}.
2669 This specifies that the base type is @code{char *}, a null-terminated string.
2674 This specifies that the base type is @code{void *}, an arbitrary pointer.
2679 This specifies that the base type is @code{float}.
2684 This specifies that the base type is @code{double}.
2689 You can define additional base types for your own programs as offsets
2690 from @code{PA_LAST}. For example, if you have data types @samp{foo}
2691 and @samp{bar} with their own specialized @code{printf} conversions,
2692 you could define encodings for these types as:
2695 #define PA_FOO PA_LAST
2696 #define PA_BAR (PA_LAST + 1)
2700 Here are the flag bits that modify a basic type. They are combined with
2701 the code for the basic type using inclusive-or.
2707 If this bit is set, it indicates that the encoded type is a pointer to
2708 the base type, rather than an immediate value.
2709 For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.
2714 If this bit is set, it indicates that the base type is modified with
2715 @code{short}. (This corresponds to the @samp{h} type modifier.)
2720 If this bit is set, it indicates that the base type is modified with
2721 @code{long}. (This corresponds to the @samp{l} type modifier.)
2725 @item PA_FLAG_LONG_LONG
2726 If this bit is set, it indicates that the base type is modified with
2727 @code{long long}. (This corresponds to the @samp{L} type modifier.)
2731 @item PA_FLAG_LONG_DOUBLE
2732 This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with
2733 a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
2737 For an example of using these facilities, see @ref{Example of Parsing}.
2740 @node Example of Parsing
2741 @subsection Example of Parsing a Template String
2743 Here is an example of decoding argument types for a format string. We
2744 assume this is part of an interpreter which contains arguments of type
2745 @code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
2746 perhaps others which are not valid here).
2749 /* @r{Test whether the @var{nargs} specified objects}
2750 @r{in the vector @var{args} are valid}
2751 @r{for the format string @var{format}:}
2752 @r{if so, return 1.}
2753 @r{If not, return 0 after printing an error message.} */
2756 validate_args (char *format, int nargs, OBJECT *args)
2761 /* @r{Get the information about the arguments.}
2762 @r{Each conversion specification must be at least two characters}
2763 @r{long, so there cannot be more specifications than half the}
2764 @r{length of the string.} */
2766 argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
2767 nwanted = parse_printf_format (string, nelts, argtypes);
2769 /* @r{Check the number of arguments.} */
2770 if (nwanted > nargs)
2772 error ("too few arguments (at least %d required)", nwanted);
2776 /* @r{Check the C type wanted for each argument}
2777 @r{and see if the object given is suitable.} */
2778 for (i = 0; i < nwanted; i++)
2782 if (argtypes[i] & PA_FLAG_PTR)
2785 switch (argtypes[i] & ~PA_FLAG_MASK)
2802 if (TYPE (args[i]) != wanted)
2804 error ("type mismatch for arg number %d", i);
2812 @node Customizing Printf
2813 @section Customizing @code{printf}
2814 @cindex customizing @code{printf}
2815 @cindex defining new @code{printf} conversions
2816 @cindex extending @code{printf}
2818 The GNU C library lets you define your own custom conversion specifiers
2819 for @code{printf} template strings, to teach @code{printf} clever ways
2820 to print the important data structures of your program.
2822 The way you do this is by registering the conversion with the function
2823 @code{register_printf_function}; see @ref{Registering New Conversions}.
2824 One of the arguments you pass to this function is a pointer to a handler
2825 function that produces the actual output; see @ref{Defining the Output
2826 Handler}, for information on how to write this function.
2828 You can also install a function that just returns information about the
2829 number and type of arguments expected by the conversion specifier.
2830 @xref{Parsing a Template String}, for information about this.
2832 The facilities of this section are declared in the header file
2836 * Registering New Conversions:: Using @code{register_printf_function}
2837 to register a new output conversion.
2838 * Conversion Specifier Options:: The handler must be able to get
2839 the options specified in the
2840 template when it is called.
2841 * Defining the Output Handler:: Defining the handler and arginfo
2842 functions that are passed as arguments
2843 to @code{register_printf_function}.
2844 * Printf Extension Example:: How to define a @code{printf}
2846 * Predefined Printf Handlers:: Predefined @code{printf} handlers.
2849 @strong{Portability Note:} The ability to extend the syntax of
2850 @code{printf} template strings is a GNU extension. ISO standard C has
2853 @node Registering New Conversions
2854 @subsection Registering New Conversions
2856 The function to register a new output conversion is
2857 @code{register_printf_function}, declared in @file{printf.h}.
2862 @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function})
2863 This function defines the conversion specifier character @var{spec}.
2864 Thus, if @var{spec} is @code{'Y'}, it defines the conversion @samp{%Y}.
2865 You can redefine the built-in conversions like @samp{%s}, but flag
2866 characters like @samp{#} and type modifiers like @samp{l} can never be
2867 used as conversions; calling @code{register_printf_function} for those
2868 characters has no effect. It is advisable not to use lowercase letters,
2869 since the ISO C standard warns that additional lowercase letters may be
2870 standardized in future editions of the standard.
2872 The @var{handler-function} is the function called by @code{printf} and
2873 friends when this conversion appears in a template string.
2874 @xref{Defining the Output Handler}, for information about how to define
2875 a function to pass as this argument. If you specify a null pointer, any
2876 existing handler function for @var{spec} is removed.
2878 The @var{arginfo-function} is the function called by
2879 @code{parse_printf_format} when this conversion appears in a
2880 template string. @xref{Parsing a Template String}, for information
2883 @c The following is not true anymore. The `parse_printf_format' function
2884 @c is now also called from `vfprintf' via `parse_one_spec'.
2885 @c --drepper@gnu, 1996/11/14
2887 @c Normally, you install both functions for a conversion at the same time,
2888 @c but if you are never going to call @code{parse_printf_format}, you do
2889 @c not need to define an arginfo function.
2891 @strong{Attention:} In the GNU C library versions before 2.0 the
2892 @var{arginfo-function} function did not need to be installed unless
2893 the user used the @code{parse_printf_format} function. This has changed.
2894 Now a call to any of the @code{printf} functions will call this
2895 function when this format specifier appears in the format string.
2897 The return value is @code{0} on success, and @code{-1} on failure
2898 (which occurs if @var{spec} is out of range).
2900 You can redefine the standard output conversions, but this is probably
2901 not a good idea because of the potential for confusion. Library routines
2902 written by other people could break if you do this.
2905 @node Conversion Specifier Options
2906 @subsection Conversion Specifier Options
2908 If you define a meaning for @samp{%A}, what if the template contains
2909 @samp{%+23A} or @samp{%-#A}? To implement a sensible meaning for these,
2910 the handler when called needs to be able to get the options specified in
2913 Both the @var{handler-function} and @var{arginfo-function} accept an
2914 argument that points to a @code{struct printf_info}, which contains
2915 information about the options appearing in an instance of the conversion
2916 specifier. This data type is declared in the header file
2922 @deftp {Type} {struct printf_info}
2923 This structure is used to pass information about the options appearing
2924 in an instance of a conversion specifier in a @code{printf} template
2925 string to the handler and arginfo functions for that specifier. It
2926 contains the following members:
2930 This is the precision specified. The value is @code{-1} if no precision
2931 was specified. If the precision was given as @samp{*}, the
2932 @code{printf_info} structure passed to the handler function contains the
2933 actual value retrieved from the argument list. But the structure passed
2934 to the arginfo function contains a value of @code{INT_MIN}, since the
2935 actual value is not known.
2938 This is the minimum field width specified. The value is @code{0} if no
2939 width was specified. If the field width was given as @samp{*}, the
2940 @code{printf_info} structure passed to the handler function contains the
2941 actual value retrieved from the argument list. But the structure passed
2942 to the arginfo function contains a value of @code{INT_MIN}, since the
2943 actual value is not known.
2946 This is the conversion specifier character specified. It's stored in
2947 the structure so that you can register the same handler function for
2948 multiple characters, but still have a way to tell them apart when the
2949 handler function is called.
2951 @item unsigned int is_long_double
2952 This is a boolean that is true if the @samp{L}, @samp{ll}, or @samp{q}
2953 type modifier was specified. For integer conversions, this indicates
2954 @code{long long int}, as opposed to @code{long double} for floating
2957 @item unsigned int is_char
2958 This is a boolean that is true if the @samp{hh} type modifier was specified.
2960 @item unsigned int is_short
2961 This is a boolean that is true if the @samp{h} type modifier was specified.
2963 @item unsigned int is_long
2964 This is a boolean that is true if the @samp{l} type modifier was specified.
2966 @item unsigned int alt
2967 This is a boolean that is true if the @samp{#} flag was specified.
2969 @item unsigned int space
2970 This is a boolean that is true if the @samp{ } flag was specified.
2972 @item unsigned int left
2973 This is a boolean that is true if the @samp{-} flag was specified.
2975 @item unsigned int showsign
2976 This is a boolean that is true if the @samp{+} flag was specified.
2978 @item unsigned int group
2979 This is a boolean that is true if the @samp{'} flag was specified.
2981 @item unsigned int extra
2982 This flag has a special meaning depending on the context. It could
2983 be used freely by the user-defined handlers but when called from
2984 the @code{printf} function this variable always contains the value
2987 @item unsigned int wide
2988 This flag is set if the stream is wide oriented.
2991 This is the character to use for padding the output to the minimum field
2992 width. The value is @code{'0'} if the @samp{0} flag was specified, and
2993 @code{' '} otherwise.
2998 @node Defining the Output Handler
2999 @subsection Defining the Output Handler
3001 Now let's look at how to define the handler and arginfo functions
3002 which are passed as arguments to @code{register_printf_function}.
3004 @strong{Compatibility Note:} The interface changed in GNU libc
3005 version 2.0. Previously the third argument was of type
3008 You should define your handler functions with a prototype like:
3011 int @var{function} (FILE *stream, const struct printf_info *info,
3012 const void *const *args)
3015 The @var{stream} argument passed to the handler function is the stream to
3016 which it should write output.
3018 The @var{info} argument is a pointer to a structure that contains
3019 information about the various options that were included with the
3020 conversion in the template string. You should not modify this structure
3021 inside your handler function. @xref{Conversion Specifier Options}, for
3022 a description of this data structure.
3024 @c The following changes some time back. --drepper@gnu, 1996/11/14
3026 @c The @code{ap_pointer} argument is used to pass the tail of the variable
3027 @c argument list containing the values to be printed to your handler.
3028 @c Unlike most other functions that can be passed an explicit variable
3029 @c argument list, this is a @emph{pointer} to a @code{va_list}, rather than
3030 @c the @code{va_list} itself. Thus, you should fetch arguments by
3031 @c means of @code{va_arg (*ap_pointer, @var{type})}.
3033 @c (Passing a pointer here allows the function that calls your handler
3034 @c function to update its own @code{va_list} variable to account for the
3035 @c arguments that your handler processes. @xref{Variadic Functions}.)
3037 The @var{args} is a vector of pointers to the arguments data.
3038 The number of arguments was determined by calling the argument
3039 information function provided by the user.
3041 Your handler function should return a value just like @code{printf}
3042 does: it should return the number of characters it has written, or a
3043 negative value to indicate an error.
3047 @deftp {Data Type} printf_function
3048 This is the data type that a handler function should have.
3051 If you are going to use @w{@code{parse_printf_format}} in your
3052 application, you must also define a function to pass as the
3053 @var{arginfo-function} argument for each new conversion you install with
3054 @code{register_printf_function}.
3056 You have to define these functions with a prototype like:
3059 int @var{function} (const struct printf_info *info,
3060 size_t n, int *argtypes)
3063 The return value from the function should be the number of arguments the
3064 conversion expects. The function should also fill in no more than
3065 @var{n} elements of the @var{argtypes} array with information about the
3066 types of each of these arguments. This information is encoded using the
3067 various @samp{PA_} macros. (You will notice that this is the same
3068 calling convention @code{parse_printf_format} itself uses.)
3072 @deftp {Data Type} printf_arginfo_function
3073 This type is used to describe functions that return information about
3074 the number and type of arguments used by a conversion specifier.
3077 @node Printf Extension Example
3078 @subsection @code{printf} Extension Example
3080 Here is an example showing how to define a @code{printf} handler function.
3081 This program defines a data structure called a @code{Widget} and
3082 defines the @samp{%W} conversion to print information about @w{@code{Widget *}}
3083 arguments, including the pointer value and the name stored in the data
3084 structure. The @samp{%W} conversion supports the minimum field width and
3085 left-justification options, but ignores everything else.
3088 @include rprintf.c.texi
3091 The output produced by this program looks like:
3094 |<Widget 0xffeffb7c: mywidget>|
3095 | <Widget 0xffeffb7c: mywidget>|
3096 |<Widget 0xffeffb7c: mywidget> |
3099 @node Predefined Printf Handlers
3100 @subsection Predefined @code{printf} Handlers
3102 The GNU libc also contains a concrete and useful application of the
3103 @code{printf} handler extension. There are two functions available
3104 which implement a special way to print floating-point numbers.
3108 @deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args})
3109 Print a given floating point number as for the format @code{%f} except
3110 that there is a postfix character indicating the divisor for the
3111 number to make this less than 1000. There are two possible divisors:
3112 powers of 1024 or powers of 1000. Which one is used depends on the
3113 format character specified while registered this handler. If the
3114 character is of lower case, 1024 is used. For upper case characters,
3117 The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes,
3118 etc. The full table is:
3121 @multitable @hsep @vsep {' '} {2^10 (1024)} {zetta} {Upper} {10^24 (1000)}
3122 @item low @tab Multiplier @tab From @tab Upper @tab Multiplier
3123 @item ' ' @tab 1 @tab @tab ' ' @tab 1
3124 @item k @tab 2^10 (1024) @tab kilo @tab K @tab 10^3 (1000)
3125 @item m @tab 2^20 @tab mega @tab M @tab 10^6
3126 @item g @tab 2^30 @tab giga @tab G @tab 10^9
3127 @item t @tab 2^40 @tab tera @tab T @tab 10^12
3128 @item p @tab 2^50 @tab peta @tab P @tab 10^15
3129 @item e @tab 2^60 @tab exa @tab E @tab 10^18
3130 @item z @tab 2^70 @tab zetta @tab Z @tab 10^21
3131 @item y @tab 2^80 @tab yotta @tab Y @tab 10^24
3136 \hbox to\hsize{\hfil\vbox{\offinterlineskip
3138 \halign{\strut#& \vrule#\tabskip=1em plus2em& {\tt#}\hfil& \vrule#& #\hfil& \vrule#& #\hfil& \vrule#& {\tt#}\hfil& \vrule#& #\hfil& \vrule#\tabskip=0pt\cr
3140 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
3141 && \omit low && Multiplier && From && \omit Upper && Multiplier &\cr
3142 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
3144 && {\tt\char32} && 1 && && {\tt\char32} && 1 &\cr
3145 && k && $2^{10} = 1024$ && kilo && K && $10^3 = 1000$ &\cr
3146 && m && $2^{20}$ && mega && M && $10^6$ &\cr
3147 && g && $2^{30}$ && giga && G && $10^9$ &\cr
3148 && t && $2^{40}$ && tera && T && $10^{12}$ &\cr
3149 && p && $2^{50}$ && peta && P && $10^{15}$ &\cr
3150 && e && $2^{60}$ && exa && E && $10^{18}$ &\cr
3151 && z && $2^{70}$ && zetta && Z && $10^{21}$ &\cr
3152 && y && $2^{80}$ && yotta && Y && $10^{24}$ &\cr
3153 \noalign{\hrule}}}\hfil}
3157 The default precision is 3, i.e., 1024 is printed with a lower-case
3158 format character as if it were @code{%.3fk} and will yield @code{1.000k}.
3161 Due to the requirements of @code{register_printf_function} we must also
3162 provide the function which returns information about the arguments.
3166 @deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes})
3167 This function will return in @var{argtypes} the information about the
3168 used parameters in the way the @code{vfprintf} implementation expects
3169 it. The format always takes one argument.
3172 To use these functions both functions must be registered with a call like
3175 register_printf_function ('B', printf_size, printf_size_info);
3178 Here we register the functions to print numbers as powers of 1000 since
3179 the format character @code{'B'} is an upper-case character. If we
3180 would additionally use @code{'b'} in a line like
3183 register_printf_function ('b', printf_size, printf_size_info);
3187 we could also print using a power of 1024. Please note that all that is
3188 different in these two lines is the format specifier. The
3189 @code{printf_size} function knows about the difference between lower and upper
3190 case format specifiers.
3192 The use of @code{'B'} and @code{'b'} is no coincidence. Rather it is
3193 the preferred way to use this functionality since it is available on
3194 some other systems which also use format specifiers.
3196 @node Formatted Input
3197 @section Formatted Input
3199 @cindex formatted input from a stream
3200 @cindex reading from a stream, formatted
3201 @cindex format string, for @code{scanf}
3202 @cindex template, for @code{scanf}
3203 The functions described in this section (@code{scanf} and related
3204 functions) provide facilities for formatted input analogous to the
3205 formatted output facilities. These functions provide a mechanism for
3206 reading arbitrary values under the control of a @dfn{format string} or
3207 @dfn{template string}.
3210 * Formatted Input Basics:: Some basics to get you started.
3211 * Input Conversion Syntax:: Syntax of conversion specifications.
3212 * Table of Input Conversions:: Summary of input conversions and what they do.
3213 * Numeric Input Conversions:: Details of conversions for reading numbers.
3214 * String Input Conversions:: Details of conversions for reading strings.
3215 * Dynamic String Input:: String conversions that @code{malloc} the buffer.
3216 * Other Input Conversions:: Details of miscellaneous other conversions.
3217 * Formatted Input Functions:: Descriptions of the actual functions.
3218 * Variable Arguments Input:: @code{vscanf} and friends.
3221 @node Formatted Input Basics
3222 @subsection Formatted Input Basics
3224 Calls to @code{scanf} are superficially similar to calls to
3225 @code{printf} in that arbitrary arguments are read under the control of
3226 a template string. While the syntax of the conversion specifications in
3227 the template is very similar to that for @code{printf}, the
3228 interpretation of the template is oriented more towards free-format
3229 input and simple pattern matching, rather than fixed-field formatting.
3230 For example, most @code{scanf} conversions skip over any amount of
3231 ``white space'' (including spaces, tabs, and newlines) in the input
3232 file, and there is no concept of precision for the numeric input
3233 conversions as there is for the corresponding output conversions.
3234 Ordinarily, non-whitespace characters in the template are expected to
3235 match characters in the input stream exactly, but a matching failure is
3236 distinct from an input error on the stream.
3237 @cindex conversion specifications (@code{scanf})
3239 Another area of difference between @code{scanf} and @code{printf} is
3240 that you must remember to supply pointers rather than immediate values
3241 as the optional arguments to @code{scanf}; the values that are read are
3242 stored in the objects that the pointers point to. Even experienced
3243 programmers tend to forget this occasionally, so if your program is
3244 getting strange errors that seem to be related to @code{scanf}, you
3245 might want to double-check this.
3247 When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
3248 leaving the first non-matching character as the next character to be
3249 read from the stream. The normal return value from @code{scanf} is the
3250 number of values that were assigned, so you can use this to determine if
3251 a matching error happened before all the expected values were read.
3252 @cindex matching failure, in @code{scanf}
3254 The @code{scanf} function is typically used for things like reading in
3255 the contents of tables. For example, here is a function that uses
3256 @code{scanf} to initialize an array of @code{double}:
3260 readarray (double *array, int n)
3264 if (scanf (" %lf", &(array[i])) != 1)
3265 invalid_input_error ();
3269 The formatted input functions are not used as frequently as the
3270 formatted output functions. Partly, this is because it takes some care
3271 to use them properly. Another reason is that it is difficult to recover
3272 from a matching error.
3274 If you are trying to read input that doesn't match a single, fixed
3275 pattern, you may be better off using a tool such as Flex to generate a
3276 lexical scanner, or Bison to generate a parser, rather than using
3277 @code{scanf}. For more information about these tools, see @ref{Top, , ,
3278 flex.info, Flex: The Lexical Scanner Generator}, and @ref{Top, , ,
3279 bison.info, The Bison Reference Manual}.
3281 @node Input Conversion Syntax
3282 @subsection Input Conversion Syntax
3284 A @code{scanf} template string is a string that contains ordinary
3285 multibyte characters interspersed with conversion specifications that
3286 start with @samp{%}.
3288 Any whitespace character (as defined by the @code{isspace} function;
3289 @pxref{Classification of Characters}) in the template causes any number
3290 of whitespace characters in the input stream to be read and discarded.
3291 The whitespace characters that are matched need not be exactly the same
3292 whitespace characters that appear in the template string. For example,
3293 write @samp{ , } in the template to recognize a comma with optional
3294 whitespace before and after.
3296 Other characters in the template string that are not part of conversion
3297 specifications must match characters in the input stream exactly; if
3298 this is not the case, a matching failure occurs.
3300 The conversion specifications in a @code{scanf} template string
3301 have the general form:
3304 % @var{flags} @var{width} @var{type} @var{conversion}
3307 In more detail, an input conversion specification consists of an initial
3308 @samp{%} character followed in sequence by:
3312 An optional @dfn{flag character} @samp{*}, which says to ignore the text
3313 read for this specification. When @code{scanf} finds a conversion
3314 specification that uses this flag, it reads input as directed by the
3315 rest of the conversion specification, but it discards this input, does
3316 not use a pointer argument, and does not increment the count of
3317 successful assignments.
3318 @cindex flag character (@code{scanf})
3321 An optional flag character @samp{a} (valid with string conversions only)
3322 which requests allocation of a buffer long enough to store the string in.
3323 (This is a GNU extension.)
3324 @xref{Dynamic String Input}.
3327 An optional decimal integer that specifies the @dfn{maximum field
3328 width}. Reading of characters from the input stream stops either when
3329 this maximum is reached or when a non-matching character is found,
3330 whichever happens first. Most conversions discard initial whitespace
3331 characters (those that don't are explicitly documented), and these
3332 discarded characters don't count towards the maximum field width.
3333 String input conversions store a null character to mark the end of the
3334 input; the maximum field width does not include this terminator.
3335 @cindex maximum field width (@code{scanf})
3338 An optional @dfn{type modifier character}. For example, you can
3339 specify a type modifier of @samp{l} with integer conversions such as
3340 @samp{%d} to specify that the argument is a pointer to a @code{long int}
3341 rather than a pointer to an @code{int}.
3342 @cindex type modifier character (@code{scanf})
3345 A character that specifies the conversion to be applied.
3348 The exact options that are permitted and how they are interpreted vary
3349 between the different conversion specifiers. See the descriptions of the
3350 individual conversions for information about the particular options that
3353 With the @samp{-Wformat} option, the GNU C compiler checks calls to
3354 @code{scanf} and related functions. It examines the format string and
3355 verifies that the correct number and types of arguments are supplied.
3356 There is also a GNU C syntax to tell the compiler that a function you
3357 write uses a @code{scanf}-style format string.
3358 @xref{Function Attributes, , Declaring Attributes of Functions,
3359 gcc.info, Using GNU CC}, for more information.
3361 @node Table of Input Conversions
3362 @subsection Table of Input Conversions
3363 @cindex input conversions, for @code{scanf}
3365 Here is a table that summarizes the various conversion specifications:
3369 Matches an optionally signed integer written in decimal. @xref{Numeric
3373 Matches an optionally signed integer in any of the formats that the C
3374 language defines for specifying an integer constant. @xref{Numeric
3378 Matches an unsigned integer written in octal radix.
3379 @xref{Numeric Input Conversions}.
3382 Matches an unsigned integer written in decimal radix.
3383 @xref{Numeric Input Conversions}.
3385 @item @samp{%x}, @samp{%X}
3386 Matches an unsigned integer written in hexadecimal radix.
3387 @xref{Numeric Input Conversions}.
3389 @item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
3390 Matches an optionally signed floating-point number. @xref{Numeric Input
3395 Matches a string containing only non-whitespace characters.
3396 @xref{String Input Conversions}. The presence of the @samp{l} modifier
3397 determines whether the output is stored as a wide character string or a
3398 multibyte string. If @samp{%s} is used in a wide character function the
3399 string is converted as with multiple calls to @code{wcrtomb} into a
3400 multibyte string. This means that the buffer must provide room for
3401 @code{MB_CUR_MAX} bytes for each wide character read. In case
3402 @samp{%ls} is used in a multibyte function the result is converted into
3403 wide characters as with multiple calls of @code{mbrtowc} before being
3404 stored in the user provided buffer.
3407 This is an alias for @samp{%ls} which is supported for compatibility
3408 with the Unix standard.
3411 Matches a string of characters that belong to a specified set.
3412 @xref{String Input Conversions}. The presence of the @samp{l} modifier
3413 determines whether the output is stored as a wide character string or a
3414 multibyte string. If @samp{%[} is used in a wide character function the
3415 string is converted as with multiple calls to @code{wcrtomb} into a
3416 multibyte string. This means that the buffer must provide room for
3417 @code{MB_CUR_MAX} bytes for each wide character read. In case
3418 @samp{%l[} is used in a multibyte function the result is converted into
3419 wide characters as with multiple calls of @code{mbrtowc} before being
3420 stored in the user provided buffer.
3423 Matches a string of one or more characters; the number of characters
3424 read is controlled by the maximum field width given for the conversion.
3425 @xref{String Input Conversions}.
3427 If the @samp{%c} is used in a wide stream function the read value is
3428 converted from a wide character to the corresponding multibyte character
3429 before storing it. Note that this conversion can produce more than one
3430 byte of output and therefore the provided buffer be large enough for up
3431 to @code{MB_CUR_MAX} bytes for each character. If @samp{%lc} is used in
3432 a multibyte function the input is treated as a multibyte sequence (and
3433 not bytes) and the result is converted as with calls to @code{mbrtowc}.
3436 This is an alias for @samp{%lc} which is supported for compatibility
3437 with the Unix standard.
3440 Matches a pointer value in the same implementation-defined format used
3441 by the @samp{%p} output conversion for @code{printf}. @xref{Other Input
3445 This conversion doesn't read any characters; it records the number of
3446 characters read so far by this call. @xref{Other Input Conversions}.
3449 This matches a literal @samp{%} character in the input stream. No
3450 corresponding argument is used. @xref{Other Input Conversions}.
3453 If the syntax of a conversion specification is invalid, the behavior is
3454 undefined. If there aren't enough function arguments provided to supply
3455 addresses for all the conversion specifications in the template strings
3456 that perform assignments, or if the arguments are not of the correct
3457 types, the behavior is also undefined. On the other hand, extra
3458 arguments are simply ignored.
3460 @node Numeric Input Conversions
3461 @subsection Numeric Input Conversions
3463 This section describes the @code{scanf} conversions for reading numeric
3466 The @samp{%d} conversion matches an optionally signed integer in decimal
3467 radix. The syntax that is recognized is the same as that for the
3468 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3469 @code{10} for the @var{base} argument.
3471 The @samp{%i} conversion matches an optionally signed integer in any of
3472 the formats that the C language defines for specifying an integer
3473 constant. The syntax that is recognized is the same as that for the
3474 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3475 @code{0} for the @var{base} argument. (You can print integers in this
3476 syntax with @code{printf} by using the @samp{#} flag character with the
3477 @samp{%x}, @samp{%o}, or @samp{%d} conversion. @xref{Integer Conversions}.)
3479 For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
3480 could be read in as integers under the @samp{%i} conversion. Each of
3481 these specifies a number with decimal value @code{10}.
3483 The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned
3484 integers in octal, decimal, and hexadecimal radices, respectively. The
3485 syntax that is recognized is the same as that for the @code{strtoul}
3486 function (@pxref{Parsing of Integers}) with the appropriate value
3487 (@code{8}, @code{10}, or @code{16}) for the @var{base} argument.
3489 The @samp{%X} conversion is identical to the @samp{%x} conversion. They
3490 both permit either uppercase or lowercase letters to be used as digits.
3492 The default type of the corresponding argument for the @code{%d} and
3493 @code{%i} conversions is @code{int *}, and @code{unsigned int *} for the
3494 other integer conversions. You can use the following type modifiers to
3495 specify other sizes of integer:
3499 Specifies that the argument is a @code{signed char *} or @code{unsigned
3502 This modifier was introduced in @w{ISO C99}.
3505 Specifies that the argument is a @code{short int *} or @code{unsigned
3509 Specifies that the argument is a @code{intmax_t *} or @code{uintmax_t *}.
3511 This modifier was introduced in @w{ISO C99}.
3514 Specifies that the argument is a @code{long int *} or @code{unsigned
3515 long int *}. Two @samp{l} characters is like the @samp{L} modifier, below.
3517 If used with @samp{%c} or @samp{%s} the corresponding parameter is
3518 considered as a pointer to a wide character or wide character string
3519 respectively. This use of @samp{l} was introduced in @w{Amendment 1} to
3526 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
3527 GNU C compiler. For systems that don't provide extra-long integers, this
3528 is the same as @code{long int}.)
3530 The @samp{q} modifier is another name for the same thing, which comes
3531 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
3535 Specifies that the argument is a @code{ptrdiff_t *}.
3537 This modifier was introduced in @w{ISO C99}.
3540 Specifies that the argument is a @code{size_t *}.
3542 This modifier was introduced in @w{ISO C99}.
3545 All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
3546 input conversions are interchangeable. They all match an optionally
3547 signed floating point number, in the same syntax as for the
3548 @code{strtod} function (@pxref{Parsing of Floats}).
3550 For the floating-point input conversions, the default argument type is
3551 @code{float *}. (This is different from the corresponding output
3552 conversions, where the default type is @code{double}; remember that
3553 @code{float} arguments to @code{printf} are converted to @code{double}
3554 by the default argument promotions, but @code{float *} arguments are
3555 not promoted to @code{double *}.) You can specify other sizes of float
3556 using these type modifiers:
3560 Specifies that the argument is of type @code{double *}.
3563 Specifies that the argument is of type @code{long double *}.
3566 For all the above number parsing formats there is an additional optional
3567 flag @samp{'}. When this flag is given the @code{scanf} function
3568 expects the number represented in the input string to be formatted
3569 according to the grouping rules of the currently selected locale
3570 (@pxref{General Numeric}).
3572 If the @code{"C"} or @code{"POSIX"} locale is selected there is no
3573 difference. But for a locale which specifies values for the appropriate
3574 fields in the locale the input must have the correct form in the input.
3575 Otherwise the longest prefix with a correct form is processed.
3577 @node String Input Conversions
3578 @subsection String Input Conversions
3580 This section describes the @code{scanf} input conversions for reading
3581 string and character values: @samp{%s}, @samp{%S}, @samp{%[}, @samp{%c},
3584 You have two options for how to receive the input from these
3589 Provide a buffer to store it in. This is the default. You should
3590 provide an argument of type @code{char *} or @code{wchar_t *} (the
3591 latter of the @samp{l} modifier is present).
3593 @strong{Warning:} To make a robust program, you must make sure that the
3594 input (plus its terminating null) cannot possibly exceed the size of the
3595 buffer you provide. In general, the only way to do this is to specify a
3596 maximum field width one less than the buffer size. @strong{If you
3597 provide the buffer, always specify a maximum field width to prevent
3601 Ask @code{scanf} to allocate a big enough buffer, by specifying the
3602 @samp{a} flag character. This is a GNU extension. You should provide
3603 an argument of type @code{char **} for the buffer address to be stored
3604 in. @xref{Dynamic String Input}.
3607 The @samp{%c} conversion is the simplest: it matches a fixed number of
3608 characters, always. The maximum field width says how many characters to
3609 read; if you don't specify the maximum, the default is 1. This
3610 conversion doesn't append a null character to the end of the text it
3611 reads. It also does not skip over initial whitespace characters. It
3612 reads precisely the next @var{n} characters, and fails if it cannot get
3613 that many. Since there is always a maximum field width with @samp{%c}
3614 (whether specified, or 1 by default), you can always prevent overflow by
3615 making the buffer long enough.
3616 @comment Is character == byte here??? --drepper
3618 If the format is @samp{%lc} or @samp{%C} the function stores wide
3619 characters which are converted using the conversion determined at the
3620 time the stream was opened from the external byte stream. The number of
3621 bytes read from the medium is limited by @code{MB_CUR_LEN * @var{n}} but
3622 at most @var{n} wide character get stored in the output string.
3624 The @samp{%s} conversion matches a string of non-whitespace characters.
3625 It skips and discards initial whitespace, but stops when it encounters
3626 more whitespace after having read something. It stores a null character
3627 at the end of the text that it reads.
3629 For example, reading the input:
3636 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
3637 reading the same input with the conversion @samp{%10s} produces
3640 @strong{Warning:} If you do not specify a field width for @samp{%s},
3641 then the number of characters read is limited only by where the next
3642 whitespace character appears. This almost certainly means that invalid
3643 input can make your program crash---which is a bug.
3645 The @samp{%ls} and @samp{%S} format are handled just like @samp{%s}
3646 except that the external byte sequence is converted using the conversion
3647 associated with the stream to wide characters with their own encoding.
3648 A width or precision specified with the format do not directly determine
3649 how many bytes are read from the stream since they measure wide
3650 characters. But an upper limit can be computed by multiplying the value
3651 of the width or precision by @code{MB_CUR_MAX}.
3653 To read in characters that belong to an arbitrary set of your choice,
3654 use the @samp{%[} conversion. You specify the set between the @samp{[}
3655 character and a following @samp{]} character, using the same syntax used
3656 in regular expressions. As special cases:
3660 A literal @samp{]} character can be specified as the first character
3664 An embedded @samp{-} character (that is, one that is not the first or
3665 last character of the set) is used to specify a range of characters.
3668 If a caret character @samp{^} immediately follows the initial @samp{[},
3669 then the set of allowed input characters is the everything @emph{except}
3670 the characters listed.
3673 The @samp{%[} conversion does not skip over initial whitespace
3676 Here are some examples of @samp{%[} conversions and what they mean:
3679 @item %25[1234567890]
3680 Matches a string of up to 25 digits.
3683 Matches a string of up to 25 square brackets.
3685 @item %25[^ \f\n\r\t\v]
3686 Matches a string up to 25 characters long that doesn't contain any of
3687 the standard whitespace characters. This is slightly different from
3688 @samp{%s}, because if the input begins with a whitespace character,
3689 @samp{%[} reports a matching failure while @samp{%s} simply discards the
3693 Matches up to 25 lowercase characters.
3696 As for @samp{%c} and @samp{%s} the @samp{%[} format is also modified to
3697 produce wide characters if the @samp{l} modifier is present. All what
3698 is said about @samp{%ls} above is true for @samp{%l[}.
3700 One more reminder: the @samp{%s} and @samp{%[} conversions are
3701 @strong{dangerous} if you don't specify a maximum width or use the
3702 @samp{a} flag, because input too long would overflow whatever buffer you
3703 have provided for it. No matter how long your buffer is, a user could
3704 supply input that is longer. A well-written program reports invalid
3705 input with a comprehensible error message, not with a crash.
3707 @node Dynamic String Input
3708 @subsection Dynamically Allocating String Conversions
3710 A GNU extension to formatted input lets you safely read a string with no
3711 maximum size. Using this feature, you don't supply a buffer; instead,
3712 @code{scanf} allocates a buffer big enough to hold the data and gives
3713 you its address. To use this feature, write @samp{a} as a flag
3714 character, as in @samp{%as} or @samp{%a[0-9a-z]}.
3716 The pointer argument you supply for where to store the input should have
3717 type @code{char **}. The @code{scanf} function allocates a buffer and
3718 stores its address in the word that the argument points to. You should
3719 free the buffer with @code{free} when you no longer need it.
3721 Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]}
3722 conversion specification to read a ``variable assignment'' of the form
3723 @samp{@var{variable} = @var{value}}.
3727 char *variable, *value;
3729 if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
3732 invalid_input_error ();
3740 @node Other Input Conversions
3741 @subsection Other Input Conversions
3743 This section describes the miscellaneous input conversions.
3745 The @samp{%p} conversion is used to read a pointer value. It recognizes
3746 the same syntax used by the @samp{%p} output conversion for
3747 @code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
3748 number just as the @samp{%x} conversion accepts. The corresponding
3749 argument should be of type @code{void **}; that is, the address of a
3750 place to store a pointer.
3752 The resulting pointer value is not guaranteed to be valid if it was not
3753 originally written during the same program execution that reads it in.
3755 The @samp{%n} conversion produces the number of characters read so far
3756 by this call. The corresponding argument should be of type @code{int *}.
3757 This conversion works in the same way as the @samp{%n} conversion for
3758 @code{printf}; see @ref{Other Output Conversions}, for an example.
3760 The @samp{%n} conversion is the only mechanism for determining the
3761 success of literal matches or conversions with suppressed assignments.
3762 If the @samp{%n} follows the locus of a matching failure, then no value
3763 is stored for it since @code{scanf} returns before processing the
3764 @samp{%n}. If you store @code{-1} in that argument slot before calling
3765 @code{scanf}, the presence of @code{-1} after @code{scanf} indicates an
3766 error occurred before the @samp{%n} was reached.
3768 Finally, the @samp{%%} conversion matches a literal @samp{%} character
3769 in the input stream, without using an argument. This conversion does
3770 not permit any flags, field width, or type modifier to be specified.
3772 @node Formatted Input Functions
3773 @subsection Formatted Input Functions
3775 Here are the descriptions of the functions for performing formatted
3777 Prototypes for these functions are in the header file @file{stdio.h}.
3782 @deftypefun int scanf (const char *@var{template}, @dots{})
3783 The @code{scanf} function reads formatted input from the stream
3784 @code{stdin} under the control of the template string @var{template}.
3785 The optional arguments are pointers to the places which receive the
3788 The return value is normally the number of successful assignments. If
3789 an end-of-file condition is detected before any matches are performed,
3790 including matches against whitespace and literal characters in the
3791 template, then @code{EOF} is returned.
3796 @deftypefun int wscanf (const wchar_t *@var{template}, @dots{})
3797 The @code{wscanf} function reads formatted input from the stream
3798 @code{stdin} under the control of the template string @var{template}.
3799 The optional arguments are pointers to the places which receive the
3802 The return value is normally the number of successful assignments. If
3803 an end-of-file condition is detected before any matches are performed,
3804 including matches against whitespace and literal characters in the
3805 template, then @code{WEOF} is returned.
3810 @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
3811 This function is just like @code{scanf}, except that the input is read
3812 from the stream @var{stream} instead of @code{stdin}.
3817 @deftypefun int fwscanf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
3818 This function is just like @code{wscanf}, except that the input is read
3819 from the stream @var{stream} instead of @code{stdin}.
3824 @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
3825 This is like @code{scanf}, except that the characters are taken from the
3826 null-terminated string @var{s} instead of from a stream. Reaching the
3827 end of the string is treated as an end-of-file condition.
3829 The behavior of this function is undefined if copying takes place
3830 between objects that overlap---for example, if @var{s} is also given
3831 as an argument to receive a string read under control of the @samp{%s},
3832 @samp{%S}, or @samp{%[} conversion.
3837 @deftypefun int swscanf (const wchar_t *@var{ws}, const char *@var{template}, @dots{})
3838 This is like @code{wscanf}, except that the characters are taken from the
3839 null-terminated string @var{ws} instead of from a stream. Reaching the
3840 end of the string is treated as an end-of-file condition.
3842 The behavior of this function is undefined if copying takes place
3843 between objects that overlap---for example, if @var{ws} is also given as
3844 an argument to receive a string read under control of the @samp{%s},
3845 @samp{%S}, or @samp{%[} conversion.
3848 @node Variable Arguments Input
3849 @subsection Variable Arguments Input Functions
3851 The functions @code{vscanf} and friends are provided so that you can
3852 define your own variadic @code{scanf}-like functions that make use of
3853 the same internals as the built-in formatted output functions.
3854 These functions are analogous to the @code{vprintf} series of output
3855 functions. @xref{Variable Arguments Output}, for important
3856 information on how to use them.
3858 @strong{Portability Note:} The functions listed in this section were
3859 introduced in @w{ISO C99} and were before available as GNU extensions.
3863 @deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
3864 This function is similar to @code{scanf}, but instead of taking
3865 a variable number of arguments directly, it takes an argument list
3866 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
3871 @deftypefun int vwscanf (const wchar_t *@var{template}, va_list @var{ap})
3872 This function is similar to @code{wscanf}, but instead of taking
3873 a variable number of arguments directly, it takes an argument list
3874 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
3879 @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
3880 This is the equivalent of @code{fscanf} with the variable argument list
3881 specified directly as for @code{vscanf}.
3886 @deftypefun int vfwscanf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
3887 This is the equivalent of @code{fwscanf} with the variable argument list
3888 specified directly as for @code{vwscanf}.
3893 @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
3894 This is the equivalent of @code{sscanf} with the variable argument list
3895 specified directly as for @code{vscanf}.
3900 @deftypefun int vswscanf (const wchar_t *@var{s}, const wchar_t *@var{template}, va_list @var{ap})
3901 This is the equivalent of @code{swscanf} with the variable argument list
3902 specified directly as for @code{vwscanf}.
3905 In GNU C, there is a special construct you can use to let the compiler
3906 know that a function uses a @code{scanf}-style format string. Then it
3907 can check the number and types of arguments in each call to the
3908 function, and warn you when they do not match the format string.
3909 For details, @xref{Function Attributes, , Declaring Attributes of Functions,
3910 gcc.info, Using GNU CC}.
3912 @node EOF and Errors
3913 @section End-Of-File and Errors
3915 @cindex end of file, on a stream
3916 Many of the functions described in this chapter return the value of the
3917 macro @code{EOF} to indicate unsuccessful completion of the operation.
3918 Since @code{EOF} is used to report both end of file and random errors,
3919 it's often better to use the @code{feof} function to check explicitly
3920 for end of file and @code{ferror} to check for errors. These functions
3921 check indicators that are part of the internal state of the stream
3922 object, indicators set if the appropriate condition was detected by a
3923 previous I/O operation on that stream.
3927 @deftypevr Macro int EOF
3928 This macro is an integer value that is returned by a number of narrow
3929 stream functions to indicate an end-of-file condition, or some other
3930 error situation. With the GNU library, @code{EOF} is @code{-1}. In
3931 other libraries, its value may be some other negative number.
3933 This symbol is declared in @file{stdio.h}.
3938 @deftypevr Macro int WEOF
3939 This macro is an integer value that is returned by a number of wide
3940 stream functions to indicate an end-of-file condition, or some other
3941 error situation. With the GNU library, @code{WEOF} is @code{-1}. In
3942 other libraries, its value may be some other negative number.
3944 This symbol is declared in @file{wchar.h}.
3949 @deftypefun int feof (FILE *@var{stream})
3950 The @code{feof} function returns nonzero if and only if the end-of-file
3951 indicator for the stream @var{stream} is set.
3953 This symbol is declared in @file{stdio.h}.
3958 @deftypefun int feof_unlocked (FILE *@var{stream})
3959 The @code{feof_unlocked} function is equivalent to the @code{feof}
3960 function except that it does not implicitly lock the stream.
3962 This function is a GNU extension.
3964 This symbol is declared in @file{stdio.h}.
3969 @deftypefun int ferror (FILE *@var{stream})
3970 The @code{ferror} function returns nonzero if and only if the error
3971 indicator for the stream @var{stream} is set, indicating that an error
3972 has occurred on a previous operation on the stream.
3974 This symbol is declared in @file{stdio.h}.
3979 @deftypefun int ferror_unlocked (FILE *@var{stream})
3980 The @code{ferror_unlocked} function is equivalent to the @code{ferror}
3981 function except that it does not implicitly lock the stream.
3983 This function is a GNU extension.
3985 This symbol is declared in @file{stdio.h}.
3988 In addition to setting the error indicator associated with the stream,
3989 the functions that operate on streams also set @code{errno} in the same
3990 way as the corresponding low-level functions that operate on file
3991 descriptors. For example, all of the functions that perform output to a
3992 stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are
3993 implemented in terms of @code{write}, and all of the @code{errno} error
3994 conditions defined for @code{write} are meaningful for these functions.
3995 For more information about the descriptor-level I/O functions, see
3996 @ref{Low-Level I/O}.
3998 @node Error Recovery
3999 @section Recovering from errors
4001 You may explicitly clear the error and EOF flags with the @code{clearerr}
4006 @deftypefun void clearerr (FILE *@var{stream})
4007 This function clears the end-of-file and error indicators for the
4008 stream @var{stream}.
4010 The file positioning functions (@pxref{File Positioning}) also clear the
4011 end-of-file indicator for the stream.
4016 @deftypefun void clearerr_unlocked (FILE *@var{stream})
4017 The @code{clearerr_unlocked} function is equivalent to the @code{clearerr}
4018 function except that it does not implicitly lock the stream.
4020 This function is a GNU extension.
4023 Note that it is @emph{not} correct to just clear the error flag and retry
4024 a failed stream operation. After a failed write, any number of
4025 characters since the last buffer flush may have been committed to the
4026 file, while some buffered data may have been discarded. Merely retrying
4027 can thus cause lost or repeated data.
4029 A failed read may leave the file pointer in an inappropriate position for
4030 a second try. In both cases, you should seek to a known position before
4033 Most errors that can happen are not recoverable --- a second try will
4034 always fail again in the same way. So usually it is best to give up and
4035 report the error to the user, rather than install complicated recovery
4038 One important exception is @code{EINTR} (@pxref{Interrupted Primitives}).
4039 Many stream I/O implementations will treat it as an ordinary error, which
4040 can be quite inconvenient. You can avoid this hassle by installing all
4041 signals with the @code{SA_RESTART} flag.
4043 For similar reasons, setting nonblocking I/O on a stream's file
4044 descriptor is not usually advisable.
4046 @node Binary Streams
4047 @section Text and Binary Streams
4049 The GNU system and other POSIX-compatible operating systems organize all
4050 files as uniform sequences of characters. However, some other systems
4051 make a distinction between files containing text and files containing
4052 binary data, and the input and output facilities of @w{ISO C} provide for
4053 this distinction. This section tells you how to write programs portable
4057 @cindex binary stream
4058 When you open a stream, you can specify either a @dfn{text stream} or a
4059 @dfn{binary stream}. You indicate that you want a binary stream by
4060 specifying the @samp{b} modifier in the @var{opentype} argument to
4061 @code{fopen}; see @ref{Opening Streams}. Without this
4062 option, @code{fopen} opens the file as a text stream.
4064 Text and binary streams differ in several ways:
4068 The data read from a text stream is divided into @dfn{lines} which are
4069 terminated by newline (@code{'\n'}) characters, while a binary stream is
4070 simply a long series of characters. A text stream might on some systems
4071 fail to handle lines more than 254 characters long (including the
4072 terminating newline character).
4073 @cindex lines (in a text file)
4076 On some systems, text files can contain only printing characters,
4077 horizontal tab characters, and newlines, and so text streams may not
4078 support other characters. However, binary streams can handle any
4082 Space characters that are written immediately preceding a newline
4083 character in a text stream may disappear when the file is read in again.
4086 More generally, there need not be a one-to-one mapping between
4087 characters that are read from or written to a text stream, and the
4088 characters in the actual file.
4091 Since a binary stream is always more capable and more predictable than a
4092 text stream, you might wonder what purpose text streams serve. Why not
4093 simply always use binary streams? The answer is that on these operating
4094 systems, text and binary streams use different file formats, and the
4095 only way to read or write ``an ordinary file of text'' that can work
4096 with other text-oriented programs is through a text stream.
4098 In the GNU library, and on all POSIX systems, there is no difference
4099 between text streams and binary streams. When you open a stream, you
4100 get the same kind of stream regardless of whether you ask for binary.
4101 This stream can handle any file content, and has none of the
4102 restrictions that text streams sometimes have.
4104 @node File Positioning
4105 @section File Positioning
4106 @cindex file positioning on a stream
4107 @cindex positioning a stream
4108 @cindex seeking on a stream
4110 The @dfn{file position} of a stream describes where in the file the
4111 stream is currently reading or writing. I/O on the stream advances the
4112 file position through the file. In the GNU system, the file position is
4113 represented as an integer, which counts the number of bytes from the
4114 beginning of the file. @xref{File Position}.
4116 During I/O to an ordinary disk file, you can change the file position
4117 whenever you wish, so as to read or write any portion of the file. Some
4118 other kinds of files may also permit this. Files which support changing
4119 the file position are sometimes referred to as @dfn{random-access}
4122 You can use the functions in this section to examine or modify the file
4123 position indicator associated with a stream. The symbols listed below
4124 are declared in the header file @file{stdio.h}.
4129 @deftypefun {long int} ftell (FILE *@var{stream})
4130 This function returns the current file position of the stream
4133 This function can fail if the stream doesn't support file positioning,
4134 or if the file position can't be represented in a @code{long int}, and
4135 possibly for other reasons as well. If a failure occurs, a value of
4136 @code{-1} is returned.
4141 @deftypefun off_t ftello (FILE *@var{stream})
4142 The @code{ftello} function is similar to @code{ftell}, except that it
4143 returns a value of type @code{off_t}. Systems which support this type
4144 use it to describe all file positions, unlike the POSIX specification
4145 which uses a long int. The two are not necessarily the same size.
4146 Therefore, using ftell can lead to problems if the implementation is
4147 written on top of a POSIX compliant low-level I/O implementation, and using
4148 @code{ftello} is preferable whenever it is available.
4150 If this function fails it returns @code{(off_t) -1}. This can happen due
4151 to missing support for file positioning or internal errors. Otherwise
4152 the return value is the current file position.
4154 The function is an extension defined in the Unix Single Specification
4157 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4158 32 bit system this function is in fact @code{ftello64}. I.e., the
4159 LFS interface transparently replaces the old interface.
4164 @deftypefun off64_t ftello64 (FILE *@var{stream})
4165 This function is similar to @code{ftello} with the only difference that
4166 the return value is of type @code{off64_t}. This also requires that the
4167 stream @var{stream} was opened using either @code{fopen64},
4168 @code{freopen64}, or @code{tmpfile64} since otherwise the underlying
4169 file operations to position the file pointer beyond the @math{2^31}
4170 bytes limit might fail.
4172 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4173 bits machine this function is available under the name @code{ftello}
4174 and so transparently replaces the old interface.
4179 @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
4180 The @code{fseek} function is used to change the file position of the
4181 stream @var{stream}. The value of @var{whence} must be one of the
4182 constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
4183 indicate whether the @var{offset} is relative to the beginning of the
4184 file, the current file position, or the end of the file, respectively.
4186 This function returns a value of zero if the operation was successful,
4187 and a nonzero value to indicate failure. A successful call also clears
4188 the end-of-file indicator of @var{stream} and discards any characters
4189 that were ``pushed back'' by the use of @code{ungetc}.
4191 @code{fseek} either flushes any buffered output before setting the file
4192 position or else remembers it so it will be written later in its proper
4198 @deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence})
4199 This function is similar to @code{fseek} but it corrects a problem with
4200 @code{fseek} in a system with POSIX types. Using a value of type
4201 @code{long int} for the offset is not compatible with POSIX.
4202 @code{fseeko} uses the correct type @code{off_t} for the @var{offset}
4205 For this reason it is a good idea to prefer @code{ftello} whenever it is
4206 available since its functionality is (if different at all) closer the
4207 underlying definition.
4209 The functionality and return value is the same as for @code{fseek}.
4211 The function is an extension defined in the Unix Single Specification
4214 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4215 32 bit system this function is in fact @code{fseeko64}. I.e., the
4216 LFS interface transparently replaces the old interface.
4221 @deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence})
4222 This function is similar to @code{fseeko} with the only difference that
4223 the @var{offset} parameter is of type @code{off64_t}. This also
4224 requires that the stream @var{stream} was opened using either
4225 @code{fopen64}, @code{freopen64}, or @code{tmpfile64} since otherwise
4226 the underlying file operations to position the file pointer beyond the
4227 @math{2^31} bytes limit might fail.
4229 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4230 bits machine this function is available under the name @code{fseeko}
4231 and so transparently replaces the old interface.
4234 @strong{Portability Note:} In non-POSIX systems, @code{ftell},
4235 @code{ftello}, @code{fseek} and @code{fseeko} might work reliably only
4236 on binary streams. @xref{Binary Streams}.
4238 The following symbolic constants are defined for use as the @var{whence}
4239 argument to @code{fseek}. They are also used with the @code{lseek}
4240 function (@pxref{I/O Primitives}) and to specify offsets for file locks
4241 (@pxref{Control Operations}).
4245 @deftypevr Macro int SEEK_SET
4246 This is an integer constant which, when used as the @var{whence}
4247 argument to the @code{fseek} or @code{fseeko} function, specifies that
4248 the offset provided is relative to the beginning of the file.
4253 @deftypevr Macro int SEEK_CUR
4254 This is an integer constant which, when used as the @var{whence}
4255 argument to the @code{fseek} or @code{fseeko} function, specifies that
4256 the offset provided is relative to the current file position.
4261 @deftypevr Macro int SEEK_END
4262 This is an integer constant which, when used as the @var{whence}
4263 argument to the @code{fseek} or @code{fseeko} function, specifies that
4264 the offset provided is relative to the end of the file.
4269 @deftypefun void rewind (FILE *@var{stream})
4270 The @code{rewind} function positions the stream @var{stream} at the
4271 beginning of the file. It is equivalent to calling @code{fseek} or
4272 @code{fseeko} on the @var{stream} with an @var{offset} argument of
4273 @code{0L} and a @var{whence} argument of @code{SEEK_SET}, except that
4274 the return value is discarded and the error indicator for the stream is
4278 These three aliases for the @samp{SEEK_@dots{}} constants exist for the
4279 sake of compatibility with older BSD systems. They are defined in two
4280 different header files: @file{fcntl.h} and @file{sys/file.h}.
4287 An alias for @code{SEEK_SET}.
4293 An alias for @code{SEEK_CUR}.
4299 An alias for @code{SEEK_END}.
4302 @node Portable Positioning
4303 @section Portable File-Position Functions
4305 On the GNU system, the file position is truly a character count. You
4306 can specify any character count value as an argument to @code{fseek} or
4307 @code{fseeko} and get reliable results for any random access file.
4308 However, some @w{ISO C} systems do not represent file positions in this
4311 On some systems where text streams truly differ from binary streams, it
4312 is impossible to represent the file position of a text stream as a count
4313 of characters from the beginning of the file. For example, the file
4314 position on some systems must encode both a record offset within the
4315 file, and a character offset within the record.
4317 As a consequence, if you want your programs to be portable to these
4318 systems, you must observe certain rules:
4322 The value returned from @code{ftell} on a text stream has no predictable
4323 relationship to the number of characters you have read so far. The only
4324 thing you can rely on is that you can use it subsequently as the
4325 @var{offset} argument to @code{fseek} or @code{fseeko} to move back to
4326 the same file position.
4329 In a call to @code{fseek} or @code{fseeko} on a text stream, either the
4330 @var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and
4331 and the @var{offset} must be the result of an earlier call to @code{ftell}
4335 The value of the file position indicator of a text stream is undefined
4336 while there are characters that have been pushed back with @code{ungetc}
4337 that haven't been read or discarded. @xref{Unreading}.
4340 But even if you observe these rules, you may still have trouble for long
4341 files, because @code{ftell} and @code{fseek} use a @code{long int} value
4342 to represent the file position. This type may not have room to encode
4343 all the file positions in a large file. Using the @code{ftello} and
4344 @code{fseeko} functions might help here since the @code{off_t} type is
4345 expected to be able to hold all file position values but this still does
4346 not help to handle additional information which must be associated with
4349 So if you do want to support systems with peculiar encodings for the
4350 file positions, it is better to use the functions @code{fgetpos} and
4351 @code{fsetpos} instead. These functions represent the file position
4352 using the data type @code{fpos_t}, whose internal representation varies
4353 from system to system.
4355 These symbols are declared in the header file @file{stdio.h}.
4360 @deftp {Data Type} fpos_t
4361 This is the type of an object that can encode information about the
4362 file position of a stream, for use by the functions @code{fgetpos} and
4365 In the GNU system, @code{fpos_t} is an opaque data structure that
4366 contains internal data to represent file offset and conversion state
4367 information. In other systems, it might have a different internal
4370 When compiling with @code{_FILE_OFFSET_BITS == 64} on a 32 bit machine
4371 this type is in fact equivalent to @code{fpos64_t} since the LFS
4372 interface transparently replaces the old interface.
4377 @deftp {Data Type} fpos64_t
4378 This is the type of an object that can encode information about the
4379 file position of a stream, for use by the functions @code{fgetpos64} and
4382 In the GNU system, @code{fpos64_t} is an opaque data structure that
4383 contains internal data to represent file offset and conversion state
4384 information. In other systems, it might have a different internal
4390 @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
4391 This function stores the value of the file position indicator for the
4392 stream @var{stream} in the @code{fpos_t} object pointed to by
4393 @var{position}. If successful, @code{fgetpos} returns zero; otherwise
4394 it returns a nonzero value and stores an implementation-defined positive
4395 value in @code{errno}.
4397 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4398 32 bit system the function is in fact @code{fgetpos64}. I.e., the LFS
4399 interface transparently replaces the old interface.
4404 @deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position})
4405 This function is similar to @code{fgetpos} but the file position is
4406 returned in a variable of type @code{fpos64_t} to which @var{position}
4409 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4410 bits machine this function is available under the name @code{fgetpos}
4411 and so transparently replaces the old interface.
4416 @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position})
4417 This function sets the file position indicator for the stream @var{stream}
4418 to the position @var{position}, which must have been set by a previous
4419 call to @code{fgetpos} on the same stream. If successful, @code{fsetpos}
4420 clears the end-of-file indicator on the stream, discards any characters
4421 that were ``pushed back'' by the use of @code{ungetc}, and returns a value
4422 of zero. Otherwise, @code{fsetpos} returns a nonzero value and stores
4423 an implementation-defined positive value in @code{errno}.
4425 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4426 32 bit system the function is in fact @code{fsetpos64}. I.e., the LFS
4427 interface transparently replaces the old interface.
4432 @deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position})
4433 This function is similar to @code{fsetpos} but the file position used
4434 for positioning is provided in a variable of type @code{fpos64_t} to
4435 which @var{position} points.
4437 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4438 bits machine this function is available under the name @code{fsetpos}
4439 and so transparently replaces the old interface.
4442 @node Stream Buffering
4443 @section Stream Buffering
4445 @cindex buffering of streams
4446 Characters that are written to a stream are normally accumulated and
4447 transmitted asynchronously to the file in a block, instead of appearing
4448 as soon as they are output by the application program. Similarly,
4449 streams often retrieve input from the host environment in blocks rather
4450 than on a character-by-character basis. This is called @dfn{buffering}.
4452 If you are writing programs that do interactive input and output using
4453 streams, you need to understand how buffering works when you design the
4454 user interface to your program. Otherwise, you might find that output
4455 (such as progress or prompt messages) doesn't appear when you intended
4456 it to, or displays some other unexpected behavior.
4458 This section deals only with controlling when characters are transmitted
4459 between the stream and the file or device, and @emph{not} with how
4460 things like echoing, flow control, and the like are handled on specific
4461 classes of devices. For information on common control operations on
4462 terminal devices, see @ref{Low-Level Terminal Interface}.
4464 You can bypass the stream buffering facilities altogether by using the
4465 low-level input and output functions that operate on file descriptors
4466 instead. @xref{Low-Level I/O}.
4469 * Buffering Concepts:: Terminology is defined here.
4470 * Flushing Buffers:: How to ensure that output buffers are flushed.
4471 * Controlling Buffering:: How to specify what kind of buffering to use.
4474 @node Buffering Concepts
4475 @subsection Buffering Concepts
4477 There are three different kinds of buffering strategies:
4481 Characters written to or read from an @dfn{unbuffered} stream are
4482 transmitted individually to or from the file as soon as possible.
4483 @cindex unbuffered stream
4486 Characters written to a @dfn{line buffered} stream are transmitted to
4487 the file in blocks when a newline character is encountered.
4488 @cindex line buffered stream
4491 Characters written to or read from a @dfn{fully buffered} stream are
4492 transmitted to or from the file in blocks of arbitrary size.
4493 @cindex fully buffered stream
4496 Newly opened streams are normally fully buffered, with one exception: a
4497 stream connected to an interactive device such as a terminal is
4498 initially line buffered. @xref{Controlling Buffering}, for information
4499 on how to select a different kind of buffering. Usually the automatic
4500 selection gives you the most convenient kind of buffering for the file
4503 The use of line buffering for interactive devices implies that output
4504 messages ending in a newline will appear immediately---which is usually
4505 what you want. Output that doesn't end in a newline might or might not
4506 show up immediately, so if you want them to appear immediately, you
4507 should flush buffered output explicitly with @code{fflush}, as described
4508 in @ref{Flushing Buffers}.
4510 @node Flushing Buffers
4511 @subsection Flushing Buffers
4513 @cindex flushing a stream
4514 @dfn{Flushing} output on a buffered stream means transmitting all
4515 accumulated characters to the file. There are many circumstances when
4516 buffered output on a stream is flushed automatically:
4520 When you try to do output and the output buffer is full.
4523 When the stream is closed. @xref{Closing Streams}.
4526 When the program terminates by calling @code{exit}.
4527 @xref{Normal Termination}.
4530 When a newline is written, if the stream is line buffered.
4533 Whenever an input operation on @emph{any} stream actually reads data
4537 If you want to flush the buffered output at another time, call
4538 @code{fflush}, which is declared in the header file @file{stdio.h}.
4543 @deftypefun int fflush (FILE *@var{stream})
4544 This function causes any buffered output on @var{stream} to be delivered
4545 to the file. If @var{stream} is a null pointer, then
4546 @code{fflush} causes buffered output on @emph{all} open output streams
4549 This function returns @code{EOF} if a write error occurs, or zero
4555 @deftypefun int fflush_unlocked (FILE *@var{stream})
4556 The @code{fflush_unlocked} function is equivalent to the @code{fflush}
4557 function except that it does not implicitly lock the stream.
4560 The @code{fflush} function can be used to flush all streams currently
4561 opened. While this is useful in some situations it does often more than
4562 necessary since it might be done in situations when terminal input is
4563 required and the program wants to be sure that all output is visible on
4564 the terminal. But this means that only line buffered streams have to be
4565 flushed. Solaris introduced a function especially for this. It was
4566 always available in the GNU C library in some form but never officially
4569 @comment stdio_ext.h
4571 @deftypefun void _flushlbf (void)
4572 The @code{_flushlbf} function flushes all line buffered streams
4575 This function is declared in the @file{stdio_ext.h} header.
4578 @strong{Compatibility Note:} Some brain-damaged operating systems have
4579 been known to be so thoroughly fixated on line-oriented input and output
4580 that flushing a line buffered stream causes a newline to be written!
4581 Fortunately, this ``feature'' seems to be becoming less common. You do
4582 not need to worry about this in the GNU system.
4584 In some situations it might be useful to not flush the output pending
4585 for a stream but instead simply forget it. If transmission is costly
4586 and the output is not needed anymore this is valid reasoning. In this
4587 situation a non-standard function introduced in Solaris and available in
4588 the GNU C library can be used.
4590 @comment stdio_ext.h
4592 @deftypefun void __fpurge (FILE *@var{stream})
4593 The @code{__fpurge} function causes the buffer of the stream
4594 @var{stream} to be emptied. If the stream is currently in read mode all
4595 input in the buffer is lost. If the stream is in output mode the
4596 buffered output is not written to the device (or whatever other
4597 underlying storage) and the buffer the cleared.
4599 This function is declared in @file{stdio_ext.h}.
4602 @node Controlling Buffering
4603 @subsection Controlling Which Kind of Buffering
4605 After opening a stream (but before any other operations have been
4606 performed on it), you can explicitly specify what kind of buffering you
4607 want it to have using the @code{setvbuf} function.
4608 @cindex buffering, controlling
4610 The facilities listed in this section are declared in the header
4611 file @file{stdio.h}.
4616 @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
4617 This function is used to specify that the stream @var{stream} should
4618 have the buffering mode @var{mode}, which can be either @code{_IOFBF}
4619 (for full buffering), @code{_IOLBF} (for line buffering), or
4620 @code{_IONBF} (for unbuffered input/output).
4622 If you specify a null pointer as the @var{buf} argument, then @code{setvbuf}
4623 allocates a buffer itself using @code{malloc}. This buffer will be freed
4624 when you close the stream.
4626 Otherwise, @var{buf} should be a character array that can hold at least
4627 @var{size} characters. You should not free the space for this array as
4628 long as the stream remains open and this array remains its buffer. You
4629 should usually either allocate it statically, or @code{malloc}
4630 (@pxref{Unconstrained Allocation}) the buffer. Using an automatic array
4631 is not a good idea unless you close the file before exiting the block
4632 that declares the array.
4634 While the array remains a stream buffer, the stream I/O functions will
4635 use the buffer for their internal purposes. You shouldn't try to access
4636 the values in the array directly while the stream is using it for
4639 The @code{setvbuf} function returns zero on success, or a nonzero value
4640 if the value of @var{mode} is not valid or if the request could not
4646 @deftypevr Macro int _IOFBF
4647 The value of this macro is an integer constant expression that can be
4648 used as the @var{mode} argument to the @code{setvbuf} function to
4649 specify that the stream should be fully buffered.
4654 @deftypevr Macro int _IOLBF
4655 The value of this macro is an integer constant expression that can be
4656 used as the @var{mode} argument to the @code{setvbuf} function to
4657 specify that the stream should be line buffered.
4662 @deftypevr Macro int _IONBF
4663 The value of this macro is an integer constant expression that can be
4664 used as the @var{mode} argument to the @code{setvbuf} function to
4665 specify that the stream should be unbuffered.
4670 @deftypevr Macro int BUFSIZ
4671 The value of this macro is an integer constant expression that is good
4672 to use for the @var{size} argument to @code{setvbuf}. This value is
4673 guaranteed to be at least @code{256}.
4675 The value of @code{BUFSIZ} is chosen on each system so as to make stream
4676 I/O efficient. So it is a good idea to use @code{BUFSIZ} as the size
4677 for the buffer when you call @code{setvbuf}.
4679 Actually, you can get an even better value to use for the buffer size
4680 by means of the @code{fstat} system call: it is found in the
4681 @code{st_blksize} field of the file attributes. @xref{Attribute Meanings}.
4683 Sometimes people also use @code{BUFSIZ} as the allocation size of
4684 buffers used for related purposes, such as strings used to receive a
4685 line of input with @code{fgets} (@pxref{Character Input}). There is no
4686 particular reason to use @code{BUFSIZ} for this instead of any other
4687 integer, except that it might lead to doing I/O in chunks of an
4693 @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
4694 If @var{buf} is a null pointer, the effect of this function is
4695 equivalent to calling @code{setvbuf} with a @var{mode} argument of
4696 @code{_IONBF}. Otherwise, it is equivalent to calling @code{setvbuf}
4697 with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size}
4698 argument of @code{BUFSIZ}.
4700 The @code{setbuf} function is provided for compatibility with old code;
4701 use @code{setvbuf} in all new programs.
4706 @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
4707 If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
4708 Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
4709 buffer. The @var{size} argument specifies the length of @var{buf}.
4711 This function is provided for compatibility with old BSD code. Use
4712 @code{setvbuf} instead.
4717 @deftypefun void setlinebuf (FILE *@var{stream})
4718 This function makes @var{stream} be line buffered, and allocates the
4721 This function is provided for compatibility with old BSD code. Use
4722 @code{setvbuf} instead.
4725 It is possible to query whether a given stream is line buffered or not
4726 using a non-standard function introduced in Solaris and available in the
4729 @comment stdio_ext.h
4731 @deftypefun int __flbf (FILE *@var{stream})
4732 The @code{__flbf} function will return a nonzero value in case the
4733 stream @var{stream} is line buffered. Otherwise the return value is
4736 This function is declared in the @file{stdio_ext.h} header.
4739 Two more extensions allow to determine the size of the buffer and how
4740 much of it is used. These functions were also introduced in Solaris.
4742 @comment stdio_ext.h
4744 @deftypefun size_t __fbufsize (FILE *@var{stream})
4745 The @code{__fbufsize} function return the size of the buffer in the
4746 stream @var{stream}. This value can be used to optimize the use of the
4749 This function is declared in the @file{stdio_ext.h} header.
4752 @comment stdio_ext.h
4754 @deftypefun size_t __fpending (FILE *@var{stream}) The @code{__fpending}
4755 function returns the number of bytes currently in the output buffer.
4756 For wide-oriented stream the measuring unit is wide characters. This
4757 function should not be used on buffers in read mode or opened read-only.
4759 This function is declared in the @file{stdio_ext.h} header.
4762 @node Other Kinds of Streams
4763 @section Other Kinds of Streams
4765 The GNU library provides ways for you to define additional kinds of
4766 streams that do not necessarily correspond to an open file.
4768 One such type of stream takes input from or writes output to a string.
4769 These kinds of streams are used internally to implement the
4770 @code{sprintf} and @code{sscanf} functions. You can also create such a
4771 stream explicitly, using the functions described in @ref{String Streams}.
4773 More generally, you can define streams that do input/output to arbitrary
4774 objects using functions supplied by your program. This protocol is
4775 discussed in @ref{Custom Streams}.
4777 @strong{Portability Note:} The facilities described in this section are
4778 specific to GNU. Other systems or C implementations might or might not
4779 provide equivalent functionality.
4782 * String Streams:: Streams that get data from or put data in
4783 a string or memory buffer.
4784 * Obstack Streams:: Streams that store data in an obstack.
4785 * Custom Streams:: Defining your own streams with an arbitrary
4786 input data source and/or output data sink.
4789 @node String Streams
4790 @subsection String Streams
4792 @cindex stream, for I/O to a string
4793 @cindex string stream
4794 The @code{fmemopen} and @code{open_memstream} functions allow you to do
4795 I/O to a string or memory buffer. These facilities are declared in
4801 @deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
4802 This function opens a stream that allows the access specified by the
4803 @var{opentype} argument, that reads from or writes to the buffer specified
4804 by the argument @var{buf}. This array must be at least @var{size} bytes long.
4806 If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
4807 dynamically allocates an array @var{size} bytes long (as with @code{malloc};
4808 @pxref{Unconstrained Allocation}). This is really only useful
4809 if you are going to write things to the buffer and then read them back
4810 in again, because you have no way of actually getting a pointer to the
4811 buffer (for this, try @code{open_memstream}, below). The buffer is
4812 freed when the stream is closed.
4814 The argument @var{opentype} is the same as in @code{fopen}
4815 (@pxref{Opening Streams}). If the @var{opentype} specifies
4816 append mode, then the initial file position is set to the first null
4817 character in the buffer. Otherwise the initial file position is at the
4818 beginning of the buffer.
4820 When a stream open for writing is flushed or closed, a null character
4821 (zero byte) is written at the end of the buffer if it fits. You
4822 should add an extra byte to the @var{size} argument to account for this.
4823 Attempts to write more than @var{size} bytes to the buffer result
4826 For a stream open for reading, null characters (zero bytes) in the
4827 buffer do not count as ``end of file''. Read operations indicate end of
4828 file only when the file position advances past @var{size} bytes. So, if
4829 you want to read characters from a null-terminated string, you should
4830 supply the length of the string as the @var{size} argument.
4833 Here is an example of using @code{fmemopen} to create a stream for
4834 reading from a string:
4837 @include memopen.c.texi
4840 This program produces the following output:
4853 @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
4854 This function opens a stream for writing to a buffer. The buffer is
4855 allocated dynamically (as with @code{malloc}; @pxref{Unconstrained
4856 Allocation}) and grown as necessary.
4858 When the stream is closed with @code{fclose} or flushed with
4859 @code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
4860 contain the pointer to the buffer and its size. The values thus stored
4861 remain valid only as long as no further output on the stream takes
4862 place. If you do more output, you must flush the stream again to store
4863 new values before you use them again.
4865 A null character is written at the end of the buffer. This null character
4866 is @emph{not} included in the size value stored at @var{sizeloc}.
4868 You can move the stream's file position with @code{fseek} or
4869 @code{fseeko} (@pxref{File Positioning}). Moving the file position past
4870 the end of the data already written fills the intervening space with
4874 Here is an example of using @code{open_memstream}:
4877 @include memstrm.c.texi
4880 This program produces the following output:
4883 buf = `hello', size = 5
4884 buf = `hello, world', size = 12
4887 @c @group Invalid outside @example.
4888 @node Obstack Streams
4889 @subsection Obstack Streams
4891 You can open an output stream that puts it data in an obstack.
4896 @deftypefun {FILE *} open_obstack_stream (struct obstack *@var{obstack})
4897 This function opens a stream for writing data into the obstack @var{obstack}.
4898 This starts an object in the obstack and makes it grow as data is
4899 written (@pxref{Growing Objects}).
4900 @c @end group Doubly invalid because not nested right.
4902 Calling @code{fflush} on this stream updates the current size of the
4903 object to match the amount of data that has been written. After a call
4904 to @code{fflush}, you can examine the object temporarily.
4906 You can move the file position of an obstack stream with @code{fseek} or
4907 @code{fseeko} (@pxref{File Positioning}). Moving the file position past
4908 the end of the data written fills the intervening space with zeros.
4910 To make the object permanent, update the obstack with @code{fflush}, and
4911 then use @code{obstack_finish} to finalize the object and get its address.
4912 The following write to the stream starts a new object in the obstack,
4913 and later writes add to that object until you do another @code{fflush}
4914 and @code{obstack_finish}.
4916 But how do you find out how long the object is? You can get the length
4917 in bytes by calling @code{obstack_object_size} (@pxref{Status of an
4918 Obstack}), or you can null-terminate the object like this:
4921 obstack_1grow (@var{obstack}, 0);
4924 Whichever one you do, you must do it @emph{before} calling
4925 @code{obstack_finish}. (You can do both if you wish.)
4928 Here is a sample function that uses @code{open_obstack_stream}:
4932 make_message_string (const char *a, int b)
4934 FILE *stream = open_obstack_stream (&message_obstack);
4935 output_task (stream);
4936 fprintf (stream, ": ");
4937 fprintf (stream, a, b);
4938 fprintf (stream, "\n");
4940 obstack_1grow (&message_obstack, 0);
4941 return obstack_finish (&message_obstack);
4945 @node Custom Streams
4946 @subsection Programming Your Own Custom Streams
4947 @cindex custom streams
4948 @cindex programming your own streams
4950 This section describes how you can make a stream that gets input from an
4951 arbitrary data source or writes output to an arbitrary data sink
4952 programmed by you. We call these @dfn{custom streams}. The functions
4953 and types described here are all GNU extensions.
4955 @c !!! this does not talk at all about the higher-level hooks
4958 * Streams and Cookies:: The @dfn{cookie} records where to fetch or
4959 store data that is read or written.
4960 * Hook Functions:: How you should define the four @dfn{hook
4961 functions} that a custom stream needs.
4964 @node Streams and Cookies
4965 @subsubsection Custom Streams and Cookies
4966 @cindex cookie, for custom stream
4968 Inside every custom stream is a special object called the @dfn{cookie}.
4969 This is an object supplied by you which records where to fetch or store
4970 the data read or written. It is up to you to define a data type to use
4971 for the cookie. The stream functions in the library never refer
4972 directly to its contents, and they don't even know what the type is;
4973 they record its address with type @code{void *}.
4975 To implement a custom stream, you must specify @emph{how} to fetch or
4976 store the data in the specified place. You do this by defining
4977 @dfn{hook functions} to read, write, change ``file position'', and close
4978 the stream. All four of these functions will be passed the stream's
4979 cookie so they can tell where to fetch or store the data. The library
4980 functions don't know what's inside the cookie, but your functions will
4983 When you create a custom stream, you must specify the cookie pointer,
4984 and also the four hook functions stored in a structure of type
4985 @code{cookie_io_functions_t}.
4987 These facilities are declared in @file{stdio.h}.
4992 @deftp {Data Type} {cookie_io_functions_t}
4993 This is a structure type that holds the functions that define the
4994 communications protocol between the stream and its cookie. It has
4995 the following members:
4998 @item cookie_read_function_t *read
4999 This is the function that reads data from the cookie. If the value is a
5000 null pointer instead of a function, then read operations on this stream
5001 always return @code{EOF}.
5003 @item cookie_write_function_t *write
5004 This is the function that writes data to the cookie. If the value is a
5005 null pointer instead of a function, then data written to the stream is
5008 @item cookie_seek_function_t *seek
5009 This is the function that performs the equivalent of file positioning on
5010 the cookie. If the value is a null pointer instead of a function, calls
5011 to @code{fseek} or @code{fseeko} on this stream can only seek to
5012 locations within the buffer; any attempt to seek outside the buffer will
5013 return an @code{ESPIPE} error.
5015 @item cookie_close_function_t *close
5016 This function performs any appropriate cleanup on the cookie when
5017 closing the stream. If the value is a null pointer instead of a
5018 function, nothing special is done to close the cookie when the stream is
5025 @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions})
5026 This function actually creates the stream for communicating with the
5027 @var{cookie} using the functions in the @var{io-functions} argument.
5028 The @var{opentype} argument is interpreted as for @code{fopen};
5029 see @ref{Opening Streams}. (But note that the ``truncate on
5030 open'' option is ignored.) The new stream is fully buffered.
5032 The @code{fopencookie} function returns the newly created stream, or a null
5033 pointer in case of an error.
5036 @node Hook Functions
5037 @subsubsection Custom Stream Hook Functions
5038 @cindex hook functions (of custom streams)
5040 Here are more details on how you should define the four hook functions
5041 that a custom stream needs.
5043 You should define the function to read data from the cookie as:
5046 ssize_t @var{reader} (void *@var{cookie}, char *@var{buffer}, size_t @var{size})
5049 This is very similar to the @code{read} function; see @ref{I/O
5050 Primitives}. Your function should transfer up to @var{size} bytes into
5051 the @var{buffer}, and return the number of bytes read, or zero to
5052 indicate end-of-file. You can return a value of @code{-1} to indicate
5055 You should define the function to write data to the cookie as:
5058 ssize_t @var{writer} (void *@var{cookie}, const char *@var{buffer}, size_t @var{size})
5061 This is very similar to the @code{write} function; see @ref{I/O
5062 Primitives}. Your function should transfer up to @var{size} bytes from
5063 the buffer, and return the number of bytes written. You can return a
5064 value of @code{-1} to indicate an error.
5066 You should define the function to perform seek operations on the cookie
5070 int @var{seeker} (void *@var{cookie}, off64_t *@var{position}, int @var{whence})
5073 For this function, the @var{position} and @var{whence} arguments are
5074 interpreted as for @code{fgetpos}; see @ref{Portable Positioning}.
5076 After doing the seek operation, your function should store the resulting
5077 file position relative to the beginning of the file in @var{position}.
5078 Your function should return a value of @code{0} on success and @code{-1}
5079 to indicate an error.
5081 You should define the function to do cleanup operations on the cookie
5082 appropriate for closing the stream as:
5085 int @var{cleaner} (void *@var{cookie})
5088 Your function should return @code{-1} to indicate an error, and @code{0}
5093 @deftp {Data Type} cookie_read_function
5094 This is the data type that the read function for a custom stream should have.
5095 If you declare the function as shown above, this is the type it will have.
5100 @deftp {Data Type} cookie_write_function
5101 The data type of the write function for a custom stream.
5106 @deftp {Data Type} cookie_seek_function
5107 The data type of the seek function for a custom stream.
5112 @deftp {Data Type} cookie_close_function
5113 The data type of the close function for a custom stream.
5120 There is another set of functions one can give a stream, the
5121 input-room and output-room functions. These functions must
5122 understand stdio internals. To describe how to use these
5123 functions, you also need to document lots of how stdio works
5124 internally (which isn't relevant for other uses of stdio).
5125 Perhaps I can write an interface spec from which you can write
5126 good documentation. But it's pretty complex and deals with lots
5127 of nitty-gritty details. I think it might be better to let this
5128 wait until the rest of the manual is more done and polished.
5132 @c ??? This section could use an example.
5135 @node Formatted Messages
5136 @section Formatted Messages
5137 @cindex formatted messages
5139 On systems which are based on System V messages of programs (especially
5140 the system tools) are printed in a strict form using the @code{fmtmsg}
5141 function. The uniformity sometimes helps the user to interpret messages
5142 and the strictness tests of the @code{fmtmsg} function ensure that the
5143 programmer follows some minimal requirements.
5146 * Printing Formatted Messages:: The @code{fmtmsg} function.
5147 * Adding Severity Classes:: Add more severity classes.
5148 * Example:: How to use @code{fmtmsg} and @code{addseverity}.
5152 @node Printing Formatted Messages
5153 @subsection Printing Formatted Messages
5155 Messages can be printed to standard error and/or to the console. To
5156 select the destination the programmer can use the following two values,
5157 bitwise OR combined if wanted, for the @var{classification} parameter of
5162 Display the message in standard error.
5164 Display the message on the system console.
5167 The erroneous piece of the system can be signalled by exactly one of the
5168 following values which also is bitwise ORed with the
5169 @var{classification} parameter to @code{fmtmsg}:
5173 The source of the condition is some hardware.
5175 The source of the condition is some software.
5177 The source of the condition is some firmware.
5180 A third component of the @var{classification} parameter to @code{fmtmsg}
5181 can describe the part of the system which detects the problem. This is
5182 done by using exactly one of the following values:
5186 The erroneous condition is detected by the application.
5188 The erroneous condition is detected by a utility.
5190 The erroneous condition is detected by the operating system.
5193 A last component of @var{classification} can signal the results of this
5194 message. Exactly one of the following values can be used:
5198 It is a recoverable error.
5200 It is a non-recoverable error.
5205 @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})
5206 Display a message described by its parameters on the device(s) specified
5207 in the @var{classification} parameter. The @var{label} parameter
5208 identifies the source of the message. The string should consist of two
5209 colon separated parts where the first part has not more than 10 and the
5210 second part not more than 14 characters. The @var{text} parameter
5211 describes the condition of the error, the @var{action} parameter possible
5212 steps to recover from the error and the @var{tag} parameter is a
5213 reference to the online documentation where more information can be
5214 found. It should contain the @var{label} value and a unique
5215 identification number.
5217 Each of the parameters can be a special value which means this value
5218 is to be omitted. The symbolic names for these values are:
5222 Ignore @var{label} parameter.
5224 Ignore @var{severity} parameter.
5226 Ignore @var{classification} parameter. This implies that nothing is
5229 Ignore @var{text} parameter.
5231 Ignore @var{action} parameter.
5233 Ignore @var{tag} parameter.
5236 There is another way certain fields can be omitted from the output to
5237 standard error. This is described below in the description of
5238 environment variables influencing the behavior.
5240 The @var{severity} parameter can have one of the values in the following
5242 @cindex severity class
5246 Nothing is printed, this value is the same as @code{MM_NULLSEV}.
5248 This value is printed as @code{HALT}.
5250 This value is printed as @code{ERROR}.
5252 This value is printed as @code{WARNING}.
5254 This value is printed as @code{INFO}.
5257 The numeric value of these five macros are between @code{0} and
5258 @code{4}. Using the environment variable @code{SEV_LEVEL} or using the
5259 @code{addseverity} function one can add more severity levels with their
5260 corresponding string to print. This is described below
5261 (@pxref{Adding Severity Classes}).
5264 If no parameter is ignored the output looks like this:
5267 @var{label}: @var{severity-string}: @var{text}
5268 TO FIX: @var{action} @var{tag}
5271 The colons, new line characters and the @code{TO FIX} string are
5272 inserted if necessary, i.e., if the corresponding parameter is not
5275 This function is specified in the X/Open Portability Guide. It is also
5276 available on all systems derived from System V.
5278 The function returns the value @code{MM_OK} if no error occurred. If
5279 only the printing to standard error failed, it returns @code{MM_NOMSG}.
5280 If printing to the console fails, it returns @code{MM_NOCON}. If
5281 nothing is printed @code{MM_NOTOK} is returned. Among situations where
5282 all outputs fail this last value is also returned if a parameter value
5286 There are two environment variables which influence the behavior of
5287 @code{fmtmsg}. The first is @code{MSGVERB}. It is used to control the
5288 output actually happening on standard error (@emph{not} the console
5289 output). Each of the five fields can explicitly be enabled. To do
5290 this the user has to put the @code{MSGVERB} variable with a format like
5291 the following in the environment before calling the @code{fmtmsg} function
5295 MSGVERB=@var{keyword}[:@var{keyword}[:@dots{}]]
5298 Valid @var{keyword}s are @code{label}, @code{severity}, @code{text},
5299 @code{action}, and @code{tag}. If the environment variable is not given
5300 or is the empty string, a not supported keyword is given or the value is
5301 somehow else invalid, no part of the message is masked out.
5303 The second environment variable which influences the behavior of
5304 @code{fmtmsg} is @code{SEV_LEVEL}. This variable and the change in the
5305 behavior of @code{fmtmsg} is not specified in the X/Open Portability
5306 Guide. It is available in System V systems, though. It can be used to
5307 introduce new severity levels. By default, only the five severity levels
5308 described above are available. Any other numeric value would make
5309 @code{fmtmsg} print nothing.
5311 If the user puts @code{SEV_LEVEL} with a format like
5314 SEV_LEVEL=[@var{description}[:@var{description}[:@dots{}]]]
5318 in the environment of the process before the first call to
5319 @code{fmtmsg}, where @var{description} has a value of the form
5322 @var{severity-keyword},@var{level},@var{printstring}
5325 The @var{severity-keyword} part is not used by @code{fmtmsg} but it has
5326 to be present. The @var{level} part is a string representation of a
5327 number. The numeric value must be a number greater than 4. This value
5328 must be used in the @var{severity} parameter of @code{fmtmsg} to select
5329 this class. It is not possible to overwrite any of the predefined
5330 classes. The @var{printstring} is the string printed when a message of
5331 this class is processed by @code{fmtmsg} (see above, @code{fmtsmg} does
5332 not print the numeric value but instead the string representation).
5335 @node Adding Severity Classes
5336 @subsection Adding Severity Classes
5337 @cindex severity class
5339 There is another possibility to introduce severity classes besides using
5340 the environment variable @code{SEV_LEVEL}. This simplifies the task of
5341 introducing new classes in a running program. One could use the
5342 @code{setenv} or @code{putenv} function to set the environment variable,
5343 but this is toilsome.
5345 @deftypefun int addseverity (int @var{severity}, const char *@var{string})
5346 This function allows the introduction of new severity classes which can be
5347 addressed by the @var{severity} parameter of the @code{fmtmsg} function.
5348 The @var{severity} parameter of @code{addseverity} must match the value
5349 for the parameter with the same name of @code{fmtmsg}, and @var{string}
5350 is the string printed in the actual messages instead of the numeric
5353 If @var{string} is @code{NULL} the severity class with the numeric value
5354 according to @var{severity} is removed.
5356 It is not possible to overwrite or remove one of the default severity
5357 classes. All calls to @code{addseverity} with @var{severity} set to one
5358 of the values for the default classes will fail.
5360 The return value is @code{MM_OK} if the task was successfully performed.
5361 If the return value is @code{MM_NOTOK} something went wrong. This could
5362 mean that no more memory is available or a class is not available when
5363 it has to be removed.
5365 This function is not specified in the X/Open Portability Guide although
5366 the @code{fmtsmg} function is. It is available on System V systems.
5371 @subsection How to use @code{fmtmsg} and @code{addseverity}
5373 Here is a simple example program to illustrate the use of the both
5374 functions described in this section.
5377 @include fmtmsgexpl.c.texi
5380 The second call to @code{fmtmsg} illustrates a use of this function as
5381 it usually occurs on System V systems, which heavily use this function.
5382 It seems worthwhile to give a short explanation here of how this system
5383 works on System V. The value of the
5384 @var{label} field (@code{UX:cat}) says that the error occurred in the
5385 Unix program @code{cat}. The explanation of the error follows and the
5386 value for the @var{action} parameter is @code{"refer to manual"}. One
5387 could be more specific here, if necessary. The @var{tag} field contains,
5388 as proposed above, the value of the string given for the @var{label}
5389 parameter, and additionally a unique ID (@code{001} in this case). For
5390 a GNU environment this string could contain a reference to the
5391 corresponding node in the Info page for the program.
5394 Running this program without specifying the @code{MSGVERB} and
5395 @code{SEV_LEVEL} function produces the following output:
5398 UX:cat: NOTE2: invalid syntax
5399 TO FIX: refer to manual UX:cat:001
5402 We see the different fields of the message and how the extra glue (the
5403 colons and the @code{TO FIX} string) are printed. But only one of the
5404 three calls to @code{fmtmsg} produced output. The first call does not
5405 print anything because the @var{label} parameter is not in the correct
5406 form. The string must contain two fields, separated by a colon
5407 (@pxref{Printing Formatted Messages}). The third @code{fmtmsg} call
5408 produced no output since the class with the numeric value @code{6} is
5409 not defined. Although a class with numeric value @code{5} is also not
5410 defined by default, the call to @code{addseverity} introduces it and
5411 the second call to @code{fmtmsg} produces the above output.
5413 When we change the environment of the program to contain
5414 @code{SEV_LEVEL=XXX,6,NOTE} when running it we get a different result:
5417 UX:cat: NOTE2: invalid syntax
5418 TO FIX: refer to manual UX:cat:001
5419 label:foo: NOTE: text
5423 Now the third call to @code{fmtmsg} produced some output and we see how
5424 the string @code{NOTE} from the environment variable appears in the
5427 Now we can reduce the output by specifying which fields we are
5428 interested in. If we additionally set the environment variable
5429 @code{MSGVERB} to the value @code{severity:label:action} we get the
5434 TO FIX: refer to manual
5440 I.e., the output produced by the @var{text} and the @var{tag} parameters
5441 to @code{fmtmsg} vanished. Please also note that now there is no colon
5442 after the @code{NOTE} and @code{NOTE2} strings in the output. This is
5443 not necessary since there is no more output on this line because the text