53 lines
2.5 KiB
Diff
53 lines
2.5 KiB
Diff
|
commit b71a51189d3e1a2f515d93c0444916293bd5221f
|
||
|
|
Author: Arjun Shankar <arjun@redhat.com>
|
||
|
|
Date: Mon Jul 29 14:30:59 2024 +0200
|
||
|
|
|
||
|
|
manual/stdio: Clarify putc and putwc
|
||
|
|
|
||
|
|
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)
|
||
|
|
|
||
|
|
diff --git a/manual/stdio.texi b/manual/stdio.texi
|
||
|
|
index 002fce7a10e97107..c11d37b363385531 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})
|