powerpc: Regenerate ULPs for expf() and exp2f()
[glibc.git] / manual / stdio.texi
blob5d7b50c442f0cba3a0e627c826e72d8b19b1eced
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
4 @c fix an overfull:
5 @tex
6 \hyphenation{which-ever}
7 @end tex
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.
14 @menu
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
34                                  and binary 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
39                                  to an open file.
40 * Formatted Messages::          Print strictly formatted messages.
41 @end menu
43 @node Streams
44 @section Streams
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.
53 @cindex file pointer
55 @pindex stdio.h
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}.
66 @end deftp
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
83 for the process.
85 These streams are declared in the header file @file{stdio.h}.
86 @pindex 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
91 program.
92 @end deftypevar
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
98 the program.
99 @end deftypevar
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.
106 @end deftypevar
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:
119 @smallexample
120 fclose (stdout);
121 stdout = fopen ("standard-output-file", "w");
122 @end smallexample
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.
140 @pindex stdio.h
141 Everything described in this section is declared in the header file
142 @file{stdio.h}.
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:
155 @table @samp
156 @item r
157 Open an existing file for reading only.
159 @item w
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.
163 @item a
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.
169 @item r+
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.
174 @item w+
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.
178 @item a+
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.
183 @end table
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
190 emptied properly.
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}:
198 @table @samp
199 @item c
200 The file is opened with cancellation in the I/O functions disabled.
202 @item e
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}.)
208 @item m
209 The file is opened and accessed using @code{mmap}.  This is only
210 supported with files opened for reading.
212 @item x
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}.
220 @end table
222 The character @samp{b} in @var{opentype} has a standard meaning; it
223 requests a binary stream rather than a text stream.  But this makes no
224 difference in POSIX systems (including @gnusystems{}).  If both
225 @samp{+} and @samp{b} are specified, they can appear in either order.
226 @xref{Binary Streams}.
228 @cindex stream orientation
229 @cindex orientation, stream
230 If the @var{opentype} string contains the sequence
231 @code{,ccs=@var{STRING}} then @var{STRING} is taken as the name of a
232 coded character set and @code{fopen} will mark the stream as
233 wide-oriented with appropriate conversion functions in place to convert
234 from and to the character set @var{STRING}.  Any other stream
235 is opened initially unoriented and the orientation is decided with the
236 first file operation.  If the first operation is a wide character
237 operation, the stream is not only marked as wide-oriented, also the
238 conversion functions to convert to the coded character set used for the
239 current locale are loaded.  This will not change anymore from this point
240 on even if the locale selected for the @code{LC_CTYPE} category is
241 changed.
243 Any other characters in @var{opentype} are simply ignored.  They may be
244 meaningful in other systems.
246 If the open fails, @code{fopen} returns a null pointer.
248 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
249 32 bit machine this function is in fact @code{fopen64} since the LFS
250 interface replaces transparently the old interface.
251 @end deftypefun
253 You can have multiple streams (or file descriptors) pointing to the same
254 file open at the same time.  If you do only input, this works
255 straightforwardly, but you must be careful if any output streams are
256 included.  @xref{Stream/Descriptor Precautions}.  This is equally true
257 whether the streams are in one program (not usual) or in several
258 programs (which can easily happen).  It may be advantageous to use the
259 file locking facilities to avoid simultaneous access.  @xref{File
260 Locks}.
262 @deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype})
263 @standards{Unix98, stdio.h}
264 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
265 This function is similar to @code{fopen} but the stream it returns a
266 pointer for is opened using @code{open64}.  Therefore this stream can be
267 used even on files larger than @twoexp{31} bytes on 32 bit machines.
269 Please note that the return type is still @code{FILE *}.  There is no
270 special @code{FILE} type for the LFS interface.
272 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
273 bits machine this function is available under the name @code{fopen}
274 and so transparently replaces the old interface.
275 @end deftypefun
277 @deftypevr Macro int FOPEN_MAX
278 @standards{ISO, stdio.h}
279 The value of this macro is an integer constant expression that
280 represents the minimum number of streams that the implementation
281 guarantees can be open simultaneously.  You might be able to open more
282 than this many streams, but that is not guaranteed.  The value of this
283 constant is at least eight, which includes the three standard streams
284 @code{stdin}, @code{stdout}, and @code{stderr}.  In POSIX.1 systems this
285 value is determined by the @code{OPEN_MAX} parameter; @pxref{General
286 Limits}.  In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE}
287 resource limit; @pxref{Limits on Resources}.
288 @end deftypevr
290 @deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
291 @standards{ISO, stdio.h}
292 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}}
293 @c Like most I/O operations, this one is guarded by a recursive lock,
294 @c released even upon cancellation, but cancellation may leak file
295 @c descriptors and leave the stream in an inconsistent state (e.g.,
296 @c still bound to the closed descriptor).  Also, if the stream is
297 @c part-way through a significant update (say running freopen) when a
298 @c signal handler calls freopen again on the same stream, the result is
299 @c likely to be an inconsistent stream, and the possibility of closing
300 @c twice file descriptor number that the stream used to use, the second
301 @c time when it might have already been reused by another thread.
302 This function is like a combination of @code{fclose} and @code{fopen}.
303 It first closes the stream referred to by @var{stream}, ignoring any
304 errors that are detected in the process.  (Because errors are ignored,
305 you should not use @code{freopen} on an output stream if you have
306 actually done any output using the stream.)  Then the file named by
307 @var{filename} is opened with mode @var{opentype} as for @code{fopen},
308 and associated with the same stream object @var{stream}.
310 If the operation fails, a null pointer is returned; otherwise,
311 @code{freopen} returns @var{stream}.  On Linux, @code{freopen} may also
312 fail and set @code{errno} to @code{EBUSY} when the kernel structure for
313 the old file descriptor was not initialized completely before @code{freopen}
314 was called.  This can only happen in multi-threaded programs, when two
315 threads race to allocate the same file descriptor number.  To avoid the
316 possibility of this race, do not use @code{close} to close the underlying
317 file descriptor for a @code{FILE}; either use @code{freopen} while the
318 file is still open, or use @code{open} and then @code{dup2} to install
319 the new file descriptor.
321 @code{freopen} has traditionally been used to connect a standard stream
322 such as @code{stdin} with a file of your own choice.  This is useful in
323 programs in which use of a standard stream for certain purposes is
324 hard-coded.  In @theglibc{}, you can simply close the standard
325 streams and open new ones with @code{fopen}.  But other systems lack
326 this ability, so using @code{freopen} is more portable.
328 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
329 32 bit machine this function is in fact @code{freopen64} since the LFS
330 interface replaces transparently the old interface.
331 @end deftypefun
333 @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
334 @standards{Unix98, stdio.h}
335 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}}
336 This function is similar to @code{freopen}.  The only difference is that
337 on 32 bit machine the stream returned is able to read beyond the
338 @twoexp{31} bytes limits imposed by the normal interface.  It should be
339 noted that the stream pointed to by @var{stream} need not be opened
340 using @code{fopen64} or @code{freopen64} since its mode is not important
341 for this function.
343 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
344 bits machine this function is available under the name @code{freopen}
345 and so transparently replaces the old interface.
346 @end deftypefun
348 In some situations it is useful to know whether a given stream is
349 available for reading or writing.  This information is normally not
350 available and would have to be remembered separately.  Solaris
351 introduced a few functions to get this information from the stream
352 descriptor and these functions are also available in @theglibc{}.
354 @deftypefun int __freadable (FILE *@var{stream})
355 @standards{GNU, stdio_ext.h}
356 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
357 The @code{__freadable} function determines whether the stream
358 @var{stream} was opened to allow reading.  In this case the return value
359 is nonzero.  For write-only streams the function returns zero.
361 This function is declared in @file{stdio_ext.h}.
362 @end deftypefun
364 @deftypefun int __fwritable (FILE *@var{stream})
365 @standards{GNU, stdio_ext.h}
366 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
367 The @code{__fwritable} function determines whether the stream
368 @var{stream} was opened to allow writing.  In this case the return value
369 is nonzero.  For read-only streams the function returns zero.
371 This function is declared in @file{stdio_ext.h}.
372 @end deftypefun
374 For slightly different kinds of problems there are two more functions.
375 They provide even finer-grained information.
377 @deftypefun int __freading (FILE *@var{stream})
378 @standards{GNU, stdio_ext.h}
379 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
380 The @code{__freading} function determines whether the stream
381 @var{stream} was last read from or whether it is opened read-only.  In
382 this case the return value is nonzero, otherwise it is zero.
383 Determining whether a stream opened for reading and writing was last
384 used for writing allows to draw conclusions about the content about the
385 buffer, among other things.
387 This function is declared in @file{stdio_ext.h}.
388 @end deftypefun
390 @deftypefun int __fwriting (FILE *@var{stream})
391 @standards{GNU, stdio_ext.h}
392 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
393 The @code{__fwriting} function determines whether the stream
394 @var{stream} was last written to or whether it is opened write-only.  In
395 this case the return value is nonzero, otherwise it is zero.
397 This function is declared in @file{stdio_ext.h}.
398 @end deftypefun
401 @node Closing Streams
402 @section Closing Streams
404 @cindex closing a stream
405 When a stream is closed with @code{fclose}, the connection between the
406 stream and the file is canceled.  After you have closed a stream, you
407 cannot perform any additional operations on it.
409 @deftypefun int fclose (FILE *@var{stream})
410 @standards{ISO, stdio.h}
411 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
412 @c After fclose, it is undefined behavior to use the stream it points
413 @c to.  Therefore, one must only call fclose when the stream is
414 @c otherwise unused.  Concurrent uses started before will complete
415 @c successfully because of the lock, which makes it MT-Safe.  Calling it
416 @c from a signal handler is perfectly safe if the stream is known to be
417 @c no longer used, which is a precondition for fclose to be safe in the
418 @c first place; since this is no further requirement, fclose is safe for
419 @c use in async signals too.  After calling fclose, you can no longer
420 @c use the stream, not even to fclose it again, so its memory and file
421 @c descriptor may leak if fclose is canceled before @c releasing them.
422 @c That the stream must be unused and it becomes unused after the call
423 @c is what would enable fclose to be AS- and AC-Safe while freopen
424 @c isn't.  However, because of the possibility of leaving __gconv_lock
425 @c taken upon cancellation, AC-Safety is lost.
426 This function causes @var{stream} to be closed and the connection to
427 the corresponding file to be broken.  Any buffered output is written
428 and any buffered input is discarded.  The @code{fclose} function returns
429 a value of @code{0} if the file was closed successfully, and @code{EOF}
430 if an error was detected.
432 It is important to check for errors when you call @code{fclose} to close
433 an output stream, because real, everyday errors can be detected at this
434 time.  For example, when @code{fclose} writes the remaining buffered
435 output, it might get an error because the disk is full.  Even if you
436 know the buffer is empty, errors can still occur when closing a file if
437 you are using NFS.
439 The function @code{fclose} is declared in @file{stdio.h}.
440 @end deftypefun
442 To close all streams currently available @theglibc{} provides
443 another function.
445 @deftypefun int fcloseall (void)
446 @standards{GNU, stdio.h}
447 @safety{@prelim{}@mtunsafe{@mtasurace{:streams}}@asunsafe{}@acsafe{}}
448 @c Like fclose, using any previously-opened streams after fcloseall is
449 @c undefined.  However, the implementation of fcloseall isn't equivalent
450 @c to calling fclose for all streams: it just flushes and unbuffers all
451 @c streams, without any locking.  It's the flushing without locking that
452 @c makes it unsafe.
453 This function causes all open streams of the process to be closed and
454 the connections to corresponding files to be broken.  All buffered data
455 is written and any buffered input is discarded.  The @code{fcloseall}
456 function returns a value of @code{0} if all the files were closed
457 successfully, and @code{EOF} if an error was detected.
459 This function should be used only in special situations, e.g., when an
460 error occurred and the program must be aborted.  Normally each single
461 stream should be closed separately so that problems with individual
462 streams can be identified.  It is also problematic since the standard
463 streams (@pxref{Standard Streams}) will also be closed.
465 The function @code{fcloseall} is declared in @file{stdio.h}.
466 @end deftypefun
468 If the @code{main} function to your program returns, or if you call the
469 @code{exit} function (@pxref{Normal Termination}), all open streams are
470 automatically closed properly.  If your program terminates in any other
471 manner, such as by calling the @code{abort} function (@pxref{Aborting a
472 Program}) or from a fatal signal (@pxref{Signal Handling}), open streams
473 might not be closed properly.  Buffered output might not be flushed and
474 files may be incomplete.  For more information on buffering of streams,
475 see @ref{Stream Buffering}.
477 @node Streams and Threads
478 @section Streams and Threads
480 @cindex threads
481 @cindex multi-threaded application
482 Streams can be used in multi-threaded applications in the same way they
483 are used in single-threaded applications.  But the programmer must be
484 aware of the possible complications.  It is important to know about
485 these also if the program one writes never use threads since the design
486 and implementation of many stream functions are heavily influenced by the
487 requirements added by multi-threaded programming.
489 The POSIX standard requires that by default the stream operations are
490 atomic.  I.e., issuing two stream operations for the same stream in two
491 threads at the same time will cause the operations to be executed as if
492 they were issued sequentially.  The buffer operations performed while
493 reading or writing are protected from other uses of the same stream.  To
494 do this each stream has an internal lock object which has to be
495 (implicitly) acquired before any work can be done.
497 But there are situations where this is not enough and there are also
498 situations where this is not wanted.  The implicit locking is not enough
499 if the program requires more than one stream function call to happen
500 atomically.  One example would be if an output line a program wants to
501 generate is created by several function calls.  The functions by
502 themselves would ensure only atomicity of their own operation, but not
503 atomicity over all the function calls.  For this it is necessary to
504 perform the stream locking in the application code.
506 @deftypefun void flockfile (FILE *@var{stream})
507 @standards{POSIX, stdio.h}
508 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
509 @c There's no way to tell whether the lock was acquired before or after
510 @c cancellation so as to unlock only when appropriate.
511 The @code{flockfile} function acquires the internal locking object
512 associated with the stream @var{stream}.  This ensures that no other
513 thread can explicitly through @code{flockfile}/@code{ftrylockfile} or
514 implicitly through the call of a stream function lock the stream.  The
515 thread will block until the lock is acquired.  An explicit call to
516 @code{funlockfile} has to be used to release the lock.
517 @end deftypefun
519 @deftypefun int ftrylockfile (FILE *@var{stream})
520 @standards{POSIX, stdio.h}
521 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
522 The @code{ftrylockfile} function tries to acquire the internal locking
523 object associated with the stream @var{stream} just like
524 @code{flockfile}.  But unlike @code{flockfile} this function does not
525 block if the lock is not available.  @code{ftrylockfile} returns zero if
526 the lock was successfully acquired.  Otherwise the stream is locked by
527 another thread.
528 @end deftypefun
530 @deftypefun void funlockfile (FILE *@var{stream})
531 @standards{POSIX, stdio.h}
532 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
533 The @code{funlockfile} function releases the internal locking object of
534 the stream @var{stream}.  The stream must have been locked before by a
535 call to @code{flockfile} or a successful call of @code{ftrylockfile}.
536 The implicit locking performed by the stream operations do not count.
537 The @code{funlockfile} function does not return an error status and the
538 behavior of a call for a stream which is not locked by the current
539 thread is undefined.
540 @end deftypefun
542 The following example shows how the functions above can be used to
543 generate an output line atomically even in multi-threaded applications
544 (yes, the same job could be done with one @code{fprintf} call but it is
545 sometimes not possible):
547 @smallexample
548 FILE *fp;
550    @dots{}
551    flockfile (fp);
552    fputs ("This is test number ", fp);
553    fprintf (fp, "%d\n", test);
554    funlockfile (fp)
556 @end smallexample
558 Without the explicit locking it would be possible for another thread to
559 use the stream @var{fp} after the @code{fputs} call returns and before
560 @code{fprintf} was called with the result that the number does not
561 follow the word @samp{number}.
563 From this description it might already be clear that the locking objects
564 in streams are no simple mutexes.  Since locking the same stream twice
565 in the same thread is allowed the locking objects must be equivalent to
566 recursive mutexes.  These mutexes keep track of the owner and the number
567 of times the lock is acquired.  The same number of @code{funlockfile}
568 calls by the same threads is necessary to unlock the stream completely.
569 For instance:
571 @smallexample
572 void
573 foo (FILE *fp)
575   ftrylockfile (fp);
576   fputs ("in foo\n", fp);
577   /* @r{This is very wrong!!!}  */
578   funlockfile (fp);
580 @end smallexample
582 It is important here that the @code{funlockfile} function is only called
583 if the @code{ftrylockfile} function succeeded in locking the stream.  It
584 is therefore always wrong to ignore the result of @code{ftrylockfile}.
585 And it makes no sense since otherwise one would use @code{flockfile}.
586 The result of code like that above is that either @code{funlockfile}
587 tries to free a stream that hasn't been locked by the current thread or it
588 frees the stream prematurely.  The code should look like this:
590 @smallexample
591 void
592 foo (FILE *fp)
594   if (ftrylockfile (fp) == 0)
595     @{
596       fputs ("in foo\n", fp);
597       funlockfile (fp);
598     @}
600 @end smallexample
602 Now that we covered why it is necessary to have locking it is
603 necessary to talk about situations when locking is unwanted and what can
604 be done.  The locking operations (explicit or implicit) don't come for
605 free.  Even if a lock is not taken the cost is not zero.  The operations
606 which have to be performed require memory operations that are safe in
607 multi-processor environments.  With the many local caches involved in
608 such systems this is quite costly.  So it is best to avoid the locking
609 completely if it is not needed -- because the code in question is never
610 used in a context where two or more threads may use a stream at a time.
611 This can be determined most of the time for application code; for
612 library code which can be used in many contexts one should default to be
613 conservative and use locking.
615 There are two basic mechanisms to avoid locking.  The first is to use
616 the @code{_unlocked} variants of the stream operations.  The POSIX
617 standard defines quite a few of those and @theglibc{} adds a few
618 more.  These variants of the functions behave just like the functions
619 with the name without the suffix except that they do not lock the
620 stream.  Using these functions is very desirable since they are
621 potentially much faster.  This is not only because the locking
622 operation itself is avoided.  More importantly, functions like
623 @code{putc} and @code{getc} are very simple and traditionally (before the
624 introduction of threads) were implemented as macros which are very fast
625 if the buffer is not empty.  With the addition of locking requirements
626 these functions are no longer implemented as macros since they would
627 expand to too much code.
628 But these macros are still available with the same functionality under the new
629 names @code{putc_unlocked} and @code{getc_unlocked}.  This possibly huge
630 difference of speed also suggests the use of the @code{_unlocked}
631 functions even if locking is required.  The difference is that the
632 locking then has to be performed in the program:
634 @smallexample
635 void
636 foo (FILE *fp, char *buf)
638   flockfile (fp);
639   while (*buf != '/')
640     putc_unlocked (*buf++, fp);
641   funlockfile (fp);
643 @end smallexample
645 If in this example the @code{putc} function would be used and the
646 explicit locking would be missing the @code{putc} function would have to
647 acquire the lock in every call, potentially many times depending on when
648 the loop terminates.  Writing it the way illustrated above allows the
649 @code{putc_unlocked} macro to be used which means no locking and direct
650 manipulation of the buffer of the stream.
652 A second way to avoid locking is by using a non-standard function which
653 was introduced in Solaris and is available in @theglibc{} as well.
655 @deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type})
656 @standards{GNU, stdio_ext.h}
657 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asulock{}}@acsafe{}}
658 @c Changing the implicit-locking status of a stream while it's in use by
659 @c another thread may cause a lock to be implicitly acquired and not
660 @c released, or vice-versa.  This function should probably hold the lock
661 @c while changing this setting, to make sure we don't change it while
662 @c there are any concurrent uses.  Meanwhile, callers should acquire the
663 @c lock themselves to be safe, and even concurrent uses with external
664 @c locking will be fine, as long as functions that require external
665 @c locking are not called without holding locks.
667 The @code{__fsetlocking} function can be used to select whether the
668 stream operations will implicitly acquire the locking object of the
669 stream @var{stream}.  By default this is done but it can be disabled and
670 reinstated using this function.  There are three values defined for the
671 @var{type} parameter.
673 @vtable @code
674 @item FSETLOCKING_INTERNAL
675 The stream @code{stream} will from now on use the default internal
676 locking.  Every stream operation with exception of the @code{_unlocked}
677 variants will implicitly lock the stream.
679 @item FSETLOCKING_BYCALLER
680 After the @code{__fsetlocking} function returns, the user is responsible
681 for locking the stream.  None of the stream operations will implicitly
682 do this anymore until the state is set back to
683 @code{FSETLOCKING_INTERNAL}.
685 @item FSETLOCKING_QUERY
686 @code{__fsetlocking} only queries the current locking state of the
687 stream.  The return value will be @code{FSETLOCKING_INTERNAL} or
688 @code{FSETLOCKING_BYCALLER} depending on the state.
689 @end vtable
691 The return value of @code{__fsetlocking} is either
692 @code{FSETLOCKING_INTERNAL} or @code{FSETLOCKING_BYCALLER} depending on
693 the state of the stream before the call.
695 This function and the values for the @var{type} parameter are declared
696 in @file{stdio_ext.h}.
697 @end deftypefun
699 This function is especially useful when program code has to be used
700 which is written without knowledge about the @code{_unlocked} functions
701 (or if the programmer was too lazy to use them).
703 @node Streams and I18N
704 @section Streams in Internationalized Applications
706 @w{ISO C90} introduced the new type @code{wchar_t} to allow handling
707 larger character sets.  What was missing was a possibility to output
708 strings of @code{wchar_t} directly.  One had to convert them into
709 multibyte strings using @code{mbstowcs} (there was no @code{mbsrtowcs}
710 yet) and then use the normal stream functions.  While this is doable it
711 is very cumbersome since performing the conversions is not trivial and
712 greatly increases program complexity and size.
714 The Unix standard early on (I think in XPG4.2) introduced two additional
715 format specifiers for the @code{printf} and @code{scanf} families of
716 functions.  Printing and reading of single wide characters was made
717 possible using the @code{%C} specifier and wide character strings can be
718 handled with @code{%S}.  These modifiers behave just like @code{%c} and
719 @code{%s} only that they expect the corresponding argument to have the
720 wide character type and that the wide character and string are
721 transformed into/from multibyte strings before being used.
723 This was a beginning but it is still not good enough.  Not always is it
724 desirable to use @code{printf} and @code{scanf}.  The other, smaller and
725 faster functions cannot handle wide characters.  Second, it is not
726 possible to have a format string for @code{printf} and @code{scanf}
727 consisting of wide characters.  The result is that format strings would
728 have to be generated if they have to contain non-basic characters.
730 @cindex C++ streams
731 @cindex streams, C++
732 In the @w{Amendment 1} to @w{ISO C90} a whole new set of functions was
733 added to solve the problem.  Most of the stream functions got a
734 counterpart which take a wide character or wide character string instead
735 of a character or string respectively.  The new functions operate on the
736 same streams (like @code{stdout}).  This is different from the model of
737 the C++ runtime library where separate streams for wide and normal I/O
738 are used.
740 @cindex orientation, stream
741 @cindex stream orientation
742 Being able to use the same stream for wide and normal operations comes
743 with a restriction: a stream can be used either for wide operations or
744 for normal operations.  Once it is decided there is no way back.  Only a
745 call to @code{freopen} or @code{freopen64} can reset the
746 @dfn{orientation}.  The orientation can be decided in three ways:
748 @itemize @bullet
749 @item
750 If any of the normal character functions are used (this includes the
751 @code{fread} and @code{fwrite} functions) the stream is marked as not
752 wide oriented.
754 @item
755 If any of the wide character functions are used the stream is marked as
756 wide oriented.
758 @item
759 The @code{fwide} function can be used to set the orientation either way.
760 @end itemize
762 It is important to never mix the use of wide and not wide operations on
763 a stream.  There are no diagnostics issued.  The application behavior
764 will simply be strange or the application will simply crash.  The
765 @code{fwide} function can help avoid this.
767 @deftypefun int fwide (FILE *@var{stream}, int @var{mode})
768 @standards{ISO, wchar.h}
769 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{}}}
770 @c Querying is always safe, but changing the stream when it's in use
771 @c upthread may be problematic.  Like most lock-acquiring functions,
772 @c this one may leak the lock if canceled.
774 The @code{fwide} function can be used to set and query the state of the
775 orientation of the stream @var{stream}.  If the @var{mode} parameter has
776 a positive value the streams get wide oriented, for negative values
777 narrow oriented.  It is not possible to overwrite previous orientations
778 with @code{fwide}.  I.e., if the stream @var{stream} was already
779 oriented before the call nothing is done.
781 If @var{mode} is zero the current orientation state is queried and
782 nothing is changed.
784 The @code{fwide} function returns a negative value, zero, or a positive
785 value if the stream is narrow, not at all, or wide oriented
786 respectively.
788 This function was introduced in @w{Amendment 1} to @w{ISO C90} and is
789 declared in @file{wchar.h}.
790 @end deftypefun
792 It is generally a good idea to orient a stream as early as possible.
793 This can prevent surprise especially for the standard streams
794 @code{stdin}, @code{stdout}, and @code{stderr}.  If some library
795 function in some situations uses one of these streams and this use
796 orients the stream in a different way the rest of the application
797 expects it one might end up with hard to reproduce errors.  Remember
798 that no errors are signal if the streams are used incorrectly.  Leaving
799 a stream unoriented after creation is normally only necessary for
800 library functions which create streams which can be used in different
801 contexts.
803 When writing code which uses streams and which can be used in different
804 contexts it is important to query the orientation of the stream before
805 using it (unless the rules of the library interface demand a specific
806 orientation).  The following little, silly function illustrates this.
808 @smallexample
809 void
810 print_f (FILE *fp)
812   if (fwide (fp, 0) > 0)
813     /* @r{Positive return value means wide orientation.}  */
814     fputwc (L'f', fp);
815   else
816     fputc ('f', fp);
818 @end smallexample
820 Note that in this case the function @code{print_f} decides about the
821 orientation of the stream if it was unoriented before (will not happen
822 if the advice above is followed).
824 The encoding used for the @code{wchar_t} values is unspecified and the
825 user must not make any assumptions about it.  For I/O of @code{wchar_t}
826 values this means that it is impossible to write these values directly
827 to the stream.  This is not what follows from the @w{ISO C} locale model
828 either.  What happens instead is that the bytes read from or written to
829 the underlying media are first converted into the internal encoding
830 chosen by the implementation for @code{wchar_t}.  The external encoding
831 is determined by the @code{LC_CTYPE} category of the current locale or
832 by the @samp{ccs} part of the mode specification given to @code{fopen},
833 @code{fopen64}, @code{freopen}, or @code{freopen64}.  How and when the
834 conversion happens is unspecified and it happens invisibly to the user.
836 Since a stream is created in the unoriented state it has at that point
837 no conversion associated with it.  The conversion which will be used is
838 determined by the @code{LC_CTYPE} category selected at the time the
839 stream is oriented.  If the locales are changed at the runtime this
840 might produce surprising results unless one pays attention.  This is
841 just another good reason to orient the stream explicitly as soon as
842 possible, perhaps with a call to @code{fwide}.
844 @node Simple Output
845 @section Simple Output by Characters or Lines
847 @cindex writing to a stream, by characters
848 This section describes functions for performing character- and
849 line-oriented output.
851 These narrow stream functions are declared in the header file
852 @file{stdio.h} and the wide stream functions in @file{wchar.h}.
853 @pindex stdio.h
854 @pindex wchar.h
856 @deftypefun int fputc (int @var{c}, FILE *@var{stream})
857 @standards{ISO, stdio.h}
858 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
859 @c If the stream is in use when interrupted by a signal, the recursive
860 @c lock won't help ensure the stream is consistent; indeed, if fputc
861 @c gets a signal precisely before the post-incremented _IO_write_ptr
862 @c value is stored, we may overwrite the interrupted write.  Conversely,
863 @c depending on compiler optimizations, the incremented _IO_write_ptr
864 @c may be stored before the character is stored in the buffer,
865 @c corrupting the stream if async cancel hits between the two stores.
866 @c There may be other reasons for AS- and AC-unsafety in the overflow
867 @c cases.
868 The @code{fputc} function converts the character @var{c} to type
869 @code{unsigned char}, and writes it to the stream @var{stream}.
870 @code{EOF} is returned if a write error occurs; otherwise the
871 character @var{c} is returned.
872 @end deftypefun
874 @deftypefun wint_t fputwc (wchar_t @var{wc}, FILE *@var{stream})
875 @standards{ISO, wchar.h}
876 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
877 The @code{fputwc} function writes the wide character @var{wc} to the
878 stream @var{stream}.  @code{WEOF} is returned if a write error occurs;
879 otherwise the character @var{wc} is returned.
880 @end deftypefun
882 @deftypefun int fputc_unlocked (int @var{c}, FILE *@var{stream})
883 @standards{POSIX, stdio.h}
884 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
885 @c The unlocked functions can't possibly satisfy the MT-Safety
886 @c requirements on their own, because they require external locking for
887 @c safety.
888 The @code{fputc_unlocked} function is equivalent to the @code{fputc}
889 function except that it does not implicitly lock the stream.
890 @end deftypefun
892 @deftypefun wint_t fputwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
893 @standards{POSIX, wchar.h}
894 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
895 The @code{fputwc_unlocked} function is equivalent to the @code{fputwc}
896 function except that it does not implicitly lock the stream.
898 This function is a GNU extension.
899 @end deftypefun
901 @deftypefun int putc (int @var{c}, FILE *@var{stream})
902 @standards{ISO, stdio.h}
903 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
904 This is just like @code{fputc}, except that most systems implement it as
905 a macro, making it faster.  One consequence is that it may evaluate the
906 @var{stream} argument more than once, which is an exception to the
907 general rule for macros.  @code{putc} is usually the best function to
908 use for writing a single character.
909 @end deftypefun
911 @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream})
912 @standards{ISO, wchar.h}
913 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
914 This is just like @code{fputwc}, except that it can be implement as
915 a macro, making it faster.  One consequence is that it may evaluate the
916 @var{stream} argument more than once, which is an exception to the
917 general rule for macros.  @code{putwc} is usually the best function to
918 use for writing a single wide character.
919 @end deftypefun
921 @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})
922 @standards{POSIX, stdio.h}
923 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
924 The @code{putc_unlocked} function is equivalent to the @code{putc}
925 function except that it does not implicitly lock the stream.
926 @end deftypefun
928 @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
929 @standards{GNU, wchar.h}
930 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
931 The @code{putwc_unlocked} function is equivalent to the @code{putwc}
932 function except that it does not implicitly lock the stream.
934 This function is a GNU extension.
935 @end deftypefun
937 @deftypefun int putchar (int @var{c})
938 @standards{ISO, stdio.h}
939 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
940 The @code{putchar} function is equivalent to @code{putc} with
941 @code{stdout} as the value of the @var{stream} argument.
942 @end deftypefun
944 @deftypefun wint_t putwchar (wchar_t @var{wc})
945 @standards{ISO, wchar.h}
946 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
947 The @code{putwchar} function is equivalent to @code{putwc} with
948 @code{stdout} as the value of the @var{stream} argument.
949 @end deftypefun
951 @deftypefun int putchar_unlocked (int @var{c})
952 @standards{POSIX, stdio.h}
953 @safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
954 The @code{putchar_unlocked} function is equivalent to the @code{putchar}
955 function except that it does not implicitly lock the stream.
956 @end deftypefun
958 @deftypefun wint_t putwchar_unlocked (wchar_t @var{wc})
959 @standards{GNU, wchar.h}
960 @safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
961 The @code{putwchar_unlocked} function is equivalent to the @code{putwchar}
962 function except that it does not implicitly lock the stream.
964 This function is a GNU extension.
965 @end deftypefun
967 @deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
968 @standards{ISO, stdio.h}
969 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
970 The function @code{fputs} writes the string @var{s} to the stream
971 @var{stream}.  The terminating null character is not written.
972 This function does @emph{not} add a newline character, either.
973 It outputs only the characters in the string.
975 This function returns @code{EOF} if a write error occurs, and otherwise
976 a non-negative value.
978 For example:
980 @smallexample
981 fputs ("Are ", stdout);
982 fputs ("you ", stdout);
983 fputs ("hungry?\n", stdout);
984 @end smallexample
986 @noindent
987 outputs the text @samp{Are you hungry?} followed by a newline.
988 @end deftypefun
990 @deftypefun int fputws (const wchar_t *@var{ws}, FILE *@var{stream})
991 @standards{ISO, wchar.h}
992 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
993 The function @code{fputws} writes the wide character string @var{ws} to
994 the stream @var{stream}.  The terminating null character is not written.
995 This function does @emph{not} add a newline character, either.  It
996 outputs only the characters in the string.
998 This function returns @code{WEOF} if a write error occurs, and otherwise
999 a non-negative value.
1000 @end deftypefun
1002 @deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream})
1003 @standards{GNU, stdio.h}
1004 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1005 The @code{fputs_unlocked} function is equivalent to the @code{fputs}
1006 function except that it does not implicitly lock the stream.
1008 This function is a GNU extension.
1009 @end deftypefun
1011 @deftypefun int fputws_unlocked (const wchar_t *@var{ws}, FILE *@var{stream})
1012 @standards{GNU, wchar.h}
1013 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1014 The @code{fputws_unlocked} function is equivalent to the @code{fputws}
1015 function except that it does not implicitly lock the stream.
1017 This function is a GNU extension.
1018 @end deftypefun
1020 @deftypefun int puts (const char *@var{s})
1021 @standards{ISO, stdio.h}
1022 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1023 The @code{puts} function writes the string @var{s} to the stream
1024 @code{stdout} followed by a newline.  The terminating null character of
1025 the string is not written.  (Note that @code{fputs} does @emph{not}
1026 write a newline as this function does.)
1028 @code{puts} is the most convenient function for printing simple
1029 messages.  For example:
1031 @smallexample
1032 puts ("This is a message.");
1033 @end smallexample
1035 @noindent
1036 outputs the text @samp{This is a message.} followed by a newline.
1037 @end deftypefun
1039 @deftypefun int putw (int @var{w}, FILE *@var{stream})
1040 @standards{SVID, stdio.h}
1041 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1042 This function writes the word @var{w} (that is, an @code{int}) to
1043 @var{stream}.  It is provided for compatibility with SVID, but we
1044 recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
1045 @end deftypefun
1047 @node Character Input
1048 @section Character Input
1050 @cindex reading from a stream, by characters
1051 This section describes functions for performing character-oriented
1052 input.  These narrow stream functions are declared in the header file
1053 @file{stdio.h} and the wide character functions are declared in
1054 @file{wchar.h}.
1055 @pindex stdio.h
1056 @pindex wchar.h
1058 These functions return an @code{int} or @code{wint_t} value (for narrow
1059 and wide stream functions respectively) that is either a character of
1060 input, or the special value @code{EOF}/@code{WEOF} (usually -1).  For
1061 the narrow stream functions it is important to store the result of these
1062 functions in a variable of type @code{int} instead of @code{char}, even
1063 when you plan to use it only as a character.  Storing @code{EOF} in a
1064 @code{char} variable truncates its value to the size of a character, so
1065 that it is no longer distinguishable from the valid character
1066 @samp{(char) -1}.  So always use an @code{int} for the result of
1067 @code{getc} and friends, and check for @code{EOF} after the call; once
1068 you've verified that the result is not @code{EOF}, you can be sure that
1069 it will fit in a @samp{char} variable without loss of information.
1071 @deftypefun int fgetc (FILE *@var{stream})
1072 @standards{ISO, stdio.h}
1073 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1074 @c Same caveats as fputc, but instead of losing a write in case of async
1075 @c signals, we may read the same character more than once, and the
1076 @c stream may be left in odd states due to cancellation in the underflow
1077 @c cases.
1078 This function reads the next character as an @code{unsigned char} from
1079 the stream @var{stream} and returns its value, converted to an
1080 @code{int}.  If an end-of-file condition or read error occurs,
1081 @code{EOF} is returned instead.
1082 @end deftypefun
1084 @deftypefun wint_t fgetwc (FILE *@var{stream})
1085 @standards{ISO, wchar.h}
1086 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1087 This function reads the next wide character from the stream @var{stream}
1088 and returns its value.  If an end-of-file condition or read error
1089 occurs, @code{WEOF} is returned instead.
1090 @end deftypefun
1092 @deftypefun int fgetc_unlocked (FILE *@var{stream})
1093 @standards{POSIX, stdio.h}
1094 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1095 The @code{fgetc_unlocked} function is equivalent to the @code{fgetc}
1096 function except that it does not implicitly lock the stream.
1097 @end deftypefun
1099 @deftypefun wint_t fgetwc_unlocked (FILE *@var{stream})
1100 @standards{GNU, wchar.h}
1101 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1102 The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc}
1103 function except that it does not implicitly lock the stream.
1105 This function is a GNU extension.
1106 @end deftypefun
1108 @deftypefun int getc (FILE *@var{stream})
1109 @standards{ISO, stdio.h}
1110 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1111 This is just like @code{fgetc}, except that it is permissible (and
1112 typical) for it to be implemented as a macro that evaluates the
1113 @var{stream} argument more than once.  @code{getc} is often highly
1114 optimized, so it is usually the best function to use to read a single
1115 character.
1116 @end deftypefun
1118 @deftypefun wint_t getwc (FILE *@var{stream})
1119 @standards{ISO, wchar.h}
1120 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1121 This is just like @code{fgetwc}, except that it is permissible for it to
1122 be implemented as a macro that evaluates the @var{stream} argument more
1123 than once.  @code{getwc} can be highly optimized, so it is usually the
1124 best function to use to read a single wide character.
1125 @end deftypefun
1127 @deftypefun int getc_unlocked (FILE *@var{stream})
1128 @standards{POSIX, stdio.h}
1129 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1130 The @code{getc_unlocked} function is equivalent to the @code{getc}
1131 function except that it does not implicitly lock the stream.
1132 @end deftypefun
1134 @deftypefun wint_t getwc_unlocked (FILE *@var{stream})
1135 @standards{GNU, wchar.h}
1136 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1137 The @code{getwc_unlocked} function is equivalent to the @code{getwc}
1138 function except that it does not implicitly lock the stream.
1140 This function is a GNU extension.
1141 @end deftypefun
1143 @deftypefun int getchar (void)
1144 @standards{ISO, stdio.h}
1145 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1146 The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
1147 as the value of the @var{stream} argument.
1148 @end deftypefun
1150 @deftypefun wint_t getwchar (void)
1151 @standards{ISO, wchar.h}
1152 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1153 The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin}
1154 as the value of the @var{stream} argument.
1155 @end deftypefun
1157 @deftypefun int getchar_unlocked (void)
1158 @standards{POSIX, stdio.h}
1159 @safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1160 The @code{getchar_unlocked} function is equivalent to the @code{getchar}
1161 function except that it does not implicitly lock the stream.
1162 @end deftypefun
1164 @deftypefun wint_t getwchar_unlocked (void)
1165 @standards{GNU, wchar.h}
1166 @safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1167 The @code{getwchar_unlocked} function is equivalent to the @code{getwchar}
1168 function except that it does not implicitly lock the stream.
1170 This function is a GNU extension.
1171 @end deftypefun
1173 Here is an example of a function that does input using @code{fgetc}.  It
1174 would work just as well using @code{getc} instead, or using
1175 @code{getchar ()} instead of @w{@code{fgetc (stdin)}}.  The code would
1176 also work the same for the wide character stream functions.
1178 @smallexample
1180 y_or_n_p (const char *question)
1182   fputs (question, stdout);
1183   while (1)
1184     @{
1185       int c, answer;
1186       /* @r{Write a space to separate answer from question.} */
1187       fputc (' ', stdout);
1188       /* @r{Read the first character of the line.}
1189          @r{This should be the answer character, but might not be.} */
1190       c = tolower (fgetc (stdin));
1191       answer = c;
1192       /* @r{Discard rest of input line.} */
1193       while (c != '\n' && c != EOF)
1194         c = fgetc (stdin);
1195       /* @r{Obey the answer if it was valid.} */
1196       if (answer == 'y')
1197         return 1;
1198       if (answer == 'n')
1199         return 0;
1200       /* @r{Answer was invalid: ask for valid answer.} */
1201       fputs ("Please answer y or n:", stdout);
1202     @}
1204 @end smallexample
1206 @deftypefun int getw (FILE *@var{stream})
1207 @standards{SVID, stdio.h}
1208 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1209 This function reads a word (that is, an @code{int}) from @var{stream}.
1210 It's provided for compatibility with SVID.  We recommend you use
1211 @code{fread} instead (@pxref{Block Input/Output}).  Unlike @code{getc},
1212 any @code{int} value could be a valid result.  @code{getw} returns
1213 @code{EOF} when it encounters end-of-file or an error, but there is no
1214 way to distinguish this from an input word with value -1.
1215 @end deftypefun
1217 @node Line Input
1218 @section Line-Oriented Input
1220 Since many programs interpret input on the basis of lines, it is
1221 convenient to have functions to read a line of text from a stream.
1223 Standard C has functions to do this, but they aren't very safe: null
1224 characters and even (for @code{gets}) long lines can confuse them.  So
1225 @theglibc{} provides the nonstandard @code{getline} function that
1226 makes it easy to read lines reliably.
1228 Another GNU extension, @code{getdelim}, generalizes @code{getline}.  It
1229 reads a delimited record, defined as everything through the next
1230 occurrence of a specified delimiter character.
1232 All these functions are declared in @file{stdio.h}.
1234 @deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
1235 @standards{GNU, stdio.h}
1236 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
1237 @c Besides the usual possibility of getting an inconsistent stream in a
1238 @c signal handler or leaving it inconsistent in case of cancellation,
1239 @c the possibility of leaving a dangling pointer upon cancellation
1240 @c between reallocing the buffer at *lineptr and updating the pointer
1241 @c brings about another case of @acucorrupt.
1242 This function reads an entire line from @var{stream}, storing the text
1243 (including the newline and a terminating null character) in a buffer
1244 and storing the buffer address in @code{*@var{lineptr}}.
1246 Before calling @code{getline}, you should place in @code{*@var{lineptr}}
1247 the address of a buffer @code{*@var{n}} bytes long, allocated with
1248 @code{malloc}.  If this buffer is long enough to hold the line,
1249 @code{getline} stores the line in this buffer.  Otherwise,
1250 @code{getline} makes the buffer bigger using @code{realloc}, storing the
1251 new buffer address back in @code{*@var{lineptr}} and the increased size
1252 back in @code{*@var{n}}.
1253 @xref{Unconstrained Allocation}.
1255 If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}}
1256 to zero, before the call, then @code{getline} allocates the initial
1257 buffer for you by calling @code{malloc}.  This buffer remains allocated
1258 even if @code{getline} encounters errors and is unable to read any bytes.
1260 In either case, when @code{getline} returns,  @code{*@var{lineptr}} is
1261 a @code{char *} which points to the text of the line.
1263 When @code{getline} is successful, it returns the number of characters
1264 read (including the newline, but not including the terminating null).
1265 This value enables you to distinguish null characters that are part of
1266 the line from the null character inserted as a terminator.
1268 This function is a GNU extension, but it is the recommended way to read
1269 lines from a stream.  The alternative standard functions are unreliable.
1271 If an error occurs or end of file is reached without any bytes read,
1272 @code{getline} returns @code{-1}.
1273 @end deftypefun
1275 @deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream})
1276 @standards{GNU, stdio.h}
1277 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
1278 @c See the getline @acucorrupt note.
1279 This function is like @code{getline} except that the character which
1280 tells it to stop reading is not necessarily newline.  The argument
1281 @var{delimiter} specifies the delimiter character; @code{getdelim} keeps
1282 reading until it sees that character (or end of file).
1284 The text is stored in @var{lineptr}, including the delimiter character
1285 and a terminating null.  Like @code{getline}, @code{getdelim} makes
1286 @var{lineptr} bigger if it isn't big enough.
1288 @code{getline} is in fact implemented in terms of @code{getdelim}, just
1289 like this:
1291 @smallexample
1292 ssize_t
1293 getline (char **lineptr, size_t *n, FILE *stream)
1295   return getdelim (lineptr, n, '\n', stream);
1297 @end smallexample
1298 @end deftypefun
1300 @deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
1301 @standards{ISO, stdio.h}
1302 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1303 The @code{fgets} function reads characters from the stream @var{stream}
1304 up to and including a newline character and stores them in the string
1305 @var{s}, adding a null character to mark the end of the string.  You
1306 must supply @var{count} characters worth of space in @var{s}, but the
1307 number of characters read is at most @var{count} @minus{} 1.  The extra
1308 character space is used to hold the null character at the end of the
1309 string.
1311 If the system is already at end of file when you call @code{fgets}, then
1312 the contents of the array @var{s} are unchanged and a null pointer is
1313 returned.  A null pointer is also returned if a read error occurs.
1314 Otherwise, the return value is the pointer @var{s}.
1316 @strong{Warning:}  If the input data has a null character, you can't tell.
1317 So don't use @code{fgets} unless you know the data cannot contain a null.
1318 Don't use it to read files edited by the user because, if the user inserts
1319 a null character, you should either handle it properly or print a clear
1320 error message.  We recommend using @code{getline} instead of @code{fgets}.
1321 @end deftypefun
1323 @deftypefun {wchar_t *} fgetws (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
1324 @standards{ISO, wchar.h}
1325 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1326 The @code{fgetws} function reads wide characters from the stream
1327 @var{stream} up to and including a newline character and stores them in
1328 the string @var{ws}, adding a null wide character to mark the end of the
1329 string.  You must supply @var{count} wide characters worth of space in
1330 @var{ws}, but the number of characters read is at most @var{count}
1331 @minus{} 1.  The extra character space is used to hold the null wide
1332 character at the end of the string.
1334 If the system is already at end of file when you call @code{fgetws}, then
1335 the contents of the array @var{ws} are unchanged and a null pointer is
1336 returned.  A null pointer is also returned if a read error occurs.
1337 Otherwise, the return value is the pointer @var{ws}.
1339 @strong{Warning:} If the input data has a null wide character (which are
1340 null bytes in the input stream), you can't tell.  So don't use
1341 @code{fgetws} unless you know the data cannot contain a null.  Don't use
1342 it to read files edited by the user because, if the user inserts a null
1343 character, you should either handle it properly or print a clear error
1344 message.
1345 @comment XXX We need getwline!!!
1346 @end deftypefun
1348 @deftypefun {char *} fgets_unlocked (char *@var{s}, int @var{count}, FILE *@var{stream})
1349 @standards{GNU, stdio.h}
1350 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1351 The @code{fgets_unlocked} function is equivalent to the @code{fgets}
1352 function except that it does not implicitly lock the stream.
1354 This function is a GNU extension.
1355 @end deftypefun
1357 @deftypefun {wchar_t *} fgetws_unlocked (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
1358 @standards{GNU, wchar.h}
1359 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1360 The @code{fgetws_unlocked} function is equivalent to the @code{fgetws}
1361 function except that it does not implicitly lock the stream.
1363 This function is a GNU extension.
1364 @end deftypefun
1366 @deftypefn {Deprecated function} {char *} gets (char *@var{s})
1367 @standards{ISO, stdio.h}
1368 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1369 The function @code{gets} reads characters from the stream @code{stdin}
1370 up to the next newline character, and stores them in the string @var{s}.
1371 The newline character is discarded (note that this differs from the
1372 behavior of @code{fgets}, which copies the newline character into the
1373 string).  If @code{gets} encounters a read error or end-of-file, it
1374 returns a null pointer; otherwise it returns @var{s}.
1376 @strong{Warning:} The @code{gets} function is @strong{very dangerous}
1377 because it provides no protection against overflowing the string
1378 @var{s}.  @Theglibc{} includes it for compatibility only.  You
1379 should @strong{always} use @code{fgets} or @code{getline} instead.  To
1380 remind you of this, the linker (if using GNU @code{ld}) will issue a
1381 warning whenever you use @code{gets}.
1382 @end deftypefn
1384 @node Unreading
1385 @section Unreading
1386 @cindex peeking at input
1387 @cindex unreading characters
1388 @cindex pushing input back
1390 In parser programs it is often useful to examine the next character in
1391 the input stream without removing it from the stream.  This is called
1392 ``peeking ahead'' at the input because your program gets a glimpse of
1393 the input it will read next.
1395 Using stream I/O, you can peek ahead at input by first reading it and
1396 then @dfn{unreading} it (also called  @dfn{pushing it back} on the stream).
1397 Unreading a character makes it available to be input again from the stream,
1398 by  the next call to @code{fgetc} or other input function on that stream.
1400 @menu
1401 * Unreading Idea::              An explanation of unreading with pictures.
1402 * How Unread::                  How to call @code{ungetc} to do unreading.
1403 @end menu
1405 @node Unreading Idea
1406 @subsection What Unreading Means
1408 Here is a pictorial explanation of unreading.  Suppose you have a
1409 stream reading a file that contains just six characters, the letters
1410 @samp{foobar}.  Suppose you have read three characters so far.  The
1411 situation looks like this:
1413 @smallexample
1414 f  o  o  b  a  r
1415          ^
1416 @end smallexample
1418 @noindent
1419 so the next input character will be @samp{b}.
1421 @c @group   Invalid outside @example
1422 If instead of reading @samp{b} you unread the letter @samp{o}, you get a
1423 situation like this:
1425 @smallexample
1426 f  o  o  b  a  r
1427          |
1428       o--
1429       ^
1430 @end smallexample
1432 @noindent
1433 so that the next input characters will be @samp{o} and @samp{b}.
1434 @c @end group
1436 @c @group
1437 If you unread @samp{9} instead of @samp{o}, you get this situation:
1439 @smallexample
1440 f  o  o  b  a  r
1441          |
1442       9--
1443       ^
1444 @end smallexample
1446 @noindent
1447 so that the next input characters will be @samp{9} and @samp{b}.
1448 @c @end group
1450 @node How Unread
1451 @subsection Using @code{ungetc} To Do Unreading
1453 The function to unread a character is called @code{ungetc}, because it
1454 reverses the action of @code{getc}.
1456 @deftypefun int ungetc (int @var{c}, FILE *@var{stream})
1457 @standards{ISO, stdio.h}
1458 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1459 The @code{ungetc} function pushes back the character @var{c} onto the
1460 input stream @var{stream}.  So the next input from @var{stream} will
1461 read @var{c} before anything else.
1463 If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
1464 @code{EOF}.  This lets you call @code{ungetc} with the return value of
1465 @code{getc} without needing to check for an error from @code{getc}.
1467 The character that you push back doesn't have to be the same as the last
1468 character that was actually read from the stream.  In fact, it isn't
1469 necessary to actually read any characters from the stream before
1470 unreading them with @code{ungetc}!  But that is a strange way to write a
1471 program; usually @code{ungetc} is used only to unread a character that
1472 was just read from the same stream.  @Theglibc{} supports this
1473 even on files opened in binary mode, but other systems might not.
1475 @Theglibc{} only supports one character of pushback---in other
1476 words, it does not work to call @code{ungetc} twice without doing input
1477 in between.  Other systems might let you push back multiple characters;
1478 then reading from the stream retrieves the characters in the reverse
1479 order that they were pushed.
1481 Pushing back characters doesn't alter the file; only the internal
1482 buffering for the stream is affected.  If a file positioning function
1483 (such as @code{fseek}, @code{fseeko} or @code{rewind}; @pxref{File
1484 Positioning}) is called, any pending pushed-back characters are
1485 discarded.
1487 Unreading a character on a stream that is at end of file clears the
1488 end-of-file indicator for the stream, because it makes the character of
1489 input available.  After you read that character, trying to read again
1490 will encounter end of file.
1491 @end deftypefun
1493 @deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream})
1494 @standards{ISO, wchar.h}
1495 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1496 The @code{ungetwc} function behaves just like @code{ungetc} just that it
1497 pushes back a wide character.
1498 @end deftypefun
1500 Here is an example showing the use of @code{getc} and @code{ungetc} to
1501 skip over whitespace characters.  When this function reaches a
1502 non-whitespace character, it unreads that character to be seen again on
1503 the next read operation on the stream.
1505 @smallexample
1506 #include <stdio.h>
1507 #include <ctype.h>
1509 void
1510 skip_whitespace (FILE *stream)
1512   int c;
1513   do
1514     /* @r{No need to check for @code{EOF} because it is not}
1515        @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.}  */
1516     c = getc (stream);
1517   while (isspace (c));
1518   ungetc (c, stream);
1520 @end smallexample
1522 @node Block Input/Output
1523 @section Block Input/Output
1525 This section describes how to do input and output operations on blocks
1526 of data.  You can use these functions to read and write binary data, as
1527 well as to read and write text in fixed-size blocks instead of by
1528 characters or lines.
1529 @cindex binary I/O to a stream
1530 @cindex block I/O to a stream
1531 @cindex reading from a stream, by blocks
1532 @cindex writing to a stream, by blocks
1534 Binary files are typically used to read and write blocks of data in the
1535 same format as is used to represent the data in a running program.  In
1536 other words, arbitrary blocks of memory---not just character or string
1537 objects---can be written to a binary file, and meaningfully read in
1538 again by the same program.
1540 Storing data in binary form is often considerably more efficient than
1541 using the formatted I/O functions.  Also, for floating-point numbers,
1542 the binary form avoids possible loss of precision in the conversion
1543 process.  On the other hand, binary files can't be examined or modified
1544 easily using many standard file utilities (such as text editors), and
1545 are not portable between different implementations of the language, or
1546 different kinds of computers.
1548 These functions are declared in @file{stdio.h}.
1549 @pindex stdio.h
1551 @deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1552 @standards{ISO, stdio.h}
1553 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1554 This function reads up to @var{count} objects of size @var{size} into
1555 the array @var{data}, from the stream @var{stream}.  It returns the
1556 number of objects actually read, which might be less than @var{count} if
1557 a read error occurs or the end of the file is reached.  This function
1558 returns a value of zero (and doesn't read anything) if either @var{size}
1559 or @var{count} is zero.
1561 If @code{fread} encounters end of file in the middle of an object, it
1562 returns the number of complete objects read, and discards the partial
1563 object.  Therefore, the stream remains at the actual end of the file.
1564 @end deftypefun
1566 @deftypefun size_t fread_unlocked (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1567 @standards{GNU, stdio.h}
1568 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1569 The @code{fread_unlocked} function is equivalent to the @code{fread}
1570 function except that it does not implicitly lock the stream.
1572 This function is a GNU extension.
1573 @end deftypefun
1575 @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1576 @standards{ISO, stdio.h}
1577 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
1578 This function writes up to @var{count} objects of size @var{size} from
1579 the array @var{data}, to the stream @var{stream}.  The return value is
1580 normally @var{count}, if the call succeeds.  Any other value indicates
1581 some sort of error, such as running out of space.
1582 @end deftypefun
1584 @deftypefun size_t fwrite_unlocked (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1585 @standards{GNU, stdio.h}
1586 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1587 The @code{fwrite_unlocked} function is equivalent to the @code{fwrite}
1588 function except that it does not implicitly lock the stream.
1590 This function is a GNU extension.
1591 @end deftypefun
1593 @node Formatted Output
1594 @section Formatted Output
1596 @cindex format string, for @code{printf}
1597 @cindex template, for @code{printf}
1598 @cindex formatted output to a stream
1599 @cindex writing to a stream, formatted
1600 The functions described in this section (@code{printf} and related
1601 functions) provide a convenient way to perform formatted output.  You
1602 call @code{printf} with a @dfn{format string} or @dfn{template string}
1603 that specifies how to format the values of the remaining arguments.
1605 Unless your program is a filter that specifically performs line- or
1606 character-oriented processing, using @code{printf} or one of the other
1607 related functions described in this section is usually the easiest and
1608 most concise way to perform output.  These functions are especially
1609 useful for printing error messages, tables of data, and the like.
1611 @menu
1612 * Formatted Output Basics::     Some examples to get you started.
1613 * Output Conversion Syntax::    General syntax of conversion
1614                                  specifications.
1615 * Table of Output Conversions:: Summary of output conversions and
1616                                  what they do.
1617 * Integer Conversions::         Details about formatting of integers.
1618 * Floating-Point Conversions::  Details about formatting of
1619                                  floating-point numbers.
1620 * Other Output Conversions::    Details about formatting of strings,
1621                                  characters, pointers, and the like.
1622 * Formatted Output Functions::  Descriptions of the actual functions.
1623 * Dynamic Output::              Functions that allocate memory for the output.
1624 * Variable Arguments Output::   @code{vprintf} and friends.
1625 * Parsing a Template String::   What kinds of args does a given template
1626                                  call for?
1627 * Example of Parsing::          Sample program using @code{parse_printf_format}.
1628 @end menu
1630 @node Formatted Output Basics
1631 @subsection Formatted Output Basics
1633 The @code{printf} function can be used to print any number of arguments.
1634 The template string argument you supply in a call provides
1635 information not only about the number of additional arguments, but also
1636 about their types and what style should be used for printing them.
1638 Ordinary characters in the template string are simply written to the
1639 output stream as-is, while @dfn{conversion specifications} introduced by
1640 a @samp{%} character in the template cause subsequent arguments to be
1641 formatted and written to the output stream.  For example,
1642 @cindex conversion specifications (@code{printf})
1644 @smallexample
1645 int pct = 37;
1646 char filename[] = "foo.txt";
1647 printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
1648         filename, pct);
1649 @end smallexample
1651 @noindent
1652 produces output like
1654 @smallexample
1655 Processing of `foo.txt' is 37% finished.
1656 Please be patient.
1657 @end smallexample
1659 This example shows the use of the @samp{%d} conversion to specify that
1660 an @code{int} argument should be printed in decimal notation, the
1661 @samp{%s} conversion to specify printing of a string argument, and
1662 the @samp{%%} conversion to print a literal @samp{%} character.
1664 There are also conversions for printing an integer argument as an
1665 unsigned value in octal, decimal, or hexadecimal radix (@samp{%o},
1666 @samp{%u}, or @samp{%x}, respectively); or as a character value
1667 (@samp{%c}).
1669 Floating-point numbers can be printed in normal, fixed-point notation
1670 using the @samp{%f} conversion or in exponential notation using the
1671 @samp{%e} conversion.  The @samp{%g} conversion uses either @samp{%e}
1672 or @samp{%f} format, depending on what is more appropriate for the
1673 magnitude of the particular number.
1675 You can control formatting more precisely by writing @dfn{modifiers}
1676 between the @samp{%} and the character that indicates which conversion
1677 to apply.  These slightly alter the ordinary behavior of the conversion.
1678 For example, most conversion specifications permit you to specify a
1679 minimum field width and a flag indicating whether you want the result
1680 left- or right-justified within the field.
1682 The specific flags and modifiers that are permitted and their
1683 interpretation vary depending on the particular conversion.  They're all
1684 described in more detail in the following sections.  Don't worry if this
1685 all seems excessively complicated at first; you can almost always get
1686 reasonable free-format output without using any of the modifiers at all.
1687 The modifiers are mostly used to make the output look ``prettier'' in
1688 tables.
1690 @node Output Conversion Syntax
1691 @subsection Output Conversion Syntax
1693 This section provides details about the precise syntax of conversion
1694 specifications that can appear in a @code{printf} template
1695 string.
1697 Characters in the template string that are not part of a conversion
1698 specification are printed as-is to the output stream.  Multibyte
1699 character sequences (@pxref{Character Set Handling}) are permitted in a
1700 template string.
1702 The conversion specifications in a @code{printf} template string have
1703 the general form:
1705 @smallexample
1706 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion}
1707 @end smallexample
1709 @noindent
1712 @smallexample
1713 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} . @r{*} @r{[} @var{param-no} @r{$]} @var{type} @var{conversion}
1714 @end smallexample
1716 For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-}
1717 is a flag, @samp{10} specifies the field width, the precision is
1718 @samp{8}, the letter @samp{l} is a type modifier, and @samp{d} specifies
1719 the conversion style.  (This particular type specifier says to
1720 print a @code{long int} argument in decimal notation, with a minimum of
1721 8 digits left-justified in a field at least 10 characters wide.)
1723 In more detail, output conversion specifications consist of an
1724 initial @samp{%} character followed in sequence by:
1726 @itemize @bullet
1727 @item
1728 An optional specification of the parameter used for this format.
1729 Normally the parameters to the @code{printf} function are assigned to the
1730 formats in the order of appearance in the format string.  But in some
1731 situations (such as message translation) this is not desirable and this
1732 extension allows an explicit parameter to be specified.
1734 The @var{param-no} parts of the format must be integers in the range of
1735 1 to the maximum number of arguments present to the function call.  Some
1736 implementations limit this number to a certain upper bound.  The exact
1737 limit can be retrieved by the following constant.
1739 @defvr Macro NL_ARGMAX
1740 The value of @code{NL_ARGMAX} is the maximum value allowed for the
1741 specification of a positional parameter in a @code{printf} call.  The
1742 actual value in effect at runtime can be retrieved by using
1743 @code{sysconf} using the @code{_SC_NL_ARGMAX} parameter @pxref{Sysconf
1744 Definition}.
1746 Some systems have a quite low limit such as @math{9} for @w{System V}
1747 systems.  @Theglibc{} has no real limit.
1748 @end defvr
1750 If any of the formats has a specification for the parameter position all
1751 of them in the format string shall have one.  Otherwise the behavior is
1752 undefined.
1754 @item
1755 Zero or more @dfn{flag characters} that modify the normal behavior of
1756 the conversion specification.
1757 @cindex flag character (@code{printf})
1759 @item
1760 An optional decimal integer specifying the @dfn{minimum field width}.
1761 If the normal conversion produces fewer characters than this, the field
1762 is padded with spaces to the specified width.  This is a @emph{minimum}
1763 value; if the normal conversion produces more characters than this, the
1764 field is @emph{not} truncated.  Normally, the output is right-justified
1765 within the field.
1766 @cindex minimum field width (@code{printf})
1768 You can also specify a field width of @samp{*}.  This means that the
1769 next argument in the argument list (before the actual value to be
1770 printed) is used as the field width.  The value must be an @code{int}.
1771 If the value is negative, this means to set the @samp{-} flag (see
1772 below) and to use the absolute value as the field width.
1774 @item
1775 An optional @dfn{precision} to specify the number of digits to be
1776 written for the numeric conversions.  If the precision is specified, it
1777 consists of a period (@samp{.}) followed optionally by a decimal integer
1778 (which defaults to zero if omitted).
1779 @cindex precision (@code{printf})
1781 You can also specify a precision of @samp{*}.  This means that the next
1782 argument in the argument list (before the actual value to be printed) is
1783 used as the precision.  The value must be an @code{int}, and is ignored
1784 if it is negative.  If you specify @samp{*} for both the field width and
1785 precision, the field width argument precedes the precision argument.
1786 Other C library versions may not recognize this syntax.
1788 @item
1789 An optional @dfn{type modifier character}, which is used to specify the
1790 data type of the corresponding argument if it differs from the default
1791 type.  (For example, the integer conversions assume a type of @code{int},
1792 but you can specify @samp{h}, @samp{l}, or @samp{L} for other integer
1793 types.)
1794 @cindex type modifier character (@code{printf})
1796 @item
1797 A character that specifies the conversion to be applied.
1798 @end itemize
1800 The exact options that are permitted and how they are interpreted vary
1801 between the different conversion specifiers.  See the descriptions of the
1802 individual conversions for information about the particular options that
1803 they use.
1805 With the @samp{-Wformat} option, the GNU C compiler checks calls to
1806 @code{printf} and related functions.  It examines the format string and
1807 verifies that the correct number and types of arguments are supplied.
1808 There is also a GNU C syntax to tell the compiler that a function you
1809 write uses a @code{printf}-style format string.
1810 @xref{Function Attributes, , Declaring Attributes of Functions,
1811 gcc.info, Using GNU CC}, for more information.
1813 @node Table of Output Conversions
1814 @subsection Table of Output Conversions
1815 @cindex output conversions, for @code{printf}
1817 Here is a table summarizing what all the different conversions do:
1819 @table @asis
1820 @item @samp{%d}, @samp{%i}
1821 Print an integer as a signed decimal number.  @xref{Integer
1822 Conversions}, for details.  @samp{%d} and @samp{%i} are synonymous for
1823 output, but are different when used with @code{scanf} for input
1824 (@pxref{Table of Input Conversions}).
1826 @item @samp{%o}
1827 Print an integer as an unsigned octal number.  @xref{Integer
1828 Conversions}, for details.
1830 @item @samp{%u}
1831 Print an integer as an unsigned decimal number.  @xref{Integer
1832 Conversions}, for details.
1834 @item @samp{%x}, @samp{%X}
1835 Print an integer as an unsigned hexadecimal number.  @samp{%x} uses
1836 lower-case letters and @samp{%X} uses upper-case.  @xref{Integer
1837 Conversions}, for details.
1839 @item @samp{%f}
1840 Print a floating-point number in normal (fixed-point) notation.
1841 @xref{Floating-Point Conversions}, for details.
1843 @item @samp{%e}, @samp{%E}
1844 Print a floating-point number in exponential notation.  @samp{%e} uses
1845 lower-case letters and @samp{%E} uses upper-case.  @xref{Floating-Point
1846 Conversions}, for details.
1848 @item @samp{%g}, @samp{%G}
1849 Print a floating-point number in either normal or exponential notation,
1850 whichever is more appropriate for its magnitude.  @samp{%g} uses
1851 lower-case letters and @samp{%G} uses upper-case.  @xref{Floating-Point
1852 Conversions}, for details.
1854 @item @samp{%a}, @samp{%A}
1855 Print a floating-point number in a hexadecimal fractional notation with
1856 the exponent to base 2 represented in decimal digits.  @samp{%a} uses
1857 lower-case letters and @samp{%A} uses upper-case.  @xref{Floating-Point
1858 Conversions}, for details.
1860 @item @samp{%c}
1861 Print a single character.  @xref{Other Output Conversions}.
1863 @item @samp{%C}
1864 This is an alias for @samp{%lc} which is supported for compatibility
1865 with the Unix standard.
1867 @item @samp{%s}
1868 Print a string.  @xref{Other Output Conversions}.
1870 @item @samp{%S}
1871 This is an alias for @samp{%ls} which is supported for compatibility
1872 with the Unix standard.
1874 @item @samp{%p}
1875 Print the value of a pointer.  @xref{Other Output Conversions}.
1877 @item @samp{%n}
1878 Get the number of characters printed so far.  @xref{Other Output Conversions}.
1879 Note that this conversion specification never produces any output.
1881 @item @samp{%m}
1882 Print the string corresponding to the value of @code{errno}.
1883 (This is a GNU extension.)
1884 @xref{Other Output Conversions}.
1886 @item @samp{%%}
1887 Print a literal @samp{%} character.  @xref{Other Output Conversions}.
1888 @end table
1890 If the syntax of a conversion specification is invalid, unpredictable
1891 things will happen, so don't do this.  If there aren't enough function
1892 arguments provided to supply values for all the conversion
1893 specifications in the template string, or if the arguments are not of
1894 the correct types, the results are unpredictable.  If you supply more
1895 arguments than conversion specifications, the extra argument values are
1896 simply ignored; this is sometimes useful.
1898 @node Integer Conversions
1899 @subsection Integer Conversions
1901 This section describes the options for the @samp{%d}, @samp{%i},
1902 @samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
1903 specifications.  These conversions print integers in various formats.
1905 The @samp{%d} and @samp{%i} conversion specifications both print an
1906 @code{int} argument as a signed decimal number; while @samp{%o},
1907 @samp{%u}, and @samp{%x} print the argument as an unsigned octal,
1908 decimal, or hexadecimal number (respectively).  The @samp{%X} conversion
1909 specification is just like @samp{%x} except that it uses the characters
1910 @samp{ABCDEF} as digits instead of @samp{abcdef}.
1912 The following flags are meaningful:
1914 @table @asis
1915 @item @samp{-}
1916 Left-justify the result in the field (instead of the normal
1917 right-justification).
1919 @item @samp{+}
1920 For the signed @samp{%d} and @samp{%i} conversions, print a
1921 plus sign if the value is positive.
1923 @item @samp{ }
1924 For the signed @samp{%d} and @samp{%i} conversions, if the result
1925 doesn't start with a plus or minus sign, prefix it with a space
1926 character instead.  Since the @samp{+} flag ensures that the result
1927 includes a sign, this flag is ignored if you supply both of them.
1929 @item @samp{#}
1930 For the @samp{%o} conversion, this forces the leading digit to be
1931 @samp{0}, as if by increasing the precision.  For @samp{%x} or
1932 @samp{%X}, this prefixes a leading @samp{0x} or @samp{0X} (respectively)
1933 to the result.  This doesn't do anything useful for the @samp{%d},
1934 @samp{%i}, or @samp{%u} conversions.  Using this flag produces output
1935 which can be parsed by the @code{strtoul} function (@pxref{Parsing of
1936 Integers}) and @code{scanf} with the @samp{%i} conversion
1937 (@pxref{Numeric Input Conversions}).
1939 @item @samp{'}
1940 Separate the digits into groups as specified by the locale specified for
1941 the @code{LC_NUMERIC} category; @pxref{General Numeric}.  This flag is a
1942 GNU extension.
1944 @item @samp{0}
1945 Pad the field with zeros instead of spaces.  The zeros are placed after
1946 any indication of sign or base.  This flag is ignored if the @samp{-}
1947 flag is also specified, or if a precision is specified.
1948 @end table
1950 If a precision is supplied, it specifies the minimum number of digits to
1951 appear; leading zeros are produced if necessary.  If you don't specify a
1952 precision, the number is printed with as many digits as it needs.  If
1953 you convert a value of zero with an explicit precision of zero, then no
1954 characters at all are produced.
1956 Without a type modifier, the corresponding argument is treated as an
1957 @code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
1958 @code{unsigned int} (for the unsigned conversions @samp{%o}, @samp{%u},
1959 @samp{%x}, and @samp{%X}).  Recall that since @code{printf} and friends
1960 are variadic, any @code{char} and @code{short} arguments are
1961 automatically converted to @code{int} by the default argument
1962 promotions.  For arguments of other integer types, you can use these
1963 modifiers:
1965 @table @samp
1966 @item hh
1967 Specifies that the argument is a @code{signed char} or @code{unsigned
1968 char}, as appropriate.  A @code{char} argument is converted to an
1969 @code{int} or @code{unsigned int} by the default argument promotions
1970 anyway, but the @samp{hh} modifier says to convert it back to a
1971 @code{char} again.
1973 This modifier was introduced in @w{ISO C99}.
1975 @item h
1976 Specifies that the argument is a @code{short int} or @code{unsigned
1977 short int}, as appropriate.  A @code{short} argument is converted to an
1978 @code{int} or @code{unsigned int} by the default argument promotions
1979 anyway, but the @samp{h} modifier says to convert it back to a
1980 @code{short} again.
1982 @item j
1983 Specifies that the argument is a @code{intmax_t} or @code{uintmax_t}, as
1984 appropriate.
1986 This modifier was introduced in @w{ISO C99}.
1988 @item l
1989 Specifies that the argument is a @code{long int} or @code{unsigned long
1990 int}, as appropriate.  Two @samp{l} characters are like the @samp{L}
1991 modifier, below.
1993 If used with @samp{%c} or @samp{%s} the corresponding parameter is
1994 considered as a wide character or wide character string respectively.
1995 This use of @samp{l} was introduced in @w{Amendment 1} to @w{ISO C90}.
1997 @item L
1998 @itemx ll
1999 @itemx q
2000 Specifies that the argument is a @code{long long int}.  (This type is
2001 an extension supported by the GNU C compiler.  On systems that don't
2002 support extra-long integers, this is the same as @code{long int}.)
2004 The @samp{q} modifier is another name for the same thing, which comes
2005 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
2006 @code{int}.
2008 @item t
2009 Specifies that the argument is a @code{ptrdiff_t}.
2011 This modifier was introduced in @w{ISO C99}.
2013 @item z
2014 @itemx Z
2015 Specifies that the argument is a @code{size_t}.
2017 @samp{z} was introduced in @w{ISO C99}.  @samp{Z} is a GNU extension
2018 predating this addition and should not be used in new code.
2019 @end table
2021 Here is an example.  Using the template string:
2023 @smallexample
2024 "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
2025 @end smallexample
2027 @noindent
2028 to print numbers using the different options for the @samp{%d}
2029 conversion gives results like:
2031 @smallexample
2032 |    0|0    |   +0|+0   |    0|00000|     |   00|0|
2033 |    1|1    |   +1|+1   |    1|00001|    1|   01|1|
2034 |   -1|-1   |   -1|-1   |   -1|-0001|   -1|  -01|-1|
2035 |100000|100000|+100000|+100000| 100000|100000|100000|100000|100000|
2036 @end smallexample
2038 In particular, notice what happens in the last case where the number
2039 is too large to fit in the minimum field width specified.
2041 Here are some more examples showing how unsigned integers print under
2042 various format options, using the template string:
2044 @smallexample
2045 "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
2046 @end smallexample
2048 @smallexample
2049 |    0|    0|    0|    0|    0|    0|    0|  00000000|
2050 |    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
2051 |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
2052 @end smallexample
2055 @node Floating-Point Conversions
2056 @subsection Floating-Point Conversions
2058 This section discusses the conversion specifications for floating-point
2059 numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G}
2060 conversions.
2062 The @samp{%f} conversion prints its argument in fixed-point notation,
2063 producing output of the form
2064 @w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
2065 where the number of digits following the decimal point is controlled
2066 by the precision you specify.
2068 The @samp{%e} conversion prints its argument in exponential notation,
2069 producing output of the form
2070 @w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}.
2071 Again, the number of digits following the decimal point is controlled by
2072 the precision.  The exponent always contains at least two digits.  The
2073 @samp{%E} conversion is similar but the exponent is marked with the letter
2074 @samp{E} instead of @samp{e}.
2076 The @samp{%g} and @samp{%G} conversions print the argument in the style
2077 of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
2078 than -4 or greater than or equal to the precision; otherwise they use
2079 the @samp{%f} style.  A precision of @code{0}, is taken as 1.
2080 Trailing zeros are removed from the fractional portion of the result and
2081 a decimal-point character appears only if it is followed by a digit.
2083 The @samp{%a} and @samp{%A} conversions are meant for representing
2084 floating-point numbers exactly in textual form so that they can be
2085 exchanged as texts between different programs and/or machines.  The
2086 numbers are represented in the form
2087 @w{[@code{-}]@code{0x}@var{h}@code{.}@var{hhh}@code{p}[@code{+}|@code{-}]@var{dd}}.
2088 At the left of the decimal-point character exactly one digit is print.
2089 This character is only @code{0} if the number is denormalized.
2090 Otherwise the value is unspecified; it is implementation dependent how many
2091 bits are used.  The number of hexadecimal digits on the right side of
2092 the decimal-point character is equal to the precision.  If the precision
2093 is zero it is determined to be large enough to provide an exact
2094 representation of the number (or it is large enough to distinguish two
2095 adjacent values if the @code{FLT_RADIX} is not a power of 2,
2096 @pxref{Floating Point Parameters}).  For the @samp{%a} conversion
2097 lower-case characters are used to represent the hexadecimal number and
2098 the prefix and exponent sign are printed as @code{0x} and @code{p}
2099 respectively.  Otherwise upper-case characters are used and @code{0X}
2100 and @code{P} are used for the representation of prefix and exponent
2101 string.  The exponent to the base of two is printed as a decimal number
2102 using at least one digit but at most as many digits as necessary to
2103 represent the value exactly.
2105 If the value to be printed represents infinity or a NaN, the output is
2106 @w{[@code{-}]@code{inf}} or @code{nan} respectively if the conversion
2107 specifier is @samp{%a}, @samp{%e}, @samp{%f}, or @samp{%g} and it is
2108 @w{[@code{-}]@code{INF}} or @code{NAN} respectively if the conversion is
2109 @samp{%A}, @samp{%E}, or @samp{%G}.
2111 The following flags can be used to modify the behavior:
2113 @comment We use @asis instead of @samp so we can have ` ' as an item.
2114 @table @asis
2115 @item @samp{-}
2116 Left-justify the result in the field.  Normally the result is
2117 right-justified.
2119 @item @samp{+}
2120 Always include a plus or minus sign in the result.
2122 @item @samp{ }
2123 If the result doesn't start with a plus or minus sign, prefix it with a
2124 space instead.  Since the @samp{+} flag ensures that the result includes
2125 a sign, this flag is ignored if you supply both of them.
2127 @item @samp{#}
2128 Specifies that the result should always include a decimal point, even
2129 if no digits follow it.  For the @samp{%g} and @samp{%G} conversions,
2130 this also forces trailing zeros after the decimal point to be left
2131 in place where they would otherwise be removed.
2133 @item @samp{'}
2134 Separate the digits of the integer part of the result into groups as
2135 specified by the locale specified for the @code{LC_NUMERIC} category;
2136 @pxref{General Numeric}.  This flag is a GNU extension.
2138 @item @samp{0}
2139 Pad the field with zeros instead of spaces; the zeros are placed
2140 after any sign.  This flag is ignored if the @samp{-} flag is also
2141 specified.
2142 @end table
2144 The precision specifies how many digits follow the decimal-point
2145 character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions.  For
2146 these conversions, the default precision is @code{6}.  If the precision
2147 is explicitly @code{0}, this suppresses the decimal point character
2148 entirely.  For the @samp{%g} and @samp{%G} conversions, the precision
2149 specifies how many significant digits to print.  Significant digits are
2150 the first digit before the decimal point, and all the digits after it.
2151 If the precision is @code{0} or not specified for @samp{%g} or @samp{%G},
2152 it is treated like a value of @code{1}.  If the value being printed
2153 cannot be expressed accurately in the specified number of digits, the
2154 value is rounded to the nearest number that fits.
2156 Without a type modifier, the floating-point conversions use an argument
2157 of type @code{double}.  (By the default argument promotions, any
2158 @code{float} arguments are automatically converted to @code{double}.)
2159 The following type modifier is supported:
2161 @table @samp
2162 @item L
2163 An uppercase @samp{L} specifies that the argument is a @code{long
2164 double}.
2165 @end table
2167 Here are some examples showing how numbers print using the various
2168 floating-point conversions.  All of the numbers were printed using
2169 this template string:
2171 @smallexample
2172 "|%13.4a|%13.4f|%13.4e|%13.4g|\n"
2173 @end smallexample
2175 Here is the output:
2177 @smallexample
2178 |  0x0.0000p+0|       0.0000|   0.0000e+00|            0|
2179 |  0x1.0000p-1|       0.5000|   5.0000e-01|          0.5|
2180 |  0x1.0000p+0|       1.0000|   1.0000e+00|            1|
2181 | -0x1.0000p+0|      -1.0000|  -1.0000e+00|           -1|
2182 |  0x1.9000p+6|     100.0000|   1.0000e+02|          100|
2183 |  0x1.f400p+9|    1000.0000|   1.0000e+03|         1000|
2184 | 0x1.3880p+13|   10000.0000|   1.0000e+04|        1e+04|
2185 | 0x1.81c8p+13|   12345.0000|   1.2345e+04|    1.234e+04|
2186 | 0x1.86a0p+16|  100000.0000|   1.0000e+05|        1e+05|
2187 | 0x1.e240p+16|  123456.0000|   1.2346e+05|    1.235e+05|
2188 @end smallexample
2190 Notice how the @samp{%g} conversion drops trailing zeros.
2192 @node Other Output Conversions
2193 @subsection Other Output Conversions
2195 This section describes miscellaneous conversions for @code{printf}.
2197 The @samp{%c} conversion prints a single character.  In case there is no
2198 @samp{l} modifier the @code{int} argument is first converted to an
2199 @code{unsigned char}.  Then, if used in a wide stream function, the
2200 character is converted into the corresponding wide character.  The
2201 @samp{-} flag can be used to specify left-justification in the field,
2202 but no other flags are defined, and no precision or type modifier can be
2203 given.  For example:
2205 @smallexample
2206 printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
2207 @end smallexample
2209 @noindent
2210 prints @samp{hello}.
2212 If there is an @samp{l} modifier present the argument is expected to be
2213 of type @code{wint_t}.  If used in a multibyte function the wide
2214 character is converted into a multibyte character before being added to
2215 the output.  In this case more than one output byte can be produced.
2217 The @samp{%s} conversion prints a string.  If no @samp{l} modifier is
2218 present the corresponding argument must be of type @code{char *} (or
2219 @code{const char *}).  If used in a wide stream function the string is
2220 first converted to a wide character string.  A precision can be
2221 specified to indicate the maximum number of characters to write;
2222 otherwise characters in the string up to but not including the
2223 terminating null character are written to the output stream.  The
2224 @samp{-} flag can be used to specify left-justification in the field,
2225 but no other flags or type modifiers are defined for this conversion.
2226 For example:
2228 @smallexample
2229 printf ("%3s%-6s", "no", "where");
2230 @end smallexample
2232 @noindent
2233 prints @samp{ nowhere }.
2235 If there is an @samp{l} modifier present, the argument is expected to
2236 be of type @code{wchar_t} (or @code{const wchar_t *}).
2238 If you accidentally pass a null pointer as the argument for a @samp{%s}
2239 conversion, @theglibc{} prints it as @samp{(null)}.  We think this
2240 is more useful than crashing.  But it's not good practice to pass a null
2241 argument intentionally.
2243 The @samp{%m} conversion prints the string corresponding to the error
2244 code in @code{errno}.  @xref{Error Messages}.  Thus:
2246 @smallexample
2247 fprintf (stderr, "can't open `%s': %m\n", filename);
2248 @end smallexample
2250 @noindent
2251 is equivalent to:
2253 @smallexample
2254 fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
2255 @end smallexample
2257 @noindent
2258 The @samp{%m} conversion is a @glibcadj{} extension.
2260 The @samp{%p} conversion prints a pointer value.  The corresponding
2261 argument must be of type @code{void *}.  In practice, you can use any
2262 type of pointer.
2264 In @theglibc{}, non-null pointers are printed as unsigned integers,
2265 as if a @samp{%#x} conversion were used.  Null pointers print as
2266 @samp{(nil)}.  (Pointers might print differently in other systems.)
2268 For example:
2270 @smallexample
2271 printf ("%p", "testing");
2272 @end smallexample
2274 @noindent
2275 prints @samp{0x} followed by a hexadecimal number---the address of the
2276 string constant @code{"testing"}.  It does not print the word
2277 @samp{testing}.
2279 You can supply the @samp{-} flag with the @samp{%p} conversion to
2280 specify left-justification, but no other flags, precision, or type
2281 modifiers are defined.
2283 The @samp{%n} conversion is unlike any of the other output conversions.
2284 It uses an argument which must be a pointer to an @code{int}, but
2285 instead of printing anything it stores the number of characters printed
2286 so far by this call at that location.  The @samp{h} and @samp{l} type
2287 modifiers are permitted to specify that the argument is of type
2288 @code{short int *} or @code{long int *} instead of @code{int *}, but no
2289 flags, field width, or precision are permitted.
2291 For example,
2293 @smallexample
2294 int nchar;
2295 printf ("%d %s%n\n", 3, "bears", &nchar);
2296 @end smallexample
2298 @noindent
2299 prints:
2301 @smallexample
2302 3 bears
2303 @end smallexample
2305 @noindent
2306 and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven
2307 characters.
2310 The @samp{%%} conversion prints a literal @samp{%} character.  This
2311 conversion doesn't use an argument, and no flags, field width,
2312 precision, or type modifiers are permitted.
2315 @node Formatted Output Functions
2316 @subsection Formatted Output Functions
2318 This section describes how to call @code{printf} and related functions.
2319 Prototypes for these functions are in the header file @file{stdio.h}.
2320 Because these functions take a variable number of arguments, you
2321 @emph{must} declare prototypes for them before using them.  Of course,
2322 the easiest way to make sure you have all the right prototypes is to
2323 just include @file{stdio.h}.
2324 @pindex stdio.h
2326 @deftypefun int printf (const char *@var{template}, @dots{})
2327 @standards{ISO, stdio.h}
2328 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2329 The @code{printf} function prints the optional arguments under the
2330 control of the template string @var{template} to the stream
2331 @code{stdout}.  It returns the number of characters printed, or a
2332 negative value if there was an output error.
2333 @end deftypefun
2335 @deftypefun int wprintf (const wchar_t *@var{template}, @dots{})
2336 @standards{ISO, wchar.h}
2337 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2338 The @code{wprintf} function prints the optional arguments under the
2339 control of the wide template string @var{template} to the stream
2340 @code{stdout}.  It returns the number of wide characters printed, or a
2341 negative value if there was an output error.
2342 @end deftypefun
2344 @deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
2345 @standards{ISO, stdio.h}
2346 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2347 This function is just like @code{printf}, except that the output is
2348 written to the stream @var{stream} instead of @code{stdout}.
2349 @end deftypefun
2351 @deftypefun int fwprintf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
2352 @standards{ISO, wchar.h}
2353 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2354 This function is just like @code{wprintf}, except that the output is
2355 written to the stream @var{stream} instead of @code{stdout}.
2356 @end deftypefun
2358 @deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
2359 @standards{ISO, stdio.h}
2360 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2361 This is like @code{printf}, except that the output is stored in the character
2362 array @var{s} instead of written to a stream.  A null character is written
2363 to mark the end of the string.
2365 The @code{sprintf} function returns the number of characters stored in
2366 the array @var{s}, not including the terminating null character.
2368 The behavior of this function is undefined if copying takes place
2369 between objects that overlap---for example, if @var{s} is also given
2370 as an argument to be printed under control of the @samp{%s} conversion.
2371 @xref{Copying Strings and Arrays}.
2373 @strong{Warning:} The @code{sprintf} function can be @strong{dangerous}
2374 because it can potentially output more characters than can fit in the
2375 allocation size of the string @var{s}.  Remember that the field width
2376 given in a conversion specification is only a @emph{minimum} value.
2378 To avoid this problem, you can use @code{snprintf} or @code{asprintf},
2379 described below.
2380 @end deftypefun
2382 @deftypefun int swprintf (wchar_t *@var{ws}, size_t @var{size}, const wchar_t *@var{template}, @dots{})
2383 @standards{GNU, wchar.h}
2384 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2385 This is like @code{wprintf}, except that the output is stored in the
2386 wide character array @var{ws} instead of written to a stream.  A null
2387 wide character is written to mark the end of the string.  The @var{size}
2388 argument specifies the maximum number of characters to produce.  The
2389 trailing null character is counted towards this limit, so you should
2390 allocate at least @var{size} wide characters for the string @var{ws}.
2392 The return value is the number of characters generated for the given
2393 input, excluding the trailing null.  If not all output fits into the
2394 provided buffer a negative value is returned.  You should try again with
2395 a bigger output string.  @emph{Note:} this is different from how
2396 @code{snprintf} handles this situation.
2398 Note that the corresponding narrow stream function takes fewer
2399 parameters.  @code{swprintf} in fact corresponds to the @code{snprintf}
2400 function.  Since the @code{sprintf} function can be dangerous and should
2401 be avoided the @w{ISO C} committee refused to make the same mistake
2402 again and decided to not define a function exactly corresponding to
2403 @code{sprintf}.
2404 @end deftypefun
2406 @deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{})
2407 @standards{GNU, stdio.h}
2408 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2409 The @code{snprintf} function is similar to @code{sprintf}, except that
2410 the @var{size} argument specifies the maximum number of characters to
2411 produce.  The trailing null character is counted towards this limit, so
2412 you should allocate at least @var{size} characters for the string @var{s}.
2413 If @var{size} is zero, nothing, not even the null byte, shall be written and
2414 @var{s} may be a null pointer.
2416 The return value is the number of characters which would be generated
2417 for the given input, excluding the trailing null.  If this value is
2418 greater than or equal to @var{size}, not all characters from the result have
2419 been stored in @var{s}.  You should try again with a bigger output
2420 string.  Here is an example of doing this:
2422 @smallexample
2423 @group
2424 /* @r{Construct a message describing the value of a variable}
2425    @r{whose name is @var{name} and whose value is @var{value}.} */
2426 char *
2427 make_message (char *name, char *value)
2429   /* @r{Guess we need no more than 100 chars of space.} */
2430   int size = 100;
2431   char *buffer = (char *) xmalloc (size);
2432   int nchars;
2433 @end group
2434 @group
2435   if (buffer == NULL)
2436     return NULL;
2438  /* @r{Try to print in the allocated space.} */
2439   nchars = snprintf (buffer, size, "value of %s is %s",
2440                      name, value);
2441 @end group
2442 @group
2443   if (nchars >= size)
2444     @{
2445       /* @r{Reallocate buffer now that we know
2446          how much space is needed.} */
2447       size = nchars + 1;
2448       buffer = (char *) xrealloc (buffer, size);
2450       if (buffer != NULL)
2451         /* @r{Try again.} */
2452         snprintf (buffer, size, "value of %s is %s",
2453                   name, value);
2454     @}
2455   /* @r{The last call worked, return the string.} */
2456   return buffer;
2458 @end group
2459 @end smallexample
2461 In practice, it is often easier just to use @code{asprintf}, below.
2463 @strong{Attention:} In versions of @theglibc{} prior to 2.1 the
2464 return value is the number of characters stored, not including the
2465 terminating null; unless there was not enough space in @var{s} to
2466 store the result in which case @code{-1} is returned.  This was
2467 changed in order to comply with the @w{ISO C99} standard.
2468 @end deftypefun
2470 @node Dynamic Output
2471 @subsection Dynamically Allocating Formatted Output
2473 The functions in this section do formatted output and place the results
2474 in dynamically allocated memory.
2476 @deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
2477 @standards{GNU, stdio.h}
2478 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2479 This function is similar to @code{sprintf}, except that it dynamically
2480 allocates a string (as with @code{malloc}; @pxref{Unconstrained
2481 Allocation}) to hold the output, instead of putting the output in a
2482 buffer you allocate in advance.  The @var{ptr} argument should be the
2483 address of a @code{char *} object, and a successful call to
2484 @code{asprintf} stores a pointer to the newly allocated string at that
2485 location.
2487 The return value is the number of characters allocated for the buffer, or
2488 less than zero if an error occurred.  Usually this means that the buffer
2489 could not be allocated.
2491 Here is how to use @code{asprintf} to get the same result as the
2492 @code{snprintf} example, but more easily:
2494 @smallexample
2495 /* @r{Construct a message describing the value of a variable}
2496    @r{whose name is @var{name} and whose value is @var{value}.} */
2497 char *
2498 make_message (char *name, char *value)
2500   char *result;
2501   if (asprintf (&result, "value of %s is %s", name, value) < 0)
2502     return NULL;
2503   return result;
2505 @end smallexample
2506 @end deftypefun
2508 @deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
2509 @standards{GNU, stdio.h}
2510 @safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
2511 This function is similar to @code{asprintf}, except that it uses the
2512 obstack @var{obstack} to allocate the space.  @xref{Obstacks}.
2514 The characters are written onto the end of the current object.
2515 To get at them, you must finish the object with @code{obstack_finish}
2516 (@pxref{Growing Objects}).@refill
2517 @end deftypefun
2519 @node Variable Arguments Output
2520 @subsection Variable Arguments Output Functions
2522 The functions @code{vprintf} and friends are provided so that you can
2523 define your own variadic @code{printf}-like functions that make use of
2524 the same internals as the built-in formatted output functions.
2526 The most natural way to define such functions would be to use a language
2527 construct to say, ``Call @code{printf} and pass this template plus all
2528 of my arguments after the first five.''  But there is no way to do this
2529 in C, and it would be hard to provide a way, since at the C language
2530 level there is no way to tell how many arguments your function received.
2532 Since that method is impossible, we provide alternative functions, the
2533 @code{vprintf} series, which lets you pass a @code{va_list} to describe
2534 ``all of my arguments after the first five.''
2536 When it is sufficient to define a macro rather than a real function,
2537 the GNU C compiler provides a way to do this much more easily with macros.
2538 For example:
2540 @smallexample
2541 #define myprintf(a, b, c, d, e, rest...) \
2542             printf (mytemplate , ## rest)
2543 @end smallexample
2545 @noindent
2546 @xref{Variadic Macros,,, cpp, The C preprocessor}, for details.
2547 But this is limited to macros, and does not apply to real functions at all.
2549 Before calling @code{vprintf} or the other functions listed in this
2550 section, you @emph{must} call @code{va_start} (@pxref{Variadic
2551 Functions}) to initialize a pointer to the variable arguments.  Then you
2552 can call @code{va_arg} to fetch the arguments that you want to handle
2553 yourself.  This advances the pointer past those arguments.
2555 Once your @code{va_list} pointer is pointing at the argument of your
2556 choice, you are ready to call @code{vprintf}.  That argument and all
2557 subsequent arguments that were passed to your function are used by
2558 @code{vprintf} along with the template that you specified separately.
2560 @strong{Portability Note:} The value of the @code{va_list} pointer is
2561 undetermined after the call to @code{vprintf}, so you must not use
2562 @code{va_arg} after you call @code{vprintf}.  Instead, you should call
2563 @code{va_end} to retire the pointer from service.  You can call
2564 @code{va_start} again and begin fetching the arguments from the start of
2565 the variable argument list.  (Alternatively, you can use @code{va_copy}
2566 to make a copy of the @code{va_list} pointer before calling
2567 @code{vfprintf}.)  Calling @code{vprintf} does not destroy the argument
2568 list of your function, merely the particular pointer that you passed to
2571 Prototypes for these functions are declared in @file{stdio.h}.
2572 @pindex stdio.h
2574 @deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
2575 @standards{ISO, stdio.h}
2576 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2577 This function is similar to @code{printf} except that, instead of taking
2578 a variable number of arguments directly, it takes an argument list
2579 pointer @var{ap}.
2580 @end deftypefun
2582 @deftypefun int vwprintf (const wchar_t *@var{template}, va_list @var{ap})
2583 @standards{ISO, wchar.h}
2584 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2585 This function is similar to @code{wprintf} except that, instead of taking
2586 a variable number of arguments directly, it takes an argument list
2587 pointer @var{ap}.
2588 @end deftypefun
2590 @deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
2591 @standards{ISO, stdio.h}
2592 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2593 @c Although vfprintf sets up a cleanup region to release the lock on the
2594 @c output stream, it doesn't use it to release args_value or string in
2595 @c case of cancellation.  This doesn't make it unsafe, but cancelling it
2596 @c may leak memory.  The unguarded use of __printf_function_table is
2597 @c also of concern for all callers.
2598 @c _itoa ok
2599 @c   _udiv_qrnnd_preinv ok
2600 @c group_number ok
2601 @c _i18n_number_rewrite
2602 @c   __wctrans ok
2603 @c   __towctrans @mtslocale
2604 @c   __wcrtomb ok? dup below
2605 @c   outdigit_value ok
2606 @c   outdigitwc_value ok
2607 @c outchar ok
2608 @c outstring ok
2609 @c PAD ok
2610 @c __printf_fp @mtslocale @ascuheap @acsmem
2611 @c __printf_fphex @mtslocale
2612 @c __readonly_area
2613 @c   [GNU/Linux] fopen, strtoul, free
2614 @c __strerror_r ok if no translation, check otherwise
2615 @c __btowc ? gconv-modules
2616 @c __wcrtomb ok (not using internal state) gconv-modules
2617 @c ARGCHECK
2618 @c UNBUFFERED_P (tested before taking the stream lock)
2619 @c buffered_vfprintf ok
2620 @c __find_spec(wc|mb)
2621 @c read_int
2622 @c __libc_use_alloca
2623 @c process_arg
2624 @c process_string_arg
2625 @c extend_alloca
2626 @c __parse_one_spec(wc|mb)
2627 @c *__printf_arginfo_table unguarded
2628 @c __printf_va_arg_table-> unguarded
2629 @c *__printf_function_table unguarded
2630 @c done_add
2631 @c printf_unknown
2632 @c   outchar
2633 @c   _itoa_word
2634 This is the equivalent of @code{fprintf} with the variable argument list
2635 specified directly as for @code{vprintf}.
2636 @end deftypefun
2638 @deftypefun int vfwprintf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
2639 @standards{ISO, wchar.h}
2640 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
2641 This is the equivalent of @code{fwprintf} with the variable argument list
2642 specified directly as for @code{vwprintf}.
2643 @end deftypefun
2645 @deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
2646 @standards{ISO, stdio.h}
2647 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2648 This is the equivalent of @code{sprintf} with the variable argument list
2649 specified directly as for @code{vprintf}.
2650 @end deftypefun
2652 @deftypefun int vswprintf (wchar_t *@var{ws}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap})
2653 @standards{GNU, wchar.h}
2654 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2655 This is the equivalent of @code{swprintf} with the variable argument list
2656 specified directly as for @code{vwprintf}.
2657 @end deftypefun
2659 @deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
2660 @standards{GNU, stdio.h}
2661 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2662 This is the equivalent of @code{snprintf} with the variable argument list
2663 specified directly as for @code{vprintf}.
2664 @end deftypefun
2666 @deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
2667 @standards{GNU, stdio.h}
2668 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2669 The @code{vasprintf} function is the equivalent of @code{asprintf} with the
2670 variable argument list specified directly as for @code{vprintf}.
2671 @end deftypefun
2673 @deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
2674 @standards{GNU, stdio.h}
2675 @safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
2676 @c The obstack is not guarded by mutexes, it might be at an inconsistent
2677 @c state within a signal handler, and it could be left at an
2678 @c inconsistent state in case of cancellation.
2679 The @code{obstack_vprintf} function is the equivalent of
2680 @code{obstack_printf} with the variable argument list specified directly
2681 as for @code{vprintf}.@refill
2682 @end deftypefun
2684 Here's an example showing how you might use @code{vfprintf}.  This is a
2685 function that prints error messages to the stream @code{stderr}, along
2686 with a prefix indicating the name of the program
2687 (@pxref{Error Messages}, for a description of
2688 @code{program_invocation_short_name}).
2690 @smallexample
2691 @group
2692 #include <stdio.h>
2693 #include <stdarg.h>
2695 void
2696 eprintf (const char *template, ...)
2698   va_list ap;
2699   extern char *program_invocation_short_name;
2701   fprintf (stderr, "%s: ", program_invocation_short_name);
2702   va_start (ap, template);
2703   vfprintf (stderr, template, ap);
2704   va_end (ap);
2706 @end group
2707 @end smallexample
2709 @noindent
2710 You could call @code{eprintf} like this:
2712 @smallexample
2713 eprintf ("file `%s' does not exist\n", filename);
2714 @end smallexample
2716 In GNU C, there is a special construct you can use to let the compiler
2717 know that a function uses a @code{printf}-style format string.  Then it
2718 can check the number and types of arguments in each call to the
2719 function, and warn you when they do not match the format string.
2720 For example, take this declaration of @code{eprintf}:
2722 @smallexample
2723 void eprintf (const char *template, ...)
2724         __attribute__ ((format (printf, 1, 2)));
2725 @end smallexample
2727 @noindent
2728 This tells the compiler that @code{eprintf} uses a format string like
2729 @code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input});
2730 the format string appears as the first argument;
2731 and the arguments to satisfy the format begin with the second.
2732 @xref{Function Attributes, , Declaring Attributes of Functions,
2733 gcc.info, Using GNU CC}, for more information.
2735 @node Parsing a Template String
2736 @subsection Parsing a Template String
2737 @cindex parsing a template string
2739 You can use the function @code{parse_printf_format} to obtain
2740 information about the number and types of arguments that are expected by
2741 a given template string.  This function permits interpreters that
2742 provide interfaces to @code{printf} to avoid passing along invalid
2743 arguments from the user's program, which could cause a crash.
2745 All the symbols described in this section are declared in the header
2746 file @file{printf.h}.
2748 @deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
2749 @standards{GNU, printf.h}
2750 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2751 This function returns information about the number and types of
2752 arguments expected by the @code{printf} template string @var{template}.
2753 The information is stored in the array @var{argtypes}; each element of
2754 this array describes one argument.  This information is encoded using
2755 the various @samp{PA_} macros, listed below.
2757 The argument @var{n} specifies the number of elements in the array
2758 @var{argtypes}.  This is the maximum number of elements that
2759 @code{parse_printf_format} will try to write.
2761 @code{parse_printf_format} returns the total number of arguments required
2762 by @var{template}.  If this number is greater than @var{n}, then the
2763 information returned describes only the first @var{n} arguments.  If you
2764 want information about additional arguments, allocate a bigger
2765 array and call @code{parse_printf_format} again.
2766 @end deftypefun
2768 The argument types are encoded as a combination of a basic type and
2769 modifier flag bits.
2771 @deftypevr Macro int PA_FLAG_MASK
2772 @standards{GNU, printf.h}
2773 This macro is a bitmask for the type modifier flag bits.  You can write
2774 the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the
2775 flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to
2776 extract just the basic type code.
2777 @end deftypevr
2779 Here are symbolic constants that represent the basic types; they stand
2780 for integer values.
2782 @vtable @code
2783 @item PA_INT
2784 @standards{GNU, printf.h}
2785 This specifies that the base type is @code{int}.
2787 @item PA_CHAR
2788 @standards{GNU, printf.h}
2789 This specifies that the base type is @code{int}, cast to @code{char}.
2791 @item PA_STRING
2792 @standards{GNU, printf.h}
2793 This specifies that the base type is @code{char *}, a null-terminated string.
2795 @item PA_POINTER
2796 @standards{GNU, printf.h}
2797 This specifies that the base type is @code{void *}, an arbitrary pointer.
2799 @item PA_FLOAT
2800 @standards{GNU, printf.h}
2801 This specifies that the base type is @code{float}.
2803 @item PA_DOUBLE
2804 @standards{GNU, printf.h}
2805 This specifies that the base type is @code{double}.
2807 @item PA_LAST
2808 @standards{GNU, printf.h}
2809 You can define additional base types for your own programs as offsets
2810 from @code{PA_LAST}.  For example, if you have data types @samp{foo}
2811 and @samp{bar} with their own specialized @code{printf} conversions,
2812 you could define encodings for these types as:
2814 @smallexample
2815 #define PA_FOO  PA_LAST
2816 #define PA_BAR  (PA_LAST + 1)
2817 @end smallexample
2818 @end vtable
2820 Here are the flag bits that modify a basic type.  They are combined with
2821 the code for the basic type using inclusive-or.
2823 @vtable @code
2824 @item PA_FLAG_PTR
2825 @standards{GNU, printf.h}
2826 If this bit is set, it indicates that the encoded type is a pointer to
2827 the base type, rather than an immediate value.
2828 For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.
2830 @item PA_FLAG_SHORT
2831 @standards{GNU, printf.h}
2832 If this bit is set, it indicates that the base type is modified with
2833 @code{short}.  (This corresponds to the @samp{h} type modifier.)
2835 @item PA_FLAG_LONG
2836 @standards{GNU, printf.h}
2837 If this bit is set, it indicates that the base type is modified with
2838 @code{long}.  (This corresponds to the @samp{l} type modifier.)
2840 @item PA_FLAG_LONG_LONG
2841 @standards{GNU, printf.h}
2842 If this bit is set, it indicates that the base type is modified with
2843 @code{long long}.  (This corresponds to the @samp{L} type modifier.)
2845 @item PA_FLAG_LONG_DOUBLE
2846 @standards{GNU, printf.h}
2847 This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with
2848 a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
2849 @end vtable
2851 @ifinfo
2852 For an example of using these facilities, see @ref{Example of Parsing}.
2853 @end ifinfo
2855 @node Example of Parsing
2856 @subsection Example of Parsing a Template String
2858 Here is an example of decoding argument types for a format string.  We
2859 assume this is part of an interpreter which contains arguments of type
2860 @code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
2861 perhaps others which are not valid here).
2863 @smallexample
2864 /* @r{Test whether the @var{nargs} specified objects}
2865    @r{in the vector @var{args} are valid}
2866    @r{for the format string @var{format}:}
2867    @r{if so, return 1.}
2868    @r{If not, return 0 after printing an error message.}  */
2871 validate_args (char *format, int nargs, OBJECT *args)
2873   int *argtypes;
2874   int nwanted;
2876   /* @r{Get the information about the arguments.}
2877      @r{Each conversion specification must be at least two characters}
2878      @r{long, so there cannot be more specifications than half the}
2879      @r{length of the string.}  */
2881   argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
2882   nwanted = parse_printf_format (string, nelts, argtypes);
2884   /* @r{Check the number of arguments.}  */
2885   if (nwanted > nargs)
2886     @{
2887       error ("too few arguments (at least %d required)", nwanted);
2888       return 0;
2889     @}
2891   /* @r{Check the C type wanted for each argument}
2892      @r{and see if the object given is suitable.}  */
2893   for (i = 0; i < nwanted; i++)
2894     @{
2895       int wanted;
2897       if (argtypes[i] & PA_FLAG_PTR)
2898         wanted = STRUCTURE;
2899       else
2900         switch (argtypes[i] & ~PA_FLAG_MASK)
2901           @{
2902           case PA_INT:
2903           case PA_FLOAT:
2904           case PA_DOUBLE:
2905             wanted = NUMBER;
2906             break;
2907           case PA_CHAR:
2908             wanted = CHAR;
2909             break;
2910           case PA_STRING:
2911             wanted = STRING;
2912             break;
2913           case PA_POINTER:
2914             wanted = STRUCTURE;
2915             break;
2916           @}
2917       if (TYPE (args[i]) != wanted)
2918         @{
2919           error ("type mismatch for arg number %d", i);
2920           return 0;
2921         @}
2922     @}
2923   return 1;
2925 @end smallexample
2927 @node Customizing Printf
2928 @section Customizing @code{printf}
2929 @cindex customizing @code{printf}
2930 @cindex defining new @code{printf} conversions
2931 @cindex extending @code{printf}
2933 @Theglibc{} lets you define your own custom conversion specifiers
2934 for @code{printf} template strings, to teach @code{printf} clever ways
2935 to print the important data structures of your program.
2937 The way you do this is by registering the conversion with the function
2938 @code{register_printf_function}; see @ref{Registering New Conversions}.
2939 One of the arguments you pass to this function is a pointer to a handler
2940 function that produces the actual output; see @ref{Defining the Output
2941 Handler}, for information on how to write this function.
2943 You can also install a function that just returns information about the
2944 number and type of arguments expected by the conversion specifier.
2945 @xref{Parsing a Template String}, for information about this.
2947 The facilities of this section are declared in the header file
2948 @file{printf.h}.
2950 @menu
2951 * Registering New Conversions::         Using @code{register_printf_function}
2952                                          to register a new output conversion.
2953 * Conversion Specifier Options::        The handler must be able to get
2954                                          the options specified in the
2955                                          template when it is called.
2956 * Defining the Output Handler::         Defining the handler and arginfo
2957                                          functions that are passed as arguments
2958                                          to @code{register_printf_function}.
2959 * Printf Extension Example::            How to define a @code{printf}
2960                                          handler function.
2961 * Predefined Printf Handlers::          Predefined @code{printf} handlers.
2962 @end menu
2964 @strong{Portability Note:} The ability to extend the syntax of
2965 @code{printf} template strings is a GNU extension.  ISO standard C has
2966 nothing similar.
2968 @node Registering New Conversions
2969 @subsection Registering New Conversions
2971 The function to register a new output conversion is
2972 @code{register_printf_function}, declared in @file{printf.h}.
2973 @pindex printf.h
2975 @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function})
2976 @standards{GNU, printf.h}
2977 @safety{@prelim{}@mtunsafe{@mtasuconst{:printfext}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
2978 @c This function is guarded by the global non-recursive libc lock, but
2979 @c users of the variables it sets aren't, and those should be MT-Safe,
2980 @c so we're ruling out the use of this extension with threads.  Calling
2981 @c it from a signal handler may self-deadlock, and cancellation may
2982 @c leave the lock held, besides leaking allocated memory.
2983 This function defines the conversion specifier character @var{spec}.
2984 Thus, if @var{spec} is @code{'Y'}, it defines the conversion @samp{%Y}.
2985 You can redefine the built-in conversions like @samp{%s}, but flag
2986 characters like @samp{#} and type modifiers like @samp{l} can never be
2987 used as conversions; calling @code{register_printf_function} for those
2988 characters has no effect.  It is advisable not to use lowercase letters,
2989 since the ISO C standard warns that additional lowercase letters may be
2990 standardized in future editions of the standard.
2992 The @var{handler-function} is the function called by @code{printf} and
2993 friends when this conversion appears in a template string.
2994 @xref{Defining the Output Handler}, for information about how to define
2995 a function to pass as this argument.  If you specify a null pointer, any
2996 existing handler function for @var{spec} is removed.
2998 The @var{arginfo-function} is the function called by
2999 @code{parse_printf_format} when this conversion appears in a
3000 template string.  @xref{Parsing a Template String}, for information
3001 about this.
3003 @c The following is not true anymore.  The `parse_printf_format' function
3004 @c is now also called from `vfprintf' via `parse_one_spec'.
3005 @c --drepper@gnu, 1996/11/14
3007 @c Normally, you install both functions for a conversion at the same time,
3008 @c but if you are never going to call @code{parse_printf_format}, you do
3009 @c not need to define an arginfo function.
3011 @strong{Attention:} In @theglibc{} versions before 2.0 the
3012 @var{arginfo-function} function did not need to be installed unless
3013 the user used the @code{parse_printf_format} function.  This has changed.
3014 Now a call to any of the @code{printf} functions will call this
3015 function when this format specifier appears in the format string.
3017 The return value is @code{0} on success, and @code{-1} on failure
3018 (which occurs if @var{spec} is out of range).
3020 You can redefine the standard output conversions, but this is probably
3021 not a good idea because of the potential for confusion.  Library routines
3022 written by other people could break if you do this.
3023 @end deftypefun
3025 @node Conversion Specifier Options
3026 @subsection Conversion Specifier Options
3028 If you define a meaning for @samp{%A}, what if the template contains
3029 @samp{%+23A} or @samp{%-#A}?  To implement a sensible meaning for these,
3030 the handler when called needs to be able to get the options specified in
3031 the template.
3033 Both the @var{handler-function} and @var{arginfo-function} accept an
3034 argument that points to a @code{struct printf_info}, which contains
3035 information about the options appearing in an instance of the conversion
3036 specifier.  This data type is declared in the header file
3037 @file{printf.h}.
3038 @pindex printf.h
3040 @deftp {Type} {struct printf_info}
3041 @standards{GNU, printf.h}
3042 This structure is used to pass information about the options appearing
3043 in an instance of a conversion specifier in a @code{printf} template
3044 string to the handler and arginfo functions for that specifier.  It
3045 contains the following members:
3047 @table @code
3048 @item int prec
3049 This is the precision specified.  The value is @code{-1} if no precision
3050 was specified.  If the precision was given as @samp{*}, the
3051 @code{printf_info} structure passed to the handler function contains the
3052 actual value retrieved from the argument list.  But the structure passed
3053 to the arginfo function contains a value of @code{INT_MIN}, since the
3054 actual value is not known.
3056 @item int width
3057 This is the minimum field width specified.  The value is @code{0} if no
3058 width was specified.  If the field width was given as @samp{*}, the
3059 @code{printf_info} structure passed to the handler function contains the
3060 actual value retrieved from the argument list.  But the structure passed
3061 to the arginfo function contains a value of @code{INT_MIN}, since the
3062 actual value is not known.
3064 @item wchar_t spec
3065 This is the conversion specifier character specified.  It's stored in
3066 the structure so that you can register the same handler function for
3067 multiple characters, but still have a way to tell them apart when the
3068 handler function is called.
3070 @item unsigned int is_long_double
3071 This is a boolean that is true if the @samp{L}, @samp{ll}, or @samp{q}
3072 type modifier was specified.  For integer conversions, this indicates
3073 @code{long long int}, as opposed to @code{long double} for floating
3074 point conversions.
3076 @item unsigned int is_char
3077 This is a boolean that is true if the @samp{hh} type modifier was specified.
3079 @item unsigned int is_short
3080 This is a boolean that is true if the @samp{h} type modifier was specified.
3082 @item unsigned int is_long
3083 This is a boolean that is true if the @samp{l} type modifier was specified.
3085 @item unsigned int alt
3086 This is a boolean that is true if the @samp{#} flag was specified.
3088 @item unsigned int space
3089 This is a boolean that is true if the @samp{ } flag was specified.
3091 @item unsigned int left
3092 This is a boolean that is true if the @samp{-} flag was specified.
3094 @item unsigned int showsign
3095 This is a boolean that is true if the @samp{+} flag was specified.
3097 @item unsigned int group
3098 This is a boolean that is true if the @samp{'} flag was specified.
3100 @item unsigned int extra
3101 This flag has a special meaning depending on the context.  It could
3102 be used freely by the user-defined handlers but when called from
3103 the @code{printf} function this variable always contains the value
3104 @code{0}.
3106 @item unsigned int wide
3107 This flag is set if the stream is wide oriented.
3109 @item wchar_t pad
3110 This is the character to use for padding the output to the minimum field
3111 width.  The value is @code{'0'} if the @samp{0} flag was specified, and
3112 @code{' '} otherwise.
3113 @end table
3114 @end deftp
3117 @node Defining the Output Handler
3118 @subsection Defining the Output Handler
3120 Now let's look at how to define the handler and arginfo functions
3121 which are passed as arguments to @code{register_printf_function}.
3123 @strong{Compatibility Note:} The interface changed in @theglibc{}
3124 version 2.0.  Previously the third argument was of type
3125 @code{va_list *}.
3127 You should define your handler functions with a prototype like:
3129 @smallexample
3130 int @var{function} (FILE *stream, const struct printf_info *info,
3131                     const void *const *args)
3132 @end smallexample
3134 The @var{stream} argument passed to the handler function is the stream to
3135 which it should write output.
3137 The @var{info} argument is a pointer to a structure that contains
3138 information about the various options that were included with the
3139 conversion in the template string.  You should not modify this structure
3140 inside your handler function.  @xref{Conversion Specifier Options}, for
3141 a description of this data structure.
3143 @c The following changes some time back.  --drepper@gnu, 1996/11/14
3145 @c The @code{ap_pointer} argument is used to pass the tail of the variable
3146 @c argument list containing the values to be printed to your handler.
3147 @c Unlike most other functions that can be passed an explicit variable
3148 @c argument list, this is a @emph{pointer} to a @code{va_list}, rather than
3149 @c the @code{va_list} itself.  Thus, you should fetch arguments by
3150 @c means of @code{va_arg (*ap_pointer, @var{type})}.
3152 @c (Passing a pointer here allows the function that calls your handler
3153 @c function to update its own @code{va_list} variable to account for the
3154 @c arguments that your handler processes.  @xref{Variadic Functions}.)
3156 The @var{args} is a vector of pointers to the arguments data.
3157 The number of arguments was determined by calling the argument
3158 information function provided by the user.
3160 Your handler function should return a value just like @code{printf}
3161 does: it should return the number of characters it has written, or a
3162 negative value to indicate an error.
3164 @deftp {Data Type} printf_function
3165 @standards{GNU, printf.h}
3166 This is the data type that a handler function should have.
3167 @end deftp
3169 If you are going to use @w{@code{parse_printf_format}} in your
3170 application, you must also define a function to pass as the
3171 @var{arginfo-function} argument for each new conversion you install with
3172 @code{register_printf_function}.
3174 You have to define these functions with a prototype like:
3176 @smallexample
3177 int @var{function} (const struct printf_info *info,
3178                     size_t n, int *argtypes)
3179 @end smallexample
3181 The return value from the function should be the number of arguments the
3182 conversion expects.  The function should also fill in no more than
3183 @var{n} elements of the @var{argtypes} array with information about the
3184 types of each of these arguments.  This information is encoded using the
3185 various @samp{PA_} macros.  (You will notice that this is the same
3186 calling convention @code{parse_printf_format} itself uses.)
3188 @deftp {Data Type} printf_arginfo_function
3189 @standards{GNU, printf.h}
3190 This type is used to describe functions that return information about
3191 the number and type of arguments used by a conversion specifier.
3192 @end deftp
3194 @node Printf Extension Example
3195 @subsection @code{printf} Extension Example
3197 Here is an example showing how to define a @code{printf} handler function.
3198 This program defines a data structure called a @code{Widget} and
3199 defines the @samp{%W} conversion to print information about @w{@code{Widget *}}
3200 arguments, including the pointer value and the name stored in the data
3201 structure.  The @samp{%W} conversion supports the minimum field width and
3202 left-justification options, but ignores everything else.
3204 @smallexample
3205 @include rprintf.c.texi
3206 @end smallexample
3208 The output produced by this program looks like:
3210 @smallexample
3211 |<Widget 0xffeffb7c: mywidget>|
3212 |      <Widget 0xffeffb7c: mywidget>|
3213 |<Widget 0xffeffb7c: mywidget>      |
3214 @end smallexample
3216 @node Predefined Printf Handlers
3217 @subsection Predefined @code{printf} Handlers
3219 @Theglibc{} also contains a concrete and useful application of the
3220 @code{printf} handler extension.  There are two functions available
3221 which implement a special way to print floating-point numbers.
3223 @deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args})
3224 @standards{GNU, printf.h}
3225 @safety{@prelim{}@mtsafe{@mtsrace{:fp} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @acucorrupt{}}}
3226 @c This is meant to be called by vfprintf, that should hold the lock on
3227 @c the stream, but if this function is called directly, output will be
3228 @c racy, besides the uses of the global locale object while other
3229 @c threads may be changing it and the possbility of leaving the stream
3230 @c object in an inconsistent state in case of cancellation.
3231 Print a given floating point number as for the format @code{%f} except
3232 that there is a postfix character indicating the divisor for the
3233 number to make this less than 1000.  There are two possible divisors:
3234 powers of 1024 or powers of 1000.  Which one is used depends on the
3235 format character specified while registered this handler.  If the
3236 character is of lower case, 1024 is used.  For upper case characters,
3237 1000 is used.
3239 The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes,
3240 etc.  The full table is:
3242 @ifinfo
3243 @multitable {' '} {2^10 (1024)} {zetta} {Upper} {10^24 (1000)}
3244 @item low @tab Multiplier  @tab From  @tab Upper @tab Multiplier
3245 @item ' ' @tab 1           @tab       @tab ' '   @tab 1
3246 @item k   @tab 2^10 (1024) @tab kilo  @tab K     @tab 10^3 (1000)
3247 @item m   @tab 2^20        @tab mega  @tab M     @tab 10^6
3248 @item g   @tab 2^30        @tab giga  @tab G     @tab 10^9
3249 @item t   @tab 2^40        @tab tera  @tab T     @tab 10^12
3250 @item p   @tab 2^50        @tab peta  @tab P     @tab 10^15
3251 @item e   @tab 2^60        @tab exa   @tab E     @tab 10^18
3252 @item z   @tab 2^70        @tab zetta @tab Z     @tab 10^21
3253 @item y   @tab 2^80        @tab yotta @tab Y     @tab 10^24
3254 @end multitable
3255 @end ifinfo
3256 @iftex
3257 @tex
3258 \hbox to\hsize{\hfil\vbox{\offinterlineskip
3259 \hrule
3260 \halign{\strut#& \vrule#\tabskip=1em plus2em& {\tt#}\hfil& \vrule#& #\hfil& \vrule#& #\hfil& \vrule#& {\tt#}\hfil& \vrule#& #\hfil& \vrule#\tabskip=0pt\cr
3261 \noalign{\hrule}
3262 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
3263 && \omit low && Multiplier && From && \omit Upper && Multiplier &\cr
3264 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
3265 \noalign{\hrule}
3266 && {\tt\char32} &&  1 && && {\tt\char32} && 1 &\cr
3267 && k && $2^{10} = 1024$ && kilo && K && $10^3 = 1000$ &\cr
3268 && m && $2^{20}$ && mega && M && $10^6$ &\cr
3269 && g && $2^{30}$ && giga && G && $10^9$ &\cr
3270 && t && $2^{40}$ && tera && T && $10^{12}$ &\cr
3271 && p && $2^{50}$ && peta && P && $10^{15}$ &\cr
3272 && e && $2^{60}$ && exa && E && $10^{18}$ &\cr
3273 && z && $2^{70}$ && zetta && Z && $10^{21}$ &\cr
3274 && y && $2^{80}$ && yotta && Y && $10^{24}$ &\cr
3275 \noalign{\hrule}}}\hfil}
3276 @end tex
3277 @end iftex
3279 The default precision is 3, i.e., 1024 is printed with a lower-case
3280 format character as if it were @code{%.3fk} and will yield @code{1.000k}.
3281 @end deftypefun
3283 Due to the requirements of @code{register_printf_function} we must also
3284 provide the function which returns information about the arguments.
3286 @deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes})
3287 @standards{GNU, printf.h}
3288 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3289 This function will return in @var{argtypes} the information about the
3290 used parameters in the way the @code{vfprintf} implementation expects
3291 it.  The format always takes one argument.
3292 @end deftypefun
3294 To use these functions both functions must be registered with a call like
3296 @smallexample
3297 register_printf_function ('B', printf_size, printf_size_info);
3298 @end smallexample
3300 Here we register the functions to print numbers as powers of 1000 since
3301 the format character @code{'B'} is an upper-case character.  If we
3302 would additionally use @code{'b'} in a line like
3304 @smallexample
3305 register_printf_function ('b', printf_size, printf_size_info);
3306 @end smallexample
3308 @noindent
3309 we could also print using a power of 1024.  Please note that all that is
3310 different in these two lines is the format specifier.  The
3311 @code{printf_size} function knows about the difference between lower and upper
3312 case format specifiers.
3314 The use of @code{'B'} and @code{'b'} is no coincidence.  Rather it is
3315 the preferred way to use this functionality since it is available on
3316 some other systems which also use format specifiers.
3318 @node Formatted Input
3319 @section Formatted Input
3321 @cindex formatted input from a stream
3322 @cindex reading from a stream, formatted
3323 @cindex format string, for @code{scanf}
3324 @cindex template, for @code{scanf}
3325 The functions described in this section (@code{scanf} and related
3326 functions) provide facilities for formatted input analogous to the
3327 formatted output facilities.  These functions provide a mechanism for
3328 reading arbitrary values under the control of a @dfn{format string} or
3329 @dfn{template string}.
3331 @menu
3332 * Formatted Input Basics::      Some basics to get you started.
3333 * Input Conversion Syntax::     Syntax of conversion specifications.
3334 * Table of Input Conversions::  Summary of input conversions and what they do.
3335 * Numeric Input Conversions::   Details of conversions for reading numbers.
3336 * String Input Conversions::    Details of conversions for reading strings.
3337 * Dynamic String Input::        String conversions that @code{malloc} the buffer.
3338 * Other Input Conversions::     Details of miscellaneous other conversions.
3339 * Formatted Input Functions::   Descriptions of the actual functions.
3340 * Variable Arguments Input::    @code{vscanf} and friends.
3341 @end menu
3343 @node Formatted Input Basics
3344 @subsection Formatted Input Basics
3346 Calls to @code{scanf} are superficially similar to calls to
3347 @code{printf} in that arbitrary arguments are read under the control of
3348 a template string.  While the syntax of the conversion specifications in
3349 the template is very similar to that for @code{printf}, the
3350 interpretation of the template is oriented more towards free-format
3351 input and simple pattern matching, rather than fixed-field formatting.
3352 For example, most @code{scanf} conversions skip over any amount of
3353 ``white space'' (including spaces, tabs, and newlines) in the input
3354 file, and there is no concept of precision for the numeric input
3355 conversions as there is for the corresponding output conversions.
3356 Ordinarily, non-whitespace characters in the template are expected to
3357 match characters in the input stream exactly, but a matching failure is
3358 distinct from an input error on the stream.
3359 @cindex conversion specifications (@code{scanf})
3361 Another area of difference between @code{scanf} and @code{printf} is
3362 that you must remember to supply pointers rather than immediate values
3363 as the optional arguments to @code{scanf}; the values that are read are
3364 stored in the objects that the pointers point to.  Even experienced
3365 programmers tend to forget this occasionally, so if your program is
3366 getting strange errors that seem to be related to @code{scanf}, you
3367 might want to double-check this.
3369 When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
3370 leaving the first non-matching character as the next character to be
3371 read from the stream.  The normal return value from @code{scanf} is the
3372 number of values that were assigned, so you can use this to determine if
3373 a matching error happened before all the expected values were read.
3374 @cindex matching failure, in @code{scanf}
3376 The @code{scanf} function is typically used for things like reading in
3377 the contents of tables.  For example, here is a function that uses
3378 @code{scanf} to initialize an array of @code{double}:
3380 @smallexample
3381 void
3382 readarray (double *array, int n)
3384   int i;
3385   for (i=0; i<n; i++)
3386     if (scanf (" %lf", &(array[i])) != 1)
3387       invalid_input_error ();
3389 @end smallexample
3391 The formatted input functions are not used as frequently as the
3392 formatted output functions.  Partly, this is because it takes some care
3393 to use them properly.  Another reason is that it is difficult to recover
3394 from a matching error.
3396 If you are trying to read input that doesn't match a single, fixed
3397 pattern, you may be better off using a tool such as Flex to generate a
3398 lexical scanner, or Bison to generate a parser, rather than using
3399 @code{scanf}.  For more information about these tools, see @ref{Top, , ,
3400 flex.info, Flex: The Lexical Scanner Generator}, and @ref{Top, , ,
3401 bison.info, The Bison Reference Manual}.
3403 @node Input Conversion Syntax
3404 @subsection Input Conversion Syntax
3406 A @code{scanf} template string is a string that contains ordinary
3407 multibyte characters interspersed with conversion specifications that
3408 start with @samp{%}.
3410 Any whitespace character (as defined by the @code{isspace} function;
3411 @pxref{Classification of Characters}) in the template causes any number
3412 of whitespace characters in the input stream to be read and discarded.
3413 The whitespace characters that are matched need not be exactly the same
3414 whitespace characters that appear in the template string.  For example,
3415 write @samp{ , } in the template to recognize a comma with optional
3416 whitespace before and after.
3418 Other characters in the template string that are not part of conversion
3419 specifications must match characters in the input stream exactly; if
3420 this is not the case, a matching failure occurs.
3422 The conversion specifications in a @code{scanf} template string
3423 have the general form:
3425 @smallexample
3426 % @var{flags} @var{width} @var{type} @var{conversion}
3427 @end smallexample
3429 In more detail, an input conversion specification consists of an initial
3430 @samp{%} character followed in sequence by:
3432 @itemize @bullet
3433 @item
3434 An optional @dfn{flag character} @samp{*}, which says to ignore the text
3435 read for this specification.  When @code{scanf} finds a conversion
3436 specification that uses this flag, it reads input as directed by the
3437 rest of the conversion specification, but it discards this input, does
3438 not use a pointer argument, and does not increment the count of
3439 successful assignments.
3440 @cindex flag character (@code{scanf})
3442 @item
3443 An optional flag character @samp{a} (valid with string conversions only)
3444 which requests allocation of a buffer long enough to store the string in.
3445 (This is a GNU extension.)
3446 @xref{Dynamic String Input}.
3448 @item
3449 An optional decimal integer that specifies the @dfn{maximum field
3450 width}.  Reading of characters from the input stream stops either when
3451 this maximum is reached or when a non-matching character is found,
3452 whichever happens first.  Most conversions discard initial whitespace
3453 characters (those that don't are explicitly documented), and these
3454 discarded characters don't count towards the maximum field width.
3455 String input conversions store a null character to mark the end of the
3456 input; the maximum field width does not include this terminator.
3457 @cindex maximum field width (@code{scanf})
3459 @item
3460 An optional @dfn{type modifier character}.  For example, you can
3461 specify a type modifier of @samp{l} with integer conversions such as
3462 @samp{%d} to specify that the argument is a pointer to a @code{long int}
3463 rather than a pointer to an @code{int}.
3464 @cindex type modifier character (@code{scanf})
3466 @item
3467 A character that specifies the conversion to be applied.
3468 @end itemize
3470 The exact options that are permitted and how they are interpreted vary
3471 between the different conversion specifiers.  See the descriptions of the
3472 individual conversions for information about the particular options that
3473 they allow.
3475 With the @samp{-Wformat} option, the GNU C compiler checks calls to
3476 @code{scanf} and related functions.  It examines the format string and
3477 verifies that the correct number and types of arguments are supplied.
3478 There is also a GNU C syntax to tell the compiler that a function you
3479 write uses a @code{scanf}-style format string.
3480 @xref{Function Attributes, , Declaring Attributes of Functions,
3481 gcc.info, Using GNU CC}, for more information.
3483 @node Table of Input Conversions
3484 @subsection Table of Input Conversions
3485 @cindex input conversions, for @code{scanf}
3487 Here is a table that summarizes the various conversion specifications:
3489 @table @asis
3490 @item @samp{%d}
3491 Matches an optionally signed integer written in decimal.  @xref{Numeric
3492 Input Conversions}.
3494 @item @samp{%i}
3495 Matches an optionally signed integer in any of the formats that the C
3496 language defines for specifying an integer constant.  @xref{Numeric
3497 Input Conversions}.
3499 @item @samp{%o}
3500 Matches an unsigned integer written in octal radix.
3501 @xref{Numeric Input Conversions}.
3503 @item @samp{%u}
3504 Matches an unsigned integer written in decimal radix.
3505 @xref{Numeric Input Conversions}.
3507 @item @samp{%x}, @samp{%X}
3508 Matches an unsigned integer written in hexadecimal radix.
3509 @xref{Numeric Input Conversions}.
3511 @item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
3512 Matches an optionally signed floating-point number.  @xref{Numeric Input
3513 Conversions}.
3515 @item @samp{%s}
3517 Matches a string containing only non-whitespace characters.
3518 @xref{String Input Conversions}.  The presence of the @samp{l} modifier
3519 determines whether the output is stored as a wide character string or a
3520 multibyte string.  If @samp{%s} is used in a wide character function the
3521 string is converted as with multiple calls to @code{wcrtomb} into a
3522 multibyte string.  This means that the buffer must provide room for
3523 @code{MB_CUR_MAX} bytes for each wide character read.  In case
3524 @samp{%ls} is used in a multibyte function the result is converted into
3525 wide characters as with multiple calls of @code{mbrtowc} before being
3526 stored in the user provided buffer.
3528 @item @samp{%S}
3529 This is an alias for @samp{%ls} which is supported for compatibility
3530 with the Unix standard.
3532 @item @samp{%[}
3533 Matches a string of characters that belong to a specified set.
3534 @xref{String Input Conversions}.  The presence of the @samp{l} modifier
3535 determines whether the output is stored as a wide character string or a
3536 multibyte string.  If @samp{%[} is used in a wide character function the
3537 string is converted as with multiple calls to @code{wcrtomb} into a
3538 multibyte string.  This means that the buffer must provide room for
3539 @code{MB_CUR_MAX} bytes for each wide character read.  In case
3540 @samp{%l[} is used in a multibyte function the result is converted into
3541 wide characters as with multiple calls of @code{mbrtowc} before being
3542 stored in the user provided buffer.
3544 @item @samp{%c}
3545 Matches a string of one or more characters; the number of characters
3546 read is controlled by the maximum field width given for the conversion.
3547 @xref{String Input Conversions}.
3549 If @samp{%c} is used in a wide stream function the read value is
3550 converted from a wide character to the corresponding multibyte character
3551 before storing it.  Note that this conversion can produce more than one
3552 byte of output and therefore the provided buffer must be large enough for up
3553 to @code{MB_CUR_MAX} bytes for each character.  If @samp{%lc} is used in
3554 a multibyte function the input is treated as a multibyte sequence (and
3555 not bytes) and the result is converted as with calls to @code{mbrtowc}.
3557 @item @samp{%C}
3558 This is an alias for @samp{%lc} which is supported for compatibility
3559 with the Unix standard.
3561 @item @samp{%p}
3562 Matches a pointer value in the same implementation-defined format used
3563 by the @samp{%p} output conversion for @code{printf}.  @xref{Other Input
3564 Conversions}.
3566 @item @samp{%n}
3567 This conversion doesn't read any characters; it records the number of
3568 characters read so far by this call.  @xref{Other Input Conversions}.
3570 @item @samp{%%}
3571 This matches a literal @samp{%} character in the input stream.  No
3572 corresponding argument is used.  @xref{Other Input Conversions}.
3573 @end table
3575 If the syntax of a conversion specification is invalid, the behavior is
3576 undefined.  If there aren't enough function arguments provided to supply
3577 addresses for all the conversion specifications in the template strings
3578 that perform assignments, or if the arguments are not of the correct
3579 types, the behavior is also undefined.  On the other hand, extra
3580 arguments are simply ignored.
3582 @node Numeric Input Conversions
3583 @subsection Numeric Input Conversions
3585 This section describes the @code{scanf} conversions for reading numeric
3586 values.
3588 The @samp{%d} conversion matches an optionally signed integer in decimal
3589 radix.  The syntax that is recognized is the same as that for the
3590 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3591 @code{10} for the @var{base} argument.
3593 The @samp{%i} conversion matches an optionally signed integer in any of
3594 the formats that the C language defines for specifying an integer
3595 constant.  The syntax that is recognized is the same as that for the
3596 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3597 @code{0} for the @var{base} argument.  (You can print integers in this
3598 syntax with @code{printf} by using the @samp{#} flag character with the
3599 @samp{%x}, @samp{%o}, or @samp{%d} conversion.  @xref{Integer Conversions}.)
3601 For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
3602 could be read in as integers under the @samp{%i} conversion.  Each of
3603 these specifies a number with decimal value @code{10}.
3605 The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned
3606 integers in octal, decimal, and hexadecimal radices, respectively.  The
3607 syntax that is recognized is the same as that for the @code{strtoul}
3608 function (@pxref{Parsing of Integers}) with the appropriate value
3609 (@code{8}, @code{10}, or @code{16}) for the @var{base} argument.
3611 The @samp{%X} conversion is identical to the @samp{%x} conversion.  They
3612 both permit either uppercase or lowercase letters to be used as digits.
3614 The default type of the corresponding argument for the @code{%d} and
3615 @code{%i} conversions is @code{int *}, and @code{unsigned int *} for the
3616 other integer conversions.  You can use the following type modifiers to
3617 specify other sizes of integer:
3619 @table @samp
3620 @item hh
3621 Specifies that the argument is a @code{signed char *} or @code{unsigned
3622 char *}.
3624 This modifier was introduced in @w{ISO C99}.
3626 @item h
3627 Specifies that the argument is a @code{short int *} or @code{unsigned
3628 short int *}.
3630 @item j
3631 Specifies that the argument is a @code{intmax_t *} or @code{uintmax_t *}.
3633 This modifier was introduced in @w{ISO C99}.
3635 @item l
3636 Specifies that the argument is a @code{long int *} or @code{unsigned
3637 long int *}.  Two @samp{l} characters is like the @samp{L} modifier, below.
3639 If used with @samp{%c} or @samp{%s} the corresponding parameter is
3640 considered as a pointer to a wide character or wide character string
3641 respectively.  This use of @samp{l} was introduced in @w{Amendment 1} to
3642 @w{ISO C90}.
3644 @need 100
3645 @item ll
3646 @itemx L
3647 @itemx q
3648 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
3649 GNU C compiler.  For systems that don't provide extra-long integers, this
3650 is the same as @code{long int}.)
3652 The @samp{q} modifier is another name for the same thing, which comes
3653 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
3654 @code{int}.
3656 @item t
3657 Specifies that the argument is a @code{ptrdiff_t *}.
3659 This modifier was introduced in @w{ISO C99}.
3661 @item z
3662 Specifies that the argument is a @code{size_t *}.
3664 This modifier was introduced in @w{ISO C99}.
3665 @end table
3667 All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
3668 input conversions are interchangeable.  They all match an optionally
3669 signed floating point number, in the same syntax as for the
3670 @code{strtod} function (@pxref{Parsing of Floats}).
3672 For the floating-point input conversions, the default argument type is
3673 @code{float *}.  (This is different from the corresponding output
3674 conversions, where the default type is @code{double}; remember that
3675 @code{float} arguments to @code{printf} are converted to @code{double}
3676 by the default argument promotions, but @code{float *} arguments are
3677 not promoted to @code{double *}.)  You can specify other sizes of float
3678 using these type modifiers:
3680 @table @samp
3681 @item l
3682 Specifies that the argument is of type @code{double *}.
3684 @item L
3685 Specifies that the argument is of type @code{long double *}.
3686 @end table
3688 For all the above number parsing formats there is an additional optional
3689 flag @samp{'}.  When this flag is given the @code{scanf} function
3690 expects the number represented in the input string to be formatted
3691 according to the grouping rules of the currently selected locale
3692 (@pxref{General Numeric}).
3694 If the @code{"C"} or @code{"POSIX"} locale is selected there is no
3695 difference.  But for a locale which specifies values for the appropriate
3696 fields in the locale the input must have the correct form in the input.
3697 Otherwise the longest prefix with a correct form is processed.
3699 @node String Input Conversions
3700 @subsection String Input Conversions
3702 This section describes the @code{scanf} input conversions for reading
3703 string and character values: @samp{%s}, @samp{%S}, @samp{%[}, @samp{%c},
3704 and @samp{%C}.
3706 You have two options for how to receive the input from these
3707 conversions:
3709 @itemize @bullet
3710 @item
3711 Provide a buffer to store it in.  This is the default.  You should
3712 provide an argument of type @code{char *} or @code{wchar_t *} (the
3713 latter if the @samp{l} modifier is present).
3715 @strong{Warning:} To make a robust program, you must make sure that the
3716 input (plus its terminating null) cannot possibly exceed the size of the
3717 buffer you provide.  In general, the only way to do this is to specify a
3718 maximum field width one less than the buffer size.  @strong{If you
3719 provide the buffer, always specify a maximum field width to prevent
3720 overflow.}
3722 @item
3723 Ask @code{scanf} to allocate a big enough buffer, by specifying the
3724 @samp{a} flag character.  This is a GNU extension.  You should provide
3725 an argument of type @code{char **} for the buffer address to be stored
3726 in.  @xref{Dynamic String Input}.
3727 @end itemize
3729 The @samp{%c} conversion is the simplest: it matches a fixed number of
3730 characters, always.  The maximum field width says how many characters to
3731 read; if you don't specify the maximum, the default is 1.  This
3732 conversion doesn't append a null character to the end of the text it
3733 reads.  It also does not skip over initial whitespace characters.  It
3734 reads precisely the next @var{n} characters, and fails if it cannot get
3735 that many.  Since there is always a maximum field width with @samp{%c}
3736 (whether specified, or 1 by default), you can always prevent overflow by
3737 making the buffer long enough.
3738 @comment Is character == byte here???  --drepper
3740 If the format is @samp{%lc} or @samp{%C} the function stores wide
3741 characters which are converted using the conversion determined at the
3742 time the stream was opened from the external byte stream.  The number of
3743 bytes read from the medium is limited by @code{MB_CUR_LEN * @var{n}} but
3744 at most @var{n} wide characters get stored in the output string.
3746 The @samp{%s} conversion matches a string of non-whitespace characters.
3747 It skips and discards initial whitespace, but stops when it encounters
3748 more whitespace after having read something.  It stores a null character
3749 at the end of the text that it reads.
3751 For example, reading the input:
3753 @smallexample
3754  hello, world
3755 @end smallexample
3757 @noindent
3758 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
3759 reading the same input with the conversion @samp{%10s} produces
3760 @code{"hello,"}.
3762 @strong{Warning:} If you do not specify a field width for @samp{%s},
3763 then the number of characters read is limited only by where the next
3764 whitespace character appears.  This almost certainly means that invalid
3765 input can make your program crash---which is a bug.
3767 The @samp{%ls} and @samp{%S} format are handled just like @samp{%s}
3768 except that the external byte sequence is converted using the conversion
3769 associated with the stream to wide characters with their own encoding.
3770 A width or precision specified with the format do not directly determine
3771 how many bytes are read from the stream since they measure wide
3772 characters.  But an upper limit can be computed by multiplying the value
3773 of the width or precision by @code{MB_CUR_MAX}.
3775 To read in characters that belong to an arbitrary set of your choice,
3776 use the @samp{%[} conversion.  You specify the set between the @samp{[}
3777 character and a following @samp{]} character, using the same syntax used
3778 in regular expressions for explicit sets of characters.  As special cases:
3780 @itemize @bullet
3781 @item
3782 A literal @samp{]} character can be specified as the first character
3783 of the set.
3785 @item
3786 An embedded @samp{-} character (that is, one that is not the first or
3787 last character of the set) is used to specify a range of characters.
3789 @item
3790 If a caret character @samp{^} immediately follows the initial @samp{[},
3791 then the set of allowed input characters is everything @emph{except}
3792 the characters listed.
3793 @end itemize
3795 The @samp{%[} conversion does not skip over initial whitespace
3796 characters.
3798 Note that the @dfn{character class} syntax available in character sets
3799 that appear inside regular expressions (such as @samp{[:alpha:]}) is
3800 @emph{not} available in the @samp{%[} conversion.
3802 Here are some examples of @samp{%[} conversions and what they mean:
3804 @table @samp
3805 @item %25[1234567890]
3806 Matches a string of up to 25 digits.
3808 @item %25[][]
3809 Matches a string of up to 25 square brackets.
3811 @item %25[^ \f\n\r\t\v]
3812 Matches a string up to 25 characters long that doesn't contain any of
3813 the standard whitespace characters.  This is slightly different from
3814 @samp{%s}, because if the input begins with a whitespace character,
3815 @samp{%[} reports a matching failure while @samp{%s} simply discards the
3816 initial whitespace.
3818 @item %25[a-z]
3819 Matches up to 25 lowercase characters.
3820 @end table
3822 As for @samp{%c} and @samp{%s} the @samp{%[} format is also modified to
3823 produce wide characters if the @samp{l} modifier is present.  All what
3824 is said about @samp{%ls} above is true for @samp{%l[}.
3826 One more reminder: the @samp{%s} and @samp{%[} conversions are
3827 @strong{dangerous} if you don't specify a maximum width or use the
3828 @samp{a} flag, because input too long would overflow whatever buffer you
3829 have provided for it.  No matter how long your buffer is, a user could
3830 supply input that is longer.  A well-written program reports invalid
3831 input with a comprehensible error message, not with a crash.
3833 @node Dynamic String Input
3834 @subsection Dynamically Allocating String Conversions
3836 A GNU extension to formatted input lets you safely read a string with no
3837 maximum size.  Using this feature, you don't supply a buffer; instead,
3838 @code{scanf} allocates a buffer big enough to hold the data and gives
3839 you its address.  To use this feature, write @samp{a} as a flag
3840 character, as in @samp{%as} or @samp{%a[0-9a-z]}.
3842 The pointer argument you supply for where to store the input should have
3843 type @code{char **}.  The @code{scanf} function allocates a buffer and
3844 stores its address in the word that the argument points to.  You should
3845 free the buffer with @code{free} when you no longer need it.
3847 Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]}
3848 conversion specification to read a ``variable assignment'' of the form
3849 @samp{@var{variable} = @var{value}}.
3851 @smallexample
3853   char *variable, *value;
3855   if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
3856                  &variable, &value))
3857     @{
3858       invalid_input_error ();
3859       return 0;
3860     @}
3862   @dots{}
3864 @end smallexample
3866 @node Other Input Conversions
3867 @subsection Other Input Conversions
3869 This section describes the miscellaneous input conversions.
3871 The @samp{%p} conversion is used to read a pointer value.  It recognizes
3872 the same syntax used by the @samp{%p} output conversion for
3873 @code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
3874 number just as the @samp{%x} conversion accepts.  The corresponding
3875 argument should be of type @code{void **}; that is, the address of a
3876 place to store a pointer.
3878 The resulting pointer value is not guaranteed to be valid if it was not
3879 originally written during the same program execution that reads it in.
3881 The @samp{%n} conversion produces the number of characters read so far
3882 by this call.  The corresponding argument should be of type @code{int *}.
3883 This conversion works in the same way as the @samp{%n} conversion for
3884 @code{printf}; see @ref{Other Output Conversions}, for an example.
3886 The @samp{%n} conversion is the only mechanism for determining the
3887 success of literal matches or conversions with suppressed assignments.
3888 If the @samp{%n} follows the locus of a matching failure, then no value
3889 is stored for it since @code{scanf} returns before processing the
3890 @samp{%n}.  If you store @code{-1} in that argument slot before calling
3891 @code{scanf}, the presence of @code{-1} after @code{scanf} indicates an
3892 error occurred before the @samp{%n} was reached.
3894 Finally, the @samp{%%} conversion matches a literal @samp{%} character
3895 in the input stream, without using an argument.  This conversion does
3896 not permit any flags, field width, or type modifier to be specified.
3898 @node Formatted Input Functions
3899 @subsection Formatted Input Functions
3901 Here are the descriptions of the functions for performing formatted
3902 input.
3903 Prototypes for these functions are in the header file @file{stdio.h}.
3904 @pindex stdio.h
3906 @deftypefun int scanf (const char *@var{template}, @dots{})
3907 @standards{ISO, stdio.h}
3908 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
3909 The @code{scanf} function reads formatted input from the stream
3910 @code{stdin} under the control of the template string @var{template}.
3911 The optional arguments are pointers to the places which receive the
3912 resulting values.
3914 The return value is normally the number of successful assignments.  If
3915 an end-of-file condition is detected before any matches are performed,
3916 including matches against whitespace and literal characters in the
3917 template, then @code{EOF} is returned.
3918 @end deftypefun
3920 @deftypefun int wscanf (const wchar_t *@var{template}, @dots{})
3921 @standards{ISO, wchar.h}
3922 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
3923 The @code{wscanf} function reads formatted input from the stream
3924 @code{stdin} under the control of the template string @var{template}.
3925 The optional arguments are pointers to the places which receive the
3926 resulting values.
3928 The return value is normally the number of successful assignments.  If
3929 an end-of-file condition is detected before any matches are performed,
3930 including matches against whitespace and literal characters in the
3931 template, then @code{WEOF} is returned.
3932 @end deftypefun
3934 @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
3935 @standards{ISO, stdio.h}
3936 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
3937 This function is just like @code{scanf}, except that the input is read
3938 from the stream @var{stream} instead of @code{stdin}.
3939 @end deftypefun
3941 @deftypefun int fwscanf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
3942 @standards{ISO, wchar.h}
3943 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
3944 This function is just like @code{wscanf}, except that the input is read
3945 from the stream @var{stream} instead of @code{stdin}.
3946 @end deftypefun
3948 @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
3949 @standards{ISO, stdio.h}
3950 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
3951 This is like @code{scanf}, except that the characters are taken from the
3952 null-terminated string @var{s} instead of from a stream.  Reaching the
3953 end of the string is treated as an end-of-file condition.
3955 The behavior of this function is undefined if copying takes place
3956 between objects that overlap---for example, if @var{s} is also given
3957 as an argument to receive a string read under control of the @samp{%s},
3958 @samp{%S}, or @samp{%[} conversion.
3959 @end deftypefun
3961 @deftypefun int swscanf (const wchar_t *@var{ws}, const wchar_t *@var{template}, @dots{})
3962 @standards{ISO, wchar.h}
3963 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
3964 This is like @code{wscanf}, except that the characters are taken from the
3965 null-terminated string @var{ws} instead of from a stream.  Reaching the
3966 end of the string is treated as an end-of-file condition.
3968 The behavior of this function is undefined if copying takes place
3969 between objects that overlap---for example, if @var{ws} is also given as
3970 an argument to receive a string read under control of the @samp{%s},
3971 @samp{%S}, or @samp{%[} conversion.
3972 @end deftypefun
3974 @node Variable Arguments Input
3975 @subsection Variable Arguments Input Functions
3977 The functions @code{vscanf} and friends are provided so that you can
3978 define your own variadic @code{scanf}-like functions that make use of
3979 the same internals as the built-in formatted output functions.
3980 These functions are analogous to the @code{vprintf} series of output
3981 functions.  @xref{Variable Arguments Output}, for important
3982 information on how to use them.
3984 @strong{Portability Note:} The functions listed in this section were
3985 introduced in @w{ISO C99} and were before available as GNU extensions.
3987 @deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
3988 @standards{ISO, stdio.h}
3989 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
3990 This function is similar to @code{scanf}, but instead of taking
3991 a variable number of arguments directly, it takes an argument list
3992 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
3993 @end deftypefun
3995 @deftypefun int vwscanf (const wchar_t *@var{template}, va_list @var{ap})
3996 @standards{ISO, wchar.h}
3997 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
3998 This function is similar to @code{wscanf}, but instead of taking
3999 a variable number of arguments directly, it takes an argument list
4000 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
4001 @end deftypefun
4003 @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
4004 @standards{ISO, stdio.h}
4005 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
4006 This is the equivalent of @code{fscanf} with the variable argument list
4007 specified directly as for @code{vscanf}.
4008 @end deftypefun
4010 @deftypefun int vfwscanf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
4011 @standards{ISO, wchar.h}
4012 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
4013 This is the equivalent of @code{fwscanf} with the variable argument list
4014 specified directly as for @code{vwscanf}.
4015 @end deftypefun
4017 @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
4018 @standards{ISO, stdio.h}
4019 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
4020 This is the equivalent of @code{sscanf} with the variable argument list
4021 specified directly as for @code{vscanf}.
4022 @end deftypefun
4024 @deftypefun int vswscanf (const wchar_t *@var{s}, const wchar_t *@var{template}, va_list @var{ap})
4025 @standards{ISO, wchar.h}
4026 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
4027 This is the equivalent of @code{swscanf} with the variable argument list
4028 specified directly as for @code{vwscanf}.
4029 @end deftypefun
4031 In GNU C, there is a special construct you can use to let the compiler
4032 know that a function uses a @code{scanf}-style format string.  Then it
4033 can check the number and types of arguments in each call to the
4034 function, and warn you when they do not match the format string.
4035 For details, see @ref{Function Attributes, , Declaring Attributes of Functions,
4036 gcc.info, Using GNU CC}.
4038 @node EOF and Errors
4039 @section End-Of-File and Errors
4041 @cindex end of file, on a stream
4042 Many of the functions described in this chapter return the value of the
4043 macro @code{EOF} to indicate unsuccessful completion of the operation.
4044 Since @code{EOF} is used to report both end of file and random errors,
4045 it's often better to use the @code{feof} function to check explicitly
4046 for end of file and @code{ferror} to check for errors.  These functions
4047 check indicators that are part of the internal state of the stream
4048 object, indicators set if the appropriate condition was detected by a
4049 previous I/O operation on that stream.
4051 @deftypevr Macro int EOF
4052 @standards{ISO, stdio.h}
4053 This macro is an integer value that is returned by a number of narrow
4054 stream functions to indicate an end-of-file condition, or some other
4055 error situation.  With @theglibc{}, @code{EOF} is @code{-1}.  In
4056 other libraries, its value may be some other negative number.
4058 This symbol is declared in @file{stdio.h}.
4059 @end deftypevr
4061 @deftypevr Macro int WEOF
4062 @standards{ISO, wchar.h}
4063 This macro is an integer value that is returned by a number of wide
4064 stream functions to indicate an end-of-file condition, or some other
4065 error situation.  With @theglibc{}, @code{WEOF} is @code{-1}.  In
4066 other libraries, its value may be some other negative number.
4068 This symbol is declared in @file{wchar.h}.
4069 @end deftypevr
4071 @deftypefun int feof (FILE *@var{stream})
4072 @standards{ISO, stdio.h}
4073 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
4074 The @code{feof} function returns nonzero if and only if the end-of-file
4075 indicator for the stream @var{stream} is set.
4077 This symbol is declared in @file{stdio.h}.
4078 @end deftypefun
4080 @deftypefun int feof_unlocked (FILE *@var{stream})
4081 @standards{GNU, stdio.h}
4082 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
4083 @c There isn't much of a thread unsafety risk in reading a flag word and
4084 @c testing a bit in it.
4085 The @code{feof_unlocked} function is equivalent to the @code{feof}
4086 function except that it does not implicitly lock the stream.
4088 This function is a GNU extension.
4090 This symbol is declared in @file{stdio.h}.
4091 @end deftypefun
4093 @deftypefun int ferror (FILE *@var{stream})
4094 @standards{ISO, stdio.h}
4095 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
4096 The @code{ferror} function returns nonzero if and only if the error
4097 indicator for the stream @var{stream} is set, indicating that an error
4098 has occurred on a previous operation on the stream.
4100 This symbol is declared in @file{stdio.h}.
4101 @end deftypefun
4103 @deftypefun int ferror_unlocked (FILE *@var{stream})
4104 @standards{GNU, stdio.h}
4105 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
4106 The @code{ferror_unlocked} function is equivalent to the @code{ferror}
4107 function except that it does not implicitly lock the stream.
4109 This function is a GNU extension.
4111 This symbol is declared in @file{stdio.h}.
4112 @end deftypefun
4114 In addition to setting the error indicator associated with the stream,
4115 the functions that operate on streams also set @code{errno} in the same
4116 way as the corresponding low-level functions that operate on file
4117 descriptors.  For example, all of the functions that perform output to a
4118 stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are
4119 implemented in terms of @code{write}, and all of the @code{errno} error
4120 conditions defined for @code{write} are meaningful for these functions.
4121 For more information about the descriptor-level I/O functions, see
4122 @ref{Low-Level I/O}.
4124 @node Error Recovery
4125 @section Recovering from errors
4127 You may explicitly clear the error and EOF flags with the @code{clearerr}
4128 function.
4130 @deftypefun void clearerr (FILE *@var{stream})
4131 @standards{ISO, stdio.h}
4132 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
4133 This function clears the end-of-file and error indicators for the
4134 stream @var{stream}.
4136 The file positioning functions (@pxref{File Positioning}) also clear the
4137 end-of-file indicator for the stream.
4138 @end deftypefun
4140 @deftypefun void clearerr_unlocked (FILE *@var{stream})
4141 @standards{GNU, stdio.h}
4142 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@assafe{}@acsafe{}}
4143 The @code{clearerr_unlocked} function is equivalent to the @code{clearerr}
4144 function except that it does not implicitly lock the stream.
4146 This function is a GNU extension.
4147 @end deftypefun
4149 Note that it is @emph{not} correct to just clear the error flag and retry
4150 a failed stream operation.  After a failed write, any number of
4151 characters since the last buffer flush may have been committed to the
4152 file, while some buffered data may have been discarded.  Merely retrying
4153 can thus cause lost or repeated data.
4155 A failed read may leave the file pointer in an inappropriate position for
4156 a second try.  In both cases, you should seek to a known position before
4157 retrying.
4159 Most errors that can happen are not recoverable --- a second try will
4160 always fail again in the same way.  So usually it is best to give up and
4161 report the error to the user, rather than install complicated recovery
4162 logic.
4164 One important exception is @code{EINTR} (@pxref{Interrupted Primitives}).
4165 Many stream I/O implementations will treat it as an ordinary error, which
4166 can be quite inconvenient.  You can avoid this hassle by installing all
4167 signals with the @code{SA_RESTART} flag.
4169 For similar reasons, setting nonblocking I/O on a stream's file
4170 descriptor is not usually advisable.
4172 @node Binary Streams
4173 @section Text and Binary Streams
4175 @gnusystems{} and other POSIX-compatible operating systems organize all
4176 files as uniform sequences of characters.  However, some other systems
4177 make a distinction between files containing text and files containing
4178 binary data, and the input and output facilities of @w{ISO C} provide for
4179 this distinction.  This section tells you how to write programs portable
4180 to such systems.
4182 @cindex text stream
4183 @cindex binary stream
4184 When you open a stream, you can specify either a @dfn{text stream} or a
4185 @dfn{binary stream}.  You indicate that you want a binary stream by
4186 specifying the @samp{b} modifier in the @var{opentype} argument to
4187 @code{fopen}; see @ref{Opening Streams}.  Without this
4188 option, @code{fopen} opens the file as a text stream.
4190 Text and binary streams differ in several ways:
4192 @itemize @bullet
4193 @item
4194 The data read from a text stream is divided into @dfn{lines} which are
4195 terminated by newline (@code{'\n'}) characters, while a binary stream is
4196 simply a long series of characters.  A text stream might on some systems
4197 fail to handle lines more than 254 characters long (including the
4198 terminating newline character).
4199 @cindex lines (in a text file)
4201 @item
4202 On some systems, text files can contain only printing characters,
4203 horizontal tab characters, and newlines, and so text streams may not
4204 support other characters.  However, binary streams can handle any
4205 character value.
4207 @item
4208 Space characters that are written immediately preceding a newline
4209 character in a text stream may disappear when the file is read in again.
4211 @item
4212 More generally, there need not be a one-to-one mapping between
4213 characters that are read from or written to a text stream, and the
4214 characters in the actual file.
4215 @end itemize
4217 Since a binary stream is always more capable and more predictable than a
4218 text stream, you might wonder what purpose text streams serve.  Why not
4219 simply always use binary streams?  The answer is that on these operating
4220 systems, text and binary streams use different file formats, and the
4221 only way to read or write ``an ordinary file of text'' that can work
4222 with other text-oriented programs is through a text stream.
4224 In @theglibc{}, and on all POSIX systems, there is no difference
4225 between text streams and binary streams.  When you open a stream, you
4226 get the same kind of stream regardless of whether you ask for binary.
4227 This stream can handle any file content, and has none of the
4228 restrictions that text streams sometimes have.
4230 @node File Positioning
4231 @section File Positioning
4232 @cindex file positioning on a stream
4233 @cindex positioning a stream
4234 @cindex seeking on a stream
4236 The @dfn{file position} of a stream describes where in the file the
4237 stream is currently reading or writing.  I/O on the stream advances the
4238 file position through the file.  On @gnusystems{}, the file position is
4239 represented as an integer, which counts the number of bytes from the
4240 beginning of the file.  @xref{File Position}.
4242 During I/O to an ordinary disk file, you can change the file position
4243 whenever you wish, so as to read or write any portion of the file.  Some
4244 other kinds of files may also permit this.  Files which support changing
4245 the file position are sometimes referred to as @dfn{random-access}
4246 files.
4248 You can use the functions in this section to examine or modify the file
4249 position indicator associated with a stream.  The symbols listed below
4250 are declared in the header file @file{stdio.h}.
4251 @pindex stdio.h
4253 @deftypefun {long int} ftell (FILE *@var{stream})
4254 @standards{ISO, stdio.h}
4255 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4256 This function returns the current file position of the stream
4257 @var{stream}.
4259 This function can fail if the stream doesn't support file positioning,
4260 or if the file position can't be represented in a @code{long int}, and
4261 possibly for other reasons as well.  If a failure occurs, a value of
4262 @code{-1} is returned.
4263 @end deftypefun
4265 @deftypefun off_t ftello (FILE *@var{stream})
4266 @standards{Unix98, stdio.h}
4267 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4268 The @code{ftello} function is similar to @code{ftell}, except that it
4269 returns a value of type @code{off_t}.  Systems which support this type
4270 use it to describe all file positions, unlike the POSIX specification
4271 which uses a long int.  The two are not necessarily the same size.
4272 Therefore, using ftell can lead to problems if the implementation is
4273 written on top of a POSIX compliant low-level I/O implementation, and using
4274 @code{ftello} is preferable whenever it is available.
4276 If this function fails it returns @code{(off_t) -1}.  This can happen due
4277 to missing support for file positioning or internal errors.  Otherwise
4278 the return value is the current file position.
4280 The function is an extension defined in the Unix Single Specification
4281 version 2.
4283 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4284 32 bit system this function is in fact @code{ftello64}.  I.e., the
4285 LFS interface transparently replaces the old interface.
4286 @end deftypefun
4288 @deftypefun off64_t ftello64 (FILE *@var{stream})
4289 @standards{Unix98, stdio.h}
4290 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4291 This function is similar to @code{ftello} with the only difference that
4292 the return value is of type @code{off64_t}.  This also requires that the
4293 stream @var{stream} was opened using either @code{fopen64},
4294 @code{freopen64}, or @code{tmpfile64} since otherwise the underlying
4295 file operations to position the file pointer beyond the @twoexp{31}
4296 bytes limit might fail.
4298 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4299 bits machine this function is available under the name @code{ftello}
4300 and so transparently replaces the old interface.
4301 @end deftypefun
4303 @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
4304 @standards{ISO, stdio.h}
4305 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4306 The @code{fseek} function is used to change the file position of the
4307 stream @var{stream}.  The value of @var{whence} must be one of the
4308 constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
4309 indicate whether the @var{offset} is relative to the beginning of the
4310 file, the current file position, or the end of the file, respectively.
4312 This function returns a value of zero if the operation was successful,
4313 and a nonzero value to indicate failure.  A successful call also clears
4314 the end-of-file indicator of @var{stream} and discards any characters
4315 that were ``pushed back'' by the use of @code{ungetc}.
4317 @code{fseek} either flushes any buffered output before setting the file
4318 position or else remembers it so it will be written later in its proper
4319 place in the file.
4320 @end deftypefun
4322 @deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence})
4323 @standards{Unix98, stdio.h}
4324 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4325 This function is similar to @code{fseek} but it corrects a problem with
4326 @code{fseek} in a system with POSIX types.  Using a value of type
4327 @code{long int} for the offset is not compatible with POSIX.
4328 @code{fseeko} uses the correct type @code{off_t} for the @var{offset}
4329 parameter.
4331 For this reason it is a good idea to prefer @code{ftello} whenever it is
4332 available since its functionality is (if different at all) closer the
4333 underlying definition.
4335 The functionality and return value are the same as for @code{fseek}.
4337 The function is an extension defined in the Unix Single Specification
4338 version 2.
4340 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4341 32 bit system this function is in fact @code{fseeko64}.  I.e., the
4342 LFS interface transparently replaces the old interface.
4343 @end deftypefun
4345 @deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence})
4346 @standards{Unix98, stdio.h}
4347 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4348 This function is similar to @code{fseeko} with the only difference that
4349 the @var{offset} parameter is of type @code{off64_t}.  This also
4350 requires that the stream @var{stream} was opened using either
4351 @code{fopen64}, @code{freopen64}, or @code{tmpfile64} since otherwise
4352 the underlying file operations to position the file pointer beyond the
4353 @twoexp{31} 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{fseeko}
4357 and so transparently replaces the old interface.
4358 @end deftypefun
4360 @strong{Portability Note:} In non-POSIX systems, @code{ftell},
4361 @code{ftello}, @code{fseek} and @code{fseeko} might work reliably only
4362 on binary streams.  @xref{Binary Streams}.
4364 The following symbolic constants are defined for use as the @var{whence}
4365 argument to @code{fseek}.  They are also used with the @code{lseek}
4366 function (@pxref{I/O Primitives}) and to specify offsets for file locks
4367 (@pxref{Control Operations}).
4369 @deftypevr Macro int SEEK_SET
4370 @standards{ISO, stdio.h}
4371 This is an integer constant which, when used as the @var{whence}
4372 argument to the @code{fseek} or @code{fseeko} functions, specifies that
4373 the offset provided is relative to the beginning of the file.
4374 @end deftypevr
4376 @deftypevr Macro int SEEK_CUR
4377 @standards{ISO, stdio.h}
4378 This is an integer constant which, when used as the @var{whence}
4379 argument to the @code{fseek} or @code{fseeko} functions, specifies that
4380 the offset provided is relative to the current file position.
4381 @end deftypevr
4383 @deftypevr Macro int SEEK_END
4384 @standards{ISO, stdio.h}
4385 This is an integer constant which, when used as the @var{whence}
4386 argument to the @code{fseek} or @code{fseeko} functions, specifies that
4387 the offset provided is relative to the end of the file.
4388 @end deftypevr
4390 @deftypefun void rewind (FILE *@var{stream})
4391 @standards{ISO, stdio.h}
4392 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4393 The @code{rewind} function positions the stream @var{stream} at the
4394 beginning of the file.  It is equivalent to calling @code{fseek} or
4395 @code{fseeko} on the @var{stream} with an @var{offset} argument of
4396 @code{0L} and a @var{whence} argument of @code{SEEK_SET}, except that
4397 the return value is discarded and the error indicator for the stream is
4398 reset.
4399 @end deftypefun
4401 These three aliases for the @samp{SEEK_@dots{}} constants exist for the
4402 sake of compatibility with older BSD systems.  They are defined in two
4403 different header files: @file{fcntl.h} and @file{sys/file.h}.
4405 @vtable @code
4406 @item L_SET
4407 @standards{BSD, sys/file.h}
4408 An alias for @code{SEEK_SET}.
4410 @item L_INCR
4411 @standards{BSD, sys/file.h}
4412 An alias for @code{SEEK_CUR}.
4414 @item L_XTND
4415 @standards{BSD, sys/file.h}
4416 An alias for @code{SEEK_END}.
4417 @end vtable
4419 @node Portable Positioning
4420 @section Portable File-Position Functions
4422 On @gnusystems{}, the file position is truly a character count.  You
4423 can specify any character count value as an argument to @code{fseek} or
4424 @code{fseeko} and get reliable results for any random access file.
4425 However, some @w{ISO C} systems do not represent file positions in this
4426 way.
4428 On some systems where text streams truly differ from binary streams, it
4429 is impossible to represent the file position of a text stream as a count
4430 of characters from the beginning of the file.  For example, the file
4431 position on some systems must encode both a record offset within the
4432 file, and a character offset within the record.
4434 As a consequence, if you want your programs to be portable to these
4435 systems, you must observe certain rules:
4437 @itemize @bullet
4438 @item
4439 The value returned from @code{ftell} on a text stream has no predictable
4440 relationship to the number of characters you have read so far.  The only
4441 thing you can rely on is that you can use it subsequently as the
4442 @var{offset} argument to @code{fseek} or @code{fseeko} to move back to
4443 the same file position.
4445 @item
4446 In a call to @code{fseek} or @code{fseeko} on a text stream, either the
4447 @var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and
4448 the @var{offset} must be the result of an earlier call to @code{ftell}
4449 on the same stream.
4451 @item
4452 The value of the file position indicator of a text stream is undefined
4453 while there are characters that have been pushed back with @code{ungetc}
4454 that haven't been read or discarded.  @xref{Unreading}.
4455 @end itemize
4457 But even if you observe these rules, you may still have trouble for long
4458 files, because @code{ftell} and @code{fseek} use a @code{long int} value
4459 to represent the file position.  This type may not have room to encode
4460 all the file positions in a large file.  Using the @code{ftello} and
4461 @code{fseeko} functions might help here since the @code{off_t} type is
4462 expected to be able to hold all file position values but this still does
4463 not help to handle additional information which must be associated with
4464 a file position.
4466 So if you do want to support systems with peculiar encodings for the
4467 file positions, it is better to use the functions @code{fgetpos} and
4468 @code{fsetpos} instead.  These functions represent the file position
4469 using the data type @code{fpos_t}, whose internal representation varies
4470 from system to system.
4472 These symbols are declared in the header file @file{stdio.h}.
4473 @pindex stdio.h
4475 @deftp {Data Type} fpos_t
4476 @standards{ISO, stdio.h}
4477 This is the type of an object that can encode information about the
4478 file position of a stream, for use by the functions @code{fgetpos} and
4479 @code{fsetpos}.
4481 In @theglibc{}, @code{fpos_t} is an opaque data structure that
4482 contains internal data to represent file offset and conversion state
4483 information.  In other systems, it might have a different internal
4484 representation.
4486 When compiling with @code{_FILE_OFFSET_BITS == 64} on a 32 bit machine
4487 this type is in fact equivalent to @code{fpos64_t} since the LFS
4488 interface transparently replaces the old interface.
4489 @end deftp
4491 @deftp {Data Type} fpos64_t
4492 @standards{Unix98, stdio.h}
4493 This is the type of an object that can encode information about the
4494 file position of a stream, for use by the functions @code{fgetpos64} and
4495 @code{fsetpos64}.
4497 In @theglibc{}, @code{fpos64_t} is an opaque data structure that
4498 contains internal data to represent file offset and conversion state
4499 information.  In other systems, it might have a different internal
4500 representation.
4501 @end deftp
4503 @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
4504 @standards{ISO, stdio.h}
4505 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4506 This function stores the value of the file position indicator for the
4507 stream @var{stream} in the @code{fpos_t} object pointed to by
4508 @var{position}.  If successful, @code{fgetpos} returns zero; otherwise
4509 it returns a nonzero value and stores an implementation-defined positive
4510 value in @code{errno}.
4512 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4513 32 bit system the function is in fact @code{fgetpos64}.  I.e., the LFS
4514 interface transparently replaces the old interface.
4515 @end deftypefun
4517 @deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position})
4518 @standards{Unix98, stdio.h}
4519 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4520 This function is similar to @code{fgetpos} but the file position is
4521 returned in a variable of type @code{fpos64_t} to which @var{position}
4522 points.
4524 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4525 bits machine this function is available under the name @code{fgetpos}
4526 and so transparently replaces the old interface.
4527 @end deftypefun
4529 @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position})
4530 @standards{ISO, stdio.h}
4531 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4532 This function sets the file position indicator for the stream @var{stream}
4533 to the position @var{position}, which must have been set by a previous
4534 call to @code{fgetpos} on the same stream.  If successful, @code{fsetpos}
4535 clears the end-of-file indicator on the stream, discards any characters
4536 that were ``pushed back'' by the use of @code{ungetc}, and returns a value
4537 of zero.  Otherwise, @code{fsetpos} returns a nonzero value and stores
4538 an implementation-defined positive value in @code{errno}.
4540 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4541 32 bit system the function is in fact @code{fsetpos64}.  I.e., the LFS
4542 interface transparently replaces the old interface.
4543 @end deftypefun
4545 @deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position})
4546 @standards{Unix98, stdio.h}
4547 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4548 This function is similar to @code{fsetpos} but the file position used
4549 for positioning is provided in a variable of type @code{fpos64_t} to
4550 which @var{position} points.
4552 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4553 bits machine this function is available under the name @code{fsetpos}
4554 and so transparently replaces the old interface.
4555 @end deftypefun
4557 @node Stream Buffering
4558 @section Stream Buffering
4560 @cindex buffering of streams
4561 Characters that are written to a stream are normally accumulated and
4562 transmitted asynchronously to the file in a block, instead of appearing
4563 as soon as they are output by the application program.  Similarly,
4564 streams often retrieve input from the host environment in blocks rather
4565 than on a character-by-character basis.  This is called @dfn{buffering}.
4567 If you are writing programs that do interactive input and output using
4568 streams, you need to understand how buffering works when you design the
4569 user interface to your program.  Otherwise, you might find that output
4570 (such as progress or prompt messages) doesn't appear when you intended
4571 it to, or displays some other unexpected behavior.
4573 This section deals only with controlling when characters are transmitted
4574 between the stream and the file or device, and @emph{not} with how
4575 things like echoing, flow control, and the like are handled on specific
4576 classes of devices.  For information on common control operations on
4577 terminal devices, see @ref{Low-Level Terminal Interface}.
4579 You can bypass the stream buffering facilities altogether by using the
4580 low-level input and output functions that operate on file descriptors
4581 instead.  @xref{Low-Level I/O}.
4583 @menu
4584 * Buffering Concepts::          Terminology is defined here.
4585 * Flushing Buffers::            How to ensure that output buffers are flushed.
4586 * Controlling Buffering::       How to specify what kind of buffering to use.
4587 @end menu
4589 @node Buffering Concepts
4590 @subsection Buffering Concepts
4592 There are three different kinds of buffering strategies:
4594 @itemize @bullet
4595 @item
4596 Characters written to or read from an @dfn{unbuffered} stream are
4597 transmitted individually to or from the file as soon as possible.
4598 @cindex unbuffered stream
4600 @item
4601 Characters written to a @dfn{line buffered} stream are transmitted to
4602 the file in blocks when a newline character is encountered.
4603 @cindex line buffered stream
4605 @item
4606 Characters written to or read from a @dfn{fully buffered} stream are
4607 transmitted to or from the file in blocks of arbitrary size.
4608 @cindex fully buffered stream
4609 @end itemize
4611 Newly opened streams are normally fully buffered, with one exception: a
4612 stream connected to an interactive device such as a terminal is
4613 initially line buffered.  @xref{Controlling Buffering}, for information
4614 on how to select a different kind of buffering.  Usually the automatic
4615 selection gives you the most convenient kind of buffering for the file
4616 or device you open.
4618 The use of line buffering for interactive devices implies that output
4619 messages ending in a newline will appear immediately---which is usually
4620 what you want.  Output that doesn't end in a newline might or might not
4621 show up immediately, so if you want them to appear immediately, you
4622 should flush buffered output explicitly with @code{fflush}, as described
4623 in @ref{Flushing Buffers}.
4625 @node Flushing Buffers
4626 @subsection Flushing Buffers
4628 @cindex flushing a stream
4629 @dfn{Flushing} output on a buffered stream means transmitting all
4630 accumulated characters to the file.  There are many circumstances when
4631 buffered output on a stream is flushed automatically:
4633 @itemize @bullet
4634 @item
4635 When you try to do output and the output buffer is full.
4637 @item
4638 When the stream is closed.  @xref{Closing Streams}.
4640 @item
4641 When the program terminates by calling @code{exit}.
4642 @xref{Normal Termination}.
4644 @item
4645 When a newline is written, if the stream is line buffered.
4647 @item
4648 Whenever an input operation on @emph{any} stream actually reads data
4649 from its file.
4650 @end itemize
4652 If you want to flush the buffered output at another time, call
4653 @code{fflush}, which is declared in the header file @file{stdio.h}.
4654 @pindex stdio.h
4656 @deftypefun int fflush (FILE *@var{stream})
4657 @standards{ISO, stdio.h}
4658 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4659 This function causes any buffered output on @var{stream} to be delivered
4660 to the file.  If @var{stream} is a null pointer, then
4661 @code{fflush} causes buffered output on @emph{all} open output streams
4662 to be flushed.
4664 This function returns @code{EOF} if a write error occurs, or zero
4665 otherwise.
4666 @end deftypefun
4668 @deftypefun int fflush_unlocked (FILE *@var{stream})
4669 @standards{POSIX, stdio.h}
4670 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
4671 The @code{fflush_unlocked} function is equivalent to the @code{fflush}
4672 function except that it does not implicitly lock the stream.
4673 @end deftypefun
4675 The @code{fflush} function can be used to flush all streams currently
4676 opened.  While this is useful in some situations it does often more than
4677 necessary since it might be done in situations when terminal input is
4678 required and the program wants to be sure that all output is visible on
4679 the terminal.  But this means that only line buffered streams have to be
4680 flushed.  Solaris introduced a function especially for this.  It was
4681 always available in @theglibc{} in some form but never officially
4682 exported.
4684 @deftypefun void _flushlbf (void)
4685 @standards{GNU, stdio_ext.h}
4686 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4687 The @code{_flushlbf} function flushes all line buffered streams
4688 currently opened.
4690 This function is declared in the @file{stdio_ext.h} header.
4691 @end deftypefun
4693 @strong{Compatibility Note:} Some brain-damaged operating systems have
4694 been known to be so thoroughly fixated on line-oriented input and output
4695 that flushing a line buffered stream causes a newline to be written!
4696 Fortunately, this ``feature'' seems to be becoming less common.  You do
4697 not need to worry about this with @theglibc{}.
4699 In some situations it might be useful to not flush the output pending
4700 for a stream but instead simply forget it.  If transmission is costly
4701 and the output is not needed anymore this is valid reasoning.  In this
4702 situation a non-standard function introduced in Solaris and available in
4703 @theglibc{} can be used.
4705 @deftypefun void __fpurge (FILE *@var{stream})
4706 @standards{GNU, stdio_ext.h}
4707 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
4708 The @code{__fpurge} function causes the buffer of the stream
4709 @var{stream} to be emptied.  If the stream is currently in read mode all
4710 input in the buffer is lost.  If the stream is in output mode the
4711 buffered output is not written to the device (or whatever other
4712 underlying storage) and the buffer is cleared.
4714 This function is declared in @file{stdio_ext.h}.
4715 @end deftypefun
4717 @node Controlling Buffering
4718 @subsection Controlling Which Kind of Buffering
4720 After opening a stream (but before any other operations have been
4721 performed on it), you can explicitly specify what kind of buffering you
4722 want it to have using the @code{setvbuf} function.
4723 @cindex buffering, controlling
4725 The facilities listed in this section are declared in the header
4726 file @file{stdio.h}.
4727 @pindex stdio.h
4729 @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
4730 @standards{ISO, stdio.h}
4731 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4732 This function is used to specify that the stream @var{stream} should
4733 have the buffering mode @var{mode}, which can be either @code{_IOFBF}
4734 (for full buffering), @code{_IOLBF} (for line buffering), or
4735 @code{_IONBF} (for unbuffered input/output).
4737 If you specify a null pointer as the @var{buf} argument, then @code{setvbuf}
4738 allocates a buffer itself using @code{malloc}.  This buffer will be freed
4739 when you close the stream.
4741 Otherwise, @var{buf} should be a character array that can hold at least
4742 @var{size} characters.  You should not free the space for this array as
4743 long as the stream remains open and this array remains its buffer.  You
4744 should usually either allocate it statically, or @code{malloc}
4745 (@pxref{Unconstrained Allocation}) the buffer.  Using an automatic array
4746 is not a good idea unless you close the file before exiting the block
4747 that declares the array.
4749 While the array remains a stream buffer, the stream I/O functions will
4750 use the buffer for their internal purposes.  You shouldn't try to access
4751 the values in the array directly while the stream is using it for
4752 buffering.
4754 The @code{setvbuf} function returns zero on success, or a nonzero value
4755 if the value of @var{mode} is not valid or if the request could not
4756 be honored.
4757 @end deftypefun
4759 @deftypevr Macro int _IOFBF
4760 @standards{ISO, stdio.h}
4761 The value of this macro is an integer constant expression that can be
4762 used as the @var{mode} argument to the @code{setvbuf} function to
4763 specify that the stream should be fully buffered.
4764 @end deftypevr
4766 @deftypevr Macro int _IOLBF
4767 @standards{ISO, stdio.h}
4768 The value of this macro is an integer constant expression that can be
4769 used as the @var{mode} argument to the @code{setvbuf} function to
4770 specify that the stream should be line buffered.
4771 @end deftypevr
4773 @deftypevr Macro int _IONBF
4774 @standards{ISO, stdio.h}
4775 The value of this macro is an integer constant expression that can be
4776 used as the @var{mode} argument to the @code{setvbuf} function to
4777 specify that the stream should be unbuffered.
4778 @end deftypevr
4780 @deftypevr Macro int BUFSIZ
4781 @standards{ISO, stdio.h}
4782 The value of this macro is an integer constant expression that is good
4783 to use for the @var{size} argument to @code{setvbuf}.  This value is
4784 guaranteed to be at least @code{256}.
4786 The value of @code{BUFSIZ} is chosen on each system so as to make stream
4787 I/O efficient.  So it is a good idea to use @code{BUFSIZ} as the size
4788 for the buffer when you call @code{setvbuf}.
4790 Actually, you can get an even better value to use for the buffer size
4791 by means of the @code{fstat} system call: it is found in the
4792 @code{st_blksize} field of the file attributes.  @xref{Attribute Meanings}.
4794 Sometimes people also use @code{BUFSIZ} as the allocation size of
4795 buffers used for related purposes, such as strings used to receive a
4796 line of input with @code{fgets} (@pxref{Character Input}).  There is no
4797 particular reason to use @code{BUFSIZ} for this instead of any other
4798 integer, except that it might lead to doing I/O in chunks of an
4799 efficient size.
4800 @end deftypevr
4802 @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
4803 @standards{ISO, stdio.h}
4804 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4805 If @var{buf} is a null pointer, the effect of this function is
4806 equivalent to calling @code{setvbuf} with a @var{mode} argument of
4807 @code{_IONBF}.  Otherwise, it is equivalent to calling @code{setvbuf}
4808 with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size}
4809 argument of @code{BUFSIZ}.
4811 The @code{setbuf} function is provided for compatibility with old code;
4812 use @code{setvbuf} in all new programs.
4813 @end deftypefun
4815 @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
4816 @standards{BSD, stdio.h}
4817 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4818 If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
4819 Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
4820 buffer.  The @var{size} argument specifies the length of @var{buf}.
4822 This function is provided for compatibility with old BSD code.  Use
4823 @code{setvbuf} instead.
4824 @end deftypefun
4826 @deftypefun void setlinebuf (FILE *@var{stream})
4827 @standards{BSD, stdio.h}
4828 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
4829 This function makes @var{stream} be line buffered, and allocates the
4830 buffer for you.
4832 This function is provided for compatibility with old BSD code.  Use
4833 @code{setvbuf} instead.
4834 @end deftypefun
4836 It is possible to query whether a given stream is line buffered or not
4837 using a non-standard function introduced in Solaris and available in
4838 @theglibc{}.
4840 @deftypefun int __flbf (FILE *@var{stream})
4841 @standards{GNU, stdio_ext.h}
4842 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
4843 The @code{__flbf} function will return a nonzero value in case the
4844 stream @var{stream} is line buffered.  Otherwise the return value is
4845 zero.
4847 This function is declared in the @file{stdio_ext.h} header.
4848 @end deftypefun
4850 Two more extensions allow to determine the size of the buffer and how
4851 much of it is used.  These functions were also introduced in Solaris.
4853 @deftypefun size_t __fbufsize (FILE *@var{stream})
4854 @standards{GNU, stdio_ext.h}
4855 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}}
4856 The @code{__fbufsize} function return the size of the buffer in the
4857 stream @var{stream}.  This value can be used to optimize the use of the
4858 stream.
4860 This function is declared in the @file{stdio_ext.h} header.
4861 @end deftypefun
4863 @deftypefun size_t __fpending (FILE *@var{stream})
4864 @standards{GNU, stdio_ext.h}
4865 @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}}
4866 The @code{__fpending}
4867 function returns the number of bytes currently in the output buffer.
4868 For wide-oriented streams the measuring unit is wide characters.  This
4869 function should not be used on buffers in read mode or opened read-only.
4871 This function is declared in the @file{stdio_ext.h} header.
4872 @end deftypefun
4874 @node Other Kinds of Streams
4875 @section Other Kinds of Streams
4877 @Theglibc{} provides ways for you to define additional kinds of
4878 streams that do not necessarily correspond to an open file.
4880 One such type of stream takes input from or writes output to a string.
4881 These kinds of streams are used internally to implement the
4882 @code{sprintf} and @code{sscanf} functions.  You can also create such a
4883 stream explicitly, using the functions described in @ref{String Streams}.
4885 More generally, you can define streams that do input/output to arbitrary
4886 objects using functions supplied by your program.  This protocol is
4887 discussed in @ref{Custom Streams}.
4889 @strong{Portability Note:} The facilities described in this section are
4890 specific to GNU.  Other systems or C implementations might or might not
4891 provide equivalent functionality.
4893 @menu
4894 * String Streams::              Streams that get data from or put data in
4895                                  a string or memory buffer.
4896 * Custom Streams::              Defining your own streams with an arbitrary
4897                                  input data source and/or output data sink.
4898 @end menu
4900 @node String Streams
4901 @subsection String Streams
4903 @cindex stream, for I/O to a string
4904 @cindex string stream
4905 The @code{fmemopen} and @code{open_memstream} functions allow you to do
4906 I/O to a string or memory buffer.  These facilities are declared in
4907 @file{stdio.h}.
4908 @pindex stdio.h
4910 @deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
4911 @standards{GNU, stdio.h}
4912 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
4913 @c Unlike open_memstream, fmemopen does (indirectly) call _IO_link_in,
4914 @c bringing with it additional potential for async trouble with
4915 @c list_all_lock.
4916 This function opens a stream that allows the access specified by the
4917 @var{opentype} argument, that reads from or writes to the buffer specified
4918 by the argument @var{buf}.  This array must be at least @var{size} bytes long.
4920 If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
4921 dynamically allocates an array @var{size} bytes long (as with @code{malloc};
4922 @pxref{Unconstrained Allocation}).  This is really only useful
4923 if you are going to write things to the buffer and then read them back
4924 in again, because you have no way of actually getting a pointer to the
4925 buffer (for this, try @code{open_memstream}, below).  The buffer is
4926 freed when the stream is closed.
4928 The argument @var{opentype} is the same as in @code{fopen}
4929 (@pxref{Opening Streams}).  If the @var{opentype} specifies
4930 append mode, then the initial file position is set to the first null
4931 character in the buffer.  Otherwise the initial file position is at the
4932 beginning of the buffer.
4934 When a stream open for writing is flushed or closed, a null character
4935 (zero byte) is written at the end of the buffer if it fits.  You
4936 should add an extra byte to the @var{size} argument to account for this.
4937 Attempts to write more than @var{size} bytes to the buffer result
4938 in an error.
4940 For a stream open for reading, null characters (zero bytes) in the
4941 buffer do not count as ``end of file''.  Read operations indicate end of
4942 file only when the file position advances past @var{size} bytes.  So, if
4943 you want to read characters from a null-terminated string, you should
4944 supply the length of the string as the @var{size} argument.
4945 @end deftypefun
4947 Here is an example of using @code{fmemopen} to create a stream for
4948 reading from a string:
4950 @smallexample
4951 @include memopen.c.texi
4952 @end smallexample
4954 This program produces the following output:
4956 @smallexample
4957 Got f
4958 Got o
4959 Got o
4960 Got b
4961 Got a
4962 Got r
4963 @end smallexample
4965 @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
4966 @standards{GNU, stdio.h}
4967 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
4968 This function opens a stream for writing to a buffer.  The buffer is
4969 allocated dynamically and grown as necessary, using @code{malloc}.
4970 After you've closed the stream, this buffer is your responsibility to
4971 clean up using @code{free} or @code{realloc}.  @xref{Unconstrained Allocation}.
4973 When the stream is closed with @code{fclose} or flushed with
4974 @code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
4975 contain the pointer to the buffer and its size.  The values thus stored
4976 remain valid only as long as no further output on the stream takes
4977 place.  If you do more output, you must flush the stream again to store
4978 new values before you use them again.
4980 A null character is written at the end of the buffer.  This null character
4981 is @emph{not} included in the size value stored at @var{sizeloc}.
4983 You can move the stream's file position with @code{fseek} or
4984 @code{fseeko} (@pxref{File Positioning}).  Moving the file position past
4985 the end of the data already written fills the intervening space with
4986 zeroes.
4987 @end deftypefun
4989 Here is an example of using @code{open_memstream}:
4991 @smallexample
4992 @include memstrm.c.texi
4993 @end smallexample
4995 This program produces the following output:
4997 @smallexample
4998 buf = `hello', size = 5
4999 buf = `hello, world', size = 12
5000 @end smallexample
5002 @node Custom Streams
5003 @subsection Programming Your Own Custom Streams
5004 @cindex custom streams
5005 @cindex programming your own streams
5007 This section describes how you can make a stream that gets input from an
5008 arbitrary data source or writes output to an arbitrary data sink
5009 programmed by you.  We call these @dfn{custom streams}.  The functions
5010 and types described here are all GNU extensions.
5012 @c !!! this does not talk at all about the higher-level hooks
5014 @menu
5015 * Streams and Cookies::         The @dfn{cookie} records where to fetch or
5016                                  store data that is read or written.
5017 * Hook Functions::              How you should define the four @dfn{hook
5018                                  functions} that a custom stream needs.
5019 @end menu
5021 @node Streams and Cookies
5022 @subsubsection Custom Streams and Cookies
5023 @cindex cookie, for custom stream
5025 Inside every custom stream is a special object called the @dfn{cookie}.
5026 This is an object supplied by you which records where to fetch or store
5027 the data read or written.  It is up to you to define a data type to use
5028 for the cookie.  The stream functions in the library never refer
5029 directly to its contents, and they don't even know what the type is;
5030 they record its address with type @code{void *}.
5032 To implement a custom stream, you must specify @emph{how} to fetch or
5033 store the data in the specified place.  You do this by defining
5034 @dfn{hook functions} to read, write, change ``file position'', and close
5035 the stream.  All four of these functions will be passed the stream's
5036 cookie so they can tell where to fetch or store the data.  The library
5037 functions don't know what's inside the cookie, but your functions will
5038 know.
5040 When you create a custom stream, you must specify the cookie pointer,
5041 and also the four hook functions stored in a structure of type
5042 @code{cookie_io_functions_t}.
5044 These facilities are declared in @file{stdio.h}.
5045 @pindex stdio.h
5047 @deftp {Data Type} {cookie_io_functions_t}
5048 @standards{GNU, stdio.h}
5049 This is a structure type that holds the functions that define the
5050 communications protocol between the stream and its cookie.  It has
5051 the following members:
5053 @table @code
5054 @item cookie_read_function_t *read
5055 This is the function that reads data from the cookie.  If the value is a
5056 null pointer instead of a function, then read operations on this stream
5057 always return @code{EOF}.
5059 @item cookie_write_function_t *write
5060 This is the function that writes data to the cookie.  If the value is a
5061 null pointer instead of a function, then data written to the stream is
5062 discarded.
5064 @item cookie_seek_function_t *seek
5065 This is the function that performs the equivalent of file positioning on
5066 the cookie.  If the value is a null pointer instead of a function, calls
5067 to @code{fseek} or @code{fseeko} on this stream can only seek to
5068 locations within the buffer; any attempt to seek outside the buffer will
5069 return an @code{ESPIPE} error.
5071 @item cookie_close_function_t *close
5072 This function performs any appropriate cleanup on the cookie when
5073 closing the stream.  If the value is a null pointer instead of a
5074 function, nothing special is done to close the cookie when the stream is
5075 closed.
5076 @end table
5077 @end deftp
5079 @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions})
5080 @standards{GNU, stdio.h}
5081 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
5082 This function actually creates the stream for communicating with the
5083 @var{cookie} using the functions in the @var{io-functions} argument.
5084 The @var{opentype} argument is interpreted as for @code{fopen};
5085 see @ref{Opening Streams}.  (But note that the ``truncate on
5086 open'' option is ignored.)  The new stream is fully buffered.
5088 The @code{fopencookie} function returns the newly created stream, or a null
5089 pointer in case of an error.
5090 @end deftypefun
5092 @node Hook Functions
5093 @subsubsection Custom Stream Hook Functions
5094 @cindex hook functions (of custom streams)
5096 Here are more details on how you should define the four hook functions
5097 that a custom stream needs.
5099 You should define the function to read data from the cookie as:
5101 @smallexample
5102 ssize_t @var{reader} (void *@var{cookie}, char *@var{buffer}, size_t @var{size})
5103 @end smallexample
5105 This is very similar to the @code{read} function; see @ref{I/O
5106 Primitives}.  Your function should transfer up to @var{size} bytes into
5107 the @var{buffer}, and return the number of bytes read, or zero to
5108 indicate end-of-file.  You can return a value of @code{-1} to indicate
5109 an error.
5111 You should define the function to write data to the cookie as:
5113 @smallexample
5114 ssize_t @var{writer} (void *@var{cookie}, const char *@var{buffer}, size_t @var{size})
5115 @end smallexample
5117 This is very similar to the @code{write} function; see @ref{I/O
5118 Primitives}.  Your function should transfer up to @var{size} bytes from
5119 the buffer, and return the number of bytes written.  You can return a
5120 value of @code{0} to indicate an error.  You must not return any
5121 negative value.
5123 You should define the function to perform seek operations on the cookie
5126 @smallexample
5127 int @var{seeker} (void *@var{cookie}, off64_t *@var{position}, int @var{whence})
5128 @end smallexample
5130 For this function, the @var{position} and @var{whence} arguments are
5131 interpreted as for @code{fgetpos}; see @ref{Portable Positioning}.
5133 After doing the seek operation, your function should store the resulting
5134 file position relative to the beginning of the file in @var{position}.
5135 Your function should return a value of @code{0} on success and @code{-1}
5136 to indicate an error.
5138 You should define the function to do cleanup operations on the cookie
5139 appropriate for closing the stream as:
5141 @smallexample
5142 int @var{cleaner} (void *@var{cookie})
5143 @end smallexample
5145 Your function should return @code{-1} to indicate an error, and @code{0}
5146 otherwise.
5148 @deftp {Data Type} cookie_read_function_t
5149 @standards{GNU, stdio.h}
5150 This is the data type that the read function for a custom stream should have.
5151 If you declare the function as shown above, this is the type it will have.
5152 @end deftp
5154 @deftp {Data Type} cookie_write_function_t
5155 @standards{GNU, stdio.h}
5156 The data type of the write function for a custom stream.
5157 @end deftp
5159 @deftp {Data Type} cookie_seek_function_t
5160 @standards{GNU, stdio.h}
5161 The data type of the seek function for a custom stream.
5162 @end deftp
5164 @deftp {Data Type} cookie_close_function_t
5165 @standards{GNU, stdio.h}
5166 The data type of the close function for a custom stream.
5167 @end deftp
5169 @ignore
5170 Roland says:
5172 @quotation
5173 There is another set of functions one can give a stream, the
5174 input-room and output-room functions.  These functions must
5175 understand stdio internals.  To describe how to use these
5176 functions, you also need to document lots of how stdio works
5177 internally (which isn't relevant for other uses of stdio).
5178 Perhaps I can write an interface spec from which you can write
5179 good documentation.  But it's pretty complex and deals with lots
5180 of nitty-gritty details.  I think it might be better to let this
5181 wait until the rest of the manual is more done and polished.
5182 @end quotation
5183 @end ignore
5185 @c ??? This section could use an example.
5188 @node Formatted Messages
5189 @section Formatted Messages
5190 @cindex formatted messages
5192 On systems which are based on System V messages of programs (especially
5193 the system tools) are printed in a strict form using the @code{fmtmsg}
5194 function.  The uniformity sometimes helps the user to interpret messages
5195 and the strictness tests of the @code{fmtmsg} function ensure that the
5196 programmer follows some minimal requirements.
5198 @menu
5199 * Printing Formatted Messages::   The @code{fmtmsg} function.
5200 * Adding Severity Classes::       Add more severity classes.
5201 * Example::                       How to use @code{fmtmsg} and @code{addseverity}.
5202 @end menu
5205 @node Printing Formatted Messages
5206 @subsection Printing Formatted Messages
5208 Messages can be printed to standard error and/or to the console.  To
5209 select the destination the programmer can use the following two values,
5210 bitwise OR combined if wanted, for the @var{classification} parameter of
5211 @code{fmtmsg}:
5213 @vtable @code
5214 @item MM_PRINT
5215 Display the message in standard error.
5216 @item MM_CONSOLE
5217 Display the message on the system console.
5218 @end vtable
5220 The erroneous piece of the system can be signalled by exactly one of the
5221 following values which also is bitwise ORed with the
5222 @var{classification} parameter to @code{fmtmsg}:
5224 @vtable @code
5225 @item MM_HARD
5226 The source of the condition is some hardware.
5227 @item MM_SOFT
5228 The source of the condition is some software.
5229 @item MM_FIRM
5230 The source of the condition is some firmware.
5231 @end vtable
5233 A third component of the @var{classification} parameter to @code{fmtmsg}
5234 can describe the part of the system which detects the problem.  This is
5235 done by using exactly one of the following values:
5237 @vtable @code
5238 @item MM_APPL
5239 The erroneous condition is detected by the application.
5240 @item MM_UTIL
5241 The erroneous condition is detected by a utility.
5242 @item MM_OPSYS
5243 The erroneous condition is detected by the operating system.
5244 @end vtable
5246 A last component of @var{classification} can signal the results of this
5247 message.  Exactly one of the following values can be used:
5249 @vtable @code
5250 @item MM_RECOVER
5251 It is a recoverable error.
5252 @item MM_NRECOV
5253 It is a non-recoverable error.
5254 @end vtable
5256 @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})
5257 @standards{XPG, fmtmsg.h}
5258 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acsafe{}}
5259 Display a message described by its parameters on the device(s) specified
5260 in the @var{classification} parameter.  The @var{label} parameter
5261 identifies the source of the message.  The string should consist of two
5262 colon separated parts where the first part has not more than 10 and the
5263 second part not more than 14 characters.  The @var{text} parameter
5264 describes the condition of the error, the @var{action} parameter possible
5265 steps to recover from the error and the @var{tag} parameter is a
5266 reference to the online documentation where more information can be
5267 found.  It should contain the @var{label} value and a unique
5268 identification number.
5270 Each of the parameters can be a special value which means this value
5271 is to be omitted.  The symbolic names for these values are:
5273 @vtable @code
5274 @item MM_NULLLBL
5275 Ignore @var{label} parameter.
5276 @item MM_NULLSEV
5277 Ignore @var{severity} parameter.
5278 @item MM_NULLMC
5279 Ignore @var{classification} parameter.  This implies that nothing is
5280 actually printed.
5281 @item MM_NULLTXT
5282 Ignore @var{text} parameter.
5283 @item MM_NULLACT
5284 Ignore @var{action} parameter.
5285 @item MM_NULLTAG
5286 Ignore @var{tag} parameter.
5287 @end vtable
5289 There is another way certain fields can be omitted from the output to
5290 standard error.  This is described below in the description of
5291 environment variables influencing the behavior.
5293 The @var{severity} parameter can have one of the values in the following
5294 table:
5295 @cindex severity class
5297 @vtable @code
5298 @item MM_NOSEV
5299 Nothing is printed, this value is the same as @code{MM_NULLSEV}.
5300 @item MM_HALT
5301 This value is printed as @code{HALT}.
5302 @item MM_ERROR
5303 This value is printed as @code{ERROR}.
5304 @item MM_WARNING
5305 This value is printed as @code{WARNING}.
5306 @item MM_INFO
5307 This value is printed as @code{INFO}.
5308 @end vtable
5310 The numeric value of these five macros are between @code{0} and
5311 @code{4}.  Using the environment variable @code{SEV_LEVEL} or using the
5312 @code{addseverity} function one can add more severity levels with their
5313 corresponding string to print.  This is described below
5314 (@pxref{Adding Severity Classes}).
5316 @noindent
5317 If no parameter is ignored the output looks like this:
5319 @smallexample
5320 @var{label}: @var{severity-string}: @var{text}
5321 TO FIX: @var{action} @var{tag}
5322 @end smallexample
5324 The colons, new line characters and the @code{TO FIX} string are
5325 inserted if necessary, i.e., if the corresponding parameter is not
5326 ignored.
5328 This function is specified in the X/Open Portability Guide.  It is also
5329 available on all systems derived from System V.
5331 The function returns the value @code{MM_OK} if no error occurred.  If
5332 only the printing to standard error failed, it returns @code{MM_NOMSG}.
5333 If printing to the console fails, it returns @code{MM_NOCON}.  If
5334 nothing is printed @code{MM_NOTOK} is returned.  Among situations where
5335 all outputs fail this last value is also returned if a parameter value
5336 is incorrect.
5337 @end deftypefun
5339 There are two environment variables which influence the behavior of
5340 @code{fmtmsg}.  The first is @code{MSGVERB}.  It is used to control the
5341 output actually happening on standard error (@emph{not} the console
5342 output).  Each of the five fields can explicitly be enabled.  To do
5343 this the user has to put the @code{MSGVERB} variable with a format like
5344 the following in the environment before calling the @code{fmtmsg} function
5345 the first time:
5347 @smallexample
5348 MSGVERB=@var{keyword}[:@var{keyword}[:@dots{}]]
5349 @end smallexample
5351 Valid @var{keyword}s are @code{label}, @code{severity}, @code{text},
5352 @code{action}, and @code{tag}.  If the environment variable is not given
5353 or is the empty string, a not supported keyword is given or the value is
5354 somehow else invalid, no part of the message is masked out.
5356 The second environment variable which influences the behavior of
5357 @code{fmtmsg} is @code{SEV_LEVEL}.  This variable and the change in the
5358 behavior of @code{fmtmsg} is not specified in the X/Open Portability
5359 Guide.  It is available in System V systems, though.  It can be used to
5360 introduce new severity levels.  By default, only the five severity levels
5361 described above are available.  Any other numeric value would make
5362 @code{fmtmsg} print nothing.
5364 If the user puts @code{SEV_LEVEL} with a format like
5366 @smallexample
5367 SEV_LEVEL=[@var{description}[:@var{description}[:@dots{}]]]
5368 @end smallexample
5370 @noindent
5371 in the environment of the process before the first call to
5372 @code{fmtmsg}, where @var{description} has a value of the form
5374 @smallexample
5375 @var{severity-keyword},@var{level},@var{printstring}
5376 @end smallexample
5378 The @var{severity-keyword} part is not used by @code{fmtmsg} but it has
5379 to be present.  The @var{level} part is a string representation of a
5380 number.  The numeric value must be a number greater than 4.  This value
5381 must be used in the @var{severity} parameter of @code{fmtmsg} to select
5382 this class.  It is not possible to overwrite any of the predefined
5383 classes.  The @var{printstring} is the string printed when a message of
5384 this class is processed by @code{fmtmsg} (see above, @code{fmtsmg} does
5385 not print the numeric value but instead the string representation).
5388 @node Adding Severity Classes
5389 @subsection Adding Severity Classes
5390 @cindex severity class
5392 There is another possibility to introduce severity classes besides using
5393 the environment variable @code{SEV_LEVEL}.  This simplifies the task of
5394 introducing new classes in a running program.  One could use the
5395 @code{setenv} or @code{putenv} function to set the environment variable,
5396 but this is toilsome.
5398 @deftypefun int addseverity (int @var{severity}, const char *@var{string})
5399 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
5400 This function allows the introduction of new severity classes which can be
5401 addressed by the @var{severity} parameter of the @code{fmtmsg} function.
5402 The @var{severity} parameter of @code{addseverity} must match the value
5403 for the parameter with the same name of @code{fmtmsg}, and @var{string}
5404 is the string printed in the actual messages instead of the numeric
5405 value.
5407 If @var{string} is @code{NULL} the severity class with the numeric value
5408 according to @var{severity} is removed.
5410 It is not possible to overwrite or remove one of the default severity
5411 classes.  All calls to @code{addseverity} with @var{severity} set to one
5412 of the values for the default classes will fail.
5414 The return value is @code{MM_OK} if the task was successfully performed.
5415 If the return value is @code{MM_NOTOK} something went wrong.  This could
5416 mean that no more memory is available or a class is not available when
5417 it has to be removed.
5419 This function is not specified in the X/Open Portability Guide although
5420 the @code{fmtsmg} function is.  It is available on System V systems.
5421 @end deftypefun
5424 @node Example
5425 @subsection How to use @code{fmtmsg} and @code{addseverity}
5427 Here is a simple example program to illustrate the use of both
5428 functions described in this section.
5430 @smallexample
5431 @include fmtmsgexpl.c.texi
5432 @end smallexample
5434 The second call to @code{fmtmsg} illustrates a use of this function as
5435 it usually occurs on System V systems, which heavily use this function.
5436 It seems worthwhile to give a short explanation here of how this system
5437 works on System V.  The value of the
5438 @var{label} field (@code{UX:cat}) says that the error occurred in the
5439 Unix program @code{cat}.  The explanation of the error follows and the
5440 value for the @var{action} parameter is @code{"refer to manual"}.  One
5441 could be more specific here, if necessary.  The @var{tag} field contains,
5442 as proposed above, the value of the string given for the @var{label}
5443 parameter, and additionally a unique ID (@code{001} in this case).  For
5444 a GNU environment this string could contain a reference to the
5445 corresponding node in the Info page for the program.
5447 @noindent
5448 Running this program without specifying the @code{MSGVERB} and
5449 @code{SEV_LEVEL} function produces the following output:
5451 @smallexample
5452 UX:cat: NOTE2: invalid syntax
5453 TO FIX: refer to manual UX:cat:001
5454 @end smallexample
5456 We see the different fields of the message and how the extra glue (the
5457 colons and the @code{TO FIX} string) is printed.  But only one of the
5458 three calls to @code{fmtmsg} produced output.  The first call does not
5459 print anything because the @var{label} parameter is not in the correct
5460 form.  The string must contain two fields, separated by a colon
5461 (@pxref{Printing Formatted Messages}).  The third @code{fmtmsg} call
5462 produced no output since the class with the numeric value @code{6} is
5463 not defined.  Although a class with numeric value @code{5} is also not
5464 defined by default, the call to @code{addseverity} introduces it and
5465 the second call to @code{fmtmsg} produces the above output.
5467 When we change the environment of the program to contain
5468 @code{SEV_LEVEL=XXX,6,NOTE} when running it we get a different result:
5470 @smallexample
5471 UX:cat: NOTE2: invalid syntax
5472 TO FIX: refer to manual UX:cat:001
5473 label:foo: NOTE: text
5474 TO FIX: action tag
5475 @end smallexample
5477 Now the third call to @code{fmtmsg} produced some output and we see how
5478 the string @code{NOTE} from the environment variable appears in the
5479 message.
5481 Now we can reduce the output by specifying which fields we are
5482 interested in.  If we additionally set the environment variable
5483 @code{MSGVERB} to the value @code{severity:label:action} we get the
5484 following output:
5486 @smallexample
5487 UX:cat: NOTE2
5488 TO FIX: refer to manual
5489 label:foo: NOTE
5490 TO FIX: action
5491 @end smallexample
5493 @noindent
5494 I.e., the output produced by the @var{text} and the @var{tag} parameters
5495 to @code{fmtmsg} vanished.  Please also note that now there is no colon
5496 after the @code{NOTE} and @code{NOTE2} strings in the output.  This is
5497 not necessary since there is no more output on this line because the text
5498 is missing.