@menu
* Streams:: About the data type representing a stream.
* Standard Streams:: Streams to the standard input and output
- devices are created for you.
+ devices are created for you.
* Opening Streams:: How to create a stream to talk to a file.
* Closing Streams:: Close a stream when you are finished with it.
* Streams and Threads:: Issues with streams in threaded programs.
* Block Input/Output:: Input and output operations on blocks of data.
* Formatted Output:: @code{printf} and related functions.
* Customizing Printf:: You can define new conversion specifiers for
- @code{printf} and friends.
+ @code{printf} and friends.
* Formatted Input:: @code{scanf} and related functions.
* EOF and Errors:: How you can tell if an I/O error happens.
* Error Recovery:: What you can do about errors.
* Binary Streams:: Some systems distinguish between text files
- and binary files.
+ and binary files.
* File Positioning:: About random-access streams.
* Portable Positioning:: Random access on peculiar ISO C systems.
* Stream Buffering:: How to control buffering of streams.
* Other Kinds of Streams:: Streams that do not necessarily correspond
- to an open file.
+ to an open file.
* Formatted Messages:: Print strictly formatted messages.
@end menu
@end deftypevar
@cindex standard error stream
-In the GNU system, you can specify what files or processes correspond to
+On @gnusystems{}, you can specify what files or processes correspond to
these streams using the pipe and redirection facilities provided by the
shell. (The primitives shells use to implement these facilities are
described in @ref{File System Interface}.) Most other operating systems
provide similar mechanisms, but the details of how to use them can vary.
-In the GNU C library, @code{stdin}, @code{stdout}, and @code{stderr} are
+In @theglibc{}, @code{stdin}, @code{stdout}, and @code{stderr} are
normal variables which you can set just like any others. For example,
to redirect the standard output to a file, you could do:
@comment stdio.h
@comment ISO
@deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
+@c fopen may leak the list lock if cancelled within _IO_link_in.
The @code{fopen} function opens a stream for I/O to the file
@var{filename}, and returns a pointer to the stream.
@end table
As you can see, @samp{+} requests a stream that can do both input and
-output. The ISO standard says that when using such a stream, you must
-call @code{fflush} (@pxref{Stream Buffering}) or a file positioning
-function such as @code{fseek} (@pxref{File Positioning}) when switching
-from reading to writing or vice versa. Otherwise, internal buffers
-might not be emptied properly. The GNU C library does not have this
-limitation; you can do arbitrary reading and writing operations on a
-stream in whatever order.
+output. When using such a stream, you must call @code{fflush}
+(@pxref{Stream Buffering}) or a file positioning function such as
+@code{fseek} (@pxref{File Positioning}) when switching from reading
+to writing or vice versa. Otherwise, internal buffers might not be
+emptied properly.
Additional characters may appear after these to specify flags for the
call. Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is
the only part you are guaranteed will be understood by all systems.
-The GNU C library defines one additional character for use in
-@var{opentype}: the character @samp{x} insists on creating a new
-file---if a file @var{filename} already exists, @code{fopen} fails
-rather than opening it. If you use @samp{x} you are guaranteed that
-you will not clobber an existing file. This is equivalent to the
-@code{O_EXCL} option to the @code{open} function (@pxref{Opening and
-Closing Files}).
+@Theglibc{} defines additional characters for use in @var{opentype}:
+
+@table @samp
+@item c
+The file is opened with cancellation in the I/O functions disabled.
+
+@item e
+The underlying file descriptor will be closed if you use any of the
+@code{exec@dots{}} functions (@pxref{Executing a File}). (This is
+equivalent to having set @code{FD_CLOEXEC} on that descriptor.
+@xref{Descriptor Flags}.)
+
+@item m
+The file is opened and accessed using @code{mmap}. This is only
+supported with files opened for reading.
+
+@item x
+Insist on creating a new file---if a file @var{filename} already
+exists, @code{fopen} fails rather than opening it. If you use
+@samp{x} you are guaranteed that you will not clobber an existing
+file. This is equivalent to the @code{O_EXCL} option to the
+@code{open} function (@pxref{Opening and Closing Files}).
+
+The @samp{x} modifier is part of @w{ISO C11}.
+@end table
The character @samp{b} in @var{opentype} has a standard meaning; it
requests a binary stream rather than a text stream. But this makes no
-difference in POSIX systems (including the GNU system). If both
+difference in POSIX systems (including @gnusystems{}). If both
@samp{+} and @samp{b} are specified, they can appear in either order.
@xref{Binary Streams}.
If the @var{opentype} string contains the sequence
@code{,ccs=@var{STRING}} then @var{STRING} is taken as the name of a
coded character set and @code{fopen} will mark the stream as
-wide-oriented which appropriate conversion functions in place to convert
-from and to the character set @var{STRING} is place. Any other stream
+wide-oriented with appropriate conversion functions in place to convert
+from and to the character set @var{STRING}. Any other stream
is opened initially unoriented and the orientation is decided with the
first file operation. If the first operation is a wide character
operation, the stream is not only marked as wide-oriented, also the
@comment stdio.h
@comment Unix98
@deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
This function is similar to @code{fopen} but the stream it returns a
pointer for is opened using @code{open64}. Therefore this stream can be
-used even on files larger then @math{2^31} bytes on 32 bit machines.
+used even on files larger than @math{2^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.
@comment stdio.h
@comment ISO
@deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}}
+@c Like most I/O operations, this one is guarded by a recursive lock,
+@c released even upon cancellation, but cancellation may leak file
+@c descriptors and leave the stream in an inconsistent state (e.g.,
+@c still bound to the closed descriptor). Also, if the stream is
+@c part-way through a significant update (say running freopen) when a
+@c signal handler calls freopen again on the same stream, the result is
+@c likely to be an inconsistent stream, and the possibility of closing
+@c twice file descriptor number that the stream used to use, the second
+@c time when it might have already been reused by another thread.
This function is like a combination of @code{fclose} and @code{fopen}.
It first closes the stream referred to by @var{stream}, ignoring any
errors that are detected in the process. (Because errors are ignored,
@code{freopen} has traditionally been used to connect a standard stream
such as @code{stdin} with a file of your own choice. This is useful in
programs in which use of a standard stream for certain purposes is
-hard-coded. In the GNU C library, you can simply close the standard
+hard-coded. In @theglibc{}, you can simply close the standard
streams and open new ones with @code{fopen}. But other systems lack
this ability, so using @code{freopen} is more portable.
@comment stdio.h
@comment Unix98
@deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}}
This function is similar to @code{freopen}. The only difference is that
on 32 bit machine the stream returned is able to read beyond the
@math{2^31} bytes limits imposed by the normal interface. It should be
available for reading or writing. This information is normally not
available and would have to be remembered separately. Solaris
introduced a few functions to get this information from the stream
-descriptor and these functions are also available in the GNU C library.
+descriptor and these functions are also available in @theglibc{}.
@comment stdio_ext.h
@comment GNU
@deftypefun int __freadable (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{__freadable} function determines whether the stream
@var{stream} was opened to allow reading. In this case the return value
is nonzero. For write-only streams the function returns zero.
@comment stdio_ext.h
@comment GNU
@deftypefun int __fwritable (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{__fwritable} function determines whether the stream
@var{stream} was opened to allow writing. In this case the return value
is nonzero. For read-only streams the function returns zero.
@comment stdio_ext.h
@comment GNU
@deftypefun int __freading (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{__freading} function determines whether the stream
@var{stream} was last read from or whether it is opened read-only. In
this case the return value is nonzero, otherwise it is zero.
@comment stdio_ext.h
@comment GNU
@deftypefun int __fwriting (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{__fwriting} function determines whether the stream
@var{stream} was last written to or whether it is opened write-only. In
this case the return value is nonzero, otherwise it is zero.
@comment stdio.h
@comment ISO
@deftypefun int fclose (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c After fclose, it is undefined behavior to use the stream it points
+@c to. Therefore, one must only call fclose when the stream is
+@c otherwise unused. Concurrent uses started before will complete
+@c successfully because of the lock, which makes it MT-Safe. Calling it
+@c from a signal handler is perfectly safe if the stream is known to be
+@c no longer used, which is a precondition for fclose to be safe in the
+@c first place; since this is no further requirement, fclose is safe for
+@c use in async signals too. After calling fclose, you can no longer
+@c use the stream, not even to fclose it again, so its memory and file
+@c descriptor may leak if fclose is canceled before @c releasing them.
+@c That the stream must be unused and it becomes unused after the call
+@c is what would enable fclose to be AS- and AC-Safe while freopen
+@c isn't. However, because of the possibility of leaving __gconv_lock
+@c taken upon cancellation, AC-Safety is lost.
This function causes @var{stream} to be closed and the connection to
the corresponding file to be broken. Any buffered output is written
and any buffered input is discarded. The @code{fclose} function returns
The function @code{fclose} is declared in @file{stdio.h}.
@end deftypefun
-To close all streams currently available the GNU C Library provides
+To close all streams currently available @theglibc{} provides
another function.
@comment stdio.h
@comment GNU
@deftypefun int fcloseall (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:streams}}@asunsafe{}@acsafe{}}
+@c Like fclose, using any previously-opened streams after fcloseall is
+@c undefined. However, the implementation of fcloseall isn't equivalent
+@c to calling fclose for all streams: it just flushes and unbuffers all
+@c streams, without any locking. It's the flushing without locking that
+@c makes it unsafe.
This function causes all open streams of the process to be closed and
the connection to corresponding files to be broken. All buffered data
is written and any buffered input is discarded. The @code{fcloseall}
@cindex multi-threaded application
Streams can be used in multi-threaded applications in the same way they
are used in single-threaded applications. But the programmer must be
-aware of a the possible complications. It is important to know about
+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
requirements added by multi-threaded programming.
@comment stdio.h
@comment POSIX
@deftypefun void flockfile (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
+@c There's no way to tell whether the lock was acquired before or after
+@c cancellation so as to unlock only when appropriate.
The @code{flockfile} function acquires the internal locking object
associated with the stream @var{stream}. This ensures that no other
thread can explicitly through @code{flockfile}/@code{ftrylockfile} or
@comment stdio.h
@comment POSIX
@deftypefun int ftrylockfile (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
The @code{ftrylockfile} function tries to acquire the internal locking
object associated with the stream @var{stream} just like
@code{flockfile}. But unlike @code{flockfile} this function does not
@comment stdio.h
@comment POSIX
@deftypefun void funlockfile (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
The @code{funlockfile} function releases the internal locking object of
the stream @var{stream}. The stream must have been locked before by a
call to @code{flockfile} or a successful call of @code{ftrylockfile}.
There are two basic mechanisms to avoid locking. The first is to use
the @code{_unlocked} variants of the stream operations. The POSIX
-standard defines quite a few of those and the GNU library adds a few
+standard defines quite a few of those and @theglibc{} adds a few
more. These variants of the functions behave just like the functions
with the name without the suffix except that they do not lock the
stream. Using these functions is very desirable since they are
introduction of threads) were implemented as macros which are very fast
if the buffer is not empty. With the addition of locking requirements
these functions are no longer implemented as macros since they would
-would expand to too much code.
+expand to too much code.
But these macros are still available with the same functionality under the new
names @code{putc_unlocked} and @code{getc_unlocked}. This possibly huge
difference of speed also suggests the use of the @code{_unlocked}
manipulation of the buffer of the stream.
A second way to avoid locking is by using a non-standard function which
-was introduced in Solaris and is available in the GNU C library as well.
+was introduced in Solaris and is available in @theglibc{} as well.
@comment stdio_ext.h
@comment GNU
@deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asulock{}}@acsafe{}}
+@c Changing the implicit-locking status of a stream while it's in use by
+@c another thread may cause a lock to be implicitly acquired and not
+@c released, or vice-versa. This function should probably hold the lock
+@c while changing this setting, to make sure we don't change it while
+@c there are any concurrent uses. Meanwhile, callers should acquire the
+@c lock themselves to be safe, and even concurrent uses with external
+@c locking will be fine, as long as functions that require external
+@c locking are not called without holding locks.
The @code{__fsetlocking} function can be used to select whether the
stream operations will implicitly acquire the locking object of the
@comment wchar.h
@comment ISO
@deftypefun int fwide (FILE *@var{stream}, int @var{mode})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{}}}
+@c Querying is always safe, but changing the stream when it's in use
+@c upthread may be problematic. Like most lock-acquiring functions,
+@c this one may leak the lock if canceled.
The @code{fwide} function can be used to set and query the state of the
orientation of the stream @var{stream}. If the @var{mode} parameter has
@comment stdio.h
@comment ISO
@deftypefun int fputc (int @var{c}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+@c If the stream is in use when interrupted by a signal, the recursive
+@c lock won't help ensure the stream is consistent; indeed, if fputc
+@c gets a signal precisely before the post-incremented _IO_write_ptr
+@c value is stored, we may overwrite the interrupted write. Conversely,
+@c depending on compiler optimizations, the incremented _IO_write_ptr
+@c may be stored before the character is stored in the buffer,
+@c corrupting the stream if async cancel hits between the two stores.
+@c There may be other reasons for AS- and AC-unsafety in the overflow
+@c cases.
The @code{fputc} function converts the character @var{c} to type
@code{unsigned char}, and writes it to the stream @var{stream}.
@code{EOF} is returned if a write error occurs; otherwise the
@comment wchar.h
@comment ISO
@deftypefun wint_t fputwc (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
The @code{fputwc} function writes the wide character @var{wc} to the
stream @var{stream}. @code{WEOF} is returned if a write error occurs;
otherwise the character @var{wc} is returned.
@comment stdio.h
@comment POSIX
@deftypefun int fputc_unlocked (int @var{c}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+@c The unlocked functions can't possibly satisfy the MT-Safety
+@c requirements on their own, because they require external locking for
+@c safety.
The @code{fputc_unlocked} function is equivalent to the @code{fputc}
function except that it does not implicitly lock the stream.
@end deftypefun
@comment wchar.h
@comment POSIX
-@deftypefun wint_t fputwc_unlocked (wint_t @var{wc}, FILE *@var{stream})
+@deftypefun wint_t fputwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{fputwc_unlocked} function is equivalent to the @code{fputwc}
function except that it does not implicitly lock the stream.
@comment stdio.h
@comment ISO
@deftypefun int putc (int @var{c}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
This is just like @code{fputc}, except that most systems implement it as
a macro, making it faster. One consequence is that it may evaluate the
@var{stream} argument more than once, which is an exception to the
@comment wchar.h
@comment ISO
@deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
This is just like @code{fputwc}, except that it can be implement as
a macro, making it faster. One consequence is that it may evaluate the
@var{stream} argument more than once, which is an exception to the
@comment stdio.h
@comment POSIX
@deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{putc_unlocked} function is equivalent to the @code{putc}
function except that it does not implicitly lock the stream.
@end deftypefun
@comment wchar.h
@comment GNU
@deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{putwc_unlocked} function is equivalent to the @code{putwc}
function except that it does not implicitly lock the stream.
@comment stdio.h
@comment ISO
@deftypefun int putchar (int @var{c})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
The @code{putchar} function is equivalent to @code{putc} with
@code{stdout} as the value of the @var{stream} argument.
@end deftypefun
@comment wchar.h
@comment ISO
@deftypefun wint_t putwchar (wchar_t @var{wc})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
The @code{putwchar} function is equivalent to @code{putwc} with
@code{stdout} as the value of the @var{stream} argument.
@end deftypefun
@comment stdio.h
@comment POSIX
@deftypefun int putchar_unlocked (int @var{c})
+@safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{putchar_unlocked} function is equivalent to the @code{putchar}
function except that it does not implicitly lock the stream.
@end deftypefun
@comment wchar.h
@comment GNU
@deftypefun wint_t putwchar_unlocked (wchar_t @var{wc})
+@safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{putwchar_unlocked} function is equivalent to the @code{putwchar}
function except that it does not implicitly lock the stream.
@comment stdio.h
@comment ISO
@deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
The function @code{fputs} writes the string @var{s} to the stream
@var{stream}. The terminating null character is not written.
This function does @emph{not} add a newline character, either.
@comment wchar.h
@comment ISO
@deftypefun int fputws (const wchar_t *@var{ws}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
The function @code{fputws} writes the wide character string @var{ws} to
the stream @var{stream}. The terminating null character is not written.
This function does @emph{not} add a newline character, either. It
@comment stdio.h
@comment GNU
@deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{fputs_unlocked} function is equivalent to the @code{fputs}
function except that it does not implicitly lock the stream.
@comment wchar.h
@comment GNU
@deftypefun int fputws_unlocked (const wchar_t *@var{ws}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{fputws_unlocked} function is equivalent to the @code{fputws}
function except that it does not implicitly lock the stream.
@comment stdio.h
@comment ISO
@deftypefun int puts (const char *@var{s})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{puts} function writes the string @var{s} to the stream
@code{stdout} followed by a newline. The terminating null character of
the string is not written. (Note that @code{fputs} does @emph{not}
@comment stdio.h
@comment SVID
@deftypefun int putw (int @var{w}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function writes the word @var{w} (that is, an @code{int}) to
@var{stream}. It is provided for compatibility with SVID, but we
recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
@comment stdio.h
@comment ISO
@deftypefun int fgetc (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+@c Same caveats as fputc, but instead of losing a write in case of async
+@c signals, we may read the same character more than once, and the
+@c stream may be left in odd states due to cancellation in the underflow
+@c cases.
This function reads the next character as an @code{unsigned char} from
the stream @var{stream} and returns its value, converted to an
@code{int}. If an end-of-file condition or read error occurs,
@comment wchar.h
@comment ISO
@deftypefun wint_t fgetwc (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function reads the next wide character from the stream @var{stream}
and returns its value. If an end-of-file condition or read error
occurs, @code{WEOF} is returned instead.
@comment stdio.h
@comment POSIX
@deftypefun int fgetc_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{fgetc_unlocked} function is equivalent to the @code{fgetc}
function except that it does not implicitly lock the stream.
@end deftypefun
@comment wchar.h
@comment GNU
@deftypefun wint_t fgetwc_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc}
function except that it does not implicitly lock the stream.
@comment stdio.h
@comment ISO
@deftypefun int getc (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This is just like @code{fgetc}, except that it is permissible (and
typical) for it to be implemented as a macro that evaluates the
@var{stream} argument more than once. @code{getc} is often highly
@comment wchar.h
@comment ISO
@deftypefun wint_t getwc (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This is just like @code{fgetwc}, except that it is permissible for it to
be implemented as a macro that evaluates the @var{stream} argument more
than once. @code{getwc} can be highly optimized, so it is usually the
@comment stdio.h
@comment POSIX
@deftypefun int getc_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{getc_unlocked} function is equivalent to the @code{getc}
function except that it does not implicitly lock the stream.
@end deftypefun
@comment wchar.h
@comment GNU
@deftypefun wint_t getwc_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{getwc_unlocked} function is equivalent to the @code{getwc}
function except that it does not implicitly lock the stream.
@comment stdio.h
@comment ISO
@deftypefun int getchar (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
as the value of the @var{stream} argument.
@end deftypefun
@comment wchar.h
@comment ISO
@deftypefun wint_t getwchar (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin}
as the value of the @var{stream} argument.
@end deftypefun
@comment stdio.h
@comment POSIX
@deftypefun int getchar_unlocked (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{getchar_unlocked} function is equivalent to the @code{getchar}
function except that it does not implicitly lock the stream.
@end deftypefun
@comment wchar.h
@comment GNU
@deftypefun wint_t getwchar_unlocked (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{getwchar_unlocked} function is equivalent to the @code{getwchar}
function except that it does not implicitly lock the stream.
/* @r{Write a space to separate answer from question.} */
fputc (' ', stdout);
/* @r{Read the first character of the line.}
- @r{This should be the answer character, but might not be.} */
+ @r{This should be the answer character, but might not be.} */
c = tolower (fgetc (stdin));
answer = c;
/* @r{Discard rest of input line.} */
while (c != '\n' && c != EOF)
- c = fgetc (stdin);
+ c = fgetc (stdin);
/* @r{Obey the answer if it was valid.} */
if (answer == 'y')
- return 1;
+ return 1;
if (answer == 'n')
- return 0;
+ return 0;
/* @r{Answer was invalid: ask for valid answer.} */
fputs ("Please answer y or n:", stdout);
@}
@comment stdio.h
@comment SVID
@deftypefun int getw (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function reads a word (that is, an @code{int}) from @var{stream}.
It's provided for compatibility with SVID. We recommend you use
@code{fread} instead (@pxref{Block Input/Output}). Unlike @code{getc},
Standard C has functions to do this, but they aren't very safe: null
characters and even (for @code{gets}) long lines can confuse them. So
-the GNU library provides the nonstandard @code{getline} function that
+@theglibc{} provides the nonstandard @code{getline} function that
makes it easy to read lines reliably.
Another GNU extension, @code{getdelim}, generalizes @code{getline}. It
@comment stdio.h
@comment GNU
@deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
+@c Besides the usual possibility of getting an inconsistent stream in a
+@c signal handler or leaving it inconsistent in case of cancellation,
+@c the possibility of leaving a dangling pointer upon cancellation
+@c between reallocing the buffer at *lineptr and updating the pointer
+@c brings about another case of @acucorrupt.
This function reads an entire line from @var{stream}, storing the text
(including the newline and a terminating null character) in a buffer
and storing the buffer address in @code{*@var{lineptr}}.
@comment stdio.h
@comment GNU
@deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
+@c See the getline @acucorrupt note.
This function is like @code{getline} except that the character which
tells it to stop reading is not necessarily newline. The argument
@var{delimiter} specifies the delimiter character; @code{getdelim} keeps
@comment stdio.h
@comment ISO
@deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{fgets} function reads characters from the stream @var{stream}
up to and including a newline character and stores them in the string
@var{s}, adding a null character to mark the end of the string. You
@comment wchar.h
@comment ISO
@deftypefun {wchar_t *} fgetws (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{fgetws} function reads wide characters from the stream
@var{stream} up to and including a newline character and stores them in
the string @var{ws}, adding a null wide character to mark the end of the
@comment stdio.h
@comment GNU
@deftypefun {char *} fgets_unlocked (char *@var{s}, int @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{fgets_unlocked} function is equivalent to the @code{fgets}
function except that it does not implicitly lock the stream.
@comment wchar.h
@comment GNU
@deftypefun {wchar_t *} fgetws_unlocked (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{fgetws_unlocked} function is equivalent to the @code{fgetws}
function except that it does not implicitly lock the stream.
@comment stdio.h
@comment ISO
@deftypefn {Deprecated function} {char *} gets (char *@var{s})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The function @code{gets} reads characters from the stream @code{stdin}
up to the next newline character, and stores them in the string @var{s}.
The newline character is discarded (note that this differs from the
@strong{Warning:} The @code{gets} function is @strong{very dangerous}
because it provides no protection against overflowing the string
-@var{s}. The GNU library includes it for compatibility only. You
+@var{s}. @Theglibc{} includes it for compatibility only. You
should @strong{always} use @code{fgets} or @code{getline} instead. To
remind you of this, the linker (if using GNU @code{ld}) will issue a
warning whenever you use @code{gets}.
@smallexample
f o o b a r
- ^
+ ^
@end smallexample
@noindent
@smallexample
f o o b a r
- |
+ |
o--
^
@end smallexample
@smallexample
f o o b a r
- |
+ |
9--
^
@end smallexample
@comment stdio.h
@comment ISO
@deftypefun int ungetc (int @var{c}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{ungetc} function pushes back the character @var{c} onto the
input stream @var{stream}. So the next input from @var{stream} will
read @var{c} before anything else.
necessary to actually read any characters from the stream before
unreading them with @code{ungetc}! But that is a strange way to write a
program; usually @code{ungetc} is used only to unread a character that
-was just read from the same stream. The GNU C library supports this
+was just read from the same stream. @Theglibc{} supports this
even on files opened in binary mode, but other systems might not.
-The GNU C library only supports one character of pushback---in other
+@Theglibc{} only supports one character of pushback---in other
words, it does not work to call @code{ungetc} twice without doing input
in between. Other systems might let you push back multiple characters;
then reading from the stream retrieves the characters in the reverse
@comment wchar.h
@comment ISO
@deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{ungetwc} function behaves just like @code{ungetc} just that it
pushes back a wide character.
@end deftypefun
@comment stdio.h
@comment ISO
@deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function reads up to @var{count} objects of size @var{size} into
the array @var{data}, from the stream @var{stream}. It returns the
number of objects actually read, which might be less than @var{count} if
@comment stdio.h
@comment GNU
@deftypefun size_t fread_unlocked (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{fread_unlocked} function is equivalent to the @code{fread}
function except that it does not implicitly lock the stream.
@comment stdio.h
@comment ISO
@deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function writes up to @var{count} objects of size @var{size} from
the array @var{data}, to the stream @var{stream}. The return value is
normally @var{count}, if the call succeeds. Any other value indicates
@comment stdio.h
@comment GNU
@deftypefun size_t fwrite_unlocked (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{fwrite_unlocked} function is equivalent to the @code{fwrite}
function except that it does not implicitly lock the stream.
@menu
* Formatted Output Basics:: Some examples to get you started.
* Output Conversion Syntax:: General syntax of conversion
- specifications.
+ specifications.
* Table of Output Conversions:: Summary of output conversions and
- what they do.
+ what they do.
* Integer Conversions:: Details about formatting of integers.
* Floating-Point Conversions:: Details about formatting of
- floating-point numbers.
+ floating-point numbers.
* Other Output Conversions:: Details about formatting of strings,
- characters, pointers, and the like.
+ characters, pointers, and the like.
* Formatted Output Functions:: Descriptions of the actual functions.
* Dynamic Output:: Functions that allocate memory for the output.
* Variable Arguments Output:: @code{vprintf} and friends.
* Parsing a Template String:: What kinds of args does a given template
- call for?
+ call for?
* Example of Parsing:: Sample program using @code{parse_printf_format}.
@end menu
int pct = 37;
char filename[] = "foo.txt";
printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
- filename, pct);
+ filename, pct);
@end smallexample
@noindent
@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}
-systems. The GNU C library has no real limit.
+systems. @Theglibc{} has no real limit.
@end defvr
If any of the formats has a specification for the parameter position all
The @samp{%g} and @samp{%G} conversions print the argument in the style
of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
than -4 or greater than or equal to the precision; otherwise they use
-the @samp{%f} style. A precision of @code{0}, is taken as 1. is
+the @samp{%f} style. A precision of @code{0}, is taken as 1.
Trailing zeros are removed from the fractional portion of the result and
a decimal-point character appears only if it is followed by a digit.
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 you accidentally pass a null pointer as the argument for a @samp{%s}
-conversion, the GNU library prints it as @samp{(null)}. We think this
+conversion, @theglibc{} prints it as @samp{(null)}. We think this
is more useful than crashing. But it's not good practice to pass a null
argument intentionally.
@end smallexample
@noindent
-The @samp{%m} conversion is a GNU C library extension.
+The @samp{%m} conversion is a @glibcadj{} extension.
The @samp{%p} conversion prints a pointer value. The corresponding
argument must be of type @code{void *}. In practice, you can use any
type of pointer.
-In the GNU system, non-null pointers are printed as unsigned integers,
+In @theglibc{}, non-null pointers are printed as unsigned integers,
as if a @samp{%#x} conversion were used. Null pointers print as
@samp{(nil)}. (Pointers might print differently in other systems.)
@comment stdio.h
@comment ISO
@deftypefun int printf (const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
The @code{printf} function prints the optional arguments under the
control of the template string @var{template} to the stream
@code{stdout}. It returns the number of characters printed, or a
@comment wchar.h
@comment ISO
@deftypefun int wprintf (const wchar_t *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
The @code{wprintf} function prints the optional arguments under the
control of the wide template string @var{template} to the stream
@code{stdout}. It returns the number of wide characters printed, or a
@comment stdio.h
@comment ISO
@deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
This function is just like @code{printf}, except that the output is
written to the stream @var{stream} instead of @code{stdout}.
@end deftypefun
@comment wchar.h
@comment ISO
@deftypefun int fwprintf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
This function is just like @code{wprintf}, except that the output is
written to the stream @var{stream} instead of @code{stdout}.
@end deftypefun
@comment stdio.h
@comment ISO
@deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
This is like @code{printf}, except that the output is stored in the character
array @var{s} instead of written to a stream. A null character is written
to mark the end of the string.
@comment wchar.h
@comment GNU
@deftypefun int swprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
This is like @code{wprintf}, except that the output is stored in the
wide character array @var{ws} instead of written to a stream. A null
wide character is written to mark the end of the string. The @var{size}
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{})
+@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
/* @r{Try to print in the allocated space.} */
nchars = snprintf (buffer, size, "value of %s is %s",
- name, value);
+ name, value);
@end group
@group
if (nchars >= size)
@{
/* @r{Reallocate buffer now that we know
- how much space is needed.} */
+ how much space is needed.} */
size = nchars + 1;
buffer = (char *) xrealloc (buffer, size);
if (buffer != NULL)
- /* @r{Try again.} */
- snprintf (buffer, size, "value of %s is %s",
- name, value);
+ /* @r{Try again.} */
+ snprintf (buffer, size, "value of %s is %s",
+ name, value);
@}
/* @r{The last call worked, return the string.} */
return buffer;
In practice, it is often easier just to use @code{asprintf}, below.
-@strong{Attention:} In versions of the GNU C library prior to 2.1 the
+@strong{Attention:} In versions of @theglibc{} prior to 2.1 the
return value is the number of characters stored, not including the
terminating null; unless there was not enough space in @var{s} to
store the result in which case @code{-1} is returned. This was
@comment stdio.h
@comment GNU
@deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
This function is similar to @code{sprintf}, except that it dynamically
allocates a string (as with @code{malloc}; @pxref{Unconstrained
Allocation}) to hold the output, instead of putting the output in a
@comment stdio.h
@comment GNU
@deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
This function is similar to @code{asprintf}, except that it uses the
obstack @var{obstack} to allocate the space. @xref{Obstacks}.
@smallexample
#define myprintf(a, b, c, d, e, rest...) \
- printf (mytemplate , ## rest)
+ printf (mytemplate , ## rest)
@end smallexample
@noindent
-@xref{Macro Varargs, , Macros with Variable Numbers of Arguments,
-gcc.info, Using GNU CC}, for details. But this is limited to macros,
-and does not apply to real functions at all.
+@xref{Variadic Macros,,, cpp, The C preprocessor}, for details.
+But this is limited to macros, and does not apply to real functions at all.
Before calling @code{vprintf} or the other functions listed in this
section, you @emph{must} call @code{va_start} (@pxref{Variadic
@comment stdio.h
@comment ISO
@deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
This function is similar to @code{printf} except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer @var{ap}.
@comment wchar.h
@comment ISO
@deftypefun int vwprintf (const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
This function is similar to @code{wprintf} except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer @var{ap}.
@comment stdio.h
@comment ISO
@deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c Although vfprintf sets up a cleanup region to release the lock on the
+@c output stream, it doesn't use it to release args_value or string in
+@c case of cancellation. This doesn't make it unsafe, but cancelling it
+@c may leak memory. The unguarded use of __printf_function_table is
+@c also of concern for all callers.
+@c _itoa ok
+@c _udiv_qrnnd_preinv ok
+@c group_number ok
+@c _i18n_number_rewrite
+@c __wctrans ok
+@c __towctrans @mtslocale
+@c __wcrtomb ok? dup below
+@c outdigit_value ok
+@c outdigitwc_value ok
+@c outchar ok
+@c outstring ok
+@c PAD ok
+@c __printf_fp @mtslocale @ascuheap @acsmem
+@c __printf_fphex @mtslocale
+@c __readonly_area
+@c [GNU/Linux] fopen, strtoul, free
+@c __strerror_r ok if no translation, check otherwise
+@c __btowc ? gconv-modules
+@c __wcrtomb ok (not using internal state) gconv-modules
+@c ARGCHECK
+@c UNBUFFERED_P (tested before taking the stream lock)
+@c buffered_vfprintf ok
+@c __find_spec(wc|mb)
+@c read_int
+@c __libc_use_alloca
+@c process_arg
+@c process_string_arg
+@c extend_alloca
+@c __parse_one_spec(wc|mb)
+@c *__printf_arginfo_table unguarded
+@c __printf_va_arg_table-> unguarded
+@c *__printf_function_table unguarded
+@c done_add
+@c printf_unknown
+@c outchar
+@c _itoa_word
This is the equivalent of @code{fprintf} with the variable argument list
specified directly as for @code{vprintf}.
@end deftypefun
@comment wchar.h
@comment ISO
@deftypefun int vfwprintf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
This is the equivalent of @code{fwprintf} with the variable argument list
specified directly as for @code{vwprintf}.
@end deftypefun
@comment stdio.h
@comment ISO
@deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
This is the equivalent of @code{sprintf} with the variable argument list
specified directly as for @code{vprintf}.
@end deftypefun
@comment wchar.h
@comment GNU
@deftypefun int vswprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
This is the equivalent of @code{swprintf} with the variable argument list
specified directly as for @code{vwprintf}.
@end deftypefun
@comment stdio.h
@comment GNU
@deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
This is the equivalent of @code{snprintf} with the variable argument list
specified directly as for @code{vprintf}.
@end deftypefun
@comment stdio.h
@comment GNU
@deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
The @code{vasprintf} function is the equivalent of @code{asprintf} with the
variable argument list specified directly as for @code{vprintf}.
@end deftypefun
@comment stdio.h
@comment GNU
@deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c The obstack is not guarded by mutexes, it might be at an inconsistent
+@c state within a signal handler, and it could be left at an
+@c inconsistent state in case of cancellation.
The @code{obstack_vprintf} function is the equivalent of
@code{obstack_printf} with the variable argument list specified directly
as for @code{vprintf}.@refill
@smallexample
void eprintf (const char *template, ...)
- __attribute__ ((format (printf, 1, 2)));
+ __attribute__ ((format (printf, 1, 2)));
@end smallexample
@noindent
@comment printf.h
@comment GNU
@deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
This function returns information about the number and types of
arguments expected by the @code{printf} template string @var{template}.
The information is stored in the array @var{argtypes}; each element of
int wanted;
if (argtypes[i] & PA_FLAG_PTR)
- wanted = STRUCTURE;
+ wanted = STRUCTURE;
else
- switch (argtypes[i] & ~PA_FLAG_MASK)
- @{
- case PA_INT:
- case PA_FLOAT:
- case PA_DOUBLE:
- wanted = NUMBER;
- break;
- case PA_CHAR:
- wanted = CHAR;
- break;
- case PA_STRING:
- wanted = STRING;
- break;
- case PA_POINTER:
- wanted = STRUCTURE;
- break;
- @}
+ switch (argtypes[i] & ~PA_FLAG_MASK)
+ @{
+ case PA_INT:
+ case PA_FLOAT:
+ case PA_DOUBLE:
+ wanted = NUMBER;
+ break;
+ case PA_CHAR:
+ wanted = CHAR;
+ break;
+ case PA_STRING:
+ wanted = STRING;
+ break;
+ case PA_POINTER:
+ wanted = STRUCTURE;
+ break;
+ @}
if (TYPE (args[i]) != wanted)
- @{
- error ("type mismatch for arg number %d", i);
- return 0;
- @}
+ @{
+ error ("type mismatch for arg number %d", i);
+ return 0;
+ @}
@}
return 1;
@}
@cindex defining new @code{printf} conversions
@cindex extending @code{printf}
-The GNU C library lets you define your own custom conversion specifiers
+@Theglibc{} lets you define your own custom conversion specifiers
for @code{printf} template strings, to teach @code{printf} clever ways
to print the important data structures of your program.
@menu
* Registering New Conversions:: Using @code{register_printf_function}
- to register a new output conversion.
+ to register a new output conversion.
* Conversion Specifier Options:: The handler must be able to get
- the options specified in the
- template when it is called.
+ the options specified in the
+ template when it is called.
* Defining the Output Handler:: Defining the handler and arginfo
- functions that are passed as arguments
- to @code{register_printf_function}.
+ functions that are passed as arguments
+ to @code{register_printf_function}.
* Printf Extension Example:: How to define a @code{printf}
- handler function.
+ handler function.
* Predefined Printf Handlers:: Predefined @code{printf} handlers.
@end menu
@comment printf.h
@comment GNU
@deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function})
+@safety{@prelim{}@mtunsafe{@mtasuconst{:printfext}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
+@c This function is guarded by the global non-recursive libc lock, but
+@c users of the variables it sets aren't, and those should be MT-Safe,
+@c so we're ruling out the use of this extension with threads. Calling
+@c it from a signal handler may self-deadlock, and cancellation may
+@c leave the lock held, besides leaking allocated memory.
This function defines the conversion specifier character @var{spec}.
Thus, if @var{spec} is @code{'Y'}, it defines the conversion @samp{%Y}.
You can redefine the built-in conversions like @samp{%s}, but flag
@c but if you are never going to call @code{parse_printf_format}, you do
@c not need to define an arginfo function.
-@strong{Attention:} In the GNU C library versions before 2.0 the
+@strong{Attention:} In @theglibc{} versions before 2.0 the
@var{arginfo-function} function did not need to be installed unless
the user used the @code{parse_printf_format} function. This has changed.
Now a call to any of the @code{printf} functions will call this
Now let's look at how to define the handler and arginfo functions
which are passed as arguments to @code{register_printf_function}.
-@strong{Compatibility Note:} The interface changed in GNU libc
+@strong{Compatibility Note:} The interface changed in @theglibc{}
version 2.0. Previously the third argument was of type
@code{va_list *}.
@smallexample
int @var{function} (FILE *stream, const struct printf_info *info,
- const void *const *args)
+ const void *const *args)
@end smallexample
The @var{stream} argument passed to the handler function is the stream to
@smallexample
int @var{function} (const struct printf_info *info,
- size_t n, int *argtypes)
+ size_t n, int *argtypes)
@end smallexample
The return value from the function should be the number of arguments the
@node Predefined Printf Handlers
@subsection Predefined @code{printf} Handlers
-The GNU libc also contains a concrete and useful application of the
+@Theglibc{} also contains a concrete and useful application of the
@code{printf} handler extension. There are two functions available
which implement a special way to print floating-point numbers.
@comment printf.h
@comment GNU
@deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args})
+@safety{@prelim{}@mtsafe{@mtsrace{:fp} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @acucorrupt{}}}
+@c This is meant to be called by vfprintf, that should hold the lock on
+@c the stream, but if this function is called directly, output will be
+@c racy, besides the uses of the global locale object while other
+@c threads may be changing it and the possbility of leaving the stream
+@c object in an inconsistent state in case of cancellation.
Print a given floating point number as for the format @code{%f} except
that there is a postfix character indicating the divisor for the
number to make this less than 1000. There are two possible divisors:
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)
@comment printf.h
@comment GNU
@deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function will return in @var{argtypes} the information about the
used parameters in the way the @code{vfprintf} implementation expects
it. The format always takes one argument.
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
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
char *variable, *value;
if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
- &variable, &value))
+ &variable, &value))
@{
invalid_input_error ();
return 0;
@comment stdio.h
@comment ISO
@deftypefun int scanf (const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
The @code{scanf} function reads formatted input from the stream
@code{stdin} under the control of the template string @var{template}.
The optional arguments are pointers to the places which receive the
@comment wchar.h
@comment ISO
@deftypefun int wscanf (const wchar_t *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
The @code{wscanf} function reads formatted input from the stream
@code{stdin} under the control of the template string @var{template}.
The optional arguments are pointers to the places which receive the
@comment stdio.h
@comment ISO
@deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
This function is just like @code{scanf}, except that the input is read
from the stream @var{stream} instead of @code{stdin}.
@end deftypefun
@comment wchar.h
@comment ISO
@deftypefun int fwscanf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
This function is just like @code{wscanf}, except that the input is read
from the stream @var{stream} instead of @code{stdin}.
@end deftypefun
@comment stdio.h
@comment ISO
@deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
This is like @code{scanf}, except that the characters are taken from the
null-terminated string @var{s} instead of from a stream. Reaching the
end of the string is treated as an end-of-file condition.
@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{})
+@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.
@comment stdio.h
@comment ISO
@deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
This function is similar to @code{scanf}, but instead of taking
a variable number of arguments directly, it takes an argument list
pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
@comment wchar.h
@comment ISO
@deftypefun int vwscanf (const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
This function is similar to @code{wscanf}, but instead of taking
a variable number of arguments directly, it takes an argument list
pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
@comment stdio.h
@comment ISO
@deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
This is the equivalent of @code{fscanf} with the variable argument list
specified directly as for @code{vscanf}.
@end deftypefun
@comment wchar.h
@comment ISO
@deftypefun int vfwscanf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
This is the equivalent of @code{fwscanf} with the variable argument list
specified directly as for @code{vwscanf}.
@end deftypefun
@comment stdio.h
@comment ISO
@deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
This is the equivalent of @code{sscanf} with the variable argument list
specified directly as for @code{vscanf}.
@end deftypefun
@comment wchar.h
@comment ISO
@deftypefun int vswscanf (const wchar_t *@var{s}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
This is the equivalent of @code{swscanf} with the variable argument list
specified directly as for @code{vwscanf}.
@end deftypefun
know that a function uses a @code{scanf}-style format string. Then it
can check the number and types of arguments in each call to the
function, and warn you when they do not match the format string.
-For details, @xref{Function Attributes, , Declaring Attributes of Functions,
+For details, see @ref{Function Attributes, , Declaring Attributes of Functions,
gcc.info, Using GNU CC}.
@node EOF and Errors
@deftypevr Macro int EOF
This macro is an integer value that is returned by a number of narrow
stream functions to indicate an end-of-file condition, or some other
-error situation. With the GNU library, @code{EOF} is @code{-1}. In
+error situation. With @theglibc{}, @code{EOF} is @code{-1}. In
other libraries, its value may be some other negative number.
This symbol is declared in @file{stdio.h}.
@deftypevr Macro int WEOF
This macro is an integer value that is returned by a number of wide
stream functions to indicate an end-of-file condition, or some other
-error situation. With the GNU library, @code{WEOF} is @code{-1}. In
+error situation. With @theglibc{}, @code{WEOF} is @code{-1}. In
other libraries, its value may be some other negative number.
This symbol is declared in @file{wchar.h}.
@comment stdio.h
@comment ISO
@deftypefun int feof (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
The @code{feof} function returns nonzero if and only if the end-of-file
indicator for the stream @var{stream} is set.
@comment stdio.h
@comment GNU
@deftypefun int feof_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c There isn't much of a thread unsafety risk in reading a flag word and
+@c testing a bit in it.
The @code{feof_unlocked} function is equivalent to the @code{feof}
function except that it does not implicitly lock the stream.
@comment stdio.h
@comment ISO
@deftypefun int ferror (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
The @code{ferror} function returns nonzero if and only if the error
indicator for the stream @var{stream} is set, indicating that an error
has occurred on a previous operation on the stream.
@comment stdio.h
@comment GNU
@deftypefun int ferror_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{ferror_unlocked} function is equivalent to the @code{ferror}
function except that it does not implicitly lock the stream.
@comment stdio.h
@comment ISO
@deftypefun void clearerr (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
This function clears the end-of-file and error indicators for the
stream @var{stream}.
@comment stdio.h
@comment GNU
@deftypefun void clearerr_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@assafe{}@acsafe{}}
The @code{clearerr_unlocked} function is equivalent to the @code{clearerr}
function except that it does not implicitly lock the stream.
@node Binary Streams
@section Text and Binary Streams
-The GNU system and other POSIX-compatible operating systems organize all
+@gnusystems{} and other POSIX-compatible operating systems organize all
files as uniform sequences of characters. However, some other systems
make a distinction between files containing text and files containing
binary data, and the input and output facilities of @w{ISO C} provide for
only way to read or write ``an ordinary file of text'' that can work
with other text-oriented programs is through a text stream.
-In the GNU library, and on all POSIX systems, there is no difference
+In @theglibc{}, and on all POSIX systems, there is no difference
between text streams and binary streams. When you open a stream, you
get the same kind of stream regardless of whether you ask for binary.
This stream can handle any file content, and has none of the
The @dfn{file position} of a stream describes where in the file the
stream is currently reading or writing. I/O on the stream advances the
-file position through the file. In the GNU system, the file position is
+file position through the file. On @gnusystems{}, the file position is
represented as an integer, which counts the number of bytes from the
beginning of the file. @xref{File Position}.
@comment stdio.h
@comment ISO
@deftypefun {long int} ftell (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function returns the current file position of the stream
@var{stream}.
@comment stdio.h
@comment Unix98
@deftypefun off_t ftello (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{ftello} function is similar to @code{ftell}, except that it
returns a value of type @code{off_t}. Systems which support this type
use it to describe all file positions, unlike the POSIX specification
@comment stdio.h
@comment Unix98
@deftypefun off64_t ftello64 (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function is similar to @code{ftello} with the only difference that
the return value is of type @code{off64_t}. This also requires that the
stream @var{stream} was opened using either @code{fopen64},
@comment stdio.h
@comment ISO
@deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{fseek} function is used to change the file position of the
stream @var{stream}. The value of @var{whence} must be one of the
constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
@comment stdio.h
@comment Unix98
@deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function is similar to @code{fseek} but it corrects a problem with
@code{fseek} in a system with POSIX types. Using a value of type
@code{long int} for the offset is not compatible with POSIX.
@comment stdio.h
@comment Unix98
@deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function is similar to @code{fseeko} with the only difference that
the @var{offset} parameter is of type @code{off64_t}. This also
requires that the stream @var{stream} was opened using either
@comment stdio.h
@comment ISO
@deftypefun void rewind (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{rewind} function positions the stream @var{stream} at the
beginning of the file. It is equivalent to calling @code{fseek} or
@code{fseeko} on the @var{stream} with an @var{offset} argument of
@node Portable Positioning
@section Portable File-Position Functions
-On the GNU system, the file position is truly a character count. You
+On @gnusystems{}, the file position is truly a character count. You
can specify any character count value as an argument to @code{fseek} or
@code{fseeko} and get reliable results for any random access file.
However, some @w{ISO C} systems do not represent file positions in this
@item
In a call to @code{fseek} or @code{fseeko} on a text stream, either the
@var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and
-and the @var{offset} must be the result of an earlier call to @code{ftell}
+the @var{offset} must be the result of an earlier call to @code{ftell}
on the same stream.
@item
file position of a stream, for use by the functions @code{fgetpos} and
@code{fsetpos}.
-In the GNU system, @code{fpos_t} is an opaque data structure that
+In @theglibc{}, @code{fpos_t} is an opaque data structure that
contains internal data to represent file offset and conversion state
information. In other systems, it might have a different internal
representation.
file position of a stream, for use by the functions @code{fgetpos64} and
@code{fsetpos64}.
-In the GNU system, @code{fpos64_t} is an opaque data structure that
+In @theglibc{}, @code{fpos64_t} is an opaque data structure that
contains internal data to represent file offset and conversion state
information. In other systems, it might have a different internal
representation.
@comment stdio.h
@comment ISO
@deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function stores the value of the file position indicator for the
stream @var{stream} in the @code{fpos_t} object pointed to by
@var{position}. If successful, @code{fgetpos} returns zero; otherwise
@comment stdio.h
@comment Unix98
@deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function is similar to @code{fgetpos} but the file position is
returned in a variable of type @code{fpos64_t} to which @var{position}
points.
@comment stdio.h
@comment ISO
@deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function sets the file position indicator for the stream @var{stream}
to the position @var{position}, which must have been set by a previous
call to @code{fgetpos} on the same stream. If successful, @code{fsetpos}
@comment stdio.h
@comment Unix98
@deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function is similar to @code{fsetpos} but the file position used
for positioning is provided in a variable of type @code{fpos64_t} to
which @var{position} points.
@comment stdio.h
@comment ISO
@deftypefun int fflush (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function causes any buffered output on @var{stream} to be delivered
to the file. If @var{stream} is a null pointer, then
@code{fflush} causes buffered output on @emph{all} open output streams
@comment stdio.h
@comment POSIX
@deftypefun int fflush_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{fflush_unlocked} function is equivalent to the @code{fflush}
function except that it does not implicitly lock the stream.
@end deftypefun
required and the program wants to be sure that all output is visible on
the terminal. But this means that only line buffered streams have to be
flushed. Solaris introduced a function especially for this. It was
-always available in the GNU C library in some form but never officially
+always available in @theglibc{} in some form but never officially
exported.
@comment stdio_ext.h
@comment GNU
@deftypefun void _flushlbf (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
The @code{_flushlbf} function flushes all line buffered streams
currently opened.
been known to be so thoroughly fixated on line-oriented input and output
that flushing a line buffered stream causes a newline to be written!
Fortunately, this ``feature'' seems to be becoming less common. You do
-not need to worry about this in the GNU system.
+not need to worry about this with @theglibc{}.
In some situations it might be useful to not flush the output pending
for a stream but instead simply forget it. If transmission is costly
and the output is not needed anymore this is valid reasoning. In this
situation a non-standard function introduced in Solaris and available in
-the GNU C library can be used.
+@theglibc{} can be used.
@comment stdio_ext.h
@comment GNU
@deftypefun void __fpurge (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
The @code{__fpurge} function causes the buffer of the stream
@var{stream} to be emptied. If the stream is currently in read mode all
input in the buffer is lost. If the stream is in output mode the
@comment stdio.h
@comment ISO
@deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function is used to specify that the stream @var{stream} should
have the buffering mode @var{mode}, which can be either @code{_IOFBF}
(for full buffering), @code{_IOLBF} (for line buffering), or
@comment stdio.h
@comment ISO
@deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
If @var{buf} is a null pointer, the effect of this function is
equivalent to calling @code{setvbuf} with a @var{mode} argument of
@code{_IONBF}. Otherwise, it is equivalent to calling @code{setvbuf}
@comment stdio.h
@comment BSD
@deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
buffer. The @var{size} argument specifies the length of @var{buf}.
@comment stdio.h
@comment BSD
@deftypefun void setlinebuf (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
This function makes @var{stream} be line buffered, and allocates the
buffer for you.
@end deftypefun
It is possible to query whether a given stream is line buffered or not
-using a non-standard function introduced in Solaris and available in the
-GNU C library.
+using a non-standard function introduced in Solaris and available in
+@theglibc{}.
@comment stdio_ext.h
@comment GNU
@deftypefun int __flbf (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{__flbf} function will return a nonzero value in case the
stream @var{stream} is line buffered. Otherwise the return value is
zero.
@comment stdio_ext.h
@comment GNU
@deftypefun size_t __fbufsize (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}}
The @code{__fbufsize} function return the size of the buffer in the
stream @var{stream}. This value can be used to optimize the use of the
stream.
@comment stdio_ext.h
@comment GNU
-@deftypefun size_t __fpending (FILE *@var{stream}) The @code{__fpending}
+@deftypefun size_t __fpending (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}}
+The @code{__fpending}
function returns the number of bytes currently in the output buffer.
For wide-oriented stream the measuring unit is wide characters. This
function should not be used on buffers in read mode or opened read-only.
@node Other Kinds of Streams
@section Other Kinds of Streams
-The GNU library provides ways for you to define additional kinds of
+@Theglibc{} provides ways for you to define additional kinds of
streams that do not necessarily correspond to an open file.
One such type of stream takes input from or writes output to a string.
@menu
* String Streams:: Streams that get data from or put data in
- a string or memory buffer.
-* Obstack Streams:: Streams that store data in an obstack.
+ a string or memory buffer.
* Custom Streams:: Defining your own streams with an arbitrary
- input data source and/or output data sink.
+ input data source and/or output data sink.
@end menu
@node String Streams
@comment stdio.h
@comment GNU
@deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
+@c Unlike open_memstream, fmemopen does (indirectly) call _IO_link_in,
+@c bringing with it additional potential for async trouble with
+@c list_all_lock.
This function opens a stream that allows the access specified by the
@var{opentype} argument, that reads from or writes to the buffer specified
by the argument @var{buf}. This array must be at least @var{size} bytes long.
@comment stdio.h
@comment GNU
@deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
This function opens a stream for writing to a buffer. The buffer is
allocated dynamically and grown as necessary, using @code{malloc}.
After you've closed the stream, this buffer is your responsibility to
buf = `hello, world', size = 12
@end smallexample
-@c @group Invalid outside @example.
-@node Obstack Streams
-@subsection Obstack Streams
-
-You can open an output stream that puts it data in an obstack.
-@xref{Obstacks}.
-
-@comment stdio.h
-@comment GNU
-@deftypefun {FILE *} open_obstack_stream (struct obstack *@var{obstack})
-This function opens a stream for writing data into the obstack @var{obstack}.
-This starts an object in the obstack and makes it grow as data is
-written (@pxref{Growing Objects}).
-@c @end group Doubly invalid because not nested right.
-
-Calling @code{fflush} on this stream updates the current size of the
-object to match the amount of data that has been written. After a call
-to @code{fflush}, you can examine the object temporarily.
-
-You can move the file position of an obstack stream with @code{fseek} or
-@code{fseeko} (@pxref{File Positioning}). Moving the file position past
-the end of the data written fills the intervening space with zeros.
-
-To make the object permanent, update the obstack with @code{fflush}, and
-then use @code{obstack_finish} to finalize the object and get its address.
-The following write to the stream starts a new object in the obstack,
-and later writes add to that object until you do another @code{fflush}
-and @code{obstack_finish}.
-
-But how do you find out how long the object is? You can get the length
-in bytes by calling @code{obstack_object_size} (@pxref{Status of an
-Obstack}), or you can null-terminate the object like this:
-
-@smallexample
-obstack_1grow (@var{obstack}, 0);
-@end smallexample
-
-Whichever one you do, you must do it @emph{before} calling
-@code{obstack_finish}. (You can do both if you wish.)
-@end deftypefun
-
-Here is a sample function that uses @code{open_obstack_stream}:
-
-@smallexample
-char *
-make_message_string (const char *a, int b)
-@{
- FILE *stream = open_obstack_stream (&message_obstack);
- output_task (stream);
- fprintf (stream, ": ");
- fprintf (stream, a, b);
- fprintf (stream, "\n");
- fclose (stream);
- obstack_1grow (&message_obstack, 0);
- return obstack_finish (&message_obstack);
-@}
-@end smallexample
-
@node Custom Streams
@subsection Programming Your Own Custom Streams
@cindex custom streams
@menu
* Streams and Cookies:: The @dfn{cookie} records where to fetch or
- store data that is read or written.
+ store data that is read or written.
* Hook Functions:: How you should define the four @dfn{hook
- functions} that a custom stream needs.
+ functions} that a custom stream needs.
@end menu
@node Streams and Cookies
@comment stdio.h
@comment GNU
@deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
This function actually creates the stream for communicating with the
@var{cookie} using the functions in the @var{io-functions} argument.
The @var{opentype} argument is interpreted as for @code{fopen};
This is very similar to the @code{write} function; see @ref{I/O
Primitives}. Your function should transfer up to @var{size} bytes from
the buffer, and return the number of bytes written. You can return a
-value of @code{-1} to indicate an error.
+value of @code{0} to indicate an error. You must not return any
+negative value.
You should define the function to perform seek operations on the cookie
as:
@comment fmtmsg.h
@comment XPG
@deftypefun int fmtmsg (long int @var{classification}, const char *@var{label}, int @var{severity}, const char *@var{text}, const char *@var{action}, const char *@var{tag})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acsafe{}}
Display a message described by its parameters on the device(s) specified
in the @var{classification} parameter. The @var{label} parameter
identifies the source of the message. The string should consist of two
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
git.samba.org / jlayton / glibc.git / blobdiff