@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
+@standards{ISO, stdio.h}
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
These streams are declared in the header file @file{stdio.h}.
@pindex stdio.h
-@comment stdio.h
-@comment ISO
@deftypevar {FILE *} stdin
+@standards{ISO, stdio.h}
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
+@standards{ISO, stdio.h}
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
+@standards{ISO, stdio.h}
The @dfn{standard error} stream, which is used for error messages and
diagnostics issued by the program.
@end deftypevar
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})
+@standards{ISO, stdio.h}
+@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.
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}.
+The @samp{x} modifier is part of @w{ISO C11}, which says the file is
+created with exclusive access; in @theglibc{} this means the
+equivalent of @code{O_EXCL}.
@end table
The character @samp{b} in @var{opentype} has a standard meaning; it
If the open fails, @code{fopen} returns a null pointer.
-When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
+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
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})
+@standards{Unix98, stdio.h}
+@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 then @math{2^31} bytes on 32 bit machines.
+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.
and so transparently replaces the old interface.
@end deftypefun
-@comment stdio.h
-@comment ISO
@deftypevr Macro int FOPEN_MAX
+@standards{ISO, stdio.h}
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
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})
+@standards{ISO, stdio.h}
+@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,
and associated with the same stream object @var{stream}.
If the operation fails, a null pointer is returned; otherwise,
-@code{freopen} returns @var{stream}.
+@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
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 compiling with @code{_FILE_OFFSET_BITS == 64} on a
+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})
+@standards{Unix98, stdio.h}
+@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
-@math{2^31} bytes limits imposed by the normal interface. It should be
+@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.
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})
+@standards{GNU, stdio_ext.h}
+@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})
+@standards{GNU, stdio_ext.h}
+@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 kind of problems there are two more functions.
+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})
+@standards{GNU, stdio_ext.h}
+@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.
This function is declared in @file{stdio_ext.h}.
@end deftypefun
-@comment stdio_ext.h
-@comment GNU
@deftypefun int __fwriting (FILE *@var{stream})
+@standards{GNU, stdio_ext.h}
+@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.
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})
+@standards{ISO, stdio.h}
+@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
To close all streams currently available @theglibc{} provides
another function.
-@comment stdio.h
-@comment GNU
@deftypefun int fcloseall (void)
+@standards{GNU, stdio.h}
+@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 connection to corresponding files to be broken. All buffered data
+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.
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 is heavily influenced by the
+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
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})
+@standards{POSIX, stdio.h}
+@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
-implicit through a call of a stream function lock the stream. The
+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})
+@standards{POSIX, stdio.h}
+@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
another thread.
@end deftypefun
-@comment stdio.h
-@comment POSIX
@deftypefun void funlockfile (FILE *@var{stream})
+@standards{POSIX, stdio.h}
+@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
+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
@end smallexample
Without the explicit locking it would be possible for another thread to
-use the stream @var{fp} after the @code{fputs} call return and before
+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}.
@}
@end smallexample
-Now that we covered why it is necessary to have these locking it is
+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
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})
+@standards{GNU, stdio_ext.h}
+@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
variants will implicitly lock the stream.
@item FSETLOCKING_BYCALLER
-After the @code{__fsetlocking} function returns the user is responsible
+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}.
@itemize @bullet
@item
-If any of the normal character functions is used (this includes the
+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 is used the stream is marked as
+If any of the wide character functions are used the stream is marked as
wide oriented.
@item
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 avoiding this.
+@code{fwide} function can help avoid this.
-@comment wchar.h
-@comment ISO
@deftypefun int fwide (FILE *@var{stream}, int @var{mode})
+@standards{ISO, wchar.h}
+@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
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 advise above is followed).
+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}
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 invisible to the user.
+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
This section describes functions for performing character- and
line-oriented output.
-These narrow streams functions are declared in the header file
+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})
+@standards{ISO, stdio.h}
+@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})
+@standards{ISO, wchar.h}
+@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})
+@standards{POSIX, stdio.h}
+@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 (wint_t @var{wc}, FILE *@var{stream})
+@deftypefun wint_t fputwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
+@standards{POSIX, wchar.h}
+@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})
+@standards{ISO, stdio.h}
+@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
use for writing a single character.
@end deftypefun
-@comment wchar.h
-@comment ISO
@deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream})
+@standards{ISO, wchar.h}
+@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
use for writing a single wide character.
@end deftypefun
-@comment stdio.h
-@comment POSIX
@deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})
+@standards{POSIX, stdio.h}
+@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})
+@standards{GNU, wchar.h}
+@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})
+@standards{ISO, stdio.h}
+@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})
+@standards{ISO, wchar.h}
+@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})
+@standards{POSIX, stdio.h}
+@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})
+@standards{GNU, wchar.h}
+@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})
+@standards{ISO, stdio.h}
+@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.
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})
+@standards{ISO, wchar.h}
+@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
a non-negative value.
@end deftypefun
-@comment stdio.h
-@comment GNU
@deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream})
+@standards{GNU, stdio.h}
+@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})
+@standards{GNU, wchar.h}
+@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})
+@standards{ISO, stdio.h}
+@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}
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})
+@standards{SVID, stdio.h}
+@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}).
@cindex reading from a stream, by characters
This section describes functions for performing character-oriented
-input. These narrow streams functions are declared in the header file
+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
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})
+@standards{ISO, stdio.h}
+@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})
+@standards{ISO, wchar.h}
+@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})
+@standards{POSIX, stdio.h}
+@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})
+@standards{GNU, wchar.h}
+@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})
+@standards{ISO, stdio.h}
+@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
character.
@end deftypefun
-@comment wchar.h
-@comment ISO
@deftypefun wint_t getwc (FILE *@var{stream})
+@standards{ISO, wchar.h}
+@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})
+@standards{POSIX, stdio.h}
+@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})
+@standards{GNU, wchar.h}
+@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)
+@standards{ISO, stdio.h}
+@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)
+@standards{ISO, wchar.h}
+@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)
+@standards{POSIX, stdio.h}
+@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)
+@standards{GNU, wchar.h}
+@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.
@}
@end smallexample
-@comment stdio.h
-@comment SVID
@deftypefun int getw (FILE *@var{stream})
+@standards{SVID, stdio.h}
+@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},
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})
+@standards{GNU, stdio.h}
+@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}}.
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}.
+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.
@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})
+@standards{GNU, stdio.h}
+@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
@end smallexample
@end deftypefun
-@comment stdio.h
-@comment ISO
@deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
+@standards{ISO, stdio.h}
+@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
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})
+@standards{ISO, wchar.h}
+@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
@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})
+@standards{GNU, stdio.h}
+@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})
+@standards{GNU, wchar.h}
+@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})
+@standards{ISO, stdio.h}
+@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
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})
+@standards{ISO, stdio.h}
+@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.
will encounter end of file.
@end deftypefun
-@comment wchar.h
-@comment ISO
@deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream})
+@standards{ISO, wchar.h}
+@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
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})
+@standards{ISO, stdio.h}
+@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
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})
+@standards{GNU, stdio.h}
+@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})
+@standards{ISO, stdio.h}
+@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})
+@standards{GNU, stdio.h}
+@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.
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}).
+unsigned value in binary, octal, decimal, or hexadecimal radix
+(@samp{%b}, @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
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 certainly upper bound. The exact
+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 an positional parameter in a @code{printf} call. 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 system have a quite low limit such as @math{9} for @w{System V}
+Some systems have a quite low limit such as @math{9} for @w{System V}
systems. @Theglibc{} has no real limit.
@end defvr
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.
+gcc, Using GNU CC}, for more information.
@node Table of Output Conversions
@subsection Table of Output Conversions
output, but are different when used with @code{scanf} for input
(@pxref{Table of Input Conversions}).
+@item @samp{%b}, @samp{%B}
+Print an integer as an unsigned binary number. @samp{%b} uses
+lower-case @samp{b} with the @samp{#} flag and @samp{%B} uses
+upper-case. @samp{%b} is an ISO C2X feature; @samp{%B} is an
+extension recommended by ISO C2X. @xref{Integer Conversions}, for
+details.
+
@item @samp{%o}
Print an integer as an unsigned octal number. @xref{Integer
Conversions}, for details.
Conversions}, for details.
@item @samp{%a}, @samp{%A}
-Print a floating-point number in a hexadecimal fractional notation which
+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.
@subsection Integer Conversions
This section describes the options for the @samp{%d}, @samp{%i},
-@samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
+@samp{%b}, @samp{%B}, @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,
+@code{int} argument as a signed decimal number; while @samp{b}, @samp{%o},
+@samp{%u}, and @samp{%x} print the argument as an unsigned binary, 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}.
+@samp{ABCDEF} as digits instead of @samp{abcdef}. The @samp{%B}
+conversion specification is just like @samp{%b} except that, with the
+@samp{#} flag, the output starts with @samp{0B} instead of @samp{0b}.
The following flags are meaningful:
@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)
+@samp{%X}, this prefixes a leading @samp{0x} or @samp{0X}
+(respectively) to the result. For @samp{%b} or @samp{%B}, this
+prefixes a leading @samp{0b} or @samp{0B} (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}).
+For the @samp{%m} conversion, print an error constant or decimal error
+number, instead of a (possibly translated) error message.
+
@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
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},
+@code{unsigned int} (for the unsigned conversions @samp{%b},
+@samp{%B}, @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
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{h} modifier says to convert it back to a
+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 l
Specifies that the argument is a @code{long int} or @code{unsigned long
-int}, as appropriate. Two @samp{l} characters is like the @samp{L}
+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
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 is the form
+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.
@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}.
+@samp{%A}, @samp{%E}, or @samp{%G}. On some implementations, a NaN
+may result in longer output with information about the payload of the
+NaN; ISO C2X defines a macro @code{_PRINTF_NAN_LEN_MAX} giving the
+maximum length of such output.
The following flags can be used to modify the behavior:
@noindent
prints @samp{hello}.
-If there is a @samp{l} modifier present the argument is expected to be
+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 in a wide character string. A precision can be
+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
@noindent
prints @samp{ nowhere }.
-If there is a @samp{l} modifier present the argument is expected to be of type @code{wchar_t} (or @code{const wchar_t *}).
+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
fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
@end smallexample
-@noindent
-The @samp{%m} conversion is a @glibcadj{} extension.
+The @samp{%m} conversion can be used with the @samp{#} flag to print an
+error constant, as provided by @code{strerrorname_np}. Both @samp{%m}
+and @samp{%#m} are @glibcadj{} extensions.
The @samp{%p} conversion prints a pointer value. The corresponding
argument must be of type @code{void *}. In practice, you can use any
just include @file{stdio.h}.
@pindex stdio.h
-@comment stdio.h
-@comment ISO
@deftypefun int printf (const char *@var{template}, @dots{})
+@standards{ISO, stdio.h}
+@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{})
+@standards{ISO, wchar.h}
+@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{})
+@standards{ISO, stdio.h}
+@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{})
+@standards{ISO, wchar.h}
+@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{})
+@standards{ISO, stdio.h}
+@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 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 and Concatenation}.
+@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
described below.
@end deftypefun
-@comment wchar.h
-@comment GNU
-@deftypefun int swprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, @dots{})
+@deftypefun int swprintf (wchar_t *@var{ws}, size_t @var{size}, const wchar_t *@var{template}, @dots{})
+@standards{GNU, wchar.h}
+@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}
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 an function exactly corresponding to
+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{})
+@standards{GNU, stdio.h}
+@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 or equal to @var{size}, not all characters from the result have
+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:
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;
+ /* @r{Guess we need no more than 100 bytes of space.} */
+ size_t size = 100;
+ char *buffer = xmalloc (size);
@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);
+ int buflen = snprintf (buffer, size, "value of %s is %s",
+ name, value);
+ if (! (0 <= buflen && buflen < SIZE_MAX))
+ fatal ("integer overflow");
@end group
@group
- if (nchars >= size)
+ if (buflen >= size)
@{
/* @r{Reallocate buffer now that we know
how much space is needed.} */
- size = nchars + 1;
- buffer = (char *) xrealloc (buffer, size);
+ size = buflen;
+ size++;
+ buffer = xrealloc (buffer, size);
- if (buffer != NULL)
- /* @r{Try again.} */
- snprintf (buffer, size, "value of %s is %s",
- name, value);
+ /* @r{Try again.} */
+ snprintf (buffer, size, "value of %s is %s",
+ name, value);
@}
/* @r{The last call worked, return the string.} */
return buffer;
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{})
+@standards{GNU, stdio.h}
+@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
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
+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
@end smallexample
@end deftypefun
-@comment stdio.h
-@comment GNU
@deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
+@standards{GNU, stdio.h}
+@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
+(@pxref{Growing Objects}).
@end deftypefun
@node Variable Arguments Output
subsequent arguments that were passed to your function are used by
@code{vprintf} along with the template that you specified separately.
-In some other systems, the @code{va_list} pointer may become invalid
-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. However, you can safely call
-@code{va_start} on another pointer variable and begin fetching the
-arguments again through that pointer. Calling @code{vprintf} does not
-destroy the argument list of your function, merely the particular
-pointer that you passed to it.
-
-GNU C does not have such restrictions. You can safely continue to fetch
-arguments from a @code{va_list} pointer after passing it to
-@code{vprintf}, and @code{va_end} is a no-op. (Note, however, that
-subsequent @code{va_arg} calls will fetch the same arguments which
-@code{vprintf} previously used.)
+@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})
+@standards{ISO, stdio.h}
+@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})
+@standards{ISO, wchar.h}
+@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})
+@standards{ISO, stdio.h}
+@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 __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})
+@standards{ISO, wchar.h}
+@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})
+@standards{ISO, stdio.h}
+@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{s}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap})
+@deftypefun int vswprintf (wchar_t *@var{ws}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap})
+@standards{GNU, wchar.h}
+@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})
+@standards{GNU, stdio.h}
+@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})
+@standards{GNU, stdio.h}
+@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})
+@standards{GNU, stdio.h}
+@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
+as for @code{vprintf}.
@end deftypefun
Here's an example showing how you might use @code{vfprintf}. This is a
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.
+gcc, Using GNU CC}, for more information.
@node Parsing a Template String
@subsection Parsing a Template String
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})
+@standards{GNU, printf.h}
+@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
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
+@standards{GNU, printf.h}
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
for integer values.
@vtable @code
-@comment printf.h
-@comment GNU
@item PA_INT
+@standards{GNU, printf.h}
This specifies that the base type is @code{int}.
-@comment printf.h
-@comment GNU
@item PA_CHAR
+@standards{GNU, printf.h}
This specifies that the base type is @code{int}, cast to @code{char}.
-@comment printf.h
-@comment GNU
@item PA_STRING
+@standards{GNU, printf.h}
This specifies that the base type is @code{char *}, a null-terminated string.
-@comment printf.h
-@comment GNU
@item PA_POINTER
+@standards{GNU, printf.h}
This specifies that the base type is @code{void *}, an arbitrary pointer.
-@comment printf.h
-@comment GNU
@item PA_FLOAT
+@standards{GNU, printf.h}
This specifies that the base type is @code{float}.
-@comment printf.h
-@comment GNU
@item PA_DOUBLE
+@standards{GNU, printf.h}
This specifies that the base type is @code{double}.
-@comment printf.h
-@comment GNU
@item PA_LAST
+@standards{GNU, printf.h}
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,
the code for the basic type using inclusive-or.
@vtable @code
-@comment printf.h
-@comment GNU
@item PA_FLAG_PTR
+@standards{GNU, printf.h}
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
+@standards{GNU, printf.h}
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
+@standards{GNU, printf.h}
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
+@standards{GNU, printf.h}
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
+@standards{GNU, printf.h}
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
@r{length of the string.} */
argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
- nwanted = parse_printf_format (string, nelts, argtypes);
+ nwanted = parse_printf_format (format, nargs, argtypes);
/* @r{Check the number of arguments.} */
if (nwanted > nargs)
@strong{Portability Note:} The ability to extend the syntax of
@code{printf} template strings is a GNU extension. ISO standard C has
-nothing similar.
+nothing similar. When using the GNU C compiler or any other compiler
+that interprets calls to standard I/O functions according to the rules
+of the language standard it is necessary to disable such handling by
+the appropriate compiler option. Otherwise the behavior of a program
+that relies on the extension is undefined.
@node Registering New Conversions
@subsection Registering New Conversions
@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})
+@standards{GNU, printf.h}
+@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
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.
+@strong{Portability Note:} It is possible to redefine the standard output
+conversions but doing so is strongly discouraged because it may interfere
+with the behavior of programs and compiler implementations that assume
+the effects of the conversions conform to the relevant language standards.
+In addition, conforming compilers need not guarantee that the function
+registered for a standard conversion will be called for each such
+conversion in every format string in a program.
@end deftypefun
@node Conversion Specifier Options
@file{printf.h}.
@pindex printf.h
-@comment printf.h
-@comment GNU
@deftp {Type} {struct printf_info}
+@standards{GNU, printf.h}
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
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
+@standards{GNU, printf.h}
This is the data type that a handler function should have.
@end deftp
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
+@standards{GNU, printf.h}
This type is used to describe functions that return information about
the number and type of arguments used by a conversion specifier.
@end deftp
@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})
+@standards{GNU, printf.h}
+@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:
etc. The full table is:
@ifinfo
-@multitable @hsep @vsep {' '} {2^10 (1024)} {zetta} {Upper} {10^24 (1000)}
+@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)
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})
+@standards{GNU, printf.h}
+@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.
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.
+gcc, Using GNU CC}, for more information.
@node Table of Input Conversions
@subsection Table of Input Conversions
read is controlled by the maximum field width given for the conversion.
@xref{String Input Conversions}.
-If the @samp{%c} is used in a wide stream function the read value is
+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 be large enough for up
+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}.
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:
+The default type of the corresponding argument for the @code{%d},
+@code{%i}, and @code{%n} 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
@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 of the @samp{l} modifier is present).
+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
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 character get stored in the output string.
+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
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. As special cases:
+in regular expressions for explicit sets of characters. As special cases:
@itemize @bullet
@item
@item
If a caret character @samp{^} immediately follows the initial @samp{[},
-then the set of allowed input characters is the everything @emph{except}
+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
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 *}.
+by this call. The corresponding argument should be of type @code{int *},
+unless a type modifier is in effect (@pxref{Numeric Input Conversions}).
This conversion works in the same way as the @samp{%n} conversion for
@code{printf}; see @ref{Other Output Conversions}, for an example.
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{})
+@standards{ISO, stdio.h}
+@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
template, then @code{EOF} is returned.
@end deftypefun
-@comment wchar.h
-@comment ISO
@deftypefun int wscanf (const wchar_t *@var{template}, @dots{})
+@standards{ISO, wchar.h}
+@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
template, then @code{WEOF} is returned.
@end deftypefun
-@comment stdio.h
-@comment ISO
@deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
+@standards{ISO, stdio.h}
+@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{})
+@standards{ISO, wchar.h}
+@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{})
+@standards{ISO, stdio.h}
+@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.
@samp{%S}, or @samp{%[} conversion.
@end deftypefun
-@comment wchar.h
-@comment ISO
-@deftypefun int swscanf (const wchar_t *@var{ws}, const char *@var{template}, @dots{})
+@deftypefun int swscanf (const wchar_t *@var{ws}, const wchar_t *@var{template}, @dots{})
+@standards{ISO, wchar.h}
+@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.
@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})
+@standards{ISO, stdio.h}
+@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})
+@standards{ISO, wchar.h}
+@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})
+@standards{ISO, stdio.h}
+@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})
+@standards{ISO, wchar.h}
+@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})
+@standards{ISO, stdio.h}
+@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})
+@standards{ISO, wchar.h}
+@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
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}.
+gcc, Using GNU CC}.
@node EOF and Errors
@section End-Of-File and Errors
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
+@standards{ISO, stdio.h}
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
This symbol is declared in @file{stdio.h}.
@end deftypevr
-@comment wchar.h
-@comment ISO
@deftypevr Macro int WEOF
+@standards{ISO, wchar.h}
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
This symbol is declared in @file{wchar.h}.
@end deftypevr
-@comment stdio.h
-@comment ISO
@deftypefun int feof (FILE *@var{stream})
+@standards{ISO, stdio.h}
+@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})
+@standards{GNU, stdio.h}
+@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 symbol is declared in @file{stdio.h}.
@end deftypefun
-@comment stdio.h
-@comment ISO
@deftypefun int ferror (FILE *@var{stream})
+@standards{ISO, stdio.h}
+@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})
+@standards{GNU, stdio.h}
+@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.
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})
+@standards{ISO, stdio.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
This function clears the end-of-file and error indicators for the
stream @var{stream}.
end-of-file indicator for the stream.
@end deftypefun
-@comment stdio.h
-@comment GNU
@deftypefun void clearerr_unlocked (FILE *@var{stream})
+@standards{GNU, stdio.h}
+@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.
are declared in the header file @file{stdio.h}.
@pindex stdio.h
-@comment stdio.h
-@comment ISO
@deftypefun {long int} ftell (FILE *@var{stream})
+@standards{ISO, stdio.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function returns the current file position of the stream
@var{stream}.
@code{-1} is returned.
@end deftypefun
-@comment stdio.h
-@comment Unix98
@deftypefun off_t ftello (FILE *@var{stream})
+@standards{Unix98, stdio.h}
+@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
LFS interface transparently replaces the old interface.
@end deftypefun
-@comment stdio.h
-@comment Unix98
@deftypefun off64_t ftello64 (FILE *@var{stream})
+@standards{Unix98, stdio.h}
+@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 @math{2^31}
+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
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})
+@standards{ISO, stdio.h}
+@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
place in the file.
@end deftypefun
-@comment stdio.h
-@comment Unix98
@deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence})
+@standards{Unix98, stdio.h}
+@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.
available since its functionality is (if different at all) closer the
underlying definition.
-The functionality and return value is the same as for @code{fseek}.
+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.
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})
+@standards{Unix98, stdio.h}
+@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
-@math{2^31} bytes limit might fail.
+@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}
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
+@standards{ISO, stdio.h}
This is an integer constant which, when used as the @var{whence}
-argument to the @code{fseek} or @code{fseeko} function, specifies that
+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
+@standards{ISO, stdio.h}
This is an integer constant which, when used as the @var{whence}
-argument to the @code{fseek} or @code{fseeko} function, specifies that
+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
+@standards{ISO, stdio.h}
This is an integer constant which, when used as the @var{whence}
-argument to the @code{fseek} or @code{fseeko} function, specifies that
+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})
+@standards{ISO, stdio.h}
+@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
sake of compatibility with older BSD systems. They are defined in two
different header files: @file{fcntl.h} and @file{sys/file.h}.
-@table @code
-@comment sys/file.h
-@comment BSD
+@vtable @code
@item L_SET
-@vindex L_SET
+@standards{BSD, sys/file.h}
An alias for @code{SEEK_SET}.
-@comment sys/file.h
-@comment BSD
@item L_INCR
-@vindex L_INCR
+@standards{BSD, sys/file.h}
An alias for @code{SEEK_CUR}.
-@comment sys/file.h
-@comment BSD
@item L_XTND
-@vindex L_XTND
+@standards{BSD, sys/file.h}
An alias for @code{SEEK_END}.
-@end table
+@end vtable
@node Portable Positioning
@section Portable File-Position Functions
These symbols are declared in the header file @file{stdio.h}.
@pindex stdio.h
-@comment stdio.h
-@comment ISO
@deftp {Data Type} fpos_t
+@standards{ISO, stdio.h}
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}.
interface transparently replaces the old interface.
@end deftp
-@comment stdio.h
-@comment Unix98
@deftp {Data Type} fpos64_t
+@standards{Unix98, stdio.h}
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}.
representation.
@end deftp
-@comment stdio.h
-@comment ISO
@deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
+@standards{ISO, stdio.h}
+@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
interface transparently replaces the old interface.
@end deftypefun
-@comment stdio.h
-@comment Unix98
@deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position})
+@standards{Unix98, stdio.h}
+@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.
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})
+@standards{ISO, stdio.h}
+@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}
interface transparently replaces the old interface.
@end deftypefun
-@comment stdio.h
-@comment Unix98
@deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position})
+@standards{Unix98, stdio.h}
+@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.
@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})
+@standards{ISO, stdio.h}
+@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
otherwise.
@end deftypefun
-@comment stdio.h
-@comment POSIX
@deftypefun int fflush_unlocked (FILE *@var{stream})
+@standards{POSIX, stdio.h}
+@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
always available in @theglibc{} in some form but never officially
exported.
-@comment stdio_ext.h
-@comment GNU
@deftypefun void _flushlbf (void)
+@standards{GNU, stdio_ext.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{_flushlbf} function flushes all line buffered streams
currently opened.
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})
+@standards{GNU, stdio_ext.h}
+@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 the cleared.
+underlying storage) and the buffer is cleared.
This function is declared in @file{stdio_ext.h}.
@end deftypefun
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})
+@standards{ISO, stdio.h}
+@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
be honored.
@end deftypefun
-@comment stdio.h
-@comment ISO
@deftypevr Macro int _IOFBF
+@standards{ISO, stdio.h}
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
+@standards{ISO, stdio.h}
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
+@standards{ISO, stdio.h}
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
+@standards{ISO, stdio.h}
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}.
efficient size.
@end deftypevr
-@comment stdio.h
-@comment ISO
@deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
+@standards{ISO, stdio.h}
+@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}
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})
+@standards{BSD, stdio.h}
+@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}.
@code{setvbuf} instead.
@end deftypefun
-@comment stdio.h
-@comment BSD
@deftypefun void setlinebuf (FILE *@var{stream})
+@standards{BSD, stdio.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function makes @var{stream} be line buffered, and allocates the
buffer for you.
using a non-standard function introduced in Solaris and available in
@theglibc{}.
-@comment stdio_ext.h
-@comment GNU
@deftypefun int __flbf (FILE *@var{stream})
+@standards{GNU, stdio_ext.h}
+@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.
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})
+@standards{GNU, stdio_ext.h}
+@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})
+@standards{GNU, stdio_ext.h}
+@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 stream the measuring unit is wide characters. This
+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.
@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})
+@standards{GNU, stdio.h}
+@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.
Got r
@end smallexample
-@comment stdio.h
-@comment GNU
@deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
+@standards{GNU, stdio.h}
+@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
These facilities are declared in @file{stdio.h}.
@pindex stdio.h
-@comment stdio.h
-@comment GNU
@deftp {Data Type} {cookie_io_functions_t}
+@standards{GNU, stdio.h}
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:
@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})
+@standards{GNU, stdio.h}
+@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};
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
+@deftp {Data Type} cookie_read_function_t
+@standards{GNU, stdio.h}
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
+@deftp {Data Type} cookie_write_function_t
+@standards{GNU, stdio.h}
The data type of the write function for a custom stream.
@end deftp
-@comment stdio.h
-@comment GNU
-@deftp {Data Type} cookie_seek_function
+@deftp {Data Type} cookie_seek_function_t
+@standards{GNU, stdio.h}
The data type of the seek function for a custom stream.
@end deftp
-@comment stdio.h
-@comment GNU
-@deftp {Data Type} cookie_close_function
+@deftp {Data Type} cookie_close_function_t
+@standards{GNU, stdio.h}
The data type of the close function for a custom stream.
@end deftp
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})
+@standards{XPG, fmtmsg.h}
+@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
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
@node Example
@subsection How to use @code{fmtmsg} and @code{addseverity}
-Here is a simple example program to illustrate the use of the both
+Here is a simple example program to illustrate the use of both
functions described in this section.
@smallexample
@end smallexample
We see the different fields of the message and how the extra glue (the
-colons and the @code{TO FIX} string) are printed. But only one of 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
projects / thirdparty / glibc.git / blobdiff