From 10de4a47ef3f481592e3c62eb07bcda23e9fde4d Mon Sep 17 00:00:00 2001 From: Arjun Shankar Date: Mon, 29 Jul 2024 14:30:59 +0200 Subject: [PATCH] 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 --- 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.43.5