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
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
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
@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
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
@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
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
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
@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
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
@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
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.
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.
@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
@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{})
@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
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:
@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})
@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}.
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}.
@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
@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
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.
@comment ISO
@deftypevr Macro int SEEK_SET
This is an integer constant which, when used as the @var{whence}
-argument to the @code{fseek} or @code{fseeko} 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 ISO
@deftypevr Macro int SEEK_CUR
This is an integer constant which, when used as the @var{whence}
-argument to the @code{fseek} or @code{fseeko} 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 ISO
@deftypevr Macro int SEEK_END
This is an integer constant which, when used as the @var{whence}
-argument to the @code{fseek} or @code{fseeko} 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
@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
@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.
@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