rpms/glibc
6
0
Fork 2
Code Issues Pull Requests Releases Activity

manual: Document the clock_nanosleep function (RHEL-57671)

Browse Source 
Resolves: RHEL-57671
This commit is contained in:
Florian Weimer 2025-06-03 11:59:56 +02:00
parent 458ff98d2a
commit 24908a1e2c
4 changed files with 225 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
glibc-RHEL-57671-1.patch Normal file
View File

@ -0,0 +1,23 @@
commit 9a743032cd59c59167bf615d8ab4acc96b2bf47e
Author: Maciej W. Rozycki <macro@redhat.com>
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

121
glibc-RHEL-57671-2.patch Normal file
View File

@ -0,0 +1,121 @@
commit 1a3d8f2201d4d613401ce5be9a283f4f28c43093
Author: Arjun Shankar <arjun@redhat.com>
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 <macro@redhat.com>
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

74
glibc-RHEL-57671-3.patch Normal file
View File

@ -0,0 +1,74 @@
commit 591283a68965fe61a7186c9c81f7812e71b282b4
Author: Arjun Shankar <arjun@redhat.com>
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 <mark.hsj@gmail.com>
Reviewed-by: Mark Harris <mark.hsj@gmail.com>
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

8
glibc.spec
View File

@ -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 <fweimer@redhat.com> - 2.34-200
- manual: Document the clock_nanosleep function (RHEL-57671)
* Tue May 27 2025 Frédéric Bérat <fberat@redhat.com> - 2.34-199
- Ensure fallback initialization of ctype TLS data pointers to fix segfaults in
programs using dlmopen or auditors (RHEL-72017)