manual: Improve documentation of putc, putwc, getc, and getwc (RHEL-46741)
Resolves: RHEL-46741
This commit is contained in:
Arjun Shankar
parent
21ce8318ac
commit
0ecf9bed9b
50
glibc-RHEL-46741-1.patch
Normal file
50
glibc-RHEL-46741-1.patch
Normal file
@ -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})
|
||||
71
glibc-RHEL-46741-2.patch
Normal file
71
glibc-RHEL-46741-2.patch
Normal file
@ -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})
|
||||
@ -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)
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user