doc: Document the advanced FILE stream functions

[Bruno Haible]

This patch documents the 11 advanced FILE stream functions.


2024-12-29  Bruno Haible  <bruno@clisp.org>

        doc: Document the advanced FILE stream functions.
        * doc/stdioext.texi: New file.
        * doc/gnulib.texi (Particular Modules): Include it.

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 9f6961e689..2c764d7dd3 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -8061,6 +8061,7 @@
 * Handling strings with NUL characters::
 * Container data types::
 * Modernized printf::
+* Advanced stdio functions::
 * libunistring::
 * Stack traces::
 * Recognizing Option Arguments::
@@ -8106,6 +8107,8 @@
 
 @include zprintf.texi
 
+@include stdioext.texi
+
 @include libunistring.texi
 
 @include stack-trace.texi
============================== doc/stdioext.texi ==============================
@node Advanced stdio functions
@section Advanced functions on FILE streams

@c Copyright (C) 2007-2024 Free Software Foundation, Inc.

@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3 or
@c any later version published by the Free Software Foundation; with no
@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
@c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.

@c Written by Bruno Haible.

Gnulib provides a few functions that operate on @code{FILE *} streams
and that go beyond what ISO C and POSIX specify.

Each such function is provided in a Gnulib module of the same name.

When Gnulib implemented them in 2007, some people considered them
``unportable'', because they required digging in undocumented internals
of the @code{FILE} structure.
But Gnulib made them portable, by providing implementations for all
platforms, from glibc to native Windows, and from Minix to QNX.
Nowadays, new platforms already implement them in their libc;
this has been seen for the Android libc and musl libc.

The stream argument of these functions must not be wide-character oriented.
But this is not an actual restriction, since
no programs use wide-character orientation on @code{FILE} streams anyway:
no one uses the @code{fwide} function.

@node State of a stream
@subsection Determining the state of a FILE stream

@mindex freadable
@mindex fwritable
@mindex freading
@mindex fwriting
Gnulib modules: freadable, fwritable, freading, fwriting

The @code{freadable} function returns
@code{true} if the given stream supports reading,
@code{false} if it supports only writing,
i.e. if it was opened write-only or append-only.

The @code{fwritable} function returns
@code{true} if the given stream supports writing,
@code{false} if it supports only reading.

The @code{freading} function returns
@code{true} if the given stream is opened read-only,
or if the last operation on the stream was a read operation.

The @code{fwriting} function returns
@code{true} if the given stream is opened write-only or append-only,
or if the last operation on the stream was a write operation.

@code{freading} and @code{fwriting} will never both be true
on the same stream at the same time.
If the stream supports both reads and writes, then
@itemize
@item
both @code{freading} and @code{fwriting} might be false
when the stream is first opened, after read encounters EOF,
or after @code{fflush},
@item
@code{freading} might be false or true and @code{fwriting} might be false
after repositioning (such as @code{fseek}, @code{fsetpos}, or @code{rewind}),
@end itemize
@noindent
depending on the underlying implementation.

@node Error in a stream
@subsection Setting an error in a FILE stream

A @code{FILE *} stream has an error indicator, that can be
tested through the @code{ferror} function and
cleared through the @code{clearerr} function.
The error indicator is set when an I/O operation on the stream fails.
But ISO C and POSIX don't provide a way to set the error indicator!

@mindex fseterr
The @code{fseterr} function sets the error indicator in the given stream.

@node Dropping the buffer contents
@subsection Dropping the contents of the buffers of a FILE stream

@mindex fpurge
The @code{fpurge} function drops
the contents of the input and output buffers of the given @code{FILE *} stream:
@itemize
@item
It discards the contents of the output buffer, if the stream is currently
writing.
That is the opposite of what the @code{fflush} function does.
@item
It discards the contents of the input buffer, if the stream is currently
reading.
That is the same as what the @code{fflush} function does.
@end itemize

@node Accessing the write buffer
@subsection Accessing the write buffer of a FILE stream

The following two functions provide information about the output buffer
of a @code{FILE *} stream.

@mindex fpending
The @code{fpending} function returns
the number of pending (a.k.a. buffered, unflushed) bytes in the given stream.

@mindex fbufmode
The @code{fbufmode} function returns the buffering mode of the given stream:
@multitable @columnfractions 0.5 0.5
@headitem Result @tab means
@item @code{_IONBF} @tab unbuffered
@item @code{_IOLBF} @tab line buffered
@item @code{_IOFBF} @tab fully buffered
@end multitable
@noindent
Note that on some platforms,
it is impossible to distinguish @code{_IOFBF} and @code{_IOLBF}.

@node Accessing the read buffer
@subsection Accessing the read buffer of a FILE stream

The following functions allow code to scan the contents of the input buffer
of a @code{FILE *} stream, without first copying it into a separate memory
area via @code{fread}.

@mindex freadahead
The function @code{freadahead} returns
the number of bytes waiting in the input buffer of the given stream.
This includes both
the bytes that have been read from the underlying input source
and the bytes that have been pushed back through @code{ungetc}.

@mindex freadptr
A function call @code{freadptr (@var{stream}, &@var{size})} returns
a pointer to the input buffer of the given @code{@var{stream}}, or NULL.
If the returned pointer is non-NULL,
@code{@var{size}} is set to the (positive) size of the input buffer.
If the returned pointer is NULL, you should use
@code{getc (@var{stream})},
@code{fgetc (@var{stream})},
or @code{fread (..., @var{stream})}
to access the input from @code{@var{stream}}.

@mindex freadseek
A function call @code{freadseek (@var{stream}, @var{offset})}
is the same as @code{fseek (@var{stream}, @var{offset}, SEEK_CUR)},
except that the latter does not work
on non-seekable input streams (such as pipes).