1 files changed, 73 insertions, 24 deletions
diff --git a/manual/stdio.texi b/manual/stdio.texi
index f5e289d58a..8590ae955a 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -330,6 +330,14 @@ this ability, so using @code{freopen} is more portable.
 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
 32 bit machine this function is in fact @code{freopen64} since the LFS
 interface replaces transparently the old interface.
+
+@Theglibc{} only supports use of @code{freopen} on streams opened with
+@code{fopen} or @code{fopen64} and on the original values of the
+standard streams @code{stdin}, @code{stdout}, and @code{stderr}; such
+a stream may be reopened multiple times with @code{freopen}.  If it is
+called on another kind of stream (opened with functions such as
+@code{popen}, @code{fmemopen}, @code{open_memstream}, and
+@code{fopencookie}), @code{freopen} fails and returns a null pointer.
 @end deftypefun
 
 @deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
@@ -903,21 +911,17 @@ This function is a GNU extension.
 @deftypefun int putc (int @var{c}, FILE *@var{stream})
 @standards{ISO, stdio.h}
 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
-This is just like @code{fputc}, except that most systems implement it as
-a macro, making it faster.  One consequence is that it may evaluate the
-@var{stream} argument more than once, which is an exception to the
-general rule for macros.  @code{putc} is usually the best function to
-use for writing a single character.
+This is just like @code{fputc}, except that it may be implemented as
+a macro and may evaluate the @var{stream} argument more than once.
+Therefore, @var{stream} should never be an expression with side-effects.
 @end deftypefun
 
 @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream})
 @standards{ISO, wchar.h}
 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
-This is just like @code{fputwc}, except that it can be implement as
-a macro, making it faster.  One consequence is that it may evaluate the
-@var{stream} argument more than once, which is an exception to the
-general rule for macros.  @code{putwc} is usually the best function to
-use for writing a single wide character.
+This is just like @code{fputwc}, except that it may be implemented as
+a macro and may evaluate the @var{stream} argument more than once.
+Therefore, @var{stream} should never be an expression with side-effects.
 @end deftypefun
 
 @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})
@@ -1110,20 +1114,17 @@ This function is a GNU extension.
 @deftypefun int getc (FILE *@var{stream})
 @standards{ISO, stdio.h}
 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
-This is just like @code{fgetc}, except that it is permissible (and
-typical) for it to be implemented as a macro that evaluates the
-@var{stream} argument more than once.  @code{getc} is often highly
-optimized, so it is usually the best function to use to read a single
-character.
+This is just like @code{fgetc}, except that it may be implemented as
+a macro and may evaluate the @var{stream} argument more than once.
+Therefore, @var{stream} should never be an expression with side-effects.
 @end deftypefun
 
 @deftypefun wint_t getwc (FILE *@var{stream})
 @standards{ISO, wchar.h}
 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
-This is just like @code{fgetwc}, except that it is permissible for it to
-be implemented as a macro that evaluates the @var{stream} argument more
-than once.  @code{getwc} can be highly optimized, so it is usually the
-best function to use to read a single wide character.
+This is just like @code{fgetwc}, except that it may be implemented as
+a macro and may evaluate the @var{stream} argument more than once.
+Therefore, @var{stream} should never be an expression with side-effects.
 @end deftypefun
 
 @deftypefun int getc_unlocked (FILE *@var{stream})
@@ -1474,11 +1475,9 @@ program; usually @code{ungetc} is used only to unread a character that
 was just read from the same stream.  @Theglibc{} supports this
 even on files opened in binary mode, but other systems might not.
 
-@Theglibc{} only supports one character of pushback---in other
-words, it does not work to call @code{ungetc} twice without doing input
-in between.  Other systems might let you push back multiple characters;
-then reading from the stream retrieves the characters in the reverse
-order that they were pushed.
+@Theglibc{} supports pushing back multiple characters; subsequently
+reading from the stream retrieves the characters in the reverse order
+that they were pushed.
 
 Pushing back characters doesn't alter the file; only the internal
 buffering for the stream is affected.  If a file positioning function
@@ -2363,6 +2362,29 @@ the easiest way to make sure you have all the right prototypes is to
 just include @file{stdio.h}.
 @pindex stdio.h
 
+The @code{printf} family shares the error codes listed below.
+Individual functions may report additional @code{errno} values if they
+fail.
+
+@table @code
+@item EOVERFLOW
+The number of written bytes would have exceeded @code{INT_MAX}, and thus
+could not be represented in the return type @code{int}.
+
+@item ENOMEM
+The function could not allocate memory during processing.  Long argument
+lists and certain floating point conversions may require memory
+allocation, as does initialization of an output stream upon first use.
+
+@item EILSEQ
+POSIX specifies this error code should be used if a wide character is
+encountered that does not have a matching valid character.  @Theglibc{}
+always performs transliteration, using a replacement character if
+necessary, so this error condition cannot occur on output.  However,
+@theglibc{} uses @code{EILSEQ} to indicate that an input character
+sequence (wide or multi-byte) could not be converted successfully.
+@end table
+
 @deftypefun int printf (const char *@var{template}, @dots{})
 @standards{ISO, stdio.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
@@ -2509,6 +2531,26 @@ store the result in which case @code{-1} is returned.  This was
 changed in order to comply with the @w{ISO C99} standard.
 @end deftypefun
 
+@deftypefun dprintf (int @var{fd}, @var{template}, ...)
+@standards{POSIX, stdio.h}
+@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This function formats its arguments according to @var{template} and
+writes the result to the file descriptor @var{fd}, using the
+@code{write} function.  It returns the number of bytes written, or a
+negative value if there was an error.  In the error case, @code{errno}
+is set appropriately.  The possible @code{errno} values depend on the
+type of the file descriptor @var{fd}, in addition to the general
+@code{printf} error codes.
+
+The number of calls to @code{write} is unspecified, and some @code{write}
+calls may have happened even if @code{dprintf} returns with an error.
+
+@strong{Portability Note:} POSIX does not require that this function is
+async-signal-safe, and @theglibc{} implementation is not.  However, some
+other systems offer this function as an async-signal-safe alternative to
+@code{fprintf}.  @xref{POSIX Safety Concepts}.
+@end deftypefun
+
 @node Dynamic Output
 @subsection Dynamically Allocating Formatted Output
 
@@ -2722,6 +2764,13 @@ The @code{obstack_vprintf} function is the equivalent of
 as for @code{vprintf}.
 @end deftypefun
 
+@deftypefun int vdprintf (int @var{fd}, const char *@var{template}, va_list @var{ap})
+@standards{POSIX, stdio.h}
+@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The @code{vdprintf} is the equivalent of @code{dprintf}, but processes
+an argument list.
+@end deftypefun
+
 Here's an example showing how you might use @code{vfprintf}.  This is a
 function that prints error messages to the stream @code{stderr}, along
 with a prefix indicating the name of the program