manual: Improve documentation of putc, putwc, getc, and getwc (RHEL-46741)

Resolves: RHEL-46741

glibc-RHEL-46741-1.patch

@@ -0,0 +1,50 @@
+commit 10de4a47ef3f481592e3c62eb07bcda23e9fde4d
+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>
+
+diff --git a/manual/stdio.texi b/manual/stdio.texi
+index fd7ed0cedc7c1a59..0c9a7ce4a9df4c05 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})

glibc-RHEL-46741-2.patch

@@ -0,0 +1,71 @@
+commit 942670c81dc8071dd75d6213e771daa5d2084cb6
+Author: Arjun Shankar <arjun@redhat.com>
+Date:   Tue Jul 30 11:37:57 2024 +0200
+
+    manual/stdio: Further clarify putc, putwc, getc, and getwc
+    
+    This is a follow-up to 10de4a47ef3f481592e3c62eb07bcda23e9fde4d that
+    reworded the manual entries for putc and putwc and removed any
+    performance claims.
+    
+    This commit further clarifies these entries and brings getc and getwc in
+    line with the descriptions of putc and putwc, removing any performance
+    claims from them as well.
+    Reviewed-by: Florian Weimer <fweimer@redhat.com>
+
+diff --git a/manual/stdio.texi b/manual/stdio.texi
+index 0c9a7ce4a9df4c05..567f6780011f9db1 100644
+--- a/manual/stdio.texi
++++ b/manual/stdio.texi
+@@ -904,20 +904,16 @@ This function is a GNU extension.
+ @standards{ISO, stdio.h}
+ @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+ 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.  Therefore, @var{stream} should never be an
+-expression with side-effects.
++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 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.  Therefore, @var{stream} should never be an
+-expression with side-effects.
++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 +1106,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})

glibc.spec

@@ -157,7 +157,7 @@ end \
 Summary: The GNU libc libraries
 Name: glibc
 Version: %{glibcversion}
-Release: 117%{?dist}
+Release: 118%{?dist}
 
 # In general, GPLv2+ is used by programs, LGPLv2+ is used for
 # libraries.
@@ -842,6 +842,8 @@ Patch603: glibc-RHEL-39992-2.patch
 Patch604: glibc-RHEL-30823.patch
 Patch605: glibc-RHEL-25257-1.patch
 Patch606: glibc-RHEL-25257-2.patch
+Patch607: glibc-RHEL-46741-1.patch
+Patch608: glibc-RHEL-46741-2.patch
 
 ##############################################################################
 # Continued list of core "glibc" package information:
@@ -3001,6 +3003,9 @@ update_gconv_modules_cache ()
 %endif
 
 %changelog
+* Tue Aug 06 2024 Arjun Shankar <arjun@redhat.com> - 2.34-118
+- manual: Improve documentation of putc, putwc, getc, and getwc (RHEL-46741)
+
 * Wed Jul 17 2024 DJ Delorie <dj@redhat.com> - 2.34-117
 - manual: add syscalls (RHEL-25257)