.
[kopensolaris-gnu/glibc.git] / manual / stdio.texi
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
8
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.
13
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
42
43 @node Streams
44 @section Streams
45
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
54
55 @pindex stdio.h
56 The @code{FILE} type is declared in the header file @file{stdio.h}.
57
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
68
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."
75
76 @node Standard Streams
77 @section Standard Streams
78 @cindex standard streams
79 @cindex streams, standard
80
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.
85
86 These streams are declared in the header file @file{stdio.h}.
87 @pindex stdio.h
88
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
96
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
104
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
112
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.
118
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:
122
123 @smallexample
124 fclose (stdout);
125 stdout = fopen ("standard-output-file", "w");
126 @end smallexample
127
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}.
132
133 The three streams @code{stdin}, @code{stdout}, and @code{stderr} are not
134 unoriented at program start (@pxref{Streams and I18N}).
135
136 @node Opening Streams
137 @section Opening Streams
138
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.
143
144 @pindex stdio.h
145 Everything described in this section is declared in the header file
146 @file{stdio.h}.
147
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.
153
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:
157
158 @table @samp
159 @item r
160 Open an existing file for reading only.
161
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.
165
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.
171
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.
176
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.
180
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
187
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.
196
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.
200
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}).
208
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}.
214
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.
229
230 Any other characters in @var{opentype} are simply ignored.  They may be
231 meaningful in other systems.
232
233 If the open fails, @code{fopen} returns a null pointer.
234
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
239
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}.
248
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.
255
256 Please note that the return type is still @code{FILE *}.  There is no
257 special @code{FILE} type for the LFS interface.
258
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
263
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
277
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}.
288
289 If the operation fails, a null pointer is returned; otherwise,
290 @code{freopen} returns @var{stream}.
291
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.
298
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
303
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.
313
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
318
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.
324
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.
331
332 This function is declared in @file{stdio_ext.h}.
333 @end deftypefun
334
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.
341
342 This function is declared in @file{stdio_ext.h}.
343 @end deftypefun
344
345 For slightly different kind of problems there are two more functions.
346 They provide even finer-grained information.
347
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.
357
358 This function is declared in @file{stdio_ext.h}.
359 @end deftypefun
360
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.
367
368 This function is declared in @file{stdio_ext.h}.
369 @end deftypefun
370
371
372 @node Closing Streams
373 @section Closing Streams
374
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.
379
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.
388
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.
395
396 The function @code{fclose} is declared in @file{stdio.h}.
397 @end deftypefun
398
399 To close all streams currently available the GNU C Library provides
400 another function.
401
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.
410
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.
416
417 The function @code{fcloseall} is declared in @file{stdio.h}.
418 @end deftypefun
419
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}.
428
429 @node Streams and Threads
430 @section Streams and Threads
431
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.
440
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.
448
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.
457
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
468
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
479
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
491
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):
496
497 @smallexample
498 FILE *fp;
499 @{
500    @dots{}
501    flockfile (fp);
502    fputs ("This is test number ", fp);
503    fprintf (fp, "%d\n", test);
504    funlockfile (fp)
505 @}
506 @end smallexample
507
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}.
512
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:
520
521 @smallexample
522 void
523 foo (FILE *fp)
524 @{
525   ftrylockfile (fp);
526   fputs ("in foo\n", fp);
527   /* @r{This is very wrong!!!}  */
528   funlockfile (fp);
529 @}
530 @end smallexample
531
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:
539
540 @smallexample
541 void
542 foo (FILE *fp)
543 @{
544   if (ftrylockfile (fp) == 0)
545     @{
546       fputs ("in foo\n", fp);
547       funlockfile (fp);
548     @}
549 @}
550 @end smallexample
551
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.
564
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:
583
584 @smallexample
585 void
586 foo (FILE *fp, char *buf)
587 @{
588   flockfile (fp);
589   while (*buf != '/')
590     putc_unlocked (*buf++, fp);
591   funlockfile (fp);
592 @}
593 @end smallexample
594
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.
601
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.
604
605 @comment stdio_ext.h
606 @comment GNU
607 @deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type})
608
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.
614
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.
620
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}.
626
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
632
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.
636
637 This function and the values for the @var{type} parameter are declared
638 in @file{stdio_ext.h}.
639 @end deftypefun
640
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).
644
645 @node Streams and I18N
646 @section Streams in Internationalized Applications
647
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.
655
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.
664
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.
671
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.
681
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:
689
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.
695
696 @item
697 If any of the wide character functions is used the stream is marked as
698 wide oriented.
699
700 @item
701 The @code{fwide} function can be used to set the orientation either way.
702 @end itemize
703
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.
708
709 @comment wchar.h
710 @comment ISO
711 @deftypefun int fwide (FILE *@var{stream}, int @var{mode})
712
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.
719
720 If @var{mode} is zero the current orientation state is queried and
721 nothing is changed.
722
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.
726
727 This function was introduced in @w{Amendment 1} to @w{ISO C90} and is
728 declared in @file{wchar.h}.
729 @end deftypefun
730
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.
741
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.
746
747 @smallexample
748 void
749 print_f (FILE *fp)
750 @{
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);
756 @}
757 @end smallexample
758
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).
762
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.
774
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}.
782
783 @node Simple Output
784 @section Simple Output by Characters or Lines
785
786 @cindex writing to a stream, by characters
787 This section describes functions for performing character- and
788 line-oriented output.
789
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
794
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
803
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
811
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
818
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.
824
825 This function is a GNU extension.
826 @end deftypefun
827
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
837
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
847
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
854
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.
860
861 This function is a GNU extension.
862 @end deftypefun
863
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
870
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
877
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
884
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.
890
891 This function is a GNU extension.
892 @end deftypefun
893
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.
901
902 This function returns @code{EOF} if a write error occurs, and otherwise
903 a non-negative value.
904
905 For example:
906
907 @smallexample
908 fputs ("Are ", stdout);
909 fputs ("you ", stdout);
910 fputs ("hungry?\n", stdout);
911 @end smallexample
912
913 @noindent
914 outputs the text @samp{Are you hungry?} followed by a newline.
915 @end deftypefun
916
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.
924
925 This function returns @code{WEOF} if a write error occurs, and otherwise
926 a non-negative value.
927 @end deftypefun
928
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.
934
935 This function is a GNU extension.
936 @end deftypefun
937
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.
943
944 This function is a GNU extension.
945 @end deftypefun
946
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.)
954
955 @code{puts} is the most convenient function for printing simple
956 messages.  For example:
957
958 @smallexample
959 puts ("This is a message.");
960 @end smallexample
961
962 @noindent
963 outputs the text @samp{This is a message.} followed by a newline.
964 @end deftypefun
965
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
973
974 @node Character Input
975 @section Character Input
976
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
984
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.
997
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
1006
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
1014
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
1021
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.
1027
1028 This function is a GNU extension.
1029 @end deftypefun
1030
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
1040
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
1049
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
1056
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.
1062
1063 This function is a GNU extension.
1064 @end deftypefun
1065
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
1072
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
1079
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
1086
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.
1092
1093 This function is a GNU extension.
1094 @end deftypefun
1095
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.
1100
1101 @smallexample
1102 int
1103 y_or_n_p (const char *question)
1104 @{
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     @}
1126 @}
1127 @end smallexample
1128
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
1139
1140 @node Line Input
1141 @section Line-Oriented Input
1142
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.
1145
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.
1150
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.
1154
1155 All these functions are declared in @file{stdio.h}.
1156
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}}.
1163
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}.
1172
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}.
1176
1177 In either case, when @code{getline} returns,  @code{*@var{lineptr}} is
1178 a @code{char *} which points to the text of the line.
1179
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.
1184
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.
1187
1188 If an error occurs or end of file is reached without any bytes read,
1189 @code{getline} returns @code{-1}.
1190 @end deftypefun
1191
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).
1199
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.
1203
1204 @code{getline} is in fact implemented in terms of @code{getdelim}, just
1205 like this:
1206
1207 @smallexample
1208 ssize_t
1209 getline (char **lineptr, size_t *n, FILE *stream)
1210 @{
1211   return getdelim (lineptr, n, '\n', stream);
1212 @}
1213 @end smallexample
1214 @end deftypefun
1215
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.
1226
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}.
1231
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
1238
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.
1249
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}.
1254
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
1263
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.
1269
1270 This function is a GNU extension.
1271 @end deftypefun
1272
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.
1278
1279 This function is a GNU extension.
1280 @end deftypefun
1281
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}.
1291
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
1299
1300 @node Unreading
1301 @section Unreading
1302 @cindex peeking at input
1303 @cindex unreading characters
1304 @cindex pushing input back
1305
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.
1310
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.
1315
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
1320
1321 @node Unreading Idea
1322 @subsection What Unreading Means
1323
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:
1328
1329 @smallexample
1330 f  o  o  b  a  r
1331          ^
1332 @end smallexample
1333
1334 @noindent
1335 so the next input character will be @samp{b}.
1336
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:
1340
1341 @smallexample
1342 f  o  o  b  a  r
1343          |
1344       o--
1345       ^
1346 @end smallexample
1347
1348 @noindent
1349 so that the next input characters will be @samp{o} and @samp{b}.
1350 @c @end group
1351
1352 @c @group
1353 If you unread @samp{9} instead of @samp{o}, you get this situation:
1354
1355 @smallexample
1356 f  o  o  b  a  r
1357          |
1358       9--
1359       ^
1360 @end smallexample
1361
1362 @noindent
1363 so that the next input characters will be @samp{9} and @samp{b}.
1364 @c @end group
1365
1366 @node How Unread
1367 @subsection Using @code{ungetc} To Do Unreading
1368
1369 The function to unread a character is called @code{ungetc}, because it
1370 reverses the action of @code{getc}.
1371
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.
1378
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}.
1382
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.
1390
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.
1396
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.
1402
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
1408
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
1415
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.
1420
1421 @smallexample
1422 #include <stdio.h>
1423 #include <ctype.h>
1424
1425 void
1426 skip_whitespace (FILE *stream)
1427 @{
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);
1435 @}
1436 @end smallexample
1437
1438 @node Block Input/Output
1439 @section Block Input/Output
1440
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
1449
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.
1455
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.
1463
1464 These functions are declared in @file{stdio.h}.
1465 @pindex stdio.h
1466
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.
1476
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
1481
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.
1487
1488 This function is a GNU extension.
1489 @end deftypefun
1490
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
1499
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.
1505
1506 This function is a GNU extension.
1507 @end deftypefun
1508
1509 @node Formatted Output
1510 @section Formatted Output
1511
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.
1520
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.
1526
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
1545
1546 @node Formatted Output Basics
1547 @subsection Formatted Output Basics
1548
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.
1553
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})
1559
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
1566
1567 @noindent
1568 produces output like
1569
1570 @smallexample
1571 Processing of `foo.txt' is 37% finished.
1572 Please be patient.
1573 @end smallexample
1574
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.
1579
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}).
1584
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.
1590
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.
1597
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.
1605
1606 @node Output Conversion Syntax
1607 @subsection Output Conversion Syntax
1608
1609 This section provides details about the precise syntax of conversion
1610 specifications that can appear in a @code{printf} template
1611 string.
1612
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.
1617
1618 The conversion specifications in a @code{printf} template string have
1619 the general form:
1620
1621 @smallexample
1622 % @r{[} @var{param-no} @r{$]} @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion}
1623 @end smallexample
1624
1625 @noindent
1626 or
1627
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
1631
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.)
1638
1639 In more detail, output conversion specifications consist of an
1640 initial @samp{%} character followed in sequence by:
1641
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.
1649
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.
1654
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}.
1661
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
1665
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.
1669
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})
1674
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})
1683
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.
1689
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})
1696
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.
1703
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})
1711
1712 @item
1713 A character that specifies the conversion to be applied.
1714 @end itemize
1715
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.
1720
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.
1728
1729 @node Table of Output Conversions
1730 @subsection Table of Output Conversions
1731 @cindex output conversions, for @code{printf}
1732
1733 Here is a table summarizing what all the different conversions do:
1734
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}).
1741
1742 @item @samp{%o}
1743 Print an integer as an unsigned octal number.  @xref{Integer
1744 Conversions}, for details.
1745
1746 @item @samp{%u}
1747 Print an integer as an unsigned decimal number.  @xref{Integer
1748 Conversions}, for details.
1749
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.
1754
1755 @item @samp{%f}
1756 Print a floating-point number in normal (fixed-point) notation.
1757 @xref{Floating-Point Conversions}, for details.
1758
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.
1763
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.
1769
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.
1775
1776 @item @samp{%c}
1777 Print a single character.  @xref{Other Output Conversions}.
1778
1779 @item @samp{%C}
1780 This is an alias for @samp{%lc} which is supported for compatibility
1781 with the Unix standard.
1782
1783 @item @samp{%s}
1784 Print a string.  @xref{Other Output Conversions}.
1785
1786 @item @samp{%S}
1787 This is an alias for @samp{%ls} which is supported for compatibility
1788 with the Unix standard.
1789
1790 @item @samp{%p}
1791 Print the value of a pointer.  @xref{Other Output Conversions}.
1792
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.
1796
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}.
1801
1802 @item @samp{%%}
1803 Print a literal @samp{%} character.  @xref{Other Output Conversions}.
1804 @end table
1805
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.
1813
1814 @node Integer Conversions
1815 @subsection Integer Conversions
1816
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.
1820
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}.
1827
1828 The following flags are meaningful:
1829
1830 @table @asis
1831 @item @samp{-}
1832 Left-justify the result in the field (instead of the normal
1833 right-justification).
1834
1835 @item @samp{+}
1836 For the signed @samp{%d} and @samp{%i} conversions, print a
1837 plus sign if the value is positive.
1838
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.
1844
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}).
1854
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.
1859
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
1865
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.
1871
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:
1880
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.
1888
1889 This modifier was introduced in @w{ISO C99}.
1890
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.
1897
1898 @item j
1899 Specifies that the argument is a @code{intmax_t} or @code{uintmax_t}, as
1900 appropriate.
1901
1902 This modifier was introduced in @w{ISO C99}.
1903
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.
1908
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}.
1912
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}.)
1919
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}.
1923
1924 @item t
1925 Specifies that the argument is a @code{ptrdiff_t}.
1926
1927 This modifier was introduced in @w{ISO C99}.
1928
1929 @item z
1930 @itemx Z
1931 Specifies that the argument is a @code{size_t}.
1932
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
1936
1937 Here is an example.  Using the template string:
1938
1939 @smallexample
1940 "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
1941 @end smallexample
1942
1943 @noindent
1944 to print numbers using the different options for the @samp{%d}
1945 conversion gives results like:
1946
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
1953
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.
1956
1957 Here are some more examples showing how unsigned integers print under
1958 various format options, using the template string:
1959
1960 @smallexample
1961 "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
1962 @end smallexample
1963
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
1969
1970
1971 @node Floating-Point Conversions
1972 @subsection Floating-Point Conversions
1973
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.
1977
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.
1983
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}.
1991
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.
1998
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.
2020
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}.
2026
2027 The following flags can be used to modify the behavior:
2028
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.
2034
2035 @item @samp{+}
2036 Always include a plus or minus sign in the result.
2037
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.
2042
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.
2048
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.
2053
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
2059
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.
2071
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:
2076
2077 @table @samp
2078 @item L
2079 An uppercase @samp{L} specifies that the argument is a @code{long
2080 double}.
2081 @end table
2082
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:
2086
2087 @smallexample
2088 "|%13.4a|%13.4f|%13.4e|%13.4g|\n"
2089 @end smallexample
2090
2091 Here is the output:
2092
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
2105
2106 Notice how the @samp{%g} conversion drops trailing zeros.
2107
2108 @node Other Output Conversions
2109 @subsection Other Output Conversions
2110
2111 This section describes miscellaneous conversions for @code{printf}.
2112
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:
2120
2121 @smallexample
2122 printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
2123 @end smallexample
2124
2125 @noindent
2126 prints @samp{hello}.
2127
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.
2132
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:
2143
2144 @smallexample
2145 printf ("%3s%-6s", "no", "where");
2146 @end smallexample
2147
2148 @noindent
2149 prints @samp{ nowhere }.
2150
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 *}).
2152
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.
2157
2158 The @samp{%m} conversion prints the string corresponding to the error
2159 code in @code{errno}.  @xref{Error Messages}.  Thus:
2160
2161 @smallexample
2162 fprintf (stderr, "can't open `%s': %m\n", filename);
2163 @end smallexample
2164
2165 @noindent
2166 is equivalent to:
2167
2168 @smallexample
2169 fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
2170 @end smallexample
2171
2172 @noindent
2173 The @samp{%m} conversion is a GNU C library extension.
2174
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.
2178
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.)
2182
2183 For example:
2184
2185 @smallexample
2186 printf ("%p", "testing");
2187 @end smallexample
2188
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}.
2193
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.
2197
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.
2205
2206 For example,
2207
2208 @smallexample
2209 int nchar;
2210 printf ("%d %s%n\n", 3, "bears", &nchar);
2211 @end smallexample
2212
2213 @noindent
2214 prints:
2215
2216 @smallexample
2217 3 bears
2218 @end smallexample
2219
2220 @noindent
2221 and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven
2222 characters.
2223
2224
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.
2228
2229
2230 @node Formatted Output Functions
2231 @subsection Formatted Output Functions
2232
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
2240
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
2249
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
2258
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
2265
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
2272
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.
2279
2280 The @code{sprintf} function returns the number of characters stored in
2281 the array @var{s}, not including the terminating null character.
2282
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}.
2287
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.
2292
2293 To avoid this problem, you can use @code{snprintf} or @code{asprintf},
2294 described below.
2295 @end deftypefun
2296
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}.
2306
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.
2312
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
2320
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}.
2328
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:
2334
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)
2341 @{
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;
2350
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);
2362
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;
2370 @}
2371 @end group
2372 @end smallexample
2373
2374 In practice, it is often easier just to use @code{asprintf}, below.
2375
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
2382
2383 @node Dynamic Output
2384 @subsection Dynamically Allocating Formatted Output
2385
2386 The functions in this section do formatted output and place the results
2387 in dynamically allocated memory.
2388
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.
2399
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.
2403
2404 Here is how to use @code{asprintf} to get the same result as the
2405 @code{snprintf} example, but more easily:
2406
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)
2412 @{
2413   char *result;
2414   if (asprintf (&result, "value of %s is %s", name, value) < 0)
2415     return NULL;
2416   return result;
2417 @}
2418 @end smallexample
2419 @end deftypefun
2420
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}.
2426
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
2431
2432 @node Variable Arguments Output
2433 @subsection Variable Arguments Output Functions
2434
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.
2438
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.
2444
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.''
2448
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:
2452
2453 @smallexample
2454 #define myprintf(a, b, c, d, e, rest...) \
2455             printf (mytemplate , ## rest)
2456 @end smallexample
2457
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.
2461
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.
2467
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.
2472
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.
2481
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.)
2487
2488 Prototypes for these functions are declared in @file{stdio.h}.
2489 @pindex stdio.h
2490
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
2498
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
2506
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
2513
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
2520
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
2527
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
2534
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
2541
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
2548
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
2556
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}).
2562
2563 @smallexample
2564 @group
2565 #include <stdio.h>
2566 #include <stdarg.h>
2567
2568 void
2569 eprintf (const char *template, ...)
2570 @{
2571   va_list ap;
2572   extern char *program_invocation_short_name;
2573
2574   fprintf (stderr, "%s: ", program_invocation_short_name);
2575   va_start (ap, template);
2576   vfprintf (stderr, template, ap);
2577   va_end (ap);
2578 @}
2579 @end group
2580 @end smallexample
2581
2582 @noindent
2583 You could call @code{eprintf} like this:
2584
2585 @smallexample
2586 eprintf ("file `%s' does not exist\n", filename);
2587 @end smallexample
2588
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}:
2594
2595 @smallexample
2596 void eprintf (const char *template, ...)
2597         __attribute__ ((format (printf, 1, 2)));
2598 @end smallexample
2599
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.
2607
2608 @node Parsing a Template String
2609 @subsection Parsing a Template String
2610 @cindex parsing a template string
2611
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.
2617
2618 All the symbols described in this section are declared in the header
2619 file @file{printf.h}.
2620
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.
2629
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.
2633
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
2640
2641 The argument types are encoded as a combination of a basic type and
2642 modifier flag bits.
2643
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
2652
2653 Here are symbolic constants that represent the basic types; they stand
2654 for integer values.
2655
2656 @vtable @code
2657 @comment printf.h
2658 @comment GNU
2659 @item PA_INT
2660 This specifies that the base type is @code{int}.
2661
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}.
2666
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.
2671
2672 @comment printf.h
2673 @comment GNU
2674 @item PA_POINTER
2675 This specifies that the base type is @code{void *}, an arbitrary pointer.
2676
2677 @comment printf.h
2678 @comment GNU
2679 @item PA_FLOAT
2680 This specifies that the base type is @code{float}.
2681
2682 @comment printf.h
2683 @comment GNU
2684 @item PA_DOUBLE
2685 This specifies that the base type is @code{double}.
2686
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:
2694
2695 @smallexample
2696 #define PA_FOO  PA_LAST
2697 #define PA_BAR  (PA_LAST + 1)
2698 @end smallexample
2699 @end vtable
2700
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.
2703
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 *}.
2711
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.)
2717
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.)
2723
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.)
2729
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
2736
2737 @ifinfo
2738 For an example of using these facilities, see @ref{Example of Parsing}.
2739 @end ifinfo
2740
2741 @node Example of Parsing
2742 @subsection Example of Parsing a Template String
2743
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).
2748
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.}  */
2755
2756 int
2757 validate_args (char *format, int nargs, OBJECT *args)
2758 @{
2759   int *argtypes;
2760   int nwanted;
2761
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.}  */
2766
2767   argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
2768   nwanted = parse_printf_format (string, nelts, argtypes);
2769
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     @}
2776
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;
2782
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;
2810 @}
2811 @end smallexample
2812
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}
2818
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.
2822
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.
2828
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.
2832
2833 The facilities of this section are declared in the header file
2834 @file{printf.h}.
2835
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
2849
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.
2853
2854 @node Registering New Conversions
2855 @subsection Registering New Conversions
2856
2857 The function to register a new output conversion is
2858 @code{register_printf_function}, declared in @file{printf.h}.
2859 @pindex printf.h
2860
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.
2872
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.
2878
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.
2883
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
2887 @c
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.
2891
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.
2897
2898 The return value is @code{0} on success, and @code{-1} on failure
2899 (which occurs if @var{spec} is out of range).
2900
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
2905
2906 @node Conversion Specifier Options
2907 @subsection Conversion Specifier Options
2908
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.
2913
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
2920
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:
2928
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.
2937
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.
2945
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.
2951
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.
2957
2958 @item unsigned int is_char
2959 This is a boolean that is true if the @samp{hh} type modifier was specified.
2960
2961 @item unsigned int is_short
2962 This is a boolean that is true if the @samp{h} type modifier was specified.
2963
2964 @item unsigned int is_long
2965 This is a boolean that is true if the @samp{l} type modifier was specified.
2966
2967 @item unsigned int alt
2968 This is a boolean that is true if the @samp{#} flag was specified.
2969
2970 @item unsigned int space
2971 This is a boolean that is true if the @samp{ } flag was specified.
2972
2973 @item unsigned int left
2974 This is a boolean that is true if the @samp{-} flag was specified.
2975
2976 @item unsigned int showsign
2977 This is a boolean that is true if the @samp{+} flag was specified.
2978
2979 @item unsigned int group
2980 This is a boolean that is true if the @samp{'} flag was specified.
2981
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}.
2987
2988 @item unsigned int wide
2989 This flag is set if the stream is wide oriented.
2990
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
2997
2998
2999 @node Defining the Output Handler
3000 @subsection Defining the Output Handler
3001
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}.
3004
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 *}.
3008
3009 You should define your handler functions with a prototype like:
3010
3011 @smallexample
3012 int @var{function} (FILE *stream, const struct printf_info *info,
3013                     const void *const *args)
3014 @end smallexample
3015
3016 The @var{stream} argument passed to the handler function is the stream to
3017 which it should write output.
3018
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.
3024
3025 @c The following changes some time back.  --drepper@gnu, 1996/11/14
3026 @c
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})}.
3033 @c
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}.)
3037
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.
3041
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.
3045
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
3051
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}.
3056
3057 You have to define these functions with a prototype like:
3058
3059 @smallexample
3060 int @var{function} (const struct printf_info *info,
3061                     size_t n, int *argtypes)
3062 @end smallexample
3063
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.)
3070
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
3077
3078 @node Printf Extension Example
3079 @subsection @code{printf} Extension Example
3080
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.
3087
3088 @smallexample
3089 @include rprintf.c.texi
3090 @end smallexample
3091
3092 The output produced by this program looks like:
3093
3094 @smallexample
3095 |<Widget 0xffeffb7c: mywidget>|
3096 |      <Widget 0xffeffb7c: mywidget>|
3097 |<Widget 0xffeffb7c: mywidget>      |
3098 @end smallexample
3099
3100 @node Predefined Printf Handlers
3101 @subsection Predefined @code{printf} Handlers
3102
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.
3106
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.
3117
3118 The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes,
3119 etc.  The full table is:
3120
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
3157
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
3161
3162 Due to the requirements of @code{register_printf_function} we must also
3163 provide the function which returns information about the arguments.
3164
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
3172
3173 To use these functions both functions must be registered with a call like
3174
3175 @smallexample
3176 register_printf_function ('B', printf_size, printf_size_info);
3177 @end smallexample
3178
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
3182
3183 @smallexample
3184 register_printf_function ('b', printf_size, printf_size_info);
3185 @end smallexample
3186
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.
3192
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.
3196
3197 @node Formatted Input
3198 @section Formatted Input
3199
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}.
3209
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
3221
3222 @node Formatted Input Basics
3223 @subsection Formatted Input Basics
3224
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})
3239
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.
3247
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}
3254
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}:
3258
3259 @smallexample
3260 void
3261 readarray (double *array, int n)
3262 @{
3263   int i;
3264   for (i=0; i<n; i++)
3265     if (scanf (" %lf", &(array[i])) != 1)
3266       invalid_input_error ();
3267 @}
3268 @end smallexample
3269
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.
3274
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}.
3281
3282 @node Input Conversion Syntax
3283 @subsection Input Conversion Syntax
3284
3285 A @code{scanf} template string is a string that contains ordinary
3286 multibyte characters interspersed with conversion specifications that
3287 start with @samp{%}.
3288
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.
3296
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.
3300
3301 The conversion specifications in a @code{scanf} template string
3302 have the general form:
3303
3304 @smallexample
3305 % @var{flags} @var{width} @var{type} @var{conversion}
3306 @end smallexample
3307
3308 In more detail, an input conversion specification consists of an initial
3309 @samp{%} character followed in sequence by:
3310
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})
3320
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}.
3326
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})
3337
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})
3344
3345 @item
3346 A character that specifies the conversion to be applied.
3347 @end itemize
3348
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.
3353
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.
3361
3362 @node Table of Input Conversions
3363 @subsection Table of Input Conversions
3364 @cindex input conversions, for @code{scanf}
3365
3366 Here is a table that summarizes the various conversion specifications:
3367
3368 @table @asis
3369 @item @samp{%d}
3370 Matches an optionally signed integer written in decimal.  @xref{Numeric
3371 Input Conversions}.
3372
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}.
3377
3378 @item @samp{%o}
3379 Matches an unsigned integer written in octal radix.
3380 @xref{Numeric Input Conversions}.
3381
3382 @item @samp{%u}
3383 Matches an unsigned integer written in decimal radix.
3384 @xref{Numeric Input Conversions}.
3385
3386 @item @samp{%x}, @samp{%X}
3387 Matches an unsigned integer written in hexadecimal radix.
3388 @xref{Numeric Input Conversions}.
3389
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}.
3393
3394 @item @samp{%s}
3395
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.
3406
3407 @item @samp{%S}
3408 This is an alias for @samp{%ls} which is supported for compatibility
3409 with the Unix standard.
3410
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.
3422
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}.
3427
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}.
3435
3436 @item @samp{%C}
3437 This is an alias for @samp{%lc} which is supported for compatibility
3438 with the Unix standard.
3439
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}.
3444
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}.
3448
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
3453
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.
3460
3461 @node Numeric Input Conversions
3462 @subsection Numeric Input Conversions
3463
3464 This section describes the @code{scanf} conversions for reading numeric
3465 values.
3466
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.
3471
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}.)
3479
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}.
3483
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.
3489
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.
3492
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:
3497
3498 @table @samp
3499 @item hh
3500 Specifies that the argument is a @code{signed char *} or @code{unsigned
3501 char *}.
3502
3503 This modifier was introduced in @w{ISO C99}.
3504
3505 @item h
3506 Specifies that the argument is a @code{short int *} or @code{unsigned
3507 short int *}.
3508
3509 @item j
3510 Specifies that the argument is a @code{intmax_t *} or @code{uintmax_t *}.
3511
3512 This modifier was introduced in @w{ISO C99}.
3513
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.
3517
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}.
3522
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}.)
3530
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}.
3534
3535 @item t
3536 Specifies that the argument is a @code{ptrdiff_t *}.
3537
3538 This modifier was introduced in @w{ISO C99}.
3539
3540 @item z
3541 Specifies that the argument is a @code{size_t *}.
3542
3543 This modifier was introduced in @w{ISO C99}.
3544 @end table
3545
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}).
3550
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:
3558
3559 @table @samp
3560 @item l
3561 Specifies that the argument is of type @code{double *}.
3562
3563 @item L
3564 Specifies that the argument is of type @code{long double *}.
3565 @end table
3566
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}).
3572
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.
3577
3578 @node String Input Conversions
3579 @subsection String Input Conversions
3580
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}.
3584
3585 You have two options for how to receive the input from these
3586 conversions:
3587
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).
3593
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.}
3600
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
3607
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
3618
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.
3624
3625 The @samp{%s} conversion matches a string of non-whitespace characters.
3626 It skips and discards initial whitespace, but stops when it encounters