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}.
58 @deftp {Data Type} FILE
59 @standards{ISO, stdio.h}
60 This is the data type used to represent stream objects. A @code{FILE}
61 object holds all of the internal state information about the connection
62 to the associated file, including such things as the file position
63 indicator and buffering information. Each stream also has error and
64 end-of-file status indicators that can be tested with the @code{ferror}
65 and @code{feof} functions; see @ref{EOF and Errors}.
68 @code{FILE} objects are allocated and managed internally by the
69 input/output library functions. Don't try to create your own objects of
70 type @code{FILE}; let the library do it. Your programs should
71 deal only with pointers to these objects (that is, @code{FILE *} values)
72 rather than the objects themselves.
73 @c !!! should say that FILE's have "No user-serviceable parts inside."
75 @node Standard Streams
76 @section Standard Streams
77 @cindex standard streams
78 @cindex streams, standard
80 When the @code{main} function of your program is invoked, it already has
81 three predefined streams open and available for use. These represent
82 the ``standard'' input and output channels that have been established
85 These streams are declared in the header file @file{stdio.h}.
88 @deftypevar {FILE *} stdin
89 @standards{ISO, stdio.h}
90 The @dfn{standard input} stream, which is the normal source of input for the
93 @cindex standard input stream
95 @deftypevar {FILE *} stdout
96 @standards{ISO, stdio.h}
97 The @dfn{standard output} stream, which is used for normal output from
100 @cindex standard output stream
102 @deftypevar {FILE *} stderr
103 @standards{ISO, stdio.h}
104 The @dfn{standard error} stream, which is used for error messages and
105 diagnostics issued by the program.
107 @cindex standard error stream
109 On @gnusystems{}, you can specify what files or processes correspond to
110 these streams using the pipe and redirection facilities provided by the
111 shell. (The primitives shells use to implement these facilities are
112 described in @ref{File System Interface}.) Most other operating systems
113 provide similar mechanisms, but the details of how to use them can vary.
115 In @theglibc{}, @code{stdin}, @code{stdout}, and @code{stderr} are
116 normal variables which you can set just like any others. For example,
117 to redirect the standard output to a file, you could do:
121 stdout = fopen ("standard-output-file", "w");
124 Note however, that in other systems @code{stdin}, @code{stdout}, and
125 @code{stderr} are macros that you cannot assign to in the normal way.
126 But you can use @code{freopen} to get the effect of closing one and
127 reopening it. @xref{Opening Streams}.
129 The three streams @code{stdin}, @code{stdout}, and @code{stderr} are not
130 unoriented at program start (@pxref{Streams and I18N}).
132 @node Opening Streams
133 @section Opening Streams
135 @cindex opening a stream
136 Opening a file with the @code{fopen} function creates a new stream and
137 establishes a connection between the stream and a file. This may
138 involve creating a new file.
141 Everything described in this section is declared in the header file
144 @deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype})
145 @standards{ISO, stdio.h}
146 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
147 @c fopen may leak the list lock if cancelled within _IO_link_in.
148 The @code{fopen} function opens a stream for I/O to the file
149 @var{filename}, and returns a pointer to the stream.
151 The @var{opentype} argument is a string that controls how the file is
152 opened and specifies attributes of the resulting stream. It must begin
153 with one of the following sequences of characters:
157 Open an existing file for reading only.
160 Open the file for writing only. If the file already exists, it is
161 truncated to zero length. Otherwise a new file is created.
164 Open a file for append access; that is, writing at the end of file only.
165 If the file already exists, its initial contents are unchanged and
166 output to the stream is appended to the end of the file.
167 Otherwise, a new, empty file is created.
170 Open an existing file for both reading and writing. The initial contents
171 of the file are unchanged and the initial file position is at the
172 beginning of the file.
175 Open a file for both reading and writing. If the file already exists, it
176 is truncated to zero length. Otherwise, a new file is created.
179 Open or create file for both reading and appending. If the file exists,
180 its initial contents are unchanged. Otherwise, a new file is created.
181 The initial file position for reading is at the beginning of the file,
182 but output is always appended to the end of the file.
185 As you can see, @samp{+} requests a stream that can do both input and
186 output. When using such a stream, you must call @code{fflush}
187 (@pxref{Stream Buffering}) or a file positioning function such as
188 @code{fseek} (@pxref{File Positioning}) when switching from reading
189 to writing or vice versa. Otherwise, internal buffers might not be
192 Additional characters may appear after these to specify flags for the
193 call. Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is
194 the only part you are guaranteed will be understood by all systems.
196 @Theglibc{} defines additional characters for use in @var{opentype}:
200 The file is opened with cancellation in the I/O functions disabled.
203 The underlying file descriptor will be closed if you use any of the
204 @code{exec@dots{}} functions (@pxref{Executing a File}). (This is
205 equivalent to having set @code{FD_CLOEXEC} on that descriptor.
206 @xref{Descriptor Flags}.)
209 The file is opened and accessed using @code{mmap}. This is only
210 supported with files opened for reading.
213 Insist on creating a new file---if a file @var{filename} already
214 exists, @code{fopen} fails rather than opening it. If you use
215 @samp{x} you are guaranteed that you will not clobber an existing
216 file. This is equivalent to the @code{O_EXCL} option to the
217 @code{open} function (@pxref{Opening and Closing Files}).
219 The @samp{x} modifier is part of @w{ISO C11}, which says the file is
220 created with exclusive access; in @theglibc{} this means the
221 equivalent of @code{O_EXCL}.
224 The character @samp{b} in @var{opentype} has a standard meaning; it
225 requests a binary stream rather than a text stream. But this makes no
226 difference in POSIX systems (including @gnusystems{}). If both
227 @samp{+} and @samp{b} are specified, they can appear in either order.
228 @xref{Binary Streams}.
230 @cindex stream orientation
231 @cindex orientation, stream
232 If the @var{opentype} string contains the sequence
233 @code{,ccs=@var{STRING}} then @var{STRING} is taken as the name of a
234 coded character set and @code{fopen} will mark the stream as
235 wide-oriented with appropriate conversion functions in place to convert
236 from and to the character set @var{STRING}. Any other stream
237 is opened initially unoriented and the orientation is decided with the
238 first file operation. If the first operation is a wide character
239 operation, the stream is not only marked as wide-oriented, also the
240 conversion functions to convert to the coded character set used for the
241 current locale are loaded. This will not change anymore from this point
242 on even if the locale selected for the @code{LC_CTYPE} category is
245 Any other characters in @var{opentype} are simply ignored. They may be
246 meaningful in other systems.
248 If the open fails, @code{fopen} returns a null pointer.
250 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
251 32 bit machine this function is in fact @code{fopen64} since the LFS
252 interface replaces transparently the old interface.
255 You can have multiple streams (or file descriptors) pointing to the same
256 file open at the same time. If you do only input, this works
257 straightforwardly, but you must be careful if any output streams are
258 included. @xref{Stream/Descriptor Precautions}. This is equally true
259 whether the streams are in one program (not usual) or in several
260 programs (which can easily happen). It may be advantageous to use the
261 file locking facilities to avoid simultaneous access. @xref{File
264 @deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype})
265 @standards{Unix98, stdio.h}
266 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
267 This function is similar to @code{fopen} but the stream it returns a
268 pointer for is opened using @code{open64}. Therefore this stream can be
269 used even on files larger than @twoexp{31} bytes on 32 bit machines.
271 Please note that the return type is still @code{FILE *}. There is no
272 special @code{FILE} type for the LFS interface.
274 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
275 bits machine this function is available under the name @code{fopen}
276 and so transparently replaces the old interface.
279 @deftypevr Macro int FOPEN_MAX
280 @standards{ISO, stdio.h}
281 The value of this macro is an integer constant expression that
282 represents the minimum number of streams that the implementation
283 guarantees can be open simultaneously. You might be able to open more
284 than this many streams, but that is not guaranteed. The value of this
285 constant is at least eight, which includes the three standard streams
286 @code{stdin}, @code{stdout}, and @code{stderr}. In POSIX.1 systems this
287 value is determined by the @code{OPEN_MAX} parameter; @pxref{General
288 Limits}. In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE}
289 resource limit; @pxref{Limits on Resources}.
292 @deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
293 @standards{ISO, stdio.h}
294 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}}
295 @c Like most I/O operations, this one is guarded by a recursive lock,
296 @c released even upon cancellation, but cancellation may leak file
297 @c descriptors and leave the stream in an inconsistent state (e.g.,
298 @c still bound to the closed descriptor). Also, if the stream is
299 @c part-way through a significant update (say running freopen) when a
300 @c signal handler calls freopen again on the same stream, the result is
301 @c likely to be an inconsistent stream, and the possibility of closing
302 @c twice file descriptor number that the stream used to use, the second
303 @c time when it might have already been reused by another thread.
304 This function is like a combination of @code{fclose} and @code{fopen}.
305 It first closes the stream referred to by @var{stream}, ignoring any
306 errors that are detected in the process. (Because errors are ignored,
307 you should not use @code{freopen} on an output stream if you have
308 actually done any output using the stream.) Then the file named by
309 @var{filename} is opened with mode @var{opentype} as for @code{fopen},
310 and associated with the same stream object @var{stream}.
312 If the operation fails, a null pointer is returned; otherwise,
313 @code{freopen} returns @var{stream}. On Linux, @code{freopen} may also
314 fail and set @code{errno} to @code{EBUSY} when the kernel structure for
315 the old file descriptor was not initialized completely before @code{freopen}
316 was called. This can only happen in multi-threaded programs, when two
317 threads race to allocate the same file descriptor number. To avoid the
318 possibility of this race, do not use @code{close} to close the underlying
319 file descriptor for a @code{FILE}; either use @code{freopen} while the
320 file is still open, or use @code{open} and then @code{dup2} to install
321 the new file descriptor.
323 @code{freopen} has traditionally been used to connect a standard stream
324 such as @code{stdin} with a file of your own choice. This is useful in
325 programs in which use of a standard stream for certain purposes is
326 hard-coded. In @theglibc{}, you can simply close the standard
327 streams and open new ones with @code{fopen}. But other systems lack
328 this ability, so using @code{freopen} is more portable.
330 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
331 32 bit machine this function is in fact @code{freopen64} since the LFS
332 interface replaces transparently the old interface.
335 @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
336 @standards{Unix98, stdio.h}
337 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}}
338 This function is similar to @code{freopen}. The only difference is that
339 on 32 bit machine the stream returned is able to read beyond the
340 @twoexp{31} bytes limits imposed by the normal interface. It should be
341 noted that the stream pointed to by @var{stream} need not be opened
342 using @code{fopen64} or @code{freopen64} since its mode is not important
345 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
346 bits machine this function is available under the name @code{freopen}
347 and so transparently replaces the old interface.
350 In some situations it is useful to know whether a given stream is
351 available for reading or writing. This information is normally not
352 available and would have to be remembered separately. Solaris
353 introduced a few functions to get this information from the stream
354 descriptor and these functions are also available in @theglibc{}.
356 @deftypefun int __freadable (FILE *@var{stream})
357 @standards{GNU, stdio_ext.h}
358 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
359 The @code{__freadable} function determines whether the stream
360 @var{stream} was opened to allow reading. In this case the return value
361 is nonzero. For write-only streams the function returns zero.
363 This function is declared in @file{stdio_ext.h}.
366 @deftypefun int __fwritable (FILE *@var{stream})
367 @standards{GNU, stdio_ext.h}
368 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
369 The @code{__fwritable} function determines whether the stream
370 @var{stream} was opened to allow writing. In this case the return value
371 is nonzero. For read-only streams the function returns zero.
373 This function is declared in @file{stdio_ext.h}.
376 For slightly different kinds of problems there are two more functions.
377 They provide even finer-grained information.
379 @deftypefun int __freading (FILE *@var{stream})
380 @standards{GNU, stdio_ext.h}
381 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
382 The @code{__freading} function determines whether the stream
383 @var{stream} was last read from or whether it is opened read-only. In
384 this case the return value is nonzero, otherwise it is zero.
385 Determining whether a stream opened for reading and writing was last
386 used for writing allows to draw conclusions about the content about the
387 buffer, among other things.
389 This function is declared in @file{stdio_ext.h}.
392 @deftypefun int __fwriting (FILE *@var{stream})
393 @standards{GNU, stdio_ext.h}
394 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
395 The @code{__fwriting} function determines whether the stream
396 @var{stream} was last written to or whether it is opened write-only. In
397 this case the return value is nonzero, otherwise it is zero.
399 This function is declared in @file{stdio_ext.h}.
403 @node Closing Streams
404 @section Closing Streams
406 @cindex closing a stream
407 When a stream is closed with @code{fclose}, the connection between the
408 stream and the file is canceled. After you have closed a stream, you
409 cannot perform any additional operations on it.
411 @deftypefun int fclose (FILE *@var{stream})
412 @standards{ISO, stdio.h}
413 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
414 @c After fclose, it is undefined behavior to use the stream it points
415 @c to. Therefore, one must only call fclose when the stream is
416 @c otherwise unused. Concurrent uses started before will complete
417 @c successfully because of the lock, which makes it MT-Safe. Calling it
418 @c from a signal handler is perfectly safe if the stream is known to be
419 @c no longer used, which is a precondition for fclose to be safe in the
420 @c first place; since this is no further requirement, fclose is safe for
421 @c use in async signals too. After calling fclose, you can no longer
422 @c use the stream, not even to fclose it again, so its memory and file
423 @c descriptor may leak if fclose is canceled before @c releasing them.
424 @c That the stream must be unused and it becomes unused after the call
425 @c is what would enable fclose to be AS- and AC-Safe while freopen
426 @c isn't. However, because of the possibility of leaving __gconv_lock
427 @c taken upon cancellation, AC-Safety is lost.
428 This function causes @var{stream} to be closed and the connection to
429 the corresponding file to be broken. Any buffered output is written
430 and any buffered input is discarded. The @code{fclose} function returns
431 a value of @code{0} if the file was closed successfully, and @code{EOF}
432 if an error was detected.
434 It is important to check for errors when you call @code{fclose} to close
435 an output stream, because real, everyday errors can be detected at this
436 time. For example, when @code{fclose} writes the remaining buffered
437 output, it might get an error because the disk is full. Even if you
438 know the buffer is empty, errors can still occur when closing a file if
441 The function @code{fclose} is declared in @file{stdio.h}.
444 To close all streams currently available @theglibc{} provides
447 @deftypefun int fcloseall (void)
448 @standards{GNU, stdio.h}
449 @safety{@prelim{}@mtunsafe{@mtasurace{:streams}}@asunsafe{}@acsafe{}}
450 @c Like fclose, using any previously-opened streams after fcloseall is
451 @c undefined. However, the implementation of fcloseall isn't equivalent
452 @c to calling fclose for all streams: it just flushes and unbuffers all
453 @c streams, without any locking. It's the flushing without locking that
455 This function causes all open streams of the process to be closed and
456 the connections to corresponding files to be broken. All buffered data
457 is written and any buffered input is discarded. The @code{fcloseall}
458 function returns a value of @code{0} if all the files were closed
459 successfully, and @code{EOF} if an error was detected.
461 This function should be used only in special situations, e.g., when an
462 error occurred and the program must be aborted. Normally each single
463 stream should be closed separately so that problems with individual
464 streams can be identified. It is also problematic since the standard
465 streams (@pxref{Standard Streams}) will also be closed.
467 The function @code{fcloseall} is declared in @file{stdio.h}.
470 If the @code{main} function to your program returns, or if you call the
471 @code{exit} function (@pxref{Normal Termination}), all open streams are
472 automatically closed properly. If your program terminates in any other
473 manner, such as by calling the @code{abort} function (@pxref{Aborting a
474 Program}) or from a fatal signal (@pxref{Signal Handling}), open streams
475 might not be closed properly. Buffered output might not be flushed and
476 files may be incomplete. For more information on buffering of streams,
477 see @ref{Stream Buffering}.
479 @node Streams and Threads
480 @section Streams and Threads
483 @cindex multi-threaded application
484 Streams can be used in multi-threaded applications in the same way they
485 are used in single-threaded applications. But the programmer must be
486 aware of the possible complications. It is important to know about
487 these also if the program one writes never use threads since the design
488 and implementation of many stream functions are heavily influenced by the
489 requirements added by multi-threaded programming.
491 The POSIX standard requires that by default the stream operations are
492 atomic. I.e., issuing two stream operations for the same stream in two
493 threads at the same time will cause the operations to be executed as if
494 they were issued sequentially. The buffer operations performed while
495 reading or writing are protected from other uses of the same stream. To
496 do this each stream has an internal lock object which has to be
497 (implicitly) acquired before any work can be done.
499 But there are situations where this is not enough and there are also
500 situations where this is not wanted. The implicit locking is not enough
501 if the program requires more than one stream function call to happen
502 atomically. One example would be if an output line a program wants to
503 generate is created by several function calls. The functions by
504 themselves would ensure only atomicity of their own operation, but not
505 atomicity over all the function calls. For this it is necessary to
506 perform the stream locking in the application code.
508 @deftypefun void flockfile (FILE *@var{stream})
509 @standards{POSIX, stdio.h}
510 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
511 @c There's no way to tell whether the lock was acquired before or after
512 @c cancellation so as to unlock only when appropriate.
513 The @code{flockfile} function acquires the internal locking object
514 associated with the stream @var{stream}. This ensures that no other
515 thread can explicitly through @code{flockfile}/@code{ftrylockfile} or
516 implicitly through the call of a stream function lock the stream. The
517 thread will block until the lock is acquired. An explicit call to
518 @code{funlockfile} has to be used to release the lock.
521 @deftypefun int ftrylockfile (FILE *@var{stream})
522 @standards{POSIX, stdio.h}
523 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
524 The @code{ftrylockfile} function tries to acquire the internal locking
525 object associated with the stream @var{stream} just like
526 @code{flockfile}. But unlike @code{flockfile} this function does not
527 block if the lock is not available. @code{ftrylockfile} returns zero if
528 the lock was successfully acquired. Otherwise the stream is locked by
532 @deftypefun void funlockfile (FILE *@var{stream})
533 @standards{POSIX, stdio.h}
534 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
535 The @code{funlockfile} function releases the internal locking object of
536 the stream @var{stream}. The stream must have been locked before by a
537 call to @code{flockfile} or a successful call of @code{ftrylockfile}.
538 The implicit locking performed by the stream operations do not count.
539 The @code{funlockfile} function does not return an error status and the
540 behavior of a call for a stream which is not locked by the current
544 The following example shows how the functions above can be used to
545 generate an output line atomically even in multi-threaded applications
546 (yes, the same job could be done with one @code{fprintf} call but it is
547 sometimes not possible):
554 fputs ("This is test number ", fp);
555 fprintf (fp, "%d\n", test);
560 Without the explicit locking it would be possible for another thread to
561 use the stream @var{fp} after the @code{fputs} call returns and before
562 @code{fprintf} was called with the result that the number does not
563 follow the word @samp{number}.
565 From this description it might already be clear that the locking objects
566 in streams are no simple mutexes. Since locking the same stream twice
567 in the same thread is allowed the locking objects must be equivalent to
568 recursive mutexes. These mutexes keep track of the owner and the number
569 of times the lock is acquired. The same number of @code{funlockfile}
570 calls by the same threads is necessary to unlock the stream completely.
578 fputs ("in foo\n", fp);
579 /* @r{This is very wrong!!!} */
584 It is important here that the @code{funlockfile} function is only called
585 if the @code{ftrylockfile} function succeeded in locking the stream. It
586 is therefore always wrong to ignore the result of @code{ftrylockfile}.
587 And it makes no sense since otherwise one would use @code{flockfile}.
588 The result of code like that above is that either @code{funlockfile}
589 tries to free a stream that hasn't been locked by the current thread or it
590 frees the stream prematurely. The code should look like this:
596 if (ftrylockfile (fp) == 0)
598 fputs ("in foo\n", fp);
604 Now that we covered why it is necessary to have locking it is
605 necessary to talk about situations when locking is unwanted and what can
606 be done. The locking operations (explicit or implicit) don't come for
607 free. Even if a lock is not taken the cost is not zero. The operations
608 which have to be performed require memory operations that are safe in
609 multi-processor environments. With the many local caches involved in
610 such systems this is quite costly. So it is best to avoid the locking
611 completely if it is not needed -- because the code in question is never
612 used in a context where two or more threads may use a stream at a time.
613 This can be determined most of the time for application code; for
614 library code which can be used in many contexts one should default to be
615 conservative and use locking.
617 There are two basic mechanisms to avoid locking. The first is to use
618 the @code{_unlocked} variants of the stream operations. The POSIX
619 standard defines quite a few of those and @theglibc{} adds a few
620 more. These variants of the functions behave just like the functions
621 with the name without the suffix except that they do not lock the
622 stream. Using these functions is very desirable since they are
623 potentially much faster. This is not only because the locking
624 operation itself is avoided. More importantly, functions like
625 @code{putc} and @code{getc} are very simple and traditionally (before the
626 introduction of threads) were implemented as macros which are very fast
627 if the buffer is not empty. With the addition of locking requirements
628 these functions are no longer implemented as macros since they would
629 expand to too much code.
630 But these macros are still available with the same functionality under the new
631 names @code{putc_unlocked} and @code{getc_unlocked}. This possibly huge
632 difference of speed also suggests the use of the @code{_unlocked}
633 functions even if locking is required. The difference is that the
634 locking then has to be performed in the program:
638 foo (FILE *fp, char *buf)
642 putc_unlocked (*buf++, fp);
647 If in this example the @code{putc} function would be used and the
648 explicit locking would be missing the @code{putc} function would have to
649 acquire the lock in every call, potentially many times depending on when
650 the loop terminates. Writing it the way illustrated above allows the
651 @code{putc_unlocked} macro to be used which means no locking and direct
652 manipulation of the buffer of the stream.
654 A second way to avoid locking is by using a non-standard function which
655 was introduced in Solaris and is available in @theglibc{} as well.
657 @deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type})
658 @standards{GNU, stdio_ext.h}
659 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asulock{}}@acsafe{}}
660 @c Changing the implicit-locking status of a stream while it's in use by
661 @c another thread may cause a lock to be implicitly acquired and not
662 @c released, or vice-versa. This function should probably hold the lock
663 @c while changing this setting, to make sure we don't change it while
664 @c there are any concurrent uses. Meanwhile, callers should acquire the
665 @c lock themselves to be safe, and even concurrent uses with external
666 @c locking will be fine, as long as functions that require external
667 @c locking are not called without holding locks.
669 The @code{__fsetlocking} function can be used to select whether the
670 stream operations will implicitly acquire the locking object of the
671 stream @var{stream}. By default this is done but it can be disabled and
672 reinstated using this function. There are three values defined for the
673 @var{type} parameter.
676 @item FSETLOCKING_INTERNAL
677 The stream @code{stream} will from now on use the default internal
678 locking. Every stream operation with exception of the @code{_unlocked}
679 variants will implicitly lock the stream.
681 @item FSETLOCKING_BYCALLER
682 After the @code{__fsetlocking} function returns, the user is responsible
683 for locking the stream. None of the stream operations will implicitly
684 do this anymore until the state is set back to
685 @code{FSETLOCKING_INTERNAL}.
687 @item FSETLOCKING_QUERY
688 @code{__fsetlocking} only queries the current locking state of the
689 stream. The return value will be @code{FSETLOCKING_INTERNAL} or
690 @code{FSETLOCKING_BYCALLER} depending on the state.
693 The return value of @code{__fsetlocking} is either
694 @code{FSETLOCKING_INTERNAL} or @code{FSETLOCKING_BYCALLER} depending on
695 the state of the stream before the call.
697 This function and the values for the @var{type} parameter are declared
698 in @file{stdio_ext.h}.
701 This function is especially useful when program code has to be used
702 which is written without knowledge about the @code{_unlocked} functions
703 (or if the programmer was too lazy to use them).
705 @node Streams and I18N
706 @section Streams in Internationalized Applications
708 @w{ISO C90} introduced the new type @code{wchar_t} to allow handling
709 larger character sets. What was missing was a possibility to output
710 strings of @code{wchar_t} directly. One had to convert them into
711 multibyte strings using @code{mbstowcs} (there was no @code{mbsrtowcs}
712 yet) and then use the normal stream functions. While this is doable it
713 is very cumbersome since performing the conversions is not trivial and
714 greatly increases program complexity and size.
716 The Unix standard early on (I think in XPG4.2) introduced two additional
717 format specifiers for the @code{printf} and @code{scanf} families of
718 functions. Printing and reading of single wide characters was made
719 possible using the @code{%C} specifier and wide character strings can be
720 handled with @code{%S}. These modifiers behave just like @code{%c} and
721 @code{%s} only that they expect the corresponding argument to have the
722 wide character type and that the wide character and string are
723 transformed into/from multibyte strings before being used.
725 This was a beginning but it is still not good enough. Not always is it
726 desirable to use @code{printf} and @code{scanf}. The other, smaller and
727 faster functions cannot handle wide characters. Second, it is not
728 possible to have a format string for @code{printf} and @code{scanf}
729 consisting of wide characters. The result is that format strings would
730 have to be generated if they have to contain non-basic characters.
734 In the @w{Amendment 1} to @w{ISO C90} a whole new set of functions was
735 added to solve the problem. Most of the stream functions got a
736 counterpart which take a wide character or wide character string instead
737 of a character or string respectively. The new functions operate on the
738 same streams (like @code{stdout}). This is different from the model of
739 the C++ runtime library where separate streams for wide and normal I/O
742 @cindex orientation, stream
743 @cindex stream orientation
744 Being able to use the same stream for wide and normal operations comes
745 with a restriction: a stream can be used either for wide operations or
746 for normal operations. Once it is decided there is no way back. Only a
747 call to @code{freopen} or @code{freopen64} can reset the
748 @dfn{orientation}. The orientation can be decided in three ways:
752 If any of the normal character functions are used (this includes the
753 @code{fread} and @code{fwrite} functions) the stream is marked as not
757 If any of the wide character functions are used the stream is marked as
761 The @code{fwide} function can be used to set the orientation either way.
764 It is important to never mix the use of wide and not wide operations on
765 a stream. There are no diagnostics issued. The application behavior
766 will simply be strange or the application will simply crash. The
767 @code{fwide} function can help avoid this.
769 @deftypefun int fwide (FILE *@var{stream}, int @var{mode})
770 @standards{ISO, wchar.h}
771 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{}}}
772 @c Querying is always safe, but changing the stream when it's in use
773 @c upthread may be problematic. Like most lock-acquiring functions,
774 @c this one may leak the lock if canceled.
776 The @code{fwide} function can be used to set and query the state of the
777 orientation of the stream @var{stream}. If the @var{mode} parameter has
778 a positive value the streams get wide oriented, for negative values
779 narrow oriented. It is not possible to overwrite previous orientations
780 with @code{fwide}. I.e., if the stream @var{stream} was already
781 oriented before the call nothing is done.
783 If @var{mode} is zero the current orientation state is queried and
786 The @code{fwide} function returns a negative value, zero, or a positive
787 value if the stream is narrow, not at all, or wide oriented
790 This function was introduced in @w{Amendment 1} to @w{ISO C90} and is
791 declared in @file{wchar.h}.
794 It is generally a good idea to orient a stream as early as possible.
795 This can prevent surprise especially for the standard streams
796 @code{stdin}, @code{stdout}, and @code{stderr}. If some library
797 function in some situations uses one of these streams and this use
798 orients the stream in a different way the rest of the application
799 expects it one might end up with hard to reproduce errors. Remember
800 that no errors are signal if the streams are used incorrectly. Leaving
801 a stream unoriented after creation is normally only necessary for
802 library functions which create streams which can be used in different
805 When writing code which uses streams and which can be used in different
806 contexts it is important to query the orientation of the stream before
807 using it (unless the rules of the library interface demand a specific
808 orientation). The following little, silly function illustrates this.
814 if (fwide (fp, 0) > 0)
815 /* @r{Positive return value means wide orientation.} */
822 Note that in this case the function @code{print_f} decides about the
823 orientation of the stream if it was unoriented before (will not happen
824 if the advice above is followed).
826 The encoding used for the @code{wchar_t} values is unspecified and the
827 user must not make any assumptions about it. For I/O of @code{wchar_t}
828 values this means that it is impossible to write these values directly
829 to the stream. This is not what follows from the @w{ISO C} locale model
830 either. What happens instead is that the bytes read from or written to
831 the underlying media are first converted into the internal encoding
832 chosen by the implementation for @code{wchar_t}. The external encoding
833 is determined by the @code{LC_CTYPE} category of the current locale or
834 by the @samp{ccs} part of the mode specification given to @code{fopen},
835 @code{fopen64}, @code{freopen}, or @code{freopen64}. How and when the
836 conversion happens is unspecified and it happens invisibly to the user.
838 Since a stream is created in the unoriented state it has at that point
839 no conversion associated with it. The conversion which will be used is
840 determined by the @code{LC_CTYPE} category selected at the time the
841 stream is oriented. If the locales are changed at the runtime this
842 might produce surprising results unless one pays attention. This is
843 just another good reason to orient the stream explicitly as soon as
844 possible, perhaps with a call to @code{fwide}.
847 @section Simple Output by Characters or Lines
849 @cindex writing to a stream, by characters
850 This section describes functions for performing character- and
851 line-oriented output.
853 These narrow stream functions are declared in the header file
854 @file{stdio.h} and the wide stream functions in @file{wchar.h}.
858 @deftypefun int fputc (int @var{c}, FILE *@var{stream})
859 @standards{ISO, stdio.h}
860 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
861 @c If the stream is in use when interrupted by a signal, the recursive
862 @c lock won't help ensure the stream is consistent; indeed, if fputc
863 @c gets a signal precisely before the post-incremented _IO_write_ptr
864 @c value is stored, we may overwrite the interrupted write. Conversely,
865 @c depending on compiler optimizations, the incremented _IO_write_ptr
866 @c may be stored before the character is stored in the buffer,
867 @c corrupting the stream if async cancel hits between the two stores.
868 @c There may be other reasons for AS- and AC-unsafety in the overflow
870 The @code{fputc} function converts the character @var{c} to type
871 @code{unsigned char}, and writes it to the stream @var{stream}.
872 @code{EOF} is returned if a write error occurs; otherwise the
873 character @var{c} is returned.
876 @deftypefun wint_t fputwc (wchar_t @var{wc}, FILE *@var{stream})
877 @standards{ISO, wchar.h}
878 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
879 The @code{fputwc} function writes the wide character @var{wc} to the
880 stream @var{stream}. @code{WEOF} is returned if a write error occurs;
881 otherwise the character @var{wc} is returned.
884 @deftypefun int fputc_unlocked (int @var{c}, FILE *@var{stream})
885 @standards{POSIX, stdio.h}
886 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
887 @c The unlocked functions can't possibly satisfy the MT-Safety
888 @c requirements on their own, because they require external locking for
890 The @code{fputc_unlocked} function is equivalent to the @code{fputc}
891 function except that it does not implicitly lock the stream.
894 @deftypefun wint_t fputwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
895 @standards{POSIX, wchar.h}
896 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
897 The @code{fputwc_unlocked} function is equivalent to the @code{fputwc}
898 function except that it does not implicitly lock the stream.
900 This function is a GNU extension.
903 @deftypefun int putc (int @var{c}, FILE *@var{stream})
904 @standards{ISO, stdio.h}
905 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
906 This is just like @code{fputc}, except that most systems implement it as
907 a macro, making it faster. One consequence is that it may evaluate the
908 @var{stream} argument more than once, which is an exception to the
909 general rule for macros. @code{putc} is usually the best function to
910 use for writing a single character.
913 @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream})
914 @standards{ISO, wchar.h}
915 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
916 This is just like @code{fputwc}, except that it can be implement as
917 a macro, making it faster. One consequence is that it may evaluate the
918 @var{stream} argument more than once, which is an exception to the
919 general rule for macros. @code{putwc} is usually the best function to
920 use for writing a single wide character.
923 @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})
924 @standards{POSIX, stdio.h}
925 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
926 The @code{putc_unlocked} function is equivalent to the @code{putc}
927 function except that it does not implicitly lock the stream.
930 @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
931 @standards{GNU, wchar.h}
932 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
933 The @code{putwc_unlocked} function is equivalent to the @code{putwc}
934 function except that it does not implicitly lock the stream.
936 This function is a GNU extension.
939 @deftypefun int putchar (int @var{c})
940 @standards{ISO, stdio.h}
941 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
942 The @code{putchar} function is equivalent to @code{putc} with
943 @code{stdout} as the value of the @var{stream} argument.
946 @deftypefun wint_t putwchar (wchar_t @var{wc})
947 @standards{ISO, wchar.h}
948 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
949 The @code{putwchar} function is equivalent to @code{putwc} with
950 @code{stdout} as the value of the @var{stream} argument.
953 @deftypefun int putchar_unlocked (int @var{c})
954 @standards{POSIX, stdio.h}
955 @safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
956 The @code{putchar_unlocked} function is equivalent to the @code{putchar}
957 function except that it does not implicitly lock the stream.
960 @deftypefun wint_t putwchar_unlocked (wchar_t @var{wc})
961 @standards{GNU, wchar.h}
962 @safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
963 The @code{putwchar_unlocked} function is equivalent to the @code{putwchar}
964 function except that it does not implicitly lock the stream.
966 This function is a GNU extension.
969 @deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
970 @standards{ISO, stdio.h}
971 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
972 The function @code{fputs} writes the string @var{s} to the stream
973 @var{stream}. The terminating null character is not written.
974 This function does @emph{not} add a newline character, either.
975 It outputs only the characters in the string.
977 This function returns @code{EOF} if a write error occurs, and otherwise
978 a non-negative value.
983 fputs ("Are ", stdout);
984 fputs ("you ", stdout);
985 fputs ("hungry?\n", stdout);
989 outputs the text @samp{Are you hungry?} followed by a newline.
992 @deftypefun int fputws (const wchar_t *@var{ws}, FILE *@var{stream})
993 @standards{ISO, wchar.h}
994 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
995 The function @code{fputws} writes the wide character string @var{ws} to
996 the stream @var{stream}. The terminating null character is not written.
997 This function does @emph{not} add a newline character, either. It
998 outputs only the characters in the string.
1000 This function returns @code{WEOF} if a write error occurs, and otherwise
1001 a non-negative value.
1004 @deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream})
1005 @standards{GNU, stdio.h}
1006 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1007 The @code{fputs_unlocked} function is equivalent to the @code{fputs}
1008 function except that it does not implicitly lock the stream.
1010 This function is a GNU extension.
1013 @deftypefun int fputws_unlocked (const wchar_t *@var{ws}, FILE *@var{stream})
1014 @standards{GNU, wchar.h}
1015 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1016 The @code{fputws_unlocked} function is equivalent to the @code{fputws}
1017 function except that it does not implicitly lock the stream.
1019 This function is a GNU extension.
1022 @deftypefun int puts (const char *@var{s})
1023 @standards{ISO, stdio.h}
1024 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1025 The @code{puts} function writes the string @var{s} to the stream
1026 @code{stdout} followed by a newline. The terminating null character of
1027 the string is not written. (Note that @code{fputs} does @emph{not}
1028 write a newline as this function does.)
1030 @code{puts} is the most convenient function for printing simple
1031 messages. For example:
1034 puts ("This is a message.");
1038 outputs the text @samp{This is a message.} followed by a newline.
1041 @deftypefun int putw (int @var{w}, FILE *@var{stream})
1042 @standards{SVID, stdio.h}
1043 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1044 This function writes the word @var{w} (that is, an @code{int}) to
1045 @var{stream}. It is provided for compatibility with SVID, but we
1046 recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
1049 @node Character Input
1050 @section Character Input
1052 @cindex reading from a stream, by characters
1053 This section describes functions for performing character-oriented
1054 input. These narrow stream functions are declared in the header file
1055 @file{stdio.h} and the wide character functions are declared in
1060 These functions return an @code{int} or @code{wint_t} value (for narrow
1061 and wide stream functions respectively) that is either a character of
1062 input, or the special value @code{EOF}/@code{WEOF} (usually -1). For
1063 the narrow stream functions it is important to store the result of these
1064 functions in a variable of type @code{int} instead of @code{char}, even
1065 when you plan to use it only as a character. Storing @code{EOF} in a
1066 @code{char} variable truncates its value to the size of a character, so
1067 that it is no longer distinguishable from the valid character
1068 @samp{(char) -1}. So always use an @code{int} for the result of
1069 @code{getc} and friends, and check for @code{EOF} after the call; once
1070 you've verified that the result is not @code{EOF}, you can be sure that
1071 it will fit in a @samp{char} variable without loss of information.
1073 @deftypefun int fgetc (FILE *@var{stream})
1074 @standards{ISO, stdio.h}
1075 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1076 @c Same caveats as fputc, but instead of losing a write in case of async
1077 @c signals, we may read the same character more than once, and the
1078 @c stream may be left in odd states due to cancellation in the underflow
1080 This function reads the next character as an @code{unsigned char} from
1081 the stream @var{stream} and returns its value, converted to an
1082 @code{int}. If an end-of-file condition or read error occurs,
1083 @code{EOF} is returned instead.
1086 @deftypefun wint_t fgetwc (FILE *@var{stream})
1087 @standards{ISO, wchar.h}
1088 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1089 This function reads the next wide character from the stream @var{stream}
1090 and returns its value. If an end-of-file condition or read error
1091 occurs, @code{WEOF} is returned instead.
1094 @deftypefun int fgetc_unlocked (FILE *@var{stream})
1095 @standards{POSIX, stdio.h}
1096 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1097 The @code{fgetc_unlocked} function is equivalent to the @code{fgetc}
1098 function except that it does not implicitly lock the stream.
1101 @deftypefun wint_t fgetwc_unlocked (FILE *@var{stream})
1102 @standards{GNU, wchar.h}
1103 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1104 The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc}
1105 function except that it does not implicitly lock the stream.
1107 This function is a GNU extension.
1110 @deftypefun int getc (FILE *@var{stream})
1111 @standards{ISO, stdio.h}
1112 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1113 This is just like @code{fgetc}, except that it is permissible (and
1114 typical) for it to be implemented as a macro that evaluates the
1115 @var{stream} argument more than once. @code{getc} is often highly
1116 optimized, so it is usually the best function to use to read a single
1120 @deftypefun wint_t getwc (FILE *@var{stream})
1121 @standards{ISO, wchar.h}
1122 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1123 This is just like @code{fgetwc}, except that it is permissible for it to
1124 be implemented as a macro that evaluates the @var{stream} argument more
1125 than once. @code{getwc} can be highly optimized, so it is usually the
1126 best function to use to read a single wide character.
1129 @deftypefun int getc_unlocked (FILE *@var{stream})
1130 @standards{POSIX, stdio.h}
1131 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1132 The @code{getc_unlocked} function is equivalent to the @code{getc}
1133 function except that it does not implicitly lock the stream.
1136 @deftypefun wint_t getwc_unlocked (FILE *@var{stream})
1137 @standards{GNU, wchar.h}
1138 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1139 The @code{getwc_unlocked} function is equivalent to the @code{getwc}
1140 function except that it does not implicitly lock the stream.
1142 This function is a GNU extension.
1145 @deftypefun int getchar (void)
1146 @standards{ISO, stdio.h}
1147 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1148 The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
1149 as the value of the @var{stream} argument.
1152 @deftypefun wint_t getwchar (void)
1153 @standards{ISO, wchar.h}
1154 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1155 The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin}
1156 as the value of the @var{stream} argument.
1159 @deftypefun int getchar_unlocked (void)
1160 @standards{POSIX, stdio.h}
1161 @safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1162 The @code{getchar_unlocked} function is equivalent to the @code{getchar}
1163 function except that it does not implicitly lock the stream.
1166 @deftypefun wint_t getwchar_unlocked (void)
1167 @standards{GNU, wchar.h}
1168 @safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1169 The @code{getwchar_unlocked} function is equivalent to the @code{getwchar}
1170 function except that it does not implicitly lock the stream.
1172 This function is a GNU extension.
1175 Here is an example of a function that does input using @code{fgetc}. It
1176 would work just as well using @code{getc} instead, or using
1177 @code{getchar ()} instead of @w{@code{fgetc (stdin)}}. The code would
1178 also work the same for the wide character stream functions.
1182 y_or_n_p (const char *question)
1184 fputs (question, stdout);
1188 /* @r{Write a space to separate answer from question.} */
1189 fputc (' ', stdout);
1190 /* @r{Read the first character of the line.}
1191 @r{This should be the answer character, but might not be.} */
1192 c = tolower (fgetc (stdin));
1194 /* @r{Discard rest of input line.} */
1195 while (c != '\n' && c != EOF)
1197 /* @r{Obey the answer if it was valid.} */
1202 /* @r{Answer was invalid: ask for valid answer.} */
1203 fputs ("Please answer y or n:", stdout);
1208 @deftypefun int getw (FILE *@var{stream})
1209 @standards{SVID, stdio.h}
1210 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1211 This function reads a word (that is, an @code{int}) from @var{stream}.
1212 It's provided for compatibility with SVID. We recommend you use
1213 @code{fread} instead (@pxref{Block Input/Output}). Unlike @code{getc},
1214 any @code{int} value could be a valid result. @code{getw} returns
1215 @code{EOF} when it encounters end-of-file or an error, but there is no
1216 way to distinguish this from an input word with value -1.
1220 @section Line-Oriented Input
1222 Since many programs interpret input on the basis of lines, it is
1223 convenient to have functions to read a line of text from a stream.
1225 Standard C has functions to do this, but they aren't very safe: null
1226 characters and even (for @code{gets}) long lines can confuse them. So
1227 @theglibc{} provides the nonstandard @code{getline} function that
1228 makes it easy to read lines reliably.
1230 Another GNU extension, @code{getdelim}, generalizes @code{getline}. It
1231 reads a delimited record, defined as everything through the next
1232 occurrence of a specified delimiter character.
1234 All these functions are declared in @file{stdio.h}.
1236 @deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
1237 @standards{GNU, stdio.h}
1238 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
1239 @c Besides the usual possibility of getting an inconsistent stream in a
1240 @c signal handler or leaving it inconsistent in case of cancellation,
1241 @c the possibility of leaving a dangling pointer upon cancellation
1242 @c between reallocing the buffer at *lineptr and updating the pointer
1243 @c brings about another case of @acucorrupt.
1244 This function reads an entire line from @var{stream}, storing the text
1245 (including the newline and a terminating null character) in a buffer
1246 and storing the buffer address in @code{*@var{lineptr}}.
1248 Before calling @code{getline}, you should place in @code{*@var{lineptr}}
1249 the address of a buffer @code{*@var{n}} bytes long, allocated with
1250 @code{malloc}. If this buffer is long enough to hold the line,
1251 @code{getline} stores the line in this buffer. Otherwise,
1252 @code{getline} makes the buffer bigger using @code{realloc}, storing the
1253 new buffer address back in @code{*@var{lineptr}} and the increased size
1254 back in @code{*@var{n}}.
1255 @xref{Unconstrained Allocation}.
1257 If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}}
1258 to zero, before the call, then @code{getline} allocates the initial
1259 buffer for you by calling @code{malloc}. This buffer remains allocated
1260 even if @code{getline} encounters errors and is unable to read any bytes.
1262 In either case, when @code{getline} returns, @code{*@var{lineptr}} is
1263 a @code{char *} which points to the text of the line.
1265 When @code{getline} is successful, it returns the number of characters
1266 read (including the newline, but not including the terminating null).
1267 This value enables you to distinguish null characters that are part of
1268 the line from the null character inserted as a terminator.
1270 This function is a GNU extension, but it is the recommended way to read
1271 lines from a stream. The alternative standard functions are unreliable.
1273 If an error occurs or end of file is reached without any bytes read,
1274 @code{getline} returns @code{-1}.
1277 @deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream})
1278 @standards{GNU, stdio.h}
1279 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
1280 @c See the getline @acucorrupt note.
1281 This function is like @code{getline} except that the character which
1282 tells it to stop reading is not necessarily newline. The argument
1283 @var{delimiter} specifies the delimiter character; @code{getdelim} keeps
1284 reading until it sees that character (or end of file).
1286 The text is stored in @var{lineptr}, including the delimiter character
1287 and a terminating null. Like @code{getline}, @code{getdelim} makes
1288 @var{lineptr} bigger if it isn't big enough.
1290 @code{getline} is in fact implemented in terms of @code{getdelim}, just
1295 getline (char **lineptr, size_t *n, FILE *stream)
1297 return getdelim (lineptr, n, '\n', stream);
1302 @deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
1303 @standards{ISO, stdio.h}
1304 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1305 The @code{fgets} function reads characters from the stream @var{stream}
1306 up to and including a newline character and stores them in the string
1307 @var{s}, adding a null character to mark the end of the string. You
1308 must supply @var{count} characters worth of space in @var{s}, but the
1309 number of characters read is at most @var{count} @minus{} 1. The extra
1310 character space is used to hold the null character at the end of the
1313 If the system is already at end of file when you call @code{fgets}, then
1314 the contents of the array @var{s} are unchanged and a null pointer is
1315 returned. A null pointer is also returned if a read error occurs.
1316 Otherwise, the return value is the pointer @var{s}.
1318 @strong{Warning:} If the input data has a null character, you can't tell.
1319 So don't use @code{fgets} unless you know the data cannot contain a null.
1320 Don't use it to read files edited by the user because, if the user inserts
1321 a null character, you should either handle it properly or print a clear
1322 error message. We recommend using @code{getline} instead of @code{fgets}.
1325 @deftypefun {wchar_t *} fgetws (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
1326 @standards{ISO, wchar.h}
1327 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1328 The @code{fgetws} function reads wide characters from the stream
1329 @var{stream} up to and including a newline character and stores them in
1330 the string @var{ws}, adding a null wide character to mark the end of the
1331 string. You must supply @var{count} wide characters worth of space in
1332 @var{ws}, but the number of characters read is at most @var{count}
1333 @minus{} 1. The extra character space is used to hold the null wide
1334 character at the end of the string.
1336 If the system is already at end of file when you call @code{fgetws}, then
1337 the contents of the array @var{ws} are unchanged and a null pointer is
1338 returned. A null pointer is also returned if a read error occurs.
1339 Otherwise, the return value is the pointer @var{ws}.
1341 @strong{Warning:} If the input data has a null wide character (which are
1342 null bytes in the input stream), you can't tell. So don't use
1343 @code{fgetws} unless you know the data cannot contain a null. Don't use
1344 it to read files edited by the user because, if the user inserts a null
1345 character, you should either handle it properly or print a clear error
1347 @comment XXX We need getwline!!!
1350 @deftypefun {char *} fgets_unlocked (char *@var{s}, int @var{count}, FILE *@var{stream})
1351 @standards{GNU, stdio.h}
1352 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1353 The @code{fgets_unlocked} function is equivalent to the @code{fgets}
1354 function except that it does not implicitly lock the stream.
1356 This function is a GNU extension.
1359 @deftypefun {wchar_t *} fgetws_unlocked (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
1360 @standards{GNU, wchar.h}
1361 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1362 The @code{fgetws_unlocked} function is equivalent to the @code{fgetws}
1363 function except that it does not implicitly lock the stream.
1365 This function is a GNU extension.
1368 @deftypefn {Deprecated function} {char *} gets (char *@var{s})
1369 @standards{ISO, stdio.h}
1370 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1371 The function @code{gets} reads characters from the stream @code{stdin}
1372 up to the next newline character, and stores them in the string @var{s}.
1373 The newline character is discarded (note that this differs from the
1374 behavior of @code{fgets}, which copies the newline character into the
1375 string). If @code{gets} encounters a read error or end-of-file, it
1376 returns a null pointer; otherwise it returns @var{s}.
1378 @strong{Warning:} The @code{gets} function is @strong{very dangerous}
1379 because it provides no protection against overflowing the string
1380 @var{s}. @Theglibc{} includes it for compatibility only. You
1381 should @strong{always} use @code{fgets} or @code{getline} instead. To
1382 remind you of this, the linker (if using GNU @code{ld}) will issue a
1383 warning whenever you use @code{gets}.
1388 @cindex peeking at input
1389 @cindex unreading characters
1390 @cindex pushing input back
1392 In parser programs it is often useful to examine the next character in
1393 the input stream without removing it from the stream. This is called
1394 ``peeking ahead'' at the input because your program gets a glimpse of
1395 the input it will read next.
1397 Using stream I/O, you can peek ahead at input by first reading it and
1398 then @dfn{unreading} it (also called @dfn{pushing it back} on the stream).
1399 Unreading a character makes it available to be input again from the stream,
1400 by the next call to @code{fgetc} or other input function on that stream.
1403 * Unreading Idea:: An explanation of unreading with pictures.
1404 * How Unread:: How to call @code{ungetc} to do unreading.
1407 @node Unreading Idea
1408 @subsection What Unreading Means
1410 Here is a pictorial explanation of unreading. Suppose you have a
1411 stream reading a file that contains just six characters, the letters
1412 @samp{foobar}. Suppose you have read three characters so far. The
1413 situation looks like this:
1421 so the next input character will be @samp{b}.
1423 @c @group Invalid outside @example
1424 If instead of reading @samp{b} you unread the letter @samp{o}, you get a
1425 situation like this:
1435 so that the next input characters will be @samp{o} and @samp{b}.
1439 If you unread @samp{9} instead of @samp{o}, you get this situation:
1449 so that the next input characters will be @samp{9} and @samp{b}.
1453 @subsection Using @code{ungetc} To Do Unreading
1455 The function to unread a character is called @code{ungetc}, because it
1456 reverses the action of @code{getc}.
1458 @deftypefun int ungetc (int @var{c}, FILE *@var{stream})
1459 @standards{ISO, stdio.h}
1460 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1461 The @code{ungetc} function pushes back the character @var{c} onto the
1462 input stream @var{stream}. So the next input from @var{stream} will
1463 read @var{c} before anything else.
1465 If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
1466 @code{EOF}. This lets you call @code{ungetc} with the return value of
1467 @code{getc} without needing to check for an error from @code{getc}.
1469 The character that you push back doesn't have to be the same as the last
1470 character that was actually read from the stream. In fact, it isn't
1471 necessary to actually read any characters from the stream before
1472 unreading them with @code{ungetc}! But that is a strange way to write a
1473 program; usually @code{ungetc} is used only to unread a character that
1474 was just read from the same stream. @Theglibc{} supports this
1475 even on files opened in binary mode, but other systems might not.
1477 @Theglibc{} only supports one character of pushback---in other
1478 words, it does not work to call @code{ungetc} twice without doing input
1479 in between. Other systems might let you push back multiple characters;
1480 then reading from the stream retrieves the characters in the reverse
1481 order that they were pushed.
1483 Pushing back characters doesn't alter the file; only the internal
1484 buffering for the stream is affected. If a file positioning function
1485 (such as @code{fseek}, @code{fseeko} or @code{rewind}; @pxref{File
1486 Positioning}) is called, any pending pushed-back characters are
1489 Unreading a character on a stream that is at end of file clears the
1490 end-of-file indicator for the stream, because it makes the character of
1491 input available. After you read that character, trying to read again
1492 will encounter end of file.
1495 @deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream})
1496 @standards{ISO, wchar.h}
1497 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1498 The @code{ungetwc} function behaves just like @code{ungetc} just that it
1499 pushes back a wide character.
1502 Here is an example showing the use of @code{getc} and @code{ungetc} to
1503 skip over whitespace characters. When this function reaches a
1504 non-whitespace character, it unreads that character to be seen again on
1505 the next read operation on the stream.
1512 skip_whitespace (FILE *stream)
1516 /* @r{No need to check for @code{EOF} because it is not}
1517 @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.} */
1519 while (isspace (c));
1524 @node Block Input/Output
1525 @section Block Input/Output
1527 This section describes how to do input and output operations on blocks
1528 of data. You can use these functions to read and write binary data, as
1529 well as to read and write text in fixed-size blocks instead of by
1530 characters or lines.
1531 @cindex binary I/O to a stream
1532 @cindex block I/O to a stream
1533 @cindex reading from a stream, by blocks
1534 @cindex writing to a stream, by blocks
1536 Binary files are typically used to read and write blocks of data in the
1537 same format as is used to represent the data in a running program. In
1538 other words, arbitrary blocks of memory---not just character or string
1539 objects---can be written to a binary file, and meaningfully read in
1540 again by the same program.
1542 Storing data in binary form is often considerably more efficient than
1543 using the formatted I/O functions. Also, for floating-point numbers,
1544 the binary form avoids possible loss of precision in the conversion
1545 process. On the other hand, binary files can't be examined or modified
1546 easily using many standard file utilities (such as text editors), and
1547 are not portable between different implementations of the language, or
1548 different kinds of computers.
1550 These functions are declared in @file{stdio.h}.
1553 @deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1554 @standards{ISO, stdio.h}
1555 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1556 This function reads up to @var{count} objects of size @var{size} into
1557 the array @var{data}, from the stream @var{stream}. It returns the
1558 number of objects actually read, which might be less than @var{count} if
1559 a read error occurs or the end of the file is reached. This function
1560 returns a value of zero (and doesn't read anything) if either @var{size}
1561 or @var{count} is zero.
1563 If @code{fread} encounters end of file in the middle of an object, it
1564 returns the number of complete objects read, and discards the partial
1565 object. Therefore, the stream remains at the actual end of the file.
1568 @deftypefun size_t fread_unlocked (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1569 @standards{GNU, stdio.h}
1570 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1571 The @code{fread_unlocked} function is equivalent to the @code{fread}
1572 function except that it does not implicitly lock the stream.
1574 This function is a GNU extension.
1577 @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1578 @standards{ISO, stdio.h}
1579 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1580 This function writes up to @var{count} objects of size @var{size} from
1581 the array @var{data}, to the stream @var{stream}. The return value is
1582 normally @var{count}, if the call succeeds. Any other value indicates
1583 some sort of error, such as running out of space.
1586 @deftypefun size_t fwrite_unlocked (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1587 @standards{GNU, stdio.h}
1588 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1589 The @code{fwrite_unlocked} function is equivalent to the @code{fwrite}
1590 function except that it does not implicitly lock the stream.
1592 This function is a GNU extension.
1595 @node Formatted Output
1596 @section Formatted Output
1598 @cindex format string, for @code{printf}
1599 @cindex template, for @code{printf}
1600 @cindex formatted output to a stream
1601 @cindex writing to a stream, formatted
1602 The functions described in this section (@code{printf} and related
1603 functions) provide a convenient way to perform formatted output. You
1604 call @code{printf} with a @dfn{format string} or @dfn{template string}
1605 that specifies how to format the values of the remaining arguments.
1607 Unless your program is a filter that specifically performs line- or
1608 character-oriented processing, using @code{printf} or one of the other
1609 related functions described in this section is usually the easiest and
1610 most concise way to perform output. These functions are especially
1611 useful for printing error messages, tables of data, and the like.
1614 * Formatted Output Basics:: Some examples to get you started.
1615 * Output Conversion Syntax:: General syntax of conversion
1617 * Table of Output Conversions:: Summary of output conversions and
1619 * Integer Conversions:: Details about formatting of integers.
1620 * Floating-Point Conversions:: Details about formatting of
1621 floating-point numbers.
1622 * Other Output Conversions:: Details about formatting of strings,
1623 characters, pointers, and the like.
1624 * Formatted Output Functions:: Descriptions of the actual functions.
1625 * Dynamic Output:: Functions that allocate memory for the output.
1626 * Variable Arguments Output:: @code{vprintf} and friends.
1627 * Parsing a Template String:: What kinds of args does a given template
1629 * Example of Parsing:: Sample program using @code{parse_printf_format}.
1632 @node Formatted Output Basics
1633 @subsection Formatted Output Basics
1635 The @code{printf} function can be used to print any number of arguments.
1636 The template string argument you supply in a call provides
1637 information not only about the number of additional arguments, but also
1638 about their types and what style should be used for printing them.
1640 Ordinary characters in the template string are simply written to the
1641 output stream as-is, while @dfn{conversion specifications} introduced by
1642 a @samp{%} character in the template cause subsequent arguments to be
1643 formatted and written to the output stream. For example,
1644 @cindex conversion specifications (@code{printf})
1648 char filename[] = "foo.txt";
1649 printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
1654 produces output like
1657 Processing of `foo.txt' is 37% finished.
1661 This example shows the use of the @samp{%d} conversion to specify that
1662 an @code{int} argument should be printed in decimal notation, the
1663 @samp{%s} conversion to specify printing of a string argument, and
1664 the @samp{%%} conversion to print a literal @samp{%} character.
1666 There are also conversions for printing an integer argument as an
1667 unsigned value in binary, octal, decimal, or hexadecimal radix
1668 (@samp{%b}, @samp{%o}, @samp{%u}, or @samp{%x}, respectively); or as a
1669 character value (@samp{%c}).
1671 Floating-point numbers can be printed in normal, fixed-point notation
1672 using the @samp{%f} conversion or in exponential notation using the
1673 @samp{%e} conversion. The @samp{%g} conversion uses either @samp{%e}
1674 or @samp{%f} format, depending on what is more appropriate for the
1675 magnitude of the particular number.
1677 You can control formatting more precisely by writing @dfn{modifiers}
1678 between the @samp{%} and the character that indicates which conversion
1679 to apply. These slightly alter the ordinary behavior of the conversion.
1680 For example, most conversion specifications permit you to specify a
1681 minimum field width and a flag indicating whether you want the result
1682 left- or right-justified within the field.
1684 The specific flags and modifiers that are permitted and their
1685 interpretation vary depending on the particular conversion. They're all
1686 described in more detail in the following sections. Don't worry if this
1687 all seems excessively complicated at first; you can almost always get
1688 reasonable free-format output without using any of the modifiers at all.
1689 The modifiers are mostly used to make the output look ``prettier'' in
1692 @node Output Conversion Syntax
1693 @subsection Output Conversion Syntax
1695 This section provides details about the precise syntax of conversion
1696 specifications that can appear in a @code{printf} template
1699 Characters in the template string that are not part of a conversion
1700 specification are printed as-is to the output stream. Multibyte
1701 character sequences (@pxref{Character Set Handling}) are permitted in a
1704 The conversion specifications in a @code{printf} template string have
1708 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion}
1715 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} . @r{*} @r{[} @var{param-no} @r{$]} @var{type} @var{conversion}
1718 For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-}
1719 is a flag, @samp{10} specifies the field width, the precision is
1720 @samp{8}, the letter @samp{l} is a type modifier, and @samp{d} specifies
1721 the conversion style. (This particular type specifier says to
1722 print a @code{long int} argument in decimal notation, with a minimum of
1723 8 digits left-justified in a field at least 10 characters wide.)
1725 In more detail, output conversion specifications consist of an
1726 initial @samp{%} character followed in sequence by:
1730 An optional specification of the parameter used for this format.
1731 Normally the parameters to the @code{printf} function are assigned to the
1732 formats in the order of appearance in the format string. But in some
1733 situations (such as message translation) this is not desirable and this
1734 extension allows an explicit parameter to be specified.
1736 The @var{param-no} parts of the format must be integers in the range of
1737 1 to the maximum number of arguments present to the function call. Some
1738 implementations limit this number to a certain upper bound. The exact
1739 limit can be retrieved by the following constant.
1741 @defvr Macro NL_ARGMAX
1742 The value of @code{NL_ARGMAX} is the maximum value allowed for the
1743 specification of a positional parameter in a @code{printf} call. The
1744 actual value in effect at runtime can be retrieved by using
1745 @code{sysconf} using the @code{_SC_NL_ARGMAX} parameter @pxref{Sysconf
1748 Some systems have a quite low limit such as @math{9} for @w{System V}
1749 systems. @Theglibc{} has no real limit.
1752 If any of the formats has a specification for the parameter position all
1753 of them in the format string shall have one. Otherwise the behavior is
1757 Zero or more @dfn{flag characters} that modify the normal behavior of
1758 the conversion specification.
1759 @cindex flag character (@code{printf})
1762 An optional decimal integer specifying the @dfn{minimum field width}.
1763 If the normal conversion produces fewer characters than this, the field
1764 is padded with spaces to the specified width. This is a @emph{minimum}
1765 value; if the normal conversion produces more characters than this, the
1766 field is @emph{not} truncated. Normally, the output is right-justified
1768 @cindex minimum field width (@code{printf})
1770 You can also specify a field width of @samp{*}. This means that the
1771 next argument in the argument list (before the actual value to be
1772 printed) is used as the field width. The value must be an @code{int}.
1773 If the value is negative, this means to set the @samp{-} flag (see
1774 below) and to use the absolute value as the field width.
1777 An optional @dfn{precision} to specify the number of digits to be
1778 written for the numeric conversions. If the precision is specified, it
1779 consists of a period (@samp{.}) followed optionally by a decimal integer
1780 (which defaults to zero if omitted).
1781 @cindex precision (@code{printf})
1783 You can also specify a precision of @samp{*}. This means that the next
1784 argument in the argument list (before the actual value to be printed) is
1785 used as the precision. The value must be an @code{int}, and is ignored
1786 if it is negative. If you specify @samp{*} for both the field width and
1787 precision, the field width argument precedes the precision argument.
1788 Other C library versions may not recognize this syntax.
1791 An optional @dfn{type modifier character}, which is used to specify the
1792 data type of the corresponding argument if it differs from the default
1793 type. (For example, the integer conversions assume a type of @code{int},
1794 but you can specify @samp{h}, @samp{l}, or @samp{L} for other integer
1796 @cindex type modifier character (@code{printf})
1799 A character that specifies the conversion to be applied.
1802 The exact options that are permitted and how they are interpreted vary
1803 between the different conversion specifiers. See the descriptions of the
1804 individual conversions for information about the particular options that
1807 With the @samp{-Wformat} option, the GNU C compiler checks calls to
1808 @code{printf} and related functions. It examines the format string and
1809 verifies that the correct number and types of arguments are supplied.
1810 There is also a GNU C syntax to tell the compiler that a function you
1811 write uses a @code{printf}-style format string.
1812 @xref{Function Attributes, , Declaring Attributes of Functions,
1813 gcc, Using GNU CC}, for more information.
1815 @node Table of Output Conversions
1816 @subsection Table of Output Conversions
1817 @cindex output conversions, for @code{printf}
1819 Here is a table summarizing what all the different conversions do:
1822 @item @samp{%d}, @samp{%i}
1823 Print an integer as a signed decimal number. @xref{Integer
1824 Conversions}, for details. @samp{%d} and @samp{%i} are synonymous for
1825 output, but are different when used with @code{scanf} for input
1826 (@pxref{Table of Input Conversions}).
1828 @item @samp{%b}, @samp{%B}
1829 Print an integer as an unsigned binary number. @samp{%b} uses
1830 lower-case @samp{b} with the @samp{#} flag and @samp{%B} uses
1831 upper-case. @samp{%b} is an ISO C2X feature; @samp{%B} is an
1832 optional ISO C2X feature. @xref{Integer Conversions}, for
1836 Print an integer as an unsigned octal number. @xref{Integer
1837 Conversions}, for details.
1840 Print an integer as an unsigned decimal number. @xref{Integer
1841 Conversions}, for details.
1843 @item @samp{%x}, @samp{%X}
1844 Print an integer as an unsigned hexadecimal number. @samp{%x} uses
1845 lower-case letters and @samp{%X} uses upper-case. @xref{Integer
1846 Conversions}, for details.
1848 @item @samp{%f}, @samp{%F}
1849 Print a floating-point number in normal (fixed-point) notation.
1850 @samp{%f} uses lower-case letters and @samp{%F} uses upper-case.
1851 @xref{Floating-Point Conversions}, for details.
1853 @item @samp{%e}, @samp{%E}
1854 Print a floating-point number in exponential notation. @samp{%e} uses
1855 lower-case letters and @samp{%E} uses upper-case. @xref{Floating-Point
1856 Conversions}, for details.
1858 @item @samp{%g}, @samp{%G}
1859 Print a floating-point number in either normal or exponential notation,
1860 whichever is more appropriate for its magnitude. @samp{%g} uses
1861 lower-case letters and @samp{%G} uses upper-case. @xref{Floating-Point
1862 Conversions}, for details.
1864 @item @samp{%a}, @samp{%A}
1865 Print a floating-point number in a hexadecimal fractional notation with
1866 the exponent to base 2 represented in decimal digits. @samp{%a} uses
1867 lower-case letters and @samp{%A} uses upper-case. @xref{Floating-Point
1868 Conversions}, for details.
1871 Print a single character. @xref{Other Output Conversions}.
1874 This is an alias for @samp{%lc} which is supported for compatibility
1875 with the Unix standard.
1878 Print a string. @xref{Other Output Conversions}.
1881 This is an alias for @samp{%ls} which is supported for compatibility
1882 with the Unix standard.
1885 Print the value of a pointer. @xref{Other Output Conversions}.
1888 Get the number of characters printed so far. @xref{Other Output Conversions}.
1889 Note that this conversion specification never produces any output.
1892 Print the string corresponding to the value of @code{errno}.
1893 (This is a GNU extension.)
1894 @xref{Other Output Conversions}.
1897 Print a literal @samp{%} character. @xref{Other Output Conversions}.
1900 If the syntax of a conversion specification is invalid, unpredictable
1901 things will happen, so don't do this. If there aren't enough function
1902 arguments provided to supply values for all the conversion
1903 specifications in the template string, or if the arguments are not of
1904 the correct types, the results are unpredictable. If you supply more
1905 arguments than conversion specifications, the extra argument values are
1906 simply ignored; this is sometimes useful.
1908 @node Integer Conversions
1909 @subsection Integer Conversions
1911 This section describes the options for the @samp{%d}, @samp{%i},
1912 @samp{%b}, @samp{%B}, @samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
1913 specifications. These conversions print integers in various formats.
1915 The @samp{%d} and @samp{%i} conversion specifications both print an
1916 @code{int} argument as a signed decimal number; while @samp{%b}, @samp{%o},
1917 @samp{%u}, and @samp{%x} print the argument as an unsigned binary, octal,
1918 decimal, or hexadecimal number (respectively). The @samp{%X} conversion
1919 specification is just like @samp{%x} except that it uses the characters
1920 @samp{ABCDEF} as digits instead of @samp{abcdef}. The @samp{%B}
1921 conversion specification is just like @samp{%b} except that, with the
1922 @samp{#} flag, the output starts with @samp{0B} instead of @samp{0b}.
1924 The following flags are meaningful:
1928 Left-justify the result in the field (instead of the normal
1929 right-justification).
1932 For the signed @samp{%d} and @samp{%i} conversions, print a
1933 plus sign if the value is positive.
1936 For the signed @samp{%d} and @samp{%i} conversions, if the result
1937 doesn't start with a plus or minus sign, prefix it with a space
1938 character instead. Since the @samp{+} flag ensures that the result
1939 includes a sign, this flag is ignored if you supply both of them.
1942 For the @samp{%o} conversion, this forces the leading digit to be
1943 @samp{0}, as if by increasing the precision. For @samp{%x} or
1944 @samp{%X}, this prefixes a leading @samp{0x} or @samp{0X}
1945 (respectively) to the result. For @samp{%b} or @samp{%B}, this
1946 prefixes a leading @samp{0b} or @samp{0B} (respectively)
1947 to the result. This doesn't do anything useful for the @samp{%d},
1948 @samp{%i}, or @samp{%u} conversions. Using this flag produces output
1949 which can be parsed by the @code{strtoul} function (@pxref{Parsing of
1950 Integers}) and @code{scanf} with the @samp{%i} conversion
1951 (@pxref{Numeric Input Conversions}).
1953 For the @samp{%m} conversion, print an error constant or decimal error
1954 number, instead of a (possibly translated) error message.
1957 Separate the digits into groups as specified by the locale specified for
1958 the @code{LC_NUMERIC} category; @pxref{General Numeric}. This flag is a
1962 Pad the field with zeros instead of spaces. The zeros are placed after
1963 any indication of sign or base. This flag is ignored if the @samp{-}
1964 flag is also specified, or if a precision is specified.
1967 If a precision is supplied, it specifies the minimum number of digits to
1968 appear; leading zeros are produced if necessary. If you don't specify a
1969 precision, the number is printed with as many digits as it needs. If
1970 you convert a value of zero with an explicit precision of zero, then no
1971 characters at all are produced.
1973 Without a type modifier, the corresponding argument is treated as an
1974 @code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
1975 @code{unsigned int} (for the unsigned conversions @samp{%b},
1976 @samp{%B}, @samp{%o}, @samp{%u},
1977 @samp{%x}, and @samp{%X}). Recall that since @code{printf} and friends
1978 are variadic, any @code{char} and @code{short} arguments are
1979 automatically converted to @code{int} by the default argument
1980 promotions. For arguments of other integer types, you can use these
1985 Specifies that the argument is a @code{signed char} or @code{unsigned
1986 char}, as appropriate. A @code{char} argument is converted to an
1987 @code{int} or @code{unsigned int} by the default argument promotions
1988 anyway, but the @samp{hh} modifier says to convert it back to a
1991 This modifier was introduced in @w{ISO C99}.
1994 Specifies that the argument is a @code{short int} or @code{unsigned
1995 short int}, as appropriate. A @code{short} argument is converted to an
1996 @code{int} or @code{unsigned int} by the default argument promotions
1997 anyway, but the @samp{h} modifier says to convert it back to a
2001 Specifies that the argument is a @code{intmax_t} or @code{uintmax_t}, as
2004 This modifier was introduced in @w{ISO C99}.
2007 Specifies that the argument is a @code{long int} or @code{unsigned long
2008 int}, as appropriate. Two @samp{l} characters are like the @samp{L}
2011 If used with @samp{%c} or @samp{%s} the corresponding parameter is
2012 considered as a wide character or wide character string respectively.
2013 This use of @samp{l} was introduced in @w{Amendment 1} to @w{ISO C90}.
2018 Specifies that the argument is a @code{long long int}. (This type is
2019 an extension supported by the GNU C compiler. On systems that don't
2020 support extra-long integers, this is the same as @code{long int}.)
2022 The @samp{q} modifier is another name for the same thing, which comes
2023 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
2027 Specifies that the argument is a @code{ptrdiff_t}.
2029 This modifier was introduced in @w{ISO C99}.
2032 Specifies that the argument is a @code{int@var{n}_t} or
2033 @code{int_least@var{n}_t} (which are the same type), for conversions
2034 taking signed integers, or @code{uint@var{n}_t} or
2035 @code{uint_least@var{n}_t} (which are the same type), for conversions
2036 taking unsigned integers. If the type is narrower than @code{int},
2037 the promoted argument is converted back to the specified type.
2039 This modifier was introduced in @w{ISO C2X}.
2042 Specifies that the argument is a @code{int_fast@var{n}_t} or
2043 @code{uint_fast@var{n}_t}, as appropriate. If the type is narrower
2044 than @code{int}, the promoted argument is converted back to the
2047 This modifier was introduced in @w{ISO C2X}.
2051 Specifies that the argument is a @code{size_t}.
2053 @samp{z} was introduced in @w{ISO C99}. @samp{Z} is a GNU extension
2054 predating this addition and should not be used in new code.
2057 Here is an example. Using the template string:
2060 "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
2064 to print numbers using the different options for the @samp{%d}
2065 conversion gives results like:
2068 | 0|0 | +0|+0 | 0|00000| | 00|0|
2069 | 1|1 | +1|+1 | 1|00001| 1| 01|1|
2070 | -1|-1 | -1|-1 | -1|-0001| -1| -01|-1|
2071 |100000|100000|+100000|+100000| 100000|100000|100000|100000|100000|
2074 In particular, notice what happens in the last case where the number
2075 is too large to fit in the minimum field width specified.
2077 Here are some more examples showing how unsigned integers print under
2078 various format options, using the template string:
2081 "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
2085 | 0| 0| 0| 0| 0| 0| 0| 00000000|
2086 | 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001|
2087 |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
2091 @node Floating-Point Conversions
2092 @subsection Floating-Point Conversions
2094 This section discusses the conversion specifications for floating-point
2095 numbers: the @samp{%f}, @samp{%F}, @samp{%e}, @samp{%E}, @samp{%g}, and
2096 @samp{%G} conversions.
2098 The @samp{%f} and @samp{%F} conversions print their argument in fixed-point
2099 notation, producing output of the form
2100 @w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
2101 where the number of digits following the decimal point is controlled
2102 by the precision you specify.
2104 The @samp{%e} conversion prints its argument in exponential notation,
2105 producing output of the form
2106 @w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}.
2107 Again, the number of digits following the decimal point is controlled by
2108 the precision. The exponent always contains at least two digits. The
2109 @samp{%E} conversion is similar but the exponent is marked with the letter
2110 @samp{E} instead of @samp{e}.
2112 The @samp{%g} and @samp{%G} conversions print the argument in the style
2113 of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
2114 than -4 or greater than or equal to the precision; otherwise they use
2115 the @samp{%f} or @samp{%F} style. A precision of @code{0}, is taken as 1.
2116 Trailing zeros are removed from the fractional portion of the result and
2117 a decimal-point character appears only if it is followed by a digit.
2119 The @samp{%a} and @samp{%A} conversions are meant for representing
2120 floating-point numbers exactly in textual form so that they can be
2121 exchanged as texts between different programs and/or machines. The
2122 numbers are represented in the form
2123 @w{[@code{-}]@code{0x}@var{h}@code{.}@var{hhh}@code{p}[@code{+}|@code{-}]@var{dd}}.
2124 At the left of the decimal-point character exactly one digit is print.
2125 This character is only @code{0} if the number is denormalized.
2126 Otherwise the value is unspecified; it is implementation dependent how many
2127 bits are used. The number of hexadecimal digits on the right side of
2128 the decimal-point character is equal to the precision. If the precision
2129 is zero it is determined to be large enough to provide an exact
2130 representation of the number (or it is large enough to distinguish two
2131 adjacent values if the @code{FLT_RADIX} is not a power of 2,
2132 @pxref{Floating Point Parameters}). For the @samp{%a} conversion
2133 lower-case characters are used to represent the hexadecimal number and
2134 the prefix and exponent sign are printed as @code{0x} and @code{p}
2135 respectively. Otherwise upper-case characters are used and @code{0X}
2136 and @code{P} are used for the representation of prefix and exponent
2137 string. The exponent to the base of two is printed as a decimal number
2138 using at least one digit but at most as many digits as necessary to
2139 represent the value exactly.
2141 If the value to be printed represents infinity or a NaN, the output is
2142 @w{[@code{-}]@code{inf}} or @code{nan} respectively if the conversion
2143 specifier is @samp{%a}, @samp{%e}, @samp{%f}, or @samp{%g} and it is
2144 @w{[@code{-}]@code{INF}} or @code{NAN} respectively if the conversion is
2145 @samp{%A}, @samp{%E}, @samp{%F} or @samp{%G}. On some implementations, a NaN
2146 may result in longer output with information about the payload of the
2147 NaN; ISO C2X defines a macro @code{_PRINTF_NAN_LEN_MAX} giving the
2148 maximum length of such output.
2150 The following flags can be used to modify the behavior:
2152 @comment We use @asis instead of @samp so we can have ` ' as an item.
2155 Left-justify the result in the field. Normally the result is
2159 Always include a plus or minus sign in the result.
2162 If the result doesn't start with a plus or minus sign, prefix it with a
2163 space instead. Since the @samp{+} flag ensures that the result includes
2164 a sign, this flag is ignored if you supply both of them.
2167 Specifies that the result should always include a decimal point, even
2168 if no digits follow it. For the @samp{%g} and @samp{%G} conversions,
2169 this also forces trailing zeros after the decimal point to be left
2170 in place where they would otherwise be removed.
2173 Separate the digits of the integer part of the result into groups as
2174 specified by the locale specified for the @code{LC_NUMERIC} category;
2175 @pxref{General Numeric}. This flag is a GNU extension.
2178 Pad the field with zeros instead of spaces; the zeros are placed
2179 after any sign. This flag is ignored if the @samp{-} flag is also
2183 The precision specifies how many digits follow the decimal-point
2184 character for the @samp{%f}, @samp{%F}, @samp{%e}, and @samp{%E} conversions.
2185 For these conversions, the default precision is @code{6}. If the precision
2186 is explicitly @code{0}, this suppresses the decimal point character
2187 entirely. For the @samp{%g} and @samp{%G} conversions, the precision
2188 specifies how many significant digits to print. Significant digits are
2189 the first digit before the decimal point, and all the digits after it.
2190 If the precision is @code{0} or not specified for @samp{%g} or @samp{%G},
2191 it is treated like a value of @code{1}. If the value being printed
2192 cannot be expressed accurately in the specified number of digits, the
2193 value is rounded to the nearest number that fits.
2195 Without a type modifier, the floating-point conversions use an argument
2196 of type @code{double}. (By the default argument promotions, any
2197 @code{float} arguments are automatically converted to @code{double}.)
2198 The following type modifier is supported:
2202 An uppercase @samp{L} specifies that the argument is a @code{long
2206 Here are some examples showing how numbers print using the various
2207 floating-point conversions. All of the numbers were printed using
2208 this template string:
2211 "|%13.4a|%13.4f|%13.4e|%13.4g|\n"
2217 | 0x0.0000p+0| 0.0000| 0.0000e+00| 0|
2218 | 0x1.0000p-1| 0.5000| 5.0000e-01| 0.5|
2219 | 0x1.0000p+0| 1.0000| 1.0000e+00| 1|
2220 | -0x1.0000p+0| -1.0000| -1.0000e+00| -1|
2221 | 0x1.9000p+6| 100.0000| 1.0000e+02| 100|
2222 | 0x1.f400p+9| 1000.0000| 1.0000e+03| 1000|
2223 | 0x1.3880p+13| 10000.0000| 1.0000e+04| 1e+04|
2224 | 0x1.81c8p+13| 12345.0000| 1.2345e+04| 1.234e+04|
2225 | 0x1.86a0p+16| 100000.0000| 1.0000e+05| 1e+05|
2226 | 0x1.e240p+16| 123456.0000| 1.2346e+05| 1.235e+05|
2229 Notice how the @samp{%g} conversion drops trailing zeros.
2231 @node Other Output Conversions
2232 @subsection Other Output Conversions
2234 This section describes miscellaneous conversions for @code{printf}.
2236 The @samp{%c} conversion prints a single character. In case there is no
2237 @samp{l} modifier the @code{int} argument is first converted to an
2238 @code{unsigned char}. Then, if used in a wide stream function, the
2239 character is converted into the corresponding wide character. The
2240 @samp{-} flag can be used to specify left-justification in the field,
2241 but no other flags are defined, and no precision or type modifier can be
2245 printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
2249 prints @samp{hello}.
2251 If there is an @samp{l} modifier present the argument is expected to be
2252 of type @code{wint_t}. If used in a multibyte function the wide
2253 character is converted into a multibyte character before being added to
2254 the output. In this case more than one output byte can be produced.
2256 The @samp{%s} conversion prints a string. If no @samp{l} modifier is
2257 present the corresponding argument must be of type @code{char *} (or
2258 @code{const char *}). If used in a wide stream function the string is
2259 first converted to a wide character string. A precision can be
2260 specified to indicate the maximum number of characters to write;
2261 otherwise characters in the string up to but not including the
2262 terminating null character are written to the output stream. The
2263 @samp{-} flag can be used to specify left-justification in the field,
2264 but no other flags or type modifiers are defined for this conversion.
2268 printf ("%3s%-6s", "no", "where");
2272 prints @samp{ nowhere }.
2274 If there is an @samp{l} modifier present, the argument is expected to
2275 be of type @code{wchar_t} (or @code{const wchar_t *}).
2277 If you accidentally pass a null pointer as the argument for a @samp{%s}
2278 conversion, @theglibc{} prints it as @samp{(null)}. We think this
2279 is more useful than crashing. But it's not good practice to pass a null
2280 argument intentionally.
2282 The @samp{%m} conversion prints the string corresponding to the error
2283 code in @code{errno}. @xref{Error Messages}. Thus:
2286 fprintf (stderr, "can't open `%s': %m\n", filename);
2293 fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
2296 The @samp{%m} conversion can be used with the @samp{#} flag to print an
2297 error constant, as provided by @code{strerrorname_np}. Both @samp{%m}
2298 and @samp{%#m} are @glibcadj{} extensions.
2300 The @samp{%p} conversion prints a pointer value. The corresponding
2301 argument must be of type @code{void *}. In practice, you can use any
2304 In @theglibc{}, non-null pointers are printed as unsigned integers,
2305 as if a @samp{%#x} conversion were used. Null pointers print as
2306 @samp{(nil)}. (Pointers might print differently in other systems.)
2311 printf ("%p", "testing");
2315 prints @samp{0x} followed by a hexadecimal number---the address of the
2316 string constant @code{"testing"}. It does not print the word
2319 You can supply the @samp{-} flag with the @samp{%p} conversion to
2320 specify left-justification, but no other flags, precision, or type
2321 modifiers are defined.
2323 The @samp{%n} conversion is unlike any of the other output conversions.
2324 It uses an argument which must be a pointer to an @code{int}, but
2325 instead of printing anything it stores the number of characters printed
2326 so far by this call at that location. The @samp{h} and @samp{l} type
2327 modifiers are permitted to specify that the argument is of type
2328 @code{short int *} or @code{long int *} instead of @code{int *}, but no
2329 flags, field width, or precision are permitted.
2335 printf ("%d %s%n\n", 3, "bears", &nchar);
2346 and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven
2350 The @samp{%%} conversion prints a literal @samp{%} character. This
2351 conversion doesn't use an argument, and no flags, field width,
2352 precision, or type modifiers are permitted.
2355 @node Formatted Output Functions
2356 @subsection Formatted Output Functions
2358 This section describes how to call @code{printf} and related functions.
2359 Prototypes for these functions are in the header file @file{stdio.h}.
2360 Because these functions take a variable number of arguments, you
2361 @emph{must} declare prototypes for them before using them. Of course,
2362 the easiest way to make sure you have all the right prototypes is to
2363 just include @file{stdio.h}.
2366 @deftypefun int printf (const char *@var{template}, @dots{})
2367 @standards{ISO, stdio.h}
2368 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2369 The @code{printf} function prints the optional arguments under the
2370 control of the template string @var{template} to the stream
2371 @code{stdout}. It returns the number of characters printed, or a
2372 negative value if there was an output error.
2375 @deftypefun int wprintf (const wchar_t *@var{template}, @dots{})
2376 @standards{ISO, wchar.h}
2377 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2378 The @code{wprintf} function prints the optional arguments under the
2379 control of the wide template string @var{template} to the stream
2380 @code{stdout}. It returns the number of wide characters printed, or a
2381 negative value if there was an output error.
2384 @deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
2385 @standards{ISO, stdio.h}
2386 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2387 This function is just like @code{printf}, except that the output is
2388 written to the stream @var{stream} instead of @code{stdout}.
2391 @deftypefun int fwprintf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
2392 @standards{ISO, wchar.h}
2393 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2394 This function is just like @code{wprintf}, except that the output is
2395 written to the stream @var{stream} instead of @code{stdout}.
2398 @deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
2399 @standards{ISO, stdio.h}
2400 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2401 This is like @code{printf}, except that the output is stored in the character
2402 array @var{s} instead of written to a stream. A null character is written
2403 to mark the end of the string.
2405 The @code{sprintf} function returns the number of characters stored in
2406 the array @var{s}, not including the terminating null character.
2408 The behavior of this function is undefined if copying takes place
2409 between objects that overlap---for example, if @var{s} is also given
2410 as an argument to be printed under control of the @samp{%s} conversion.
2411 @xref{Copying Strings and Arrays}.
2413 @strong{Warning:} The @code{sprintf} function can be @strong{dangerous}
2414 because it can potentially output more characters than can fit in the
2415 allocation size of the string @var{s}. Remember that the field width
2416 given in a conversion specification is only a @emph{minimum} value.
2418 To avoid this problem, you can use @code{snprintf} or @code{asprintf},
2422 @deftypefun int swprintf (wchar_t *@var{ws}, size_t @var{size}, const wchar_t *@var{template}, @dots{})
2423 @standards{GNU, wchar.h}
2424 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2425 This is like @code{wprintf}, except that the output is stored in the
2426 wide character array @var{ws} instead of written to a stream. A null
2427 wide character is written to mark the end of the string. The @var{size}
2428 argument specifies the maximum number of characters to produce. The
2429 trailing null character is counted towards this limit, so you should
2430 allocate at least @var{size} wide characters for the string @var{ws}.
2432 The return value is the number of characters generated for the given
2433 input, excluding the trailing null. If not all output fits into the
2434 provided buffer a negative value is returned, and @code{errno} is set to
2435 @code{E2BIG}. (The setting of @code{errno} is a GNU extension.) You
2436 should try again with a bigger output string. @emph{Note:} this is
2437 different from how @code{snprintf} handles this situation.
2439 Note that the corresponding narrow stream function takes fewer
2440 parameters. @code{swprintf} in fact corresponds to the @code{snprintf}
2441 function. Since the @code{sprintf} function can be dangerous and should
2442 be avoided the @w{ISO C} committee refused to make the same mistake
2443 again and decided to not define a function exactly corresponding to
2447 @deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{})
2448 @standards{GNU, stdio.h}
2449 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2450 The @code{snprintf} function is similar to @code{sprintf}, except that
2451 the @var{size} argument specifies the maximum number of characters to
2452 produce. The trailing null character is counted towards this limit, so
2453 you should allocate at least @var{size} characters for the string @var{s}.
2454 If @var{size} is zero, nothing, not even the null byte, shall be written and
2455 @var{s} may be a null pointer.
2457 The return value is the number of characters which would be generated
2458 for the given input, excluding the trailing null. If this value is
2459 greater than or equal to @var{size}, not all characters from the result have
2460 been stored in @var{s}. If this happens, you should be wary of using
2461 the truncated result as that could lead to security, encoding, or
2462 other bugs in your program (@pxref{Truncating Strings}).
2463 Instead, you should try again with a bigger output
2464 string. Here is an example of doing this:
2468 /* @r{Construct a message describing the value of a variable}
2469 @r{whose name is @var{name} and whose value is @var{value}.} */
2471 make_message (char *name, char *value)
2473 /* @r{Guess we need no more than 100 bytes of space.} */
2475 char *buffer = xmalloc (size);
2478 /* @r{Try to print in the allocated space.} */
2479 int buflen = snprintf (buffer, size, "value of %s is %s",
2481 if (! (0 <= buflen && buflen < SIZE_MAX))
2482 fatal ("integer overflow");
2487 /* @r{Reallocate buffer now that we know
2488 how much space is needed.} */
2491 buffer = xrealloc (buffer, size);
2493 /* @r{Try again.} */
2494 snprintf (buffer, size, "value of %s is %s",
2497 /* @r{The last call worked, return the string.} */
2503 In practice, it is often easier just to use @code{asprintf}, below.
2505 @strong{Attention:} In versions of @theglibc{} prior to 2.1 the
2506 return value is the number of characters stored, not including the
2507 terminating null; unless there was not enough space in @var{s} to
2508 store the result in which case @code{-1} is returned. This was
2509 changed in order to comply with the @w{ISO C99} standard.
2512 @node Dynamic Output
2513 @subsection Dynamically Allocating Formatted Output
2515 The functions in this section do formatted output and place the results
2516 in dynamically allocated memory.
2518 @deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
2519 @standards{GNU, stdio.h}
2520 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2521 This function is similar to @code{sprintf}, except that it dynamically
2522 allocates a string (as with @code{malloc}; @pxref{Unconstrained
2523 Allocation}) to hold the output, instead of putting the output in a
2524 buffer you allocate in advance. The @var{ptr} argument should be the
2525 address of a @code{char *} object, and a successful call to
2526 @code{asprintf} stores a pointer to the newly allocated string at that
2529 The return value is the number of characters allocated for the buffer, or
2530 less than zero if an error occurred. Usually this means that the buffer
2531 could not be allocated.
2533 Here is how to use @code{asprintf} to get the same result as the
2534 @code{snprintf} example, but more easily:
2537 /* @r{Construct a message describing the value of a variable}
2538 @r{whose name is @var{name} and whose value is @var{value}.} */
2540 make_message (char *name, char *value)
2543 if (asprintf (&result, "value of %s is %s", name, value) < 0)
2550 @deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
2551 @standards{GNU, stdio.h}
2552 @safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
2553 This function is similar to @code{asprintf}, except that it uses the
2554 obstack @var{obstack} to allocate the space. @xref{Obstacks}.
2556 The characters are written onto the end of the current object.
2557 To get at them, you must finish the object with @code{obstack_finish}
2558 (@pxref{Growing Objects}).
2561 @node Variable Arguments Output
2562 @subsection Variable Arguments Output Functions
2564 The functions @code{vprintf} and friends are provided so that you can
2565 define your own variadic @code{printf}-like functions that make use of
2566 the same internals as the built-in formatted output functions.
2568 The most natural way to define such functions would be to use a language
2569 construct to say, ``Call @code{printf} and pass this template plus all
2570 of my arguments after the first five.'' But there is no way to do this
2571 in C, and it would be hard to provide a way, since at the C language
2572 level there is no way to tell how many arguments your function received.
2574 Since that method is impossible, we provide alternative functions, the
2575 @code{vprintf} series, which lets you pass a @code{va_list} to describe
2576 ``all of my arguments after the first five.''
2578 When it is sufficient to define a macro rather than a real function,
2579 the GNU C compiler provides a way to do this much more easily with macros.
2583 #define myprintf(a, b, c, d, e, rest...) \
2584 printf (mytemplate , ## rest)
2588 @xref{Variadic Macros,,, cpp, The C preprocessor}, for details.
2589 But this is limited to macros, and does not apply to real functions at all.
2591 Before calling @code{vprintf} or the other functions listed in this
2592 section, you @emph{must} call @code{va_start} (@pxref{Variadic
2593 Functions}) to initialize a pointer to the variable arguments. Then you
2594 can call @code{va_arg} to fetch the arguments that you want to handle
2595 yourself. This advances the pointer past those arguments.
2597 Once your @code{va_list} pointer is pointing at the argument of your
2598 choice, you are ready to call @code{vprintf}. That argument and all
2599 subsequent arguments that were passed to your function are used by
2600 @code{vprintf} along with the template that you specified separately.
2602 @strong{Portability Note:} The value of the @code{va_list} pointer is
2603 undetermined after the call to @code{vprintf}, so you must not use
2604 @code{va_arg} after you call @code{vprintf}. Instead, you should call
2605 @code{va_end} to retire the pointer from service. You can call
2606 @code{va_start} again and begin fetching the arguments from the start of
2607 the variable argument list. (Alternatively, you can use @code{va_copy}
2608 to make a copy of the @code{va_list} pointer before calling
2609 @code{vfprintf}.) Calling @code{vprintf} does not destroy the argument
2610 list of your function, merely the particular pointer that you passed to
2613 Prototypes for these functions are declared in @file{stdio.h}.
2616 @deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
2617 @standards{ISO, stdio.h}
2618 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2619 This function is similar to @code{printf} except that, instead of taking
2620 a variable number of arguments directly, it takes an argument list
2624 @deftypefun int vwprintf (const wchar_t *@var{template}, va_list @var{ap})
2625 @standards{ISO, wchar.h}
2626 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2627 This function is similar to @code{wprintf} except that, instead of taking
2628 a variable number of arguments directly, it takes an argument list
2632 @deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
2633 @standards{ISO, stdio.h}
2634 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2635 @c Although vfprintf sets up a cleanup region to release the lock on the
2636 @c output stream, it doesn't use it to release args_value or string in
2637 @c case of cancellation. This doesn't make it unsafe, but cancelling it
2638 @c may leak memory. The unguarded use of __printf_function_table is
2639 @c also of concern for all callers.
2641 @c _udiv_qrnnd_preinv ok
2643 @c _i18n_number_rewrite
2645 @c __towctrans @mtslocale
2646 @c __wcrtomb ok? dup below
2647 @c outdigit_value ok
2648 @c outdigitwc_value ok
2652 @c __printf_fp @mtslocale @ascuheap @acsmem
2653 @c __printf_fphex @mtslocale
2655 @c [GNU/Linux] fopen, strtoul, free
2656 @c __strerror_r ok if no translation, check otherwise
2657 @c __btowc ? gconv-modules
2658 @c __wcrtomb ok (not using internal state) gconv-modules
2660 @c UNBUFFERED_P (tested before taking the stream lock)
2661 @c buffered_vfprintf ok
2662 @c __find_spec(wc|mb)
2664 @c __libc_use_alloca
2666 @c process_string_arg
2667 @c __parse_one_spec(wc|mb)
2668 @c *__printf_arginfo_table unguarded
2669 @c __printf_va_arg_table-> unguarded
2670 @c *__printf_function_table unguarded
2675 This is the equivalent of @code{fprintf} with the variable argument list
2676 specified directly as for @code{vprintf}.
2679 @deftypefun int vfwprintf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
2680 @standards{ISO, wchar.h}
2681 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2682 This is the equivalent of @code{fwprintf} with the variable argument list
2683 specified directly as for @code{vwprintf}.
2686 @deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
2687 @standards{ISO, stdio.h}
2688 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2689 This is the equivalent of @code{sprintf} with the variable argument list
2690 specified directly as for @code{vprintf}.
2693 @deftypefun int vswprintf (wchar_t *@var{ws}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap})
2694 @standards{GNU, wchar.h}
2695 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2696 This is the equivalent of @code{swprintf} with the variable argument list
2697 specified directly as for @code{vwprintf}.
2700 @deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
2701 @standards{GNU, stdio.h}
2702 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2703 This is the equivalent of @code{snprintf} with the variable argument list
2704 specified directly as for @code{vprintf}.
2707 @deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
2708 @standards{GNU, stdio.h}
2709 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2710 The @code{vasprintf} function is the equivalent of @code{asprintf} with the
2711 variable argument list specified directly as for @code{vprintf}.
2714 @deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
2715 @standards{GNU, stdio.h}
2716 @safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
2717 @c The obstack is not guarded by mutexes, it might be at an inconsistent
2718 @c state within a signal handler, and it could be left at an
2719 @c inconsistent state in case of cancellation.
2720 The @code{obstack_vprintf} function is the equivalent of
2721 @code{obstack_printf} with the variable argument list specified directly
2722 as for @code{vprintf}.
2725 Here's an example showing how you might use @code{vfprintf}. This is a
2726 function that prints error messages to the stream @code{stderr}, along
2727 with a prefix indicating the name of the program
2728 (@pxref{Error Messages}, for a description of
2729 @code{program_invocation_short_name}).
2737 eprintf (const char *template, ...)
2740 extern char *program_invocation_short_name;
2742 fprintf (stderr, "%s: ", program_invocation_short_name);
2743 va_start (ap, template);
2744 vfprintf (stderr, template, ap);
2751 You could call @code{eprintf} like this:
2754 eprintf ("file `%s' does not exist\n", filename);
2757 In GNU C, there is a special construct you can use to let the compiler
2758 know that a function uses a @code{printf}-style format string. Then it
2759 can check the number and types of arguments in each call to the
2760 function, and warn you when they do not match the format string.
2761 For example, take this declaration of @code{eprintf}:
2764 void eprintf (const char *template, ...)
2765 __attribute__ ((format (printf, 1, 2)));
2769 This tells the compiler that @code{eprintf} uses a format string like
2770 @code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input});
2771 the format string appears as the first argument;
2772 and the arguments to satisfy the format begin with the second.
2773 @xref{Function Attributes, , Declaring Attributes of Functions,
2774 gcc, Using GNU CC}, for more information.
2776 @node Parsing a Template String
2777 @subsection Parsing a Template String
2778 @cindex parsing a template string
2780 You can use the function @code{parse_printf_format} to obtain
2781 information about the number and types of arguments that are expected by
2782 a given template string. This function permits interpreters that
2783 provide interfaces to @code{printf} to avoid passing along invalid
2784 arguments from the user's program, which could cause a crash.
2786 All the symbols described in this section are declared in the header
2787 file @file{printf.h}.
2789 @deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
2790 @standards{GNU, printf.h}
2791 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2792 This function returns information about the number and types of
2793 arguments expected by the @code{printf} template string @var{template}.
2794 The information is stored in the array @var{argtypes}; each element of
2795 this array describes one argument. This information is encoded using
2796 the various @samp{PA_} macros, listed below.
2798 The argument @var{n} specifies the number of elements in the array
2799 @var{argtypes}. This is the maximum number of elements that
2800 @code{parse_printf_format} will try to write.
2802 @code{parse_printf_format} returns the total number of arguments required
2803 by @var{template}. If this number is greater than @var{n}, then the
2804 information returned describes only the first @var{n} arguments. If you
2805 want information about additional arguments, allocate a bigger
2806 array and call @code{parse_printf_format} again.
2809 The argument types are encoded as a combination of a basic type and
2812 @deftypevr Macro int PA_FLAG_MASK
2813 @standards{GNU, printf.h}
2814 This macro is a bitmask for the type modifier flag bits. You can write
2815 the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the
2816 flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to
2817 extract just the basic type code.
2820 Here are symbolic constants that represent the basic types; they stand
2825 @standards{GNU, printf.h}
2826 This specifies that the base type is @code{int}.
2829 @standards{GNU, printf.h}
2830 This specifies that the base type is @code{int}, cast to @code{char}.
2833 @standards{GNU, printf.h}
2834 This specifies that the base type is @code{char *}, a null-terminated string.
2837 @standards{GNU, printf.h}
2838 This specifies that the base type is @code{void *}, an arbitrary pointer.
2841 @standards{GNU, printf.h}
2842 This specifies that the base type is @code{float}.
2845 @standards{GNU, printf.h}
2846 This specifies that the base type is @code{double}.
2849 @standards{GNU, printf.h}
2850 You can define additional base types for your own programs as offsets
2851 from @code{PA_LAST}. For example, if you have data types @samp{foo}
2852 and @samp{bar} with their own specialized @code{printf} conversions,
2853 you could define encodings for these types as:
2856 #define PA_FOO PA_LAST
2857 #define PA_BAR (PA_LAST + 1)
2861 Here are the flag bits that modify a basic type. They are combined with
2862 the code for the basic type using inclusive-or.
2866 @standards{GNU, printf.h}
2867 If this bit is set, it indicates that the encoded type is a pointer to
2868 the base type, rather than an immediate value.
2869 For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.
2872 @standards{GNU, printf.h}
2873 If this bit is set, it indicates that the base type is modified with
2874 @code{short}. (This corresponds to the @samp{h} type modifier.)
2877 @standards{GNU, printf.h}
2878 If this bit is set, it indicates that the base type is modified with
2879 @code{long}. (This corresponds to the @samp{l} type modifier.)
2881 @item PA_FLAG_LONG_LONG
2882 @standards{GNU, printf.h}
2883 If this bit is set, it indicates that the base type is modified with
2884 @code{long long}. (This corresponds to the @samp{L} type modifier.)
2886 @item PA_FLAG_LONG_DOUBLE
2887 @standards{GNU, printf.h}
2888 This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with
2889 a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
2893 For an example of using these facilities, see @ref{Example of Parsing}.
2896 @node Example of Parsing
2897 @subsection Example of Parsing a Template String
2899 Here is an example of decoding argument types for a format string. We
2900 assume this is part of an interpreter which contains arguments of type
2901 @code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
2902 perhaps others which are not valid here).
2905 /* @r{Test whether the @var{nargs} specified objects}
2906 @r{in the vector @var{args} are valid}
2907 @r{for the format string @var{format}:}
2908 @r{if so, return 1.}
2909 @r{If not, return 0 after printing an error message.} */
2912 validate_args (char *format, int nargs, OBJECT *args)
2917 /* @r{Get the information about the arguments.}
2918 @r{Each conversion specification must be at least two characters}
2919 @r{long, so there cannot be more specifications than half the}
2920 @r{length of the string.} */
2922 argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
2923 nwanted = parse_printf_format (format, nargs, argtypes);
2925 /* @r{Check the number of arguments.} */
2926 if (nwanted > nargs)
2928 error ("too few arguments (at least %d required)", nwanted);
2932 /* @r{Check the C type wanted for each argument}
2933 @r{and see if the object given is suitable.} */
2934 for (i = 0; i < nwanted; i++)
2938 if (argtypes[i] & PA_FLAG_PTR)
2941 switch (argtypes[i] & ~PA_FLAG_MASK)
2958 if (TYPE (args[i]) != wanted)
2960 error ("type mismatch for arg number %d", i);
2968 @node Customizing Printf
2969 @section Customizing @code{printf}
2970 @cindex customizing @code{printf}
2971 @cindex defining new @code{printf} conversions
2972 @cindex extending @code{printf}
2974 @Theglibc{} lets you define your own custom conversion specifiers
2975 for @code{printf} template strings, to teach @code{printf} clever ways
2976 to print the important data structures of your program.
2978 The way you do this is by registering the conversion with the function
2979 @code{register_printf_function}; see @ref{Registering New Conversions}.
2980 One of the arguments you pass to this function is a pointer to a handler
2981 function that produces the actual output; see @ref{Defining the Output
2982 Handler}, for information on how to write this function.
2984 You can also install a function that just returns information about the
2985 number and type of arguments expected by the conversion specifier.
2986 @xref{Parsing a Template String}, for information about this.
2988 The facilities of this section are declared in the header file
2992 * Registering New Conversions:: Using @code{register_printf_function}
2993 to register a new output conversion.
2994 * Conversion Specifier Options:: The handler must be able to get
2995 the options specified in the
2996 template when it is called.
2997 * Defining the Output Handler:: Defining the handler and arginfo
2998 functions that are passed as arguments
2999 to @code{register_printf_function}.
3000 * Printf Extension Example:: How to define a @code{printf}
3002 * Predefined Printf Handlers:: Predefined @code{printf} handlers.
3005 @strong{Portability Note:} The ability to extend the syntax of
3006 @code{printf} template strings is a GNU extension. ISO standard C has
3007 nothing similar. When using the GNU C compiler or any other compiler
3008 that interprets calls to standard I/O functions according to the rules
3009 of the language standard it is necessary to disable such handling by
3010 the appropriate compiler option. Otherwise the behavior of a program
3011 that relies on the extension is undefined.
3013 @node Registering New Conversions
3014 @subsection Registering New Conversions
3016 The function to register a new output conversion is
3017 @code{register_printf_function}, declared in @file{printf.h}.
3020 @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function})
3021 @standards{GNU, printf.h}
3022 @safety{@prelim{}@mtunsafe{@mtasuconst{:printfext}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
3023 @c This function is guarded by the global non-recursive libc lock, but
3024 @c users of the variables it sets aren't, and those should be MT-Safe,
3025 @c so we're ruling out the use of this extension with threads. Calling
3026 @c it from a signal handler may self-deadlock, and cancellation may
3027 @c leave the lock held, besides leaking allocated memory.
3028 This function defines the conversion specifier character @var{spec}.
3029 Thus, if @var{spec} is @code{'Y'}, it defines the conversion @samp{%Y}.
3030 You can redefine the built-in conversions like @samp{%s}, but flag
3031 characters like @samp{#} and type modifiers like @samp{l} can never be
3032 used as conversions; calling @code{register_printf_function} for those
3033 characters has no effect. It is advisable not to use lowercase letters,
3034 since the ISO C standard warns that additional lowercase letters may be
3035 standardized in future editions of the standard.
3037 The @var{handler-function} is the function called by @code{printf} and
3038 friends when this conversion appears in a template string.
3039 @xref{Defining the Output Handler}, for information about how to define
3040 a function to pass as this argument. If you specify a null pointer, any
3041 existing handler function for @var{spec} is removed.
3043 The @var{arginfo-function} is the function called by
3044 @code{parse_printf_format} when this conversion appears in a
3045 template string. @xref{Parsing a Template String}, for information
3048 @c The following is not true anymore. The `parse_printf_format' function
3049 @c is now also called from `vfprintf' via `parse_one_spec'.
3050 @c --drepper@gnu, 1996/11/14
3052 @c Normally, you install both functions for a conversion at the same time,
3053 @c but if you are never going to call @code{parse_printf_format}, you do
3054 @c not need to define an arginfo function.
3056 @strong{Attention:} In @theglibc{} versions before 2.0 the
3057 @var{arginfo-function} function did not need to be installed unless
3058 the user used the @code{parse_printf_format} function. This has changed.
3059 Now a call to any of the @code{printf} functions will call this
3060 function when this format specifier appears in the format string.
3062 The return value is @code{0} on success, and @code{-1} on failure
3063 (which occurs if @var{spec} is out of range).
3065 @strong{Portability Note:} It is possible to redefine the standard output
3066 conversions but doing so is strongly discouraged because it may interfere
3067 with the behavior of programs and compiler implementations that assume
3068 the effects of the conversions conform to the relevant language standards.
3069 In addition, conforming compilers need not guarantee that the function
3070 registered for a standard conversion will be called for each such
3071 conversion in every format string in a program.
3074 @node Conversion Specifier Options
3075 @subsection Conversion Specifier Options
3077 If you define a meaning for @samp{%A}, what if the template contains
3078 @samp{%+23A} or @samp{%-#A}? To implement a sensible meaning for these,
3079 the handler when called needs to be able to get the options specified in
3082 Both the @var{handler-function} and @var{arginfo-function} accept an
3083 argument that points to a @code{struct printf_info}, which contains
3084 information about the options appearing in an instance of the conversion
3085 specifier. This data type is declared in the header file
3089 @deftp {Type} {struct printf_info}
3090 @standards{GNU, printf.h}
3091 This structure is used to pass information about the options appearing
3092 in an instance of a conversion specifier in a @code{printf} template
3093 string to the handler and arginfo functions for that specifier. It
3094 contains the following members:
3098 This is the precision specified. The value is @code{-1} if no precision
3099 was specified. If the precision was given as @samp{*}, the
3100 @code{printf_info} structure passed to the handler function contains the
3101 actual value retrieved from the argument list. But the structure passed
3102 to the arginfo function contains a value of @code{INT_MIN}, since the
3103 actual value is not known.
3106 This is the minimum field width specified. The value is @code{0} if no
3107 width was specified. If the field width was given as @samp{*}, the
3108 @code{printf_info} structure passed to the handler function contains the
3109 actual value retrieved from the argument list. But the structure passed
3110 to the arginfo function contains a value of @code{INT_MIN}, since the
3111 actual value is not known.
3114 This is the conversion specifier character specified. It's stored in
3115 the structure so that you can register the same handler function for
3116 multiple characters, but still have a way to tell them apart when the
3117 handler function is called.
3119 @item unsigned int is_long_double
3120 This is a boolean that is true if the @samp{L}, @samp{ll}, or @samp{q}
3121 type modifier was specified. For integer conversions, this indicates
3122 @code{long long int}, as opposed to @code{long double} for floating
3125 @item unsigned int is_char
3126 This is a boolean that is true if the @samp{hh} type modifier was specified.
3128 @item unsigned int is_short
3129 This is a boolean that is true if the @samp{h} type modifier was specified.
3131 @item unsigned int is_long
3132 This is a boolean that is true if the @samp{l} type modifier was specified.
3134 @item unsigned int alt
3135 This is a boolean that is true if the @samp{#} flag was specified.
3137 @item unsigned int space
3138 This is a boolean that is true if the @samp{ } flag was specified.
3140 @item unsigned int left
3141 This is a boolean that is true if the @samp{-} flag was specified.
3143 @item unsigned int showsign
3144 This is a boolean that is true if the @samp{+} flag was specified.
3146 @item unsigned int group
3147 This is a boolean that is true if the @samp{'} flag was specified.
3149 @item unsigned int extra
3150 This flag has a special meaning depending on the context. It could
3151 be used freely by the user-defined handlers but when called from
3152 the @code{printf} function this variable always contains the value
3155 @item unsigned int wide
3156 This flag is set if the stream is wide oriented.
3159 This is the character to use for padding the output to the minimum field
3160 width. The value is @code{'0'} if the @samp{0} flag was specified, and
3161 @code{' '} otherwise.
3166 @node Defining the Output Handler
3167 @subsection Defining the Output Handler
3169 Now let's look at how to define the handler and arginfo functions
3170 which are passed as arguments to @code{register_printf_function}.
3172 @strong{Compatibility Note:} The interface changed in @theglibc{}
3173 version 2.0. Previously the third argument was of type
3176 You should define your handler functions with a prototype like:
3179 int @var{function} (FILE *stream, const struct printf_info *info,
3180 const void *const *args)
3183 The @var{stream} argument passed to the handler function is the stream to
3184 which it should write output.
3186 The @var{info} argument is a pointer to a structure that contains
3187 information about the various options that were included with the
3188 conversion in the template string. You should not modify this structure
3189 inside your handler function. @xref{Conversion Specifier Options}, for
3190 a description of this data structure.
3192 @c The following changes some time back. --drepper@gnu, 1996/11/14
3194 @c The @code{ap_pointer} argument is used to pass the tail of the variable
3195 @c argument list containing the values to be printed to your handler.
3196 @c Unlike most other functions that can be passed an explicit variable
3197 @c argument list, this is a @emph{pointer} to a @code{va_list}, rather than
3198 @c the @code{va_list} itself. Thus, you should fetch arguments by
3199 @c means of @code{va_arg (*ap_pointer, @var{type})}.
3201 @c (Passing a pointer here allows the function that calls your handler
3202 @c function to update its own @code{va_list} variable to account for the
3203 @c arguments that your handler processes. @xref{Variadic Functions}.)
3205 The @var{args} is a vector of pointers to the arguments data.
3206 The number of arguments was determined by calling the argument
3207 information function provided by the user.
3209 Your handler function should return a value just like @code{printf}
3210 does: it should return the number of characters it has written, or a
3211 negative value to indicate an error.
3213 @deftp {Data Type} printf_function
3214 @standards{GNU, printf.h}
3215 This is the data type that a handler function should have.
3218 If you are going to use @w{@code{parse_printf_format}} in your
3219 application, you must also define a function to pass as the
3220 @var{arginfo-function} argument for each new conversion you install with
3221 @code{register_printf_function}.
3223 You have to define these functions with a prototype like:
3226 int @var{function} (const struct printf_info *info,
3227 size_t n, int *argtypes)
3230 The return value from the function should be the number of arguments the
3231 conversion expects. The function should also fill in no more than
3232 @var{n} elements of the @var{argtypes} array with information about the
3233 types of each of these arguments. This information is encoded using the
3234 various @samp{PA_} macros. (You will notice that this is the same
3235 calling convention @code{parse_printf_format} itself uses.)
3237 @deftp {Data Type} printf_arginfo_function
3238 @standards{GNU, printf.h}
3239 This type is used to describe functions that return information about
3240 the number and type of arguments used by a conversion specifier.
3243 @node Printf Extension Example
3244 @subsection @code{printf} Extension Example
3246 Here is an example showing how to define a @code{printf} handler function.
3247 This program defines a data structure called a @code{Widget} and
3248 defines the @samp{%W} conversion to print information about @w{@code{Widget *}}
3249 arguments, including the pointer value and the name stored in the data
3250 structure. The @samp{%W} conversion supports the minimum field width and
3251 left-justification options, but ignores everything else.
3254 @include rprintf.c.texi
3257 The output produced by this program looks like:
3260 |<Widget 0xffeffb7c: mywidget>|
3261 | <Widget 0xffeffb7c: mywidget>|
3262 |<Widget 0xffeffb7c: mywidget> |
3265 @node Predefined Printf Handlers
3266 @subsection Predefined @code{printf} Handlers
3268 @Theglibc{} also contains a concrete and useful application of the
3269 @code{printf} handler extension. There are two functions available
3270 which implement a special way to print floating-point numbers.
3272 @deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args})
3273 @standards{GNU, printf.h}
3274 @safety{@prelim{}@mtsafe{@mtsrace{:fp} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @acucorrupt{}}}
3275 @c This is meant to be called by vfprintf, that should hold the lock on
3276 @c the stream, but if this function is called directly, output will be
3277 @c racy, besides the uses of the global locale object while other
3278 @c threads may be changing it and the possbility of leaving the stream
3279 @c object in an inconsistent state in case of cancellation.
3280 Print a given floating point number as for the format @code{%f} except
3281 that there is a postfix character indicating the divisor for the
3282 number to make this less than 1000. There are two possible divisors:
3283 powers of 1024 or powers of 1000. Which one is used depends on the
3284 format character specified while registered this handler. If the
3285 character is of lower case, 1024 is used. For upper case characters,
3288 The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes,
3289 etc. The full table is:
3292 @multitable {' '} {2^10 (1024)} {zetta} {Upper} {10^24 (1000)}
3293 @item low @tab Multiplier @tab From @tab Upper @tab Multiplier
3294 @item ' ' @tab 1 @tab @tab ' ' @tab 1
3295 @item k @tab 2^10 (1024) @tab kilo @tab K @tab 10^3 (1000)
3296 @item m @tab 2^20 @tab mega @tab M @tab 10^6
3297 @item g @tab 2^30 @tab giga @tab G @tab 10^9
3298 @item t @tab 2^40 @tab tera @tab T @tab 10^12
3299 @item p @tab 2^50 @tab peta @tab P @tab 10^15
3300 @item e @tab 2^60 @tab exa @tab E @tab 10^18
3301 @item z @tab 2^70 @tab zetta @tab Z @tab 10^21
3302 @item y @tab 2^80 @tab yotta @tab Y @tab 10^24
3307 \hbox to\hsize{\hfil\vbox{\offinterlineskip
3309 \halign{\strut#& \vrule#\tabskip=1em plus2em& {\tt#}\hfil& \vrule#& #\hfil& \vrule#& #\hfil& \vrule#& {\tt#}\hfil& \vrule#& #\hfil& \vrule#\tabskip=0pt\cr
3311 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
3312 && \omit low && Multiplier && From && \omit Upper && Multiplier &\cr
3313 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
3315 && {\tt\char32} && 1 && && {\tt\char32} && 1 &\cr
3316 && k && $2^{10} = 1024$ && kilo && K && $10^3 = 1000$ &\cr
3317 && m && $2^{20}$ && mega && M && $10^6$ &\cr
3318 && g && $2^{30}$ && giga && G && $10^9$ &\cr
3319 && t && $2^{40}$ && tera && T && $10^{12}$ &\cr
3320 && p && $2^{50}$ && peta && P && $10^{15}$ &\cr
3321 && e && $2^{60}$ && exa && E && $10^{18}$ &\cr
3322 && z && $2^{70}$ && zetta && Z && $10^{21}$ &\cr
3323 && y && $2^{80}$ && yotta && Y && $10^{24}$ &\cr
3324 \noalign{\hrule}}}\hfil}
3328 The default precision is 3, i.e., 1024 is printed with a lower-case
3329 format character as if it were @code{%.3fk} and will yield @code{1.000k}.
3332 Due to the requirements of @code{register_printf_function} we must also
3333 provide the function which returns information about the arguments.
3335 @deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes})
3336 @standards{GNU, printf.h}
3337 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3338 This function will return in @var{argtypes} the information about the
3339 used parameters in the way the @code{vfprintf} implementation expects
3340 it. The format always takes one argument.
3343 To use these functions both functions must be registered with a call like
3346 register_printf_function ('B', printf_size, printf_size_info);
3349 Here we register the functions to print numbers as powers of 1000 since
3350 the format character @code{'B'} is an upper-case character. If we
3351 would additionally use @code{'b'} in a line like
3354 register_printf_function ('b', printf_size, printf_size_info);
3358 we could also print using a power of 1024. Please note that all that is
3359 different in these two lines is the format specifier. The
3360 @code{printf_size} function knows about the difference between lower and upper
3361 case format specifiers.
3363 The use of @code{'B'} and @code{'b'} is no coincidence. Rather it is
3364 the preferred way to use this functionality since it is available on
3365 some other systems which also use format specifiers.
3367 @node Formatted Input
3368 @section Formatted Input
3370 @cindex formatted input from a stream
3371 @cindex reading from a stream, formatted
3372 @cindex format string, for @code{scanf}
3373 @cindex template, for @code{scanf}
3374 The functions described in this section (@code{scanf} and related
3375 functions) provide facilities for formatted input analogous to the
3376 formatted output facilities. These functions provide a mechanism for
3377 reading arbitrary values under the control of a @dfn{format string} or
3378 @dfn{template string}.
3381 * Formatted Input Basics:: Some basics to get you started.
3382 * Input Conversion Syntax:: Syntax of conversion specifications.
3383 * Table of Input Conversions:: Summary of input conversions and what they do.
3384 * Numeric Input Conversions:: Details of conversions for reading numbers.
3385 * String Input Conversions:: Details of conversions for reading strings.
3386 * Dynamic String Input:: String conversions that @code{malloc} the buffer.
3387 * Other Input Conversions:: Details of miscellaneous other conversions.
3388 * Formatted Input Functions:: Descriptions of the actual functions.
3389 * Variable Arguments Input:: @code{vscanf} and friends.
3392 @node Formatted Input Basics
3393 @subsection Formatted Input Basics
3395 Calls to @code{scanf} are superficially similar to calls to
3396 @code{printf} in that arbitrary arguments are read under the control of
3397 a template string. While the syntax of the conversion specifications in
3398 the template is very similar to that for @code{printf}, the
3399 interpretation of the template is oriented more towards free-format
3400 input and simple pattern matching, rather than fixed-field formatting.
3401 For example, most @code{scanf} conversions skip over any amount of
3402 ``white space'' (including spaces, tabs, and newlines) in the input
3403 file, and there is no concept of precision for the numeric input
3404 conversions as there is for the corresponding output conversions.
3405 Ordinarily, non-whitespace characters in the template are expected to
3406 match characters in the input stream exactly, but a matching failure is
3407 distinct from an input error on the stream.
3408 @cindex conversion specifications (@code{scanf})
3410 Another area of difference between @code{scanf} and @code{printf} is
3411 that you must remember to supply pointers rather than immediate values
3412 as the optional arguments to @code{scanf}; the values that are read are
3413 stored in the objects that the pointers point to. Even experienced
3414 programmers tend to forget this occasionally, so if your program is
3415 getting strange errors that seem to be related to @code{scanf}, you
3416 might want to double-check this.
3418 When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
3419 leaving the first non-matching character as the next character to be
3420 read from the stream. The normal return value from @code{scanf} is the
3421 number of values that were assigned, so you can use this to determine if
3422 a matching error happened before all the expected values were read.
3423 @cindex matching failure, in @code{scanf}
3425 The @code{scanf} function is typically used for things like reading in
3426 the contents of tables. For example, here is a function that uses
3427 @code{scanf} to initialize an array of @code{double}:
3431 readarray (double *array, int n)
3435 if (scanf (" %lf", &(array[i])) != 1)
3436 invalid_input_error ();
3440 The formatted input functions are not used as frequently as the
3441 formatted output functions. Partly, this is because it takes some care
3442 to use them properly. Another reason is that it is difficult to recover
3443 from a matching error.
3445 If you are trying to read input that doesn't match a single, fixed
3446 pattern, you may be better off using a tool such as Flex to generate a
3447 lexical scanner, or Bison to generate a parser, rather than using
3448 @code{scanf}. For more information about these tools, see @ref{Top, , ,
3449 flex.info, Flex: The Lexical Scanner Generator}, and @ref{Top, , ,
3450 bison.info, The Bison Reference Manual}.
3452 @node Input Conversion Syntax
3453 @subsection Input Conversion Syntax
3455 A @code{scanf} template string is a string that contains ordinary
3456 multibyte characters interspersed with conversion specifications that
3457 start with @samp{%}.
3459 Any whitespace character (as defined by the @code{isspace} function;
3460 @pxref{Classification of Characters}) in the template causes any number
3461 of whitespace characters in the input stream to be read and discarded.
3462 The whitespace characters that are matched need not be exactly the same
3463 whitespace characters that appear in the template string. For example,
3464 write @samp{ , } in the template to recognize a comma with optional
3465 whitespace before and after.
3467 Other characters in the template string that are not part of conversion
3468 specifications must match characters in the input stream exactly; if
3469 this is not the case, a matching failure occurs.
3471 The conversion specifications in a @code{scanf} template string
3472 have the general form:
3475 % @var{flags} @var{width} @var{type} @var{conversion}
3478 In more detail, an input conversion specification consists of an initial
3479 @samp{%} character followed in sequence by:
3483 An optional @dfn{flag character} @samp{*}, which says to ignore the text
3484 read for this specification. When @code{scanf} finds a conversion
3485 specification that uses this flag, it reads input as directed by the
3486 rest of the conversion specification, but it discards this input, does
3487 not use a pointer argument, and does not increment the count of
3488 successful assignments.
3489 @cindex flag character (@code{scanf})
3492 An optional flag character @samp{a} (valid with string conversions only)
3493 which requests allocation of a buffer long enough to store the string in.
3494 (This is a GNU extension.)
3495 @xref{Dynamic String Input}.
3498 An optional decimal integer that specifies the @dfn{maximum field
3499 width}. Reading of characters from the input stream stops either when
3500 this maximum is reached or when a non-matching character is found,
3501 whichever happens first. Most conversions discard initial whitespace
3502 characters (those that don't are explicitly documented), and these
3503 discarded characters don't count towards the maximum field width.
3504 String input conversions store a null character to mark the end of the
3505 input; the maximum field width does not include this terminator.
3506 @cindex maximum field width (@code{scanf})
3509 An optional @dfn{type modifier character}. For example, you can
3510 specify a type modifier of @samp{l} with integer conversions such as
3511 @samp{%d} to specify that the argument is a pointer to a @code{long int}
3512 rather than a pointer to an @code{int}.
3513 @cindex type modifier character (@code{scanf})
3516 A character that specifies the conversion to be applied.
3519 The exact options that are permitted and how they are interpreted vary
3520 between the different conversion specifiers. See the descriptions of the
3521 individual conversions for information about the particular options that
3524 With the @samp{-Wformat} option, the GNU C compiler checks calls to
3525 @code{scanf} and related functions. It examines the format string and
3526 verifies that the correct number and types of arguments are supplied.
3527 There is also a GNU C syntax to tell the compiler that a function you
3528 write uses a @code{scanf}-style format string.
3529 @xref{Function Attributes, , Declaring Attributes of Functions,
3530 gcc, Using GNU CC}, for more information.
3532 @node Table of Input Conversions
3533 @subsection Table of Input Conversions
3534 @cindex input conversions, for @code{scanf}
3536 Here is a table that summarizes the various conversion specifications:
3540 Matches an optionally signed integer written in decimal. @xref{Numeric
3544 Matches an optionally signed integer in any of the formats that the C
3545 language defines for specifying an integer constant. @xref{Numeric
3549 Matches an unsigned integer written in binary radix. This is an ISO
3550 C2X feature. @xref{Numeric Input Conversions}.
3553 Matches an unsigned integer written in octal radix.
3554 @xref{Numeric Input Conversions}.
3557 Matches an unsigned integer written in decimal radix.
3558 @xref{Numeric Input Conversions}.
3560 @item @samp{%x}, @samp{%X}
3561 Matches an unsigned integer written in hexadecimal radix.
3562 @xref{Numeric Input Conversions}.
3564 @item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%F}, @samp{%G}
3565 Matches an optionally signed floating-point number. @xref{Numeric Input
3570 Matches a string containing only non-whitespace characters.
3571 @xref{String Input Conversions}. The presence of the @samp{l} modifier
3572 determines whether the output is stored as a wide character string or a
3573 multibyte string. If @samp{%s} is used in a wide character function the
3574 string is converted as with multiple calls to @code{wcrtomb} into a
3575 multibyte string. This means that the buffer must provide room for
3576 @code{MB_CUR_MAX} bytes for each wide character read. In case
3577 @samp{%ls} is used in a multibyte function the result is converted into
3578 wide characters as with multiple calls of @code{mbrtowc} before being
3579 stored in the user provided buffer.
3582 This is an alias for @samp{%ls} which is supported for compatibility
3583 with the Unix standard.
3586 Matches a string of characters that belong to a specified set.
3587 @xref{String Input Conversions}. The presence of the @samp{l} modifier
3588 determines whether the output is stored as a wide character string or a
3589 multibyte string. If @samp{%[} is used in a wide character function the
3590 string is converted as with multiple calls to @code{wcrtomb} into a
3591 multibyte string. This means that the buffer must provide room for
3592 @code{MB_CUR_MAX} bytes for each wide character read. In case
3593 @samp{%l[} is used in a multibyte function the result is converted into
3594 wide characters as with multiple calls of @code{mbrtowc} before being
3595 stored in the user provided buffer.
3598 Matches a string of one or more characters; the number of characters
3599 read is controlled by the maximum field width given for the conversion.
3600 @xref{String Input Conversions}.
3602 If @samp{%c} is used in a wide stream function the read value is
3603 converted from a wide character to the corresponding multibyte character
3604 before storing it. Note that this conversion can produce more than one
3605 byte of output and therefore the provided buffer must be large enough for up
3606 to @code{MB_CUR_MAX} bytes for each character. If @samp{%lc} is used in
3607 a multibyte function the input is treated as a multibyte sequence (and
3608 not bytes) and the result is converted as with calls to @code{mbrtowc}.
3611 This is an alias for @samp{%lc} which is supported for compatibility
3612 with the Unix standard.
3615 Matches a pointer value in the same implementation-defined format used
3616 by the @samp{%p} output conversion for @code{printf}. @xref{Other Input
3620 This conversion doesn't read any characters; it records the number of
3621 characters read so far by this call. @xref{Other Input Conversions}.
3624 This matches a literal @samp{%} character in the input stream. No
3625 corresponding argument is used. @xref{Other Input Conversions}.
3628 If the syntax of a conversion specification is invalid, the behavior is
3629 undefined. If there aren't enough function arguments provided to supply
3630 addresses for all the conversion specifications in the template strings
3631 that perform assignments, or if the arguments are not of the correct
3632 types, the behavior is also undefined. On the other hand, extra
3633 arguments are simply ignored.
3635 @node Numeric Input Conversions
3636 @subsection Numeric Input Conversions
3638 This section describes the @code{scanf} conversions for reading numeric
3641 The @samp{%d} conversion matches an optionally signed integer in decimal
3642 radix. The syntax that is recognized is the same as that for the
3643 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3644 @code{10} for the @var{base} argument.
3646 The @samp{%i} conversion matches an optionally signed integer in any of
3647 the formats that the C language defines for specifying an integer
3648 constant. The syntax that is recognized is the same as that for the
3649 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3650 @code{0} for the @var{base} argument. (You can print integers in this
3651 syntax with @code{printf} by using the @samp{#} flag character with the
3652 @samp{%x}, @samp{%o}, @samp{%b}, or @samp{%d} conversion.
3653 @xref{Integer Conversions}.)
3655 For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
3656 could be read in as integers under the @samp{%i} conversion. Each of
3657 these specifies a number with decimal value @code{10}.
3659 The @samp{%b}, @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned
3660 integers in binary, octal, decimal, and hexadecimal radices, respectively. The
3661 syntax that is recognized is the same as that for the @code{strtoul}
3662 function (@pxref{Parsing of Integers}) with the appropriate value
3663 (@code{2}, @code{8}, @code{10}, or @code{16}) for the @var{base}
3664 argument. The @samp{%b} conversion accepts an optional leading
3665 @samp{0b} or @samp{0B} in all standards modes.
3667 The @samp{%X} conversion is identical to the @samp{%x} conversion. They
3668 both permit either uppercase or lowercase letters to be used as digits.
3670 The default type of the corresponding argument for the @code{%d},
3671 @code{%i}, and @code{%n} conversions is @code{int *}, and
3672 @code{unsigned int *} for the other integer conversions. You can use
3673 the following type modifiers to specify other sizes of integer:
3677 Specifies that the argument is a @code{signed char *} or @code{unsigned
3680 This modifier was introduced in @w{ISO C99}.
3683 Specifies that the argument is a @code{short int *} or @code{unsigned
3687 Specifies that the argument is a @code{intmax_t *} or @code{uintmax_t *}.
3689 This modifier was introduced in @w{ISO C99}.
3692 Specifies that the argument is a @code{long int *} or @code{unsigned
3693 long int *}. Two @samp{l} characters is like the @samp{L} modifier, below.
3695 If used with @samp{%c} or @samp{%s} the corresponding parameter is
3696 considered as a pointer to a wide character or wide character string
3697 respectively. This use of @samp{l} was introduced in @w{Amendment 1} to
3704 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
3705 GNU C compiler. For systems that don't provide extra-long integers, this
3706 is the same as @code{long int}.)
3708 The @samp{q} modifier is another name for the same thing, which comes
3709 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
3713 Specifies that the argument is a @code{ptrdiff_t *}.
3715 This modifier was introduced in @w{ISO C99}.
3718 Specifies that the argument is a @code{size_t *}.
3720 This modifier was introduced in @w{ISO C99}.
3723 All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%F} and @samp{%G}
3724 input conversions are interchangeable. They all match an optionally
3725 signed floating point number, in the same syntax as for the
3726 @code{strtod} function (@pxref{Parsing of Floats}).
3728 For the floating-point input conversions, the default argument type is
3729 @code{float *}. (This is different from the corresponding output
3730 conversions, where the default type is @code{double}; remember that
3731 @code{float} arguments to @code{printf} are converted to @code{double}
3732 by the default argument promotions, but @code{float *} arguments are
3733 not promoted to @code{double *}.) You can specify other sizes of float
3734 using these type modifiers:
3738 Specifies that the argument is of type @code{double *}.
3741 Specifies that the argument is of type @code{long double *}.
3744 For all the above number parsing formats there is an additional optional
3745 flag @samp{'}. When this flag is given the @code{scanf} function
3746 expects the number represented in the input string to be formatted
3747 according to the grouping rules of the currently selected locale
3748 (@pxref{General Numeric}).
3750 If the @code{"C"} or @code{"POSIX"} locale is selected there is no
3751 difference. But for a locale which specifies values for the appropriate
3752 fields in the locale the input must have the correct form in the input.
3753 Otherwise the longest prefix with a correct form is processed.
3755 @node String Input Conversions
3756 @subsection String Input Conversions
3758 This section describes the @code{scanf} input conversions for reading
3759 string and character values: @samp{%s}, @samp{%S}, @samp{%[}, @samp{%c},
3762 You have two options for how to receive the input from these
3767 Provide a buffer to store it in. This is the default. You should
3768 provide an argument of type @code{char *} or @code{wchar_t *} (the
3769 latter if the @samp{l} modifier is present).
3771 @strong{Warning:} To make a robust program, you must make sure that the
3772 input (plus its terminating null) cannot possibly exceed the size of the
3773 buffer you provide. In general, the only way to do this is to specify a
3774 maximum field width one less than the buffer size. @strong{If you
3775 provide the buffer, always specify a maximum field width to prevent
3779 Ask @code{scanf} to allocate a big enough buffer, by specifying the
3780 @samp{a} flag character. This is a GNU extension. You should provide
3781 an argument of type @code{char **} for the buffer address to be stored
3782 in. @xref{Dynamic String Input}.
3785 The @samp{%c} conversion is the simplest: it matches a fixed number of
3786 characters, always. The maximum field width says how many characters to
3787 read; if you don't specify the maximum, the default is 1. This
3788 conversion doesn't append a null character to the end of the text it
3789 reads. It also does not skip over initial whitespace characters. It
3790 reads precisely the next @var{n} characters, and fails if it cannot get
3791 that many. Since there is always a maximum field width with @samp{%c}
3792 (whether specified, or 1 by default), you can always prevent overflow by
3793 making the buffer long enough.
3794 @comment Is character == byte here??? --drepper
3796 If the format is @samp{%lc} or @samp{%C} the function stores wide
3797 characters which are converted using the conversion determined at the
3798 time the stream was opened from the external byte stream. The number of
3799 bytes read from the medium is limited by @code{MB_CUR_LEN * @var{n}} but
3800 at most @var{n} wide characters get stored in the output string.
3802 The @samp{%s} conversion matches a string of non-whitespace characters.
3803 It skips and discards initial whitespace, but stops when it encounters
3804 more whitespace after having read something. It stores a null character
3805 at the end of the text that it reads.
3807 For example, reading the input:
3814 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
3815 reading the same input with the conversion @samp{%10s} produces
3818 @strong{Warning:} If you do not specify a field width for @samp{%s},
3819 then the number of characters read is limited only by where the next
3820 whitespace character appears. This almost certainly means that invalid
3821 input can make your program crash---which is a bug.
3823 The @samp{%ls} and @samp{%S} format are handled just like @samp{%s}
3824 except that the external byte sequence is converted using the conversion
3825 associated with the stream to wide characters with their own encoding.
3826 A width or precision specified with the format do not directly determine
3827 how many bytes are read from the stream since they measure wide
3828 characters. But an upper limit can be computed by multiplying the value
3829 of the width or precision by @code{MB_CUR_MAX}.
3831 To read in characters that belong to an arbitrary set of your choice,
3832 use the @samp{%[} conversion. You specify the set between the @samp{[}
3833 character and a following @samp{]} character, using the same syntax used
3834 in regular expressions for explicit sets of characters. As special cases:
3838 A literal @samp{]} character can be specified as the first character
3842 An embedded @samp{-} character (that is, one that is not the first or
3843 last character of the set) is used to specify a range of characters.
3846 If a caret character @samp{^} immediately follows the initial @samp{[},
3847 then the set of allowed input characters is everything @emph{except}
3848 the characters listed.
3851 The @samp{%[} conversion does not skip over initial whitespace
3854 Note that the @dfn{character class} syntax available in character sets
3855 that appear inside regular expressions (such as @samp{[:alpha:]}) is
3856 @emph{not} available in the @samp{%[} conversion.
3858 Here are some examples of @samp{%[} conversions and what they mean:
3861 @item %25[1234567890]
3862 Matches a string of up to 25 digits.
3865 Matches a string of up to 25 square brackets.
3867 @item %25[^ \f\n\r\t\v]
3868 Matches a string up to 25 characters long that doesn't contain any of
3869 the standard whitespace characters. This is slightly different from
3870 @samp{%s}, because if the input begins with a whitespace character,
3871 @samp{%[} reports a matching failure while @samp{%s} simply discards the
3875 Matches up to 25 lowercase characters.
3878 As for @samp{%c} and @samp{%s} the @samp{%[} format is also modified to
3879 produce wide characters if the @samp{l} modifier is present. All what
3880 is said about @samp{%ls} above is true for @samp{%l[}.
3882 One more reminder: the @samp{%s} and @samp{%[} conversions are
3883 @strong{dangerous} if you don't specify a maximum width or use the
3884 @samp{a} flag, because input too long would overflow whatever buffer you
3885 have provided for it. No matter how long your buffer is, a user could
3886 supply input that is longer. A well-written program reports invalid
3887 input with a comprehensible error message, not with a crash.
3889 @node Dynamic String Input
3890 @subsection Dynamically Allocating String Conversions
3892 A GNU extension to formatted input lets you safely read a string with no
3893 maximum size. Using this feature, you don't supply a buffer; instead,
3894 @code{scanf} allocates a buffer big enough to hold the data and gives
3895 you its address. To use this feature, write @samp{a} as a flag
3896 character, as in @samp{%as} or @samp{%a[0-9a-z]}.
3898 The pointer argument you supply for where to store the input should have
3899 type @code{char **}. The @code{scanf} function allocates a buffer and
3900 stores its address in the word that the argument points to. You should
3901 free the buffer with @code{free} when you no longer need it.
3903 Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]}
3904 conversion specification to read a ``variable assignment'' of the form
3905 @samp{@var{variable} = @var{value}}.
3909 char *variable, *value;
3911 if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
3914 invalid_input_error ();
3922 @node Other Input Conversions
3923 @subsection Other Input Conversions
3925 This section describes the miscellaneous input conversions.
3927 The @samp{%p} conversion is used to read a pointer value. It recognizes
3928 the same syntax used by the @samp{%p} output conversion for
3929 @code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
3930 number just as the @samp{%x} conversion accepts. The corresponding
3931 argument should be of type @code{void **}; that is, the address of a
3932 place to store a pointer.
3934 The resulting pointer value is not guaranteed to be valid if it was not
3935 originally written during the same program execution that reads it in.
3937 The @samp{%n} conversion produces the number of characters read so far
3938 by this call. The corresponding argument should be of type @code{int *},
3939 unless a type modifier is in effect (@pxref{Numeric Input Conversions}).
3940 This conversion works in the same way as the @samp{%n} conversion for
3941 @code{printf}; see @ref{Other Output Conversions}, for an example.
3943 The @samp{%n} conversion is the only mechanism for determining the
3944 success of literal matches or conversions with suppressed assignments.
3945 If the @samp{%n} follows the locus of a matching failure, then no value
3946 is stored for it since @code{scanf} returns before processing the
3947 @samp{%n}. If you store @code{-1} in that argument slot before calling
3948 @code{scanf}, the presence of @code{-1} after @code{scanf} indicates an
3949 error occurred before the @samp{%n} was reached.
3951 Finally, the @samp{%%} conversion matches a literal @samp{%} character
3952 in the input stream, without using an argument. This conversion does
3953 not permit any flags, field width, or type modifier to be specified.
3955 @node Formatted Input Functions
3956 @subsection Formatted Input Functions
3958 Here are the descriptions of the functions for performing formatted
3960 Prototypes for these functions are in the header file @file{stdio.h}.
3963 @deftypefun int scanf (const char *@var{template}, @dots{})
3964 @standards{ISO, stdio.h}
3965 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
3966 The @code{scanf} function reads formatted input from the stream
3967 @code{stdin} under the control of the template string @var{template}.
3968 The optional arguments are pointers to the places which receive the
3971 The return value is normally the number of successful assignments. If
3972 an end-of-file condition is detected before any matches are performed,
3973 including matches against whitespace and literal characters in the
3974 template, then @code{EOF} is returned.
3977 @deftypefun int wscanf (const wchar_t *@var{template}, @dots{})
3978 @standards{ISO, wchar.h}
3979 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
3980 The @code{wscanf} function reads formatted input from the stream
3981 @code{stdin} under the control of the template string @var{template}.
3982 The optional arguments are pointers to the places which receive the
3985 The return value is normally the number of successful assignments. If
3986 an end-of-file condition is detected before any matches are performed,
3987 including matches against whitespace and literal characters in the
3988 template, then @code{WEOF} is returned.
3991 @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
3992 @standards{ISO, stdio.h}
3993 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
3994 This function is just like @code{scanf}, except that the input is read
3995 from the stream @var{stream} instead of @code{stdin}.
3998 @deftypefun int fwscanf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
3999 @standards{ISO, wchar.h}
4000 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
4001 This function is just like @code{wscanf}, except that the input is read
4002 from the stream @var{stream} instead of @code{stdin}.
4005 @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
4006 @standards{ISO, stdio.h}
4007 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
4008 This is like @code{scanf}, except that the characters are taken from the
4009 null-terminated string @var{s} instead of from a stream. Reaching the
4010 end of the string is treated as an end-of-file condition.
4012 The behavior of this function is undefined if copying takes place
4013 between objects that overlap---for example, if @var{s} is also given
4014 as an argument to receive a string read under control of the @samp{%s},
4015 @samp{%S}, or @samp{%[} conversion.
4018 @deftypefun int swscanf (const wchar_t *@var{ws}, const wchar_t *@var{template}, @dots{})
4019 @standards{ISO, wchar.h}
4020 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
4021 This is like @code{wscanf}, except that the characters are taken from the
4022 null-terminated string @var{ws} instead of from a stream. Reaching the
4023 end of the string is treated as an end-of-file condition.
4025 The behavior of this function is undefined if copying takes place
4026 between objects that overlap---for example, if @var{ws} is also given as
4027 an argument to receive a string read under control of the @samp{%s},
4028 @samp{%S}, or @samp{%[} conversion.
4031 @node Variable Arguments Input
4032 @subsection Variable Arguments Input Functions
4034 The functions @code{vscanf} and friends are provided so that you can
4035 define your own variadic @code{scanf}-like functions that make use of
4036 the same internals as the built-in formatted output functions.
4037 These functions are analogous to the @code{vprintf} series of output
4038 functions. @xref{Variable Arguments Output}, for important
4039 information on how to use them.
4041 @strong{Portability Note:} The functions listed in this section were
4042 introduced in @w{ISO C99} and were before available as GNU extensions.
4044 @deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
4045 @standards{ISO, stdio.h}
4046 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
4047 This function is similar to @code{scanf}, but instead of taking
4048 a variable number of arguments directly, it takes an argument list
4049 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
4052 @deftypefun int vwscanf (const wchar_t *@var{template}, va_list @var{ap})
4053 @standards{ISO, wchar.h}
4054 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
4055 This function is similar to @code{wscanf}, but instead of taking
4056 a variable number of arguments directly, it takes an argument list
4057 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
4060 @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
4061 @standards{ISO, stdio.h}
4062 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
4063 This is the equivalent of @code{fscanf} with the variable argument list
4064 specified directly as for @code{vscanf}.
4067 @deftypefun int vfwscanf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
4068 @standards{ISO, wchar.h}
4069 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
4070 This is the equivalent of @code{fwscanf} with the variable argument list
4071 specified directly as for @code{vwscanf}.
4074 @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
4075 @standards{ISO, stdio.h}
4076 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
4077 This is the equivalent of @code{sscanf} with the variable argument list
4078 specified directly as for @code{vscanf}.
4081 @deftypefun int vswscanf (const wchar_t *@var{s}, const wchar_t *@var{template}, va_list @var{ap})
4082 @standards{ISO, wchar.h}
4083 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
4084 This is the equivalent of @code{swscanf} with the variable argument list
4085 specified directly as for @code{vwscanf}.
4088 In GNU C, there is a special construct you can use to let the compiler
4089 know that a function uses a @code{scanf}-style format string. Then it
4090 can check the number and types of arguments in each call to the
4091 function, and warn you when they do not match the format string.
4092 For details, see @ref{Function Attributes, , Declaring Attributes of Functions,
4095 @node EOF and Errors
4096 @section End-Of-File and Errors
4098 @cindex end of file, on a stream
4099 Many of the functions described in this chapter return the value of the
4100 macro @code{EOF} to indicate unsuccessful completion of the operation.
4101 Since @code{EOF} is used to report both end of file and random errors,
4102 it's often better to use the @code{feof} function to check explicitly
4103 for end of file and @code{ferror} to check for errors. These functions
4104 check indicators that are part of the internal state of the stream
4105 object, indicators set if the appropriate condition was detected by a
4106 previous I/O operation on that stream.
4108 @deftypevr Macro int EOF
4109 @standards{ISO, stdio.h}
4110 This macro is an integer value that is returned by a number of narrow
4111 stream functions to indicate an end-of-file condition, or some other
4112 error situation. With @theglibc{}, @code{EOF} is @code{-1}. In
4113 other libraries, its value may be some other negative number.
4115 This symbol is declared in @file{stdio.h}.
4118 @deftypevr Macro int WEOF
4119 @standards{ISO, wchar.h}
4120 This macro is an integer value that is returned by a number of wide
4121 stream functions to indicate an end-of-file condition, or some other
4122 error situation. With @theglibc{}, @code{WEOF} is @code{-1}. In
4123 other libraries, its value may be some other negative number.
4125 This symbol is declared in @file{wchar.h}.
4128 @deftypefun int feof (FILE *@var{stream})
4129 @standards{ISO, stdio.h}
4130 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
4131 The @code{feof} function returns nonzero if and only if the end-of-file
4132 indicator for the stream @var{stream} is set.
4134 This symbol is declared in @file{stdio.h}.
4137 @deftypefun int feof_unlocked (FILE *@var{stream})
4138 @standards{GNU, stdio.h}
4139 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
4140 @c There isn't much of a thread unsafety risk in reading a flag word and
4141 @c testing a bit in it.
4142 The @code{feof_unlocked} function is equivalent to the @code{feof}
4143 function except that it does not implicitly lock the stream.
4145 This function is a GNU extension.
4147 This symbol is declared in @file{stdio.h}.
4150 @deftypefun int ferror (FILE *@var{stream})
4151 @standards{ISO, stdio.h}
4152 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
4153 The @code{ferror} function returns nonzero if and only if the error
4154 indicator for the stream @var{stream} is set, indicating that an error
4155 has occurred on a previous operation on the stream.
4157 This symbol is declared in @file{stdio.h}.
4160 @deftypefun int ferror_unlocked (FILE *@var{stream})
4161 @standards{GNU, stdio.h}
4162 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
4163 The @code{ferror_unlocked} function is equivalent to the @code{ferror}
4164 function except that it does not implicitly lock the stream.
4166 This function is a GNU extension.
4168 This symbol is declared in @file{stdio.h}.
4171 In addition to setting the error indicator associated with the stream,
4172 the functions that operate on streams also set @code{errno} in the same
4173 way as the corresponding low-level functions that operate on file
4174 descriptors. For example, all of the functions that perform output to a
4175 stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are
4176 implemented in terms of @code{write}, and all of the @code{errno} error
4177 conditions defined for @code{write} are meaningful for these functions.
4178 For more information about the descriptor-level I/O functions, see
4179 @ref{Low-Level I/O}.
4181 @node Error Recovery
4182 @section Recovering from errors
4184 You may explicitly clear the error and EOF flags with the @code{clearerr}
4187 @deftypefun void clearerr (FILE *@var{stream})
4188 @standards{ISO, stdio.h}
4189 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
4190 This function clears the end-of-file and error indicators for the
4191 stream @var{stream}.
4193 The file positioning functions (@pxref{File Positioning}) also clear the
4194 end-of-file indicator for the stream.
4197 @deftypefun void clearerr_unlocked (FILE *@var{stream})
4198 @standards{GNU, stdio.h}
4199 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@assafe{}@acsafe{}}
4200 The @code{clearerr_unlocked} function is equivalent to the @code{clearerr}
4201 function except that it does not implicitly lock the stream.
4203 This function is a GNU extension.
4206 Note that it is @emph{not} correct to just clear the error flag and retry
4207 a failed stream operation. After a failed write, any number of
4208 characters since the last buffer flush may have been committed to the
4209 file, while some buffered data may have been discarded. Merely retrying
4210 can thus cause lost or repeated data.
4212 A failed read may leave the file pointer in an inappropriate position for
4213 a second try. In both cases, you should seek to a known position before
4216 Most errors that can happen are not recoverable --- a second try will
4217 always fail again in the same way. So usually it is best to give up and
4218 report the error to the user, rather than install complicated recovery
4221 One important exception is @code{EINTR} (@pxref{Interrupted Primitives}).
4222 Many stream I/O implementations will treat it as an ordinary error, which
4223 can be quite inconvenient. You can avoid this hassle by installing all
4224 signals with the @code{SA_RESTART} flag.
4226 For similar reasons, setting nonblocking I/O on a stream's file
4227 descriptor is not usually advisable.
4229 @node Binary Streams
4230 @section Text and Binary Streams
4232 @gnusystems{} and other POSIX-compatible operating systems organize all
4233 files as uniform sequences of characters. However, some other systems
4234 make a distinction between files containing text and files containing
4235 binary data, and the input and output facilities of @w{ISO C} provide for
4236 this distinction. This section tells you how to write programs portable
4240 @cindex binary stream
4241 When you open a stream, you can specify either a @dfn{text stream} or a
4242 @dfn{binary stream}. You indicate that you want a binary stream by
4243 specifying the @samp{b} modifier in the @var{opentype} argument to
4244 @code{fopen}; see @ref{Opening Streams}. Without this
4245 option, @code{fopen} opens the file as a text stream.
4247 Text and binary streams differ in several ways:
4251 The data read from a text stream is divided into @dfn{lines} which are
4252 terminated by newline (@code{'\n'}) characters, while a binary stream is
4253 simply a long series of characters. A text stream might on some systems
4254 fail to handle lines more than 254 characters long (including the
4255 terminating newline character).
4256 @cindex lines (in a text file)
4259 On some systems, text files can contain only printing characters,
4260 horizontal tab characters, and newlines, and so text streams may not
4261 support other characters. However, binary streams can handle any
4265 Space characters that are written immediately preceding a newline
4266 character in a text stream may disappear when the file is read in again.
4269 More generally, there need not be a one-to-one mapping between
4270 characters that are read from or written to a text stream, and the
4271 characters in the actual file.
4274 Since a binary stream is always more capable and more predictable than a
4275 text stream, you might wonder what purpose text streams serve. Why not
4276 simply always use binary streams? The answer is that on these operating
4277 systems, text and binary streams use different file formats, and the
4278 only way to read or write ``an ordinary file of text'' that can work
4279 with other text-oriented programs is through a text stream.
4281 In @theglibc{}, and on all POSIX systems, there is no difference
4282 between text streams and binary streams. When you open a stream, you
4283 get the same kind of stream regardless of whether you ask for binary.
4284 This stream can handle any file content, and has none of the
4285 restrictions that text streams sometimes have.
4287 @node File Positioning
4288 @section File Positioning
4289 @cindex file positioning on a stream
4290 @cindex positioning a stream
4291 @cindex seeking on a stream
4293 The @dfn{file position} of a stream describes where in the file the
4294 stream is currently reading or writing. I/O on the stream advances the
4295 file position through the file. On @gnusystems{}, the file position is
4296 represented as an integer, which counts the number of bytes from the
4297 beginning of the file. @xref{File Position}.
4299 During I/O to an ordinary disk file, you can change the file position
4300 whenever you wish, so as to read or write any portion of the file. Some
4301 other kinds of files may also permit this. Files which support changing
4302 the file position are sometimes referred to as @dfn{random-access}
4305 You can use the functions in this section to examine or modify the file
4306 position indicator associated with a stream. The symbols listed below
4307 are declared in the header file @file{stdio.h}.
4310 @deftypefun {long int} ftell (FILE *@var{stream})
4311 @standards{ISO, stdio.h}
4312 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4313 This function returns the current file position of the stream
4316 This function can fail if the stream doesn't support file positioning,
4317 or if the file position can't be represented in a @code{long int}, and
4318 possibly for other reasons as well. If a failure occurs, a value of
4319 @code{-1} is returned.
4322 @deftypefun off_t ftello (FILE *@var{stream})
4323 @standards{Unix98, stdio.h}
4324 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4325 The @code{ftello} function is similar to @code{ftell}, except that it
4326 returns a value of type @code{off_t}. Systems which support this type
4327 use it to describe all file positions, unlike the POSIX specification
4328 which uses a long int. The two are not necessarily the same size.
4329 Therefore, using ftell can lead to problems if the implementation is
4330 written on top of a POSIX compliant low-level I/O implementation, and using
4331 @code{ftello} is preferable whenever it is available.
4333 If this function fails it returns @code{(off_t) -1}. This can happen due
4334 to missing support for file positioning or internal errors. Otherwise
4335 the return value is the current file position.
4337 The function is an extension defined in the Unix Single Specification
4340 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4341 32 bit system this function is in fact @code{ftello64}. I.e., the
4342 LFS interface transparently replaces the old interface.
4345 @deftypefun off64_t ftello64 (FILE *@var{stream})
4346 @standards{Unix98, stdio.h}
4347 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4348 This function is similar to @code{ftello} with the only difference that
4349 the return value is of type @code{off64_t}. This also requires that the
4350 stream @var{stream} was opened using either @code{fopen64},
4351 @code{freopen64}, or @code{tmpfile64} since otherwise the underlying
4352 file operations to position the file pointer beyond the @twoexp{31}
4353 bytes limit might fail.
4355 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4356 bits machine this function is available under the name @code{ftello}
4357 and so transparently replaces the old interface.
4360 @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
4361 @standards{ISO, stdio.h}
4362 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4363 The @code{fseek} function is used to change the file position of the
4364 stream @var{stream}. The value of @var{whence} must be one of the
4365 constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
4366 indicate whether the @var{offset} is relative to the beginning of the
4367 file, the current file position, or the end of the file, respectively.
4369 This function returns a value of zero if the operation was successful,
4370 and a nonzero value to indicate failure. A successful call also clears
4371 the end-of-file indicator of @var{stream} and discards any characters
4372 that were ``pushed back'' by the use of @code{ungetc}.
4374 @code{fseek} either flushes any buffered output before setting the file
4375 position or else remembers it so it will be written later in its proper
4379 @deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence})
4380 @standards{Unix98, stdio.h}
4381 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4382 This function is similar to @code{fseek} but it corrects a problem with
4383 @code{fseek} in a system with POSIX types. Using a value of type
4384 @code{long int} for the offset is not compatible with POSIX.
4385 @code{fseeko} uses the correct type @code{off_t} for the @var{offset}
4388 For this reason it is a good idea to prefer @code{ftello} whenever it is
4389 available since its functionality is (if different at all) closer the
4390 underlying definition.
4392 The functionality and return value are the same as for @code{fseek}.
4394 The function is an extension defined in the Unix Single Specification
4397 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4398 32 bit system this function is in fact @code{fseeko64}. I.e., the
4399 LFS interface transparently replaces the old interface.
4402 @deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence})
4403 @standards{Unix98, stdio.h}
4404 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4405 This function is similar to @code{fseeko} with the only difference that
4406 the @var{offset} parameter is of type @code{off64_t}. This also
4407 requires that the stream @var{stream} was opened using either
4408 @code{fopen64}, @code{freopen64}, or @code{tmpfile64} since otherwise
4409 the underlying file operations to position the file pointer beyond the
4410 @twoexp{31} bytes limit might fail.
4412 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4413 bits machine this function is available under the name @code{fseeko}
4414 and so transparently replaces the old interface.
4417 @strong{Portability Note:} In non-POSIX systems, @code{ftell},
4418 @code{ftello}, @code{fseek} and @code{fseeko} might work reliably only
4419 on binary streams. @xref{Binary Streams}.
4421 The following symbolic constants are defined for use as the @var{whence}
4422 argument to @code{fseek}. They are also used with the @code{lseek}
4423 function (@pxref{I/O Primitives}) and to specify offsets for file locks
4424 (@pxref{Control Operations}).
4426 @deftypevr Macro int SEEK_SET
4427 @standards{ISO, stdio.h}
4428 This is an integer constant which, when used as the @var{whence}
4429 argument to the @code{fseek} or @code{fseeko} functions, specifies that
4430 the offset provided is relative to the beginning of the file.
4433 @deftypevr Macro int SEEK_CUR
4434 @standards{ISO, stdio.h}
4435 This is an integer constant which, when used as the @var{whence}
4436 argument to the @code{fseek} or @code{fseeko} functions, specifies that
4437 the offset provided is relative to the current file position.
4440 @deftypevr Macro int SEEK_END
4441 @standards{ISO, stdio.h}
4442 This is an integer constant which, when used as the @var{whence}
4443 argument to the @code{fseek} or @code{fseeko} functions, specifies that
4444 the offset provided is relative to the end of the file.
4447 @deftypefun void rewind (FILE *@var{stream})
4448 @standards{ISO, stdio.h}
4449 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4450 The @code{rewind} function positions the stream @var{stream} at the
4451 beginning of the file. It is equivalent to calling @code{fseek} or
4452 @code{fseeko} on the @var{stream} with an @var{offset} argument of
4453 @code{0L} and a @var{whence} argument of @code{SEEK_SET}, except that
4454 the return value is discarded and the error indicator for the stream is
4458 These three aliases for the @samp{SEEK_@dots{}} constants exist for the
4459 sake of compatibility with older BSD systems. They are defined in two
4460 different header files: @file{fcntl.h} and @file{sys/file.h}.
4464 @standards{BSD, sys/file.h}
4465 An alias for @code{SEEK_SET}.
4468 @standards{BSD, sys/file.h}
4469 An alias for @code{SEEK_CUR}.
4472 @standards{BSD, sys/file.h}
4473 An alias for @code{SEEK_END}.
4476 @node Portable Positioning
4477 @section Portable File-Position Functions
4479 On @gnusystems{}, the file position is truly a character count. You
4480 can specify any character count value as an argument to @code{fseek} or
4481 @code{fseeko} and get reliable results for any random access file.
4482 However, some @w{ISO C} systems do not represent file positions in this
4485 On some systems where text streams truly differ from binary streams, it
4486 is impossible to represent the file position of a text stream as a count
4487 of characters from the beginning of the file. For example, the file
4488 position on some systems must encode both a record offset within the
4489 file, and a character offset within the record.
4491 As a consequence, if you want your programs to be portable to these
4492 systems, you must observe certain rules:
4496 The value returned from @code{ftell} on a text stream has no predictable
4497 relationship to the number of characters you have read so far. The only
4498 thing you can rely on is that you can use it subsequently as the
4499 @var{offset} argument to @code{fseek} or @code{fseeko} to move back to
4500 the same file position.
4503 In a call to @code{fseek} or @code{fseeko} on a text stream, either the
4504 @var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and
4505 the @var{offset} must be the result of an earlier call to @code{ftell}
4509 The value of the file position indicator of a text stream is undefined
4510 while there are characters that have been pushed back with @code{ungetc}
4511 that haven't been read or discarded. @xref{Unreading}.
4514 But even if you observe these rules, you may still have trouble for long
4515 files, because @code{ftell} and @code{fseek} use a @code{long int} value
4516 to represent the file position. This type may not have room to encode
4517 all the file positions in a large file. Using the @code{ftello} and
4518 @code{fseeko} functions might help here since the @code{off_t} type is
4519 expected to be able to hold all file position values but this still does
4520 not help to handle additional information which must be associated with
4523 So if you do want to support systems with peculiar encodings for the
4524 file positions, it is better to use the functions @code{fgetpos} and
4525 @code{fsetpos} instead. These functions represent the file position
4526 using the data type @code{fpos_t}, whose internal representation varies
4527 from system to system.
4529 These symbols are declared in the header file @file{stdio.h}.
4532 @deftp {Data Type} fpos_t
4533 @standards{ISO, stdio.h}
4534 This is the type of an object that can encode information about the
4535 file position of a stream, for use by the functions @code{fgetpos} and
4538 In @theglibc{}, @code{fpos_t} is an opaque data structure that
4539 contains internal data to represent file offset and conversion state
4540 information. In other systems, it might have a different internal
4543 When compiling with @code{_FILE_OFFSET_BITS == 64} on a 32 bit machine
4544 this type is in fact equivalent to @code{fpos64_t} since the LFS
4545 interface transparently replaces the old interface.
4548 @deftp {Data Type} fpos64_t
4549 @standards{Unix98, stdio.h}
4550 This is the type of an object that can encode information about the
4551 file position of a stream, for use by the functions @code{fgetpos64} and
4554 In @theglibc{}, @code{fpos64_t} is an opaque data structure that
4555 contains internal data to represent file offset and conversion state
4556 information. In other systems, it might have a different internal
4560 @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
4561 @standards{ISO, stdio.h}
4562 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4563 This function stores the value of the file position indicator for the
4564 stream @var{stream} in the @code{fpos_t} object pointed to by
4565 @var{position}. If successful, @code{fgetpos} returns zero; otherwise
4566 it returns a nonzero value and stores an implementation-defined positive
4567 value in @code{errno}.
4569 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4570 32 bit system the function is in fact @code{fgetpos64}. I.e., the LFS
4571 interface transparently replaces the old interface.
4574 @deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position})
4575 @standards{Unix98, stdio.h}
4576 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4577 This function is similar to @code{fgetpos} but the file position is
4578 returned in a variable of type @code{fpos64_t} to which @var{position}
4581 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4582 bits machine this function is available under the name @code{fgetpos}
4583 and so transparently replaces the old interface.
4586 @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position})
4587 @standards{ISO, stdio.h}
4588 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4589 This function sets the file position indicator for the stream @var{stream}
4590 to the position @var{position}, which must have been set by a previous
4591 call to @code{fgetpos} on the same stream. If successful, @code{fsetpos}
4592 clears the end-of-file indicator on the stream, discards any characters
4593 that were ``pushed back'' by the use of @code{ungetc}, and returns a value
4594 of zero. Otherwise, @code{fsetpos} returns a nonzero value and stores
4595 an implementation-defined positive value in @code{errno}.
4597 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4598 32 bit system the function is in fact @code{fsetpos64}. I.e., the LFS
4599 interface transparently replaces the old interface.
4602 @deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position})
4603 @standards{Unix98, stdio.h}
4604 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4605 This function is similar to @code{fsetpos} but the file position used
4606 for positioning is provided in a variable of type @code{fpos64_t} to
4607 which @var{position} points.
4609 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4610 bits machine this function is available under the name @code{fsetpos}
4611 and so transparently replaces the old interface.
4614 @node Stream Buffering
4615 @section Stream Buffering
4617 @cindex buffering of streams
4618 Characters that are written to a stream are normally accumulated and
4619 transmitted asynchronously to the file in a block, instead of appearing
4620 as soon as they are output by the application program. Similarly,
4621 streams often retrieve input from the host environment in blocks rather
4622 than on a character-by-character basis. This is called @dfn{buffering}.
4624 If you are writing programs that do interactive input and output using
4625 streams, you need to understand how buffering works when you design the
4626 user interface to your program. Otherwise, you might find that output
4627 (such as progress or prompt messages) doesn't appear when you intended
4628 it to, or displays some other unexpected behavior.
4630 This section deals only with controlling when characters are transmitted
4631 between the stream and the file or device, and @emph{not} with how
4632 things like echoing, flow control, and the like are handled on specific
4633 classes of devices. For information on common control operations on
4634 terminal devices, see @ref{Low-Level Terminal Interface}.
4636 You can bypass the stream buffering facilities altogether by using the
4637 low-level input and output functions that operate on file descriptors
4638 instead. @xref{Low-Level I/O}.
4641 * Buffering Concepts:: Terminology is defined here.
4642 * Flushing Buffers:: How to ensure that output buffers are flushed.
4643 * Controlling Buffering:: How to specify what kind of buffering to use.
4646 @node Buffering Concepts
4647 @subsection Buffering Concepts
4649 There are three different kinds of buffering strategies:
4653 Characters written to or read from an @dfn{unbuffered} stream are
4654 transmitted individually to or from the file as soon as possible.
4655 @cindex unbuffered stream
4658 Characters written to a @dfn{line buffered} stream are transmitted to
4659 the file in blocks when a newline character is encountered.
4660 @cindex line buffered stream
4663 Characters written to or read from a @dfn{fully buffered} stream are
4664 transmitted to or from the file in blocks of arbitrary size.
4665 @cindex fully buffered stream
4668 Newly opened streams are normally fully buffered, with one exception: a
4669 stream connected to an interactive device such as a terminal is
4670 initially line buffered. @xref{Controlling Buffering}, for information
4671 on how to select a different kind of buffering. Usually the automatic
4672 selection gives you the most convenient kind of buffering for the file
4675 The use of line buffering for interactive devices implies that output
4676 messages ending in a newline will appear immediately---which is usually
4677 what you want. Output that doesn't end in a newline might or might not
4678 show up immediately, so if you want them to appear immediately, you
4679 should flush buffered output explicitly with @code{fflush}, as described
4680 in @ref{Flushing Buffers}.
4682 @node Flushing Buffers
4683 @subsection Flushing Buffers
4685 @cindex flushing a stream
4686 @dfn{Flushing} output on a buffered stream means transmitting all
4687 accumulated characters to the file. There are many circumstances when
4688 buffered output on a stream is flushed automatically:
4692 When you try to do output and the output buffer is full.
4695 When the stream is closed. @xref{Closing Streams}.
4698 When the program terminates by calling @code{exit}.
4699 @xref{Normal Termination}.
4702 When a newline is written, if the stream is line buffered.
4705 Whenever an input operation on @emph{any} stream actually reads data
4709 If you want to flush the buffered output at another time, call
4710 @code{fflush}, which is declared in the header file @file{stdio.h}.
4713 @deftypefun int fflush (FILE *@var{stream})
4714 @standards{ISO, stdio.h}
4715 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4716 This function causes any buffered output on @var{stream} to be delivered
4717 to the file. If @var{stream} is a null pointer, then
4718 @code{fflush} causes buffered output on @emph{all} open output streams
4721 This function returns @code{EOF} if a write error occurs, or zero
4725 @deftypefun int fflush_unlocked (FILE *@var{stream})
4726 @standards{POSIX, stdio.h}
4727 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
4728 The @code{fflush_unlocked} function is equivalent to the @code{fflush}
4729 function except that it does not implicitly lock the stream.
4732 The @code{fflush} function can be used to flush all streams currently
4733 opened. While this is useful in some situations it does often more than
4734 necessary since it might be done in situations when terminal input is
4735 required and the program wants to be sure that all output is visible on
4736 the terminal. But this means that only line buffered streams have to be
4737 flushed. Solaris introduced a function especially for this. It was
4738 always available in @theglibc{} in some form but never officially
4741 @deftypefun void _flushlbf (void)
4742 @standards{GNU, stdio_ext.h}
4743 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4744 The @code{_flushlbf} function flushes all line buffered streams
4747 This function is declared in the @file{stdio_ext.h} header.
4750 @strong{Compatibility Note:} Some brain-damaged operating systems have
4751 been known to be so thoroughly fixated on line-oriented input and output
4752 that flushing a line buffered stream causes a newline to be written!
4753 Fortunately, this ``feature'' seems to be becoming less common. You do
4754 not need to worry about this with @theglibc{}.
4756 In some situations it might be useful to not flush the output pending
4757 for a stream but instead simply forget it. If transmission is costly
4758 and the output is not needed anymore this is valid reasoning. In this
4759 situation a non-standard function introduced in Solaris and available in
4760 @theglibc{} can be used.
4762 @deftypefun void __fpurge (FILE *@var{stream})
4763 @standards{GNU, stdio_ext.h}
4764 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
4765 The @code{__fpurge} function causes the buffer of the stream
4766 @var{stream} to be emptied. If the stream is currently in read mode all
4767 input in the buffer is lost. If the stream is in output mode the
4768 buffered output is not written to the device (or whatever other
4769 underlying storage) and the buffer is cleared.
4771 This function is declared in @file{stdio_ext.h}.
4774 @node Controlling Buffering
4775 @subsection Controlling Which Kind of Buffering
4777 After opening a stream (but before any other operations have been
4778 performed on it), you can explicitly specify what kind of buffering you
4779 want it to have using the @code{setvbuf} function.
4780 @cindex buffering, controlling
4782 The facilities listed in this section are declared in the header
4783 file @file{stdio.h}.
4786 @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
4787 @standards{ISO, stdio.h}
4788 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4789 This function is used to specify that the stream @var{stream} should
4790 have the buffering mode @var{mode}, which can be either @code{_IOFBF}
4791 (for full buffering), @code{_IOLBF} (for line buffering), or
4792 @code{_IONBF} (for unbuffered input/output).
4794 If you specify a null pointer as the @var{buf} argument, then @code{setvbuf}
4795 allocates a buffer itself using @code{malloc}. This buffer will be freed
4796 when you close the stream.
4798 Otherwise, @var{buf} should be a character array that can hold at least
4799 @var{size} characters. You should not free the space for this array as
4800 long as the stream remains open and this array remains its buffer. You
4801 should usually either allocate it statically, or @code{malloc}
4802 (@pxref{Unconstrained Allocation}) the buffer. Using an automatic array
4803 is not a good idea unless you close the file before exiting the block
4804 that declares the array.
4806 While the array remains a stream buffer, the stream I/O functions will
4807 use the buffer for their internal purposes. You shouldn't try to access
4808 the values in the array directly while the stream is using it for
4811 The @code{setvbuf} function returns zero on success, or a nonzero value
4812 if the value of @var{mode} is not valid or if the request could not
4816 @deftypevr Macro int _IOFBF
4817 @standards{ISO, stdio.h}
4818 The value of this macro is an integer constant expression that can be
4819 used as the @var{mode} argument to the @code{setvbuf} function to
4820 specify that the stream should be fully buffered.
4823 @deftypevr Macro int _IOLBF
4824 @standards{ISO, stdio.h}
4825 The value of this macro is an integer constant expression that can be
4826 used as the @var{mode} argument to the @code{setvbuf} function to
4827 specify that the stream should be line buffered.
4830 @deftypevr Macro int _IONBF
4831 @standards{ISO, stdio.h}
4832 The value of this macro is an integer constant expression that can be
4833 used as the @var{mode} argument to the @code{setvbuf} function to
4834 specify that the stream should be unbuffered.
4837 @deftypevr Macro int BUFSIZ
4838 @standards{ISO, stdio.h}
4839 The value of this macro is an integer constant expression that is good
4840 to use for the @var{size} argument to @code{setvbuf}. This value is
4841 guaranteed to be at least @code{256}.
4843 The value of @code{BUFSIZ} is chosen on each system so as to make stream
4844 I/O efficient. So it is a good idea to use @code{BUFSIZ} as the size
4845 for the buffer when you call @code{setvbuf}.
4847 Actually, you can get an even better value to use for the buffer size
4848 by means of the @code{fstat} system call: it is found in the
4849 @code{st_blksize} field of the file attributes. @xref{Attribute Meanings}.
4851 Sometimes people also use @code{BUFSIZ} as the allocation size of
4852 buffers used for related purposes, such as strings used to receive a
4853 line of input with @code{fgets} (@pxref{Character Input}). There is no
4854 particular reason to use @code{BUFSIZ} for this instead of any other
4855 integer, except that it might lead to doing I/O in chunks of an
4859 @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
4860 @standards{ISO, stdio.h}
4861 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4862 If @var{buf} is a null pointer, the effect of this function is
4863 equivalent to calling @code{setvbuf} with a @var{mode} argument of
4864 @code{_IONBF}. Otherwise, it is equivalent to calling @code{setvbuf}
4865 with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size}
4866 argument of @code{BUFSIZ}.
4868 The @code{setbuf} function is provided for compatibility with old code;
4869 use @code{setvbuf} in all new programs.
4872 @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
4873 @standards{BSD, stdio.h}
4874 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4875 If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
4876 Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
4877 buffer. The @var{size} argument specifies the length of @var{buf}.
4879 This function is provided for compatibility with old BSD code. Use
4880 @code{setvbuf} instead.
4883 @deftypefun void setlinebuf (FILE *@var{stream})
4884 @standards{BSD, stdio.h}
4885 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4886 This function makes @var{stream} be line buffered, and allocates the
4889 This function is provided for compatibility with old BSD code. Use
4890 @code{setvbuf} instead.
4893 It is possible to query whether a given stream is line buffered or not
4894 using a non-standard function introduced in Solaris and available in
4897 @deftypefun int __flbf (FILE *@var{stream})
4898 @standards{GNU, stdio_ext.h}
4899 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
4900 The @code{__flbf} function will return a nonzero value in case the
4901 stream @var{stream} is line buffered. Otherwise the return value is
4904 This function is declared in the @file{stdio_ext.h} header.
4907 Two more extensions allow to determine the size of the buffer and how
4908 much of it is used. These functions were also introduced in Solaris.
4910 @deftypefun size_t __fbufsize (FILE *@var{stream})
4911 @standards{GNU, stdio_ext.h}
4912 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}}
4913 The @code{__fbufsize} function return the size of the buffer in the
4914 stream @var{stream}. This value can be used to optimize the use of the
4917 This function is declared in the @file{stdio_ext.h} header.
4920 @deftypefun size_t __fpending (FILE *@var{stream})
4921 @standards{GNU, stdio_ext.h}
4922 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}}
4923 The @code{__fpending}
4924 function returns the number of bytes currently in the output buffer.
4925 For wide-oriented streams the measuring unit is wide characters. This
4926 function should not be used on buffers in read mode or opened read-only.
4928 This function is declared in the @file{stdio_ext.h} header.
4931 @node Other Kinds of Streams
4932 @section Other Kinds of Streams
4934 @Theglibc{} provides ways for you to define additional kinds of
4935 streams that do not necessarily correspond to an open file.
4937 One such type of stream takes input from or writes output to a string.
4938 These kinds of streams are used internally to implement the
4939 @code{sprintf} and @code{sscanf} functions. You can also create such a
4940 stream explicitly, using the functions described in @ref{String Streams}.
4942 More generally, you can define streams that do input/output to arbitrary
4943 objects using functions supplied by your program. This protocol is
4944 discussed in @ref{Custom Streams}.
4946 @strong{Portability Note:} The facilities described in this section are
4947 specific to GNU. Other systems or C implementations might or might not
4948 provide equivalent functionality.
4951 * String Streams:: Streams that get data from or put data in
4952 a string or memory buffer.
4953 * Custom Streams:: Defining your own streams with an arbitrary
4954 input data source and/or output data sink.
4957 @node String Streams
4958 @subsection String Streams
4960 @cindex stream, for I/O to a string
4961 @cindex string stream
4962 The @code{fmemopen} and @code{open_memstream} functions allow you to do
4963 I/O to a string or memory buffer. These facilities are declared in
4967 @deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
4968 @standards{GNU, stdio.h}
4969 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
4970 @c Unlike open_memstream, fmemopen does (indirectly) call _IO_link_in,
4971 @c bringing with it additional potential for async trouble with
4973 This function opens a stream that allows the access specified by the
4974 @var{opentype} argument, that reads from or writes to the buffer specified
4975 by the argument @var{buf}. This array must be at least @var{size} bytes long.
4977 If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
4978 dynamically allocates an array @var{size} bytes long (as with @code{malloc};
4979 @pxref{Unconstrained Allocation}). This is really only useful
4980 if you are going to write things to the buffer and then read them back
4981 in again, because you have no way of actually getting a pointer to the
4982 buffer (for this, try @code{open_memstream}, below). The buffer is
4983 freed when the stream is closed.
4985 The argument @var{opentype} is the same as in @code{fopen}
4986 (@pxref{Opening Streams}). If the @var{opentype} specifies
4987 append mode, then the initial file position is set to the first null
4988 character in the buffer. Otherwise the initial file position is at the
4989 beginning of the buffer.
4991 When a stream open for writing is flushed or closed, a null character
4992 (zero byte) is written at the end of the buffer if it fits. You
4993 should add an extra byte to the @var{size} argument to account for this.
4994 Attempts to write more than @var{size} bytes to the buffer result
4997 For a stream open for reading, null characters (zero bytes) in the
4998 buffer do not count as ``end of file''. Read operations indicate end of
4999 file only when the file position advances past @var{size} bytes. So, if
5000 you want to read characters from a null-terminated string, you should
5001 supply the length of the string as the @var{size} argument.
5004 Here is an example of using @code{fmemopen} to create a stream for
5005 reading from a string:
5008 @include memopen.c.texi
5011 This program produces the following output:
5022 @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
5023 @standards{GNU, stdio.h}
5024 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
5025 This function opens a stream for writing to a buffer. The buffer is
5026 allocated dynamically and grown as necessary, using @code{malloc}.
5027 After you've closed the stream, this buffer is your responsibility to
5028 clean up using @code{free} or @code{realloc}. @xref{Unconstrained Allocation}.
5030 When the stream is closed with @code{fclose} or flushed with
5031 @code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
5032 contain the pointer to the buffer and its size. The values thus stored
5033 remain valid only as long as no further output on the stream takes
5034 place. If you do more output, you must flush the stream again to store
5035 new values before you use them again.
5037 A null character is written at the end of the buffer. This null character
5038 is @emph{not} included in the size value stored at @var{sizeloc}.
5040 You can move the stream's file position with @code{fseek} or
5041 @code{fseeko} (@pxref{File Positioning}). Moving the file position past
5042 the end of the data already written fills the intervening space with
5046 Here is an example of using @code{open_memstream}:
5049 @include memstrm.c.texi
5052 This program produces the following output:
5055 buf = `hello', size = 5
5056 buf = `hello, world', size = 12
5059 @node Custom Streams
5060 @subsection Programming Your Own Custom Streams
5061 @cindex custom streams
5062 @cindex programming your own streams
5064 This section describes how you can make a stream that gets input from an
5065 arbitrary data source or writes output to an arbitrary data sink
5066 programmed by you. We call these @dfn{custom streams}. The functions
5067 and types described here are all GNU extensions.
5069 @c !!! this does not talk at all about the higher-level hooks
5072 * Streams and Cookies:: The @dfn{cookie} records where to fetch or
5073 store data that is read or written.
5074 * Hook Functions:: How you should define the four @dfn{hook
5075 functions} that a custom stream needs.
5078 @node Streams and Cookies
5079 @subsubsection Custom Streams and Cookies
5080 @cindex cookie, for custom stream
5082 Inside every custom stream is a special object called the @dfn{cookie}.
5083 This is an object supplied by you which records where to fetch or store
5084 the data read or written. It is up to you to define a data type to use
5085 for the cookie. The stream functions in the library never refer
5086 directly to its contents, and they don't even know what the type is;
5087 they record its address with type @code{void *}.
5089 To implement a custom stream, you must specify @emph{how} to fetch or
5090 store the data in the specified place. You do this by defining
5091 @dfn{hook functions} to read, write, change ``file position'', and close
5092 the stream. All four of these functions will be passed the stream's
5093 cookie so they can tell where to fetch or store the data. The library
5094 functions don't know what's inside the cookie, but your functions will
5097 When you create a custom stream, you must specify the cookie pointer,
5098 and also the four hook functions stored in a structure of type
5099 @code{cookie_io_functions_t}.
5101 These facilities are declared in @file{stdio.h}.
5104 @deftp {Data Type} {cookie_io_functions_t}
5105 @standards{GNU, stdio.h}
5106 This is a structure type that holds the functions that define the
5107 communications protocol between the stream and its cookie. It has
5108 the following members:
5111 @item cookie_read_function_t *read
5112 This is the function that reads data from the cookie. If the value is a
5113 null pointer instead of a function, then read operations on this stream
5114 always return @code{EOF}.
5116 @item cookie_write_function_t *write
5117 This is the function that writes data to the cookie. If the value is a
5118 null pointer instead of a function, then data written to the stream is
5121 @item cookie_seek_function_t *seek
5122 This is the function that performs the equivalent of file positioning on
5123 the cookie. If the value is a null pointer instead of a function, calls
5124 to @code{fseek} or @code{fseeko} on this stream can only seek to
5125 locations within the buffer; any attempt to seek outside the buffer will
5126 return an @code{ESPIPE} error.
5128 @item cookie_close_function_t *close
5129 This function performs any appropriate cleanup on the cookie when
5130 closing the stream. If the value is a null pointer instead of a
5131 function, nothing special is done to close the cookie when the stream is
5136 @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions})
5137 @standards{GNU, stdio.h}
5138 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
5139 This function actually creates the stream for communicating with the
5140 @var{cookie} using the functions in the @var{io-functions} argument.
5141 The @var{opentype} argument is interpreted as for @code{fopen};
5142 see @ref{Opening Streams}. (But note that the ``truncate on
5143 open'' option is ignored.) The new stream is fully buffered.
5145 The @code{fopencookie} function returns the newly created stream, or a null
5146 pointer in case of an error.
5149 @node Hook Functions
5150 @subsubsection Custom Stream Hook Functions
5151 @cindex hook functions (of custom streams)
5153 Here are more details on how you should define the four hook functions
5154 that a custom stream needs.
5156 You should define the function to read data from the cookie as:
5159 ssize_t @var{reader} (void *@var{cookie}, char *@var{buffer}, size_t @var{size})
5162 This is very similar to the @code{read} function; see @ref{I/O
5163 Primitives}. Your function should transfer up to @var{size} bytes into
5164 the @var{buffer}, and return the number of bytes read, or zero to
5165 indicate end-of-file. You can return a value of @code{-1} to indicate
5168 You should define the function to write data to the cookie as:
5171 ssize_t @var{writer} (void *@var{cookie}, const char *@var{buffer}, size_t @var{size})
5174 This is very similar to the @code{write} function; see @ref{I/O
5175 Primitives}. Your function should transfer up to @var{size} bytes from
5176 the buffer, and return the number of bytes written. You can return a
5177 value of @code{0} to indicate an error. You must not return any
5180 You should define the function to perform seek operations on the cookie
5184 int @var{seeker} (void *@var{cookie}, off64_t *@var{position}, int @var{whence})
5187 For this function, the @var{position} and @var{whence} arguments are
5188 interpreted as for @code{fgetpos}; see @ref{Portable Positioning}.
5190 After doing the seek operation, your function should store the resulting
5191 file position relative to the beginning of the file in @var{position}.
5192 Your function should return a value of @code{0} on success and @code{-1}
5193 to indicate an error.
5195 You should define the function to do cleanup operations on the cookie
5196 appropriate for closing the stream as:
5199 int @var{cleaner} (void *@var{cookie})
5202 Your function should return @code{-1} to indicate an error, and @code{0}
5205 @deftp {Data Type} cookie_read_function_t
5206 @standards{GNU, stdio.h}
5207 This is the data type that the read function for a custom stream should have.
5208 If you declare the function as shown above, this is the type it will have.
5211 @deftp {Data Type} cookie_write_function_t
5212 @standards{GNU, stdio.h}
5213 The data type of the write function for a custom stream.
5216 @deftp {Data Type} cookie_seek_function_t
5217 @standards{GNU, stdio.h}
5218 The data type of the seek function for a custom stream.
5221 @deftp {Data Type} cookie_close_function_t
5222 @standards{GNU, stdio.h}
5223 The data type of the close function for a custom stream.
5230 There is another set of functions one can give a stream, the
5231 input-room and output-room functions. These functions must
5232 understand stdio internals. To describe how to use these
5233 functions, you also need to document lots of how stdio works
5234 internally (which isn't relevant for other uses of stdio).
5235 Perhaps I can write an interface spec from which you can write
5236 good documentation. But it's pretty complex and deals with lots
5237 of nitty-gritty details. I think it might be better to let this
5238 wait until the rest of the manual is more done and polished.
5242 @c ??? This section could use an example.
5245 @node Formatted Messages
5246 @section Formatted Messages
5247 @cindex formatted messages
5249 On systems which are based on System V messages of programs (especially
5250 the system tools) are printed in a strict form using the @code{fmtmsg}
5251 function. The uniformity sometimes helps the user to interpret messages
5252 and the strictness tests of the @code{fmtmsg} function ensure that the
5253 programmer follows some minimal requirements.
5256 * Printing Formatted Messages:: The @code{fmtmsg} function.
5257 * Adding Severity Classes:: Add more severity classes.
5258 * Example:: How to use @code{fmtmsg} and @code{addseverity}.
5262 @node Printing Formatted Messages
5263 @subsection Printing Formatted Messages
5265 Messages can be printed to standard error and/or to the console. To
5266 select the destination the programmer can use the following two values,
5267 bitwise OR combined if wanted, for the @var{classification} parameter of
5272 Display the message in standard error.
5274 Display the message on the system console.
5277 The erroneous piece of the system can be signalled by exactly one of the
5278 following values which also is bitwise ORed with the
5279 @var{classification} parameter to @code{fmtmsg}:
5283 The source of the condition is some hardware.
5285 The source of the condition is some software.
5287 The source of the condition is some firmware.
5290 A third component of the @var{classification} parameter to @code{fmtmsg}
5291 can describe the part of the system which detects the problem. This is
5292 done by using exactly one of the following values:
5296 The erroneous condition is detected by the application.
5298 The erroneous condition is detected by a utility.
5300 The erroneous condition is detected by the operating system.
5303 A last component of @var{classification} can signal the results of this
5304 message. Exactly one of the following values can be used:
5308 It is a recoverable error.
5310 It is a non-recoverable error.
5313 @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})
5314 @standards{XPG, fmtmsg.h}
5315 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acsafe{}}
5316 Display a message described by its parameters on the device(s) specified
5317 in the @var{classification} parameter. The @var{label} parameter
5318 identifies the source of the message. The string should consist of two
5319 colon separated parts where the first part has not more than 10 and the
5320 second part not more than 14 characters. The @var{text} parameter
5321 describes the condition of the error, the @var{action} parameter possible
5322 steps to recover from the error and the @var{tag} parameter is a
5323 reference to the online documentation where more information can be
5324 found. It should contain the @var{label} value and a unique
5325 identification number.
5327 Each of the parameters can be a special value which means this value
5328 is to be omitted. The symbolic names for these values are:
5332 Ignore @var{label} parameter.
5334 Ignore @var{severity} parameter.
5336 Ignore @var{classification} parameter. This implies that nothing is
5339 Ignore @var{text} parameter.
5341 Ignore @var{action} parameter.
5343 Ignore @var{tag} parameter.
5346 There is another way certain fields can be omitted from the output to
5347 standard error. This is described below in the description of
5348 environment variables influencing the behavior.
5350 The @var{severity} parameter can have one of the values in the following
5352 @cindex severity class
5356 Nothing is printed, this value is the same as @code{MM_NULLSEV}.
5358 This value is printed as @code{HALT}.
5360 This value is printed as @code{ERROR}.
5362 This value is printed as @code{WARNING}.
5364 This value is printed as @code{INFO}.
5367 The numeric value of these five macros are between @code{0} and
5368 @code{4}. Using the environment variable @code{SEV_LEVEL} or using the
5369 @code{addseverity} function one can add more severity levels with their
5370 corresponding string to print. This is described below
5371 (@pxref{Adding Severity Classes}).
5374 If no parameter is ignored the output looks like this:
5377 @var{label}: @var{severity-string}: @var{text}
5378 TO FIX: @var{action} @var{tag}
5381 The colons, new line characters and the @code{TO FIX} string are
5382 inserted if necessary, i.e., if the corresponding parameter is not
5385 This function is specified in the X/Open Portability Guide. It is also
5386 available on all systems derived from System V.
5388 The function returns the value @code{MM_OK} if no error occurred. If
5389 only the printing to standard error failed, it returns @code{MM_NOMSG}.
5390 If printing to the console fails, it returns @code{MM_NOCON}. If
5391 nothing is printed @code{MM_NOTOK} is returned. Among situations where
5392 all outputs fail this last value is also returned if a parameter value
5396 There are two environment variables which influence the behavior of
5397 @code{fmtmsg}. The first is @code{MSGVERB}. It is used to control the
5398 output actually happening on standard error (@emph{not} the console
5399 output). Each of the five fields can explicitly be enabled. To do
5400 this the user has to put the @code{MSGVERB} variable with a format like
5401 the following in the environment before calling the @code{fmtmsg} function
5405 MSGVERB=@var{keyword}[:@var{keyword}[:@dots{}]]
5408 Valid @var{keyword}s are @code{label}, @code{severity}, @code{text},
5409 @code{action}, and @code{tag}. If the environment variable is not given
5410 or is the empty string, a not supported keyword is given or the value is
5411 somehow else invalid, no part of the message is masked out.
5413 The second environment variable which influences the behavior of
5414 @code{fmtmsg} is @code{SEV_LEVEL}. This variable and the change in the
5415 behavior of @code{fmtmsg} is not specified in the X/Open Portability
5416 Guide. It is available in System V systems, though. It can be used to
5417 introduce new severity levels. By default, only the five severity levels
5418 described above are available. Any other numeric value would make
5419 @code{fmtmsg} print nothing.
5421 If the user puts @code{SEV_LEVEL} with a format like
5424 SEV_LEVEL=[@var{description}[:@var{description}[:@dots{}]]]
5428 in the environment of the process before the first call to
5429 @code{fmtmsg}, where @var{description} has a value of the form
5432 @var{severity-keyword},@var{level},@var{printstring}
5435 The @var{severity-keyword} part is not used by @code{fmtmsg} but it has
5436 to be present. The @var{level} part is a string representation of a
5437 number. The numeric value must be a number greater than 4. This value
5438 must be used in the @var{severity} parameter of @code{fmtmsg} to select
5439 this class. It is not possible to overwrite any of the predefined
5440 classes. The @var{printstring} is the string printed when a message of
5441 this class is processed by @code{fmtmsg} (see above, @code{fmtsmg} does
5442 not print the numeric value but instead the string representation).
5445 @node Adding Severity Classes
5446 @subsection Adding Severity Classes
5447 @cindex severity class
5449 There is another possibility to introduce severity classes besides using
5450 the environment variable @code{SEV_LEVEL}. This simplifies the task of
5451 introducing new classes in a running program. One could use the
5452 @code{setenv} or @code{putenv} function to set the environment variable,
5453 but this is toilsome.
5455 @deftypefun int addseverity (int @var{severity}, const char *@var{string})
5456 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
5457 This function allows the introduction of new severity classes which can be
5458 addressed by the @var{severity} parameter of the @code{fmtmsg} function.
5459 The @var{severity} parameter of @code{addseverity} must match the value
5460 for the parameter with the same name of @code{fmtmsg}, and @var{string}
5461 is the string printed in the actual messages instead of the numeric
5464 If @var{string} is @code{NULL} the severity class with the numeric value
5465 according to @var{severity} is removed.
5467 It is not possible to overwrite or remove one of the default severity
5468 classes. All calls to @code{addseverity} with @var{severity} set to one
5469 of the values for the default classes will fail.
5471 The return value is @code{MM_OK} if the task was successfully performed.
5472 If the return value is @code{MM_NOTOK} something went wrong. This could
5473 mean that no more memory is available or a class is not available when
5474 it has to be removed.
5476 This function is not specified in the X/Open Portability Guide although
5477 the @code{fmtsmg} function is. It is available on System V systems.
5482 @subsection How to use @code{fmtmsg} and @code{addseverity}
5484 Here is a simple example program to illustrate the use of both
5485 functions described in this section.
5488 @include fmtmsgexpl.c.texi
5491 The second call to @code{fmtmsg} illustrates a use of this function as
5492 it usually occurs on System V systems, which heavily use this function.
5493 It seems worthwhile to give a short explanation here of how this system
5494 works on System V. The value of the
5495 @var{label} field (@code{UX:cat}) says that the error occurred in the
5496 Unix program @code{cat}. The explanation of the error follows and the
5497 value for the @var{action} parameter is @code{"refer to manual"}. One
5498 could be more specific here, if necessary. The @var{tag} field contains,
5499 as proposed above, the value of the string given for the @var{label}
5500 parameter, and additionally a unique ID (@code{001} in this case). For
5501 a GNU environment this string could contain a reference to the
5502 corresponding node in the Info page for the program.
5505 Running this program without specifying the @code{MSGVERB} and
5506 @code{SEV_LEVEL} function produces the following output:
5509 UX:cat: NOTE2: invalid syntax
5510 TO FIX: refer to manual UX:cat:001
5513 We see the different fields of the message and how the extra glue (the
5514 colons and the @code{TO FIX} string) is printed. But only one of the
5515 three calls to @code{fmtmsg} produced output. The first call does not
5516 print anything because the @var{label} parameter is not in the correct
5517 form. The string must contain two fields, separated by a colon
5518 (@pxref{Printing Formatted Messages}). The third @code{fmtmsg} call
5519 produced no output since the class with the numeric value @code{6} is
5520 not defined. Although a class with numeric value @code{5} is also not
5521 defined by default, the call to @code{addseverity} introduces it and
5522 the second call to @code{fmtmsg} produces the above output.
5524 When we change the environment of the program to contain
5525 @code{SEV_LEVEL=XXX,6,NOTE} when running it we get a different result:
5528 UX:cat: NOTE2: invalid syntax
5529 TO FIX: refer to manual UX:cat:001
5530 label:foo: NOTE: text
5534 Now the third call to @code{fmtmsg} produced some output and we see how
5535 the string @code{NOTE} from the environment variable appears in the
5538 Now we can reduce the output by specifying which fields we are
5539 interested in. If we additionally set the environment variable
5540 @code{MSGVERB} to the value @code{severity:label:action} we get the
5545 TO FIX: refer to manual
5551 I.e., the output produced by the @var{text} and the @var{tag} parameters
5552 to @code{fmtmsg} vanished. Please also note that now there is no colon
5553 after the @code{NOTE} and @code{NOTE2} strings in the output. This is
5554 not necessary since there is no more output on this line because the text