[COMMITTED 2.40] manual/stdio: Clarify putc and putwc

[COMMITTED 2.40] manual/stdio: Clarify putc and putwc

[Arjun Shankar]

The manual entry for `putc' described what "most systems" do instead of
describing the glibc implementation and its guarantees.  This commit
fixes that by warning that putc may be implemented as a macro that
double-evaluates `stream', and removing the performance claim.

Even though the current `putc' implementation does not double-evaluate
`stream', offering this obscure guarantee as an extension to what
POSIX allows does not seem very useful.

The entry for `putwc' is also edited to bring it in line with `putc'.
Reviewed-by: Florian Weimer <fweimer@redhat.com>

(cherry picked from commit 10de4a47ef3f481592e3c62eb07bcda23e9fde4d)
---
 manual/stdio.texi | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/manual/stdio.texi b/manual/stdio.texi
index f5e289d58a..f9529a098d 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -903,21 +903,21 @@ 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
+This is just like @code{fputc}, except that it may be implemented 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.
+general rule for macros.  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
+This is just like @code{fputwc}, except that it may be implemented 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.
+general rule for macros.  Therefore, @var{stream} should never be an
+expression with side-effects.
 @end deftypefun
 
 @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})
-- 
2.45.0