From 24908a1e2c07d45b87c8a24e12972a4de6fc02e8 Mon Sep 17 00:00:00 2001 From: Florian Weimer Date: Tue, 3 Jun 2025 11:59:56 +0200 Subject: [PATCH] manual: Document the clock_nanosleep function (RHEL-57671) Resolves: RHEL-57671 --- glibc-RHEL-57671-1.patch | 23 ++++++++ glibc-RHEL-57671-2.patch | 121 +++++++++++++++++++++++++++++++++++++++ glibc-RHEL-57671-3.patch | 74 ++++++++++++++++++++++++ glibc.spec | 8 ++- 4 files changed, 225 insertions(+), 1 deletion(-) create mode 100644 glibc-RHEL-57671-1.patch create mode 100644 glibc-RHEL-57671-2.patch create mode 100644 glibc-RHEL-57671-3.patch diff --git a/glibc-RHEL-57671-1.patch b/glibc-RHEL-57671-1.patch new file mode 100644 index 0000000..f5c66a8 --- /dev/null +++ b/glibc-RHEL-57671-1.patch @@ -0,0 +1,23 @@ +commit 9a743032cd59c59167bf615d8ab4acc96b2bf47e +Author: Maciej W. Rozycki +Date: Fri May 30 15:01:51 2025 +0100 + + manual: Fix invalid 'illegal' usage with 'nanosleep' + + The GNU Coding Standards demand that 'illegal' only be used to refer to + activities prohibited by law. Replace it with 'invalid' accordingly in + the description of the EINVAL error condition for 'nanosleep'. + +diff --git a/manual/time.texi b/manual/time.texi +index 8e072c7e375a750e..6b2d133f8e3080f3 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -3212,7 +3212,7 @@ elapsed time. + + @item EINVAL + The nanosecond value in the @var{requested_time} parameter contains an +-illegal value. Either the value is negative or greater than or equal to ++invalid value. Either the value is negative or greater than or equal to + 1000 million. + @end table + diff --git a/glibc-RHEL-57671-2.patch b/glibc-RHEL-57671-2.patch new file mode 100644 index 0000000..ff06259 --- /dev/null +++ b/glibc-RHEL-57671-2.patch @@ -0,0 +1,121 @@ +commit 1a3d8f2201d4d613401ce5be9a283f4f28c43093 +Author: Arjun Shankar +Date: Fri May 30 02:09:50 2025 +0200 + + manual: Document clock_nanosleep + + Make minor clarifications in the documentation for 'nanosleep' and add + an entry for 'clock_nanosleep' as a generalized variant of the former + function that allows clock selection. + Reviewed-by: Maciej W. Rozycki + +diff --git a/manual/time.texi b/manual/time.texi +index 6b2d133f8e3080f3..2df54a1b28c72ffe 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -3179,12 +3179,12 @@ On @gnusystems{}, it is safe to use @code{sleep} and @code{SIGALRM} in + the same program, because @code{sleep} does not work by means of + @code{SIGALRM}. + +-@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining}) ++@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining_time}) + @standards{POSIX.1, time.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + @c On Linux, it's a syscall. On Mach, it calls gettimeofday and uses + @c ports. +-If resolution to seconds is not enough the @code{nanosleep} function can ++If resolution to seconds is not enough, the @code{nanosleep} function can + be used. As the name suggests the sleep interval can be specified in + nanoseconds. The actual elapsed time of the sleep interval might be + longer since the system rounds the elapsed time you request up to the +@@ -3193,21 +3193,22 @@ next integer multiple of the actual resolution the system can deliver. + @code{*@var{requested_time}} is the elapsed time of the interval you + want to sleep. + +-The function returns as @code{*@var{remaining}} the elapsed time left +-in the interval for which you requested to sleep. If the interval +-completed without getting interrupted by a signal, this is zero. ++If @var{remaining_time} is not the null pointer, the function returns as ++@code{*@var{remaining_time}} the elapsed time left in the interval for which ++you requested to sleep. If the interval completed without getting ++interrupted by a signal, this is zero. + + @code{struct timespec} is described in @ref{Time Types}. + +-If the function returns because the interval is over the return value is +-zero. If the function returns @math{-1} the global variable @code{errno} ++If the function returns because the interval is over, the return value is ++zero. If the function returns @math{-1}, the global variable @code{errno} + is set to the following values: + + @table @code + @item EINTR + The call was interrupted because a signal was delivered to the thread. +-If the @var{remaining} parameter is not the null pointer the structure +-pointed to by @var{remaining} is updated to contain the remaining ++If the @var{remaining_time} parameter is not the null pointer, the structure ++pointed to by @var{remaining_time} is updated to contain the remaining + elapsed time. + + @item EINVAL +@@ -3219,10 +3220,58 @@ invalid value. Either the value is negative or greater than or equal to + This function is a cancellation point in multi-threaded programs. This + is a problem if the thread allocates some resources (like memory, file + descriptors, semaphores or whatever) at the time @code{nanosleep} is +-called. If the thread gets canceled these resources stay allocated +-until the program ends. To avoid this calls to @code{nanosleep} should ++called. If the thread gets canceled, these resources stay allocated ++until the program ends. To avoid this, calls to @code{nanosleep} should + be protected using cancellation handlers. + @c ref pthread_cleanup_push / pthread_cleanup_pop + + The @code{nanosleep} function is declared in @file{time.h}. + @end deftypefun ++ ++@deftypefun int clock_nanosleep (clockid_t @var{clock}, int @var{flags}, const struct timespec *@var{requested_time}, struct timespec *@var{remaining_time}) ++@standards{POSIX.1-2001, time.h} ++@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} ++This function is a generalized variant of @code{nanosleep}, providing the ++caller with a way to specify the clock to be used to measure elapsed time ++and express the sleep interval in absolute or relative terms. The call: ++ ++@smallexample ++nanosleep (@var{requested_time}, @var{remaining_time}) ++@end smallexample ++ ++is equivalent to: ++ ++@smallexample ++clock_nanosleep (CLOCK_REALTIME, 0, @var{requested_time}, @var{remaining_time}) ++@end smallexample ++ ++The @var{clock} argument specifies the clock to use. ++@xref{Getting the Time}, for the @code{clockid_t} type and possible values ++of @var{clock}. Not all clocks listed are supported for use with ++@code{clock_nanosleep}. For details, see the manual page ++@manpageurl{clock_nanosleep,2}. ++ ++The @var{flags} argument is either @code{0} or @code{TIMER_ABSTIME}. If ++@var{flags} is @code{0}, then @code{clock_nanosleep} interprets ++@var{requested_time} as an interval relative to the current time specified ++by @var{clock}. If it is @code{TIMER_ABSTIME} instead, @var{requested_time} ++specifies an absolute time measured by @var{clock}; if at the time of the ++call the value requested is less than or equal to the clock specified, then ++the function returns right away. When @var{flags} is @code{TIMER_ABSTIME}, ++@var{remaining_time} is not updated. ++ ++The return values and error conditions for @code{clock_nanosleep} are the ++same as for @code{nanosleep}, with the following conditions additionally ++defined: ++ ++@table @code ++@item EINVAL ++The @var{clock} argument is not a valid clock. ++ ++@item EOPNOTSUPP ++The @var{clock} argument is not supported by the kernel for ++@code{clock_nanosleep}. ++@end table ++ ++The @code{clock_nanosleep} function is declared in @file{time.h}. ++@end deftypefun diff --git a/glibc-RHEL-57671-3.patch b/glibc-RHEL-57671-3.patch new file mode 100644 index 0000000..e833d69 --- /dev/null +++ b/glibc-RHEL-57671-3.patch @@ -0,0 +1,74 @@ +commit 591283a68965fe61a7186c9c81f7812e71b282b4 +Author: Arjun Shankar +Date: Mon Jun 2 10:41:02 2025 +0200 + + manual: Correct return value description of 'clock_nanosleep' + + Commit 1a3d8f2201d4d613401ce5be9a283f4f28c43093 incorrectly described + 'clock_nanosleep' as having the same return values as 'nanosleep'. Fix + this, clarifying that 'clock_nanosleep' returns a positive error number + upon failure instead of setting 'errno'. Also clarify that 'nanosleep' + returns '-1' upon error. + + Fixes: 1a3d8f2201d4d613401ce5be9a283f4f28c43093 + Reported-by: Mark Harris + Reviewed-by: Mark Harris + +diff --git a/manual/time.texi b/manual/time.texi +index 2df54a1b28c72ffe..2db0cf0bd8167161 100644 +--- a/manual/time.texi ++++ b/manual/time.texi +@@ -3200,9 +3200,9 @@ interrupted by a signal, this is zero. + + @code{struct timespec} is described in @ref{Time Types}. + +-If the function returns because the interval is over, the return value is +-zero. If the function returns @math{-1}, the global variable @code{errno} +-is set to the following values: ++If the function returns because the interval is over, it returns zero. ++Otherwise it returns @math{-1} and sets the global variable @code{errno} to ++one of the following values: + + @table @code + @item EINTR +@@ -3231,19 +3231,14 @@ The @code{nanosleep} function is declared in @file{time.h}. + @deftypefun int clock_nanosleep (clockid_t @var{clock}, int @var{flags}, const struct timespec *@var{requested_time}, struct timespec *@var{remaining_time}) + @standards{POSIX.1-2001, time.h} + @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +-This function is a generalized variant of @code{nanosleep}, providing the +-caller with a way to specify the clock to be used to measure elapsed time +-and express the sleep interval in absolute or relative terms. The call: +- +-@smallexample +-nanosleep (@var{requested_time}, @var{remaining_time}) +-@end smallexample +- +-is equivalent to: +- +-@smallexample +-clock_nanosleep (CLOCK_REALTIME, 0, @var{requested_time}, @var{remaining_time}) +-@end smallexample ++This function is similar to @code{nanosleep} while additionally providing ++the caller with a way to specify the clock to be used to measure elapsed ++time and express the sleep interval in absolute or relative terms. It ++returns zero when returning because the interval is over, and a positive ++error number corresponding to the error encountered otherwise. This is ++different from @code{nanosleep}, which returns @math{-1} upon failure and ++sets the global variable @code{errno} according to the error encountered ++instead. + + The @var{clock} argument specifies the clock to use. + @xref{Getting the Time}, for the @code{clockid_t} type and possible values +@@ -3260,9 +3255,9 @@ call the value requested is less than or equal to the clock specified, then + the function returns right away. When @var{flags} is @code{TIMER_ABSTIME}, + @var{remaining_time} is not updated. + +-The return values and error conditions for @code{clock_nanosleep} are the +-same as for @code{nanosleep}, with the following conditions additionally +-defined: ++The @code{clock_nanosleep} function returns error codes as positive return ++values. The error conditions for @code{clock_nanosleep} are the same as for ++@code{nanosleep}, with the following conditions additionally defined: + + @table @code + @item EINVAL diff --git a/glibc.spec b/glibc.spec index 9f392fb..3b9a2dd 100644 --- a/glibc.spec +++ b/glibc.spec @@ -157,7 +157,7 @@ end \ Summary: The GNU libc libraries Name: glibc Version: %{glibcversion} -Release: 199%{?dist} +Release: 200%{?dist} # In general, GPLv2+ is used by programs, LGPLv2+ is used for # libraries. @@ -1221,6 +1221,9 @@ Patch912: glibc-RHEL-72017-2.patch Patch913: glibc-RHEL-72017-3.patch Patch914: glibc-RHEL-72017-4.patch Patch915: glibc-RHEL-72017-5.patch +Patch916: glibc-RHEL-57671-1.patch +Patch917: glibc-RHEL-57671-2.patch +Patch918: glibc-RHEL-57671-3.patch ############################################################################## # Continued list of core "glibc" package information: @@ -3214,6 +3217,9 @@ update_gconv_modules_cache () %endif %changelog +* Tue Jun 03 2025 Florian Weimer - 2.34-200 +- manual: Document the clock_nanosleep function (RHEL-57671) + * Tue May 27 2025 Frédéric Bérat - 2.34-199 - Ensure fallback initialization of ctype TLS data pointers to fix segfaults in programs using dlmopen or auditors (RHEL-72017)