From 0ecf9bed9bedaad481f3bf24b574d742eebe53df Mon Sep 17 00:00:00 2001 From: Arjun Shankar Date: Tue, 6 Aug 2024 14:00:31 +0200 Subject: [PATCH] manual: Improve documentation of putc, putwc, getc, and getwc (RHEL-46741) Resolves: RHEL-46741 --- glibc-RHEL-46741-1.patch | 50 ++++++++++++++++++++++++++++ glibc-RHEL-46741-2.patch | 71 ++++++++++++++++++++++++++++++++++++++++ glibc.spec | 7 +++- 3 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 glibc-RHEL-46741-1.patch create mode 100644 glibc-RHEL-46741-2.patch diff --git a/glibc-RHEL-46741-1.patch b/glibc-RHEL-46741-1.patch new file mode 100644 index 0000000..c0ba98b --- /dev/null +++ b/glibc-RHEL-46741-1.patch @@ -0,0 +1,50 @@ +commit 10de4a47ef3f481592e3c62eb07bcda23e9fde4d +Author: Arjun Shankar +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 + +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}) diff --git a/glibc-RHEL-46741-2.patch b/glibc-RHEL-46741-2.patch new file mode 100644 index 0000000..cac84f0 --- /dev/null +++ b/glibc-RHEL-46741-2.patch @@ -0,0 +1,71 @@ +commit 942670c81dc8071dd75d6213e771daa5d2084cb6 +Author: Arjun Shankar +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 + +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}) diff --git a/glibc.spec b/glibc.spec index b0ee9fa..2a7a74f 100644 --- a/glibc.spec +++ b/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 - 2.34-118 +- manual: Improve documentation of putc, putwc, getc, and getwc (RHEL-46741) + * Wed Jul 17 2024 DJ Delorie - 2.34-117 - manual: add syscalls (RHEL-25257)