diff mbox series

manual/stdio: Clarify putc and putwc

Message ID 20240729114034.50894-1-arjun@redhat.com
State New
Headers show
Series manual/stdio: Clarify putc and putwc | expand

Commit Message

Arjun Shankar July 29, 2024, 11:40 a.m. UTC 
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'.

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'.
---
 manual/stdio.texi | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

Comments

Florian Weimer July 29, 2024, 12:09 p.m. UTC | #1 
* Arjun Shankar:

> diff --git a/manual/stdio.texi b/manual/stdio.texi
> index f5e289d58a..c3066114d2 100644
> --- a/manual/stdio.texi
> +++ b/manual/stdio.texi
> @@ -903,21 +903,23 @@ 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.  @code{putc} is usually the best function
> +to use for writing a single character.
>  @end deftypefun

I would drop the performance claim.  On glibc, there is no difference
(and we should merge the two implementations we have of the same
function).

Thanks,
Florian
diff mbox series

Patch

diff --git a/manual/stdio.texi b/manual/stdio.texi
index f5e289d58a..c3066114d2 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -903,21 +903,23 @@  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.  @code{putc} is usually the best function
+to use for writing a single character.
 @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.  @code{putwc} is usually the best function
+to use for writing a single wide character.
 @end deftypefun
 
 @deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})