diff options
Diffstat (limited to 'manual/stdio.texi')
| -rw-r--r-- | manual/stdio.texi | 5663 |
1 files changed, 0 insertions, 5663 deletions
diff --git a/manual/stdio.texi b/manual/stdio.texi deleted file mode 100644 index 29f3fed89b..0000000000 --- a/manual/stdio.texi +++ /dev/null @@ -1,5663 +0,0 @@ -@node I/O on Streams, Low-Level I/O, I/O Overview, Top -@c %MENU% High-level, portable I/O facilities -@chapter Input/Output on Streams -@c fix an overfull: -@tex -\hyphenation{which-ever} -@end tex - -This chapter describes the functions for creating streams and performing -input and output operations on them. As discussed in @ref{I/O -Overview}, a stream is a fairly abstract, high-level concept -representing a communications channel to a file, device, or process. - -@menu -* Streams:: About the data type representing a stream. -* Standard Streams:: Streams to the standard input and output - devices are created for you. -* Opening Streams:: How to create a stream to talk to a file. -* Closing Streams:: Close a stream when you are finished with it. -* Streams and Threads:: Issues with streams in threaded programs. -* Streams and I18N:: Streams in internationalized applications. -* Simple Output:: Unformatted output by characters and lines. -* Character Input:: Unformatted input by characters and words. -* Line Input:: Reading a line or a record from a stream. -* Unreading:: Peeking ahead/pushing back input just read. -* Block Input/Output:: Input and output operations on blocks of data. -* Formatted Output:: @code{printf} and related functions. -* Customizing Printf:: You can define new conversion specifiers for - @code{printf} and friends. -* Formatted Input:: @code{scanf} and related functions. -* EOF and Errors:: How you can tell if an I/O error happens. -* Error Recovery:: What you can do about errors. -* Binary Streams:: Some systems distinguish between text files - and binary files. -* File Positioning:: About random-access streams. -* Portable Positioning:: Random access on peculiar ISO C systems. -* Stream Buffering:: How to control buffering of streams. -* Other Kinds of Streams:: Streams that do not necessarily correspond - to an open file. -* Formatted Messages:: Print strictly formatted messages. -@end menu - -@node Streams -@section Streams - -For historical reasons, the type of the C data structure that represents -a stream is called @code{FILE} rather than ``stream''. Since most of -the library functions deal with objects of type @code{FILE *}, sometimes -the term @dfn{file pointer} is also used to mean ``stream''. This leads -to unfortunate confusion over terminology in many books on C. This -manual, however, is careful to use the terms ``file'' and ``stream'' -only in the technical sense. -@cindex file pointer - -@pindex stdio.h -The @code{FILE} type is declared in the header file @file{stdio.h}. - -@comment stdio.h -@comment ISO -@deftp {Data Type} FILE -This is the data type used to represent stream objects. A @code{FILE} -object holds all of the internal state information about the connection -to the associated file, including such things as the file position -indicator and buffering information. Each stream also has error and -end-of-file status indicators that can be tested with the @code{ferror} -and @code{feof} functions; see @ref{EOF and Errors}. -@end deftp - -@code{FILE} objects are allocated and managed internally by the -input/output library functions. Don't try to create your own objects of -type @code{FILE}; let the library do it. Your programs should -deal only with pointers to these objects (that is, @code{FILE *} values) -rather than the objects themselves. -@c !!! should say that FILE's have "No user-serviceable parts inside." - -@node Standard Streams -@section Standard Streams -@cindex standard streams -@cindex streams, standard - -When the @code{main} function of your program is invoked, it already has -three predefined streams open and available for use. These represent -the ``standard'' input and output channels that have been established -for the process. - -These streams are declared in the header file @file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment ISO -@deftypevar {FILE *} stdin -The @dfn{standard input} stream, which is the normal source of input for the -program. -@end deftypevar -@cindex standard input stream - -@comment stdio.h -@comment ISO -@deftypevar {FILE *} stdout -The @dfn{standard output} stream, which is used for normal output from -the program. -@end deftypevar -@cindex standard output stream - -@comment stdio.h -@comment ISO -@deftypevar {FILE *} stderr -The @dfn{standard error} stream, which is used for error messages and -diagnostics issued by the program. -@end deftypevar -@cindex standard error stream - -On @gnusystems{}, you can specify what files or processes correspond to -these streams using the pipe and redirection facilities provided by the -shell. (The primitives shells use to implement these facilities are -described in @ref{File System Interface}.) Most other operating systems -provide similar mechanisms, but the details of how to use them can vary. - -In @theglibc{}, @code{stdin}, @code{stdout}, and @code{stderr} are -normal variables which you can set just like any others. For example, -to redirect the standard output to a file, you could do: - -@smallexample -fclose (stdout); -stdout = fopen ("standard-output-file", "w"); -@end smallexample - -Note however, that in other systems @code{stdin}, @code{stdout}, and -@code{stderr} are macros that you cannot assign to in the normal way. -But you can use @code{freopen} to get the effect of closing one and -reopening it. @xref{Opening Streams}. - -The three streams @code{stdin}, @code{stdout}, and @code{stderr} are not -unoriented at program start (@pxref{Streams and I18N}). - -@node Opening Streams -@section Opening Streams - -@cindex opening a stream -Opening a file with the @code{fopen} function creates a new stream and -establishes a connection between the stream and a file. This may -involve creating a new file. - -@pindex stdio.h -Everything described in this section is declared in the header file -@file{stdio.h}. - -@comment stdio.h -@comment ISO -@deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} -@c fopen may leak the list lock if cancelled within _IO_link_in. -The @code{fopen} function opens a stream for I/O to the file -@var{filename}, and returns a pointer to the stream. - -The @var{opentype} argument is a string that controls how the file is -opened and specifies attributes of the resulting stream. It must begin -with one of the following sequences of characters: - -@table @samp -@item r -Open an existing file for reading only. - -@item w -Open the file for writing only. If the file already exists, it is -truncated to zero length. Otherwise a new file is created. - -@item a -Open a file for append access; that is, writing at the end of file only. -If the file already exists, its initial contents are unchanged and -output to the stream is appended to the end of the file. -Otherwise, a new, empty file is created. - -@item r+ -Open an existing file for both reading and writing. The initial contents -of the file are unchanged and the initial file position is at the -beginning of the file. - -@item w+ -Open a file for both reading and writing. If the file already exists, it -is truncated to zero length. Otherwise, a new file is created. - -@item a+ -Open or create file for both reading and appending. If the file exists, -its initial contents are unchanged. Otherwise, a new file is created. -The initial file position for reading is at the beginning of the file, -but output is always appended to the end of the file. -@end table - -As you can see, @samp{+} requests a stream that can do both input and -output. When using such a stream, you must call @code{fflush} -(@pxref{Stream Buffering}) or a file positioning function such as -@code{fseek} (@pxref{File Positioning}) when switching from reading -to writing or vice versa. Otherwise, internal buffers might not be -emptied properly. - -Additional characters may appear after these to specify flags for the -call. Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is -the only part you are guaranteed will be understood by all systems. - -@Theglibc{} defines additional characters for use in @var{opentype}: - -@table @samp -@item c -The file is opened with cancellation in the I/O functions disabled. - -@item e -The underlying file descriptor will be closed if you use any of the -@code{exec@dots{}} functions (@pxref{Executing a File}). (This is -equivalent to having set @code{FD_CLOEXEC} on that descriptor. -@xref{Descriptor Flags}.) - -@item m -The file is opened and accessed using @code{mmap}. This is only -supported with files opened for reading. - -@item x -Insist on creating a new file---if a file @var{filename} already -exists, @code{fopen} fails rather than opening it. If you use -@samp{x} you are guaranteed that you will not clobber an existing -file. This is equivalent to the @code{O_EXCL} option to the -@code{open} function (@pxref{Opening and Closing Files}). - -The @samp{x} modifier is part of @w{ISO C11}. -@end table - -The character @samp{b} in @var{opentype} has a standard meaning; it -requests a binary stream rather than a text stream. But this makes no -difference in POSIX systems (including @gnusystems{}). If both -@samp{+} and @samp{b} are specified, they can appear in either order. -@xref{Binary Streams}. - -@cindex stream orientation -@cindex orientation, stream -If the @var{opentype} string contains the sequence -@code{,ccs=@var{STRING}} then @var{STRING} is taken as the name of a -coded character set and @code{fopen} will mark the stream as -wide-oriented with appropriate conversion functions in place to convert -from and to the character set @var{STRING}. Any other stream -is opened initially unoriented and the orientation is decided with the -first file operation. If the first operation is a wide character -operation, the stream is not only marked as wide-oriented, also the -conversion functions to convert to the coded character set used for the -current locale are loaded. This will not change anymore from this point -on even if the locale selected for the @code{LC_CTYPE} category is -changed. - -Any other characters in @var{opentype} are simply ignored. They may be -meaningful in other systems. - -If the open fails, @code{fopen} returns a null pointer. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bit machine this function is in fact @code{fopen64} since the LFS -interface replaces transparently the old interface. -@end deftypefun - -You can have multiple streams (or file descriptors) pointing to the same -file open at the same time. If you do only input, this works -straightforwardly, but you must be careful if any output streams are -included. @xref{Stream/Descriptor Precautions}. This is equally true -whether the streams are in one program (not usual) or in several -programs (which can easily happen). It may be advantageous to use the -file locking facilities to avoid simultaneous access. @xref{File -Locks}. - -@comment stdio.h -@comment Unix98 -@deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} -This function is similar to @code{fopen} but the stream it returns a -pointer for is opened using @code{open64}. Therefore this stream can be -used even on files larger than @twoexp{31} bytes on 32 bit machines. - -Please note that the return type is still @code{FILE *}. There is no -special @code{FILE} type for the LFS interface. - -If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 -bits machine this function is available under the name @code{fopen} -and so transparently replaces the old interface. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypevr Macro int FOPEN_MAX -The value of this macro is an integer constant expression that -represents the minimum number of streams that the implementation -guarantees can be open simultaneously. You might be able to open more -than this many streams, but that is not guaranteed. The value of this -constant is at least eight, which includes the three standard streams -@code{stdin}, @code{stdout}, and @code{stderr}. In POSIX.1 systems this -value is determined by the @code{OPEN_MAX} parameter; @pxref{General -Limits}. In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE} -resource limit; @pxref{Limits on Resources}. -@end deftypevr - -@comment stdio.h -@comment ISO -@deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}} -@c Like most I/O operations, this one is guarded by a recursive lock, -@c released even upon cancellation, but cancellation may leak file -@c descriptors and leave the stream in an inconsistent state (e.g., -@c still bound to the closed descriptor). Also, if the stream is -@c part-way through a significant update (say running freopen) when a -@c signal handler calls freopen again on the same stream, the result is -@c likely to be an inconsistent stream, and the possibility of closing -@c twice file descriptor number that the stream used to use, the second -@c time when it might have already been reused by another thread. -This function is like a combination of @code{fclose} and @code{fopen}. -It first closes the stream referred to by @var{stream}, ignoring any -errors that are detected in the process. (Because errors are ignored, -you should not use @code{freopen} on an output stream if you have -actually done any output using the stream.) Then the file named by -@var{filename} is opened with mode @var{opentype} as for @code{fopen}, -and associated with the same stream object @var{stream}. - -If the operation fails, a null pointer is returned; otherwise, -@code{freopen} returns @var{stream}. On Linux, @code{freopen} may also -fail and set @code{errno} to @code{EBUSY} when the kernel structure for -the old file descriptor was not initialized completely before @code{freopen} -was called. This can only happen in multi-threaded programs, when two -threads race to allocate the same file descriptor number. To avoid the -possibility of this race, do not use @code{close} to close the underlying -file descriptor for a @code{FILE}; either use @code{freopen} while the -file is still open, or use @code{open} and then @code{dup2} to install -the new file descriptor. - -@code{freopen} has traditionally been used to connect a standard stream -such as @code{stdin} with a file of your own choice. This is useful in -programs in which use of a standard stream for certain purposes is -hard-coded. In @theglibc{}, you can simply close the standard -streams and open new ones with @code{fopen}. But other systems lack -this ability, so using @code{freopen} is more portable. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bit machine this function is in fact @code{freopen64} since the LFS -interface replaces transparently the old interface. -@end deftypefun - -@comment stdio.h -@comment Unix98 -@deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}} -This function is similar to @code{freopen}. The only difference is that -on 32 bit machine the stream returned is able to read beyond the -@twoexp{31} bytes limits imposed by the normal interface. It should be -noted that the stream pointed to by @var{stream} need not be opened -using @code{fopen64} or @code{freopen64} since its mode is not important -for this function. - -If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 -bits machine this function is available under the name @code{freopen} -and so transparently replaces the old interface. -@end deftypefun - -In some situations it is useful to know whether a given stream is -available for reading or writing. This information is normally not -available and would have to be remembered separately. Solaris -introduced a few functions to get this information from the stream -descriptor and these functions are also available in @theglibc{}. - -@comment stdio_ext.h -@comment GNU -@deftypefun int __freadable (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{__freadable} function determines whether the stream -@var{stream} was opened to allow reading. In this case the return value -is nonzero. For write-only streams the function returns zero. - -This function is declared in @file{stdio_ext.h}. -@end deftypefun - -@comment stdio_ext.h -@comment GNU -@deftypefun int __fwritable (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{__fwritable} function determines whether the stream -@var{stream} was opened to allow writing. In this case the return value -is nonzero. For read-only streams the function returns zero. - -This function is declared in @file{stdio_ext.h}. -@end deftypefun - -For slightly different kinds of problems there are two more functions. -They provide even finer-grained information. - -@comment stdio_ext.h -@comment GNU -@deftypefun int __freading (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{__freading} function determines whether the stream -@var{stream} was last read from or whether it is opened read-only. In -this case the return value is nonzero, otherwise it is zero. -Determining whether a stream opened for reading and writing was last -used for writing allows to draw conclusions about the content about the -buffer, among other things. - -This function is declared in @file{stdio_ext.h}. -@end deftypefun - -@comment stdio_ext.h -@comment GNU -@deftypefun int __fwriting (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{__fwriting} function determines whether the stream -@var{stream} was last written to or whether it is opened write-only. In -this case the return value is nonzero, otherwise it is zero. - -This function is declared in @file{stdio_ext.h}. -@end deftypefun - - -@node Closing Streams -@section Closing Streams - -@cindex closing a stream -When a stream is closed with @code{fclose}, the connection between the -stream and the file is canceled. After you have closed a stream, you -cannot perform any additional operations on it. - -@comment stdio.h -@comment ISO -@deftypefun int fclose (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} -@c After fclose, it is undefined behavior to use the stream it points -@c to. Therefore, one must only call fclose when the stream is -@c otherwise unused. Concurrent uses started before will complete -@c successfully because of the lock, which makes it MT-Safe. Calling it -@c from a signal handler is perfectly safe if the stream is known to be -@c no longer used, which is a precondition for fclose to be safe in the -@c first place; since this is no further requirement, fclose is safe for -@c use in async signals too. After calling fclose, you can no longer -@c use the stream, not even to fclose it again, so its memory and file -@c descriptor may leak if fclose is canceled before @c releasing them. -@c That the stream must be unused and it becomes unused after the call -@c is what would enable fclose to be AS- and AC-Safe while freopen -@c isn't. However, because of the possibility of leaving __gconv_lock -@c taken upon cancellation, AC-Safety is lost. -This function causes @var{stream} to be closed and the connection to -the corresponding file to be broken. Any buffered output is written -and any buffered input is discarded. The @code{fclose} function returns -a value of @code{0} if the file was closed successfully, and @code{EOF} -if an error was detected. - -It is important to check for errors when you call @code{fclose} to close -an output stream, because real, everyday errors can be detected at this -time. For example, when @code{fclose} writes the remaining buffered -output, it might get an error because the disk is full. Even if you -know the buffer is empty, errors can still occur when closing a file if -you are using NFS. - -The function @code{fclose} is declared in @file{stdio.h}. -@end deftypefun - -To close all streams currently available @theglibc{} provides -another function. - -@comment stdio.h -@comment GNU -@deftypefun int fcloseall (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:streams}}@asunsafe{}@acsafe{}} -@c Like fclose, using any previously-opened streams after fcloseall is -@c undefined. However, the implementation of fcloseall isn't equivalent -@c to calling fclose for all streams: it just flushes and unbuffers all -@c streams, without any locking. It's the flushing without locking that -@c makes it unsafe. -This function causes all open streams of the process to be closed and -the connections to corresponding files to be broken. All buffered data -is written and any buffered input is discarded. The @code{fcloseall} -function returns a value of @code{0} if all the files were closed -successfully, and @code{EOF} if an error was detected. - -This function should be used only in special situations, e.g., when an -error occurred and the program must be aborted. Normally each single -stream should be closed separately so that problems with individual -streams can be identified. It is also problematic since the standard -streams (@pxref{Standard Streams}) will also be closed. - -The function @code{fcloseall} is declared in @file{stdio.h}. -@end deftypefun - -If the @code{main} function to your program returns, or if you call the -@code{exit} function (@pxref{Normal Termination}), all open streams are -automatically closed properly. If your program terminates in any other -manner, such as by calling the @code{abort} function (@pxref{Aborting a -Program}) or from a fatal signal (@pxref{Signal Handling}), open streams -might not be closed properly. Buffered output might not be flushed and -files may be incomplete. For more information on buffering of streams, -see @ref{Stream Buffering}. - -@node Streams and Threads -@section Streams and Threads - -@cindex threads -@cindex multi-threaded application -Streams can be used in multi-threaded applications in the same way they -are used in single-threaded applications. But the programmer must be -aware of the possible complications. It is important to know about -these also if the program one writes never use threads since the design -and implementation of many stream functions are heavily influenced by the -requirements added by multi-threaded programming. - -The POSIX standard requires that by default the stream operations are -atomic. I.e., issuing two stream operations for the same stream in two -threads at the same time will cause the operations to be executed as if -they were issued sequentially. The buffer operations performed while -reading or writing are protected from other uses of the same stream. To -do this each stream has an internal lock object which has to be -(implicitly) acquired before any work can be done. - -But there are situations where this is not enough and there are also -situations where this is not wanted. The implicit locking is not enough -if the program requires more than one stream function call to happen -atomically. One example would be if an output line a program wants to -generate is created by several function calls. The functions by -themselves would ensure only atomicity of their own operation, but not -atomicity over all the function calls. For this it is necessary to -perform the stream locking in the application code. - -@comment stdio.h -@comment POSIX -@deftypefun void flockfile (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} -@c There's no way to tell whether the lock was acquired before or after -@c cancellation so as to unlock only when appropriate. -The @code{flockfile} function acquires the internal locking object -associated with the stream @var{stream}. This ensures that no other -thread can explicitly through @code{flockfile}/@code{ftrylockfile} or -implicitly through the call of a stream function lock the stream. The -thread will block until the lock is acquired. An explicit call to -@code{funlockfile} has to be used to release the lock. -@end deftypefun - -@comment stdio.h -@comment POSIX -@deftypefun int ftrylockfile (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} -The @code{ftrylockfile} function tries to acquire the internal locking -object associated with the stream @var{stream} just like -@code{flockfile}. But unlike @code{flockfile} this function does not -block if the lock is not available. @code{ftrylockfile} returns zero if -the lock was successfully acquired. Otherwise the stream is locked by -another thread. -@end deftypefun - -@comment stdio.h -@comment POSIX -@deftypefun void funlockfile (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} -The @code{funlockfile} function releases the internal locking object of -the stream @var{stream}. The stream must have been locked before by a -call to @code{flockfile} or a successful call of @code{ftrylockfile}. -The implicit locking performed by the stream operations do not count. -The @code{funlockfile} function does not return an error status and the -behavior of a call for a stream which is not locked by the current -thread is undefined. -@end deftypefun - -The following example shows how the functions above can be used to -generate an output line atomically even in multi-threaded applications -(yes, the same job could be done with one @code{fprintf} call but it is -sometimes not possible): - -@smallexample -FILE *fp; -@{ - @dots{} - flockfile (fp); - fputs ("This is test number ", fp); - fprintf (fp, "%d\n", test); - funlockfile (fp) -@} -@end smallexample - -Without the explicit locking it would be possible for another thread to -use the stream @var{fp} after the @code{fputs} call returns and before -@code{fprintf} was called with the result that the number does not -follow the word @samp{number}. - -From this description it might already be clear that the locking objects -in streams are no simple mutexes. Since locking the same stream twice -in the same thread is allowed the locking objects must be equivalent to -recursive mutexes. These mutexes keep track of the owner and the number -of times the lock is acquired. The same number of @code{funlockfile} -calls by the same threads is necessary to unlock the stream completely. -For instance: - -@smallexample -void -foo (FILE *fp) -@{ - ftrylockfile (fp); - fputs ("in foo\n", fp); - /* @r{This is very wrong!!!} */ - funlockfile (fp); -@} -@end smallexample - -It is important here that the @code{funlockfile} function is only called -if the @code{ftrylockfile} function succeeded in locking the stream. It -is therefore always wrong to ignore the result of @code{ftrylockfile}. -And it makes no sense since otherwise one would use @code{flockfile}. -The result of code like that above is that either @code{funlockfile} -tries to free a stream that hasn't been locked by the current thread or it -frees the stream prematurely. The code should look like this: - -@smallexample -void -foo (FILE *fp) -@{ - if (ftrylockfile (fp) == 0) - @{ - fputs ("in foo\n", fp); - funlockfile (fp); - @} -@} -@end smallexample - -Now that we covered why it is necessary to have locking it is -necessary to talk about situations when locking is unwanted and what can -be done. The locking operations (explicit or implicit) don't come for -free. Even if a lock is not taken the cost is not zero. The operations -which have to be performed require memory operations that are safe in -multi-processor environments. With the many local caches involved in -such systems this is quite costly. So it is best to avoid the locking -completely if it is not needed -- because the code in question is never -used in a context where two or more threads may use a stream at a time. -This can be determined most of the time for application code; for -library code which can be used in many contexts one should default to be -conservative and use locking. - -There are two basic mechanisms to avoid locking. The first is to use -the @code{_unlocked} variants of the stream operations. The POSIX -standard defines quite a few of those and @theglibc{} adds a few -more. These variants of the functions behave just like the functions -with the name without the suffix except that they do not lock the -stream. Using these functions is very desirable since they are -potentially much faster. This is not only because the locking -operation itself is avoided. More importantly, functions like -@code{putc} and @code{getc} are very simple and traditionally (before the -introduction of threads) were implemented as macros which are very fast -if the buffer is not empty. With the addition of locking requirements -these functions are no longer implemented as macros since they would -expand to too much code. -But these macros are still available with the same functionality under the new -names @code{putc_unlocked} and @code{getc_unlocked}. This possibly huge -difference of speed also suggests the use of the @code{_unlocked} -functions even if locking is required. The difference is that the -locking then has to be performed in the program: - -@smallexample -void -foo (FILE *fp, char *buf) -@{ - flockfile (fp); - while (*buf != '/') - putc_unlocked (*buf++, fp); - funlockfile (fp); -@} -@end smallexample - -If in this example the @code{putc} function would be used and the -explicit locking would be missing the @code{putc} function would have to -acquire the lock in every call, potentially many times depending on when -the loop terminates. Writing it the way illustrated above allows the -@code{putc_unlocked} macro to be used which means no locking and direct -manipulation of the buffer of the stream. - -A second way to avoid locking is by using a non-standard function which -was introduced in Solaris and is available in @theglibc{} as well. - -@comment stdio_ext.h -@comment GNU -@deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asulock{}}@acsafe{}} -@c Changing the implicit-locking status of a stream while it's in use by -@c another thread may cause a lock to be implicitly acquired and not -@c released, or vice-versa. This function should probably hold the lock -@c while changing this setting, to make sure we don't change it while -@c there are any concurrent uses. Meanwhile, callers should acquire the -@c lock themselves to be safe, and even concurrent uses with external -@c locking will be fine, as long as functions that require external -@c locking are not called without holding locks. - -The @code{__fsetlocking} function can be used to select whether the -stream operations will implicitly acquire the locking object of the -stream @var{stream}. By default this is done but it can be disabled and -reinstated using this function. There are three values defined for the -@var{type} parameter. - -@vtable @code -@item FSETLOCKING_INTERNAL -The stream @code{stream} will from now on use the default internal -locking. Every stream operation with exception of the @code{_unlocked} -variants will implicitly lock the stream. - -@item FSETLOCKING_BYCALLER -After the @code{__fsetlocking} function returns, the user is responsible -for locking the stream. None of the stream operations will implicitly -do this anymore until the state is set back to -@code{FSETLOCKING_INTERNAL}. - -@item FSETLOCKING_QUERY -@code{__fsetlocking} only queries the current locking state of the -stream. The return value will be @code{FSETLOCKING_INTERNAL} or -@code{FSETLOCKING_BYCALLER} depending on the state. -@end vtable - -The return value of @code{__fsetlocking} is either -@code{FSETLOCKING_INTERNAL} or @code{FSETLOCKING_BYCALLER} depending on -the state of the stream before the call. - -This function and the values for the @var{type} parameter are declared -in @file{stdio_ext.h}. -@end deftypefun - -This function is especially useful when program code has to be used -which is written without knowledge about the @code{_unlocked} functions -(or if the programmer was too lazy to use them). - -@node Streams and I18N -@section Streams in Internationalized Applications - -@w{ISO C90} introduced the new type @code{wchar_t} to allow handling -larger character sets. What was missing was a possibility to output -strings of @code{wchar_t} directly. One had to convert them into -multibyte strings using @code{mbstowcs} (there was no @code{mbsrtowcs} -yet) and then use the normal stream functions. While this is doable it -is very cumbersome since performing the conversions is not trivial and -greatly increases program complexity and size. - -The Unix standard early on (I think in XPG4.2) introduced two additional -format specifiers for the @code{printf} and @code{scanf} families of -functions. Printing and reading of single wide characters was made -possible using the @code{%C} specifier and wide character strings can be -handled with @code{%S}. These modifiers behave just like @code{%c} and -@code{%s} only that they expect the corresponding argument to have the -wide character type and that the wide character and string are -transformed into/from multibyte strings before being used. - -This was a beginning but it is still not good enough. Not always is it -desirable to use @code{printf} and @code{scanf}. The other, smaller and -faster functions cannot handle wide characters. Second, it is not -possible to have a format string for @code{printf} and @code{scanf} -consisting of wide characters. The result is that format strings would -have to be generated if they have to contain non-basic characters. - -@cindex C++ streams -@cindex streams, C++ -In the @w{Amendment 1} to @w{ISO C90} a whole new set of functions was -added to solve the problem. Most of the stream functions got a -counterpart which take a wide character or wide character string instead -of a character or string respectively. The new functions operate on the -same streams (like @code{stdout}). This is different from the model of -the C++ runtime library where separate streams for wide and normal I/O -are used. - -@cindex orientation, stream -@cindex stream orientation -Being able to use the same stream for wide and normal operations comes -with a restriction: a stream can be used either for wide operations or -for normal operations. Once it is decided there is no way back. Only a -call to @code{freopen} or @code{freopen64} can reset the -@dfn{orientation}. The orientation can be decided in three ways: - -@itemize @bullet -@item -If any of the normal character functions are used (this includes the -@code{fread} and @code{fwrite} functions) the stream is marked as not -wide oriented. - -@item -If any of the wide character functions are used the stream is marked as -wide oriented. - -@item -The @code{fwide} function can be used to set the orientation either way. -@end itemize - -It is important to never mix the use of wide and not wide operations on -a stream. There are no diagnostics issued. The application behavior -will simply be strange or the application will simply crash. The -@code{fwide} function can help avoid this. - -@comment wchar.h -@comment ISO -@deftypefun int fwide (FILE *@var{stream}, int @var{mode}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{}}} -@c Querying is always safe, but changing the stream when it's in use -@c upthread may be problematic. Like most lock-acquiring functions, -@c this one may leak the lock if canceled. - -The @code{fwide} function can be used to set and query the state of the -orientation of the stream @var{stream}. If the @var{mode} parameter has -a positive value the streams get wide oriented, for negative values -narrow oriented. It is not possible to overwrite previous orientations -with @code{fwide}. I.e., if the stream @var{stream} was already -oriented before the call nothing is done. - -If @var{mode} is zero the current orientation state is queried and -nothing is changed. - -The @code{fwide} function returns a negative value, zero, or a positive -value if the stream is narrow, not at all, or wide oriented -respectively. - -This function was introduced in @w{Amendment 1} to @w{ISO C90} and is -declared in @file{wchar.h}. -@end deftypefun - -It is generally a good idea to orient a stream as early as possible. -This can prevent surprise especially for the standard streams -@code{stdin}, @code{stdout}, and @code{stderr}. If some library -function in some situations uses one of these streams and this use -orients the stream in a different way the rest of the application -expects it one might end up with hard to reproduce errors. Remember -that no errors are signal if the streams are used incorrectly. Leaving -a stream unoriented after creation is normally only necessary for -library functions which create streams which can be used in different -contexts. - -When writing code which uses streams and which can be used in different -contexts it is important to query the orientation of the stream before -using it (unless the rules of the library interface demand a specific -orientation). The following little, silly function illustrates this. - -@smallexample -void -print_f (FILE *fp) -@{ - if (fwide (fp, 0) > 0) - /* @r{Positive return value means wide orientation.} */ - fputwc (L'f', fp); - else - fputc ('f', fp); -@} -@end smallexample - -Note that in this case the function @code{print_f} decides about the -orientation of the stream if it was unoriented before (will not happen -if the advice above is followed). - -The encoding used for the @code{wchar_t} values is unspecified and the -user must not make any assumptions about it. For I/O of @code{wchar_t} -values this means that it is impossible to write these values directly -to the stream. This is not what follows from the @w{ISO C} locale model -either. What happens instead is that the bytes read from or written to -the underlying media are first converted into the internal encoding -chosen by the implementation for @code{wchar_t}. The external encoding -is determined by the @code{LC_CTYPE} category of the current locale or -by the @samp{ccs} part of the mode specification given to @code{fopen}, -@code{fopen64}, @code{freopen}, or @code{freopen64}. How and when the -conversion happens is unspecified and it happens invisibly to the user. - -Since a stream is created in the unoriented state it has at that point -no conversion associated with it. The conversion which will be used is -determined by the @code{LC_CTYPE} category selected at the time the -stream is oriented. If the locales are changed at the runtime this -might produce surprising results unless one pays attention. This is -just another good reason to orient the stream explicitly as soon as -possible, perhaps with a call to @code{fwide}. - -@node Simple Output -@section Simple Output by Characters or Lines - -@cindex writing to a stream, by characters -This section describes functions for performing character- and -line-oriented output. - -These narrow stream functions are declared in the header file -@file{stdio.h} and the wide stream functions in @file{wchar.h}. -@pindex stdio.h -@pindex wchar.h - -@comment stdio.h -@comment ISO -@deftypefun int fputc (int @var{c}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} -@c If the stream is in use when interrupted by a signal, the recursive -@c lock won't help ensure the stream is consistent; indeed, if fputc -@c gets a signal precisely before the post-incremented _IO_write_ptr -@c value is stored, we may overwrite the interrupted write. Conversely, -@c depending on compiler optimizations, the incremented _IO_write_ptr -@c may be stored before the character is stored in the buffer, -@c corrupting the stream if async cancel hits between the two stores. -@c There may be other reasons for AS- and AC-unsafety in the overflow -@c cases. -The @code{fputc} function converts the character @var{c} to type -@code{unsigned char}, and writes it to the stream @var{stream}. -@code{EOF} is returned if a write error occurs; otherwise the -character @var{c} is returned. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun wint_t fputwc (wchar_t @var{wc}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} -The @code{fputwc} function writes the wide character @var{wc} to the -stream @var{stream}. @code{WEOF} is returned if a write error occurs; -otherwise the character @var{wc} is returned. -@end deftypefun - -@comment stdio.h -@comment POSIX -@deftypefun int fputc_unlocked (int @var{c}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -@c The unlocked functions can't possibly satisfy the MT-Safety -@c requirements on their own, because they require external locking for -@c safety. -The @code{fputc_unlocked} function is equivalent to the @code{fputc} -function except that it does not implicitly lock the stream. -@end deftypefun - -@comment wchar.h -@comment POSIX -@deftypefun wint_t fputwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{fputwc_unlocked} function is equivalent to the @code{fputwc} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int putc (int @var{c}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} -This is just like @code{fputc}, except that most systems implement it as -a macro, making it faster. One consequence is that it may evaluate the -@var{stream} argument more than once, which is an exception to the -general rule for macros. @code{putc} is usually the best function to -use for writing a single character. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} -This is just like @code{fputwc}, except that it can be implement as -a macro, making it faster. One consequence is that it may evaluate the -@var{stream} argument more than once, which is an exception to the -general rule for macros. @code{putwc} is usually the best function to -use for writing a single wide character. -@end deftypefun - -@comment stdio.h -@comment POSIX -@deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{putc_unlocked} function is equivalent to the @code{putc} -function except that it does not implicitly lock the stream. -@end deftypefun - -@comment wchar.h -@comment GNU -@deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{putwc_unlocked} function is equivalent to the @code{putwc} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int putchar (int @var{c}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} -The @code{putchar} function is equivalent to @code{putc} with -@code{stdout} as the value of the @var{stream} argument. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun wint_t putwchar (wchar_t @var{wc}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} -The @code{putwchar} function is equivalent to @code{putwc} with -@code{stdout} as the value of the @var{stream} argument. -@end deftypefun - -@comment stdio.h -@comment POSIX -@deftypefun int putchar_unlocked (int @var{c}) -@safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{putchar_unlocked} function is equivalent to the @code{putchar} -function except that it does not implicitly lock the stream. -@end deftypefun - -@comment wchar.h -@comment GNU -@deftypefun wint_t putwchar_unlocked (wchar_t @var{wc}) -@safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{putwchar_unlocked} function is equivalent to the @code{putwchar} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int fputs (const char *@var{s}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} -The function @code{fputs} writes the string @var{s} to the stream -@var{stream}. The terminating null character is not written. -This function does @emph{not} add a newline character, either. -It outputs only the characters in the string. - -This function returns @code{EOF} if a write error occurs, and otherwise -a non-negative value. - -For example: - -@smallexample -fputs ("Are ", stdout); -fputs ("you ", stdout); -fputs ("hungry?\n", stdout); -@end smallexample - -@noindent -outputs the text @samp{Are you hungry?} followed by a newline. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun int fputws (const wchar_t *@var{ws}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} -The function @code{fputws} writes the wide character string @var{ws} to -the stream @var{stream}. The terminating null character is not written. -This function does @emph{not} add a newline character, either. It -outputs only the characters in the string. - -This function returns @code{WEOF} if a write error occurs, and otherwise -a non-negative value. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{fputs_unlocked} function is equivalent to the @code{fputs} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -@comment wchar.h -@comment GNU -@deftypefun int fputws_unlocked (const wchar_t *@var{ws}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{fputws_unlocked} function is equivalent to the @code{fputws} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int puts (const char *@var{s}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The @code{puts} function writes the string @var{s} to the stream -@code{stdout} followed by a newline. The terminating null character of -the string is not written. (Note that @code{fputs} does @emph{not} -write a newline as this function does.) - -@code{puts} is the most convenient function for printing simple -messages. For example: - -@smallexample -puts ("This is a message."); -@end smallexample - -@noindent -outputs the text @samp{This is a message.} followed by a newline. -@end deftypefun - -@comment stdio.h -@comment SVID -@deftypefun int putw (int @var{w}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function writes the word @var{w} (that is, an @code{int}) to -@var{stream}. It is provided for compatibility with SVID, but we -recommend you use @code{fwrite} instead (@pxref{Block Input/Output}). -@end deftypefun - -@node Character Input -@section Character Input - -@cindex reading from a stream, by characters -This section describes functions for performing character-oriented -input. These narrow stream functions are declared in the header file -@file{stdio.h} and the wide character functions are declared in -@file{wchar.h}. -@pindex stdio.h -@pindex wchar.h - -These functions return an @code{int} or @code{wint_t} value (for narrow -and wide stream functions respectively) that is either a character of -input, or the special value @code{EOF}/@code{WEOF} (usually -1). For -the narrow stream functions it is important to store the result of these -functions in a variable of type @code{int} instead of @code{char}, even -when you plan to use it only as a character. Storing @code{EOF} in a -@code{char} variable truncates its value to the size of a character, so -that it is no longer distinguishable from the valid character -@samp{(char) -1}. So always use an @code{int} for the result of -@code{getc} and friends, and check for @code{EOF} after the call; once -you've verified that the result is not @code{EOF}, you can be sure that -it will fit in a @samp{char} variable without loss of information. - -@comment stdio.h -@comment ISO -@deftypefun int fgetc (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -@c Same caveats as fputc, but instead of losing a write in case of async -@c signals, we may read the same character more than once, and the -@c stream may be left in odd states due to cancellation in the underflow -@c cases. -This function reads the next character as an @code{unsigned char} from -the stream @var{stream} and returns its value, converted to an -@code{int}. If an end-of-file condition or read error occurs, -@code{EOF} is returned instead. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun wint_t fgetwc (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function reads the next wide character from the stream @var{stream} -and returns its value. If an end-of-file condition or read error -occurs, @code{WEOF} is returned instead. -@end deftypefun - -@comment stdio.h -@comment POSIX -@deftypefun int fgetc_unlocked (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{fgetc_unlocked} function is equivalent to the @code{fgetc} -function except that it does not implicitly lock the stream. -@end deftypefun - -@comment wchar.h -@comment GNU -@deftypefun wint_t fgetwc_unlocked (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int getc (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This is just like @code{fgetc}, except that it is permissible (and -typical) for it to be implemented as a macro that evaluates the -@var{stream} argument more than once. @code{getc} is often highly -optimized, so it is usually the best function to use to read a single -character. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun wint_t getwc (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This is just like @code{fgetwc}, except that it is permissible for it to -be implemented as a macro that evaluates the @var{stream} argument more -than once. @code{getwc} can be highly optimized, so it is usually the -best function to use to read a single wide character. -@end deftypefun - -@comment stdio.h -@comment POSIX -@deftypefun int getc_unlocked (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{getc_unlocked} function is equivalent to the @code{getc} -function except that it does not implicitly lock the stream. -@end deftypefun - -@comment wchar.h -@comment GNU -@deftypefun wint_t getwc_unlocked (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{getwc_unlocked} function is equivalent to the @code{getwc} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int getchar (void) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The @code{getchar} function is equivalent to @code{getc} with @code{stdin} -as the value of the @var{stream} argument. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun wint_t getwchar (void) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin} -as the value of the @var{stream} argument. -@end deftypefun - -@comment stdio.h -@comment POSIX -@deftypefun int getchar_unlocked (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{getchar_unlocked} function is equivalent to the @code{getchar} -function except that it does not implicitly lock the stream. -@end deftypefun - -@comment wchar.h -@comment GNU -@deftypefun wint_t getwchar_unlocked (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{getwchar_unlocked} function is equivalent to the @code{getwchar} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -Here is an example of a function that does input using @code{fgetc}. It -would work just as well using @code{getc} instead, or using -@code{getchar ()} instead of @w{@code{fgetc (stdin)}}. The code would -also work the same for the wide character stream functions. - -@smallexample -int -y_or_n_p (const char *question) -@{ - fputs (question, stdout); - while (1) - @{ - int c, answer; - /* @r{Write a space to separate answer from question.} */ - fputc (' ', stdout); - /* @r{Read the first character of the line.} - @r{This should be the answer character, but might not be.} */ - c = tolower (fgetc (stdin)); - answer = c; - /* @r{Discard rest of input line.} */ - while (c != '\n' && c != EOF) - c = fgetc (stdin); - /* @r{Obey the answer if it was valid.} */ - if (answer == 'y') - return 1; - if (answer == 'n') - return 0; - /* @r{Answer was invalid: ask for valid answer.} */ - fputs ("Please answer y or n:", stdout); - @} -@} -@end smallexample - -@comment stdio.h -@comment SVID -@deftypefun int getw (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function reads a word (that is, an @code{int}) from @var{stream}. -It's provided for compatibility with SVID. We recommend you use -@code{fread} instead (@pxref{Block Input/Output}). Unlike @code{getc}, -any @code{int} value could be a valid result. @code{getw} returns -@code{EOF} when it encounters end-of-file or an error, but there is no -way to distinguish this from an input word with value -1. -@end deftypefun - -@node Line Input -@section Line-Oriented Input - -Since many programs interpret input on the basis of lines, it is -convenient to have functions to read a line of text from a stream. - -Standard C has functions to do this, but they aren't very safe: null -characters and even (for @code{gets}) long lines can confuse them. So -@theglibc{} provides the nonstandard @code{getline} function that -makes it easy to read lines reliably. - -Another GNU extension, @code{getdelim}, generalizes @code{getline}. It -reads a delimited record, defined as everything through the next -occurrence of a specified delimiter character. - -All these functions are declared in @file{stdio.h}. - -@comment stdio.h -@comment GNU -@deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} -@c Besides the usual possibility of getting an inconsistent stream in a -@c signal handler or leaving it inconsistent in case of cancellation, -@c the possibility of leaving a dangling pointer upon cancellation -@c between reallocing the buffer at *lineptr and updating the pointer -@c brings about another case of @acucorrupt. -This function reads an entire line from @var{stream}, storing the text -(including the newline and a terminating null character) in a buffer -and storing the buffer address in @code{*@var{lineptr}}. - -Before calling @code{getline}, you should place in @code{*@var{lineptr}} -the address of a buffer @code{*@var{n}} bytes long, allocated with -@code{malloc}. If this buffer is long enough to hold the line, -@code{getline} stores the line in this buffer. Otherwise, -@code{getline} makes the buffer bigger using @code{realloc}, storing the -new buffer address back in @code{*@var{lineptr}} and the increased size -back in @code{*@var{n}}. -@xref{Unconstrained Allocation}. - -If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}} -to zero, before the call, then @code{getline} allocates the initial -buffer for you by calling @code{malloc}. This buffer remains allocated -even if @code{getline} encounters errors and is unable to read any bytes. - -In either case, when @code{getline} returns, @code{*@var{lineptr}} is -a @code{char *} which points to the text of the line. - -When @code{getline} is successful, it returns the number of characters -read (including the newline, but not including the terminating null). -This value enables you to distinguish null characters that are part of -the line from the null character inserted as a terminator. - -This function is a GNU extension, but it is the recommended way to read -lines from a stream. The alternative standard functions are unreliable. - -If an error occurs or end of file is reached without any bytes read, -@code{getline} returns @code{-1}. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} -@c See the getline @acucorrupt note. -This function is like @code{getline} except that the character which -tells it to stop reading is not necessarily newline. The argument -@var{delimiter} specifies the delimiter character; @code{getdelim} keeps -reading until it sees that character (or end of file). - -The text is stored in @var{lineptr}, including the delimiter character -and a terminating null. Like @code{getline}, @code{getdelim} makes -@var{lineptr} bigger if it isn't big enough. - -@code{getline} is in fact implemented in terms of @code{getdelim}, just -like this: - -@smallexample -ssize_t -getline (char **lineptr, size_t *n, FILE *stream) -@{ - return getdelim (lineptr, n, '\n', stream); -@} -@end smallexample -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The @code{fgets} function reads characters from the stream @var{stream} -up to and including a newline character and stores them in the string -@var{s}, adding a null character to mark the end of the string. You -must supply @var{count} characters worth of space in @var{s}, but the -number of characters read is at most @var{count} @minus{} 1. The extra -character space is used to hold the null character at the end of the -string. - -If the system is already at end of file when you call @code{fgets}, then -the contents of the array @var{s} are unchanged and a null pointer is -returned. A null pointer is also returned if a read error occurs. -Otherwise, the return value is the pointer @var{s}. - -@strong{Warning:} If the input data has a null character, you can't tell. -So don't use @code{fgets} unless you know the data cannot contain a null. -Don't use it to read files edited by the user because, if the user inserts -a null character, you should either handle it properly or print a clear -error message. We recommend using @code{getline} instead of @code{fgets}. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun {wchar_t *} fgetws (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The @code{fgetws} function reads wide characters from the stream -@var{stream} up to and including a newline character and stores them in -the string @var{ws}, adding a null wide character to mark the end of the -string. You must supply @var{count} wide characters worth of space in -@var{ws}, but the number of characters read is at most @var{count} -@minus{} 1. The extra character space is used to hold the null wide -character at the end of the string. - -If the system is already at end of file when you call @code{fgetws}, then -the contents of the array @var{ws} are unchanged and a null pointer is -returned. A null pointer is also returned if a read error occurs. -Otherwise, the return value is the pointer @var{ws}. - -@strong{Warning:} If the input data has a null wide character (which are -null bytes in the input stream), you can't tell. So don't use -@code{fgetws} unless you know the data cannot contain a null. Don't use -it to read files edited by the user because, if the user inserts a null -character, you should either handle it properly or print a clear error -message. -@comment XXX We need getwline!!! -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun {char *} fgets_unlocked (char *@var{s}, int @var{count}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{fgets_unlocked} function is equivalent to the @code{fgets} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -@comment wchar.h -@comment GNU -@deftypefun {wchar_t *} fgetws_unlocked (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{fgetws_unlocked} function is equivalent to the @code{fgetws} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefn {Deprecated function} {char *} gets (char *@var{s}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The function @code{gets} reads characters from the stream @code{stdin} -up to the next newline character, and stores them in the string @var{s}. -The newline character is discarded (note that this differs from the -behavior of @code{fgets}, which copies the newline character into the -string). If @code{gets} encounters a read error or end-of-file, it -returns a null pointer; otherwise it returns @var{s}. - -@strong{Warning:} The @code{gets} function is @strong{very dangerous} -because it provides no protection against overflowing the string -@var{s}. @Theglibc{} includes it for compatibility only. You -should @strong{always} use @code{fgets} or @code{getline} instead. To -remind you of this, the linker (if using GNU @code{ld}) will issue a -warning whenever you use @code{gets}. -@end deftypefn - -@node Unreading -@section Unreading -@cindex peeking at input -@cindex unreading characters -@cindex pushing input back - -In parser programs it is often useful to examine the next character in -the input stream without removing it from the stream. This is called -``peeking ahead'' at the input because your program gets a glimpse of -the input it will read next. - -Using stream I/O, you can peek ahead at input by first reading it and -then @dfn{unreading} it (also called @dfn{pushing it back} on the stream). -Unreading a character makes it available to be input again from the stream, -by the next call to @code{fgetc} or other input function on that stream. - -@menu -* Unreading Idea:: An explanation of unreading with pictures. -* How Unread:: How to call @code{ungetc} to do unreading. -@end menu - -@node Unreading Idea -@subsection What Unreading Means - -Here is a pictorial explanation of unreading. Suppose you have a -stream reading a file that contains just six characters, the letters -@samp{foobar}. Suppose you have read three characters so far. The -situation looks like this: - -@smallexample -f o o b a r - ^ -@end smallexample - -@noindent -so the next input character will be @samp{b}. - -@c @group Invalid outside @example -If instead of reading @samp{b} you unread the letter @samp{o}, you get a -situation like this: - -@smallexample -f o o b a r - | - o-- - ^ -@end smallexample - -@noindent -so that the next input characters will be @samp{o} and @samp{b}. -@c @end group - -@c @group -If you unread @samp{9} instead of @samp{o}, you get this situation: - -@smallexample -f o o b a r - | - 9-- - ^ -@end smallexample - -@noindent -so that the next input characters will be @samp{9} and @samp{b}. -@c @end group - -@node How Unread -@subsection Using @code{ungetc} To Do Unreading - -The function to unread a character is called @code{ungetc}, because it -reverses the action of @code{getc}. - -@comment stdio.h -@comment ISO -@deftypefun int ungetc (int @var{c}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The @code{ungetc} function pushes back the character @var{c} onto the -input stream @var{stream}. So the next input from @var{stream} will -read @var{c} before anything else. - -If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns -@code{EOF}. This lets you call @code{ungetc} with the return value of -@code{getc} without needing to check for an error from @code{getc}. - -The character that you push back doesn't have to be the same as the last -character that was actually read from the stream. In fact, it isn't -necessary to actually read any characters from the stream before -unreading them with @code{ungetc}! But that is a strange way to write a -program; usually @code{ungetc} is used only to unread a character that -was just read from the same stream. @Theglibc{} supports this -even on files opened in binary mode, but other systems might not. - -@Theglibc{} only supports one character of pushback---in other -words, it does not work to call @code{ungetc} twice without doing input -in between. Other systems might let you push back multiple characters; -then reading from the stream retrieves the characters in the reverse -order that they were pushed. - -Pushing back characters doesn't alter the file; only the internal -buffering for the stream is affected. If a file positioning function -(such as @code{fseek}, @code{fseeko} or @code{rewind}; @pxref{File -Positioning}) is called, any pending pushed-back characters are -discarded. - -Unreading a character on a stream that is at end of file clears the -end-of-file indicator for the stream, because it makes the character of -input available. After you read that character, trying to read again -will encounter end of file. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The @code{ungetwc} function behaves just like @code{ungetc} just that it -pushes back a wide character. -@end deftypefun - -Here is an example showing the use of @code{getc} and @code{ungetc} to -skip over whitespace characters. When this function reaches a -non-whitespace character, it unreads that character to be seen again on -the next read operation on the stream. - -@smallexample -#include <stdio.h> -#include <ctype.h> - -void -skip_whitespace (FILE *stream) -@{ - int c; - do - /* @r{No need to check for @code{EOF} because it is not} - @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.} */ - c = getc (stream); - while (isspace (c)); - ungetc (c, stream); -@} -@end smallexample - -@node Block Input/Output -@section Block Input/Output - -This section describes how to do input and output operations on blocks -of data. You can use these functions to read and write binary data, as -well as to read and write text in fixed-size blocks instead of by -characters or lines. -@cindex binary I/O to a stream -@cindex block I/O to a stream -@cindex reading from a stream, by blocks -@cindex writing to a stream, by blocks - -Binary files are typically used to read and write blocks of data in the -same format as is used to represent the data in a running program. In -other words, arbitrary blocks of memory---not just character or string -objects---can be written to a binary file, and meaningfully read in -again by the same program. - -Storing data in binary form is often considerably more efficient than -using the formatted I/O functions. Also, for floating-point numbers, -the binary form avoids possible loss of precision in the conversion -process. On the other hand, binary files can't be examined or modified -easily using many standard file utilities (such as text editors), and -are not portable between different implementations of the language, or -different kinds of computers. - -These functions are declared in @file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment ISO -@deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function reads up to @var{count} objects of size @var{size} into -the array @var{data}, from the stream @var{stream}. It returns the -number of objects actually read, which might be less than @var{count} if -a read error occurs or the end of the file is reached. This function -returns a value of zero (and doesn't read anything) if either @var{size} -or @var{count} is zero. - -If @code{fread} encounters end of file in the middle of an object, it -returns the number of complete objects read, and discards the partial -object. Therefore, the stream remains at the actual end of the file. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun size_t fread_unlocked (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{fread_unlocked} function is equivalent to the @code{fread} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function writes up to @var{count} objects of size @var{size} from -the array @var{data}, to the stream @var{stream}. The return value is -normally @var{count}, if the call succeeds. Any other value indicates -some sort of error, such as running out of space. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun size_t fwrite_unlocked (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{fwrite_unlocked} function is equivalent to the @code{fwrite} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -@node Formatted Output -@section Formatted Output - -@cindex format string, for @code{printf} -@cindex template, for @code{printf} -@cindex formatted output to a stream -@cindex writing to a stream, formatted -The functions described in this section (@code{printf} and related -functions) provide a convenient way to perform formatted output. You -call @code{printf} with a @dfn{format string} or @dfn{template string} -that specifies how to format the values of the remaining arguments. - -Unless your program is a filter that specifically performs line- or -character-oriented processing, using @code{printf} or one of the other -related functions described in this section is usually the easiest and -most concise way to perform output. These functions are especially -useful for printing error messages, tables of data, and the like. - -@menu -* Formatted Output Basics:: Some examples to get you started. -* Output Conversion Syntax:: General syntax of conversion - specifications. -* Table of Output Conversions:: Summary of output conversions and - what they do. -* Integer Conversions:: Details about formatting of integers. -* Floating-Point Conversions:: Details about formatting of - floating-point numbers. -* Other Output Conversions:: Details about formatting of strings, - characters, pointers, and the like. -* Formatted Output Functions:: Descriptions of the actual functions. -* Dynamic Output:: Functions that allocate memory for the output. -* Variable Arguments Output:: @code{vprintf} and friends. -* Parsing a Template String:: What kinds of args does a given template - call for? -* Example of Parsing:: Sample program using @code{parse_printf_format}. -@end menu - -@node Formatted Output Basics -@subsection Formatted Output Basics - -The @code{printf} function can be used to print any number of arguments. -The template string argument you supply in a call provides -information not only about the number of additional arguments, but also -about their types and what style should be used for printing them. - -Ordinary characters in the template string are simply written to the -output stream as-is, while @dfn{conversion specifications} introduced by -a @samp{%} character in the template cause subsequent arguments to be -formatted and written to the output stream. For example, -@cindex conversion specifications (@code{printf}) - -@smallexample -int pct = 37; -char filename[] = "foo.txt"; -printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n", - filename, pct); -@end smallexample - -@noindent -produces output like - -@smallexample -Processing of `foo.txt' is 37% finished. -Please be patient. -@end smallexample - -This example shows the use of the @samp{%d} conversion to specify that -an @code{int} argument should be printed in decimal notation, the -@samp{%s} conversion to specify printing of a string argument, and -the @samp{%%} conversion to print a literal @samp{%} character. - -There are also conversions for printing an integer argument as an -unsigned value in octal, decimal, or hexadecimal radix (@samp{%o}, -@samp{%u}, or @samp{%x}, respectively); or as a character value -(@samp{%c}). - -Floating-point numbers can be printed in normal, fixed-point notation -using the @samp{%f} conversion or in exponential notation using the -@samp{%e} conversion. The @samp{%g} conversion uses either @samp{%e} -or @samp{%f} format, depending on what is more appropriate for the -magnitude of the particular number. - -You can control formatting more precisely by writing @dfn{modifiers} -between the @samp{%} and the character that indicates which conversion -to apply. These slightly alter the ordinary behavior of the conversion. -For example, most conversion specifications permit you to specify a -minimum field width and a flag indicating whether you want the result -left- or right-justified within the field. - -The specific flags and modifiers that are permitted and their -interpretation vary depending on the particular conversion. They're all -described in more detail in the following sections. Don't worry if this -all seems excessively complicated at first; you can almost always get -reasonable free-format output without using any of the modifiers at all. -The modifiers are mostly used to make the output look ``prettier'' in -tables. - -@node Output Conversion Syntax -@subsection Output Conversion Syntax - -This section provides details about the precise syntax of conversion -specifications that can appear in a @code{printf} template -string. - -Characters in the template string that are not part of a conversion -specification are printed as-is to the output stream. Multibyte -character sequences (@pxref{Character Set Handling}) are permitted in a -template string. - -The conversion specifications in a @code{printf} template string have -the general form: - -@smallexample -% @r{[} @var{param-no} @r{$]} @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion} -@end smallexample - -@noindent -or - -@smallexample -% @r{[} @var{param-no} @r{$]} @var{flags} @var{width} . @r{*} @r{[} @var{param-no} @r{$]} @var{type} @var{conversion} -@end smallexample - -For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-} -is a flag, @samp{10} specifies the field width, the precision is -@samp{8}, the letter @samp{l} is a type modifier, and @samp{d} specifies -the conversion style. (This particular type specifier says to -print a @code{long int} argument in decimal notation, with a minimum of -8 digits left-justified in a field at least 10 characters wide.) - -In more detail, output conversion specifications consist of an -initial @samp{%} character followed in sequence by: - -@itemize @bullet -@item -An optional specification of the parameter used for this format. -Normally the parameters to the @code{printf} function are assigned to the -formats in the order of appearance in the format string. But in some -situations (such as message translation) this is not desirable and this -extension allows an explicit parameter to be specified. - -The @var{param-no} parts of the format must be integers in the range of -1 to the maximum number of arguments present to the function call. Some -implementations limit this number to a certain upper bound. The exact -limit can be retrieved by the following constant. - -@defvr Macro NL_ARGMAX -The value of @code{NL_ARGMAX} is the maximum value allowed for the -specification of a positional parameter in a @code{printf} call. The -actual value in effect at runtime can be retrieved by using -@code{sysconf} using the @code{_SC_NL_ARGMAX} parameter @pxref{Sysconf -Definition}. - -Some systems have a quite low limit such as @math{9} for @w{System V} -systems. @Theglibc{} has no real limit. -@end defvr - -If any of the formats has a specification for the parameter position all -of them in the format string shall have one. Otherwise the behavior is -undefined. - -@item -Zero or more @dfn{flag characters} that modify the normal behavior of -the conversion specification. -@cindex flag character (@code{printf}) - -@item -An optional decimal integer specifying the @dfn{minimum field width}. -If the normal conversion produces fewer characters than this, the field -is padded with spaces to the specified width. This is a @emph{minimum} -value; if the normal conversion produces more characters than this, the -field is @emph{not} truncated. Normally, the output is right-justified -within the field. -@cindex minimum field width (@code{printf}) - -You can also specify a field width of @samp{*}. This means that the -next argument in the argument list (before the actual value to be -printed) is used as the field width. The value must be an @code{int}. -If the value is negative, this means to set the @samp{-} flag (see -below) and to use the absolute value as the field width. - -@item -An optional @dfn{precision} to specify the number of digits to be -written for the numeric conversions. If the precision is specified, it -consists of a period (@samp{.}) followed optionally by a decimal integer -(which defaults to zero if omitted). -@cindex precision (@code{printf}) - -You can also specify a precision of @samp{*}. This means that the next -argument in the argument list (before the actual value to be printed) is -used as the precision. The value must be an @code{int}, and is ignored -if it is negative. If you specify @samp{*} for both the field width and -precision, the field width argument precedes the precision argument. -Other C library versions may not recognize this syntax. - -@item -An optional @dfn{type modifier character}, which is used to specify the -data type of the corresponding argument if it differs from the default -type. (For example, the integer conversions assume a type of @code{int}, -but you can specify @samp{h}, @samp{l}, or @samp{L} for other integer -types.) -@cindex type modifier character (@code{printf}) - -@item -A character that specifies the conversion to be applied. -@end itemize - -The exact options that are permitted and how they are interpreted vary -between the different conversion specifiers. See the descriptions of the -individual conversions for information about the particular options that -they use. - -With the @samp{-Wformat} option, the GNU C compiler checks calls to -@code{printf} and related functions. It examines the format string and -verifies that the correct number and types of arguments are supplied. -There is also a GNU C syntax to tell the compiler that a function you -write uses a @code{printf}-style format string. -@xref{Function Attributes, , Declaring Attributes of Functions, -gcc.info, Using GNU CC}, for more information. - -@node Table of Output Conversions -@subsection Table of Output Conversions -@cindex output conversions, for @code{printf} - -Here is a table summarizing what all the different conversions do: - -@table @asis -@item @samp{%d}, @samp{%i} -Print an integer as a signed decimal number. @xref{Integer -Conversions}, for details. @samp{%d} and @samp{%i} are synonymous for -output, but are different when used with @code{scanf} for input -(@pxref{Table of Input Conversions}). - -@item @samp{%o} -Print an integer as an unsigned octal number. @xref{Integer -Conversions}, for details. - -@item @samp{%u} -Print an integer as an unsigned decimal number. @xref{Integer -Conversions}, for details. - -@item @samp{%x}, @samp{%X} -Print an integer as an unsigned hexadecimal number. @samp{%x} uses -lower-case letters and @samp{%X} uses upper-case. @xref{Integer -Conversions}, for details. - -@item @samp{%f} -Print a floating-point number in normal (fixed-point) notation. -@xref{Floating-Point Conversions}, for details. - -@item @samp{%e}, @samp{%E} -Print a floating-point number in exponential notation. @samp{%e} uses -lower-case letters and @samp{%E} uses upper-case. @xref{Floating-Point -Conversions}, for details. - -@item @samp{%g}, @samp{%G} -Print a floating-point number in either normal or exponential notation, -whichever is more appropriate for its magnitude. @samp{%g} uses -lower-case letters and @samp{%G} uses upper-case. @xref{Floating-Point -Conversions}, for details. - -@item @samp{%a}, @samp{%A} -Print a floating-point number in a hexadecimal fractional notation with -the exponent to base 2 represented in decimal digits. @samp{%a} uses -lower-case letters and @samp{%A} uses upper-case. @xref{Floating-Point -Conversions}, for details. - -@item @samp{%c} -Print a single character. @xref{Other Output Conversions}. - -@item @samp{%C} -This is an alias for @samp{%lc} which is supported for compatibility -with the Unix standard. - -@item @samp{%s} -Print a string. @xref{Other Output Conversions}. - -@item @samp{%S} -This is an alias for @samp{%ls} which is supported for compatibility -with the Unix standard. - -@item @samp{%p} -Print the value of a pointer. @xref{Other Output Conversions}. - -@item @samp{%n} -Get the number of characters printed so far. @xref{Other Output Conversions}. -Note that this conversion specification never produces any output. - -@item @samp{%m} -Print the string corresponding to the value of @code{errno}. -(This is a GNU extension.) -@xref{Other Output Conversions}. - -@item @samp{%%} -Print a literal @samp{%} character. @xref{Other Output Conversions}. -@end table - -If the syntax of a conversion specification is invalid, unpredictable -things will happen, so don't do this. If there aren't enough function -arguments provided to supply values for all the conversion -specifications in the template string, or if the arguments are not of -the correct types, the results are unpredictable. If you supply more -arguments than conversion specifications, the extra argument values are -simply ignored; this is sometimes useful. - -@node Integer Conversions -@subsection Integer Conversions - -This section describes the options for the @samp{%d}, @samp{%i}, -@samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion -specifications. These conversions print integers in various formats. - -The @samp{%d} and @samp{%i} conversion specifications both print an -@code{int} argument as a signed decimal number; while @samp{%o}, -@samp{%u}, and @samp{%x} print the argument as an unsigned octal, -decimal, or hexadecimal number (respectively). The @samp{%X} conversion -specification is just like @samp{%x} except that it uses the characters -@samp{ABCDEF} as digits instead of @samp{abcdef}. - -The following flags are meaningful: - -@table @asis -@item @samp{-} -Left-justify the result in the field (instead of the normal -right-justification). - -@item @samp{+} -For the signed @samp{%d} and @samp{%i} conversions, print a -plus sign if the value is positive. - -@item @samp{ } -For the signed @samp{%d} and @samp{%i} conversions, if the result -doesn't start with a plus or minus sign, prefix it with a space -character instead. Since the @samp{+} flag ensures that the result -includes a sign, this flag is ignored if you supply both of them. - -@item @samp{#} -For the @samp{%o} conversion, this forces the leading digit to be -@samp{0}, as if by increasing the precision. For @samp{%x} or -@samp{%X}, this prefixes a leading @samp{0x} or @samp{0X} (respectively) -to the result. This doesn't do anything useful for the @samp{%d}, -@samp{%i}, or @samp{%u} conversions. Using this flag produces output -which can be parsed by the @code{strtoul} function (@pxref{Parsing of -Integers}) and @code{scanf} with the @samp{%i} conversion -(@pxref{Numeric Input Conversions}). - -@item @samp{'} -Separate the digits into groups as specified by the locale specified for -the @code{LC_NUMERIC} category; @pxref{General Numeric}. This flag is a -GNU extension. - -@item @samp{0} -Pad the field with zeros instead of spaces. The zeros are placed after -any indication of sign or base. This flag is ignored if the @samp{-} -flag is also specified, or if a precision is specified. -@end table - -If a precision is supplied, it specifies the minimum number of digits to -appear; leading zeros are produced if necessary. If you don't specify a -precision, the number is printed with as many digits as it needs. If -you convert a value of zero with an explicit precision of zero, then no -characters at all are produced. - -Without a type modifier, the corresponding argument is treated as an -@code{int} (for the signed conversions @samp{%i} and @samp{%d}) or -@code{unsigned int} (for the unsigned conversions @samp{%o}, @samp{%u}, -@samp{%x}, and @samp{%X}). Recall that since @code{printf} and friends -are variadic, any @code{char} and @code{short} arguments are -automatically converted to @code{int} by the default argument -promotions. For arguments of other integer types, you can use these -modifiers: - -@table @samp -@item hh -Specifies that the argument is a @code{signed char} or @code{unsigned -char}, as appropriate. A @code{char} argument is converted to an -@code{int} or @code{unsigned int} by the default argument promotions -anyway, but the @samp{hh} modifier says to convert it back to a -@code{char} again. - -This modifier was introduced in @w{ISO C99}. - -@item h -Specifies that the argument is a @code{short int} or @code{unsigned -short int}, as appropriate. A @code{short} argument is converted to an -@code{int} or @code{unsigned int} by the default argument promotions -anyway, but the @samp{h} modifier says to convert it back to a -@code{short} again. - -@item j -Specifies that the argument is a @code{intmax_t} or @code{uintmax_t}, as -appropriate. - -This modifier was introduced in @w{ISO C99}. - -@item l -Specifies that the argument is a @code{long int} or @code{unsigned long -int}, as appropriate. Two @samp{l} characters are like the @samp{L} -modifier, below. - -If used with @samp{%c} or @samp{%s} the corresponding parameter is -considered as a wide character or wide character string respectively. -This use of @samp{l} was introduced in @w{Amendment 1} to @w{ISO C90}. - -@item L -@itemx ll -@itemx q -Specifies that the argument is a @code{long long int}. (This type is -an extension supported by the GNU C compiler. On systems that don't -support extra-long integers, this is the same as @code{long int}.) - -The @samp{q} modifier is another name for the same thing, which comes -from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad'' -@code{int}. - -@item t -Specifies that the argument is a @code{ptrdiff_t}. - -This modifier was introduced in @w{ISO C99}. - -@item z -@itemx Z -Specifies that the argument is a @code{size_t}. - -@samp{z} was introduced in @w{ISO C99}. @samp{Z} is a GNU extension -predating this addition and should not be used in new code. -@end table - -Here is an example. Using the template string: - -@smallexample -"|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n" -@end smallexample - -@noindent -to print numbers using the different options for the @samp{%d} -conversion gives results like: - -@smallexample -| 0|0 | +0|+0 | 0|00000| | 00|0| -| 1|1 | +1|+1 | 1|00001| 1| 01|1| -| -1|-1 | -1|-1 | -1|-0001| -1| -01|-1| -|100000|100000|+100000|+100000| 100000|100000|100000|100000|100000| -@end smallexample - -In particular, notice what happens in the last case where the number -is too large to fit in the minimum field width specified. - -Here are some more examples showing how unsigned integers print under -various format options, using the template string: - -@smallexample -"|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n" -@end smallexample - -@smallexample -| 0| 0| 0| 0| 0| 0| 0| 00000000| -| 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001| -|100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0| -@end smallexample - - -@node Floating-Point Conversions -@subsection Floating-Point Conversions - -This section discusses the conversion specifications for floating-point -numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G} -conversions. - -The @samp{%f} conversion prints its argument in fixed-point notation, -producing output of the form -@w{[@code{-}]@var{ddd}@code{.}@var{ddd}}, -where the number of digits following the decimal point is controlled -by the precision you specify. - -The @samp{%e} conversion prints its argument in exponential notation, -producing output of the form -@w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}. -Again, the number of digits following the decimal point is controlled by -the precision. The exponent always contains at least two digits. The -@samp{%E} conversion is similar but the exponent is marked with the letter -@samp{E} instead of @samp{e}. - -The @samp{%g} and @samp{%G} conversions print the argument in the style -of @samp{%e} or @samp{%E} (respectively) if the exponent would be less -than -4 or greater than or equal to the precision; otherwise they use -the @samp{%f} style. A precision of @code{0}, is taken as 1. -Trailing zeros are removed from the fractional portion of the result and -a decimal-point character appears only if it is followed by a digit. - -The @samp{%a} and @samp{%A} conversions are meant for representing -floating-point numbers exactly in textual form so that they can be -exchanged as texts between different programs and/or machines. The -numbers are represented in the form -@w{[@code{-}]@code{0x}@var{h}@code{.}@var{hhh}@code{p}[@code{+}|@code{-}]@var{dd}}. -At the left of the decimal-point character exactly one digit is print. -This character is only @code{0} if the number is denormalized. -Otherwise the value is unspecified; it is implementation dependent how many -bits are used. The number of hexadecimal digits on the right side of -the decimal-point character is equal to the precision. If the precision -is zero it is determined to be large enough to provide an exact -representation of the number (or it is large enough to distinguish two -adjacent values if the @code{FLT_RADIX} is not a power of 2, -@pxref{Floating Point Parameters}). For the @samp{%a} conversion -lower-case characters are used to represent the hexadecimal number and -the prefix and exponent sign are printed as @code{0x} and @code{p} -respectively. Otherwise upper-case characters are used and @code{0X} -and @code{P} are used for the representation of prefix and exponent -string. The exponent to the base of two is printed as a decimal number -using at least one digit but at most as many digits as necessary to -represent the value exactly. - -If the value to be printed represents infinity or a NaN, the output is -@w{[@code{-}]@code{inf}} or @code{nan} respectively if the conversion -specifier is @samp{%a}, @samp{%e}, @samp{%f}, or @samp{%g} and it is -@w{[@code{-}]@code{INF}} or @code{NAN} respectively if the conversion is -@samp{%A}, @samp{%E}, or @samp{%G}. - -The following flags can be used to modify the behavior: - -@comment We use @asis instead of @samp so we can have ` ' as an item. -@table @asis -@item @samp{-} -Left-justify the result in the field. Normally the result is -right-justified. - -@item @samp{+} -Always include a plus or minus sign in the result. - -@item @samp{ } -If the result doesn't start with a plus or minus sign, prefix it with a -space instead. Since the @samp{+} flag ensures that the result includes -a sign, this flag is ignored if you supply both of them. - -@item @samp{#} -Specifies that the result should always include a decimal point, even -if no digits follow it. For the @samp{%g} and @samp{%G} conversions, -this also forces trailing zeros after the decimal point to be left -in place where they would otherwise be removed. - -@item @samp{'} -Separate the digits of the integer part of the result into groups as -specified by the locale specified for the @code{LC_NUMERIC} category; -@pxref{General Numeric}. This flag is a GNU extension. - -@item @samp{0} -Pad the field with zeros instead of spaces; the zeros are placed -after any sign. This flag is ignored if the @samp{-} flag is also -specified. -@end table - -The precision specifies how many digits follow the decimal-point -character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions. For -these conversions, the default precision is @code{6}. If the precision -is explicitly @code{0}, this suppresses the decimal point character -entirely. For the @samp{%g} and @samp{%G} conversions, the precision -specifies how many significant digits to print. Significant digits are -the first digit before the decimal point, and all the digits after it. -If the precision is @code{0} or not specified for @samp{%g} or @samp{%G}, -it is treated like a value of @code{1}. If the value being printed -cannot be expressed accurately in the specified number of digits, the -value is rounded to the nearest number that fits. - -Without a type modifier, the floating-point conversions use an argument -of type @code{double}. (By the default argument promotions, any -@code{float} arguments are automatically converted to @code{double}.) -The following type modifier is supported: - -@table @samp -@item L -An uppercase @samp{L} specifies that the argument is a @code{long -double}. -@end table - -Here are some examples showing how numbers print using the various -floating-point conversions. All of the numbers were printed using -this template string: - -@smallexample -"|%13.4a|%13.4f|%13.4e|%13.4g|\n" -@end smallexample - -Here is the output: - -@smallexample -| 0x0.0000p+0| 0.0000| 0.0000e+00| 0| -| 0x1.0000p-1| 0.5000| 5.0000e-01| 0.5| -| 0x1.0000p+0| 1.0000| 1.0000e+00| 1| -| -0x1.0000p+0| -1.0000| -1.0000e+00| -1| -| 0x1.9000p+6| 100.0000| 1.0000e+02| 100| -| 0x1.f400p+9| 1000.0000| 1.0000e+03| 1000| -| 0x1.3880p+13| 10000.0000| 1.0000e+04| 1e+04| -| 0x1.81c8p+13| 12345.0000| 1.2345e+04| 1.234e+04| -| 0x1.86a0p+16| 100000.0000| 1.0000e+05| 1e+05| -| 0x1.e240p+16| 123456.0000| 1.2346e+05| 1.235e+05| -@end smallexample - -Notice how the @samp{%g} conversion drops trailing zeros. - -@node Other Output Conversions -@subsection Other Output Conversions - -This section describes miscellaneous conversions for @code{printf}. - -The @samp{%c} conversion prints a single character. In case there is no -@samp{l} modifier the @code{int} argument is first converted to an -@code{unsigned char}. Then, if used in a wide stream function, the -character is converted into the corresponding wide character. The -@samp{-} flag can be used to specify left-justification in the field, -but no other flags are defined, and no precision or type modifier can be -given. For example: - -@smallexample -printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o'); -@end smallexample - -@noindent -prints @samp{hello}. - -If there is an @samp{l} modifier present the argument is expected to be -of type @code{wint_t}. If used in a multibyte function the wide -character is converted into a multibyte character before being added to -the output. In this case more than one output byte can be produced. - -The @samp{%s} conversion prints a string. If no @samp{l} modifier is -present the corresponding argument must be of type @code{char *} (or -@code{const char *}). If used in a wide stream function the string is -first converted to a wide character string. A precision can be -specified to indicate the maximum number of characters to write; -otherwise characters in the string up to but not including the -terminating null character are written to the output stream. The -@samp{-} flag can be used to specify left-justification in the field, -but no other flags or type modifiers are defined for this conversion. -For example: - -@smallexample -printf ("%3s%-6s", "no", "where"); -@end smallexample - -@noindent -prints @samp{ nowhere }. - -If there is an @samp{l} modifier present, the argument is expected to -be of type @code{wchar_t} (or @code{const wchar_t *}). - -If you accidentally pass a null pointer as the argument for a @samp{%s} -conversion, @theglibc{} prints it as @samp{(null)}. We think this -is more useful than crashing. But it's not good practice to pass a null -argument intentionally. - -The @samp{%m} conversion prints the string corresponding to the error -code in @code{errno}. @xref{Error Messages}. Thus: - -@smallexample -fprintf (stderr, "can't open `%s': %m\n", filename); -@end smallexample - -@noindent -is equivalent to: - -@smallexample -fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno)); -@end smallexample - -@noindent -The @samp{%m} conversion is a @glibcadj{} extension. - -The @samp{%p} conversion prints a pointer value. The corresponding -argument must be of type @code{void *}. In practice, you can use any -type of pointer. - -In @theglibc{}, non-null pointers are printed as unsigned integers, -as if a @samp{%#x} conversion were used. Null pointers print as -@samp{(nil)}. (Pointers might print differently in other systems.) - -For example: - -@smallexample -printf ("%p", "testing"); -@end smallexample - -@noindent -prints @samp{0x} followed by a hexadecimal number---the address of the -string constant @code{"testing"}. It does not print the word -@samp{testing}. - -You can supply the @samp{-} flag with the @samp{%p} conversion to -specify left-justification, but no other flags, precision, or type -modifiers are defined. - -The @samp{%n} conversion is unlike any of the other output conversions. -It uses an argument which must be a pointer to an @code{int}, but -instead of printing anything it stores the number of characters printed -so far by this call at that location. The @samp{h} and @samp{l} type -modifiers are permitted to specify that the argument is of type -@code{short int *} or @code{long int *} instead of @code{int *}, but no -flags, field width, or precision are permitted. - -For example, - -@smallexample -int nchar; -printf ("%d %s%n\n", 3, "bears", &nchar); -@end smallexample - -@noindent -prints: - -@smallexample -3 bears -@end smallexample - -@noindent -and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven -characters. - - -The @samp{%%} conversion prints a literal @samp{%} character. This -conversion doesn't use an argument, and no flags, field width, -precision, or type modifiers are permitted. - - -@node Formatted Output Functions -@subsection Formatted Output Functions - -This section describes how to call @code{printf} and related functions. -Prototypes for these functions are in the header file @file{stdio.h}. -Because these functions take a variable number of arguments, you -@emph{must} declare prototypes for them before using them. Of course, -the easiest way to make sure you have all the right prototypes is to -just include @file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment ISO -@deftypefun int printf (const char *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -The @code{printf} function prints the optional arguments under the -control of the template string @var{template} to the stream -@code{stdout}. It returns the number of characters printed, or a -negative value if there was an output error. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun int wprintf (const wchar_t *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -The @code{wprintf} function prints the optional arguments under the -control of the wide template string @var{template} to the stream -@code{stdout}. It returns the number of wide characters printed, or a -negative value if there was an output error. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -This function is just like @code{printf}, except that the output is -written to the stream @var{stream} instead of @code{stdout}. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun int fwprintf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -This function is just like @code{wprintf}, except that the output is -written to the stream @var{stream} instead of @code{stdout}. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -This is like @code{printf}, except that the output is stored in the character -array @var{s} instead of written to a stream. A null character is written -to mark the end of the string. - -The @code{sprintf} function returns the number of characters stored in -the array @var{s}, not including the terminating null character. - -The behavior of this function is undefined if copying takes place -between objects that overlap---for example, if @var{s} is also given -as an argument to be printed under control of the @samp{%s} conversion. -@xref{Copying Strings and Arrays}. - -@strong{Warning:} The @code{sprintf} function can be @strong{dangerous} -because it can potentially output more characters than can fit in the -allocation size of the string @var{s}. Remember that the field width -given in a conversion specification is only a @emph{minimum} value. - -To avoid this problem, you can use @code{snprintf} or @code{asprintf}, -described below. -@end deftypefun - -@comment wchar.h -@comment GNU -@deftypefun int swprintf (wchar_t *@var{ws}, size_t @var{size}, const wchar_t *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -This is like @code{wprintf}, except that the output is stored in the -wide character array @var{ws} instead of written to a stream. A null -wide character is written to mark the end of the string. The @var{size} -argument specifies the maximum number of characters to produce. The -trailing null character is counted towards this limit, so you should -allocate at least @var{size} wide characters for the string @var{ws}. - -The return value is the number of characters generated for the given -input, excluding the trailing null. If not all output fits into the -provided buffer a negative value is returned. You should try again with -a bigger output string. @emph{Note:} this is different from how -@code{snprintf} handles this situation. - -Note that the corresponding narrow stream function takes fewer -parameters. @code{swprintf} in fact corresponds to the @code{snprintf} -function. Since the @code{sprintf} function can be dangerous and should -be avoided the @w{ISO C} committee refused to make the same mistake -again and decided to not define a function exactly corresponding to -@code{sprintf}. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -The @code{snprintf} function is similar to @code{sprintf}, except that -the @var{size} argument specifies the maximum number of characters to -produce. The trailing null character is counted towards this limit, so -you should allocate at least @var{size} characters for the string @var{s}. -If @var{size} is zero, nothing, not even the null byte, shall be written and -@var{s} may be a null pointer. - -The return value is the number of characters which would be generated -for the given input, excluding the trailing null. If this value is -greater than or equal to @var{size}, not all characters from the result have -been stored in @var{s}. You should try again with a bigger output -string. Here is an example of doing this: - -@smallexample -@group -/* @r{Construct a message describing the value of a variable} - @r{whose name is @var{name} and whose value is @var{value}.} */ -char * -make_message (char *name, char *value) -@{ - /* @r{Guess we need no more than 100 chars of space.} */ - int size = 100; - char *buffer = (char *) xmalloc (size); - int nchars; -@end group -@group - if (buffer == NULL) - return NULL; - - /* @r{Try to print in the allocated space.} */ - nchars = snprintf (buffer, size, "value of %s is %s", - name, value); -@end group -@group - if (nchars >= size) - @{ - /* @r{Reallocate buffer now that we know - how much space is needed.} */ - size = nchars + 1; - buffer = (char *) xrealloc (buffer, size); - - if (buffer != NULL) - /* @r{Try again.} */ - snprintf (buffer, size, "value of %s is %s", - name, value); - @} - /* @r{The last call worked, return the string.} */ - return buffer; -@} -@end group -@end smallexample - -In practice, it is often easier just to use @code{asprintf}, below. - -@strong{Attention:} In versions of @theglibc{} prior to 2.1 the -return value is the number of characters stored, not including the -terminating null; unless there was not enough space in @var{s} to -store the result in which case @code{-1} is returned. This was -changed in order to comply with the @w{ISO C99} standard. -@end deftypefun - -@node Dynamic Output -@subsection Dynamically Allocating Formatted Output - -The functions in this section do formatted output and place the results -in dynamically allocated memory. - -@comment stdio.h -@comment GNU -@deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -This function is similar to @code{sprintf}, except that it dynamically -allocates a string (as with @code{malloc}; @pxref{Unconstrained -Allocation}) to hold the output, instead of putting the output in a -buffer you allocate in advance. The @var{ptr} argument should be the -address of a @code{char *} object, and a successful call to -@code{asprintf} stores a pointer to the newly allocated string at that -location. - -The return value is the number of characters allocated for the buffer, or -less than zero if an error occurred. Usually this means that the buffer -could not be allocated. - -Here is how to use @code{asprintf} to get the same result as the -@code{snprintf} example, but more easily: - -@smallexample -/* @r{Construct a message describing the value of a variable} - @r{whose name is @var{name} and whose value is @var{value}.} */ -char * -make_message (char *name, char *value) -@{ - char *result; - if (asprintf (&result, "value of %s is %s", name, value) < 0) - return NULL; - return result; -@} -@end smallexample -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} -This function is similar to @code{asprintf}, except that it uses the -obstack @var{obstack} to allocate the space. @xref{Obstacks}. - -The characters are written onto the end of the current object. -To get at them, you must finish the object with @code{obstack_finish} -(@pxref{Growing Objects}).@refill -@end deftypefun - -@node Variable Arguments Output -@subsection Variable Arguments Output Functions - -The functions @code{vprintf} and friends are provided so that you can -define your own variadic @code{printf}-like functions that make use of -the same internals as the built-in formatted output functions. - -The most natural way to define such functions would be to use a language -construct to say, ``Call @code{printf} and pass this template plus all -of my arguments after the first five.'' But there is no way to do this -in C, and it would be hard to provide a way, since at the C language -level there is no way to tell how many arguments your function received. - -Since that method is impossible, we provide alternative functions, the -@code{vprintf} series, which lets you pass a @code{va_list} to describe -``all of my arguments after the first five.'' - -When it is sufficient to define a macro rather than a real function, -the GNU C compiler provides a way to do this much more easily with macros. -For example: - -@smallexample -#define myprintf(a, b, c, d, e, rest...) \ - printf (mytemplate , ## rest) -@end smallexample - -@noindent -@xref{Variadic Macros,,, cpp, The C preprocessor}, for details. -But this is limited to macros, and does not apply to real functions at all. - -Before calling @code{vprintf} or the other functions listed in this -section, you @emph{must} call @code{va_start} (@pxref{Variadic -Functions}) to initialize a pointer to the variable arguments. Then you -can call @code{va_arg} to fetch the arguments that you want to handle -yourself. This advances the pointer past those arguments. - -Once your @code{va_list} pointer is pointing at the argument of your -choice, you are ready to call @code{vprintf}. That argument and all -subsequent arguments that were passed to your function are used by -@code{vprintf} along with the template that you specified separately. - -@strong{Portability Note:} The value of the @code{va_list} pointer is -undetermined after the call to @code{vprintf}, so you must not use -@code{va_arg} after you call @code{vprintf}. Instead, you should call -@code{va_end} to retire the pointer from service. You can call -@code{va_start} again and begin fetching the arguments from the start of -the variable argument list. (Alternatively, you can use @code{va_copy} -to make a copy of the @code{va_list} pointer before calling -@code{vfprintf}.) Calling @code{vprintf} does not destroy the argument -list of your function, merely the particular pointer that you passed to -it. - -Prototypes for these functions are declared in @file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment ISO -@deftypefun int vprintf (const char *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -This function is similar to @code{printf} except that, instead of taking -a variable number of arguments directly, it takes an argument list -pointer @var{ap}. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun int vwprintf (const wchar_t *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -This function is similar to @code{wprintf} except that, instead of taking -a variable number of arguments directly, it takes an argument list -pointer @var{ap}. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -@c Although vfprintf sets up a cleanup region to release the lock on the -@c output stream, it doesn't use it to release args_value or string in -@c case of cancellation. This doesn't make it unsafe, but cancelling it -@c may leak memory. The unguarded use of __printf_function_table is -@c also of concern for all callers. -@c _itoa ok -@c _udiv_qrnnd_preinv ok -@c group_number ok -@c _i18n_number_rewrite -@c __wctrans ok -@c __towctrans @mtslocale -@c __wcrtomb ok? dup below -@c outdigit_value ok -@c outdigitwc_value ok -@c outchar ok -@c outstring ok -@c PAD ok -@c __printf_fp @mtslocale @ascuheap @acsmem -@c __printf_fphex @mtslocale -@c __readonly_area -@c [GNU/Linux] fopen, strtoul, free -@c __strerror_r ok if no translation, check otherwise -@c __btowc ? gconv-modules -@c __wcrtomb ok (not using internal state) gconv-modules -@c ARGCHECK -@c UNBUFFERED_P (tested before taking the stream lock) -@c buffered_vfprintf ok -@c __find_spec(wc|mb) -@c read_int -@c __libc_use_alloca -@c process_arg -@c process_string_arg -@c extend_alloca -@c __parse_one_spec(wc|mb) -@c *__printf_arginfo_table unguarded -@c __printf_va_arg_table-> unguarded -@c *__printf_function_table unguarded -@c done_add -@c printf_unknown -@c outchar -@c _itoa_word -This is the equivalent of @code{fprintf} with the variable argument list -specified directly as for @code{vprintf}. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun int vfwprintf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -This is the equivalent of @code{fwprintf} with the variable argument list -specified directly as for @code{vwprintf}. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -This is the equivalent of @code{sprintf} with the variable argument list -specified directly as for @code{vprintf}. -@end deftypefun - -@comment wchar.h -@comment GNU -@deftypefun int vswprintf (wchar_t *@var{ws}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -This is the equivalent of @code{swprintf} with the variable argument list -specified directly as for @code{vwprintf}. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -This is the equivalent of @code{snprintf} with the variable argument list -specified directly as for @code{vprintf}. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -The @code{vasprintf} function is the equivalent of @code{asprintf} with the -variable argument list specified directly as for @code{vprintf}. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} -@c The obstack is not guarded by mutexes, it might be at an inconsistent -@c state within a signal handler, and it could be left at an -@c inconsistent state in case of cancellation. -The @code{obstack_vprintf} function is the equivalent of -@code{obstack_printf} with the variable argument list specified directly -as for @code{vprintf}.@refill -@end deftypefun - -Here's an example showing how you might use @code{vfprintf}. This is a -function that prints error messages to the stream @code{stderr}, along -with a prefix indicating the name of the program -(@pxref{Error Messages}, for a description of -@code{program_invocation_short_name}). - -@smallexample -@group -#include <stdio.h> -#include <stdarg.h> - -void -eprintf (const char *template, ...) -@{ - va_list ap; - extern char *program_invocation_short_name; - - fprintf (stderr, "%s: ", program_invocation_short_name); - va_start (ap, template); - vfprintf (stderr, template, ap); - va_end (ap); -@} -@end group -@end smallexample - -@noindent -You could call @code{eprintf} like this: - -@smallexample -eprintf ("file `%s' does not exist\n", filename); -@end smallexample - -In GNU C, there is a special construct you can use to let the compiler -know that a function uses a @code{printf}-style format string. Then it -can check the number and types of arguments in each call to the -function, and warn you when they do not match the format string. -For example, take this declaration of @code{eprintf}: - -@smallexample -void eprintf (const char *template, ...) - __attribute__ ((format (printf, 1, 2))); -@end smallexample - -@noindent -This tells the compiler that @code{eprintf} uses a format string like -@code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input}); -the format string appears as the first argument; -and the arguments to satisfy the format begin with the second. -@xref{Function Attributes, , Declaring Attributes of Functions, -gcc.info, Using GNU CC}, for more information. - -@node Parsing a Template String -@subsection Parsing a Template String -@cindex parsing a template string - -You can use the function @code{parse_printf_format} to obtain -information about the number and types of arguments that are expected by -a given template string. This function permits interpreters that -provide interfaces to @code{printf} to avoid passing along invalid -arguments from the user's program, which could cause a crash. - -All the symbols described in this section are declared in the header -file @file{printf.h}. - -@comment printf.h -@comment GNU -@deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} -This function returns information about the number and types of -arguments expected by the @code{printf} template string @var{template}. -The information is stored in the array @var{argtypes}; each element of -this array describes one argument. This information is encoded using -the various @samp{PA_} macros, listed below. - -The argument @var{n} specifies the number of elements in the array -@var{argtypes}. This is the maximum number of elements that -@code{parse_printf_format} will try to write. - -@code{parse_printf_format} returns the total number of arguments required -by @var{template}. If this number is greater than @var{n}, then the -information returned describes only the first @var{n} arguments. If you -want information about additional arguments, allocate a bigger -array and call @code{parse_printf_format} again. -@end deftypefun - -The argument types are encoded as a combination of a basic type and -modifier flag bits. - -@comment printf.h -@comment GNU -@deftypevr Macro int PA_FLAG_MASK -This macro is a bitmask for the type modifier flag bits. You can write -the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the -flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to -extract just the basic type code. -@end deftypevr - -Here are symbolic constants that represent the basic types; they stand -for integer values. - -@vtable @code -@comment printf.h -@comment GNU -@item PA_INT -This specifies that the base type is @code{int}. - -@comment printf.h -@comment GNU -@item PA_CHAR -This specifies that the base type is @code{int}, cast to @code{char}. - -@comment printf.h -@comment GNU -@item PA_STRING -This specifies that the base type is @code{char *}, a null-terminated string. - -@comment printf.h -@comment GNU -@item PA_POINTER -This specifies that the base type is @code{void *}, an arbitrary pointer. - -@comment printf.h -@comment GNU -@item PA_FLOAT -This specifies that the base type is @code{float}. - -@comment printf.h -@comment GNU -@item PA_DOUBLE -This specifies that the base type is @code{double}. - -@comment printf.h -@comment GNU -@item PA_LAST -You can define additional base types for your own programs as offsets -from @code{PA_LAST}. For example, if you have data types @samp{foo} -and @samp{bar} with their own specialized @code{printf} conversions, -you could define encodings for these types as: - -@smallexample -#define PA_FOO PA_LAST -#define PA_BAR (PA_LAST + 1) -@end smallexample -@end vtable - -Here are the flag bits that modify a basic type. They are combined with -the code for the basic type using inclusive-or. - -@vtable @code -@comment printf.h -@comment GNU -@item PA_FLAG_PTR -If this bit is set, it indicates that the encoded type is a pointer to -the base type, rather than an immediate value. -For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}. - -@comment printf.h -@comment GNU -@item PA_FLAG_SHORT -If this bit is set, it indicates that the base type is modified with -@code{short}. (This corresponds to the @samp{h} type modifier.) - -@comment printf.h -@comment GNU -@item PA_FLAG_LONG -If this bit is set, it indicates that the base type is modified with -@code{long}. (This corresponds to the @samp{l} type modifier.) - -@comment printf.h -@comment GNU -@item PA_FLAG_LONG_LONG -If this bit is set, it indicates that the base type is modified with -@code{long long}. (This corresponds to the @samp{L} type modifier.) - -@comment printf.h -@comment GNU -@item PA_FLAG_LONG_DOUBLE -This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with -a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}. -@end vtable - -@ifinfo -For an example of using these facilities, see @ref{Example of Parsing}. -@end ifinfo - -@node Example of Parsing -@subsection Example of Parsing a Template String - -Here is an example of decoding argument types for a format string. We -assume this is part of an interpreter which contains arguments of type -@code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and -perhaps others which are not valid here). - -@smallexample -/* @r{Test whether the @var{nargs} specified objects} - @r{in the vector @var{args} are valid} - @r{for the format string @var{format}:} - @r{if so, return 1.} - @r{If not, return 0 after printing an error message.} */ - -int -validate_args (char *format, int nargs, OBJECT *args) -@{ - int *argtypes; - int nwanted; - - /* @r{Get the information about the arguments.} - @r{Each conversion specification must be at least two characters} - @r{long, so there cannot be more specifications than half the} - @r{length of the string.} */ - - argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int)); - nwanted = parse_printf_format (string, nelts, argtypes); - - /* @r{Check the number of arguments.} */ - if (nwanted > nargs) - @{ - error ("too few arguments (at least %d required)", nwanted); - return 0; - @} - - /* @r{Check the C type wanted for each argument} - @r{and see if the object given is suitable.} */ - for (i = 0; i < nwanted; i++) - @{ - int wanted; - - if (argtypes[i] & PA_FLAG_PTR) - wanted = STRUCTURE; - else - switch (argtypes[i] & ~PA_FLAG_MASK) - @{ - case PA_INT: - case PA_FLOAT: - case PA_DOUBLE: - wanted = NUMBER; - break; - case PA_CHAR: - wanted = CHAR; - break; - case PA_STRING: - wanted = STRING; - break; - case PA_POINTER: - wanted = STRUCTURE; - break; - @} - if (TYPE (args[i]) != wanted) - @{ - error ("type mismatch for arg number %d", i); - return 0; - @} - @} - return 1; -@} -@end smallexample - -@node Customizing Printf -@section Customizing @code{printf} -@cindex customizing @code{printf} -@cindex defining new @code{printf} conversions -@cindex extending @code{printf} - -@Theglibc{} lets you define your own custom conversion specifiers -for @code{printf} template strings, to teach @code{printf} clever ways -to print the important data structures of your program. - -The way you do this is by registering the conversion with the function -@code{register_printf_function}; see @ref{Registering New Conversions}. -One of the arguments you pass to this function is a pointer to a handler -function that produces the actual output; see @ref{Defining the Output -Handler}, for information on how to write this function. - -You can also install a function that just returns information about the -number and type of arguments expected by the conversion specifier. -@xref{Parsing a Template String}, for information about this. - -The facilities of this section are declared in the header file -@file{printf.h}. - -@menu -* Registering New Conversions:: Using @code{register_printf_function} - to register a new output conversion. -* Conversion Specifier Options:: The handler must be able to get - the options specified in the - template when it is called. -* Defining the Output Handler:: Defining the handler and arginfo - functions that are passed as arguments - to @code{register_printf_function}. -* Printf Extension Example:: How to define a @code{printf} - handler function. -* Predefined Printf Handlers:: Predefined @code{printf} handlers. -@end menu - -@strong{Portability Note:} The ability to extend the syntax of -@code{printf} template strings is a GNU extension. ISO standard C has -nothing similar. - -@node Registering New Conversions -@subsection Registering New Conversions - -The function to register a new output conversion is -@code{register_printf_function}, declared in @file{printf.h}. -@pindex printf.h - -@comment printf.h -@comment GNU -@deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function}) -@safety{@prelim{}@mtunsafe{@mtasuconst{:printfext}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}} -@c This function is guarded by the global non-recursive libc lock, but -@c users of the variables it sets aren't, and those should be MT-Safe, -@c so we're ruling out the use of this extension with threads. Calling -@c it from a signal handler may self-deadlock, and cancellation may -@c leave the lock held, besides leaking allocated memory. -This function defines the conversion specifier character @var{spec}. -Thus, if @var{spec} is @code{'Y'}, it defines the conversion @samp{%Y}. -You can redefine the built-in conversions like @samp{%s}, but flag -characters like @samp{#} and type modifiers like @samp{l} can never be -used as conversions; calling @code{register_printf_function} for those -characters has no effect. It is advisable not to use lowercase letters, -since the ISO C standard warns that additional lowercase letters may be -standardized in future editions of the standard. - -The @var{handler-function} is the function called by @code{printf} and -friends when this conversion appears in a template string. -@xref{Defining the Output Handler}, for information about how to define -a function to pass as this argument. If you specify a null pointer, any -existing handler function for @var{spec} is removed. - -The @var{arginfo-function} is the function called by -@code{parse_printf_format} when this conversion appears in a -template string. @xref{Parsing a Template String}, for information -about this. - -@c The following is not true anymore. The `parse_printf_format' function -@c is now also called from `vfprintf' via `parse_one_spec'. -@c --drepper@gnu, 1996/11/14 -@c -@c Normally, you install both functions for a conversion at the same time, -@c but if you are never going to call @code{parse_printf_format}, you do -@c not need to define an arginfo function. - -@strong{Attention:} In @theglibc{} versions before 2.0 the -@var{arginfo-function} function did not need to be installed unless -the user used the @code{parse_printf_format} function. This has changed. -Now a call to any of the @code{printf} functions will call this -function when this format specifier appears in the format string. - -The return value is @code{0} on success, and @code{-1} on failure -(which occurs if @var{spec} is out of range). - -You can redefine the standard output conversions, but this is probably -not a good idea because of the potential for confusion. Library routines -written by other people could break if you do this. -@end deftypefun - -@node Conversion Specifier Options -@subsection Conversion Specifier Options - -If you define a meaning for @samp{%A}, what if the template contains -@samp{%+23A} or @samp{%-#A}? To implement a sensible meaning for these, -the handler when called needs to be able to get the options specified in -the template. - -Both the @var{handler-function} and @var{arginfo-function} accept an -argument that points to a @code{struct printf_info}, which contains -information about the options appearing in an instance of the conversion -specifier. This data type is declared in the header file -@file{printf.h}. -@pindex printf.h - -@comment printf.h -@comment GNU -@deftp {Type} {struct printf_info} -This structure is used to pass information about the options appearing -in an instance of a conversion specifier in a @code{printf} template -string to the handler and arginfo functions for that specifier. It -contains the following members: - -@table @code -@item int prec -This is the precision specified. The value is @code{-1} if no precision -was specified. If the precision was given as @samp{*}, the -@code{printf_info} structure passed to the handler function contains the -actual value retrieved from the argument list. But the structure passed -to the arginfo function contains a value of @code{INT_MIN}, since the -actual value is not known. - -@item int width -This is the minimum field width specified. The value is @code{0} if no -width was specified. If the field width was given as @samp{*}, the -@code{printf_info} structure passed to the handler function contains the -actual value retrieved from the argument list. But the structure passed -to the arginfo function contains a value of @code{INT_MIN}, since the -actual value is not known. - -@item wchar_t spec -This is the conversion specifier character specified. It's stored in -the structure so that you can register the same handler function for -multiple characters, but still have a way to tell them apart when the -handler function is called. - -@item unsigned int is_long_double -This is a boolean that is true if the @samp{L}, @samp{ll}, or @samp{q} -type modifier was specified. For integer conversions, this indicates -@code{long long int}, as opposed to @code{long double} for floating -point conversions. - -@item unsigned int is_char -This is a boolean that is true if the @samp{hh} type modifier was specified. - -@item unsigned int is_short -This is a boolean that is true if the @samp{h} type modifier was specified. - -@item unsigned int is_long -This is a boolean that is true if the @samp{l} type modifier was specified. - -@item unsigned int alt -This is a boolean that is true if the @samp{#} flag was specified. - -@item unsigned int space -This is a boolean that is true if the @samp{ } flag was specified. - -@item unsigned int left -This is a boolean that is true if the @samp{-} flag was specified. - -@item unsigned int showsign -This is a boolean that is true if the @samp{+} flag was specified. - -@item unsigned int group -This is a boolean that is true if the @samp{'} flag was specified. - -@item unsigned int extra -This flag has a special meaning depending on the context. It could -be used freely by the user-defined handlers but when called from -the @code{printf} function this variable always contains the value -@code{0}. - -@item unsigned int wide -This flag is set if the stream is wide oriented. - -@item wchar_t pad -This is the character to use for padding the output to the minimum field -width. The value is @code{'0'} if the @samp{0} flag was specified, and -@code{' '} otherwise. -@end table -@end deftp - - -@node Defining the Output Handler -@subsection Defining the Output Handler - -Now let's look at how to define the handler and arginfo functions -which are passed as arguments to @code{register_printf_function}. - -@strong{Compatibility Note:} The interface changed in @theglibc{} -version 2.0. Previously the third argument was of type -@code{va_list *}. - -You should define your handler functions with a prototype like: - -@smallexample -int @var{function} (FILE *stream, const struct printf_info *info, - const void *const *args) -@end smallexample - -The @var{stream} argument passed to the handler function is the stream to -which it should write output. - -The @var{info} argument is a pointer to a structure that contains -information about the various options that were included with the -conversion in the template string. You should not modify this structure -inside your handler function. @xref{Conversion Specifier Options}, for -a description of this data structure. - -@c The following changes some time back. --drepper@gnu, 1996/11/14 -@c -@c The @code{ap_pointer} argument is used to pass the tail of the variable -@c argument list containing the values to be printed to your handler. -@c Unlike most other functions that can be passed an explicit variable -@c argument list, this is a @emph{pointer} to a @code{va_list}, rather than -@c the @code{va_list} itself. Thus, you should fetch arguments by -@c means of @code{va_arg (*ap_pointer, @var{type})}. -@c -@c (Passing a pointer here allows the function that calls your handler -@c function to update its own @code{va_list} variable to account for the -@c arguments that your handler processes. @xref{Variadic Functions}.) - -The @var{args} is a vector of pointers to the arguments data. -The number of arguments was determined by calling the argument -information function provided by the user. - -Your handler function should return a value just like @code{printf} -does: it should return the number of characters it has written, or a -negative value to indicate an error. - -@comment printf.h -@comment GNU -@deftp {Data Type} printf_function -This is the data type that a handler function should have. -@end deftp - -If you are going to use @w{@code{parse_printf_format}} in your -application, you must also define a function to pass as the -@var{arginfo-function} argument for each new conversion you install with -@code{register_printf_function}. - -You have to define these functions with a prototype like: - -@smallexample -int @var{function} (const struct printf_info *info, - size_t n, int *argtypes) -@end smallexample - -The return value from the function should be the number of arguments the -conversion expects. The function should also fill in no more than -@var{n} elements of the @var{argtypes} array with information about the -types of each of these arguments. This information is encoded using the -various @samp{PA_} macros. (You will notice that this is the same -calling convention @code{parse_printf_format} itself uses.) - -@comment printf.h -@comment GNU -@deftp {Data Type} printf_arginfo_function -This type is used to describe functions that return information about -the number and type of arguments used by a conversion specifier. -@end deftp - -@node Printf Extension Example -@subsection @code{printf} Extension Example - -Here is an example showing how to define a @code{printf} handler function. -This program defines a data structure called a @code{Widget} and -defines the @samp{%W} conversion to print information about @w{@code{Widget *}} -arguments, including the pointer value and the name stored in the data -structure. The @samp{%W} conversion supports the minimum field width and -left-justification options, but ignores everything else. - -@smallexample -@include rprintf.c.texi -@end smallexample - -The output produced by this program looks like: - -@smallexample -|<Widget 0xffeffb7c: mywidget>| -| <Widget 0xffeffb7c: mywidget>| -|<Widget 0xffeffb7c: mywidget> | -@end smallexample - -@node Predefined Printf Handlers -@subsection Predefined @code{printf} Handlers - -@Theglibc{} also contains a concrete and useful application of the -@code{printf} handler extension. There are two functions available -which implement a special way to print floating-point numbers. - -@comment printf.h -@comment GNU -@deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args}) -@safety{@prelim{}@mtsafe{@mtsrace{:fp} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @acucorrupt{}}} -@c This is meant to be called by vfprintf, that should hold the lock on -@c the stream, but if this function is called directly, output will be -@c racy, besides the uses of the global locale object while other -@c threads may be changing it and the possbility of leaving the stream -@c object in an inconsistent state in case of cancellation. -Print a given floating point number as for the format @code{%f} except -that there is a postfix character indicating the divisor for the -number to make this less than 1000. There are two possible divisors: -powers of 1024 or powers of 1000. Which one is used depends on the -format character specified while registered this handler. If the -character is of lower case, 1024 is used. For upper case characters, -1000 is used. - -The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes, -etc. The full table is: - -@ifinfo -@multitable {' '} {2^10 (1024)} {zetta} {Upper} {10^24 (1000)} -@item low @tab Multiplier @tab From @tab Upper @tab Multiplier -@item ' ' @tab 1 @tab @tab ' ' @tab 1 -@item k @tab 2^10 (1024) @tab kilo @tab K @tab 10^3 (1000) -@item m @tab 2^20 @tab mega @tab M @tab 10^6 -@item g @tab 2^30 @tab giga @tab G @tab 10^9 -@item t @tab 2^40 @tab tera @tab T @tab 10^12 -@item p @tab 2^50 @tab peta @tab P @tab 10^15 -@item e @tab 2^60 @tab exa @tab E @tab 10^18 -@item z @tab 2^70 @tab zetta @tab Z @tab 10^21 -@item y @tab 2^80 @tab yotta @tab Y @tab 10^24 -@end multitable -@end ifinfo -@iftex -@tex -\hbox to\hsize{\hfil\vbox{\offinterlineskip -\hrule -\halign{\strut#& \vrule#\tabskip=1em plus2em& {\tt#}\hfil& \vrule#& #\hfil& \vrule#& #\hfil& \vrule#& {\tt#}\hfil& \vrule#& #\hfil& \vrule#\tabskip=0pt\cr -\noalign{\hrule} -\omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr -&& \omit low && Multiplier && From && \omit Upper && Multiplier &\cr -\omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr -\noalign{\hrule} -&& {\tt\char32} && 1 && && {\tt\char32} && 1 &\cr -&& k && $2^{10} = 1024$ && kilo && K && $10^3 = 1000$ &\cr -&& m && $2^{20}$ && mega && M && $10^6$ &\cr -&& g && $2^{30}$ && giga && G && $10^9$ &\cr -&& t && $2^{40}$ && tera && T && $10^{12}$ &\cr -&& p && $2^{50}$ && peta && P && $10^{15}$ &\cr -&& e && $2^{60}$ && exa && E && $10^{18}$ &\cr -&& z && $2^{70}$ && zetta && Z && $10^{21}$ &\cr -&& y && $2^{80}$ && yotta && Y && $10^{24}$ &\cr -\noalign{\hrule}}}\hfil} -@end tex -@end iftex - -The default precision is 3, i.e., 1024 is printed with a lower-case -format character as if it were @code{%.3fk} and will yield @code{1.000k}. -@end deftypefun - -Due to the requirements of @code{register_printf_function} we must also -provide the function which returns information about the arguments. - -@comment printf.h -@comment GNU -@deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function will return in @var{argtypes} the information about the -used parameters in the way the @code{vfprintf} implementation expects -it. The format always takes one argument. -@end deftypefun - -To use these functions both functions must be registered with a call like - -@smallexample -register_printf_function ('B', printf_size, printf_size_info); -@end smallexample - -Here we register the functions to print numbers as powers of 1000 since -the format character @code{'B'} is an upper-case character. If we -would additionally use @code{'b'} in a line like - -@smallexample -register_printf_function ('b', printf_size, printf_size_info); -@end smallexample - -@noindent -we could also print using a power of 1024. Please note that all that is -different in these two lines is the format specifier. The -@code{printf_size} function knows about the difference between lower and upper -case format specifiers. - -The use of @code{'B'} and @code{'b'} is no coincidence. Rather it is -the preferred way to use this functionality since it is available on -some other systems which also use format specifiers. - -@node Formatted Input -@section Formatted Input - -@cindex formatted input from a stream -@cindex reading from a stream, formatted -@cindex format string, for @code{scanf} -@cindex template, for @code{scanf} -The functions described in this section (@code{scanf} and related -functions) provide facilities for formatted input analogous to the -formatted output facilities. These functions provide a mechanism for -reading arbitrary values under the control of a @dfn{format string} or -@dfn{template string}. - -@menu -* Formatted Input Basics:: Some basics to get you started. -* Input Conversion Syntax:: Syntax of conversion specifications. -* Table of Input Conversions:: Summary of input conversions and what they do. -* Numeric Input Conversions:: Details of conversions for reading numbers. -* String Input Conversions:: Details of conversions for reading strings. -* Dynamic String Input:: String conversions that @code{malloc} the buffer. -* Other Input Conversions:: Details of miscellaneous other conversions. -* Formatted Input Functions:: Descriptions of the actual functions. -* Variable Arguments Input:: @code{vscanf} and friends. -@end menu - -@node Formatted Input Basics -@subsection Formatted Input Basics - -Calls to @code{scanf} are superficially similar to calls to -@code{printf} in that arbitrary arguments are read under the control of -a template string. While the syntax of the conversion specifications in -the template is very similar to that for @code{printf}, the -interpretation of the template is oriented more towards free-format -input and simple pattern matching, rather than fixed-field formatting. -For example, most @code{scanf} conversions skip over any amount of -``white space'' (including spaces, tabs, and newlines) in the input -file, and there is no concept of precision for the numeric input -conversions as there is for the corresponding output conversions. -Ordinarily, non-whitespace characters in the template are expected to -match characters in the input stream exactly, but a matching failure is -distinct from an input error on the stream. -@cindex conversion specifications (@code{scanf}) - -Another area of difference between @code{scanf} and @code{printf} is -that you must remember to supply pointers rather than immediate values -as the optional arguments to @code{scanf}; the values that are read are -stored in the objects that the pointers point to. Even experienced -programmers tend to forget this occasionally, so if your program is -getting strange errors that seem to be related to @code{scanf}, you -might want to double-check this. - -When a @dfn{matching failure} occurs, @code{scanf} returns immediately, -leaving the first non-matching character as the next character to be -read from the stream. The normal return value from @code{scanf} is the -number of values that were assigned, so you can use this to determine if -a matching error happened before all the expected values were read. -@cindex matching failure, in @code{scanf} - -The @code{scanf} function is typically used for things like reading in -the contents of tables. For example, here is a function that uses -@code{scanf} to initialize an array of @code{double}: - -@smallexample -void -readarray (double *array, int n) -@{ - int i; - for (i=0; i<n; i++) - if (scanf (" %lf", &(array[i])) != 1) - invalid_input_error (); -@} -@end smallexample - -The formatted input functions are not used as frequently as the -formatted output functions. Partly, this is because it takes some care -to use them properly. Another reason is that it is difficult to recover -from a matching error. - -If you are trying to read input that doesn't match a single, fixed -pattern, you may be better off using a tool such as Flex to generate a -lexical scanner, or Bison to generate a parser, rather than using -@code{scanf}. For more information about these tools, see @ref{Top, , , -flex.info, Flex: The Lexical Scanner Generator}, and @ref{Top, , , -bison.info, The Bison Reference Manual}. - -@node Input Conversion Syntax -@subsection Input Conversion Syntax - -A @code{scanf} template string is a string that contains ordinary -multibyte characters interspersed with conversion specifications that -start with @samp{%}. - -Any whitespace character (as defined by the @code{isspace} function; -@pxref{Classification of Characters}) in the template causes any number -of whitespace characters in the input stream to be read and discarded. -The whitespace characters that are matched need not be exactly the same -whitespace characters that appear in the template string. For example, -write @samp{ , } in the template to recognize a comma with optional -whitespace before and after. - -Other characters in the template string that are not part of conversion -specifications must match characters in the input stream exactly; if -this is not the case, a matching failure occurs. - -The conversion specifications in a @code{scanf} template string -have the general form: - -@smallexample -% @var{flags} @var{width} @var{type} @var{conversion} -@end smallexample - -In more detail, an input conversion specification consists of an initial -@samp{%} character followed in sequence by: - -@itemize @bullet -@item -An optional @dfn{flag character} @samp{*}, which says to ignore the text -read for this specification. When @code{scanf} finds a conversion -specification that uses this flag, it reads input as directed by the -rest of the conversion specification, but it discards this input, does -not use a pointer argument, and does not increment the count of -successful assignments. -@cindex flag character (@code{scanf}) - -@item -An optional flag character @samp{a} (valid with string conversions only) -which requests allocation of a buffer long enough to store the string in. -(This is a GNU extension.) -@xref{Dynamic String Input}. - -@item -An optional decimal integer that specifies the @dfn{maximum field -width}. Reading of characters from the input stream stops either when -this maximum is reached or when a non-matching character is found, -whichever happens first. Most conversions discard initial whitespace -characters (those that don't are explicitly documented), and these -discarded characters don't count towards the maximum field width. -String input conversions store a null character to mark the end of the -input; the maximum field width does not include this terminator. -@cindex maximum field width (@code{scanf}) - -@item -An optional @dfn{type modifier character}. For example, you can -specify a type modifier of @samp{l} with integer conversions such as -@samp{%d} to specify that the argument is a pointer to a @code{long int} -rather than a pointer to an @code{int}. -@cindex type modifier character (@code{scanf}) - -@item -A character that specifies the conversion to be applied. -@end itemize - -The exact options that are permitted and how they are interpreted vary -between the different conversion specifiers. See the descriptions of the -individual conversions for information about the particular options that -they allow. - -With the @samp{-Wformat} option, the GNU C compiler checks calls to -@code{scanf} and related functions. It examines the format string and -verifies that the correct number and types of arguments are supplied. -There is also a GNU C syntax to tell the compiler that a function you -write uses a @code{scanf}-style format string. -@xref{Function Attributes, , Declaring Attributes of Functions, -gcc.info, Using GNU CC}, for more information. - -@node Table of Input Conversions -@subsection Table of Input Conversions -@cindex input conversions, for @code{scanf} - -Here is a table that summarizes the various conversion specifications: - -@table @asis -@item @samp{%d} -Matches an optionally signed integer written in decimal. @xref{Numeric -Input Conversions}. - -@item @samp{%i} -Matches an optionally signed integer in any of the formats that the C -language defines for specifying an integer constant. @xref{Numeric -Input Conversions}. - -@item @samp{%o} -Matches an unsigned integer written in octal radix. -@xref{Numeric Input Conversions}. - -@item @samp{%u} -Matches an unsigned integer written in decimal radix. -@xref{Numeric Input Conversions}. - -@item @samp{%x}, @samp{%X} -Matches an unsigned integer written in hexadecimal radix. -@xref{Numeric Input Conversions}. - -@item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G} -Matches an optionally signed floating-point number. @xref{Numeric Input -Conversions}. - -@item @samp{%s} - -Matches a string containing only non-whitespace characters. -@xref{String Input Conversions}. The presence of the @samp{l} modifier -determines whether the output is stored as a wide character string or a -multibyte string. If @samp{%s} is used in a wide character function the -string is converted as with multiple calls to @code{wcrtomb} into a -multibyte string. This means that the buffer must provide room for -@code{MB_CUR_MAX} bytes for each wide character read. In case -@samp{%ls} is used in a multibyte function the result is converted into -wide characters as with multiple calls of @code{mbrtowc} before being -stored in the user provided buffer. - -@item @samp{%S} -This is an alias for @samp{%ls} which is supported for compatibility -with the Unix standard. - -@item @samp{%[} -Matches a string of characters that belong to a specified set. -@xref{String Input Conversions}. The presence of the @samp{l} modifier -determines whether the output is stored as a wide character string or a -multibyte string. If @samp{%[} is used in a wide character function the -string is converted as with multiple calls to @code{wcrtomb} into a -multibyte string. This means that the buffer must provide room for -@code{MB_CUR_MAX} bytes for each wide character read. In case -@samp{%l[} is used in a multibyte function the result is converted into -wide characters as with multiple calls of @code{mbrtowc} before being -stored in the user provided buffer. - -@item @samp{%c} -Matches a string of one or more characters; the number of characters -read is controlled by the maximum field width given for the conversion. -@xref{String Input Conversions}. - -If @samp{%c} is used in a wide stream function the read value is -converted from a wide character to the corresponding multibyte character -before storing it. Note that this conversion can produce more than one -byte of output and therefore the provided buffer must be large enough for up -to @code{MB_CUR_MAX} bytes for each character. If @samp{%lc} is used in -a multibyte function the input is treated as a multibyte sequence (and -not bytes) and the result is converted as with calls to @code{mbrtowc}. - -@item @samp{%C} -This is an alias for @samp{%lc} which is supported for compatibility -with the Unix standard. - -@item @samp{%p} -Matches a pointer value in the same implementation-defined format used -by the @samp{%p} output conversion for @code{printf}. @xref{Other Input -Conversions}. - -@item @samp{%n} -This conversion doesn't read any characters; it records the number of -characters read so far by this call. @xref{Other Input Conversions}. - -@item @samp{%%} -This matches a literal @samp{%} character in the input stream. No -corresponding argument is used. @xref{Other Input Conversions}. -@end table - -If the syntax of a conversion specification is invalid, the behavior is -undefined. If there aren't enough function arguments provided to supply -addresses for all the conversion specifications in the template strings -that perform assignments, or if the arguments are not of the correct -types, the behavior is also undefined. On the other hand, extra -arguments are simply ignored. - -@node Numeric Input Conversions -@subsection Numeric Input Conversions - -This section describes the @code{scanf} conversions for reading numeric -values. - -The @samp{%d} conversion matches an optionally signed integer in decimal -radix. The syntax that is recognized is the same as that for the -@code{strtol} function (@pxref{Parsing of Integers}) with the value -@code{10} for the @var{base} argument. - -The @samp{%i} conversion matches an optionally signed integer in any of -the formats that the C language defines for specifying an integer -constant. The syntax that is recognized is the same as that for the -@code{strtol} function (@pxref{Parsing of Integers}) with the value -@code{0} for the @var{base} argument. (You can print integers in this -syntax with @code{printf} by using the @samp{#} flag character with the -@samp{%x}, @samp{%o}, or @samp{%d} conversion. @xref{Integer Conversions}.) - -For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012} -could be read in as integers under the @samp{%i} conversion. Each of -these specifies a number with decimal value @code{10}. - -The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned -integers in octal, decimal, and hexadecimal radices, respectively. The -syntax that is recognized is the same as that for the @code{strtoul} -function (@pxref{Parsing of Integers}) with the appropriate value -(@code{8}, @code{10}, or @code{16}) for the @var{base} argument. - -The @samp{%X} conversion is identical to the @samp{%x} conversion. They -both permit either uppercase or lowercase letters to be used as digits. - -The default type of the corresponding argument for the @code{%d} and -@code{%i} conversions is @code{int *}, and @code{unsigned int *} for the -other integer conversions. You can use the following type modifiers to -specify other sizes of integer: - -@table @samp -@item hh -Specifies that the argument is a @code{signed char *} or @code{unsigned -char *}. - -This modifier was introduced in @w{ISO C99}. - -@item h -Specifies that the argument is a @code{short int *} or @code{unsigned -short int *}. - -@item j -Specifies that the argument is a @code{intmax_t *} or @code{uintmax_t *}. - -This modifier was introduced in @w{ISO C99}. - -@item l -Specifies that the argument is a @code{long int *} or @code{unsigned -long int *}. Two @samp{l} characters is like the @samp{L} modifier, below. - -If used with @samp{%c} or @samp{%s} the corresponding parameter is -considered as a pointer to a wide character or wide character string -respectively. This use of @samp{l} was introduced in @w{Amendment 1} to -@w{ISO C90}. - -@need 100 -@item ll -@itemx L -@itemx q -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 -GNU C compiler. For systems that don't provide extra-long integers, this -is the same as @code{long int}.) - -The @samp{q} modifier is another name for the same thing, which comes -from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad'' -@code{int}. - -@item t -Specifies that the argument is a @code{ptrdiff_t *}. - -This modifier was introduced in @w{ISO C99}. - -@item z -Specifies that the argument is a @code{size_t *}. - -This modifier was introduced in @w{ISO C99}. -@end table - -All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G} -input conversions are interchangeable. They all match an optionally -signed floating point number, in the same syntax as for the -@code{strtod} function (@pxref{Parsing of Floats}). - -For the floating-point input conversions, the default argument type is -@code{float *}. (This is different from the corresponding output -conversions, where the default type is @code{double}; remember that -@code{float} arguments to @code{printf} are converted to @code{double} -by the default argument promotions, but @code{float *} arguments are -not promoted to @code{double *}.) You can specify other sizes of float -using these type modifiers: - -@table @samp -@item l -Specifies that the argument is of type @code{double *}. - -@item L -Specifies that the argument is of type @code{long double *}. -@end table - -For all the above number parsing formats there is an additional optional -flag @samp{'}. When this flag is given the @code{scanf} function -expects the number represented in the input string to be formatted -according to the grouping rules of the currently selected locale -(@pxref{General Numeric}). - -If the @code{"C"} or @code{"POSIX"} locale is selected there is no -difference. But for a locale which specifies values for the appropriate -fields in the locale the input must have the correct form in the input. -Otherwise the longest prefix with a correct form is processed. - -@node String Input Conversions -@subsection String Input Conversions - -This section describes the @code{scanf} input conversions for reading -string and character values: @samp{%s}, @samp{%S}, @samp{%[}, @samp{%c}, -and @samp{%C}. - -You have two options for how to receive the input from these -conversions: - -@itemize @bullet -@item -Provide a buffer to store it in. This is the default. You should -provide an argument of type @code{char *} or @code{wchar_t *} (the -latter if the @samp{l} modifier is present). - -@strong{Warning:} To make a robust program, you must make sure that the -input (plus its terminating null) cannot possibly exceed the size of the -buffer you provide. In general, the only way to do this is to specify a -maximum field width one less than the buffer size. @strong{If you -provide the buffer, always specify a maximum field width to prevent -overflow.} - -@item -Ask @code{scanf} to allocate a big enough buffer, by specifying the -@samp{a} flag character. This is a GNU extension. You should provide -an argument of type @code{char **} for the buffer address to be stored -in. @xref{Dynamic String Input}. -@end itemize - -The @samp{%c} conversion is the simplest: it matches a fixed number of -characters, always. The maximum field width says how many characters to -read; if you don't specify the maximum, the default is 1. This -conversion doesn't append a null character to the end of the text it -reads. It also does not skip over initial whitespace characters. It -reads precisely the next @var{n} characters, and fails if it cannot get -that many. Since there is always a maximum field width with @samp{%c} -(whether specified, or 1 by default), you can always prevent overflow by -making the buffer long enough. -@comment Is character == byte here??? --drepper - -If the format is @samp{%lc} or @samp{%C} the function stores wide -characters which are converted using the conversion determined at the -time the stream was opened from the external byte stream. The number of -bytes read from the medium is limited by @code{MB_CUR_LEN * @var{n}} but -at most @var{n} wide characters get stored in the output string. - -The @samp{%s} conversion matches a string of non-whitespace characters. -It skips and discards initial whitespace, but stops when it encounters -more whitespace after having read something. It stores a null character -at the end of the text that it reads. - -For example, reading the input: - -@smallexample - hello, world -@end smallexample - -@noindent -with the conversion @samp{%10c} produces @code{" hello, wo"}, but -reading the same input with the conversion @samp{%10s} produces -@code{"hello,"}. - -@strong{Warning:} If you do not specify a field width for @samp{%s}, -then the number of characters read is limited only by where the next -whitespace character appears. This almost certainly means that invalid -input can make your program crash---which is a bug. - -The @samp{%ls} and @samp{%S} format are handled just like @samp{%s} -except that the external byte sequence is converted using the conversion -associated with the stream to wide characters with their own encoding. -A width or precision specified with the format do not directly determine -how many bytes are read from the stream since they measure wide -characters. But an upper limit can be computed by multiplying the value -of the width or precision by @code{MB_CUR_MAX}. - -To read in characters that belong to an arbitrary set of your choice, -use the @samp{%[} conversion. You specify the set between the @samp{[} -character and a following @samp{]} character, using the same syntax used -in regular expressions for explicit sets of characters. As special cases: - -@itemize @bullet -@item -A literal @samp{]} character can be specified as the first character -of the set. - -@item -An embedded @samp{-} character (that is, one that is not the first or -last character of the set) is used to specify a range of characters. - -@item -If a caret character @samp{^} immediately follows the initial @samp{[}, -then the set of allowed input characters is everything @emph{except} -the characters listed. -@end itemize - -The @samp{%[} conversion does not skip over initial whitespace -characters. - -Note that the @dfn{character class} syntax available in character sets -that appear inside regular expressions (such as @samp{[:alpha:]}) is -@emph{not} available in the @samp{%[} conversion. - -Here are some examples of @samp{%[} conversions and what they mean: - -@table @samp -@item %25[1234567890] -Matches a string of up to 25 digits. - -@item %25[][] -Matches a string of up to 25 square brackets. - -@item %25[^ \f\n\r\t\v] -Matches a string up to 25 characters long that doesn't contain any of -the standard whitespace characters. This is slightly different from -@samp{%s}, because if the input begins with a whitespace character, -@samp{%[} reports a matching failure while @samp{%s} simply discards the -initial whitespace. - -@item %25[a-z] -Matches up to 25 lowercase characters. -@end table - -As for @samp{%c} and @samp{%s} the @samp{%[} format is also modified to -produce wide characters if the @samp{l} modifier is present. All what -is said about @samp{%ls} above is true for @samp{%l[}. - -One more reminder: the @samp{%s} and @samp{%[} conversions are -@strong{dangerous} if you don't specify a maximum width or use the -@samp{a} flag, because input too long would overflow whatever buffer you -have provided for it. No matter how long your buffer is, a user could -supply input that is longer. A well-written program reports invalid -input with a comprehensible error message, not with a crash. - -@node Dynamic String Input -@subsection Dynamically Allocating String Conversions - -A GNU extension to formatted input lets you safely read a string with no -maximum size. Using this feature, you don't supply a buffer; instead, -@code{scanf} allocates a buffer big enough to hold the data and gives -you its address. To use this feature, write @samp{a} as a flag -character, as in @samp{%as} or @samp{%a[0-9a-z]}. - -The pointer argument you supply for where to store the input should have -type @code{char **}. The @code{scanf} function allocates a buffer and -stores its address in the word that the argument points to. You should -free the buffer with @code{free} when you no longer need it. - -Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]} -conversion specification to read a ``variable assignment'' of the form -@samp{@var{variable} = @var{value}}. - -@smallexample -@{ - char *variable, *value; - - if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n", - &variable, &value)) - @{ - invalid_input_error (); - return 0; - @} - - @dots{} -@} -@end smallexample - -@node Other Input Conversions -@subsection Other Input Conversions - -This section describes the miscellaneous input conversions. - -The @samp{%p} conversion is used to read a pointer value. It recognizes -the same syntax used by the @samp{%p} output conversion for -@code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal -number just as the @samp{%x} conversion accepts. The corresponding -argument should be of type @code{void **}; that is, the address of a -place to store a pointer. - -The resulting pointer value is not guaranteed to be valid if it was not -originally written during the same program execution that reads it in. - -The @samp{%n} conversion produces the number of characters read so far -by this call. The corresponding argument should be of type @code{int *}. -This conversion works in the same way as the @samp{%n} conversion for -@code{printf}; see @ref{Other Output Conversions}, for an example. - -The @samp{%n} conversion is the only mechanism for determining the -success of literal matches or conversions with suppressed assignments. -If the @samp{%n} follows the locus of a matching failure, then no value -is stored for it since @code{scanf} returns before processing the -@samp{%n}. If you store @code{-1} in that argument slot before calling -@code{scanf}, the presence of @code{-1} after @code{scanf} indicates an -error occurred before the @samp{%n} was reached. - -Finally, the @samp{%%} conversion matches a literal @samp{%} character -in the input stream, without using an argument. This conversion does -not permit any flags, field width, or type modifier to be specified. - -@node Formatted Input Functions -@subsection Formatted Input Functions - -Here are the descriptions of the functions for performing formatted -input. -Prototypes for these functions are in the header file @file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment ISO -@deftypefun int scanf (const char *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -The @code{scanf} function reads formatted input from the stream -@code{stdin} under the control of the template string @var{template}. -The optional arguments are pointers to the places which receive the -resulting values. - -The return value is normally the number of successful assignments. If -an end-of-file condition is detected before any matches are performed, -including matches against whitespace and literal characters in the -template, then @code{EOF} is returned. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun int wscanf (const wchar_t *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -The @code{wscanf} function reads formatted input from the stream -@code{stdin} under the control of the template string @var{template}. -The optional arguments are pointers to the places which receive the -resulting values. - -The return value is normally the number of successful assignments. If -an end-of-file condition is detected before any matches are performed, -including matches against whitespace and literal characters in the -template, then @code{WEOF} is returned. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -This function is just like @code{scanf}, except that the input is read -from the stream @var{stream} instead of @code{stdin}. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun int fwscanf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -This function is just like @code{wscanf}, except that the input is read -from the stream @var{stream} instead of @code{stdin}. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -This is like @code{scanf}, except that the characters are taken from the -null-terminated string @var{s} instead of from a stream. Reaching the -end of the string is treated as an end-of-file condition. - -The behavior of this function is undefined if copying takes place -between objects that overlap---for example, if @var{s} is also given -as an argument to receive a string read under control of the @samp{%s}, -@samp{%S}, or @samp{%[} conversion. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun int swscanf (const wchar_t *@var{ws}, const wchar_t *@var{template}, @dots{}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -This is like @code{wscanf}, except that the characters are taken from the -null-terminated string @var{ws} instead of from a stream. Reaching the -end of the string is treated as an end-of-file condition. - -The behavior of this function is undefined if copying takes place -between objects that overlap---for example, if @var{ws} is also given as -an argument to receive a string read under control of the @samp{%s}, -@samp{%S}, or @samp{%[} conversion. -@end deftypefun - -@node Variable Arguments Input -@subsection Variable Arguments Input Functions - -The functions @code{vscanf} and friends are provided so that you can -define your own variadic @code{scanf}-like functions that make use of -the same internals as the built-in formatted output functions. -These functions are analogous to the @code{vprintf} series of output -functions. @xref{Variable Arguments Output}, for important -information on how to use them. - -@strong{Portability Note:} The functions listed in this section were -introduced in @w{ISO C99} and were before available as GNU extensions. - -@comment stdio.h -@comment ISO -@deftypefun int vscanf (const char *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -This function is similar to @code{scanf}, but instead of taking -a variable number of arguments directly, it takes an argument list -pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}). -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun int vwscanf (const wchar_t *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -This function is similar to @code{wscanf}, but instead of taking -a variable number of arguments directly, it takes an argument list -pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}). -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -This is the equivalent of @code{fscanf} with the variable argument list -specified directly as for @code{vscanf}. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun int vfwscanf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} -This is the equivalent of @code{fwscanf} with the variable argument list -specified directly as for @code{vwscanf}. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -This is the equivalent of @code{sscanf} with the variable argument list -specified directly as for @code{vscanf}. -@end deftypefun - -@comment wchar.h -@comment ISO -@deftypefun int vswscanf (const wchar_t *@var{s}, const wchar_t *@var{template}, va_list @var{ap}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -This is the equivalent of @code{swscanf} with the variable argument list -specified directly as for @code{vwscanf}. -@end deftypefun - -In GNU C, there is a special construct you can use to let the compiler -know that a function uses a @code{scanf}-style format string. Then it -can check the number and types of arguments in each call to the -function, and warn you when they do not match the format string. -For details, see @ref{Function Attributes, , Declaring Attributes of Functions, -gcc.info, Using GNU CC}. - -@node EOF and Errors -@section End-Of-File and Errors - -@cindex end of file, on a stream -Many of the functions described in this chapter return the value of the -macro @code{EOF} to indicate unsuccessful completion of the operation. -Since @code{EOF} is used to report both end of file and random errors, -it's often better to use the @code{feof} function to check explicitly -for end of file and @code{ferror} to check for errors. These functions -check indicators that are part of the internal state of the stream -object, indicators set if the appropriate condition was detected by a -previous I/O operation on that stream. - -@comment stdio.h -@comment ISO -@deftypevr Macro int EOF -This macro is an integer value that is returned by a number of narrow -stream functions to indicate an end-of-file condition, or some other -error situation. With @theglibc{}, @code{EOF} is @code{-1}. In -other libraries, its value may be some other negative number. - -This symbol is declared in @file{stdio.h}. -@end deftypevr - -@comment wchar.h -@comment ISO -@deftypevr Macro int WEOF -This macro is an integer value that is returned by a number of wide -stream functions to indicate an end-of-file condition, or some other -error situation. With @theglibc{}, @code{WEOF} is @code{-1}. In -other libraries, its value may be some other negative number. - -This symbol is declared in @file{wchar.h}. -@end deftypevr - -@comment stdio.h -@comment ISO -@deftypefun int feof (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} -The @code{feof} function returns nonzero if and only if the end-of-file -indicator for the stream @var{stream} is set. - -This symbol is declared in @file{stdio.h}. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun int feof_unlocked (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c There isn't much of a thread unsafety risk in reading a flag word and -@c testing a bit in it. -The @code{feof_unlocked} function is equivalent to the @code{feof} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. - -This symbol is declared in @file{stdio.h}. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int ferror (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} -The @code{ferror} function returns nonzero if and only if the error -indicator for the stream @var{stream} is set, indicating that an error -has occurred on a previous operation on the stream. - -This symbol is declared in @file{stdio.h}. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun int ferror_unlocked (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{ferror_unlocked} function is equivalent to the @code{ferror} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. - -This symbol is declared in @file{stdio.h}. -@end deftypefun - -In addition to setting the error indicator associated with the stream, -the functions that operate on streams also set @code{errno} in the same -way as the corresponding low-level functions that operate on file -descriptors. For example, all of the functions that perform output to a -stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are -implemented in terms of @code{write}, and all of the @code{errno} error -conditions defined for @code{write} are meaningful for these functions. -For more information about the descriptor-level I/O functions, see -@ref{Low-Level I/O}. - -@node Error Recovery -@section Recovering from errors - -You may explicitly clear the error and EOF flags with the @code{clearerr} -function. - -@comment stdio.h -@comment ISO -@deftypefun void clearerr (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} -This function clears the end-of-file and error indicators for the -stream @var{stream}. - -The file positioning functions (@pxref{File Positioning}) also clear the -end-of-file indicator for the stream. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun void clearerr_unlocked (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@assafe{}@acsafe{}} -The @code{clearerr_unlocked} function is equivalent to the @code{clearerr} -function except that it does not implicitly lock the stream. - -This function is a GNU extension. -@end deftypefun - -Note that it is @emph{not} correct to just clear the error flag and retry -a failed stream operation. After a failed write, any number of -characters since the last buffer flush may have been committed to the -file, while some buffered data may have been discarded. Merely retrying -can thus cause lost or repeated data. - -A failed read may leave the file pointer in an inappropriate position for -a second try. In both cases, you should seek to a known position before -retrying. - -Most errors that can happen are not recoverable --- a second try will -always fail again in the same way. So usually it is best to give up and -report the error to the user, rather than install complicated recovery -logic. - -One important exception is @code{EINTR} (@pxref{Interrupted Primitives}). -Many stream I/O implementations will treat it as an ordinary error, which -can be quite inconvenient. You can avoid this hassle by installing all -signals with the @code{SA_RESTART} flag. - -For similar reasons, setting nonblocking I/O on a stream's file -descriptor is not usually advisable. - -@node Binary Streams -@section Text and Binary Streams - -@gnusystems{} and other POSIX-compatible operating systems organize all -files as uniform sequences of characters. However, some other systems -make a distinction between files containing text and files containing -binary data, and the input and output facilities of @w{ISO C} provide for -this distinction. This section tells you how to write programs portable -to such systems. - -@cindex text stream -@cindex binary stream -When you open a stream, you can specify either a @dfn{text stream} or a -@dfn{binary stream}. You indicate that you want a binary stream by -specifying the @samp{b} modifier in the @var{opentype} argument to -@code{fopen}; see @ref{Opening Streams}. Without this -option, @code{fopen} opens the file as a text stream. - -Text and binary streams differ in several ways: - -@itemize @bullet -@item -The data read from a text stream is divided into @dfn{lines} which are -terminated by newline (@code{'\n'}) characters, while a binary stream is -simply a long series of characters. A text stream might on some systems -fail to handle lines more than 254 characters long (including the -terminating newline character). -@cindex lines (in a text file) - -@item -On some systems, text files can contain only printing characters, -horizontal tab characters, and newlines, and so text streams may not -support other characters. However, binary streams can handle any -character value. - -@item -Space characters that are written immediately preceding a newline -character in a text stream may disappear when the file is read in again. - -@item -More generally, there need not be a one-to-one mapping between -characters that are read from or written to a text stream, and the -characters in the actual file. -@end itemize - -Since a binary stream is always more capable and more predictable than a -text stream, you might wonder what purpose text streams serve. Why not -simply always use binary streams? The answer is that on these operating -systems, text and binary streams use different file formats, and the -only way to read or write ``an ordinary file of text'' that can work -with other text-oriented programs is through a text stream. - -In @theglibc{}, and on all POSIX systems, there is no difference -between text streams and binary streams. When you open a stream, you -get the same kind of stream regardless of whether you ask for binary. -This stream can handle any file content, and has none of the -restrictions that text streams sometimes have. - -@node File Positioning -@section File Positioning -@cindex file positioning on a stream -@cindex positioning a stream -@cindex seeking on a stream - -The @dfn{file position} of a stream describes where in the file the -stream is currently reading or writing. I/O on the stream advances the -file position through the file. On @gnusystems{}, the file position is -represented as an integer, which counts the number of bytes from the -beginning of the file. @xref{File Position}. - -During I/O to an ordinary disk file, you can change the file position -whenever you wish, so as to read or write any portion of the file. Some -other kinds of files may also permit this. Files which support changing -the file position are sometimes referred to as @dfn{random-access} -files. - -You can use the functions in this section to examine or modify the file -position indicator associated with a stream. The symbols listed below -are declared in the header file @file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment ISO -@deftypefun {long int} ftell (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function returns the current file position of the stream -@var{stream}. - -This function can fail if the stream doesn't support file positioning, -or if the file position can't be represented in a @code{long int}, and -possibly for other reasons as well. If a failure occurs, a value of -@code{-1} is returned. -@end deftypefun - -@comment stdio.h -@comment Unix98 -@deftypefun off_t ftello (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The @code{ftello} function is similar to @code{ftell}, except that it -returns a value of type @code{off_t}. Systems which support this type -use it to describe all file positions, unlike the POSIX specification -which uses a long int. The two are not necessarily the same size. -Therefore, using ftell can lead to problems if the implementation is -written on top of a POSIX compliant low-level I/O implementation, and using -@code{ftello} is preferable whenever it is available. - -If this function fails it returns @code{(off_t) -1}. This can happen due -to missing support for file positioning or internal errors. Otherwise -the return value is the current file position. - -The function is an extension defined in the Unix Single Specification -version 2. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bit system this function is in fact @code{ftello64}. I.e., the -LFS interface transparently replaces the old interface. -@end deftypefun - -@comment stdio.h -@comment Unix98 -@deftypefun off64_t ftello64 (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function is similar to @code{ftello} with the only difference that -the return value is of type @code{off64_t}. This also requires that the -stream @var{stream} was opened using either @code{fopen64}, -@code{freopen64}, or @code{tmpfile64} since otherwise the underlying -file operations to position the file pointer beyond the @twoexp{31} -bytes limit might fail. - -If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 -bits machine this function is available under the name @code{ftello} -and so transparently replaces the old interface. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The @code{fseek} function is used to change the file position of the -stream @var{stream}. The value of @var{whence} must be one of the -constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to -indicate whether the @var{offset} is relative to the beginning of the -file, the current file position, or the end of the file, respectively. - -This function returns a value of zero if the operation was successful, -and a nonzero value to indicate failure. A successful call also clears -the end-of-file indicator of @var{stream} and discards any characters -that were ``pushed back'' by the use of @code{ungetc}. - -@code{fseek} either flushes any buffered output before setting the file -position or else remembers it so it will be written later in its proper -place in the file. -@end deftypefun - -@comment stdio.h -@comment Unix98 -@deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function is similar to @code{fseek} but it corrects a problem with -@code{fseek} in a system with POSIX types. Using a value of type -@code{long int} for the offset is not compatible with POSIX. -@code{fseeko} uses the correct type @code{off_t} for the @var{offset} -parameter. - -For this reason it is a good idea to prefer @code{ftello} whenever it is -available since its functionality is (if different at all) closer the -underlying definition. - -The functionality and return value are the same as for @code{fseek}. - -The function is an extension defined in the Unix Single Specification -version 2. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bit system this function is in fact @code{fseeko64}. I.e., the -LFS interface transparently replaces the old interface. -@end deftypefun - -@comment stdio.h -@comment Unix98 -@deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function is similar to @code{fseeko} with the only difference that -the @var{offset} parameter is of type @code{off64_t}. This also -requires that the stream @var{stream} was opened using either -@code{fopen64}, @code{freopen64}, or @code{tmpfile64} since otherwise -the underlying file operations to position the file pointer beyond the -@twoexp{31} bytes limit might fail. - -If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 -bits machine this function is available under the name @code{fseeko} -and so transparently replaces the old interface. -@end deftypefun - -@strong{Portability Note:} In non-POSIX systems, @code{ftell}, -@code{ftello}, @code{fseek} and @code{fseeko} might work reliably only -on binary streams. @xref{Binary Streams}. - -The following symbolic constants are defined for use as the @var{whence} -argument to @code{fseek}. They are also used with the @code{lseek} -function (@pxref{I/O Primitives}) and to specify offsets for file locks -(@pxref{Control Operations}). - -@comment stdio.h -@comment ISO -@deftypevr Macro int SEEK_SET -This is an integer constant which, when used as the @var{whence} -argument to the @code{fseek} or @code{fseeko} functions, specifies that -the offset provided is relative to the beginning of the file. -@end deftypevr - -@comment stdio.h -@comment ISO -@deftypevr Macro int SEEK_CUR -This is an integer constant which, when used as the @var{whence} -argument to the @code{fseek} or @code{fseeko} functions, specifies that -the offset provided is relative to the current file position. -@end deftypevr - -@comment stdio.h -@comment ISO -@deftypevr Macro int SEEK_END -This is an integer constant which, when used as the @var{whence} -argument to the @code{fseek} or @code{fseeko} functions, specifies that -the offset provided is relative to the end of the file. -@end deftypevr - -@comment stdio.h -@comment ISO -@deftypefun void rewind (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The @code{rewind} function positions the stream @var{stream} at the -beginning of the file. It is equivalent to calling @code{fseek} or -@code{fseeko} on the @var{stream} with an @var{offset} argument of -@code{0L} and a @var{whence} argument of @code{SEEK_SET}, except that -the return value is discarded and the error indicator for the stream is -reset. -@end deftypefun - -These three aliases for the @samp{SEEK_@dots{}} constants exist for the -sake of compatibility with older BSD systems. They are defined in two -different header files: @file{fcntl.h} and @file{sys/file.h}. - -@vtable @code -@comment sys/file.h -@comment BSD -@item L_SET -An alias for @code{SEEK_SET}. - -@comment sys/file.h -@comment BSD -@item L_INCR -An alias for @code{SEEK_CUR}. - -@comment sys/file.h -@comment BSD -@item L_XTND -An alias for @code{SEEK_END}. -@end vtable - -@node Portable Positioning -@section Portable File-Position Functions - -On @gnusystems{}, the file position is truly a character count. You -can specify any character count value as an argument to @code{fseek} or -@code{fseeko} and get reliable results for any random access file. -However, some @w{ISO C} systems do not represent file positions in this -way. - -On some systems where text streams truly differ from binary streams, it -is impossible to represent the file position of a text stream as a count -of characters from the beginning of the file. For example, the file -position on some systems must encode both a record offset within the -file, and a character offset within the record. - -As a consequence, if you want your programs to be portable to these -systems, you must observe certain rules: - -@itemize @bullet -@item -The value returned from @code{ftell} on a text stream has no predictable -relationship to the number of characters you have read so far. The only -thing you can rely on is that you can use it subsequently as the -@var{offset} argument to @code{fseek} or @code{fseeko} to move back to -the same file position. - -@item -In a call to @code{fseek} or @code{fseeko} on a text stream, either the -@var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and -the @var{offset} must be the result of an earlier call to @code{ftell} -on the same stream. - -@item -The value of the file position indicator of a text stream is undefined -while there are characters that have been pushed back with @code{ungetc} -that haven't been read or discarded. @xref{Unreading}. -@end itemize - -But even if you observe these rules, you may still have trouble for long -files, because @code{ftell} and @code{fseek} use a @code{long int} value -to represent the file position. This type may not have room to encode -all the file positions in a large file. Using the @code{ftello} and -@code{fseeko} functions might help here since the @code{off_t} type is -expected to be able to hold all file position values but this still does -not help to handle additional information which must be associated with -a file position. - -So if you do want to support systems with peculiar encodings for the -file positions, it is better to use the functions @code{fgetpos} and -@code{fsetpos} instead. These functions represent the file position -using the data type @code{fpos_t}, whose internal representation varies -from system to system. - -These symbols are declared in the header file @file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment ISO -@deftp {Data Type} fpos_t -This is the type of an object that can encode information about the -file position of a stream, for use by the functions @code{fgetpos} and -@code{fsetpos}. - -In @theglibc{}, @code{fpos_t} is an opaque data structure that -contains internal data to represent file offset and conversion state -information. In other systems, it might have a different internal -representation. - -When compiling with @code{_FILE_OFFSET_BITS == 64} on a 32 bit machine -this type is in fact equivalent to @code{fpos64_t} since the LFS -interface transparently replaces the old interface. -@end deftp - -@comment stdio.h -@comment Unix98 -@deftp {Data Type} fpos64_t -This is the type of an object that can encode information about the -file position of a stream, for use by the functions @code{fgetpos64} and -@code{fsetpos64}. - -In @theglibc{}, @code{fpos64_t} is an opaque data structure that -contains internal data to represent file offset and conversion state -information. In other systems, it might have a different internal -representation. -@end deftp - -@comment stdio.h -@comment ISO -@deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function stores the value of the file position indicator for the -stream @var{stream} in the @code{fpos_t} object pointed to by -@var{position}. If successful, @code{fgetpos} returns zero; otherwise -it returns a nonzero value and stores an implementation-defined positive -value in @code{errno}. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bit system the function is in fact @code{fgetpos64}. I.e., the LFS -interface transparently replaces the old interface. -@end deftypefun - -@comment stdio.h -@comment Unix98 -@deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function is similar to @code{fgetpos} but the file position is -returned in a variable of type @code{fpos64_t} to which @var{position} -points. - -If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 -bits machine this function is available under the name @code{fgetpos} -and so transparently replaces the old interface. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function sets the file position indicator for the stream @var{stream} -to the position @var{position}, which must have been set by a previous -call to @code{fgetpos} on the same stream. If successful, @code{fsetpos} -clears the end-of-file indicator on the stream, discards any characters -that were ``pushed back'' by the use of @code{ungetc}, and returns a value -of zero. Otherwise, @code{fsetpos} returns a nonzero value and stores -an implementation-defined positive value in @code{errno}. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bit system the function is in fact @code{fsetpos64}. I.e., the LFS -interface transparently replaces the old interface. -@end deftypefun - -@comment stdio.h -@comment Unix98 -@deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function is similar to @code{fsetpos} but the file position used -for positioning is provided in a variable of type @code{fpos64_t} to -which @var{position} points. - -If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 -bits machine this function is available under the name @code{fsetpos} -and so transparently replaces the old interface. -@end deftypefun - -@node Stream Buffering -@section Stream Buffering - -@cindex buffering of streams -Characters that are written to a stream are normally accumulated and -transmitted asynchronously to the file in a block, instead of appearing -as soon as they are output by the application program. Similarly, -streams often retrieve input from the host environment in blocks rather -than on a character-by-character basis. This is called @dfn{buffering}. - -If you are writing programs that do interactive input and output using -streams, you need to understand how buffering works when you design the -user interface to your program. Otherwise, you might find that output -(such as progress or prompt messages) doesn't appear when you intended -it to, or displays some other unexpected behavior. - -This section deals only with controlling when characters are transmitted -between the stream and the file or device, and @emph{not} with how -things like echoing, flow control, and the like are handled on specific -classes of devices. For information on common control operations on -terminal devices, see @ref{Low-Level Terminal Interface}. - -You can bypass the stream buffering facilities altogether by using the -low-level input and output functions that operate on file descriptors -instead. @xref{Low-Level I/O}. - -@menu -* Buffering Concepts:: Terminology is defined here. -* Flushing Buffers:: How to ensure that output buffers are flushed. -* Controlling Buffering:: How to specify what kind of buffering to use. -@end menu - -@node Buffering Concepts -@subsection Buffering Concepts - -There are three different kinds of buffering strategies: - -@itemize @bullet -@item -Characters written to or read from an @dfn{unbuffered} stream are -transmitted individually to or from the file as soon as possible. -@cindex unbuffered stream - -@item -Characters written to a @dfn{line buffered} stream are transmitted to -the file in blocks when a newline character is encountered. -@cindex line buffered stream - -@item -Characters written to or read from a @dfn{fully buffered} stream are -transmitted to or from the file in blocks of arbitrary size. -@cindex fully buffered stream -@end itemize - -Newly opened streams are normally fully buffered, with one exception: a -stream connected to an interactive device such as a terminal is -initially line buffered. @xref{Controlling Buffering}, for information -on how to select a different kind of buffering. Usually the automatic -selection gives you the most convenient kind of buffering for the file -or device you open. - -The use of line buffering for interactive devices implies that output -messages ending in a newline will appear immediately---which is usually -what you want. Output that doesn't end in a newline might or might not -show up immediately, so if you want them to appear immediately, you -should flush buffered output explicitly with @code{fflush}, as described -in @ref{Flushing Buffers}. - -@node Flushing Buffers -@subsection Flushing Buffers - -@cindex flushing a stream -@dfn{Flushing} output on a buffered stream means transmitting all -accumulated characters to the file. There are many circumstances when -buffered output on a stream is flushed automatically: - -@itemize @bullet -@item -When you try to do output and the output buffer is full. - -@item -When the stream is closed. @xref{Closing Streams}. - -@item -When the program terminates by calling @code{exit}. -@xref{Normal Termination}. - -@item -When a newline is written, if the stream is line buffered. - -@item -Whenever an input operation on @emph{any} stream actually reads data -from its file. -@end itemize - -If you want to flush the buffered output at another time, call -@code{fflush}, which is declared in the header file @file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment ISO -@deftypefun int fflush (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function causes any buffered output on @var{stream} to be delivered -to the file. If @var{stream} is a null pointer, then -@code{fflush} causes buffered output on @emph{all} open output streams -to be flushed. - -This function returns @code{EOF} if a write error occurs, or zero -otherwise. -@end deftypefun - -@comment stdio.h -@comment POSIX -@deftypefun int fflush_unlocked (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{fflush_unlocked} function is equivalent to the @code{fflush} -function except that it does not implicitly lock the stream. -@end deftypefun - -The @code{fflush} function can be used to flush all streams currently -opened. While this is useful in some situations it does often more than -necessary since it might be done in situations when terminal input is -required and the program wants to be sure that all output is visible on -the terminal. But this means that only line buffered streams have to be -flushed. Solaris introduced a function especially for this. It was -always available in @theglibc{} in some form but never officially -exported. - -@comment stdio_ext.h -@comment GNU -@deftypefun void _flushlbf (void) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -The @code{_flushlbf} function flushes all line buffered streams -currently opened. - -This function is declared in the @file{stdio_ext.h} header. -@end deftypefun - -@strong{Compatibility Note:} Some brain-damaged operating systems have -been known to be so thoroughly fixated on line-oriented input and output -that flushing a line buffered stream causes a newline to be written! -Fortunately, this ``feature'' seems to be becoming less common. You do -not need to worry about this with @theglibc{}. - -In some situations it might be useful to not flush the output pending -for a stream but instead simply forget it. If transmission is costly -and the output is not needed anymore this is valid reasoning. In this -situation a non-standard function introduced in Solaris and available in -@theglibc{} can be used. - -@comment stdio_ext.h -@comment GNU -@deftypefun void __fpurge (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} -The @code{__fpurge} function causes the buffer of the stream -@var{stream} to be emptied. If the stream is currently in read mode all -input in the buffer is lost. If the stream is in output mode the -buffered output is not written to the device (or whatever other -underlying storage) and the buffer is cleared. - -This function is declared in @file{stdio_ext.h}. -@end deftypefun - -@node Controlling Buffering -@subsection Controlling Which Kind of Buffering - -After opening a stream (but before any other operations have been -performed on it), you can explicitly specify what kind of buffering you -want it to have using the @code{setvbuf} function. -@cindex buffering, controlling - -The facilities listed in this section are declared in the header -file @file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment ISO -@deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function is used to specify that the stream @var{stream} should -have the buffering mode @var{mode}, which can be either @code{_IOFBF} -(for full buffering), @code{_IOLBF} (for line buffering), or -@code{_IONBF} (for unbuffered input/output). - -If you specify a null pointer as the @var{buf} argument, then @code{setvbuf} -allocates a buffer itself using @code{malloc}. This buffer will be freed -when you close the stream. - -Otherwise, @var{buf} should be a character array that can hold at least -@var{size} characters. You should not free the space for this array as -long as the stream remains open and this array remains its buffer. You -should usually either allocate it statically, or @code{malloc} -(@pxref{Unconstrained Allocation}) the buffer. Using an automatic array -is not a good idea unless you close the file before exiting the block -that declares the array. - -While the array remains a stream buffer, the stream I/O functions will -use the buffer for their internal purposes. You shouldn't try to access -the values in the array directly while the stream is using it for -buffering. - -The @code{setvbuf} function returns zero on success, or a nonzero value -if the value of @var{mode} is not valid or if the request could not -be honored. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypevr Macro int _IOFBF -The value of this macro is an integer constant expression that can be -used as the @var{mode} argument to the @code{setvbuf} function to -specify that the stream should be fully buffered. -@end deftypevr - -@comment stdio.h -@comment ISO -@deftypevr Macro int _IOLBF -The value of this macro is an integer constant expression that can be -used as the @var{mode} argument to the @code{setvbuf} function to -specify that the stream should be line buffered. -@end deftypevr - -@comment stdio.h -@comment ISO -@deftypevr Macro int _IONBF -The value of this macro is an integer constant expression that can be -used as the @var{mode} argument to the @code{setvbuf} function to -specify that the stream should be unbuffered. -@end deftypevr - -@comment stdio.h -@comment ISO -@deftypevr Macro int BUFSIZ -The value of this macro is an integer constant expression that is good -to use for the @var{size} argument to @code{setvbuf}. This value is -guaranteed to be at least @code{256}. - -The value of @code{BUFSIZ} is chosen on each system so as to make stream -I/O efficient. So it is a good idea to use @code{BUFSIZ} as the size -for the buffer when you call @code{setvbuf}. - -Actually, you can get an even better value to use for the buffer size -by means of the @code{fstat} system call: it is found in the -@code{st_blksize} field of the file attributes. @xref{Attribute Meanings}. - -Sometimes people also use @code{BUFSIZ} as the allocation size of -buffers used for related purposes, such as strings used to receive a -line of input with @code{fgets} (@pxref{Character Input}). There is no -particular reason to use @code{BUFSIZ} for this instead of any other -integer, except that it might lead to doing I/O in chunks of an -efficient size. -@end deftypevr - -@comment stdio.h -@comment ISO -@deftypefun void setbuf (FILE *@var{stream}, char *@var{buf}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -If @var{buf} is a null pointer, the effect of this function is -equivalent to calling @code{setvbuf} with a @var{mode} argument of -@code{_IONBF}. Otherwise, it is equivalent to calling @code{setvbuf} -with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size} -argument of @code{BUFSIZ}. - -The @code{setbuf} function is provided for compatibility with old code; -use @code{setvbuf} in all new programs. -@end deftypefun - -@comment stdio.h -@comment BSD -@deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -If @var{buf} is a null pointer, this function makes @var{stream} unbuffered. -Otherwise, it makes @var{stream} fully buffered using @var{buf} as the -buffer. The @var{size} argument specifies the length of @var{buf}. - -This function is provided for compatibility with old BSD code. Use -@code{setvbuf} instead. -@end deftypefun - -@comment stdio.h -@comment BSD -@deftypefun void setlinebuf (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}} -This function makes @var{stream} be line buffered, and allocates the -buffer for you. - -This function is provided for compatibility with old BSD code. Use -@code{setvbuf} instead. -@end deftypefun - -It is possible to query whether a given stream is line buffered or not -using a non-standard function introduced in Solaris and available in -@theglibc{}. - -@comment stdio_ext.h -@comment GNU -@deftypefun int __flbf (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{__flbf} function will return a nonzero value in case the -stream @var{stream} is line buffered. Otherwise the return value is -zero. - -This function is declared in the @file{stdio_ext.h} header. -@end deftypefun - -Two more extensions allow to determine the size of the buffer and how -much of it is used. These functions were also introduced in Solaris. - -@comment stdio_ext.h -@comment GNU -@deftypefun size_t __fbufsize (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}} -The @code{__fbufsize} function return the size of the buffer in the -stream @var{stream}. This value can be used to optimize the use of the -stream. - -This function is declared in the @file{stdio_ext.h} header. -@end deftypefun - -@comment stdio_ext.h -@comment GNU -@deftypefun size_t __fpending (FILE *@var{stream}) -@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}} -The @code{__fpending} -function returns the number of bytes currently in the output buffer. -For wide-oriented streams the measuring unit is wide characters. This -function should not be used on buffers in read mode or opened read-only. - -This function is declared in the @file{stdio_ext.h} header. -@end deftypefun - -@node Other Kinds of Streams -@section Other Kinds of Streams - -@Theglibc{} provides ways for you to define additional kinds of -streams that do not necessarily correspond to an open file. - -One such type of stream takes input from or writes output to a string. -These kinds of streams are used internally to implement the -@code{sprintf} and @code{sscanf} functions. You can also create such a -stream explicitly, using the functions described in @ref{String Streams}. - -More generally, you can define streams that do input/output to arbitrary -objects using functions supplied by your program. This protocol is -discussed in @ref{Custom Streams}. - -@strong{Portability Note:} The facilities described in this section are -specific to GNU. Other systems or C implementations might or might not -provide equivalent functionality. - -@menu -* String Streams:: Streams that get data from or put data in - a string or memory buffer. -* Custom Streams:: Defining your own streams with an arbitrary - input data source and/or output data sink. -@end menu - -@node String Streams -@subsection String Streams - -@cindex stream, for I/O to a string -@cindex string stream -The @code{fmemopen} and @code{open_memstream} functions allow you to do -I/O to a string or memory buffer. These facilities are declared in -@file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment GNU -@deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}} -@c Unlike open_memstream, fmemopen does (indirectly) call _IO_link_in, -@c bringing with it additional potential for async trouble with -@c list_all_lock. -This function opens a stream that allows the access specified by the -@var{opentype} argument, that reads from or writes to the buffer specified -by the argument @var{buf}. This array must be at least @var{size} bytes long. - -If you specify a null pointer as the @var{buf} argument, @code{fmemopen} -dynamically allocates an array @var{size} bytes long (as with @code{malloc}; -@pxref{Unconstrained Allocation}). This is really only useful -if you are going to write things to the buffer and then read them back -in again, because you have no way of actually getting a pointer to the -buffer (for this, try @code{open_memstream}, below). The buffer is -freed when the stream is closed. - -The argument @var{opentype} is the same as in @code{fopen} -(@pxref{Opening Streams}). If the @var{opentype} specifies -append mode, then the initial file position is set to the first null -character in the buffer. Otherwise the initial file position is at the -beginning of the buffer. - -When a stream open for writing is flushed or closed, a null character -(zero byte) is written at the end of the buffer if it fits. You -should add an extra byte to the @var{size} argument to account for this. -Attempts to write more than @var{size} bytes to the buffer result -in an error. - -For a stream open for reading, null characters (zero bytes) in the -buffer do not count as ``end of file''. Read operations indicate end of -file only when the file position advances past @var{size} bytes. So, if -you want to read characters from a null-terminated string, you should -supply the length of the string as the @var{size} argument. -@end deftypefun - -Here is an example of using @code{fmemopen} to create a stream for -reading from a string: - -@smallexample -@include memopen.c.texi -@end smallexample - -This program produces the following output: - -@smallexample -Got f -Got o -Got o -Got b -Got a -Got r -@end smallexample - -@comment stdio.h -@comment GNU -@deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -This function opens a stream for writing to a buffer. The buffer is -allocated dynamically and grown as necessary, using @code{malloc}. -After you've closed the stream, this buffer is your responsibility to -clean up using @code{free} or @code{realloc}. @xref{Unconstrained Allocation}. - -When the stream is closed with @code{fclose} or flushed with -@code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to -contain the pointer to the buffer and its size. The values thus stored -remain valid only as long as no further output on the stream takes -place. If you do more output, you must flush the stream again to store -new values before you use them again. - -A null character is written at the end of the buffer. This null character -is @emph{not} included in the size value stored at @var{sizeloc}. - -You can move the stream's file position with @code{fseek} or -@code{fseeko} (@pxref{File Positioning}). Moving the file position past -the end of the data already written fills the intervening space with -zeroes. -@end deftypefun - -Here is an example of using @code{open_memstream}: - -@smallexample -@include memstrm.c.texi -@end smallexample - -This program produces the following output: - -@smallexample -buf = `hello', size = 5 -buf = `hello, world', size = 12 -@end smallexample - -@node Custom Streams -@subsection Programming Your Own Custom Streams -@cindex custom streams -@cindex programming your own streams - -This section describes how you can make a stream that gets input from an -arbitrary data source or writes output to an arbitrary data sink -programmed by you. We call these @dfn{custom streams}. The functions -and types described here are all GNU extensions. - -@c !!! this does not talk at all about the higher-level hooks - -@menu -* Streams and Cookies:: The @dfn{cookie} records where to fetch or - store data that is read or written. -* Hook Functions:: How you should define the four @dfn{hook - functions} that a custom stream needs. -@end menu - -@node Streams and Cookies -@subsubsection Custom Streams and Cookies -@cindex cookie, for custom stream - -Inside every custom stream is a special object called the @dfn{cookie}. -This is an object supplied by you which records where to fetch or store -the data read or written. It is up to you to define a data type to use -for the cookie. The stream functions in the library never refer -directly to its contents, and they don't even know what the type is; -they record its address with type @code{void *}. - -To implement a custom stream, you must specify @emph{how} to fetch or -store the data in the specified place. You do this by defining -@dfn{hook functions} to read, write, change ``file position'', and close -the stream. All four of these functions will be passed the stream's -cookie so they can tell where to fetch or store the data. The library -functions don't know what's inside the cookie, but your functions will -know. - -When you create a custom stream, you must specify the cookie pointer, -and also the four hook functions stored in a structure of type -@code{cookie_io_functions_t}. - -These facilities are declared in @file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment GNU -@deftp {Data Type} {cookie_io_functions_t} -This is a structure type that holds the functions that define the -communications protocol between the stream and its cookie. It has -the following members: - -@table @code -@item cookie_read_function_t *read -This is the function that reads data from the cookie. If the value is a -null pointer instead of a function, then read operations on this stream -always return @code{EOF}. - -@item cookie_write_function_t *write -This is the function that writes data to the cookie. If the value is a -null pointer instead of a function, then data written to the stream is -discarded. - -@item cookie_seek_function_t *seek -This is the function that performs the equivalent of file positioning on -the cookie. If the value is a null pointer instead of a function, calls -to @code{fseek} or @code{fseeko} on this stream can only seek to -locations within the buffer; any attempt to seek outside the buffer will -return an @code{ESPIPE} error. - -@item cookie_close_function_t *close -This function performs any appropriate cleanup on the cookie when -closing the stream. If the value is a null pointer instead of a -function, nothing special is done to close the cookie when the stream is -closed. -@end table -@end deftp - -@comment stdio.h -@comment GNU -@deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}} -This function actually creates the stream for communicating with the -@var{cookie} using the functions in the @var{io-functions} argument. -The @var{opentype} argument is interpreted as for @code{fopen}; -see @ref{Opening Streams}. (But note that the ``truncate on -open'' option is ignored.) The new stream is fully buffered. - -The @code{fopencookie} function returns the newly created stream, or a null -pointer in case of an error. -@end deftypefun - -@node Hook Functions -@subsubsection Custom Stream Hook Functions -@cindex hook functions (of custom streams) - -Here are more details on how you should define the four hook functions -that a custom stream needs. - -You should define the function to read data from the cookie as: - -@smallexample -ssize_t @var{reader} (void *@var{cookie}, char *@var{buffer}, size_t @var{size}) -@end smallexample - -This is very similar to the @code{read} function; see @ref{I/O -Primitives}. Your function should transfer up to @var{size} bytes into -the @var{buffer}, and return the number of bytes read, or zero to -indicate end-of-file. You can return a value of @code{-1} to indicate -an error. - -You should define the function to write data to the cookie as: - -@smallexample -ssize_t @var{writer} (void *@var{cookie}, const char *@var{buffer}, size_t @var{size}) -@end smallexample - -This is very similar to the @code{write} function; see @ref{I/O -Primitives}. Your function should transfer up to @var{size} bytes from -the buffer, and return the number of bytes written. You can return a -value of @code{0} to indicate an error. You must not return any -negative value. - -You should define the function to perform seek operations on the cookie -as: - -@smallexample -int @var{seeker} (void *@var{cookie}, off64_t *@var{position}, int @var{whence}) -@end smallexample - -For this function, the @var{position} and @var{whence} arguments are -interpreted as for @code{fgetpos}; see @ref{Portable Positioning}. - -After doing the seek operation, your function should store the resulting -file position relative to the beginning of the file in @var{position}. -Your function should return a value of @code{0} on success and @code{-1} -to indicate an error. - -You should define the function to do cleanup operations on the cookie -appropriate for closing the stream as: - -@smallexample -int @var{cleaner} (void *@var{cookie}) -@end smallexample - -Your function should return @code{-1} to indicate an error, and @code{0} -otherwise. - -@comment stdio.h -@comment GNU -@deftp {Data Type} cookie_read_function_t -This is the data type that the read function for a custom stream should have. -If you declare the function as shown above, this is the type it will have. -@end deftp - -@comment stdio.h -@comment GNU -@deftp {Data Type} cookie_write_function_t -The data type of the write function for a custom stream. -@end deftp - -@comment stdio.h -@comment GNU -@deftp {Data Type} cookie_seek_function_t -The data type of the seek function for a custom stream. -@end deftp - -@comment stdio.h -@comment GNU -@deftp {Data Type} cookie_close_function_t -The data type of the close function for a custom stream. -@end deftp - -@ignore -Roland says: - -@quotation -There is another set of functions one can give a stream, the -input-room and output-room functions. These functions must -understand stdio internals. To describe how to use these -functions, you also need to document lots of how stdio works -internally (which isn't relevant for other uses of stdio). -Perhaps I can write an interface spec from which you can write -good documentation. But it's pretty complex and deals with lots -of nitty-gritty details. I think it might be better to let this -wait until the rest of the manual is more done and polished. -@end quotation -@end ignore - -@c ??? This section could use an example. - - -@node Formatted Messages -@section Formatted Messages -@cindex formatted messages - -On systems which are based on System V messages of programs (especially -the system tools) are printed in a strict form using the @code{fmtmsg} -function. The uniformity sometimes helps the user to interpret messages -and the strictness tests of the @code{fmtmsg} function ensure that the -programmer follows some minimal requirements. - -@menu -* Printing Formatted Messages:: The @code{fmtmsg} function. -* Adding Severity Classes:: Add more severity classes. -* Example:: How to use @code{fmtmsg} and @code{addseverity}. -@end menu - - -@node Printing Formatted Messages -@subsection Printing Formatted Messages - -Messages can be printed to standard error and/or to the console. To -select the destination the programmer can use the following two values, -bitwise OR combined if wanted, for the @var{classification} parameter of -@code{fmtmsg}: - -@vtable @code -@item MM_PRINT -Display the message in standard error. -@item MM_CONSOLE -Display the message on the system console. -@end vtable - -The erroneous piece of the system can be signalled by exactly one of the -following values which also is bitwise ORed with the -@var{classification} parameter to @code{fmtmsg}: - -@vtable @code -@item MM_HARD -The source of the condition is some hardware. -@item MM_SOFT -The source of the condition is some software. -@item MM_FIRM -The source of the condition is some firmware. -@end vtable - -A third component of the @var{classification} parameter to @code{fmtmsg} -can describe the part of the system which detects the problem. This is -done by using exactly one of the following values: - -@vtable @code -@item MM_APPL -The erroneous condition is detected by the application. -@item MM_UTIL -The erroneous condition is detected by a utility. -@item MM_OPSYS -The erroneous condition is detected by the operating system. -@end vtable - -A last component of @var{classification} can signal the results of this -message. Exactly one of the following values can be used: - -@vtable @code -@item MM_RECOVER -It is a recoverable error. -@item MM_NRECOV -It is a non-recoverable error. -@end vtable - -@comment fmtmsg.h -@comment XPG -@deftypefun int fmtmsg (long int @var{classification}, const char *@var{label}, int @var{severity}, const char *@var{text}, const char *@var{action}, const char *@var{tag}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acsafe{}} -Display a message described by its parameters on the device(s) specified -in the @var{classification} parameter. The @var{label} parameter -identifies the source of the message. The string should consist of two -colon separated parts where the first part has not more than 10 and the -second part not more than 14 characters. The @var{text} parameter -describes the condition of the error, the @var{action} parameter possible -steps to recover from the error and the @var{tag} parameter is a -reference to the online documentation where more information can be -found. It should contain the @var{label} value and a unique -identification number. - -Each of the parameters can be a special value which means this value -is to be omitted. The symbolic names for these values are: - -@vtable @code -@item MM_NULLLBL -Ignore @var{label} parameter. -@item MM_NULLSEV -Ignore @var{severity} parameter. -@item MM_NULLMC -Ignore @var{classification} parameter. This implies that nothing is -actually printed. -@item MM_NULLTXT -Ignore @var{text} parameter. -@item MM_NULLACT -Ignore @var{action} parameter. -@item MM_NULLTAG -Ignore @var{tag} parameter. -@end vtable - -There is another way certain fields can be omitted from the output to -standard error. This is described below in the description of -environment variables influencing the behavior. - -The @var{severity} parameter can have one of the values in the following -table: -@cindex severity class - -@vtable @code -@item MM_NOSEV -Nothing is printed, this value is the same as @code{MM_NULLSEV}. -@item MM_HALT -This value is printed as @code{HALT}. -@item MM_ERROR -This value is printed as @code{ERROR}. -@item MM_WARNING -This value is printed as @code{WARNING}. -@item MM_INFO -This value is printed as @code{INFO}. -@end vtable - -The numeric value of these five macros are between @code{0} and -@code{4}. Using the environment variable @code{SEV_LEVEL} or using the -@code{addseverity} function one can add more severity levels with their -corresponding string to print. This is described below -(@pxref{Adding Severity Classes}). - -@noindent -If no parameter is ignored the output looks like this: - -@smallexample -@var{label}: @var{severity-string}: @var{text} -TO FIX: @var{action} @var{tag} -@end smallexample - -The colons, new line characters and the @code{TO FIX} string are -inserted if necessary, i.e., if the corresponding parameter is not -ignored. - -This function is specified in the X/Open Portability Guide. It is also -available on all systems derived from System V. - -The function returns the value @code{MM_OK} if no error occurred. If -only the printing to standard error failed, it returns @code{MM_NOMSG}. -If printing to the console fails, it returns @code{MM_NOCON}. If -nothing is printed @code{MM_NOTOK} is returned. Among situations where -all outputs fail this last value is also returned if a parameter value -is incorrect. -@end deftypefun - -There are two environment variables which influence the behavior of -@code{fmtmsg}. The first is @code{MSGVERB}. It is used to control the -output actually happening on standard error (@emph{not} the console -output). Each of the five fields can explicitly be enabled. To do -this the user has to put the @code{MSGVERB} variable with a format like -the following in the environment before calling the @code{fmtmsg} function -the first time: - -@smallexample -MSGVERB=@var{keyword}[:@var{keyword}[:@dots{}]] -@end smallexample - -Valid @var{keyword}s are @code{label}, @code{severity}, @code{text}, -@code{action}, and @code{tag}. If the environment variable is not given -or is the empty string, a not supported keyword is given or the value is -somehow else invalid, no part of the message is masked out. - -The second environment variable which influences the behavior of -@code{fmtmsg} is @code{SEV_LEVEL}. This variable and the change in the -behavior of @code{fmtmsg} is not specified in the X/Open Portability -Guide. It is available in System V systems, though. It can be used to -introduce new severity levels. By default, only the five severity levels -described above are available. Any other numeric value would make -@code{fmtmsg} print nothing. - -If the user puts @code{SEV_LEVEL} with a format like - -@smallexample -SEV_LEVEL=[@var{description}[:@var{description}[:@dots{}]]] -@end smallexample - -@noindent -in the environment of the process before the first call to -@code{fmtmsg}, where @var{description} has a value of the form - -@smallexample -@var{severity-keyword},@var{level},@var{printstring} -@end smallexample - -The @var{severity-keyword} part is not used by @code{fmtmsg} but it has -to be present. The @var{level} part is a string representation of a -number. The numeric value must be a number greater than 4. This value -must be used in the @var{severity} parameter of @code{fmtmsg} to select -this class. It is not possible to overwrite any of the predefined -classes. The @var{printstring} is the string printed when a message of -this class is processed by @code{fmtmsg} (see above, @code{fmtsmg} does -not print the numeric value but instead the string representation). - - -@node Adding Severity Classes -@subsection Adding Severity Classes -@cindex severity class - -There is another possibility to introduce severity classes besides using -the environment variable @code{SEV_LEVEL}. This simplifies the task of -introducing new classes in a running program. One could use the -@code{setenv} or @code{putenv} function to set the environment variable, -but this is toilsome. - -@deftypefun int addseverity (int @var{severity}, const char *@var{string}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} -This function allows the introduction of new severity classes which can be -addressed by the @var{severity} parameter of the @code{fmtmsg} function. -The @var{severity} parameter of @code{addseverity} must match the value -for the parameter with the same name of @code{fmtmsg}, and @var{string} -is the string printed in the actual messages instead of the numeric -value. - -If @var{string} is @code{NULL} the severity class with the numeric value -according to @var{severity} is removed. - -It is not possible to overwrite or remove one of the default severity -classes. All calls to @code{addseverity} with @var{severity} set to one -of the values for the default classes will fail. - -The return value is @code{MM_OK} if the task was successfully performed. -If the return value is @code{MM_NOTOK} something went wrong. This could -mean that no more memory is available or a class is not available when -it has to be removed. - -This function is not specified in the X/Open Portability Guide although -the @code{fmtsmg} function is. It is available on System V systems. -@end deftypefun - - -@node Example -@subsection How to use @code{fmtmsg} and @code{addseverity} - -Here is a simple example program to illustrate the use of both -functions described in this section. - -@smallexample -@include fmtmsgexpl.c.texi -@end smallexample - -The second call to @code{fmtmsg} illustrates a use of this function as -it usually occurs on System V systems, which heavily use this function. -It seems worthwhile to give a short explanation here of how this system -works on System V. The value of the -@var{label} field (@code{UX:cat}) says that the error occurred in the -Unix program @code{cat}. The explanation of the error follows and the -value for the @var{action} parameter is @code{"refer to manual"}. One -could be more specific here, if necessary. The @var{tag} field contains, -as proposed above, the value of the string given for the @var{label} -parameter, and additionally a unique ID (@code{001} in this case). For -a GNU environment this string could contain a reference to the -corresponding node in the Info page for the program. - -@noindent -Running this program without specifying the @code{MSGVERB} and -@code{SEV_LEVEL} function produces the following output: - -@smallexample -UX:cat: NOTE2: invalid syntax -TO FIX: refer to manual UX:cat:001 -@end smallexample - -We see the different fields of the message and how the extra glue (the -colons and the @code{TO FIX} string) is printed. But only one of the -three calls to @code{fmtmsg} produced output. The first call does not -print anything because the @var{label} parameter is not in the correct -form. The string must contain two fields, separated by a colon -(@pxref{Printing Formatted Messages}). The third @code{fmtmsg} call -produced no output since the class with the numeric value @code{6} is -not defined. Although a class with numeric value @code{5} is also not -defined by default, the call to @code{addseverity} introduces it and -the second call to @code{fmtmsg} produces the above output. - -When we change the environment of the program to contain -@code{SEV_LEVEL=XXX,6,NOTE} when running it we get a different result: - -@smallexample -UX:cat: NOTE2: invalid syntax -TO FIX: refer to manual UX:cat:001 -label:foo: NOTE: text -TO FIX: action tag -@end smallexample - -Now the third call to @code{fmtmsg} produced some output and we see how -the string @code{NOTE} from the environment variable appears in the -message. - -Now we can reduce the output by specifying which fields we are -interested in. If we additionally set the environment variable -@code{MSGVERB} to the value @code{severity:label:action} we get the -following output: - -@smallexample -UX:cat: NOTE2 -TO FIX: refer to manual -label:foo: NOTE -TO FIX: action -@end smallexample - -@noindent -I.e., the output produced by the @var{text} and the @var{tag} parameters -to @code{fmtmsg} vanished. Please also note that now there is no colon -after the @code{NOTE} and @code{NOTE2} strings in the output. This is -not necessary since there is no more output on this line because the text -is missing. |