regexec.c: avoid arithmetic overflow in buffer size calculation
[glibc.git] / manual / stdio.texi
blob67485135499be023fb2aaa10cdc07857441c81e2
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 @comment stdio.h
59 @comment ISO
60 @deftp {Data Type} FILE
61 This is the data type used to represent stream objects.  A @code{FILE}
62 object holds all of the internal state information about the connection
63 to the associated file, including such things as the file position
64 indicator and buffering information.  Each stream also has error and
65 end-of-file status indicators that can be tested with the @code{ferror}
66 and @code{feof} functions; see @ref{EOF and Errors}.
67 @end deftp
69 @code{FILE} objects are allocated and managed internally by the
70 input/output library functions.  Don't try to create your own objects of
71 type @code{FILE}; let the library do it.  Your programs should
72 deal only with pointers to these objects (that is, @code{FILE *} values)
73 rather than the objects themselves.
74 @c !!! should say that FILE's have "No user-serviceable parts inside."
76 @node Standard Streams
77 @section Standard Streams
78 @cindex standard streams
79 @cindex streams, standard
81 When the @code{main} function of your program is invoked, it already has
82 three predefined streams open and available for use.  These represent
83 the ``standard'' input and output channels that have been established
84 for the process.
86 These streams are declared in the header file @file{stdio.h}.
87 @pindex stdio.h
89 @comment stdio.h
90 @comment ISO
91 @deftypevar {FILE *} stdin
92 The @dfn{standard input} stream, which is the normal source of input for the
93 program.
94 @end deftypevar
95 @cindex standard input stream
97 @comment stdio.h
98 @comment ISO
99 @deftypevar {FILE *} stdout
100 The @dfn{standard output} stream, which is used for normal output from
101 the program.
102 @end deftypevar
103 @cindex standard output stream
105 @comment stdio.h
106 @comment ISO
107 @deftypevar {FILE *} stderr
108 The @dfn{standard error} stream, which is used for error messages and
109 diagnostics issued by the program.
110 @end deftypevar
111 @cindex standard error stream
113 In the GNU system, you can specify what files or processes correspond to
114 these streams using the pipe and redirection facilities provided by the
115 shell.  (The primitives shells use to implement these facilities are
116 described in @ref{File System Interface}.)  Most other operating systems
117 provide similar mechanisms, but the details of how to use them can vary.
119 In the GNU C library, @code{stdin}, @code{stdout}, and @code{stderr} are
120 normal variables which you can set just like any others.  For example,
121 to redirect the standard output to a file, you could do:
123 @smallexample
124 fclose (stdout);
125 stdout = fopen ("standard-output-file", "w");
126 @end smallexample
128 Note however, that in other systems @code{stdin}, @code{stdout}, and
129 @code{stderr} are macros that you cannot assign to in the normal way.
130 But you can use @code{freopen} to get the effect of closing one and
131 reopening it.  @xref{Opening Streams}.
133 The three streams @code{stdin}, @code{stdout}, and @code{stderr} are not
134 unoriented at program start (@pxref{Streams and I18N}).
136 @node Opening Streams
137 @section Opening Streams
139 @cindex opening a stream
140 Opening a file with the @code{fopen} function creates a new stream and
141 establishes a connection between the stream and a file.  This may
142 involve creating a new file.
144 @pindex stdio.h
145 Everything described in this section is declared in the header file
146 @file{stdio.h}.
148 @comment stdio.h
149 @comment ISO
150 @deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype})
151 The @code{fopen} function opens a stream for I/O to the file
152 @var{filename}, and returns a pointer to the stream.
154 The @var{opentype} argument is a string that controls how the file is
155 opened and specifies attributes of the resulting stream.  It must begin
156 with one of the following sequences of characters:
158 @table @samp
159 @item r
160 Open an existing file for reading only.
162 @item w
163 Open the file for writing only.  If the file already exists, it is
164 truncated to zero length.  Otherwise a new file is created.
166 @item a
167 Open a file for append access; that is, writing at the end of file only.
168 If the file already exists, its initial contents are unchanged and
169 output to the stream is appended to the end of the file.
170 Otherwise, a new, empty file is created.
172 @item r+
173 Open an existing file for both reading and writing.  The initial contents
174 of the file are unchanged and the initial file position is at the
175 beginning of the file.
177 @item w+
178 Open a file for both reading and writing.  If the file already exists, it
179 is truncated to zero length.  Otherwise, a new file is created.
181 @item a+
182 Open or create file for both reading and appending.  If the file exists,
183 its initial contents are unchanged.  Otherwise, a new file is created.
184 The initial file position for reading is at the beginning of the file,
185 but output is always appended to the end of the file.
186 @end table
188 As you can see, @samp{+} requests a stream that can do both input and
189 output.  The ISO standard says that when using such a stream, you must
190 call @code{fflush} (@pxref{Stream Buffering}) or a file positioning
191 function such as @code{fseek} (@pxref{File Positioning}) when switching
192 from reading to writing or vice versa.  Otherwise, internal buffers
193 might not be emptied properly.  The GNU C library does not have this
194 limitation; you can do arbitrary reading and writing operations on a
195 stream in whatever order.
197 Additional characters may appear after these to specify flags for the
198 call.  Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is
199 the only part you are guaranteed will be understood by all systems.
201 The GNU C library defines one additional character for use in
202 @var{opentype}: the character @samp{x} insists on creating a new
203 file---if a file @var{filename} already exists, @code{fopen} fails
204 rather than opening it.  If you use @samp{x} you are guaranteed that
205 you will not clobber an existing file.  This is equivalent to the
206 @code{O_EXCL} option to the @code{open} function (@pxref{Opening and
207 Closing Files}).
209 The character @samp{b} in @var{opentype} has a standard meaning; it
210 requests a binary stream rather than a text stream.  But this makes no
211 difference in POSIX systems (including the GNU system).  If both
212 @samp{+} and @samp{b} are specified, they can appear in either order.
213 @xref{Binary Streams}.
215 @cindex stream orientation
216 @cindex orientation, stream
217 If the @var{opentype} string contains the sequence
218 @code{,ccs=@var{STRING}} then @var{STRING} is taken as the name of a
219 coded character set and @code{fopen} will mark the stream as
220 wide-oriented which appropriate conversion functions in place to convert
221 from and to the character set @var{STRING} is place.  Any other stream
222 is opened initially unoriented and the orientation is decided with the
223 first file operation.  If the first operation is a wide character
224 operation, the stream is not only marked as wide-oriented, also the
225 conversion functions to convert to the coded character set used for the
226 current locale are loaded.  This will not change anymore from this point
227 on even if the locale selected for the @code{LC_CTYPE} category is
228 changed.
230 Any other characters in @var{opentype} are simply ignored.  They may be
231 meaningful in other systems.
233 If the open fails, @code{fopen} returns a null pointer.
235 When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
236 32 bit machine this function is in fact @code{fopen64} since the LFS
237 interface replaces transparently the old interface.
238 @end deftypefun
240 You can have multiple streams (or file descriptors) pointing to the same
241 file open at the same time.  If you do only input, this works
242 straightforwardly, but you must be careful if any output streams are
243 included.  @xref{Stream/Descriptor Precautions}.  This is equally true
244 whether the streams are in one program (not usual) or in several
245 programs (which can easily happen).  It may be advantageous to use the
246 file locking facilities to avoid simultaneous access.  @xref{File
247 Locks}.
249 @comment stdio.h
250 @comment Unix98
251 @deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype})
252 This function is similar to @code{fopen} but the stream it returns a
253 pointer for is opened using @code{open64}.  Therefore this stream can be
254 used even on files larger then @math{2^31} bytes on 32 bit machines.
256 Please note that the return type is still @code{FILE *}.  There is no
257 special @code{FILE} type for the LFS interface.
259 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
260 bits machine this function is available under the name @code{fopen}
261 and so transparently replaces the old interface.
262 @end deftypefun
264 @comment stdio.h
265 @comment ISO
266 @deftypevr Macro int FOPEN_MAX
267 The value of this macro is an integer constant expression that
268 represents the minimum number of streams that the implementation
269 guarantees can be open simultaneously.  You might be able to open more
270 than this many streams, but that is not guaranteed.  The value of this
271 constant is at least eight, which includes the three standard streams
272 @code{stdin}, @code{stdout}, and @code{stderr}.  In POSIX.1 systems this
273 value is determined by the @code{OPEN_MAX} parameter; @pxref{General
274 Limits}.  In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE}
275 resource limit; @pxref{Limits on Resources}.
276 @end deftypevr
278 @comment stdio.h
279 @comment ISO
280 @deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
281 This function is like a combination of @code{fclose} and @code{fopen}.
282 It first closes the stream referred to by @var{stream}, ignoring any
283 errors that are detected in the process.  (Because errors are ignored,
284 you should not use @code{freopen} on an output stream if you have
285 actually done any output using the stream.)  Then the file named by
286 @var{filename} is opened with mode @var{opentype} as for @code{fopen},
287 and associated with the same stream object @var{stream}.
289 If the operation fails, a null pointer is returned; otherwise,
290 @code{freopen} returns @var{stream}.
292 @code{freopen} has traditionally been used to connect a standard stream
293 such as @code{stdin} with a file of your own choice.  This is useful in
294 programs in which use of a standard stream for certain purposes is
295 hard-coded.  In the GNU C library, you can simply close the standard
296 streams and open new ones with @code{fopen}.  But other systems lack
297 this ability, so using @code{freopen} is more portable.
299 When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
300 32 bit machine this function is in fact @code{freopen64} since the LFS
301 interface replaces transparently the old interface.
302 @end deftypefun
304 @comment stdio.h
305 @comment Unix98
306 @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
307 This function is similar to @code{freopen}.  The only difference is that
308 on 32 bit machine the stream returned is able to read beyond the
309 @math{2^31} bytes limits imposed by the normal interface.  It should be
310 noted that the stream pointed to by @var{stream} need not be opened
311 using @code{fopen64} or @code{freopen64} since its mode is not important
312 for this function.
314 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
315 bits machine this function is available under the name @code{freopen}
316 and so transparently replaces the old interface.
317 @end deftypefun
319 In some situations it is useful to know whether a given stream is
320 available for reading or writing.  This information is normally not
321 available and would have to be remembered separately.  Solaris
322 introduced a few functions to get this information from the stream
323 descriptor and these functions are also available in the GNU C library.
325 @comment stdio_ext.h
326 @comment GNU
327 @deftypefun int __freadable (FILE *@var{stream})
328 The @code{__freadable} function determines whether the stream
329 @var{stream} was opened to allow reading.  In this case the return value
330 is nonzero.  For write-only streams the function returns zero.
332 This function is declared in @file{stdio_ext.h}.
333 @end deftypefun
335 @comment stdio_ext.h
336 @comment GNU
337 @deftypefun int __fwritable (FILE *@var{stream})
338 The @code{__fwritable} function determines whether the stream
339 @var{stream} was opened to allow writing.  In this case the return value
340 is nonzero.  For read-only streams the function returns zero.
342 This function is declared in @file{stdio_ext.h}.
343 @end deftypefun
345 For slightly different kind of problems there are two more functions.
346 They provide even finer-grained information.
348 @comment stdio_ext.h
349 @comment GNU
350 @deftypefun int __freading (FILE *@var{stream})
351 The @code{__freading} function determines whether the stream
352 @var{stream} was last read from or whether it is opened read-only.  In
353 this case the return value is nonzero, otherwise it is zero.
354 Determining whether a stream opened for reading and writing was last
355 used for writing allows to draw conclusions about the content about the
356 buffer, among other things.
358 This function is declared in @file{stdio_ext.h}.
359 @end deftypefun
361 @comment stdio_ext.h
362 @comment GNU
363 @deftypefun int __fwriting (FILE *@var{stream})
364 The @code{__fwriting} function determines whether the stream
365 @var{stream} was last written to or whether it is opened write-only.  In
366 this case the return value is nonzero, otherwise it is zero.
368 This function is declared in @file{stdio_ext.h}.
369 @end deftypefun
372 @node Closing Streams
373 @section Closing Streams
375 @cindex closing a stream
376 When a stream is closed with @code{fclose}, the connection between the
377 stream and the file is canceled.  After you have closed a stream, you
378 cannot perform any additional operations on it.
380 @comment stdio.h
381 @comment ISO
382 @deftypefun int fclose (FILE *@var{stream})
383 This function causes @var{stream} to be closed and the connection to
384 the corresponding file to be broken.  Any buffered output is written
385 and any buffered input is discarded.  The @code{fclose} function returns
386 a value of @code{0} if the file was closed successfully, and @code{EOF}
387 if an error was detected.
389 It is important to check for errors when you call @code{fclose} to close
390 an output stream, because real, everyday errors can be detected at this
391 time.  For example, when @code{fclose} writes the remaining buffered
392 output, it might get an error because the disk is full.  Even if you
393 know the buffer is empty, errors can still occur when closing a file if
394 you are using NFS.
396 The function @code{fclose} is declared in @file{stdio.h}.
397 @end deftypefun
399 To close all streams currently available the GNU C Library provides
400 another function.
402 @comment stdio.h
403 @comment GNU
404 @deftypefun int fcloseall (void)
405 This function causes all open streams of the process to be closed and
406 the connection to corresponding files to be broken.  All buffered data
407 is written and any buffered input is discarded.  The @code{fcloseall}
408 function returns a value of @code{0} if all the files were closed
409 successfully, and @code{EOF} if an error was detected.
411 This function should be used only in special situations, e.g., when an
412 error occurred and the program must be aborted.  Normally each single
413 stream should be closed separately so that problems with individual
414 streams can be identified.  It is also problematic since the standard
415 streams (@pxref{Standard Streams}) will also be closed.
417 The function @code{fcloseall} is declared in @file{stdio.h}.
418 @end deftypefun
420 If the @code{main} function to your program returns, or if you call the
421 @code{exit} function (@pxref{Normal Termination}), all open streams are
422 automatically closed properly.  If your program terminates in any other
423 manner, such as by calling the @code{abort} function (@pxref{Aborting a
424 Program}) or from a fatal signal (@pxref{Signal Handling}), open streams
425 might not be closed properly.  Buffered output might not be flushed and
426 files may be incomplete.  For more information on buffering of streams,
427 see @ref{Stream Buffering}.
429 @node Streams and Threads
430 @section Streams and Threads
432 @cindex threads
433 @cindex multi-threaded application
434 Streams can be used in multi-threaded applications in the same way they
435 are used in single-threaded applications.  But the programmer must be
436 aware of the possible complications.  It is important to know about
437 these also if the program one writes never use threads since the design
438 and implementation of many stream functions is heavily influenced by the
439 requirements added by multi-threaded programming.
441 The POSIX standard requires that by default the stream operations are
442 atomic.  I.e., issuing two stream operations for the same stream in two
443 threads at the same time will cause the operations to be executed as if
444 they were issued sequentially.  The buffer operations performed while
445 reading or writing are protected from other uses of the same stream.  To
446 do this each stream has an internal lock object which has to be
447 (implicitly) acquired before any work can be done.
449 But there are situations where this is not enough and there are also
450 situations where this is not wanted.  The implicit locking is not enough
451 if the program requires more than one stream function call to happen
452 atomically.  One example would be if an output line a program wants to
453 generate is created by several function calls.  The functions by
454 themselves would ensure only atomicity of their own operation, but not
455 atomicity over all the function calls.  For this it is necessary to
456 perform the stream locking in the application code.
458 @comment stdio.h
459 @comment POSIX
460 @deftypefun void flockfile (FILE *@var{stream})
461 The @code{flockfile} function acquires the internal locking object
462 associated with the stream @var{stream}.  This ensures that no other
463 thread can explicitly through @code{flockfile}/@code{ftrylockfile} or
464 implicit through a call of a stream function lock the stream.  The
465 thread will block until the lock is acquired.  An explicit call to
466 @code{funlockfile} has to be used to release the lock.
467 @end deftypefun
469 @comment stdio.h
470 @comment POSIX
471 @deftypefun int ftrylockfile (FILE *@var{stream})
472 The @code{ftrylockfile} function tries to acquire the internal locking
473 object associated with the stream @var{stream} just like
474 @code{flockfile}.  But unlike @code{flockfile} this function does not
475 block if the lock is not available.  @code{ftrylockfile} returns zero if
476 the lock was successfully acquired.  Otherwise the stream is locked by
477 another thread.
478 @end deftypefun
480 @comment stdio.h
481 @comment POSIX
482 @deftypefun void funlockfile (FILE *@var{stream})
483 The @code{funlockfile} function releases the internal locking object of
484 the stream @var{stream}. The stream must have been locked before by a
485 call to @code{flockfile} or a successful call of @code{ftrylockfile}.
486 The implicit locking performed by the stream operations do not count.
487 The @code{funlockfile} function does not return an error status and the
488 behavior of a call for a stream which is not locked by the current
489 thread is undefined.
490 @end deftypefun
492 The following example shows how the functions above can be used to
493 generate an output line atomically even in multi-threaded applications
494 (yes, the same job could be done with one @code{fprintf} call but it is
495 sometimes not possible):
497 @smallexample
498 FILE *fp;
500    @dots{}
501    flockfile (fp);
502    fputs ("This is test number ", fp);
503    fprintf (fp, "%d\n", test);
504    funlockfile (fp)
506 @end smallexample
508 Without the explicit locking it would be possible for another thread to
509 use the stream @var{fp} after the @code{fputs} call return and before
510 @code{fprintf} was called with the result that the number does not
511 follow the word @samp{number}.
513 From this description it might already be clear that the locking objects
514 in streams are no simple mutexes.  Since locking the same stream twice
515 in the same thread is allowed the locking objects must be equivalent to
516 recursive mutexes.  These mutexes keep track of the owner and the number
517 of times the lock is acquired.  The same number of @code{funlockfile}
518 calls by the same threads is necessary to unlock the stream completely.
519 For instance:
521 @smallexample
522 void
523 foo (FILE *fp)
525   ftrylockfile (fp);
526   fputs ("in foo\n", fp);
527   /* @r{This is very wrong!!!}  */
528   funlockfile (fp);
530 @end smallexample
532 It is important here that the @code{funlockfile} function is only called
533 if the @code{ftrylockfile} function succeeded in locking the stream.  It
534 is therefore always wrong to ignore the result of @code{ftrylockfile}.
535 And it makes no sense since otherwise one would use @code{flockfile}.
536 The result of code like that above is that either @code{funlockfile}
537 tries to free a stream that hasn't been locked by the current thread or it
538 frees the stream prematurely.  The code should look like this:
540 @smallexample
541 void
542 foo (FILE *fp)
544   if (ftrylockfile (fp) == 0)
545     @{
546       fputs ("in foo\n", fp);
547       funlockfile (fp);
548     @}
550 @end smallexample
552 Now that we covered why it is necessary to have these locking it is
553 necessary to talk about situations when locking is unwanted and what can
554 be done.  The locking operations (explicit or implicit) don't come for
555 free.  Even if a lock is not taken the cost is not zero.  The operations
556 which have to be performed require memory operations that are safe in
557 multi-processor environments.  With the many local caches involved in
558 such systems this is quite costly.  So it is best to avoid the locking
559 completely if it is not needed -- because the code in question is never
560 used in a context where two or more threads may use a stream at a time.
561 This can be determined most of the time for application code; for
562 library code which can be used in many contexts one should default to be
563 conservative and use locking.
565 There are two basic mechanisms to avoid locking.  The first is to use
566 the @code{_unlocked} variants of the stream operations.  The POSIX
567 standard defines quite a few of those and the GNU library adds a few
568 more.  These variants of the functions behave just like the functions
569 with the name without the suffix except that they do not lock the
570 stream.  Using these functions is very desirable since they are
571 potentially much faster.  This is not only because the locking
572 operation itself is avoided.  More importantly, functions like
573 @code{putc} and @code{getc} are very simple and traditionally (before the
574 introduction of threads) were implemented as macros which are very fast
575 if the buffer is not empty.  With the addition of locking requirements
576 these functions are no longer implemented as macros since they would
577 would expand to too much code.
578 But these macros are still available with the same functionality under the new
579 names @code{putc_unlocked} and @code{getc_unlocked}.  This possibly huge
580 difference of speed also suggests the use of the @code{_unlocked}
581 functions even if locking is required.  The difference is that the
582 locking then has to be performed in the program:
584 @smallexample
585 void
586 foo (FILE *fp, char *buf)
588   flockfile (fp);
589   while (*buf != '/')
590     putc_unlocked (*buf++, fp);
591   funlockfile (fp);
593 @end smallexample
595 If in this example the @code{putc} function would be used and the
596 explicit locking would be missing the @code{putc} function would have to
597 acquire the lock in every call, potentially many times depending on when
598 the loop terminates.  Writing it the way illustrated above allows the
599 @code{putc_unlocked} macro to be used which means no locking and direct
600 manipulation of the buffer of the stream.
602 A second way to avoid locking is by using a non-standard function which
603 was introduced in Solaris and is available in the GNU C library as well.
605 @comment stdio_ext.h
606 @comment GNU
607 @deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type})
609 The @code{__fsetlocking} function can be used to select whether the
610 stream operations will implicitly acquire the locking object of the
611 stream @var{stream}.  By default this is done but it can be disabled and
612 reinstated using this function.  There are three values defined for the
613 @var{type} parameter.
615 @vtable @code
616 @item FSETLOCKING_INTERNAL
617 The stream @code{stream} will from now on use the default internal
618 locking.  Every stream operation with exception of the @code{_unlocked}
619 variants will implicitly lock the stream.
621 @item FSETLOCKING_BYCALLER
622 After the @code{__fsetlocking} function returns the user is responsible
623 for locking the stream.  None of the stream operations will implicitly
624 do this anymore until the state is set back to
625 @code{FSETLOCKING_INTERNAL}.
627 @item FSETLOCKING_QUERY
628 @code{__fsetlocking} only queries the current locking state of the
629 stream.  The return value will be @code{FSETLOCKING_INTERNAL} or
630 @code{FSETLOCKING_BYCALLER} depending on the state.
631 @end vtable
633 The return value of @code{__fsetlocking} is either
634 @code{FSETLOCKING_INTERNAL} or @code{FSETLOCKING_BYCALLER} depending on
635 the state of the stream before the call.
637 This function and the values for the @var{type} parameter are declared
638 in @file{stdio_ext.h}.
639 @end deftypefun
641 This function is especially useful when program code has to be used
642 which is written without knowledge about the @code{_unlocked} functions
643 (or if the programmer was too lazy to use them).
645 @node Streams and I18N
646 @section Streams in Internationalized Applications
648 @w{ISO C90} introduced the new type @code{wchar_t} to allow handling
649 larger character sets.  What was missing was a possibility to output
650 strings of @code{wchar_t} directly.  One had to convert them into
651 multibyte strings using @code{mbstowcs} (there was no @code{mbsrtowcs}
652 yet) and then use the normal stream functions.  While this is doable it
653 is very cumbersome since performing the conversions is not trivial and
654 greatly increases program complexity and size.
656 The Unix standard early on (I think in XPG4.2) introduced two additional
657 format specifiers for the @code{printf} and @code{scanf} families of
658 functions.  Printing and reading of single wide characters was made
659 possible using the @code{%C} specifier and wide character strings can be
660 handled with @code{%S}.  These modifiers behave just like @code{%c} and
661 @code{%s} only that they expect the corresponding argument to have the
662 wide character type and that the wide character and string are
663 transformed into/from multibyte strings before being used.
665 This was a beginning but it is still not good enough.  Not always is it
666 desirable to use @code{printf} and @code{scanf}.  The other, smaller and
667 faster functions cannot handle wide characters.  Second, it is not
668 possible to have a format string for @code{printf} and @code{scanf}
669 consisting of wide characters.  The result is that format strings would
670 have to be generated if they have to contain non-basic characters.
672 @cindex C++ streams
673 @cindex streams, C++
674 In the @w{Amendment 1} to @w{ISO C90} a whole new set of functions was
675 added to solve the problem.  Most of the stream functions got a
676 counterpart which take a wide character or wide character string instead
677 of a character or string respectively.  The new functions operate on the
678 same streams (like @code{stdout}).  This is different from the model of
679 the C++ runtime library where separate streams for wide and normal I/O
680 are used.
682 @cindex orientation, stream
683 @cindex stream orientation
684 Being able to use the same stream for wide and normal operations comes
685 with a restriction: a stream can be used either for wide operations or
686 for normal operations.  Once it is decided there is no way back.  Only a
687 call to @code{freopen} or @code{freopen64} can reset the
688 @dfn{orientation}.  The orientation can be decided in three ways:
690 @itemize @bullet
691 @item
692 If any of the normal character functions is used (this includes the
693 @code{fread} and @code{fwrite} functions) the stream is marked as not
694 wide oriented.
696 @item
697 If any of the wide character functions is used the stream is marked as
698 wide oriented.
700 @item
701 The @code{fwide} function can be used to set the orientation either way.
702 @end itemize
704 It is important to never mix the use of wide and not wide operations on
705 a stream.  There are no diagnostics issued.  The application behavior
706 will simply be strange or the application will simply crash.  The
707 @code{fwide} function can help avoiding this.
709 @comment wchar.h
710 @comment ISO
711 @deftypefun int fwide (FILE *@var{stream}, int @var{mode})
713 The @code{fwide} function can be used to set and query the state of the
714 orientation of the stream @var{stream}.  If the @var{mode} parameter has
715 a positive value the streams get wide oriented, for negative values
716 narrow oriented.  It is not possible to overwrite previous orientations
717 with @code{fwide}.  I.e., if the stream @var{stream} was already
718 oriented before the call nothing is done.
720 If @var{mode} is zero the current orientation state is queried and
721 nothing is changed.
723 The @code{fwide} function returns a negative value, zero, or a positive
724 value if the stream is narrow, not at all, or wide oriented
725 respectively.
727 This function was introduced in @w{Amendment 1} to @w{ISO C90} and is
728 declared in @file{wchar.h}.
729 @end deftypefun
731 It is generally a good idea to orient a stream as early as possible.
732 This can prevent surprise especially for the standard streams
733 @code{stdin}, @code{stdout}, and @code{stderr}.  If some library
734 function in some situations uses one of these streams and this use
735 orients the stream in a different way the rest of the application
736 expects it one might end up with hard to reproduce errors.  Remember
737 that no errors are signal if the streams are used incorrectly.  Leaving
738 a stream unoriented after creation is normally only necessary for
739 library functions which create streams which can be used in different
740 contexts.
742 When writing code which uses streams and which can be used in different
743 contexts it is important to query the orientation of the stream before
744 using it (unless the rules of the library interface demand a specific
745 orientation).  The following little, silly function illustrates this.
747 @smallexample
748 void
749 print_f (FILE *fp)
751   if (fwide (fp, 0) > 0)
752     /* @r{Positive return value means wide orientation.}  */
753     fputwc (L'f', fp);
754   else
755     fputc ('f', fp);
757 @end smallexample
759 Note that in this case the function @code{print_f} decides about the
760 orientation of the stream if it was unoriented before (will not happen
761 if the advise above is followed).
763 The encoding used for the @code{wchar_t} values is unspecified and the
764 user must not make any assumptions about it.  For I/O of @code{wchar_t}
765 values this means that it is impossible to write these values directly
766 to the stream.  This is not what follows from the @w{ISO C} locale model
767 either.  What happens instead is that the bytes read from or written to
768 the underlying media are first converted into the internal encoding
769 chosen by the implementation for @code{wchar_t}.  The external encoding
770 is determined by the @code{LC_CTYPE} category of the current locale or
771 by the @samp{ccs} part of the mode specification given to @code{fopen},
772 @code{fopen64}, @code{freopen}, or @code{freopen64}.  How and when the
773 conversion happens is unspecified and it happens invisible to the user.
775 Since a stream is created in the unoriented state it has at that point
776 no conversion associated with it.  The conversion which will be used is
777 determined by the @code{LC_CTYPE} category selected at the time the
778 stream is oriented.  If the locales are changed at the runtime this
779 might produce surprising results unless one pays attention.  This is
780 just another good reason to orient the stream explicitly as soon as
781 possible, perhaps with a call to @code{fwide}.
783 @node Simple Output
784 @section Simple Output by Characters or Lines
786 @cindex writing to a stream, by characters
787 This section describes functions for performing character- and
788 line-oriented output.
790 These narrow streams functions are declared in the header file
791 @file{stdio.h} and the wide stream functions in @file{wchar.h}.
792 @pindex stdio.h
793 @pindex wchar.h
795 @comment stdio.h
796 @comment ISO
797 @deftypefun int fputc (int @var{c}, FILE *@var{stream})
798 The @code{fputc} function converts the character @var{c} to type
799 @code{unsigned char}, and writes it to the stream @var{stream}.
800 @code{EOF} is returned if a write error occurs; otherwise the
801 character @var{c} is returned.
802 @end deftypefun
804 @comment wchar.h
805 @comment ISO
806 @deftypefun wint_t fputwc (wchar_t @var{wc}, FILE *@var{stream})
807 The @code{fputwc} function writes the wide character @var{wc} to the
808 stream @var{stream}.  @code{WEOF} is returned if a write error occurs;
809 otherwise the character @var{wc} is returned.
810 @end deftypefun
812 @comment stdio.h
813 @comment POSIX
814 @deftypefun int fputc_unlocked (int @var{c}, FILE *@var{stream})
815 The @code{fputc_unlocked} function is equivalent to the @code{fputc}
816 function except that it does not implicitly lock the stream.
817 @end deftypefun
819 @comment wchar.h
820 @comment POSIX
821 @deftypefun wint_t fputwc_unlocked (wint_t @var{wc}, FILE *@var{stream})
822 The @code{fputwc_unlocked} function is equivalent to the @code{fputwc}
823 function except that it does not implicitly lock the stream.
825 This function is a GNU extension.
826 @end deftypefun
828 @comment stdio.h
829 @comment ISO
830 @deftypefun int putc (int @var{c}, FILE *@var{stream})
831 This is just like @code{fputc}, except that most systems implement it as
832 a macro, making it faster.  One consequence is that it may evaluate the
833 @var{stream} argument more than once, which is an exception to the
834 general rule for macros.  @code{putc} is usually the best function to
835 use for writing a single character.
836 @end deftypefun
838 @comment wchar.h
839 @comment ISO
840 @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream})
841 This is just like @code{fputwc}, except that it can be implement as
842 a macro, making it faster.  One consequence is that it may evaluate the
843 @var{stream} argument more than once, which is an exception to the
844 general rule for macros.  @code{putwc} is usually the best function to
845 use for writing a single wide character.
846 @end deftypefun
848 @comment stdio.h
849 @comment POSIX
850 @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})
851 The @code{putc_unlocked} function is equivalent to the @code{putc}
852 function except that it does not implicitly lock the stream.
853 @end deftypefun
855 @comment wchar.h
856 @comment GNU
857 @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
858 The @code{putwc_unlocked} function is equivalent to the @code{putwc}
859 function except that it does not implicitly lock the stream.
861 This function is a GNU extension.
862 @end deftypefun
864 @comment stdio.h
865 @comment ISO
866 @deftypefun int putchar (int @var{c})
867 The @code{putchar} function is equivalent to @code{putc} with
868 @code{stdout} as the value of the @var{stream} argument.
869 @end deftypefun
871 @comment wchar.h
872 @comment ISO
873 @deftypefun wint_t putwchar (wchar_t @var{wc})
874 The @code{putwchar} function is equivalent to @code{putwc} with
875 @code{stdout} as the value of the @var{stream} argument.
876 @end deftypefun
878 @comment stdio.h
879 @comment POSIX
880 @deftypefun int putchar_unlocked (int @var{c})
881 The @code{putchar_unlocked} function is equivalent to the @code{putchar}
882 function except that it does not implicitly lock the stream.
883 @end deftypefun
885 @comment wchar.h
886 @comment GNU
887 @deftypefun wint_t putwchar_unlocked (wchar_t @var{wc})
888 The @code{putwchar_unlocked} function is equivalent to the @code{putwchar}
889 function except that it does not implicitly lock the stream.
891 This function is a GNU extension.
892 @end deftypefun
894 @comment stdio.h
895 @comment ISO
896 @deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
897 The function @code{fputs} writes the string @var{s} to the stream
898 @var{stream}.  The terminating null character is not written.
899 This function does @emph{not} add a newline character, either.
900 It outputs only the characters in the string.
902 This function returns @code{EOF} if a write error occurs, and otherwise
903 a non-negative value.
905 For example:
907 @smallexample
908 fputs ("Are ", stdout);
909 fputs ("you ", stdout);
910 fputs ("hungry?\n", stdout);
911 @end smallexample
913 @noindent
914 outputs the text @samp{Are you hungry?} followed by a newline.
915 @end deftypefun
917 @comment wchar.h
918 @comment ISO
919 @deftypefun int fputws (const wchar_t *@var{ws}, FILE *@var{stream})
920 The function @code{fputws} writes the wide character string @var{ws} to
921 the stream @var{stream}.  The terminating null character is not written.
922 This function does @emph{not} add a newline character, either.  It
923 outputs only the characters in the string.
925 This function returns @code{WEOF} if a write error occurs, and otherwise
926 a non-negative value.
927 @end deftypefun
929 @comment stdio.h
930 @comment GNU
931 @deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream})
932 The @code{fputs_unlocked} function is equivalent to the @code{fputs}
933 function except that it does not implicitly lock the stream.
935 This function is a GNU extension.
936 @end deftypefun
938 @comment wchar.h
939 @comment GNU
940 @deftypefun int fputws_unlocked (const wchar_t *@var{ws}, FILE *@var{stream})
941 The @code{fputws_unlocked} function is equivalent to the @code{fputws}
942 function except that it does not implicitly lock the stream.
944 This function is a GNU extension.
945 @end deftypefun
947 @comment stdio.h
948 @comment ISO
949 @deftypefun int puts (const char *@var{s})
950 The @code{puts} function writes the string @var{s} to the stream
951 @code{stdout} followed by a newline.  The terminating null character of
952 the string is not written.  (Note that @code{fputs} does @emph{not}
953 write a newline as this function does.)
955 @code{puts} is the most convenient function for printing simple
956 messages.  For example:
958 @smallexample
959 puts ("This is a message.");
960 @end smallexample
962 @noindent
963 outputs the text @samp{This is a message.} followed by a newline.
964 @end deftypefun
966 @comment stdio.h
967 @comment SVID
968 @deftypefun int putw (int @var{w}, FILE *@var{stream})
969 This function writes the word @var{w} (that is, an @code{int}) to
970 @var{stream}.  It is provided for compatibility with SVID, but we
971 recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
972 @end deftypefun
974 @node Character Input
975 @section Character Input
977 @cindex reading from a stream, by characters
978 This section describes functions for performing character-oriented
979 input.  These narrow streams functions are declared in the header file
980 @file{stdio.h} and the wide character functions are declared in
981 @file{wchar.h}.
982 @pindex stdio.h
983 @pindex wchar.h
985 These functions return an @code{int} or @code{wint_t} value (for narrow
986 and wide stream functions respectively) that is either a character of
987 input, or the special value @code{EOF}/@code{WEOF} (usually -1).  For
988 the narrow stream functions it is important to store the result of these
989 functions in a variable of type @code{int} instead of @code{char}, even
990 when you plan to use it only as a character.  Storing @code{EOF} in a
991 @code{char} variable truncates its value to the size of a character, so
992 that it is no longer distinguishable from the valid character
993 @samp{(char) -1}.  So always use an @code{int} for the result of
994 @code{getc} and friends, and check for @code{EOF} after the call; once
995 you've verified that the result is not @code{EOF}, you can be sure that
996 it will fit in a @samp{char} variable without loss of information.
998 @comment stdio.h
999 @comment ISO
1000 @deftypefun int fgetc (FILE *@var{stream})
1001 This function reads the next character as an @code{unsigned char} from
1002 the stream @var{stream} and returns its value, converted to an
1003 @code{int}.  If an end-of-file condition or read error occurs,
1004 @code{EOF} is returned instead.
1005 @end deftypefun
1007 @comment wchar.h
1008 @comment ISO
1009 @deftypefun wint_t fgetwc (FILE *@var{stream})
1010 This function reads the next wide character from the stream @var{stream}
1011 and returns its value.  If an end-of-file condition or read error
1012 occurs, @code{WEOF} is returned instead.
1013 @end deftypefun
1015 @comment stdio.h
1016 @comment POSIX
1017 @deftypefun int fgetc_unlocked (FILE *@var{stream})
1018 The @code{fgetc_unlocked} function is equivalent to the @code{fgetc}
1019 function except that it does not implicitly lock the stream.
1020 @end deftypefun
1022 @comment wchar.h
1023 @comment GNU
1024 @deftypefun wint_t fgetwc_unlocked (FILE *@var{stream})
1025 The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc}
1026 function except that it does not implicitly lock the stream.
1028 This function is a GNU extension.
1029 @end deftypefun
1031 @comment stdio.h
1032 @comment ISO
1033 @deftypefun int getc (FILE *@var{stream})
1034 This is just like @code{fgetc}, except that it is permissible (and
1035 typical) for it to be implemented as a macro that evaluates the
1036 @var{stream} argument more than once.  @code{getc} is often highly
1037 optimized, so it is usually the best function to use to read a single
1038 character.
1039 @end deftypefun
1041 @comment wchar.h
1042 @comment ISO
1043 @deftypefun wint_t getwc (FILE *@var{stream})
1044 This is just like @code{fgetwc}, except that it is permissible for it to
1045 be implemented as a macro that evaluates the @var{stream} argument more
1046 than once.  @code{getwc} can be highly optimized, so it is usually the
1047 best function to use to read a single wide character.
1048 @end deftypefun
1050 @comment stdio.h
1051 @comment POSIX
1052 @deftypefun int getc_unlocked (FILE *@var{stream})
1053 The @code{getc_unlocked} function is equivalent to the @code{getc}
1054 function except that it does not implicitly lock the stream.
1055 @end deftypefun
1057 @comment wchar.h
1058 @comment GNU
1059 @deftypefun wint_t getwc_unlocked (FILE *@var{stream})
1060 The @code{getwc_unlocked} function is equivalent to the @code{getwc}
1061 function except that it does not implicitly lock the stream.
1063 This function is a GNU extension.
1064 @end deftypefun
1066 @comment stdio.h
1067 @comment ISO
1068 @deftypefun int getchar (void)
1069 The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
1070 as the value of the @var{stream} argument.
1071 @end deftypefun
1073 @comment wchar.h
1074 @comment ISO
1075 @deftypefun wint_t getwchar (void)
1076 The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin}
1077 as the value of the @var{stream} argument.
1078 @end deftypefun
1080 @comment stdio.h
1081 @comment POSIX
1082 @deftypefun int getchar_unlocked (void)
1083 The @code{getchar_unlocked} function is equivalent to the @code{getchar}
1084 function except that it does not implicitly lock the stream.
1085 @end deftypefun
1087 @comment wchar.h
1088 @comment GNU
1089 @deftypefun wint_t getwchar_unlocked (void)
1090 The @code{getwchar_unlocked} function is equivalent to the @code{getwchar}
1091 function except that it does not implicitly lock the stream.
1093 This function is a GNU extension.
1094 @end deftypefun
1096 Here is an example of a function that does input using @code{fgetc}.  It
1097 would work just as well using @code{getc} instead, or using
1098 @code{getchar ()} instead of @w{@code{fgetc (stdin)}}.  The code would
1099 also work the same for the wide character stream functions.
1101 @smallexample
1103 y_or_n_p (const char *question)
1105   fputs (question, stdout);
1106   while (1)
1107     @{
1108       int c, answer;
1109       /* @r{Write a space to separate answer from question.} */
1110       fputc (' ', stdout);
1111       /* @r{Read the first character of the line.}
1112          @r{This should be the answer character, but might not be.} */
1113       c = tolower (fgetc (stdin));
1114       answer = c;
1115       /* @r{Discard rest of input line.} */
1116       while (c != '\n' && c != EOF)
1117         c = fgetc (stdin);
1118       /* @r{Obey the answer if it was valid.} */
1119       if (answer == 'y')
1120         return 1;
1121       if (answer == 'n')
1122         return 0;
1123       /* @r{Answer was invalid: ask for valid answer.} */
1124       fputs ("Please answer y or n:", stdout);
1125     @}
1127 @end smallexample
1129 @comment stdio.h
1130 @comment SVID
1131 @deftypefun int getw (FILE *@var{stream})
1132 This function reads a word (that is, an @code{int}) from @var{stream}.
1133 It's provided for compatibility with SVID.  We recommend you use
1134 @code{fread} instead (@pxref{Block Input/Output}).  Unlike @code{getc},
1135 any @code{int} value could be a valid result.  @code{getw} returns
1136 @code{EOF} when it encounters end-of-file or an error, but there is no
1137 way to distinguish this from an input word with value -1.
1138 @end deftypefun
1140 @node Line Input
1141 @section Line-Oriented Input
1143 Since many programs interpret input on the basis of lines, it is
1144 convenient to have functions to read a line of text from a stream.
1146 Standard C has functions to do this, but they aren't very safe: null
1147 characters and even (for @code{gets}) long lines can confuse them.  So
1148 the GNU library provides the nonstandard @code{getline} function that
1149 makes it easy to read lines reliably.
1151 Another GNU extension, @code{getdelim}, generalizes @code{getline}.  It
1152 reads a delimited record, defined as everything through the next
1153 occurrence of a specified delimiter character.
1155 All these functions are declared in @file{stdio.h}.
1157 @comment stdio.h
1158 @comment GNU
1159 @deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
1160 This function reads an entire line from @var{stream}, storing the text
1161 (including the newline and a terminating null character) in a buffer
1162 and storing the buffer address in @code{*@var{lineptr}}.
1164 Before calling @code{getline}, you should place in @code{*@var{lineptr}}
1165 the address of a buffer @code{*@var{n}} bytes long, allocated with
1166 @code{malloc}.  If this buffer is long enough to hold the line,
1167 @code{getline} stores the line in this buffer.  Otherwise,
1168 @code{getline} makes the buffer bigger using @code{realloc}, storing the
1169 new buffer address back in @code{*@var{lineptr}} and the increased size
1170 back in @code{*@var{n}}.
1171 @xref{Unconstrained Allocation}.
1173 If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}}
1174 to zero, before the call, then @code{getline} allocates the initial
1175 buffer for you by calling @code{malloc}.
1177 In either case, when @code{getline} returns,  @code{*@var{lineptr}} is
1178 a @code{char *} which points to the text of the line.
1180 When @code{getline} is successful, it returns the number of characters
1181 read (including the newline, but not including the terminating null).
1182 This value enables you to distinguish null characters that are part of
1183 the line from the null character inserted as a terminator.
1185 This function is a GNU extension, but it is the recommended way to read
1186 lines from a stream.  The alternative standard functions are unreliable.
1188 If an error occurs or end of file is reached without any bytes read,
1189 @code{getline} returns @code{-1}.
1190 @end deftypefun
1192 @comment stdio.h
1193 @comment GNU
1194 @deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream})
1195 This function is like @code{getline} except that the character which
1196 tells it to stop reading is not necessarily newline.  The argument
1197 @var{delimiter} specifies the delimiter character; @code{getdelim} keeps
1198 reading until it sees that character (or end of file).
1200 The text is stored in @var{lineptr}, including the delimiter character
1201 and a terminating null.  Like @code{getline}, @code{getdelim} makes
1202 @var{lineptr} bigger if it isn't big enough.
1204 @code{getline} is in fact implemented in terms of @code{getdelim}, just
1205 like this:
1207 @smallexample
1208 ssize_t
1209 getline (char **lineptr, size_t *n, FILE *stream)
1211   return getdelim (lineptr, n, '\n', stream);
1213 @end smallexample
1214 @end deftypefun
1216 @comment stdio.h
1217 @comment ISO
1218 @deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
1219 The @code{fgets} function reads characters from the stream @var{stream}
1220 up to and including a newline character and stores them in the string
1221 @var{s}, adding a null character to mark the end of the string.  You
1222 must supply @var{count} characters worth of space in @var{s}, but the
1223 number of characters read is at most @var{count} @minus{} 1.  The extra
1224 character space is used to hold the null character at the end of the
1225 string.
1227 If the system is already at end of file when you call @code{fgets}, then
1228 the contents of the array @var{s} are unchanged and a null pointer is
1229 returned.  A null pointer is also returned if a read error occurs.
1230 Otherwise, the return value is the pointer @var{s}.
1232 @strong{Warning:}  If the input data has a null character, you can't tell.
1233 So don't use @code{fgets} unless you know the data cannot contain a null.
1234 Don't use it to read files edited by the user because, if the user inserts
1235 a null character, you should either handle it properly or print a clear
1236 error message.  We recommend using @code{getline} instead of @code{fgets}.
1237 @end deftypefun
1239 @comment wchar.h
1240 @comment ISO
1241 @deftypefun {wchar_t *} fgetws (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
1242 The @code{fgetws} function reads wide characters from the stream
1243 @var{stream} up to and including a newline character and stores them in
1244 the string @var{ws}, adding a null wide character to mark the end of the
1245 string.  You must supply @var{count} wide characters worth of space in
1246 @var{ws}, but the number of characters read is at most @var{count}
1247 @minus{} 1.  The extra character space is used to hold the null wide
1248 character at the end of the string.
1250 If the system is already at end of file when you call @code{fgetws}, then
1251 the contents of the array @var{ws} are unchanged and a null pointer is
1252 returned.  A null pointer is also returned if a read error occurs.
1253 Otherwise, the return value is the pointer @var{ws}.
1255 @strong{Warning:} If the input data has a null wide character (which are
1256 null bytes in the input stream), you can't tell.  So don't use
1257 @code{fgetws} unless you know the data cannot contain a null.  Don't use
1258 it to read files edited by the user because, if the user inserts a null
1259 character, you should either handle it properly or print a clear error
1260 message.
1261 @comment XXX We need getwline!!!
1262 @end deftypefun
1264 @comment stdio.h
1265 @comment GNU
1266 @deftypefun {char *} fgets_unlocked (char *@var{s}, int @var{count}, FILE *@var{stream})
1267 The @code{fgets_unlocked} function is equivalent to the @code{fgets}
1268 function except that it does not implicitly lock the stream.
1270 This function is a GNU extension.
1271 @end deftypefun
1273 @comment wchar.h
1274 @comment GNU
1275 @deftypefun {wchar_t *} fgetws_unlocked (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
1276 The @code{fgetws_unlocked} function is equivalent to the @code{fgetws}
1277 function except that it does not implicitly lock the stream.
1279 This function is a GNU extension.
1280 @end deftypefun
1282 @comment stdio.h
1283 @comment ISO
1284 @deftypefn {Deprecated function} {char *} gets (char *@var{s})
1285 The function @code{gets} reads characters from the stream @code{stdin}
1286 up to the next newline character, and stores them in the string @var{s}.
1287 The newline character is discarded (note that this differs from the
1288 behavior of @code{fgets}, which copies the newline character into the
1289 string).  If @code{gets} encounters a read error or end-of-file, it
1290 returns a null pointer; otherwise it returns @var{s}.
1292 @strong{Warning:} The @code{gets} function is @strong{very dangerous}
1293 because it provides no protection against overflowing the string
1294 @var{s}.  The GNU library includes it for compatibility only.  You
1295 should @strong{always} use @code{fgets} or @code{getline} instead.  To
1296 remind you of this, the linker (if using GNU @code{ld}) will issue a
1297 warning whenever you use @code{gets}.
1298 @end deftypefn
1300 @node Unreading
1301 @section Unreading
1302 @cindex peeking at input
1303 @cindex unreading characters
1304 @cindex pushing input back
1306 In parser programs it is often useful to examine the next character in
1307 the input stream without removing it from the stream.  This is called
1308 ``peeking ahead'' at the input because your program gets a glimpse of
1309 the input it will read next.
1311 Using stream I/O, you can peek ahead at input by first reading it and
1312 then @dfn{unreading} it (also called  @dfn{pushing it back} on the stream).
1313 Unreading a character makes it available to be input again from the stream,
1314 by  the next call to @code{fgetc} or other input function on that stream.
1316 @menu
1317 * Unreading Idea::              An explanation of unreading with pictures.
1318 * How Unread::                  How to call @code{ungetc} to do unreading.
1319 @end menu
1321 @node Unreading Idea
1322 @subsection What Unreading Means
1324 Here is a pictorial explanation of unreading.  Suppose you have a
1325 stream reading a file that contains just six characters, the letters
1326 @samp{foobar}.  Suppose you have read three characters so far.  The
1327 situation looks like this:
1329 @smallexample
1330 f  o  o  b  a  r
1331          ^
1332 @end smallexample
1334 @noindent
1335 so the next input character will be @samp{b}.
1337 @c @group   Invalid outside @example
1338 If instead of reading @samp{b} you unread the letter @samp{o}, you get a
1339 situation like this:
1341 @smallexample
1342 f  o  o  b  a  r
1343          |
1344       o--
1345       ^
1346 @end smallexample
1348 @noindent
1349 so that the next input characters will be @samp{o} and @samp{b}.
1350 @c @end group
1352 @c @group
1353 If you unread @samp{9} instead of @samp{o}, you get this situation:
1355 @smallexample
1356 f  o  o  b  a  r
1357          |
1358       9--
1359       ^
1360 @end smallexample
1362 @noindent
1363 so that the next input characters will be @samp{9} and @samp{b}.
1364 @c @end group
1366 @node How Unread
1367 @subsection Using @code{ungetc} To Do Unreading
1369 The function to unread a character is called @code{ungetc}, because it
1370 reverses the action of @code{getc}.
1372 @comment stdio.h
1373 @comment ISO
1374 @deftypefun int ungetc (int @var{c}, FILE *@var{stream})
1375 The @code{ungetc} function pushes back the character @var{c} onto the
1376 input stream @var{stream}.  So the next input from @var{stream} will
1377 read @var{c} before anything else.
1379 If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
1380 @code{EOF}.  This lets you call @code{ungetc} with the return value of
1381 @code{getc} without needing to check for an error from @code{getc}.
1383 The character that you push back doesn't have to be the same as the last
1384 character that was actually read from the stream.  In fact, it isn't
1385 necessary to actually read any characters from the stream before
1386 unreading them with @code{ungetc}!  But that is a strange way to write a
1387 program; usually @code{ungetc} is used only to unread a character that
1388 was just read from the same stream.  The GNU C library supports this
1389 even on files opened in binary mode, but other systems might not.
1391 The GNU C library only supports one character of pushback---in other
1392 words, it does not work to call @code{ungetc} twice without doing input
1393 in between.  Other systems might let you push back multiple characters;
1394 then reading from the stream retrieves the characters in the reverse
1395 order that they were pushed.
1397 Pushing back characters doesn't alter the file; only the internal
1398 buffering for the stream is affected.  If a file positioning function
1399 (such as @code{fseek}, @code{fseeko} or @code{rewind}; @pxref{File
1400 Positioning}) is called, any pending pushed-back characters are
1401 discarded.
1403 Unreading a character on a stream that is at end of file clears the
1404 end-of-file indicator for the stream, because it makes the character of
1405 input available.  After you read that character, trying to read again
1406 will encounter end of file.
1407 @end deftypefun
1409 @comment wchar.h
1410 @comment ISO
1411 @deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream})
1412 The @code{ungetwc} function behaves just like @code{ungetc} just that it
1413 pushes back a wide character.
1414 @end deftypefun
1416 Here is an example showing the use of @code{getc} and @code{ungetc} to
1417 skip over whitespace characters.  When this function reaches a
1418 non-whitespace character, it unreads that character to be seen again on
1419 the next read operation on the stream.
1421 @smallexample
1422 #include <stdio.h>
1423 #include <ctype.h>
1425 void
1426 skip_whitespace (FILE *stream)
1428   int c;
1429   do
1430     /* @r{No need to check for @code{EOF} because it is not}
1431        @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.}  */
1432     c = getc (stream);
1433   while (isspace (c));
1434   ungetc (c, stream);
1436 @end smallexample
1438 @node Block Input/Output
1439 @section Block Input/Output
1441 This section describes how to do input and output operations on blocks
1442 of data.  You can use these functions to read and write binary data, as
1443 well as to read and write text in fixed-size blocks instead of by
1444 characters or lines.
1445 @cindex binary I/O to a stream
1446 @cindex block I/O to a stream
1447 @cindex reading from a stream, by blocks
1448 @cindex writing to a stream, by blocks
1450 Binary files are typically used to read and write blocks of data in the
1451 same format as is used to represent the data in a running program.  In
1452 other words, arbitrary blocks of memory---not just character or string
1453 objects---can be written to a binary file, and meaningfully read in
1454 again by the same program.
1456 Storing data in binary form is often considerably more efficient than
1457 using the formatted I/O functions.  Also, for floating-point numbers,
1458 the binary form avoids possible loss of precision in the conversion
1459 process.  On the other hand, binary files can't be examined or modified
1460 easily using many standard file utilities (such as text editors), and
1461 are not portable between different implementations of the language, or
1462 different kinds of computers.
1464 These functions are declared in @file{stdio.h}.
1465 @pindex stdio.h
1467 @comment stdio.h
1468 @comment ISO
1469 @deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1470 This function reads up to @var{count} objects of size @var{size} into
1471 the array @var{data}, from the stream @var{stream}.  It returns the
1472 number of objects actually read, which might be less than @var{count} if
1473 a read error occurs or the end of the file is reached.  This function
1474 returns a value of zero (and doesn't read anything) if either @var{size}
1475 or @var{count} is zero.
1477 If @code{fread} encounters end of file in the middle of an object, it
1478 returns the number of complete objects read, and discards the partial
1479 object.  Therefore, the stream remains at the actual end of the file.
1480 @end deftypefun
1482 @comment stdio.h
1483 @comment GNU
1484 @deftypefun size_t fread_unlocked (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1485 The @code{fread_unlocked} function is equivalent to the @code{fread}
1486 function except that it does not implicitly lock the stream.
1488 This function is a GNU extension.
1489 @end deftypefun
1491 @comment stdio.h
1492 @comment ISO
1493 @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1494 This function writes up to @var{count} objects of size @var{size} from
1495 the array @var{data}, to the stream @var{stream}.  The return value is
1496 normally @var{count}, if the call succeeds.  Any other value indicates
1497 some sort of error, such as running out of space.
1498 @end deftypefun
1500 @comment stdio.h
1501 @comment GNU
1502 @deftypefun size_t fwrite_unlocked (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
1503 The @code{fwrite_unlocked} function is equivalent to the @code{fwrite}
1504 function except that it does not implicitly lock the stream.
1506 This function is a GNU extension.
1507 @end deftypefun
1509 @node Formatted Output
1510 @section Formatted Output
1512 @cindex format string, for @code{printf}
1513 @cindex template, for @code{printf}
1514 @cindex formatted output to a stream
1515 @cindex writing to a stream, formatted
1516 The functions described in this section (@code{printf} and related
1517 functions) provide a convenient way to perform formatted output.  You
1518 call @code{printf} with a @dfn{format string} or @dfn{template string}
1519 that specifies how to format the values of the remaining arguments.
1521 Unless your program is a filter that specifically performs line- or
1522 character-oriented processing, using @code{printf} or one of the other
1523 related functions described in this section is usually the easiest and
1524 most concise way to perform output.  These functions are especially
1525 useful for printing error messages, tables of data, and the like.
1527 @menu
1528 * Formatted Output Basics::     Some examples to get you started.
1529 * Output Conversion Syntax::    General syntax of conversion
1530                                  specifications.
1531 * Table of Output Conversions:: Summary of output conversions and
1532                                  what they do.
1533 * Integer Conversions::         Details about formatting of integers.
1534 * Floating-Point Conversions::  Details about formatting of
1535                                  floating-point numbers.
1536 * Other Output Conversions::    Details about formatting of strings,
1537                                  characters, pointers, and the like.
1538 * Formatted Output Functions::  Descriptions of the actual functions.
1539 * Dynamic Output::              Functions that allocate memory for the output.
1540 * Variable Arguments Output::   @code{vprintf} and friends.
1541 * Parsing a Template String::   What kinds of args does a given template
1542                                  call for?
1543 * Example of Parsing::          Sample program using @code{parse_printf_format}.
1544 @end menu
1546 @node Formatted Output Basics
1547 @subsection Formatted Output Basics
1549 The @code{printf} function can be used to print any number of arguments.
1550 The template string argument you supply in a call provides
1551 information not only about the number of additional arguments, but also
1552 about their types and what style should be used for printing them.
1554 Ordinary characters in the template string are simply written to the
1555 output stream as-is, while @dfn{conversion specifications} introduced by
1556 a @samp{%} character in the template cause subsequent arguments to be
1557 formatted and written to the output stream.  For example,
1558 @cindex conversion specifications (@code{printf})
1560 @smallexample
1561 int pct = 37;
1562 char filename[] = "foo.txt";
1563 printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
1564         filename, pct);
1565 @end smallexample
1567 @noindent
1568 produces output like
1570 @smallexample
1571 Processing of `foo.txt' is 37% finished.
1572 Please be patient.
1573 @end smallexample
1575 This example shows the use of the @samp{%d} conversion to specify that
1576 an @code{int} argument should be printed in decimal notation, the
1577 @samp{%s} conversion to specify printing of a string argument, and
1578 the @samp{%%} conversion to print a literal @samp{%} character.
1580 There are also conversions for printing an integer argument as an
1581 unsigned value in octal, decimal, or hexadecimal radix (@samp{%o},
1582 @samp{%u}, or @samp{%x}, respectively); or as a character value
1583 (@samp{%c}).
1585 Floating-point numbers can be printed in normal, fixed-point notation
1586 using the @samp{%f} conversion or in exponential notation using the
1587 @samp{%e} conversion.  The @samp{%g} conversion uses either @samp{%e}
1588 or @samp{%f} format, depending on what is more appropriate for the
1589 magnitude of the particular number.
1591 You can control formatting more precisely by writing @dfn{modifiers}
1592 between the @samp{%} and the character that indicates which conversion
1593 to apply.  These slightly alter the ordinary behavior of the conversion.
1594 For example, most conversion specifications permit you to specify a
1595 minimum field width and a flag indicating whether you want the result
1596 left- or right-justified within the field.
1598 The specific flags and modifiers that are permitted and their
1599 interpretation vary depending on the particular conversion.  They're all
1600 described in more detail in the following sections.  Don't worry if this
1601 all seems excessively complicated at first; you can almost always get
1602 reasonable free-format output without using any of the modifiers at all.
1603 The modifiers are mostly used to make the output look ``prettier'' in
1604 tables.
1606 @node Output Conversion Syntax
1607 @subsection Output Conversion Syntax
1609 This section provides details about the precise syntax of conversion
1610 specifications that can appear in a @code{printf} template
1611 string.
1613 Characters in the template string that are not part of a conversion
1614 specification are printed as-is to the output stream.  Multibyte
1615 character sequences (@pxref{Character Set Handling}) are permitted in a
1616 template string.
1618 The conversion specifications in a @code{printf} template string have
1619 the general form:
1621 @smallexample
1622 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion}
1623 @end smallexample
1625 @noindent
1628 @smallexample
1629 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} . @r{*} @r{[} @var{param-no} @r{$]} @var{type} @var{conversion}
1630 @end smallexample
1632 For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-}
1633 is a flag, @samp{10} specifies the field width, the precision is
1634 @samp{8}, the letter @samp{l} is a type modifier, and @samp{d} specifies
1635 the conversion style.  (This particular type specifier says to
1636 print a @code{long int} argument in decimal notation, with a minimum of
1637 8 digits left-justified in a field at least 10 characters wide.)
1639 In more detail, output conversion specifications consist of an
1640 initial @samp{%} character followed in sequence by:
1642 @itemize @bullet
1643 @item
1644 An optional specification of the parameter used for this format.
1645 Normally the parameters to the @code{printf} function are assigned to the
1646 formats in the order of appearance in the format string.  But in some
1647 situations (such as message translation) this is not desirable and this
1648 extension allows an explicit parameter to be specified.
1650 The @var{param-no} parts of the format must be integers in the range of
1651 1 to the maximum number of arguments present to the function call.  Some
1652 implementations limit this number to a certainly upper bound.  The exact
1653 limit can be retrieved by the following constant.
1655 @defvr Macro NL_ARGMAX
1656 The value of @code{NL_ARGMAX} is the maximum value allowed for the
1657 specification of an positional parameter in a @code{printf} call.  The
1658 actual value in effect at runtime can be retrieved by using
1659 @code{sysconf} using the @code{_SC_NL_ARGMAX} parameter @pxref{Sysconf
1660 Definition}.
1662 Some system have a quite low limit such as @math{9} for @w{System V}
1663 systems.  The GNU C library has no real limit.
1664 @end defvr
1666 If any of the formats has a specification for the parameter position all
1667 of them in the format string shall have one.  Otherwise the behavior is
1668 undefined.
1670 @item
1671 Zero or more @dfn{flag characters} that modify the normal behavior of
1672 the conversion specification.
1673 @cindex flag character (@code{printf})
1675 @item
1676 An optional decimal integer specifying the @dfn{minimum field width}.
1677 If the normal conversion produces fewer characters than this, the field
1678 is padded with spaces to the specified width.  This is a @emph{minimum}
1679 value; if the normal conversion produces more characters than this, the
1680 field is @emph{not} truncated.  Normally, the output is right-justified
1681 within the field.
1682 @cindex minimum field width (@code{printf})
1684 You can also specify a field width of @samp{*}.  This means that the
1685 next argument in the argument list (before the actual value to be
1686 printed) is used as the field width.  The value must be an @code{int}.
1687 If the value is negative, this means to set the @samp{-} flag (see
1688 below) and to use the absolute value as the field width.
1690 @item
1691 An optional @dfn{precision} to specify the number of digits to be
1692 written for the numeric conversions.  If the precision is specified, it
1693 consists of a period (@samp{.}) followed optionally by a decimal integer
1694 (which defaults to zero if omitted).
1695 @cindex precision (@code{printf})
1697 You can also specify a precision of @samp{*}.  This means that the next
1698 argument in the argument list (before the actual value to be printed) is
1699 used as the precision.  The value must be an @code{int}, and is ignored
1700 if it is negative.  If you specify @samp{*} for both the field width and
1701 precision, the field width argument precedes the precision argument.
1702 Other C library versions may not recognize this syntax.
1704 @item
1705 An optional @dfn{type modifier character}, which is used to specify the
1706 data type of the corresponding argument if it differs from the default
1707 type.  (For example, the integer conversions assume a type of @code{int},
1708 but you can specify @samp{h}, @samp{l}, or @samp{L} for other integer
1709 types.)
1710 @cindex type modifier character (@code{printf})
1712 @item
1713 A character that specifies the conversion to be applied.
1714 @end itemize
1716 The exact options that are permitted and how they are interpreted vary
1717 between the different conversion specifiers.  See the descriptions of the
1718 individual conversions for information about the particular options that
1719 they use.
1721 With the @samp{-Wformat} option, the GNU C compiler checks calls to
1722 @code{printf} and related functions.  It examines the format string and
1723 verifies that the correct number and types of arguments are supplied.
1724 There is also a GNU C syntax to tell the compiler that a function you
1725 write uses a @code{printf}-style format string.
1726 @xref{Function Attributes, , Declaring Attributes of Functions,
1727 gcc.info, Using GNU CC}, for more information.
1729 @node Table of Output Conversions
1730 @subsection Table of Output Conversions
1731 @cindex output conversions, for @code{printf}
1733 Here is a table summarizing what all the different conversions do:
1735 @table @asis
1736 @item @samp{%d}, @samp{%i}
1737 Print an integer as a signed decimal number.  @xref{Integer
1738 Conversions}, for details.  @samp{%d} and @samp{%i} are synonymous for
1739 output, but are different when used with @code{scanf} for input
1740 (@pxref{Table of Input Conversions}).
1742 @item @samp{%o}
1743 Print an integer as an unsigned octal number.  @xref{Integer
1744 Conversions}, for details.
1746 @item @samp{%u}
1747 Print an integer as an unsigned decimal number.  @xref{Integer
1748 Conversions}, for details.
1750 @item @samp{%x}, @samp{%X}
1751 Print an integer as an unsigned hexadecimal number.  @samp{%x} uses
1752 lower-case letters and @samp{%X} uses upper-case.  @xref{Integer
1753 Conversions}, for details.
1755 @item @samp{%f}
1756 Print a floating-point number in normal (fixed-point) notation.
1757 @xref{Floating-Point Conversions}, for details.
1759 @item @samp{%e}, @samp{%E}
1760 Print a floating-point number in exponential notation.  @samp{%e} uses
1761 lower-case letters and @samp{%E} uses upper-case.  @xref{Floating-Point
1762 Conversions}, for details.
1764 @item @samp{%g}, @samp{%G}
1765 Print a floating-point number in either normal or exponential notation,
1766 whichever is more appropriate for its magnitude.  @samp{%g} uses
1767 lower-case letters and @samp{%G} uses upper-case.  @xref{Floating-Point
1768 Conversions}, for details.
1770 @item @samp{%a}, @samp{%A}
1771 Print a floating-point number in a hexadecimal fractional notation which
1772 the exponent to base 2 represented in decimal digits.  @samp{%a} uses
1773 lower-case letters and @samp{%A} uses upper-case.  @xref{Floating-Point
1774 Conversions}, for details.
1776 @item @samp{%c}
1777 Print a single character.  @xref{Other Output Conversions}.
1779 @item @samp{%C}
1780 This is an alias for @samp{%lc} which is supported for compatibility
1781 with the Unix standard.
1783 @item @samp{%s}
1784 Print a string.  @xref{Other Output Conversions}.
1786 @item @samp{%S}
1787 This is an alias for @samp{%ls} which is supported for compatibility
1788 with the Unix standard.
1790 @item @samp{%p}
1791 Print the value of a pointer.  @xref{Other Output Conversions}.
1793 @item @samp{%n}
1794 Get the number of characters printed so far.  @xref{Other Output Conversions}.
1795 Note that this conversion specification never produces any output.
1797 @item @samp{%m}
1798 Print the string corresponding to the value of @code{errno}.
1799 (This is a GNU extension.)
1800 @xref{Other Output Conversions}.
1802 @item @samp{%%}
1803 Print a literal @samp{%} character.  @xref{Other Output Conversions}.
1804 @end table
1806 If the syntax of a conversion specification is invalid, unpredictable
1807 things will happen, so don't do this.  If there aren't enough function
1808 arguments provided to supply values for all the conversion
1809 specifications in the template string, or if the arguments are not of
1810 the correct types, the results are unpredictable.  If you supply more
1811 arguments than conversion specifications, the extra argument values are
1812 simply ignored; this is sometimes useful.
1814 @node Integer Conversions
1815 @subsection Integer Conversions
1817 This section describes the options for the @samp{%d}, @samp{%i},
1818 @samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
1819 specifications.  These conversions print integers in various formats.
1821 The @samp{%d} and @samp{%i} conversion specifications both print an
1822 @code{int} argument as a signed decimal number; while @samp{%o},
1823 @samp{%u}, and @samp{%x} print the argument as an unsigned octal,
1824 decimal, or hexadecimal number (respectively).  The @samp{%X} conversion
1825 specification is just like @samp{%x} except that it uses the characters
1826 @samp{ABCDEF} as digits instead of @samp{abcdef}.
1828 The following flags are meaningful:
1830 @table @asis
1831 @item @samp{-}
1832 Left-justify the result in the field (instead of the normal
1833 right-justification).
1835 @item @samp{+}
1836 For the signed @samp{%d} and @samp{%i} conversions, print a
1837 plus sign if the value is positive.
1839 @item @samp{ }
1840 For the signed @samp{%d} and @samp{%i} conversions, if the result
1841 doesn't start with a plus or minus sign, prefix it with a space
1842 character instead.  Since the @samp{+} flag ensures that the result
1843 includes a sign, this flag is ignored if you supply both of them.
1845 @item @samp{#}
1846 For the @samp{%o} conversion, this forces the leading digit to be
1847 @samp{0}, as if by increasing the precision.  For @samp{%x} or
1848 @samp{%X}, this prefixes a leading @samp{0x} or @samp{0X} (respectively)
1849 to the result.  This doesn't do anything useful for the @samp{%d},
1850 @samp{%i}, or @samp{%u} conversions.  Using this flag produces output
1851 which can be parsed by the @code{strtoul} function (@pxref{Parsing of
1852 Integers}) and @code{scanf} with the @samp{%i} conversion
1853 (@pxref{Numeric Input Conversions}).
1855 @item @samp{'}
1856 Separate the digits into groups as specified by the locale specified for
1857 the @code{LC_NUMERIC} category; @pxref{General Numeric}.  This flag is a
1858 GNU extension.
1860 @item @samp{0}
1861 Pad the field with zeros instead of spaces.  The zeros are placed after
1862 any indication of sign or base.  This flag is ignored if the @samp{-}
1863 flag is also specified, or if a precision is specified.
1864 @end table
1866 If a precision is supplied, it specifies the minimum number of digits to
1867 appear; leading zeros are produced if necessary.  If you don't specify a
1868 precision, the number is printed with as many digits as it needs.  If
1869 you convert a value of zero with an explicit precision of zero, then no
1870 characters at all are produced.
1872 Without a type modifier, the corresponding argument is treated as an
1873 @code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
1874 @code{unsigned int} (for the unsigned conversions @samp{%o}, @samp{%u},
1875 @samp{%x}, and @samp{%X}).  Recall that since @code{printf} and friends
1876 are variadic, any @code{char} and @code{short} arguments are
1877 automatically converted to @code{int} by the default argument
1878 promotions.  For arguments of other integer types, you can use these
1879 modifiers:
1881 @table @samp
1882 @item hh
1883 Specifies that the argument is a @code{signed char} or @code{unsigned
1884 char}, as appropriate.  A @code{char} argument is converted to an
1885 @code{int} or @code{unsigned int} by the default argument promotions
1886 anyway, but the @samp{h} modifier says to convert it back to a
1887 @code{char} again.
1889 This modifier was introduced in @w{ISO C99}.
1891 @item h
1892 Specifies that the argument is a @code{short int} or @code{unsigned
1893 short int}, as appropriate.  A @code{short} argument is converted to an
1894 @code{int} or @code{unsigned int} by the default argument promotions
1895 anyway, but the @samp{h} modifier says to convert it back to a
1896 @code{short} again.
1898 @item j
1899 Specifies that the argument is a @code{intmax_t} or @code{uintmax_t}, as
1900 appropriate.
1902 This modifier was introduced in @w{ISO C99}.
1904 @item l
1905 Specifies that the argument is a @code{long int} or @code{unsigned long
1906 int}, as appropriate.  Two @samp{l} characters is like the @samp{L}
1907 modifier, below.
1909 If used with @samp{%c} or @samp{%s} the corresponding parameter is
1910 considered as a wide character or wide character string respectively.
1911 This use of @samp{l} was introduced in @w{Amendment 1} to @w{ISO C90}.
1913 @item L
1914 @itemx ll
1915 @itemx q
1916 Specifies that the argument is a @code{long long int}.  (This type is
1917 an extension supported by the GNU C compiler.  On systems that don't
1918 support extra-long integers, this is the same as @code{long int}.)
1920 The @samp{q} modifier is another name for the same thing, which comes
1921 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
1922 @code{int}.
1924 @item t
1925 Specifies that the argument is a @code{ptrdiff_t}.
1927 This modifier was introduced in @w{ISO C99}.
1929 @item z
1930 @itemx Z
1931 Specifies that the argument is a @code{size_t}.
1933 @samp{z} was introduced in @w{ISO C99}.  @samp{Z} is a GNU extension
1934 predating this addition and should not be used in new code.
1935 @end table
1937 Here is an example.  Using the template string:
1939 @smallexample
1940 "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
1941 @end smallexample
1943 @noindent
1944 to print numbers using the different options for the @samp{%d}
1945 conversion gives results like:
1947 @smallexample
1948 |    0|0    |   +0|+0   |    0|00000|     |   00|0|
1949 |    1|1    |   +1|+1   |    1|00001|    1|   01|1|
1950 |   -1|-1   |   -1|-1   |   -1|-0001|   -1|  -01|-1|
1951 |100000|100000|+100000|+100000| 100000|100000|100000|100000|100000|
1952 @end smallexample
1954 In particular, notice what happens in the last case where the number
1955 is too large to fit in the minimum field width specified.
1957 Here are some more examples showing how unsigned integers print under
1958 various format options, using the template string:
1960 @smallexample
1961 "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
1962 @end smallexample
1964 @smallexample
1965 |    0|    0|    0|    0|    0|    0|    0|  00000000|
1966 |    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
1967 |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
1968 @end smallexample
1971 @node Floating-Point Conversions
1972 @subsection Floating-Point Conversions
1974 This section discusses the conversion specifications for floating-point
1975 numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G}
1976 conversions.
1978 The @samp{%f} conversion prints its argument in fixed-point notation,
1979 producing output of the form
1980 @w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
1981 where the number of digits following the decimal point is controlled
1982 by the precision you specify.
1984 The @samp{%e} conversion prints its argument in exponential notation,
1985 producing output of the form
1986 @w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}.
1987 Again, the number of digits following the decimal point is controlled by
1988 the precision.  The exponent always contains at least two digits.  The
1989 @samp{%E} conversion is similar but the exponent is marked with the letter
1990 @samp{E} instead of @samp{e}.
1992 The @samp{%g} and @samp{%G} conversions print the argument in the style
1993 of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
1994 than -4 or greater than or equal to the precision; otherwise they use
1995 the @samp{%f} style.  A precision of @code{0}, is taken as 1.
1996 Trailing zeros are removed from the fractional portion of the result and
1997 a decimal-point character appears only if it is followed by a digit.
1999 The @samp{%a} and @samp{%A} conversions are meant for representing
2000 floating-point numbers exactly in textual form so that they can be
2001 exchanged as texts between different programs and/or machines.  The
2002 numbers are represented is the form
2003 @w{[@code{-}]@code{0x}@var{h}@code{.}@var{hhh}@code{p}[@code{+}|@code{-}]@var{dd}}.
2004 At the left of the decimal-point character exactly one digit is print.
2005 This character is only @code{0} if the number is denormalized.
2006 Otherwise the value is unspecified; it is implementation dependent how many
2007 bits are used.  The number of hexadecimal digits on the right side of
2008 the decimal-point character is equal to the precision.  If the precision
2009 is zero it is determined to be large enough to provide an exact
2010 representation of the number (or it is large enough to distinguish two
2011 adjacent values if the @code{FLT_RADIX} is not a power of 2,
2012 @pxref{Floating Point Parameters}).  For the @samp{%a} conversion
2013 lower-case characters are used to represent the hexadecimal number and
2014 the prefix and exponent sign are printed as @code{0x} and @code{p}
2015 respectively.  Otherwise upper-case characters are used and @code{0X}
2016 and @code{P} are used for the representation of prefix and exponent
2017 string.  The exponent to the base of two is printed as a decimal number
2018 using at least one digit but at most as many digits as necessary to
2019 represent the value exactly.
2021 If the value to be printed represents infinity or a NaN, the output is
2022 @w{[@code{-}]@code{inf}} or @code{nan} respectively if the conversion
2023 specifier is @samp{%a}, @samp{%e}, @samp{%f}, or @samp{%g} and it is
2024 @w{[@code{-}]@code{INF}} or @code{NAN} respectively if the conversion is
2025 @samp{%A}, @samp{%E}, or @samp{%G}.
2027 The following flags can be used to modify the behavior:
2029 @comment We use @asis instead of @samp so we can have ` ' as an item.
2030 @table @asis
2031 @item @samp{-}
2032 Left-justify the result in the field.  Normally the result is
2033 right-justified.
2035 @item @samp{+}
2036 Always include a plus or minus sign in the result.
2038 @item @samp{ }
2039 If the result doesn't start with a plus or minus sign, prefix it with a
2040 space instead.  Since the @samp{+} flag ensures that the result includes
2041 a sign, this flag is ignored if you supply both of them.
2043 @item @samp{#}
2044 Specifies that the result should always include a decimal point, even
2045 if no digits follow it.  For the @samp{%g} and @samp{%G} conversions,
2046 this also forces trailing zeros after the decimal point to be left
2047 in place where they would otherwise be removed.
2049 @item @samp{'}
2050 Separate the digits of the integer part of the result into groups as
2051 specified by the locale specified for the @code{LC_NUMERIC} category;
2052 @pxref{General Numeric}.  This flag is a GNU extension.
2054 @item @samp{0}
2055 Pad the field with zeros instead of spaces; the zeros are placed
2056 after any sign.  This flag is ignored if the @samp{-} flag is also
2057 specified.
2058 @end table
2060 The precision specifies how many digits follow the decimal-point
2061 character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions.  For
2062 these conversions, the default precision is @code{6}.  If the precision
2063 is explicitly @code{0}, this suppresses the decimal point character
2064 entirely.  For the @samp{%g} and @samp{%G} conversions, the precision
2065 specifies how many significant digits to print.  Significant digits are
2066 the first digit before the decimal point, and all the digits after it.
2067 If the precision is @code{0} or not specified for @samp{%g} or @samp{%G},
2068 it is treated like a value of @code{1}.  If the value being printed
2069 cannot be expressed accurately in the specified number of digits, the
2070 value is rounded to the nearest number that fits.
2072 Without a type modifier, the floating-point conversions use an argument
2073 of type @code{double}.  (By the default argument promotions, any
2074 @code{float} arguments are automatically converted to @code{double}.)
2075 The following type modifier is supported:
2077 @table @samp
2078 @item L
2079 An uppercase @samp{L} specifies that the argument is a @code{long
2080 double}.
2081 @end table
2083 Here are some examples showing how numbers print using the various
2084 floating-point conversions.  All of the numbers were printed using
2085 this template string:
2087 @smallexample
2088 "|%13.4a|%13.4f|%13.4e|%13.4g|\n"
2089 @end smallexample
2091 Here is the output:
2093 @smallexample
2094 |  0x0.0000p+0|       0.0000|   0.0000e+00|            0|
2095 |  0x1.0000p-1|       0.5000|   5.0000e-01|          0.5|
2096 |  0x1.0000p+0|       1.0000|   1.0000e+00|            1|
2097 | -0x1.0000p+0|      -1.0000|  -1.0000e+00|           -1|
2098 |  0x1.9000p+6|     100.0000|   1.0000e+02|          100|
2099 |  0x1.f400p+9|    1000.0000|   1.0000e+03|         1000|
2100 | 0x1.3880p+13|   10000.0000|   1.0000e+04|        1e+04|
2101 | 0x1.81c8p+13|   12345.0000|   1.2345e+04|    1.234e+04|
2102 | 0x1.86a0p+16|  100000.0000|   1.0000e+05|        1e+05|
2103 | 0x1.e240p+16|  123456.0000|   1.2346e+05|    1.235e+05|
2104 @end smallexample
2106 Notice how the @samp{%g} conversion drops trailing zeros.
2108 @node Other Output Conversions
2109 @subsection Other Output Conversions
2111 This section describes miscellaneous conversions for @code{printf}.
2113 The @samp{%c} conversion prints a single character.  In case there is no
2114 @samp{l} modifier the @code{int} argument is first converted to an
2115 @code{unsigned char}.  Then, if used in a wide stream function, the
2116 character is converted into the corresponding wide character.  The
2117 @samp{-} flag can be used to specify left-justification in the field,
2118 but no other flags are defined, and no precision or type modifier can be
2119 given.  For example:
2121 @smallexample
2122 printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
2123 @end smallexample
2125 @noindent
2126 prints @samp{hello}.
2128 If there is a @samp{l} modifier present the argument is expected to be
2129 of type @code{wint_t}.  If used in a multibyte function the wide
2130 character is converted into a multibyte character before being added to
2131 the output.  In this case more than one output byte can be produced.
2133 The @samp{%s} conversion prints a string.  If no @samp{l} modifier is
2134 present the corresponding argument must be of type @code{char *} (or
2135 @code{const char *}).  If used in a wide stream function the string is
2136 first converted in a wide character string.  A precision can be
2137 specified to indicate the maximum number of characters to write;
2138 otherwise characters in the string up to but not including the
2139 terminating null character are written to the output stream.  The
2140 @samp{-} flag can be used to specify left-justification in the field,
2141 but no other flags or type modifiers are defined for this conversion.
2142 For example:
2144 @smallexample
2145 printf ("%3s%-6s", "no", "where");
2146 @end smallexample
2148 @noindent
2149 prints @samp{ nowhere }.
2151 If there is a @samp{l} modifier present the argument is expected to be of type @code{wchar_t} (or @code{const wchar_t *}).
2153 If you accidentally pass a null pointer as the argument for a @samp{%s}
2154 conversion, the GNU library prints it as @samp{(null)}.  We think this
2155 is more useful than crashing.  But it's not good practice to pass a null
2156 argument intentionally.
2158 The @samp{%m} conversion prints the string corresponding to the error
2159 code in @code{errno}.  @xref{Error Messages}.  Thus:
2161 @smallexample
2162 fprintf (stderr, "can't open `%s': %m\n", filename);
2163 @end smallexample
2165 @noindent
2166 is equivalent to:
2168 @smallexample
2169 fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
2170 @end smallexample
2172 @noindent
2173 The @samp{%m} conversion is a GNU C library extension.
2175 The @samp{%p} conversion prints a pointer value.  The corresponding
2176 argument must be of type @code{void *}.  In practice, you can use any
2177 type of pointer.
2179 In the GNU system, non-null pointers are printed as unsigned integers,
2180 as if a @samp{%#x} conversion were used.  Null pointers print as
2181 @samp{(nil)}.  (Pointers might print differently in other systems.)
2183 For example:
2185 @smallexample
2186 printf ("%p", "testing");
2187 @end smallexample
2189 @noindent
2190 prints @samp{0x} followed by a hexadecimal number---the address of the
2191 string constant @code{"testing"}.  It does not print the word
2192 @samp{testing}.
2194 You can supply the @samp{-} flag with the @samp{%p} conversion to
2195 specify left-justification, but no other flags, precision, or type
2196 modifiers are defined.
2198 The @samp{%n} conversion is unlike any of the other output conversions.
2199 It uses an argument which must be a pointer to an @code{int}, but
2200 instead of printing anything it stores the number of characters printed
2201 so far by this call at that location.  The @samp{h} and @samp{l} type
2202 modifiers are permitted to specify that the argument is of type
2203 @code{short int *} or @code{long int *} instead of @code{int *}, but no
2204 flags, field width, or precision are permitted.
2206 For example,
2208 @smallexample
2209 int nchar;
2210 printf ("%d %s%n\n", 3, "bears", &nchar);
2211 @end smallexample
2213 @noindent
2214 prints:
2216 @smallexample
2217 3 bears
2218 @end smallexample
2220 @noindent
2221 and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven
2222 characters.
2225 The @samp{%%} conversion prints a literal @samp{%} character.  This
2226 conversion doesn't use an argument, and no flags, field width,
2227 precision, or type modifiers are permitted.
2230 @node Formatted Output Functions
2231 @subsection Formatted Output Functions
2233 This section describes how to call @code{printf} and related functions.
2234 Prototypes for these functions are in the header file @file{stdio.h}.
2235 Because these functions take a variable number of arguments, you
2236 @emph{must} declare prototypes for them before using them.  Of course,
2237 the easiest way to make sure you have all the right prototypes is to
2238 just include @file{stdio.h}.
2239 @pindex stdio.h
2241 @comment stdio.h
2242 @comment ISO
2243 @deftypefun int printf (const char *@var{template}, @dots{})
2244 The @code{printf} function prints the optional arguments under the
2245 control of the template string @var{template} to the stream
2246 @code{stdout}.  It returns the number of characters printed, or a
2247 negative value if there was an output error.
2248 @end deftypefun
2250 @comment wchar.h
2251 @comment ISO
2252 @deftypefun int wprintf (const wchar_t *@var{template}, @dots{})
2253 The @code{wprintf} function prints the optional arguments under the
2254 control of the wide template string @var{template} to the stream
2255 @code{stdout}.  It returns the number of wide characters printed, or a
2256 negative value if there was an output error.
2257 @end deftypefun
2259 @comment stdio.h
2260 @comment ISO
2261 @deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
2262 This function is just like @code{printf}, except that the output is
2263 written to the stream @var{stream} instead of @code{stdout}.
2264 @end deftypefun
2266 @comment wchar.h
2267 @comment ISO
2268 @deftypefun int fwprintf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
2269 This function is just like @code{wprintf}, except that the output is
2270 written to the stream @var{stream} instead of @code{stdout}.
2271 @end deftypefun
2273 @comment stdio.h
2274 @comment ISO
2275 @deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
2276 This is like @code{printf}, except that the output is stored in the character
2277 array @var{s} instead of written to a stream.  A null character is written
2278 to mark the end of the string.
2280 The @code{sprintf} function returns the number of characters stored in
2281 the array @var{s}, not including the terminating null character.
2283 The behavior of this function is undefined if copying takes place
2284 between objects that overlap---for example, if @var{s} is also given
2285 as an argument to be printed under control of the @samp{%s} conversion.
2286 @xref{Copying and Concatenation}.
2288 @strong{Warning:} The @code{sprintf} function can be @strong{dangerous}
2289 because it can potentially output more characters than can fit in the
2290 allocation size of the string @var{s}.  Remember that the field width
2291 given in a conversion specification is only a @emph{minimum} value.
2293 To avoid this problem, you can use @code{snprintf} or @code{asprintf},
2294 described below.
2295 @end deftypefun
2297 @comment wchar.h
2298 @comment GNU
2299 @deftypefun int swprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, @dots{})
2300 This is like @code{wprintf}, except that the output is stored in the
2301 wide character array @var{ws} instead of written to a stream.  A null
2302 wide character is written to mark the end of the string.  The @var{size}
2303 argument specifies the maximum number of characters to produce.  The
2304 trailing null character is counted towards this limit, so you should
2305 allocate at least @var{size} wide characters for the string @var{ws}.
2307 The return value is the number of characters generated for the given
2308 input, excluding the trailing null.  If not all output fits into the
2309 provided buffer a negative value is returned.  You should try again with
2310 a bigger output string.  @emph{Note:} this is different from how
2311 @code{snprintf} handles this situation.
2313 Note that the corresponding narrow stream function takes fewer
2314 parameters.  @code{swprintf} in fact corresponds to the @code{snprintf}
2315 function.  Since the @code{sprintf} function can be dangerous and should
2316 be avoided the @w{ISO C} committee refused to make the same mistake
2317 again and decided to not define an function exactly corresponding to
2318 @code{sprintf}.
2319 @end deftypefun
2321 @comment stdio.h
2322 @comment GNU
2323 @deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{})
2324 The @code{snprintf} function is similar to @code{sprintf}, except that
2325 the @var{size} argument specifies the maximum number of characters to
2326 produce.  The trailing null character is counted towards this limit, so
2327 you should allocate at least @var{size} characters for the string @var{s}.
2329 The return value is the number of characters which would be generated
2330 for the given input, excluding the trailing null.  If this value is
2331 greater or equal to @var{size}, not all characters from the result have
2332 been stored in @var{s}.  You should try again with a bigger output
2333 string.  Here is an example of doing this:
2335 @smallexample
2336 @group
2337 /* @r{Construct a message describing the value of a variable}
2338    @r{whose name is @var{name} and whose value is @var{value}.} */
2339 char *
2340 make_message (char *name, char *value)
2342   /* @r{Guess we need no more than 100 chars of space.} */
2343   int size = 100;
2344   char *buffer = (char *) xmalloc (size);
2345   int nchars;
2346 @end group
2347 @group
2348   if (buffer == NULL)
2349     return NULL;
2351  /* @r{Try to print in the allocated space.} */
2352   nchars = snprintf (buffer, size, "value of %s is %s",
2353                      name, value);
2354 @end group
2355 @group
2356   if (nchars >= size)
2357     @{
2358       /* @r{Reallocate buffer now that we know
2359          how much space is needed.} */
2360       size = nchars + 1;
2361       buffer = (char *) xrealloc (buffer, size);
2363       if (buffer != NULL)
2364         /* @r{Try again.} */
2365         snprintf (buffer, size, "value of %s is %s",
2366                   name, value);
2367     @}
2368   /* @r{The last call worked, return the string.} */
2369   return buffer;
2371 @end group
2372 @end smallexample
2374 In practice, it is often easier just to use @code{asprintf}, below.
2376 @strong{Attention:} In versions of the GNU C library prior to 2.1 the
2377 return value is the number of characters stored, not including the
2378 terminating null; unless there was not enough space in @var{s} to
2379 store the result in which case @code{-1} is returned.  This was
2380 changed in order to comply with the @w{ISO C99} standard.
2381 @end deftypefun
2383 @node Dynamic Output
2384 @subsection Dynamically Allocating Formatted Output
2386 The functions in this section do formatted output and place the results
2387 in dynamically allocated memory.
2389 @comment stdio.h
2390 @comment GNU
2391 @deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
2392 This function is similar to @code{sprintf}, except that it dynamically
2393 allocates a string (as with @code{malloc}; @pxref{Unconstrained
2394 Allocation}) to hold the output, instead of putting the output in a
2395 buffer you allocate in advance.  The @var{ptr} argument should be the
2396 address of a @code{char *} object, and a successful call to
2397 @code{asprintf} stores a pointer to the newly allocated string at that
2398 location.
2400 The return value is the number of characters allocated for the buffer, or
2401 less than zero if an error occurred. Usually this means that the buffer
2402 could not be allocated.
2404 Here is how to use @code{asprintf} to get the same result as the
2405 @code{snprintf} example, but more easily:
2407 @smallexample
2408 /* @r{Construct a message describing the value of a variable}
2409    @r{whose name is @var{name} and whose value is @var{value}.} */
2410 char *
2411 make_message (char *name, char *value)
2413   char *result;
2414   if (asprintf (&result, "value of %s is %s", name, value) < 0)
2415     return NULL;
2416   return result;
2418 @end smallexample
2419 @end deftypefun
2421 @comment stdio.h
2422 @comment GNU
2423 @deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
2424 This function is similar to @code{asprintf}, except that it uses the
2425 obstack @var{obstack} to allocate the space.  @xref{Obstacks}.
2427 The characters are written onto the end of the current object.
2428 To get at them, you must finish the object with @code{obstack_finish}
2429 (@pxref{Growing Objects}).@refill
2430 @end deftypefun
2432 @node Variable Arguments Output
2433 @subsection Variable Arguments Output Functions
2435 The functions @code{vprintf} and friends are provided so that you can
2436 define your own variadic @code{printf}-like functions that make use of
2437 the same internals as the built-in formatted output functions.
2439 The most natural way to define such functions would be to use a language
2440 construct to say, ``Call @code{printf} and pass this template plus all
2441 of my arguments after the first five.''  But there is no way to do this
2442 in C, and it would be hard to provide a way, since at the C language
2443 level there is no way to tell how many arguments your function received.
2445 Since that method is impossible, we provide alternative functions, the
2446 @code{vprintf} series, which lets you pass a @code{va_list} to describe
2447 ``all of my arguments after the first five.''
2449 When it is sufficient to define a macro rather than a real function,
2450 the GNU C compiler provides a way to do this much more easily with macros.
2451 For example:
2453 @smallexample
2454 #define myprintf(a, b, c, d, e, rest...) \
2455             printf (mytemplate , ## rest)
2456 @end smallexample
2458 @noindent
2459 @xref{Variadic Macros,,, cpp, The C preprocessor}, for details.
2460 But this is limited to macros, and does not apply to real functions at all.
2462 Before calling @code{vprintf} or the other functions listed in this
2463 section, you @emph{must} call @code{va_start} (@pxref{Variadic
2464 Functions}) to initialize a pointer to the variable arguments.  Then you
2465 can call @code{va_arg} to fetch the arguments that you want to handle
2466 yourself.  This advances the pointer past those arguments.
2468 Once your @code{va_list} pointer is pointing at the argument of your
2469 choice, you are ready to call @code{vprintf}.  That argument and all
2470 subsequent arguments that were passed to your function are used by
2471 @code{vprintf} along with the template that you specified separately.
2473 In some other systems, the @code{va_list} pointer may become invalid
2474 after the call to @code{vprintf}, so you must not use @code{va_arg}
2475 after you call @code{vprintf}.  Instead, you should call @code{va_end}
2476 to retire the pointer from service.  However, you can safely call
2477 @code{va_start} on another pointer variable and begin fetching the
2478 arguments again through that pointer.  Calling @code{vprintf} does not
2479 destroy the argument list of your function, merely the particular
2480 pointer that you passed to it.
2482 GNU C does not have such restrictions.  You can safely continue to fetch
2483 arguments from a @code{va_list} pointer after passing it to
2484 @code{vprintf}, and @code{va_end} is a no-op.  (Note, however, that
2485 subsequent @code{va_arg} calls will fetch the same arguments which
2486 @code{vprintf} previously used.)
2488 Prototypes for these functions are declared in @file{stdio.h}.
2489 @pindex stdio.h
2491 @comment stdio.h
2492 @comment ISO
2493 @deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
2494 This function is similar to @code{printf} except that, instead of taking
2495 a variable number of arguments directly, it takes an argument list
2496 pointer @var{ap}.
2497 @end deftypefun
2499 @comment wchar.h
2500 @comment ISO
2501 @deftypefun int vwprintf (const wchar_t *@var{template}, va_list @var{ap})
2502 This function is similar to @code{wprintf} except that, instead of taking
2503 a variable number of arguments directly, it takes an argument list
2504 pointer @var{ap}.
2505 @end deftypefun
2507 @comment stdio.h
2508 @comment ISO
2509 @deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
2510 This is the equivalent of @code{fprintf} with the variable argument list
2511 specified directly as for @code{vprintf}.
2512 @end deftypefun
2514 @comment wchar.h
2515 @comment ISO
2516 @deftypefun int vfwprintf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
2517 This is the equivalent of @code{fwprintf} with the variable argument list
2518 specified directly as for @code{vwprintf}.
2519 @end deftypefun
2521 @comment stdio.h
2522 @comment ISO
2523 @deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
2524 This is the equivalent of @code{sprintf} with the variable argument list
2525 specified directly as for @code{vprintf}.
2526 @end deftypefun
2528 @comment wchar.h
2529 @comment GNU
2530 @deftypefun int vswprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap})
2531 This is the equivalent of @code{swprintf} with the variable argument list
2532 specified directly as for @code{vwprintf}.
2533 @end deftypefun
2535 @comment stdio.h
2536 @comment GNU
2537 @deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
2538 This is the equivalent of @code{snprintf} with the variable argument list
2539 specified directly as for @code{vprintf}.
2540 @end deftypefun
2542 @comment stdio.h
2543 @comment GNU
2544 @deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
2545 The @code{vasprintf} function is the equivalent of @code{asprintf} with the
2546 variable argument list specified directly as for @code{vprintf}.
2547 @end deftypefun
2549 @comment stdio.h
2550 @comment GNU
2551 @deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
2552 The @code{obstack_vprintf} function is the equivalent of
2553 @code{obstack_printf} with the variable argument list specified directly
2554 as for @code{vprintf}.@refill
2555 @end deftypefun
2557 Here's an example showing how you might use @code{vfprintf}.  This is a
2558 function that prints error messages to the stream @code{stderr}, along
2559 with a prefix indicating the name of the program
2560 (@pxref{Error Messages}, for a description of
2561 @code{program_invocation_short_name}).
2563 @smallexample
2564 @group
2565 #include <stdio.h>
2566 #include <stdarg.h>
2568 void
2569 eprintf (const char *template, ...)
2571   va_list ap;
2572   extern char *program_invocation_short_name;
2574   fprintf (stderr, "%s: ", program_invocation_short_name);
2575   va_start (ap, template);
2576   vfprintf (stderr, template, ap);
2577   va_end (ap);
2579 @end group
2580 @end smallexample
2582 @noindent
2583 You could call @code{eprintf} like this:
2585 @smallexample
2586 eprintf ("file `%s' does not exist\n", filename);
2587 @end smallexample
2589 In GNU C, there is a special construct you can use to let the compiler
2590 know that a function uses a @code{printf}-style format string.  Then it
2591 can check the number and types of arguments in each call to the
2592 function, and warn you when they do not match the format string.
2593 For example, take this declaration of @code{eprintf}:
2595 @smallexample
2596 void eprintf (const char *template, ...)
2597         __attribute__ ((format (printf, 1, 2)));
2598 @end smallexample
2600 @noindent
2601 This tells the compiler that @code{eprintf} uses a format string like
2602 @code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input});
2603 the format string appears as the first argument;
2604 and the arguments to satisfy the format begin with the second.
2605 @xref{Function Attributes, , Declaring Attributes of Functions,
2606 gcc.info, Using GNU CC}, for more information.
2608 @node Parsing a Template String
2609 @subsection Parsing a Template String
2610 @cindex parsing a template string
2612 You can use the function @code{parse_printf_format} to obtain
2613 information about the number and types of arguments that are expected by
2614 a given template string.  This function permits interpreters that
2615 provide interfaces to @code{printf} to avoid passing along invalid
2616 arguments from the user's program, which could cause a crash.
2618 All the symbols described in this section are declared in the header
2619 file @file{printf.h}.
2621 @comment printf.h
2622 @comment GNU
2623 @deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
2624 This function returns information about the number and types of
2625 arguments expected by the @code{printf} template string @var{template}.
2626 The information is stored in the array @var{argtypes}; each element of
2627 this array describes one argument.  This information is encoded using
2628 the various @samp{PA_} macros, listed below.
2630 The argument @var{n} specifies the number of elements in the array
2631 @var{argtypes}.  This is the maximum number of elements that
2632 @code{parse_printf_format} will try to write.
2634 @code{parse_printf_format} returns the total number of arguments required
2635 by @var{template}.  If this number is greater than @var{n}, then the
2636 information returned describes only the first @var{n} arguments.  If you
2637 want information about additional arguments, allocate a bigger
2638 array and call @code{parse_printf_format} again.
2639 @end deftypefun
2641 The argument types are encoded as a combination of a basic type and
2642 modifier flag bits.
2644 @comment printf.h
2645 @comment GNU
2646 @deftypevr Macro int PA_FLAG_MASK
2647 This macro is a bitmask for the type modifier flag bits.  You can write
2648 the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the
2649 flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to
2650 extract just the basic type code.
2651 @end deftypevr
2653 Here are symbolic constants that represent the basic types; they stand
2654 for integer values.
2656 @vtable @code
2657 @comment printf.h
2658 @comment GNU
2659 @item PA_INT
2660 This specifies that the base type is @code{int}.
2662 @comment printf.h
2663 @comment GNU
2664 @item PA_CHAR
2665 This specifies that the base type is @code{int}, cast to @code{char}.
2667 @comment printf.h
2668 @comment GNU
2669 @item PA_STRING
2670 This specifies that the base type is @code{char *}, a null-terminated string.
2672 @comment printf.h
2673 @comment GNU
2674 @item PA_POINTER
2675 This specifies that the base type is @code{void *}, an arbitrary pointer.
2677 @comment printf.h
2678 @comment GNU
2679 @item PA_FLOAT
2680 This specifies that the base type is @code{float}.
2682 @comment printf.h
2683 @comment GNU
2684 @item PA_DOUBLE
2685 This specifies that the base type is @code{double}.
2687 @comment printf.h
2688 @comment GNU
2689 @item PA_LAST
2690 You can define additional base types for your own programs as offsets
2691 from @code{PA_LAST}.  For example, if you have data types @samp{foo}
2692 and @samp{bar} with their own specialized @code{printf} conversions,
2693 you could define encodings for these types as:
2695 @smallexample
2696 #define PA_FOO  PA_LAST
2697 #define PA_BAR  (PA_LAST + 1)
2698 @end smallexample
2699 @end vtable
2701 Here are the flag bits that modify a basic type.  They are combined with
2702 the code for the basic type using inclusive-or.
2704 @vtable @code
2705 @comment printf.h
2706 @comment GNU
2707 @item PA_FLAG_PTR
2708 If this bit is set, it indicates that the encoded type is a pointer to
2709 the base type, rather than an immediate value.
2710 For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.
2712 @comment printf.h
2713 @comment GNU
2714 @item PA_FLAG_SHORT
2715 If this bit is set, it indicates that the base type is modified with
2716 @code{short}.  (This corresponds to the @samp{h} type modifier.)
2718 @comment printf.h
2719 @comment GNU
2720 @item PA_FLAG_LONG
2721 If this bit is set, it indicates that the base type is modified with
2722 @code{long}.  (This corresponds to the @samp{l} type modifier.)
2724 @comment printf.h
2725 @comment GNU
2726 @item PA_FLAG_LONG_LONG
2727 If this bit is set, it indicates that the base type is modified with
2728 @code{long long}.  (This corresponds to the @samp{L} type modifier.)
2730 @comment printf.h
2731 @comment GNU
2732 @item PA_FLAG_LONG_DOUBLE
2733 This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with
2734 a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
2735 @end vtable
2737 @ifinfo
2738 For an example of using these facilities, see @ref{Example of Parsing}.
2739 @end ifinfo
2741 @node Example of Parsing
2742 @subsection Example of Parsing a Template String
2744 Here is an example of decoding argument types for a format string.  We
2745 assume this is part of an interpreter which contains arguments of type
2746 @code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
2747 perhaps others which are not valid here).
2749 @smallexample
2750 /* @r{Test whether the @var{nargs} specified objects}
2751    @r{in the vector @var{args} are valid}
2752    @r{for the format string @var{format}:}
2753    @r{if so, return 1.}
2754    @r{If not, return 0 after printing an error message.}  */
2757 validate_args (char *format, int nargs, OBJECT *args)
2759   int *argtypes;
2760   int nwanted;
2762   /* @r{Get the information about the arguments.}
2763      @r{Each conversion specification must be at least two characters}
2764      @r{long, so there cannot be more specifications than half the}
2765      @r{length of the string.}  */
2767   argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
2768   nwanted = parse_printf_format (string, nelts, argtypes);
2770   /* @r{Check the number of arguments.}  */
2771   if (nwanted > nargs)
2772     @{
2773       error ("too few arguments (at least %d required)", nwanted);
2774       return 0;
2775     @}
2777   /* @r{Check the C type wanted for each argument}
2778      @r{and see if the object given is suitable.}  */
2779   for (i = 0; i < nwanted; i++)
2780     @{
2781       int wanted;
2783       if (argtypes[i] & PA_FLAG_PTR)
2784         wanted = STRUCTURE;
2785       else
2786         switch (argtypes[i] & ~PA_FLAG_MASK)
2787           @{
2788           case PA_INT:
2789           case PA_FLOAT:
2790           case PA_DOUBLE:
2791             wanted = NUMBER;
2792             break;
2793           case PA_CHAR:
2794             wanted = CHAR;
2795             break;
2796           case PA_STRING:
2797             wanted = STRING;
2798             break;
2799           case PA_POINTER:
2800             wanted = STRUCTURE;
2801             break;
2802           @}
2803       if (TYPE (args[i]) != wanted)
2804         @{
2805           error ("type mismatch for arg number %d", i);
2806           return 0;
2807         @}
2808     @}
2809   return 1;
2811 @end smallexample
2813 @node Customizing Printf
2814 @section Customizing @code{printf}
2815 @cindex customizing @code{printf}
2816 @cindex defining new @code{printf} conversions
2817 @cindex extending @code{printf}
2819 The GNU C library lets you define your own custom conversion specifiers
2820 for @code{printf} template strings, to teach @code{printf} clever ways
2821 to print the important data structures of your program.
2823 The way you do this is by registering the conversion with the function
2824 @code{register_printf_function}; see @ref{Registering New Conversions}.
2825 One of the arguments you pass to this function is a pointer to a handler
2826 function that produces the actual output; see @ref{Defining the Output
2827 Handler}, for information on how to write this function.
2829 You can also install a function that just returns information about the
2830 number and type of arguments expected by the conversion specifier.
2831 @xref{Parsing a Template String}, for information about this.
2833 The facilities of this section are declared in the header file
2834 @file{printf.h}.
2836 @menu
2837 * Registering New Conversions::         Using @code{register_printf_function}
2838                                          to register a new output conversion.
2839 * Conversion Specifier Options::        The handler must be able to get
2840                                          the options specified in the
2841                                          template when it is called.
2842 * Defining the Output Handler::         Defining the handler and arginfo
2843                                          functions that are passed as arguments
2844                                          to @code{register_printf_function}.
2845 * Printf Extension Example::            How to define a @code{printf}
2846                                          handler function.
2847 * Predefined Printf Handlers::          Predefined @code{printf} handlers.
2848 @end menu
2850 @strong{Portability Note:} The ability to extend the syntax of
2851 @code{printf} template strings is a GNU extension.  ISO standard C has
2852 nothing similar.
2854 @node Registering New Conversions
2855 @subsection Registering New Conversions
2857 The function to register a new output conversion is
2858 @code{register_printf_function}, declared in @file{printf.h}.
2859 @pindex printf.h
2861 @comment printf.h
2862 @comment GNU
2863 @deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function})
2864 This function defines the conversion specifier character @var{spec}.
2865 Thus, if @var{spec} is @code{'Y'}, it defines the conversion @samp{%Y}.
2866 You can redefine the built-in conversions like @samp{%s}, but flag
2867 characters like @samp{#} and type modifiers like @samp{l} can never be
2868 used as conversions; calling @code{register_printf_function} for those
2869 characters has no effect.  It is advisable not to use lowercase letters,
2870 since the ISO C standard warns that additional lowercase letters may be
2871 standardized in future editions of the standard.
2873 The @var{handler-function} is the function called by @code{printf} and
2874 friends when this conversion appears in a template string.
2875 @xref{Defining the Output Handler}, for information about how to define
2876 a function to pass as this argument.  If you specify a null pointer, any
2877 existing handler function for @var{spec} is removed.
2879 The @var{arginfo-function} is the function called by
2880 @code{parse_printf_format} when this conversion appears in a
2881 template string.  @xref{Parsing a Template String}, for information
2882 about this.
2884 @c The following is not true anymore.  The `parse_printf_format' function
2885 @c is now also called from `vfprintf' via `parse_one_spec'.
2886 @c --drepper@gnu, 1996/11/14
2888 @c Normally, you install both functions for a conversion at the same time,
2889 @c but if you are never going to call @code{parse_printf_format}, you do
2890 @c not need to define an arginfo function.
2892 @strong{Attention:} In the GNU C library versions before 2.0 the
2893 @var{arginfo-function} function did not need to be installed unless
2894 the user used the @code{parse_printf_format} function.  This has changed.
2895 Now a call to any of the @code{printf} functions will call this
2896 function when this format specifier appears in the format string.
2898 The return value is @code{0} on success, and @code{-1} on failure
2899 (which occurs if @var{spec} is out of range).
2901 You can redefine the standard output conversions, but this is probably
2902 not a good idea because of the potential for confusion.  Library routines
2903 written by other people could break if you do this.
2904 @end deftypefun
2906 @node Conversion Specifier Options
2907 @subsection Conversion Specifier Options
2909 If you define a meaning for @samp{%A}, what if the template contains
2910 @samp{%+23A} or @samp{%-#A}?  To implement a sensible meaning for these,
2911 the handler when called needs to be able to get the options specified in
2912 the template.
2914 Both the @var{handler-function} and @var{arginfo-function} accept an
2915 argument that points to a @code{struct printf_info}, which contains
2916 information about the options appearing in an instance of the conversion
2917 specifier.  This data type is declared in the header file
2918 @file{printf.h}.
2919 @pindex printf.h
2921 @comment printf.h
2922 @comment GNU
2923 @deftp {Type} {struct printf_info}
2924 This structure is used to pass information about the options appearing
2925 in an instance of a conversion specifier in a @code{printf} template
2926 string to the handler and arginfo functions for that specifier.  It
2927 contains the following members:
2929 @table @code
2930 @item int prec
2931 This is the precision specified.  The value is @code{-1} if no precision
2932 was specified.  If the precision was given as @samp{*}, the
2933 @code{printf_info} structure passed to the handler function contains the
2934 actual value retrieved from the argument list.  But the structure passed
2935 to the arginfo function contains a value of @code{INT_MIN}, since the
2936 actual value is not known.
2938 @item int width
2939 This is the minimum field width specified.  The value is @code{0} if no
2940 width was specified.  If the field width was given as @samp{*}, the
2941 @code{printf_info} structure passed to the handler function contains the
2942 actual value retrieved from the argument list.  But the structure passed
2943 to the arginfo function contains a value of @code{INT_MIN}, since the
2944 actual value is not known.
2946 @item wchar_t spec
2947 This is the conversion specifier character specified.  It's stored in
2948 the structure so that you can register the same handler function for
2949 multiple characters, but still have a way to tell them apart when the
2950 handler function is called.
2952 @item unsigned int is_long_double
2953 This is a boolean that is true if the @samp{L}, @samp{ll}, or @samp{q}
2954 type modifier was specified.  For integer conversions, this indicates
2955 @code{long long int}, as opposed to @code{long double} for floating
2956 point conversions.
2958 @item unsigned int is_char
2959 This is a boolean that is true if the @samp{hh} type modifier was specified.
2961 @item unsigned int is_short
2962 This is a boolean that is true if the @samp{h} type modifier was specified.
2964 @item unsigned int is_long
2965 This is a boolean that is true if the @samp{l} type modifier was specified.
2967 @item unsigned int alt
2968 This is a boolean that is true if the @samp{#} flag was specified.
2970 @item unsigned int space
2971 This is a boolean that is true if the @samp{ } flag was specified.
2973 @item unsigned int left
2974 This is a boolean that is true if the @samp{-} flag was specified.
2976 @item unsigned int showsign
2977 This is a boolean that is true if the @samp{+} flag was specified.
2979 @item unsigned int group
2980 This is a boolean that is true if the @samp{'} flag was specified.
2982 @item unsigned int extra
2983 This flag has a special meaning depending on the context.  It could
2984 be used freely by the user-defined handlers but when called from
2985 the @code{printf} function this variable always contains the value
2986 @code{0}.
2988 @item unsigned int wide
2989 This flag is set if the stream is wide oriented.
2991 @item wchar_t pad
2992 This is the character to use for padding the output to the minimum field
2993 width.  The value is @code{'0'} if the @samp{0} flag was specified, and
2994 @code{' '} otherwise.
2995 @end table
2996 @end deftp
2999 @node Defining the Output Handler
3000 @subsection Defining the Output Handler
3002 Now let's look at how to define the handler and arginfo functions
3003 which are passed as arguments to @code{register_printf_function}.
3005 @strong{Compatibility Note:} The interface changed in GNU libc
3006 version 2.0.  Previously the third argument was of type
3007 @code{va_list *}.
3009 You should define your handler functions with a prototype like:
3011 @smallexample
3012 int @var{function} (FILE *stream, const struct printf_info *info,
3013                     const void *const *args)
3014 @end smallexample
3016 The @var{stream} argument passed to the handler function is the stream to
3017 which it should write output.
3019 The @var{info} argument is a pointer to a structure that contains
3020 information about the various options that were included with the
3021 conversion in the template string.  You should not modify this structure
3022 inside your handler function.  @xref{Conversion Specifier Options}, for
3023 a description of this data structure.
3025 @c The following changes some time back.  --drepper@gnu, 1996/11/14
3027 @c The @code{ap_pointer} argument is used to pass the tail of the variable
3028 @c argument list containing the values to be printed to your handler.
3029 @c Unlike most other functions that can be passed an explicit variable
3030 @c argument list, this is a @emph{pointer} to a @code{va_list}, rather than
3031 @c the @code{va_list} itself.  Thus, you should fetch arguments by
3032 @c means of @code{va_arg (*ap_pointer, @var{type})}.
3034 @c (Passing a pointer here allows the function that calls your handler
3035 @c function to update its own @code{va_list} variable to account for the
3036 @c arguments that your handler processes.  @xref{Variadic Functions}.)
3038 The @var{args} is a vector of pointers to the arguments data.
3039 The number of arguments was determined by calling the argument
3040 information function provided by the user.
3042 Your handler function should return a value just like @code{printf}
3043 does: it should return the number of characters it has written, or a
3044 negative value to indicate an error.
3046 @comment printf.h
3047 @comment GNU
3048 @deftp {Data Type} printf_function
3049 This is the data type that a handler function should have.
3050 @end deftp
3052 If you are going to use @w{@code{parse_printf_format}} in your
3053 application, you must also define a function to pass as the
3054 @var{arginfo-function} argument for each new conversion you install with
3055 @code{register_printf_function}.
3057 You have to define these functions with a prototype like:
3059 @smallexample
3060 int @var{function} (const struct printf_info *info,
3061                     size_t n, int *argtypes)
3062 @end smallexample
3064 The return value from the function should be the number of arguments the
3065 conversion expects.  The function should also fill in no more than
3066 @var{n} elements of the @var{argtypes} array with information about the
3067 types of each of these arguments.  This information is encoded using the
3068 various @samp{PA_} macros.  (You will notice that this is the same
3069 calling convention @code{parse_printf_format} itself uses.)
3071 @comment printf.h
3072 @comment GNU
3073 @deftp {Data Type} printf_arginfo_function
3074 This type is used to describe functions that return information about
3075 the number and type of arguments used by a conversion specifier.
3076 @end deftp
3078 @node Printf Extension Example
3079 @subsection @code{printf} Extension Example
3081 Here is an example showing how to define a @code{printf} handler function.
3082 This program defines a data structure called a @code{Widget} and
3083 defines the @samp{%W} conversion to print information about @w{@code{Widget *}}
3084 arguments, including the pointer value and the name stored in the data
3085 structure.  The @samp{%W} conversion supports the minimum field width and
3086 left-justification options, but ignores everything else.
3088 @smallexample
3089 @include rprintf.c.texi
3090 @end smallexample
3092 The output produced by this program looks like:
3094 @smallexample
3095 |<Widget 0xffeffb7c: mywidget>|
3096 |      <Widget 0xffeffb7c: mywidget>|
3097 |<Widget 0xffeffb7c: mywidget>      |
3098 @end smallexample
3100 @node Predefined Printf Handlers
3101 @subsection Predefined @code{printf} Handlers
3103 The GNU libc also contains a concrete and useful application of the
3104 @code{printf} handler extension.  There are two functions available
3105 which implement a special way to print floating-point numbers.
3107 @comment printf.h
3108 @comment GNU
3109 @deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args})
3110 Print a given floating point number as for the format @code{%f} except
3111 that there is a postfix character indicating the divisor for the
3112 number to make this less than 1000.  There are two possible divisors:
3113 powers of 1024 or powers of 1000.  Which one is used depends on the
3114 format character specified while registered this handler.  If the
3115 character is of lower case, 1024 is used.  For upper case characters,
3116 1000 is used.
3118 The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes,
3119 etc.  The full table is:
3121 @ifinfo
3122 @multitable @hsep @vsep {' '} {2^10 (1024)} {zetta} {Upper} {10^24 (1000)}
3123 @item low @tab Multiplier  @tab From  @tab Upper @tab Multiplier
3124 @item ' ' @tab 1           @tab       @tab ' '   @tab 1
3125 @item k   @tab 2^10 (1024) @tab kilo  @tab K     @tab 10^3 (1000)
3126 @item m   @tab 2^20        @tab mega  @tab M     @tab 10^6
3127 @item g   @tab 2^30        @tab giga  @tab G     @tab 10^9
3128 @item t   @tab 2^40        @tab tera  @tab T     @tab 10^12
3129 @item p   @tab 2^50        @tab peta  @tab P     @tab 10^15
3130 @item e   @tab 2^60        @tab exa   @tab E     @tab 10^18
3131 @item z   @tab 2^70        @tab zetta @tab Z     @tab 10^21
3132 @item y   @tab 2^80        @tab yotta @tab Y     @tab 10^24
3133 @end multitable
3134 @end ifinfo
3135 @iftex
3136 @tex
3137 \hbox to\hsize{\hfil\vbox{\offinterlineskip
3138 \hrule
3139 \halign{\strut#& \vrule#\tabskip=1em plus2em& {\tt#}\hfil& \vrule#& #\hfil& \vrule#& #\hfil& \vrule#& {\tt#}\hfil& \vrule#& #\hfil& \vrule#\tabskip=0pt\cr
3140 \noalign{\hrule}
3141 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
3142 && \omit low && Multiplier && From && \omit Upper && Multiplier &\cr
3143 \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
3144 \noalign{\hrule}
3145 && {\tt\char32} &&  1 && && {\tt\char32} && 1 &\cr
3146 && k && $2^{10} = 1024$ && kilo && K && $10^3 = 1000$ &\cr
3147 && m && $2^{20}$ && mega && M && $10^6$ &\cr
3148 && g && $2^{30}$ && giga && G && $10^9$ &\cr
3149 && t && $2^{40}$ && tera && T && $10^{12}$ &\cr
3150 && p && $2^{50}$ && peta && P && $10^{15}$ &\cr
3151 && e && $2^{60}$ && exa && E && $10^{18}$ &\cr
3152 && z && $2^{70}$ && zetta && Z && $10^{21}$ &\cr
3153 && y && $2^{80}$ && yotta && Y && $10^{24}$ &\cr
3154 \noalign{\hrule}}}\hfil}
3155 @end tex
3156 @end iftex
3158 The default precision is 3, i.e., 1024 is printed with a lower-case
3159 format character as if it were @code{%.3fk} and will yield @code{1.000k}.
3160 @end deftypefun
3162 Due to the requirements of @code{register_printf_function} we must also
3163 provide the function which returns information about the arguments.
3165 @comment printf.h
3166 @comment GNU
3167 @deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes})
3168 This function will return in @var{argtypes} the information about the
3169 used parameters in the way the @code{vfprintf} implementation expects
3170 it.  The format always takes one argument.
3171 @end deftypefun
3173 To use these functions both functions must be registered with a call like
3175 @smallexample
3176 register_printf_function ('B', printf_size, printf_size_info);
3177 @end smallexample
3179 Here we register the functions to print numbers as powers of 1000 since
3180 the format character @code{'B'} is an upper-case character.  If we
3181 would additionally use @code{'b'} in a line like
3183 @smallexample
3184 register_printf_function ('b', printf_size, printf_size_info);
3185 @end smallexample
3187 @noindent
3188 we could also print using a power of 1024.  Please note that all that is
3189 different in these two lines is the format specifier.  The
3190 @code{printf_size} function knows about the difference between lower and upper
3191 case format specifiers.
3193 The use of @code{'B'} and @code{'b'} is no coincidence.  Rather it is
3194 the preferred way to use this functionality since it is available on
3195 some other systems which also use format specifiers.
3197 @node Formatted Input
3198 @section Formatted Input
3200 @cindex formatted input from a stream
3201 @cindex reading from a stream, formatted
3202 @cindex format string, for @code{scanf}
3203 @cindex template, for @code{scanf}
3204 The functions described in this section (@code{scanf} and related
3205 functions) provide facilities for formatted input analogous to the
3206 formatted output facilities.  These functions provide a mechanism for
3207 reading arbitrary values under the control of a @dfn{format string} or
3208 @dfn{template string}.
3210 @menu
3211 * Formatted Input Basics::      Some basics to get you started.
3212 * Input Conversion Syntax::     Syntax of conversion specifications.
3213 * Table of Input Conversions::  Summary of input conversions and what they do.
3214 * Numeric Input Conversions::   Details of conversions for reading numbers.
3215 * String Input Conversions::    Details of conversions for reading strings.
3216 * Dynamic String Input::        String conversions that @code{malloc} the buffer.
3217 * Other Input Conversions::     Details of miscellaneous other conversions.
3218 * Formatted Input Functions::   Descriptions of the actual functions.
3219 * Variable Arguments Input::    @code{vscanf} and friends.
3220 @end menu
3222 @node Formatted Input Basics
3223 @subsection Formatted Input Basics
3225 Calls to @code{scanf} are superficially similar to calls to
3226 @code{printf} in that arbitrary arguments are read under the control of
3227 a template string.  While the syntax of the conversion specifications in
3228 the template is very similar to that for @code{printf}, the
3229 interpretation of the template is oriented more towards free-format
3230 input and simple pattern matching, rather than fixed-field formatting.
3231 For example, most @code{scanf} conversions skip over any amount of
3232 ``white space'' (including spaces, tabs, and newlines) in the input
3233 file, and there is no concept of precision for the numeric input
3234 conversions as there is for the corresponding output conversions.
3235 Ordinarily, non-whitespace characters in the template are expected to
3236 match characters in the input stream exactly, but a matching failure is
3237 distinct from an input error on the stream.
3238 @cindex conversion specifications (@code{scanf})
3240 Another area of difference between @code{scanf} and @code{printf} is
3241 that you must remember to supply pointers rather than immediate values
3242 as the optional arguments to @code{scanf}; the values that are read are
3243 stored in the objects that the pointers point to.  Even experienced
3244 programmers tend to forget this occasionally, so if your program is
3245 getting strange errors that seem to be related to @code{scanf}, you
3246 might want to double-check this.
3248 When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
3249 leaving the first non-matching character as the next character to be
3250 read from the stream.  The normal return value from @code{scanf} is the
3251 number of values that were assigned, so you can use this to determine if
3252 a matching error happened before all the expected values were read.
3253 @cindex matching failure, in @code{scanf}
3255 The @code{scanf} function is typically used for things like reading in
3256 the contents of tables.  For example, here is a function that uses
3257 @code{scanf} to initialize an array of @code{double}:
3259 @smallexample
3260 void
3261 readarray (double *array, int n)
3263   int i;
3264   for (i=0; i<n; i++)
3265     if (scanf (" %lf", &(array[i])) != 1)
3266       invalid_input_error ();
3268 @end smallexample
3270 The formatted input functions are not used as frequently as the
3271 formatted output functions.  Partly, this is because it takes some care
3272 to use them properly.  Another reason is that it is difficult to recover
3273 from a matching error.
3275 If you are trying to read input that doesn't match a single, fixed
3276 pattern, you may be better off using a tool such as Flex to generate a
3277 lexical scanner, or Bison to generate a parser, rather than using
3278 @code{scanf}.  For more information about these tools, see @ref{Top, , ,
3279 flex.info, Flex: The Lexical Scanner Generator}, and @ref{Top, , ,
3280 bison.info, The Bison Reference Manual}.
3282 @node Input Conversion Syntax
3283 @subsection Input Conversion Syntax
3285 A @code{scanf} template string is a string that contains ordinary
3286 multibyte characters interspersed with conversion specifications that
3287 start with @samp{%}.
3289 Any whitespace character (as defined by the @code{isspace} function;
3290 @pxref{Classification of Characters}) in the template causes any number
3291 of whitespace characters in the input stream to be read and discarded.
3292 The whitespace characters that are matched need not be exactly the same
3293 whitespace characters that appear in the template string.  For example,
3294 write @samp{ , } in the template to recognize a comma with optional
3295 whitespace before and after.
3297 Other characters in the template string that are not part of conversion
3298 specifications must match characters in the input stream exactly; if
3299 this is not the case, a matching failure occurs.
3301 The conversion specifications in a @code{scanf} template string
3302 have the general form:
3304 @smallexample
3305 % @var{flags} @var{width} @var{type} @var{conversion}
3306 @end smallexample
3308 In more detail, an input conversion specification consists of an initial
3309 @samp{%} character followed in sequence by:
3311 @itemize @bullet
3312 @item
3313 An optional @dfn{flag character} @samp{*}, which says to ignore the text
3314 read for this specification.  When @code{scanf} finds a conversion
3315 specification that uses this flag, it reads input as directed by the
3316 rest of the conversion specification, but it discards this input, does
3317 not use a pointer argument, and does not increment the count of
3318 successful assignments.
3319 @cindex flag character (@code{scanf})
3321 @item
3322 An optional flag character @samp{a} (valid with string conversions only)
3323 which requests allocation of a buffer long enough to store the string in.
3324 (This is a GNU extension.)
3325 @xref{Dynamic String Input}.
3327 @item
3328 An optional decimal integer that specifies the @dfn{maximum field
3329 width}.  Reading of characters from the input stream stops either when
3330 this maximum is reached or when a non-matching character is found,
3331 whichever happens first.  Most conversions discard initial whitespace
3332 characters (those that don't are explicitly documented), and these
3333 discarded characters don't count towards the maximum field width.
3334 String input conversions store a null character to mark the end of the
3335 input; the maximum field width does not include this terminator.
3336 @cindex maximum field width (@code{scanf})
3338 @item
3339 An optional @dfn{type modifier character}.  For example, you can
3340 specify a type modifier of @samp{l} with integer conversions such as
3341 @samp{%d} to specify that the argument is a pointer to a @code{long int}
3342 rather than a pointer to an @code{int}.
3343 @cindex type modifier character (@code{scanf})
3345 @item
3346 A character that specifies the conversion to be applied.
3347 @end itemize
3349 The exact options that are permitted and how they are interpreted vary
3350 between the different conversion specifiers.  See the descriptions of the
3351 individual conversions for information about the particular options that
3352 they allow.
3354 With the @samp{-Wformat} option, the GNU C compiler checks calls to
3355 @code{scanf} and related functions.  It examines the format string and
3356 verifies that the correct number and types of arguments are supplied.
3357 There is also a GNU C syntax to tell the compiler that a function you
3358 write uses a @code{scanf}-style format string.
3359 @xref{Function Attributes, , Declaring Attributes of Functions,
3360 gcc.info, Using GNU CC}, for more information.
3362 @node Table of Input Conversions
3363 @subsection Table of Input Conversions
3364 @cindex input conversions, for @code{scanf}
3366 Here is a table that summarizes the various conversion specifications:
3368 @table @asis
3369 @item @samp{%d}
3370 Matches an optionally signed integer written in decimal.  @xref{Numeric
3371 Input Conversions}.
3373 @item @samp{%i}
3374 Matches an optionally signed integer in any of the formats that the C
3375 language defines for specifying an integer constant.  @xref{Numeric
3376 Input Conversions}.
3378 @item @samp{%o}
3379 Matches an unsigned integer written in octal radix.
3380 @xref{Numeric Input Conversions}.
3382 @item @samp{%u}
3383 Matches an unsigned integer written in decimal radix.
3384 @xref{Numeric Input Conversions}.
3386 @item @samp{%x}, @samp{%X}
3387 Matches an unsigned integer written in hexadecimal radix.
3388 @xref{Numeric Input Conversions}.
3390 @item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
3391 Matches an optionally signed floating-point number.  @xref{Numeric Input
3392 Conversions}.
3394 @item @samp{%s}
3396 Matches a string containing only non-whitespace characters.
3397 @xref{String Input Conversions}.  The presence of the @samp{l} modifier
3398 determines whether the output is stored as a wide character string or a
3399 multibyte string.  If @samp{%s} is used in a wide character function the
3400 string is converted as with multiple calls to @code{wcrtomb} into a
3401 multibyte string.  This means that the buffer must provide room for
3402 @code{MB_CUR_MAX} bytes for each wide character read.  In case
3403 @samp{%ls} is used in a multibyte function the result is converted into
3404 wide characters as with multiple calls of @code{mbrtowc} before being
3405 stored in the user provided buffer.
3407 @item @samp{%S}
3408 This is an alias for @samp{%ls} which is supported for compatibility
3409 with the Unix standard.
3411 @item @samp{%[}
3412 Matches a string of characters that belong to a specified set.
3413 @xref{String Input Conversions}.  The presence of the @samp{l} modifier
3414 determines whether the output is stored as a wide character string or a
3415 multibyte string.  If @samp{%[} is used in a wide character function the
3416 string is converted as with multiple calls to @code{wcrtomb} into a
3417 multibyte string.  This means that the buffer must provide room for
3418 @code{MB_CUR_MAX} bytes for each wide character read.  In case
3419 @samp{%l[} is used in a multibyte function the result is converted into
3420 wide characters as with multiple calls of @code{mbrtowc} before being
3421 stored in the user provided buffer.
3423 @item @samp{%c}
3424 Matches a string of one or more characters; the number of characters
3425 read is controlled by the maximum field width given for the conversion.
3426 @xref{String Input Conversions}.
3428 If the @samp{%c} is used in a wide stream function the read value is
3429 converted from a wide character to the corresponding multibyte character
3430 before storing it.  Note that this conversion can produce more than one
3431 byte of output and therefore the provided buffer be large enough for up
3432 to @code{MB_CUR_MAX} bytes for each character.  If @samp{%lc} is used in
3433 a multibyte function the input is treated as a multibyte sequence (and
3434 not bytes) and the result is converted as with calls to @code{mbrtowc}.
3436 @item @samp{%C}
3437 This is an alias for @samp{%lc} which is supported for compatibility
3438 with the Unix standard.
3440 @item @samp{%p}
3441 Matches a pointer value in the same implementation-defined format used
3442 by the @samp{%p} output conversion for @code{printf}.  @xref{Other Input
3443 Conversions}.
3445 @item @samp{%n}
3446 This conversion doesn't read any characters; it records the number of
3447 characters read so far by this call.  @xref{Other Input Conversions}.
3449 @item @samp{%%}
3450 This matches a literal @samp{%} character in the input stream.  No
3451 corresponding argument is used.  @xref{Other Input Conversions}.
3452 @end table
3454 If the syntax of a conversion specification is invalid, the behavior is
3455 undefined.  If there aren't enough function arguments provided to supply
3456 addresses for all the conversion specifications in the template strings
3457 that perform assignments, or if the arguments are not of the correct
3458 types, the behavior is also undefined.  On the other hand, extra
3459 arguments are simply ignored.
3461 @node Numeric Input Conversions
3462 @subsection Numeric Input Conversions
3464 This section describes the @code{scanf} conversions for reading numeric
3465 values.
3467 The @samp{%d} conversion matches an optionally signed integer in decimal
3468 radix.  The syntax that is recognized is the same as that for the
3469 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3470 @code{10} for the @var{base} argument.
3472 The @samp{%i} conversion matches an optionally signed integer in any of
3473 the formats that the C language defines for specifying an integer
3474 constant.  The syntax that is recognized is the same as that for the
3475 @code{strtol} function (@pxref{Parsing of Integers}) with the value
3476 @code{0} for the @var{base} argument.  (You can print integers in this
3477 syntax with @code{printf} by using the @samp{#} flag character with the
3478 @samp{%x}, @samp{%o}, or @samp{%d} conversion.  @xref{Integer Conversions}.)
3480 For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
3481 could be read in as integers under the @samp{%i} conversion.  Each of
3482 these specifies a number with decimal value @code{10}.
3484 The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned
3485 integers in octal, decimal, and hexadecimal radices, respectively.  The
3486 syntax that is recognized is the same as that for the @code{strtoul}
3487 function (@pxref{Parsing of Integers}) with the appropriate value
3488 (@code{8}, @code{10}, or @code{16}) for the @var{base} argument.
3490 The @samp{%X} conversion is identical to the @samp{%x} conversion.  They
3491 both permit either uppercase or lowercase letters to be used as digits.
3493 The default type of the corresponding argument for the @code{%d} and
3494 @code{%i} conversions is @code{int *}, and @code{unsigned int *} for the
3495 other integer conversions.  You can use the following type modifiers to
3496 specify other sizes of integer:
3498 @table @samp
3499 @item hh
3500 Specifies that the argument is a @code{signed char *} or @code{unsigned
3501 char *}.
3503 This modifier was introduced in @w{ISO C99}.
3505 @item h
3506 Specifies that the argument is a @code{short int *} or @code{unsigned
3507 short int *}.
3509 @item j
3510 Specifies that the argument is a @code{intmax_t *} or @code{uintmax_t *}.
3512 This modifier was introduced in @w{ISO C99}.
3514 @item l
3515 Specifies that the argument is a @code{long int *} or @code{unsigned
3516 long int *}.  Two @samp{l} characters is like the @samp{L} modifier, below.
3518 If used with @samp{%c} or @samp{%s} the corresponding parameter is
3519 considered as a pointer to a wide character or wide character string
3520 respectively.  This use of @samp{l} was introduced in @w{Amendment 1} to
3521 @w{ISO C90}.
3523 @need 100
3524 @item ll
3525 @itemx L
3526 @itemx q
3527 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
3528 GNU C compiler.  For systems that don't provide extra-long integers, this
3529 is the same as @code{long int}.)
3531 The @samp{q} modifier is another name for the same thing, which comes
3532 from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
3533 @code{int}.
3535 @item t
3536 Specifies that the argument is a @code{ptrdiff_t *}.
3538 This modifier was introduced in @w{ISO C99}.
3540 @item z
3541 Specifies that the argument is a @code{size_t *}.
3543 This modifier was introduced in @w{ISO C99}.
3544 @end table
3546 All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
3547 input conversions are interchangeable.  They all match an optionally
3548 signed floating point number, in the same syntax as for the
3549 @code{strtod} function (@pxref{Parsing of Floats}).
3551 For the floating-point input conversions, the default argument type is
3552 @code{float *}.  (This is different from the corresponding output
3553 conversions, where the default type is @code{double}; remember that
3554 @code{float} arguments to @code{printf} are converted to @code{double}
3555 by the default argument promotions, but @code{float *} arguments are
3556 not promoted to @code{double *}.)  You can specify other sizes of float
3557 using these type modifiers:
3559 @table @samp
3560 @item l
3561 Specifies that the argument is of type @code{double *}.
3563 @item L
3564 Specifies that the argument is of type @code{long double *}.
3565 @end table
3567 For all the above number parsing formats there is an additional optional
3568 flag @samp{'}.  When this flag is given the @code{scanf} function
3569 expects the number represented in the input string to be formatted
3570 according to the grouping rules of the currently selected locale
3571 (@pxref{General Numeric}).
3573 If the @code{"C"} or @code{"POSIX"} locale is selected there is no
3574 difference.  But for a locale which specifies values for the appropriate
3575 fields in the locale the input must have the correct form in the input.
3576 Otherwise the longest prefix with a correct form is processed.
3578 @node String Input Conversions
3579 @subsection String Input Conversions
3581 This section describes the @code{scanf} input conversions for reading
3582 string and character values: @samp{%s}, @samp{%S}, @samp{%[}, @samp{%c},
3583 and @samp{%C}.
3585 You have two options for how to receive the input from these
3586 conversions:
3588 @itemize @bullet
3589 @item
3590 Provide a buffer to store it in.  This is the default.  You should
3591 provide an argument of type @code{char *} or @code{wchar_t *} (the
3592 latter of the @samp{l} modifier is present).
3594 @strong{Warning:} To make a robust program, you must make sure that the
3595 input (plus its terminating null) cannot possibly exceed the size of the
3596 buffer you provide.  In general, the only way to do this is to specify a
3597 maximum field width one less than the buffer size.  @strong{If you
3598 provide the buffer, always specify a maximum field width to prevent
3599 overflow.}
3601 @item
3602 Ask @code{scanf} to allocate a big enough buffer, by specifying the
3603 @samp{a} flag character.  This is a GNU extension.  You should provide
3604 an argument of type @code{char **} for the buffer address to be stored
3605 in.  @xref{Dynamic String Input}.
3606 @end itemize
3608 The @samp{%c} conversion is the simplest: it matches a fixed number of
3609 characters, always.  The maximum field width says how many characters to
3610 read; if you don't specify the maximum, the default is 1.  This
3611 conversion doesn't append a null character to the end of the text it
3612 reads.  It also does not skip over initial whitespace characters.  It
3613 reads precisely the next @var{n} characters, and fails if it cannot get
3614 that many.  Since there is always a maximum field width with @samp{%c}
3615 (whether specified, or 1 by default), you can always prevent overflow by
3616 making the buffer long enough.
3617 @comment Is character == byte here???  --drepper
3619 If the format is @samp{%lc} or @samp{%C} the function stores wide
3620 characters which are converted using the conversion determined at the
3621 time the stream was opened from the external byte stream.  The number of
3622 bytes read from the medium is limited by @code{MB_CUR_LEN * @var{n}} but
3623 at most @var{n} wide character get stored in the output string.
3625 The @samp{%s} conversion matches a string of non-whitespace characters.
3626 It skips and discards initial whitespace, but stops when it encounters
3627 more whitespace after having read something.  It stores a null character
3628 at the end of the text that it reads.
3630 For example, reading the input:
3632 @smallexample
3633  hello, world
3634 @end smallexample
3636 @noindent
3637 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
3638 reading the same input with the conversion @samp{%10s} produces
3639 @code{"hello,"}.
3641 @strong{Warning:} If you do not specify a field width for @samp{%s},
3642 then the number of characters read is limited only by where the next
3643 whitespace character appears.  This almost certainly means that invalid
3644 input can make your program crash---which is a bug.
3646 The @samp{%ls} and @samp{%S} format are handled just like @samp{%s}
3647 except that the external byte sequence is converted using the conversion
3648 associated with the stream to wide characters with their own encoding.
3649 A width or precision specified with the format do not directly determine
3650 how many bytes are read from the stream since they measure wide
3651 characters.  But an upper limit can be computed by multiplying the value
3652 of the width or precision by @code{MB_CUR_MAX}.
3654 To read in characters that belong to an arbitrary set of your choice,
3655 use the @samp{%[} conversion.  You specify the set between the @samp{[}
3656 character and a following @samp{]} character, using the same syntax used
3657 in regular expressions.  As special cases:
3659 @itemize @bullet
3660 @item
3661 A literal @samp{]} character can be specified as the first character
3662 of the set.
3664 @item
3665 An embedded @samp{-} character (that is, one that is not the first or
3666 last character of the set) is used to specify a range of characters.
3668 @item
3669 If a caret character @samp{^} immediately follows the initial @samp{[},
3670 then the set of allowed input characters is the everything @emph{except}
3671 the characters listed.
3672 @end itemize
3674 The @samp{%[} conversion does not skip over initial whitespace
3675 characters.
3677 Here are some examples of @samp{%[} conversions and what they mean:
3679 @table @samp
3680 @item %25[1234567890]
3681 Matches a string of up to 25 digits.
3683 @item %25[][]
3684 Matches a string of up to 25 square brackets.
3686 @item %25[^ \f\n\r\t\v]
3687 Matches a string up to 25 characters long that doesn't contain any of
3688 the standard whitespace characters.  This is slightly different from
3689 @samp{%s}, because if the input begins with a whitespace character,
3690 @samp{%[} reports a matching failure while @samp{%s} simply discards the
3691 initial whitespace.
3693 @item %25[a-z]
3694 Matches up to 25 lowercase characters.
3695 @end table
3697 As for @samp{%c} and @samp{%s} the @samp{%[} format is also modified to
3698 produce wide characters if the @samp{l} modifier is present.  All what
3699 is said about @samp{%ls} above is true for @samp{%l[}.
3701 One more reminder: the @samp{%s} and @samp{%[} conversions are
3702 @strong{dangerous} if you don't specify a maximum width or use the
3703 @samp{a} flag, because input too long would overflow whatever buffer you
3704 have provided for it.  No matter how long your buffer is, a user could
3705 supply input that is longer.  A well-written program reports invalid
3706 input with a comprehensible error message, not with a crash.
3708 @node Dynamic String Input
3709 @subsection Dynamically Allocating String Conversions
3711 A GNU extension to formatted input lets you safely read a string with no
3712 maximum size.  Using this feature, you don't supply a buffer; instead,
3713 @code{scanf} allocates a buffer big enough to hold the data and gives
3714 you its address.  To use this feature, write @samp{a} as a flag
3715 character, as in @samp{%as} or @samp{%a[0-9a-z]}.
3717 The pointer argument you supply for where to store the input should have
3718 type @code{char **}.  The @code{scanf} function allocates a buffer and
3719 stores its address in the word that the argument points to.  You should
3720 free the buffer with @code{free} when you no longer need it.
3722 Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]}
3723 conversion specification to read a ``variable assignment'' of the form
3724 @samp{@var{variable} = @var{value}}.
3726 @smallexample
3728   char *variable, *value;
3730   if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
3731                  &variable, &value))
3732     @{
3733       invalid_input_error ();
3734       return 0;
3735     @}
3737   @dots{}
3739 @end smallexample
3741 @node Other Input Conversions
3742 @subsection Other Input Conversions
3744 This section describes the miscellaneous input conversions.
3746 The @samp{%p} conversion is used to read a pointer value.  It recognizes
3747 the same syntax used by the @samp{%p} output conversion for
3748 @code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
3749 number just as the @samp{%x} conversion accepts.  The corresponding
3750 argument should be of type @code{void **}; that is, the address of a
3751 place to store a pointer.
3753 The resulting pointer value is not guaranteed to be valid if it was not
3754 originally written during the same program execution that reads it in.
3756 The @samp{%n} conversion produces the number of characters read so far
3757 by this call.  The corresponding argument should be of type @code{int *}.
3758 This conversion works in the same way as the @samp{%n} conversion for
3759 @code{printf}; see @ref{Other Output Conversions}, for an example.
3761 The @samp{%n} conversion is the only mechanism for determining the
3762 success of literal matches or conversions with suppressed assignments.
3763 If the @samp{%n} follows the locus of a matching failure, then no value
3764 is stored for it since @code{scanf} returns before processing the
3765 @samp{%n}.  If you store @code{-1} in that argument slot before calling
3766 @code{scanf}, the presence of @code{-1} after @code{scanf} indicates an
3767 error occurred before the @samp{%n} was reached.
3769 Finally, the @samp{%%} conversion matches a literal @samp{%} character
3770 in the input stream, without using an argument.  This conversion does
3771 not permit any flags, field width, or type modifier to be specified.
3773 @node Formatted Input Functions
3774 @subsection Formatted Input Functions
3776 Here are the descriptions of the functions for performing formatted
3777 input.
3778 Prototypes for these functions are in the header file @file{stdio.h}.
3779 @pindex stdio.h
3781 @comment stdio.h
3782 @comment ISO
3783 @deftypefun int scanf (const char *@var{template}, @dots{})
3784 The @code{scanf} function reads formatted input from the stream
3785 @code{stdin} under the control of the template string @var{template}.
3786 The optional arguments are pointers to the places which receive the
3787 resulting values.
3789 The return value is normally the number of successful assignments.  If
3790 an end-of-file condition is detected before any matches are performed,
3791 including matches against whitespace and literal characters in the
3792 template, then @code{EOF} is returned.
3793 @end deftypefun
3795 @comment wchar.h
3796 @comment ISO
3797 @deftypefun int wscanf (const wchar_t *@var{template}, @dots{})
3798 The @code{wscanf} function reads formatted input from the stream
3799 @code{stdin} under the control of the template string @var{template}.
3800 The optional arguments are pointers to the places which receive the
3801 resulting values.
3803 The return value is normally the number of successful assignments.  If
3804 an end-of-file condition is detected before any matches are performed,
3805 including matches against whitespace and literal characters in the
3806 template, then @code{WEOF} is returned.
3807 @end deftypefun
3809 @comment stdio.h
3810 @comment ISO
3811 @deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
3812 This function is just like @code{scanf}, except that the input is read
3813 from the stream @var{stream} instead of @code{stdin}.
3814 @end deftypefun
3816 @comment wchar.h
3817 @comment ISO
3818 @deftypefun int fwscanf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
3819 This function is just like @code{wscanf}, except that the input is read
3820 from the stream @var{stream} instead of @code{stdin}.
3821 @end deftypefun
3823 @comment stdio.h
3824 @comment ISO
3825 @deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
3826 This is like @code{scanf}, except that the characters are taken from the
3827 null-terminated string @var{s} instead of from a stream.  Reaching the
3828 end of the string is treated as an end-of-file condition.
3830 The behavior of this function is undefined if copying takes place
3831 between objects that overlap---for example, if @var{s} is also given
3832 as an argument to receive a string read under control of the @samp{%s},
3833 @samp{%S}, or @samp{%[} conversion.
3834 @end deftypefun
3836 @comment wchar.h
3837 @comment ISO
3838 @deftypefun int swscanf (const wchar_t *@var{ws}, const char *@var{template}, @dots{})
3839 This is like @code{wscanf}, except that the characters are taken from the
3840 null-terminated string @var{ws} instead of from a stream.  Reaching the
3841 end of the string is treated as an end-of-file condition.
3843 The behavior of this function is undefined if copying takes place
3844 between objects that overlap---for example, if @var{ws} is also given as
3845 an argument to receive a string read under control of the @samp{%s},
3846 @samp{%S}, or @samp{%[} conversion.
3847 @end deftypefun
3849 @node Variable Arguments Input
3850 @subsection Variable Arguments Input Functions
3852 The functions @code{vscanf} and friends are provided so that you can
3853 define your own variadic @code{scanf}-like functions that make use of
3854 the same internals as the built-in formatted output functions.
3855 These functions are analogous to the @code{vprintf} series of output
3856 functions.  @xref{Variable Arguments Output}, for important
3857 information on how to use them.
3859 @strong{Portability Note:} The functions listed in this section were
3860 introduced in @w{ISO C99} and were before available as GNU extensions.
3862 @comment stdio.h
3863 @comment ISO
3864 @deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
3865 This function is similar to @code{scanf}, but instead of taking
3866 a variable number of arguments directly, it takes an argument list
3867 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
3868 @end deftypefun
3870 @comment wchar.h
3871 @comment ISO
3872 @deftypefun int vwscanf (const wchar_t *@var{template}, va_list @var{ap})
3873 This function is similar to @code{wscanf}, but instead of taking
3874 a variable number of arguments directly, it takes an argument list
3875 pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
3876 @end deftypefun
3878 @comment stdio.h
3879 @comment ISO
3880 @deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
3881 This is the equivalent of @code{fscanf} with the variable argument list
3882 specified directly as for @code{vscanf}.
3883 @end deftypefun
3885 @comment wchar.h
3886 @comment ISO
3887 @deftypefun int vfwscanf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
3888 This is the equivalent of @code{fwscanf} with the variable argument list
3889 specified directly as for @code{vwscanf}.
3890 @end deftypefun
3892 @comment stdio.h
3893 @comment ISO
3894 @deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
3895 This is the equivalent of @code{sscanf} with the variable argument list
3896 specified directly as for @code{vscanf}.
3897 @end deftypefun
3899 @comment wchar.h
3900 @comment ISO
3901 @deftypefun int vswscanf (const wchar_t *@var{s}, const wchar_t *@var{template}, va_list @var{ap})
3902 This is the equivalent of @code{swscanf} with the variable argument list
3903 specified directly as for @code{vwscanf}.
3904 @end deftypefun
3906 In GNU C, there is a special construct you can use to let the compiler
3907 know that a function uses a @code{scanf}-style format string.  Then it
3908 can check the number and types of arguments in each call to the
3909 function, and warn you when they do not match the format string.
3910 For details, see @ref{Function Attributes, , Declaring Attributes of Functions,
3911 gcc.info, Using GNU CC}.
3913 @node EOF and Errors
3914 @section End-Of-File and Errors
3916 @cindex end of file, on a stream
3917 Many of the functions described in this chapter return the value of the
3918 macro @code{EOF} to indicate unsuccessful completion of the operation.
3919 Since @code{EOF} is used to report both end of file and random errors,
3920 it's often better to use the @code{feof} function to check explicitly
3921 for end of file and @code{ferror} to check for errors.  These functions
3922 check indicators that are part of the internal state of the stream
3923 object, indicators set if the appropriate condition was detected by a
3924 previous I/O operation on that stream.
3926 @comment stdio.h
3927 @comment ISO
3928 @deftypevr Macro int EOF
3929 This macro is an integer value that is returned by a number of narrow
3930 stream functions to indicate an end-of-file condition, or some other
3931 error situation.  With the GNU library, @code{EOF} is @code{-1}.  In
3932 other libraries, its value may be some other negative number.
3934 This symbol is declared in @file{stdio.h}.
3935 @end deftypevr
3937 @comment wchar.h
3938 @comment ISO
3939 @deftypevr Macro int WEOF
3940 This macro is an integer value that is returned by a number of wide
3941 stream functions to indicate an end-of-file condition, or some other
3942 error situation.  With the GNU library, @code{WEOF} is @code{-1}.  In
3943 other libraries, its value may be some other negative number.
3945 This symbol is declared in @file{wchar.h}.
3946 @end deftypevr
3948 @comment stdio.h
3949 @comment ISO
3950 @deftypefun int feof (FILE *@var{stream})
3951 The @code{feof} function returns nonzero if and only if the end-of-file
3952 indicator for the stream @var{stream} is set.
3954 This symbol is declared in @file{stdio.h}.
3955 @end deftypefun
3957 @comment stdio.h
3958 @comment GNU
3959 @deftypefun int feof_unlocked (FILE *@var{stream})
3960 The @code{feof_unlocked} function is equivalent to the @code{feof}
3961 function except that it does not implicitly lock the stream.
3963 This function is a GNU extension.
3965 This symbol is declared in @file{stdio.h}.
3966 @end deftypefun
3968 @comment stdio.h
3969 @comment ISO
3970 @deftypefun int ferror (FILE *@var{stream})
3971 The @code{ferror} function returns nonzero if and only if the error
3972 indicator for the stream @var{stream} is set, indicating that an error
3973 has occurred on a previous operation on the stream.
3975 This symbol is declared in @file{stdio.h}.
3976 @end deftypefun
3978 @comment stdio.h
3979 @comment GNU
3980 @deftypefun int ferror_unlocked (FILE *@var{stream})
3981 The @code{ferror_unlocked} function is equivalent to the @code{ferror}
3982 function except that it does not implicitly lock the stream.
3984 This function is a GNU extension.
3986 This symbol is declared in @file{stdio.h}.
3987 @end deftypefun
3989 In addition to setting the error indicator associated with the stream,
3990 the functions that operate on streams also set @code{errno} in the same
3991 way as the corresponding low-level functions that operate on file
3992 descriptors.  For example, all of the functions that perform output to a
3993 stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are
3994 implemented in terms of @code{write}, and all of the @code{errno} error
3995 conditions defined for @code{write} are meaningful for these functions.
3996 For more information about the descriptor-level I/O functions, see
3997 @ref{Low-Level I/O}.
3999 @node Error Recovery
4000 @section Recovering from errors
4002 You may explicitly clear the error and EOF flags with the @code{clearerr}
4003 function.
4005 @comment stdio.h
4006 @comment ISO
4007 @deftypefun void clearerr (FILE *@var{stream})
4008 This function clears the end-of-file and error indicators for the
4009 stream @var{stream}.
4011 The file positioning functions (@pxref{File Positioning}) also clear the
4012 end-of-file indicator for the stream.
4013 @end deftypefun
4015 @comment stdio.h
4016 @comment GNU
4017 @deftypefun void clearerr_unlocked (FILE *@var{stream})
4018 The @code{clearerr_unlocked} function is equivalent to the @code{clearerr}
4019 function except that it does not implicitly lock the stream.
4021 This function is a GNU extension.
4022 @end deftypefun
4024 Note that it is @emph{not} correct to just clear the error flag and retry
4025 a failed stream operation.  After a failed write, any number of
4026 characters since the last buffer flush may have been committed to the
4027 file, while some buffered data may have been discarded.  Merely retrying
4028 can thus cause lost or repeated data.
4030 A failed read may leave the file pointer in an inappropriate position for
4031 a second try.  In both cases, you should seek to a known position before
4032 retrying.
4034 Most errors that can happen are not recoverable --- a second try will
4035 always fail again in the same way.  So usually it is best to give up and
4036 report the error to the user, rather than install complicated recovery
4037 logic.
4039 One important exception is @code{EINTR} (@pxref{Interrupted Primitives}).
4040 Many stream I/O implementations will treat it as an ordinary error, which
4041 can be quite inconvenient.  You can avoid this hassle by installing all
4042 signals with the @code{SA_RESTART} flag.
4044 For similar reasons, setting nonblocking I/O on a stream's file
4045 descriptor is not usually advisable.
4047 @node Binary Streams
4048 @section Text and Binary Streams
4050 The GNU system and other POSIX-compatible operating systems organize all
4051 files as uniform sequences of characters.  However, some other systems
4052 make a distinction between files containing text and files containing
4053 binary data, and the input and output facilities of @w{ISO C} provide for
4054 this distinction.  This section tells you how to write programs portable
4055 to such systems.
4057 @cindex text stream
4058 @cindex binary stream
4059 When you open a stream, you can specify either a @dfn{text stream} or a
4060 @dfn{binary stream}.  You indicate that you want a binary stream by
4061 specifying the @samp{b} modifier in the @var{opentype} argument to
4062 @code{fopen}; see @ref{Opening Streams}.  Without this
4063 option, @code{fopen} opens the file as a text stream.
4065 Text and binary streams differ in several ways:
4067 @itemize @bullet
4068 @item
4069 The data read from a text stream is divided into @dfn{lines} which are
4070 terminated by newline (@code{'\n'}) characters, while a binary stream is
4071 simply a long series of characters.  A text stream might on some systems
4072 fail to handle lines more than 254 characters long (including the
4073 terminating newline character).
4074 @cindex lines (in a text file)
4076 @item
4077 On some systems, text files can contain only printing characters,
4078 horizontal tab characters, and newlines, and so text streams may not
4079 support other characters.  However, binary streams can handle any
4080 character value.
4082 @item
4083 Space characters that are written immediately preceding a newline
4084 character in a text stream may disappear when the file is read in again.
4086 @item
4087 More generally, there need not be a one-to-one mapping between
4088 characters that are read from or written to a text stream, and the
4089 characters in the actual file.
4090 @end itemize
4092 Since a binary stream is always more capable and more predictable than a
4093 text stream, you might wonder what purpose text streams serve.  Why not
4094 simply always use binary streams?  The answer is that on these operating
4095 systems, text and binary streams use different file formats, and the
4096 only way to read or write ``an ordinary file of text'' that can work
4097 with other text-oriented programs is through a text stream.
4099 In the GNU library, and on all POSIX systems, there is no difference
4100 between text streams and binary streams.  When you open a stream, you
4101 get the same kind of stream regardless of whether you ask for binary.
4102 This stream can handle any file content, and has none of the
4103 restrictions that text streams sometimes have.
4105 @node File Positioning
4106 @section File Positioning
4107 @cindex file positioning on a stream
4108 @cindex positioning a stream
4109 @cindex seeking on a stream
4111 The @dfn{file position} of a stream describes where in the file the
4112 stream is currently reading or writing.  I/O on the stream advances the
4113 file position through the file.  In the GNU system, the file position is
4114 represented as an integer, which counts the number of bytes from the
4115 beginning of the file.  @xref{File Position}.
4117 During I/O to an ordinary disk file, you can change the file position
4118 whenever you wish, so as to read or write any portion of the file.  Some
4119 other kinds of files may also permit this.  Files which support changing
4120 the file position are sometimes referred to as @dfn{random-access}
4121 files.
4123 You can use the functions in this section to examine or modify the file
4124 position indicator associated with a stream.  The symbols listed below
4125 are declared in the header file @file{stdio.h}.
4126 @pindex stdio.h
4128 @comment stdio.h
4129 @comment ISO
4130 @deftypefun {long int} ftell (FILE *@var{stream})
4131 This function returns the current file position of the stream
4132 @var{stream}.
4134 This function can fail if the stream doesn't support file positioning,
4135 or if the file position can't be represented in a @code{long int}, and
4136 possibly for other reasons as well.  If a failure occurs, a value of
4137 @code{-1} is returned.
4138 @end deftypefun
4140 @comment stdio.h
4141 @comment Unix98
4142 @deftypefun off_t ftello (FILE *@var{stream})
4143 The @code{ftello} function is similar to @code{ftell}, except that it
4144 returns a value of type @code{off_t}.  Systems which support this type
4145 use it to describe all file positions, unlike the POSIX specification
4146 which uses a long int.  The two are not necessarily the same size.
4147 Therefore, using ftell can lead to problems if the implementation is
4148 written on top of a POSIX compliant low-level I/O implementation, and using
4149 @code{ftello} is preferable whenever it is available.
4151 If this function fails it returns @code{(off_t) -1}.  This can happen due
4152 to missing support for file positioning or internal errors.  Otherwise
4153 the return value is the current file position.
4155 The function is an extension defined in the Unix Single Specification
4156 version 2.
4158 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4159 32 bit system this function is in fact @code{ftello64}.  I.e., the
4160 LFS interface transparently replaces the old interface.
4161 @end deftypefun
4163 @comment stdio.h
4164 @comment Unix98
4165 @deftypefun off64_t ftello64 (FILE *@var{stream})
4166 This function is similar to @code{ftello} with the only difference that
4167 the return value is of type @code{off64_t}.  This also requires that the
4168 stream @var{stream} was opened using either @code{fopen64},
4169 @code{freopen64}, or @code{tmpfile64} since otherwise the underlying
4170 file operations to position the file pointer beyond the @math{2^31}
4171 bytes limit might fail.
4173 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4174 bits machine this function is available under the name @code{ftello}
4175 and so transparently replaces the old interface.
4176 @end deftypefun
4178 @comment stdio.h
4179 @comment ISO
4180 @deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
4181 The @code{fseek} function is used to change the file position of the
4182 stream @var{stream}.  The value of @var{whence} must be one of the
4183 constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
4184 indicate whether the @var{offset} is relative to the beginning of the
4185 file, the current file position, or the end of the file, respectively.
4187 This function returns a value of zero if the operation was successful,
4188 and a nonzero value to indicate failure.  A successful call also clears
4189 the end-of-file indicator of @var{stream} and discards any characters
4190 that were ``pushed back'' by the use of @code{ungetc}.
4192 @code{fseek} either flushes any buffered output before setting the file
4193 position or else remembers it so it will be written later in its proper
4194 place in the file.
4195 @end deftypefun
4197 @comment stdio.h
4198 @comment Unix98
4199 @deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence})
4200 This function is similar to @code{fseek} but it corrects a problem with
4201 @code{fseek} in a system with POSIX types.  Using a value of type
4202 @code{long int} for the offset is not compatible with POSIX.
4203 @code{fseeko} uses the correct type @code{off_t} for the @var{offset}
4204 parameter.
4206 For this reason it is a good idea to prefer @code{ftello} whenever it is
4207 available since its functionality is (if different at all) closer the
4208 underlying definition.
4210 The functionality and return value is the same as for @code{fseek}.
4212 The function is an extension defined in the Unix Single Specification
4213 version 2.
4215 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4216 32 bit system this function is in fact @code{fseeko64}.  I.e., the
4217 LFS interface transparently replaces the old interface.
4218 @end deftypefun
4220 @comment stdio.h
4221 @comment Unix98
4222 @deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence})
4223 This function is similar to @code{fseeko} with the only difference that
4224 the @var{offset} parameter is of type @code{off64_t}.  This also
4225 requires that the stream @var{stream} was opened using either
4226 @code{fopen64}, @code{freopen64}, or @code{tmpfile64} since otherwise
4227 the underlying file operations to position the file pointer beyond the
4228 @math{2^31} bytes limit might fail.
4230 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4231 bits machine this function is available under the name @code{fseeko}
4232 and so transparently replaces the old interface.
4233 @end deftypefun
4235 @strong{Portability Note:} In non-POSIX systems, @code{ftell},
4236 @code{ftello}, @code{fseek} and @code{fseeko} might work reliably only
4237 on binary streams.  @xref{Binary Streams}.
4239 The following symbolic constants are defined for use as the @var{whence}
4240 argument to @code{fseek}.  They are also used with the @code{lseek}
4241 function (@pxref{I/O Primitives}) and to specify offsets for file locks
4242 (@pxref{Control Operations}).
4244 @comment stdio.h
4245 @comment ISO
4246 @deftypevr Macro int SEEK_SET
4247 This is an integer constant which, when used as the @var{whence}
4248 argument to the @code{fseek} or @code{fseeko} function, specifies that
4249 the offset provided is relative to the beginning of the file.
4250 @end deftypevr
4252 @comment stdio.h
4253 @comment ISO
4254 @deftypevr Macro int SEEK_CUR
4255 This is an integer constant which, when used as the @var{whence}
4256 argument to the @code{fseek} or @code{fseeko} function, specifies that
4257 the offset provided is relative to the current file position.
4258 @end deftypevr
4260 @comment stdio.h
4261 @comment ISO
4262 @deftypevr Macro int SEEK_END
4263 This is an integer constant which, when used as the @var{whence}
4264 argument to the @code{fseek} or @code{fseeko} function, specifies that
4265 the offset provided is relative to the end of the file.
4266 @end deftypevr
4268 @comment stdio.h
4269 @comment ISO
4270 @deftypefun void rewind (FILE *@var{stream})
4271 The @code{rewind} function positions the stream @var{stream} at the
4272 beginning of the file.  It is equivalent to calling @code{fseek} or
4273 @code{fseeko} on the @var{stream} with an @var{offset} argument of
4274 @code{0L} and a @var{whence} argument of @code{SEEK_SET}, except that
4275 the return value is discarded and the error indicator for the stream is
4276 reset.
4277 @end deftypefun
4279 These three aliases for the @samp{SEEK_@dots{}} constants exist for the
4280 sake of compatibility with older BSD systems.  They are defined in two
4281 different header files: @file{fcntl.h} and @file{sys/file.h}.
4283 @table @code
4284 @comment sys/file.h
4285 @comment BSD
4286 @item L_SET
4287 @vindex L_SET
4288 An alias for @code{SEEK_SET}.
4290 @comment sys/file.h
4291 @comment BSD
4292 @item L_INCR
4293 @vindex L_INCR
4294 An alias for @code{SEEK_CUR}.
4296 @comment sys/file.h
4297 @comment BSD
4298 @item L_XTND
4299 @vindex L_XTND
4300 An alias for @code{SEEK_END}.
4301 @end table
4303 @node Portable Positioning
4304 @section Portable File-Position Functions
4306 On the GNU system, the file position is truly a character count.  You
4307 can specify any character count value as an argument to @code{fseek} or
4308 @code{fseeko} and get reliable results for any random access file.
4309 However, some @w{ISO C} systems do not represent file positions in this
4310 way.
4312 On some systems where text streams truly differ from binary streams, it
4313 is impossible to represent the file position of a text stream as a count
4314 of characters from the beginning of the file.  For example, the file
4315 position on some systems must encode both a record offset within the
4316 file, and a character offset within the record.
4318 As a consequence, if you want your programs to be portable to these
4319 systems, you must observe certain rules:
4321 @itemize @bullet
4322 @item
4323 The value returned from @code{ftell} on a text stream has no predictable
4324 relationship to the number of characters you have read so far.  The only
4325 thing you can rely on is that you can use it subsequently as the
4326 @var{offset} argument to @code{fseek} or @code{fseeko} to move back to
4327 the same file position.
4329 @item
4330 In a call to @code{fseek} or @code{fseeko} on a text stream, either the
4331 @var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and
4332 and the @var{offset} must be the result of an earlier call to @code{ftell}
4333 on the same stream.
4335 @item
4336 The value of the file position indicator of a text stream is undefined
4337 while there are characters that have been pushed back with @code{ungetc}
4338 that haven't been read or discarded.  @xref{Unreading}.
4339 @end itemize
4341 But even if you observe these rules, you may still have trouble for long
4342 files, because @code{ftell} and @code{fseek} use a @code{long int} value
4343 to represent the file position.  This type may not have room to encode
4344 all the file positions in a large file.  Using the @code{ftello} and
4345 @code{fseeko} functions might help here since the @code{off_t} type is
4346 expected to be able to hold all file position values but this still does
4347 not help to handle additional information which must be associated with
4348 a file position.
4350 So if you do want to support systems with peculiar encodings for the
4351 file positions, it is better to use the functions @code{fgetpos} and
4352 @code{fsetpos} instead.  These functions represent the file position
4353 using the data type @code{fpos_t}, whose internal representation varies
4354 from system to system.
4356 These symbols are declared in the header file @file{stdio.h}.
4357 @pindex stdio.h
4359 @comment stdio.h
4360 @comment ISO
4361 @deftp {Data Type} fpos_t
4362 This is the type of an object that can encode information about the
4363 file position of a stream, for use by the functions @code{fgetpos} and
4364 @code{fsetpos}.
4366 In the GNU system, @code{fpos_t} is an opaque data structure that
4367 contains internal data to represent file offset and conversion state
4368 information.  In other systems, it might have a different internal
4369 representation.
4371 When compiling with @code{_FILE_OFFSET_BITS == 64} on a 32 bit machine
4372 this type is in fact equivalent to @code{fpos64_t} since the LFS
4373 interface transparently replaces the old interface.
4374 @end deftp
4376 @comment stdio.h
4377 @comment Unix98
4378 @deftp {Data Type} fpos64_t
4379 This is the type of an object that can encode information about the
4380 file position of a stream, for use by the functions @code{fgetpos64} and
4381 @code{fsetpos64}.
4383 In the GNU system, @code{fpos64_t} is an opaque data structure that
4384 contains internal data to represent file offset and conversion state
4385 information.  In other systems, it might have a different internal
4386 representation.
4387 @end deftp
4389 @comment stdio.h
4390 @comment ISO
4391 @deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
4392 This function stores the value of the file position indicator for the
4393 stream @var{stream} in the @code{fpos_t} object pointed to by
4394 @var{position}.  If successful, @code{fgetpos} returns zero; otherwise
4395 it returns a nonzero value and stores an implementation-defined positive
4396 value in @code{errno}.
4398 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4399 32 bit system the function is in fact @code{fgetpos64}.  I.e., the LFS
4400 interface transparently replaces the old interface.
4401 @end deftypefun
4403 @comment stdio.h
4404 @comment Unix98
4405 @deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position})
4406 This function is similar to @code{fgetpos} but the file position is
4407 returned in a variable of type @code{fpos64_t} to which @var{position}
4408 points.
4410 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4411 bits machine this function is available under the name @code{fgetpos}
4412 and so transparently replaces the old interface.
4413 @end deftypefun
4415 @comment stdio.h
4416 @comment ISO
4417 @deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position})
4418 This function sets the file position indicator for the stream @var{stream}
4419 to the position @var{position}, which must have been set by a previous
4420 call to @code{fgetpos} on the same stream.  If successful, @code{fsetpos}
4421 clears the end-of-file indicator on the stream, discards any characters
4422 that were ``pushed back'' by the use of @code{ungetc}, and returns a value
4423 of zero.  Otherwise, @code{fsetpos} returns a nonzero value and stores
4424 an implementation-defined positive value in @code{errno}.
4426 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
4427 32 bit system the function is in fact @code{fsetpos64}.  I.e., the LFS
4428 interface transparently replaces the old interface.
4429 @end deftypefun
4431 @comment stdio.h
4432 @comment Unix98
4433 @deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position})
4434 This function is similar to @code{fsetpos} but the file position used
4435 for positioning is provided in a variable of type @code{fpos64_t} to
4436 which @var{position} points.
4438 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
4439 bits machine this function is available under the name @code{fsetpos}
4440 and so transparently replaces the old interface.
4441 @end deftypefun
4443 @node Stream Buffering
4444 @section Stream Buffering
4446 @cindex buffering of streams
4447 Characters that are written to a stream are normally accumulated and
4448 transmitted asynchronously to the file in a block, instead of appearing
4449 as soon as they are output by the application program.  Similarly,
4450 streams often retrieve input from the host environment in blocks rather
4451 than on a character-by-character basis.  This is called @dfn{buffering}.
4453 If you are writing programs that do interactive input and output using
4454 streams, you need to understand how buffering works when you design the
4455 user interface to your program.  Otherwise, you might find that output
4456 (such as progress or prompt messages) doesn't appear when you intended
4457 it to, or displays some other unexpected behavior.
4459 This section deals only with controlling when characters are transmitted
4460 between the stream and the file or device, and @emph{not} with how
4461 things like echoing, flow control, and the like are handled on specific
4462 classes of devices.  For information on common control operations on
4463 terminal devices, see @ref{Low-Level Terminal Interface}.
4465 You can bypass the stream buffering facilities altogether by using the
4466 low-level input and output functions that operate on file descriptors
4467 instead.  @xref{Low-Level I/O}.
4469 @menu
4470 * Buffering Concepts::          Terminology is defined here.
4471 * Flushing Buffers::            How to ensure that output buffers are flushed.
4472 * Controlling Buffering::       How to specify what kind of buffering to use.
4473 @end menu
4475 @node Buffering Concepts
4476 @subsection Buffering Concepts
4478 There are three different kinds of buffering strategies:
4480 @itemize @bullet
4481 @item
4482 Characters written to or read from an @dfn{unbuffered} stream are
4483 transmitted individually to or from the file as soon as possible.
4484 @cindex unbuffered stream
4486 @item
4487 Characters written to a @dfn{line buffered} stream are transmitted to
4488 the file in blocks when a newline character is encountered.
4489 @cindex line buffered stream
4491 @item
4492 Characters written to or read from a @dfn{fully buffered} stream are
4493 transmitted to or from the file in blocks of arbitrary size.
4494 @cindex fully buffered stream
4495 @end itemize
4497 Newly opened streams are normally fully buffered, with one exception: a
4498 stream connected to an interactive device such as a terminal is
4499 initially line buffered.  @xref{Controlling Buffering}, for information
4500 on how to select a different kind of buffering.  Usually the automatic
4501 selection gives you the most convenient kind of buffering for the file
4502 or device you open.
4504 The use of line buffering for interactive devices implies that output
4505 messages ending in a newline will appear immediately---which is usually
4506 what you want.  Output that doesn't end in a newline might or might not
4507 show up immediately, so if you want them to appear immediately, you
4508 should flush buffered output explicitly with @code{fflush}, as described
4509 in @ref{Flushing Buffers}.
4511 @node Flushing Buffers
4512 @subsection Flushing Buffers
4514 @cindex flushing a stream
4515 @dfn{Flushing} output on a buffered stream means transmitting all
4516 accumulated characters to the file.  There are many circumstances when
4517 buffered output on a stream is flushed automatically:
4519 @itemize @bullet
4520 @item
4521 When you try to do output and the output buffer is full.
4523 @item
4524 When the stream is closed.  @xref{Closing Streams}.
4526 @item
4527 When the program terminates by calling @code{exit}.
4528 @xref{Normal Termination}.
4530 @item
4531 When a newline is written, if the stream is line buffered.
4533 @item
4534 Whenever an input operation on @emph{any} stream actually reads data
4535 from its file.
4536 @end itemize
4538 If you want to flush the buffered output at another time, call
4539 @code{fflush}, which is declared in the header file @file{stdio.h}.
4540 @pindex stdio.h
4542 @comment stdio.h
4543 @comment ISO
4544 @deftypefun int fflush (FILE *@var{stream})
4545 This function causes any buffered output on @var{stream} to be delivered
4546 to the file.  If @var{stream} is a null pointer, then
4547 @code{fflush} causes buffered output on @emph{all} open output streams
4548 to be flushed.
4550 This function returns @code{EOF} if a write error occurs, or zero
4551 otherwise.
4552 @end deftypefun
4554 @comment stdio.h
4555 @comment POSIX
4556 @deftypefun int fflush_unlocked (FILE *@var{stream})
4557 The @code{fflush_unlocked} function is equivalent to the @code{fflush}
4558 function except that it does not implicitly lock the stream.
4559 @end deftypefun
4561 The @code{fflush} function can be used to flush all streams currently
4562 opened.  While this is useful in some situations it does often more than
4563 necessary since it might be done in situations when terminal input is
4564 required and the program wants to be sure that all output is visible on
4565 the terminal.  But this means that only line buffered streams have to be
4566 flushed.  Solaris introduced a function especially for this.  It was
4567 always available in the GNU C library in some form but never officially
4568 exported.
4570 @comment stdio_ext.h
4571 @comment GNU
4572 @deftypefun void _flushlbf (void)
4573 The @code{_flushlbf} function flushes all line buffered streams
4574 currently opened.
4576 This function is declared in the @file{stdio_ext.h} header.
4577 @end deftypefun
4579 @strong{Compatibility Note:} Some brain-damaged operating systems have
4580 been known to be so thoroughly fixated on line-oriented input and output
4581 that flushing a line buffered stream causes a newline to be written!
4582 Fortunately, this ``feature'' seems to be becoming less common.  You do
4583 not need to worry about this in the GNU system.
4585 In some situations it might be useful to not flush the output pending
4586 for a stream but instead simply forget it.  If transmission is costly
4587 and the output is not needed anymore this is valid reasoning.  In this
4588 situation a non-standard function introduced in Solaris and available in
4589 the GNU C library can be used.
4591 @comment stdio_ext.h
4592 @comment GNU
4593 @deftypefun void __fpurge (FILE *@var{stream})
4594 The @code{__fpurge} function causes the buffer of the stream
4595 @var{stream} to be emptied.  If the stream is currently in read mode all
4596 input in the buffer is lost.  If the stream is in output mode the
4597 buffered output is not written to the device (or whatever other
4598 underlying storage) and the buffer the cleared.
4600 This function is declared in @file{stdio_ext.h}.
4601 @end deftypefun
4603 @node Controlling Buffering
4604 @subsection Controlling Which Kind of Buffering
4606 After opening a stream (but before any other operations have been
4607 performed on it), you can explicitly specify what kind of buffering you
4608 want it to have using the @code{setvbuf} function.
4609 @cindex buffering, controlling
4611 The facilities listed in this section are declared in the header
4612 file @file{stdio.h}.
4613 @pindex stdio.h
4615 @comment stdio.h
4616 @comment ISO
4617 @deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
4618 This function is used to specify that the stream @var{stream} should
4619 have the buffering mode @var{mode}, which can be either @code{_IOFBF}
4620 (for full buffering), @code{_IOLBF} (for line buffering), or
4621 @code{_IONBF} (for unbuffered input/output).
4623 If you specify a null pointer as the @var{buf} argument, then @code{setvbuf}
4624 allocates a buffer itself using @code{malloc}.  This buffer will be freed
4625 when you close the stream.
4627 Otherwise, @var{buf} should be a character array that can hold at least
4628 @var{size} characters.  You should not free the space for this array as
4629 long as the stream remains open and this array remains its buffer.  You
4630 should usually either allocate it statically, or @code{malloc}
4631 (@pxref{Unconstrained Allocation}) the buffer.  Using an automatic array
4632 is not a good idea unless you close the file before exiting the block
4633 that declares the array.
4635 While the array remains a stream buffer, the stream I/O functions will
4636 use the buffer for their internal purposes.  You shouldn't try to access
4637 the values in the array directly while the stream is using it for
4638 buffering.
4640 The @code{setvbuf} function returns zero on success, or a nonzero value
4641 if the value of @var{mode} is not valid or if the request could not
4642 be honored.
4643 @end deftypefun
4645 @comment stdio.h
4646 @comment ISO
4647 @deftypevr Macro int _IOFBF
4648 The value of this macro is an integer constant expression that can be
4649 used as the @var{mode} argument to the @code{setvbuf} function to
4650 specify that the stream should be fully buffered.
4651 @end deftypevr
4653 @comment stdio.h
4654 @comment ISO
4655 @deftypevr Macro int _IOLBF
4656 The value of this macro is an integer constant expression that can be
4657 used as the @var{mode} argument to the @code{setvbuf} function to
4658 specify that the stream should be line buffered.
4659 @end deftypevr
4661 @comment stdio.h
4662 @comment ISO
4663 @deftypevr Macro int _IONBF
4664 The value of this macro is an integer constant expression that can be
4665 used as the @var{mode} argument to the @code{setvbuf} function to
4666 specify that the stream should be unbuffered.
4667 @end deftypevr
4669 @comment stdio.h
4670 @comment ISO
4671 @deftypevr Macro int BUFSIZ
4672 The value of this macro is an integer constant expression that is good
4673 to use for the @var{size} argument to @code{setvbuf}.  This value is
4674 guaranteed to be at least @code{256}.
4676 The value of @code{BUFSIZ} is chosen on each system so as to make stream
4677 I/O efficient.  So it is a good idea to use @code{BUFSIZ} as the size
4678 for the buffer when you call @code{setvbuf}.
4680 Actually, you can get an even better value to use for the buffer size
4681 by means of the @code{fstat} system call: it is found in the
4682 @code{st_blksize} field of the file attributes.  @xref{Attribute Meanings}.
4684 Sometimes people also use @code{BUFSIZ} as the allocation size of
4685 buffers used for related purposes, such as strings used to receive a
4686 line of input with @code{fgets} (@pxref{Character Input}).  There is no
4687 particular reason to use @code{BUFSIZ} for this instead of any other
4688 integer, except that it might lead to doing I/O in chunks of an
4689 efficient size.
4690 @end deftypevr
4692 @comment stdio.h
4693 @comment ISO
4694 @deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
4695 If @var{buf} is a null pointer, the effect of this function is
4696 equivalent to calling @code{setvbuf} with a @var{mode} argument of
4697 @code{_IONBF}.  Otherwise, it is equivalent to calling @code{setvbuf}
4698 with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size}
4699 argument of @code{BUFSIZ}.
4701 The @code{setbuf} function is provided for compatibility with old code;
4702 use @code{setvbuf} in all new programs.
4703 @end deftypefun
4705 @comment stdio.h
4706 @comment BSD
4707 @deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
4708 If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
4709 Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
4710 buffer.  The @var{size} argument specifies the length of @var{buf}.
4712 This function is provided for compatibility with old BSD code.  Use
4713 @code{setvbuf} instead.
4714 @end deftypefun
4716 @comment stdio.h
4717 @comment BSD
4718 @deftypefun void setlinebuf (FILE *@var{stream})
4719 This function makes @var{stream} be line buffered, and allocates the
4720 buffer for you.
4722 This function is provided for compatibility with old BSD code.  Use
4723 @code{setvbuf} instead.
4724 @end deftypefun
4726 It is possible to query whether a given stream is line buffered or not
4727 using a non-standard function introduced in Solaris and available in the
4728 GNU C library.
4730 @comment stdio_ext.h
4731 @comment GNU
4732 @deftypefun int __flbf (FILE *@var{stream})
4733 The @code{__flbf} function will return a nonzero value in case the
4734 stream @var{stream} is line buffered.  Otherwise the return value is
4735 zero.
4737 This function is declared in the @file{stdio_ext.h} header.
4738 @end deftypefun
4740 Two more extensions allow to determine the size of the buffer and how
4741 much of it is used.  These functions were also introduced in Solaris.
4743 @comment stdio_ext.h
4744 @comment GNU
4745 @deftypefun size_t __fbufsize (FILE *@var{stream})
4746 The @code{__fbufsize} function return the size of the buffer in the
4747 stream @var{stream}.  This value can be used to optimize the use of the
4748 stream.
4750 This function is declared in the @file{stdio_ext.h} header.
4751 @end deftypefun
4753 @comment stdio_ext.h
4754 @comment GNU
4755 @deftypefun size_t __fpending (FILE *@var{stream}) The @code{__fpending}
4756 function returns the number of bytes currently in the output buffer.
4757 For wide-oriented stream the measuring unit is wide characters.  This
4758 function should not be used on buffers in read mode or opened read-only.
4760 This function is declared in the @file{stdio_ext.h} header.
4761 @end deftypefun
4763 @node Other Kinds of Streams
4764 @section Other Kinds of Streams
4766 The GNU library provides ways for you to define additional kinds of
4767 streams that do not necessarily correspond to an open file.
4769 One such type of stream takes input from or writes output to a string.
4770 These kinds of streams are used internally to implement the
4771 @code{sprintf} and @code{sscanf} functions.  You can also create such a
4772 stream explicitly, using the functions described in @ref{String Streams}.
4774 More generally, you can define streams that do input/output to arbitrary
4775 objects using functions supplied by your program.  This protocol is
4776 discussed in @ref{Custom Streams}.
4778 @strong{Portability Note:} The facilities described in this section are
4779 specific to GNU.  Other systems or C implementations might or might not
4780 provide equivalent functionality.
4782 @menu
4783 * String Streams::              Streams that get data from or put data in
4784                                  a string or memory buffer.
4785 * Obstack Streams::             Streams that store data in an obstack.
4786 * Custom Streams::              Defining your own streams with an arbitrary
4787                                  input data source and/or output data sink.
4788 @end menu
4790 @node String Streams
4791 @subsection String Streams
4793 @cindex stream, for I/O to a string
4794 @cindex string stream
4795 The @code{fmemopen} and @code{open_memstream} functions allow you to do
4796 I/O to a string or memory buffer.  These facilities are declared in
4797 @file{stdio.h}.
4798 @pindex stdio.h
4800 @comment stdio.h
4801 @comment GNU
4802 @deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
4803 This function opens a stream that allows the access specified by the
4804 @var{opentype} argument, that reads from or writes to the buffer specified
4805 by the argument @var{buf}.  This array must be at least @var{size} bytes long.
4807 If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
4808 dynamically allocates an array @var{size} bytes long (as with @code{malloc};
4809 @pxref{Unconstrained Allocation}).  This is really only useful
4810 if you are going to write things to the buffer and then read them back
4811 in again, because you have no way of actually getting a pointer to the
4812 buffer (for this, try @code{open_memstream}, below).  The buffer is
4813 freed when the stream is closed.
4815 The argument @var{opentype} is the same as in @code{fopen}
4816 (@pxref{Opening Streams}).  If the @var{opentype} specifies
4817 append mode, then the initial file position is set to the first null
4818 character in the buffer.  Otherwise the initial file position is at the
4819 beginning of the buffer.
4821 When a stream open for writing is flushed or closed, a null character
4822 (zero byte) is written at the end of the buffer if it fits.  You
4823 should add an extra byte to the @var{size} argument to account for this.
4824 Attempts to write more than @var{size} bytes to the buffer result
4825 in an error.
4827 For a stream open for reading, null characters (zero bytes) in the
4828 buffer do not count as ``end of file''.  Read operations indicate end of
4829 file only when the file position advances past @var{size} bytes.  So, if
4830 you want to read characters from a null-terminated string, you should
4831 supply the length of the string as the @var{size} argument.
4832 @end deftypefun
4834 Here is an example of using @code{fmemopen} to create a stream for
4835 reading from a string:
4837 @smallexample
4838 @include memopen.c.texi
4839 @end smallexample
4841 This program produces the following output:
4843 @smallexample
4844 Got f
4845 Got o
4846 Got o
4847 Got b
4848 Got a
4849 Got r
4850 @end smallexample
4852 @comment stdio.h
4853 @comment GNU
4854 @deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
4855 This function opens a stream for writing to a buffer.  The buffer is
4856 allocated dynamically and grown as necessary, using @code{malloc}.
4857 After you've closed the stream, this buffer is your responsibility to
4858 clean up using @code{free} or @code{realloc}.  @xref{Unconstrained Allocation}.
4860 When the stream is closed with @code{fclose} or flushed with
4861 @code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
4862 contain the pointer to the buffer and its size.  The values thus stored
4863 remain valid only as long as no further output on the stream takes
4864 place.  If you do more output, you must flush the stream again to store
4865 new values before you use them again.
4867 A null character is written at the end of the buffer.  This null character
4868 is @emph{not} included in the size value stored at @var{sizeloc}.
4870 You can move the stream's file position with @code{fseek} or
4871 @code{fseeko} (@pxref{File Positioning}).  Moving the file position past
4872 the end of the data already written fills the intervening space with
4873 zeroes.
4874 @end deftypefun
4876 Here is an example of using @code{open_memstream}:
4878 @smallexample
4879 @include memstrm.c.texi
4880 @end smallexample
4882 This program produces the following output:
4884 @smallexample
4885 buf = `hello', size = 5
4886 buf = `hello, world', size = 12
4887 @end smallexample
4889 @c @group  Invalid outside @example.
4890 @node Obstack Streams
4891 @subsection Obstack Streams
4893 You can open an output stream that puts it data in an obstack.
4894 @xref{Obstacks}.
4896 @comment stdio.h
4897 @comment GNU
4898 @deftypefun {FILE *} open_obstack_stream (struct obstack *@var{obstack})
4899 This function opens a stream for writing data into the obstack @var{obstack}.
4900 This starts an object in the obstack and makes it grow as data is
4901 written (@pxref{Growing Objects}).
4902 @c @end group  Doubly invalid because not nested right.
4904 Calling @code{fflush} on this stream updates the current size of the
4905 object to match the amount of data that has been written.  After a call
4906 to @code{fflush}, you can examine the object temporarily.
4908 You can move the file position of an obstack stream with @code{fseek} or
4909 @code{fseeko} (@pxref{File Positioning}).  Moving the file position past
4910 the end of the data written fills the intervening space with zeros.
4912 To make the object permanent, update the obstack with @code{fflush}, and
4913 then use @code{obstack_finish} to finalize the object and get its address.
4914 The following write to the stream starts a new object in the obstack,
4915 and later writes add to that object until you do another @code{fflush}
4916 and @code{obstack_finish}.
4918 But how do you find out how long the object is?  You can get the length
4919 in bytes by calling @code{obstack_object_size} (@pxref{Status of an
4920 Obstack}), or you can null-terminate the object like this:
4922 @smallexample
4923 obstack_1grow (@var{obstack}, 0);
4924 @end smallexample
4926 Whichever one you do, you must do it @emph{before} calling
4927 @code{obstack_finish}.  (You can do both if you wish.)
4928 @end deftypefun
4930 Here is a sample function that uses @code{open_obstack_stream}:
4932 @smallexample
4933 char *
4934 make_message_string (const char *a, int b)
4936   FILE *stream = open_obstack_stream (&message_obstack);
4937   output_task (stream);
4938   fprintf (stream, ": ");
4939   fprintf (stream, a, b);
4940   fprintf (stream, "\n");
4941   fclose (stream);
4942   obstack_1grow (&message_obstack, 0);
4943   return obstack_finish (&message_obstack);
4945 @end smallexample
4947 @node Custom Streams
4948 @subsection Programming Your Own Custom Streams
4949 @cindex custom streams
4950 @cindex programming your own streams
4952 This section describes how you can make a stream that gets input from an
4953 arbitrary data source or writes output to an arbitrary data sink
4954 programmed by you.  We call these @dfn{custom streams}.  The functions
4955 and types described here are all GNU extensions.
4957 @c !!! this does not talk at all about the higher-level hooks
4959 @menu
4960 * Streams and Cookies::         The @dfn{cookie} records where to fetch or
4961                                  store data that is read or written.
4962 * Hook Functions::              How you should define the four @dfn{hook
4963                                  functions} that a custom stream needs.
4964 @end menu
4966 @node Streams and Cookies
4967 @subsubsection Custom Streams and Cookies
4968 @cindex cookie, for custom stream
4970 Inside every custom stream is a special object called the @dfn{cookie}.
4971 This is an object supplied by you which records where to fetch or store
4972 the data read or written.  It is up to you to define a data type to use
4973 for the cookie.  The stream functions in the library never refer
4974 directly to its contents, and they don't even know what the type is;
4975 they record its address with type @code{void *}.
4977 To implement a custom stream, you must specify @emph{how} to fetch or
4978 store the data in the specified place.  You do this by defining
4979 @dfn{hook functions} to read, write, change ``file position'', and close
4980 the stream.  All four of these functions will be passed the stream's
4981 cookie so they can tell where to fetch or store the data.  The library
4982 functions don't know what's inside the cookie, but your functions will
4983 know.
4985 When you create a custom stream, you must specify the cookie pointer,
4986 and also the four hook functions stored in a structure of type
4987 @code{cookie_io_functions_t}.
4989 These facilities are declared in @file{stdio.h}.
4990 @pindex stdio.h
4992 @comment stdio.h
4993 @comment GNU
4994 @deftp {Data Type} {cookie_io_functions_t}
4995 This is a structure type that holds the functions that define the
4996 communications protocol between the stream and its cookie.  It has
4997 the following members:
4999 @table @code
5000 @item cookie_read_function_t *read
5001 This is the function that reads data from the cookie.  If the value is a
5002 null pointer instead of a function, then read operations on this stream
5003 always return @code{EOF}.
5005 @item cookie_write_function_t *write
5006 This is the function that writes data to the cookie.  If the value is a
5007 null pointer instead of a function, then data written to the stream is
5008 discarded.
5010 @item cookie_seek_function_t *seek
5011 This is the function that performs the equivalent of file positioning on
5012 the cookie.  If the value is a null pointer instead of a function, calls
5013 to @code{fseek} or @code{fseeko} on this stream can only seek to
5014 locations within the buffer; any attempt to seek outside the buffer will
5015 return an @code{ESPIPE} error.
5017 @item cookie_close_function_t *close
5018 This function performs any appropriate cleanup on the cookie when
5019 closing the stream.  If the value is a null pointer instead of a
5020 function, nothing special is done to close the cookie when the stream is
5021 closed.
5022 @end table
5023 @end deftp
5025 @comment stdio.h
5026 @comment GNU
5027 @deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions})
5028 This function actually creates the stream for communicating with the
5029 @var{cookie} using the functions in the @var{io-functions} argument.
5030 The @var{opentype} argument is interpreted as for @code{fopen};
5031 see @ref{Opening Streams}.  (But note that the ``truncate on
5032 open'' option is ignored.)  The new stream is fully buffered.
5034 The @code{fopencookie} function returns the newly created stream, or a null
5035 pointer in case of an error.
5036 @end deftypefun
5038 @node Hook Functions
5039 @subsubsection Custom Stream Hook Functions
5040 @cindex hook functions (of custom streams)
5042 Here are more details on how you should define the four hook functions
5043 that a custom stream needs.
5045 You should define the function to read data from the cookie as:
5047 @smallexample
5048 ssize_t @var{reader} (void *@var{cookie}, char *@var{buffer}, size_t @var{size})
5049 @end smallexample
5051 This is very similar to the @code{read} function; see @ref{I/O
5052 Primitives}.  Your function should transfer up to @var{size} bytes into
5053 the @var{buffer}, and return the number of bytes read, or zero to
5054 indicate end-of-file.  You can return a value of @code{-1} to indicate
5055 an error.
5057 You should define the function to write data to the cookie as:
5059 @smallexample
5060 ssize_t @var{writer} (void *@var{cookie}, const char *@var{buffer}, size_t @var{size})
5061 @end smallexample
5063 This is very similar to the @code{write} function; see @ref{I/O
5064 Primitives}.  Your function should transfer up to @var{size} bytes from
5065 the buffer, and return the number of bytes written.  You can return a
5066 value of @code{-1} to indicate an error.
5068 You should define the function to perform seek operations on the cookie
5071 @smallexample
5072 int @var{seeker} (void *@var{cookie}, off64_t *@var{position}, int @var{whence})
5073 @end smallexample
5075 For this function, the @var{position} and @var{whence} arguments are
5076 interpreted as for @code{fgetpos}; see @ref{Portable Positioning}.
5078 After doing the seek operation, your function should store the resulting
5079 file position relative to the beginning of the file in @var{position}.
5080 Your function should return a value of @code{0} on success and @code{-1}
5081 to indicate an error.
5083 You should define the function to do cleanup operations on the cookie
5084 appropriate for closing the stream as:
5086 @smallexample
5087 int @var{cleaner} (void *@var{cookie})
5088 @end smallexample
5090 Your function should return @code{-1} to indicate an error, and @code{0}
5091 otherwise.
5093 @comment stdio.h
5094 @comment GNU
5095 @deftp {Data Type} cookie_read_function
5096 This is the data type that the read function for a custom stream should have.
5097 If you declare the function as shown above, this is the type it will have.
5098 @end deftp
5100 @comment stdio.h
5101 @comment GNU
5102 @deftp {Data Type} cookie_write_function
5103 The data type of the write function for a custom stream.
5104 @end deftp
5106 @comment stdio.h
5107 @comment GNU
5108 @deftp {Data Type} cookie_seek_function
5109 The data type of the seek function for a custom stream.
5110 @end deftp
5112 @comment stdio.h
5113 @comment GNU
5114 @deftp {Data Type} cookie_close_function
5115 The data type of the close function for a custom stream.
5116 @end deftp
5118 @ignore
5119 Roland says:
5121 @quotation
5122 There is another set of functions one can give a stream, the
5123 input-room and output-room functions.  These functions must
5124 understand stdio internals.  To describe how to use these
5125 functions, you also need to document lots of how stdio works
5126 internally (which isn't relevant for other uses of stdio).
5127 Perhaps I can write an interface spec from which you can write
5128 good documentation.  But it's pretty complex and deals with lots
5129 of nitty-gritty details.  I think it might be better to let this
5130 wait until the rest of the manual is more done and polished.
5131 @end quotation
5132 @end ignore
5134 @c ??? This section could use an example.
5137 @node Formatted Messages
5138 @section Formatted Messages
5139 @cindex formatted messages
5141 On systems which are based on System V messages of programs (especially
5142 the system tools) are printed in a strict form using the @code{fmtmsg}
5143 function.  The uniformity sometimes helps the user to interpret messages
5144 and the strictness tests of the @code{fmtmsg} function ensure that the
5145 programmer follows some minimal requirements.
5147 @menu
5148 * Printing Formatted Messages::   The @code{fmtmsg} function.
5149 * Adding Severity Classes::       Add more severity classes.
5150 * Example::                       How to use @code{fmtmsg} and @code{addseverity}.
5151 @end menu
5154 @node Printing Formatted Messages
5155 @subsection Printing Formatted Messages
5157 Messages can be printed to standard error and/or to the console.  To
5158 select the destination the programmer can use the following two values,
5159 bitwise OR combined if wanted, for the @var{classification} parameter of
5160 @code{fmtmsg}:
5162 @vtable @code
5163 @item MM_PRINT
5164 Display the message in standard error.
5165 @item MM_CONSOLE
5166 Display the message on the system console.
5167 @end vtable
5169 The erroneous piece of the system can be signalled by exactly one of the
5170 following values which also is bitwise ORed with the
5171 @var{classification} parameter to @code{fmtmsg}:
5173 @vtable @code
5174 @item MM_HARD
5175 The source of the condition is some hardware.
5176 @item MM_SOFT
5177 The source of the condition is some software.
5178 @item MM_FIRM
5179 The source of the condition is some firmware.
5180 @end vtable
5182 A third component of the @var{classification} parameter to @code{fmtmsg}
5183 can describe the part of the system which detects the problem.  This is
5184 done by using exactly one of the following values:
5186 @vtable @code
5187 @item MM_APPL
5188 The erroneous condition is detected by the application.
5189 @item MM_UTIL
5190 The erroneous condition is detected by a utility.
5191 @item MM_OPSYS
5192 The erroneous condition is detected by the operating system.
5193 @end vtable
5195 A last component of @var{classification} can signal the results of this
5196 message.  Exactly one of the following values can be used:
5198 @vtable @code
5199 @item MM_RECOVER
5200 It is a recoverable error.
5201 @item MM_NRECOV
5202 It is a non-recoverable error.
5203 @end vtable
5205 @comment fmtmsg.h
5206 @comment XPG
5207 @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})
5208 Display a message described by its parameters on the device(s) specified
5209 in the @var{classification} parameter.  The @var{label} parameter
5210 identifies the source of the message.  The string should consist of two
5211 colon separated parts where the first part has not more than 10 and the
5212 second part not more than 14 characters.  The @var{text} parameter
5213 describes the condition of the error, the @var{action} parameter possible
5214 steps to recover from the error and the @var{tag} parameter is a
5215 reference to the online documentation where more information can be
5216 found.  It should contain the @var{label} value and a unique
5217 identification number.
5219 Each of the parameters can be a special value which means this value
5220 is to be omitted.  The symbolic names for these values are:
5222 @vtable @code
5223 @item MM_NULLLBL
5224 Ignore @var{label} parameter.
5225 @item MM_NULLSEV
5226 Ignore @var{severity} parameter.
5227 @item MM_NULLMC
5228 Ignore @var{classification} parameter.  This implies that nothing is
5229 actually printed.
5230 @item MM_NULLTXT
5231 Ignore @var{text} parameter.
5232 @item MM_NULLACT
5233 Ignore @var{action} parameter.
5234 @item MM_NULLTAG
5235 Ignore @var{tag} parameter.
5236 @end vtable
5238 There is another way certain fields can be omitted from the output to
5239 standard error.  This is described below in the description of
5240 environment variables influencing the behavior.
5242 The @var{severity} parameter can have one of the values in the following
5243 table:
5244 @cindex severity class
5246 @vtable @code
5247 @item MM_NOSEV
5248 Nothing is printed, this value is the same as @code{MM_NULLSEV}.
5249 @item MM_HALT
5250 This value is printed as @code{HALT}.
5251 @item MM_ERROR
5252 This value is printed as @code{ERROR}.
5253 @item MM_WARNING
5254 This value is printed as @code{WARNING}.
5255 @item MM_INFO
5256 This value is printed as @code{INFO}.
5257 @end vtable
5259 The numeric value of these five macros are between @code{0} and
5260 @code{4}.  Using the environment variable @code{SEV_LEVEL} or using the
5261 @code{addseverity} function one can add more severity levels with their
5262 corresponding string to print.  This is described below
5263 (@pxref{Adding Severity Classes}).
5265 @noindent
5266 If no parameter is ignored the output looks like this:
5268 @smallexample
5269 @var{label}: @var{severity-string}: @var{text}
5270 TO FIX: @var{action} @var{tag}
5271 @end smallexample
5273 The colons, new line characters and the @code{TO FIX} string are
5274 inserted if necessary, i.e., if the corresponding parameter is not
5275 ignored.
5277 This function is specified in the X/Open Portability Guide.  It is also
5278 available on all systems derived from System V.
5280 The function returns the value @code{MM_OK} if no error occurred.  If
5281 only the printing to standard error failed, it returns @code{MM_NOMSG}.
5282 If printing to the console fails, it returns @code{MM_NOCON}.  If
5283 nothing is printed @code{MM_NOTOK} is returned.  Among situations where
5284 all outputs fail this last value is also returned if a parameter value
5285 is incorrect.
5286 @end deftypefun
5288 There are two environment variables which influence the behavior of
5289 @code{fmtmsg}.  The first is @code{MSGVERB}.  It is used to control the
5290 output actually happening on standard error (@emph{not} the console
5291 output).  Each of the five fields can explicitly be enabled.  To do
5292 this the user has to put the @code{MSGVERB} variable with a format like
5293 the following in the environment before calling the @code{fmtmsg} function
5294 the first time:
5296 @smallexample
5297 MSGVERB=@var{keyword}[:@var{keyword}[:@dots{}]]
5298 @end smallexample
5300 Valid @var{keyword}s are @code{label}, @code{severity}, @code{text},
5301 @code{action}, and @code{tag}.  If the environment variable is not given
5302 or is the empty string, a not supported keyword is given or the value is
5303 somehow else invalid, no part of the message is masked out.
5305 The second environment variable which influences the behavior of
5306 @code{fmtmsg} is @code{SEV_LEVEL}.  This variable and the change in the
5307 behavior of @code{fmtmsg} is not specified in the X/Open Portability
5308 Guide.  It is available in System V systems, though.  It can be used to
5309 introduce new severity levels.  By default, only the five severity levels
5310 described above are available.  Any other numeric value would make
5311 @code{fmtmsg} print nothing.
5313 If the user puts @code{SEV_LEVEL} with a format like
5315 @smallexample
5316 SEV_LEVEL=[@var{description}[:@var{description}[:@dots{}]]]
5317 @end smallexample
5319 @noindent
5320 in the environment of the process before the first call to
5321 @code{fmtmsg}, where @var{description} has a value of the form
5323 @smallexample
5324 @var{severity-keyword},@var{level},@var{printstring}
5325 @end smallexample
5327 The @var{severity-keyword} part is not used by @code{fmtmsg} but it has
5328 to be present.  The @var{level} part is a string representation of a
5329 number.  The numeric value must be a number greater than 4.  This value
5330 must be used in the @var{severity} parameter of @code{fmtmsg} to select
5331 this class.  It is not possible to overwrite any of the predefined
5332 classes.  The @var{printstring} is the string printed when a message of
5333 this class is processed by @code{fmtmsg} (see above, @code{fmtsmg} does
5334 not print the numeric value but instead the string representation).
5337 @node Adding Severity Classes
5338 @subsection Adding Severity Classes
5339 @cindex severity class
5341 There is another possibility to introduce severity classes besides using
5342 the environment variable @code{SEV_LEVEL}.  This simplifies the task of
5343 introducing new classes in a running program.  One could use the
5344 @code{setenv} or @code{putenv} function to set the environment variable,
5345 but this is toilsome.
5347 @deftypefun int addseverity (int @var{severity}, const char *@var{string})
5348 This function allows the introduction of new severity classes which can be
5349 addressed by the @var{severity} parameter of the @code{fmtmsg} function.
5350 The @var{severity} parameter of @code{addseverity} must match the value
5351 for the parameter with the same name of @code{fmtmsg}, and @var{string}
5352 is the string printed in the actual messages instead of the numeric
5353 value.
5355 If @var{string} is @code{NULL} the severity class with the numeric value
5356 according to @var{severity} is removed.
5358 It is not possible to overwrite or remove one of the default severity
5359 classes.  All calls to @code{addseverity} with @var{severity} set to one
5360 of the values for the default classes will fail.
5362 The return value is @code{MM_OK} if the task was successfully performed.
5363 If the return value is @code{MM_NOTOK} something went wrong.  This could
5364 mean that no more memory is available or a class is not available when
5365 it has to be removed.
5367 This function is not specified in the X/Open Portability Guide although
5368 the @code{fmtsmg} function is.  It is available on System V systems.
5369 @end deftypefun
5372 @node Example
5373 @subsection How to use @code{fmtmsg} and @code{addseverity}
5375 Here is a simple example program to illustrate the use of the both
5376 functions described in this section.
5378 @smallexample
5379 @include fmtmsgexpl.c.texi
5380 @end smallexample
5382 The second call to @code{fmtmsg} illustrates a use of this function as
5383 it usually occurs on System V systems, which heavily use this function.
5384 It seems worthwhile to give a short explanation here of how this system
5385 works on System V.  The value of the
5386 @var{label} field (@code{UX:cat}) says that the error occurred in the
5387 Unix program @code{cat}.  The explanation of the error follows and the
5388 value for the @var{action} parameter is @code{"refer to manual"}.  One
5389 could be more specific here, if necessary.  The @var{tag} field contains,
5390 as proposed above, the value of the string given for the @var{label}
5391 parameter, and additionally a unique ID (@code{001} in this case).  For
5392 a GNU environment this string could contain a reference to the
5393 corresponding node in the Info page for the program.
5395 @noindent
5396 Running this program without specifying the @code{MSGVERB} and
5397 @code{SEV_LEVEL} function produces the following output:
5399 @smallexample
5400 UX:cat: NOTE2: invalid syntax
5401 TO FIX: refer to manual UX:cat:001
5402 @end smallexample
5404 We see the different fields of the message and how the extra glue (the
5405 colons and the @code{TO FIX} string) are printed.  But only one of the
5406 three calls to @code{fmtmsg} produced output.  The first call does not
5407 print anything because the @var{label} parameter is not in the correct
5408 form.  The string must contain two fields, separated by a colon
5409 (@pxref{Printing Formatted Messages}).  The third @code{fmtmsg} call
5410 produced no output since the class with the numeric value @code{6} is
5411 not defined.  Although a class with numeric value @code{5} is also not
5412 defined by default, the call to @code{addseverity} introduces it and
5413 the second call to @code{fmtmsg} produces the above output.
5415 When we change the environment of the program to contain
5416 @code{SEV_LEVEL=XXX,6,NOTE} when running it we get a different result:
5418 @smallexample
5419 UX:cat: NOTE2: invalid syntax
5420 TO FIX: refer to manual UX:cat:001
5421 label:foo: NOTE: text
5422 TO FIX: action tag
5423 @end smallexample
5425 Now the third call to @code{fmtmsg} produced some output and we see how
5426 the string @code{NOTE} from the environment variable appears in the
5427 message.
5429 Now we can reduce the output by specifying which fields we are
5430 interested in.  If we additionally set the environment variable
5431 @code{MSGVERB} to the value @code{severity:label:action} we get the
5432 following output:
5434 @smallexample
5435 UX:cat: NOTE2
5436 TO FIX: refer to manual
5437 label:foo: NOTE
5438 TO FIX: action
5439 @end smallexample
5441 @noindent
5442 I.e., the output produced by the @var{text} and the @var{tag} parameters
5443 to @code{fmtmsg} vanished.  Please also note that now there is no colon
5444 after the @code{NOTE} and @code{NOTE2} strings in the output.  This is
5445 not necessary since there is no more output on this line because the text
5446 is missing.