Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 539 insertions, 0 deletions

diff --git a/man/man2/clock_getres.2 b/man/man2/clock_getres.2
new file mode 100644
index 0000000..51282df
--- /dev/null
+++ b/man/man2/clock_getres.2
@@ -0,0 +1,539 @@
+'\" t
+.\" Copyright (c) 2003 Nick Clifford (zaf@nrc.co.nz), Jan 25, 2003
+.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl), Aug 24, 2003
+.\" Copyright (c) 2020 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 2003-08-23 Martin Schulze <joey@infodrom.org> improvements
+.\" 2003-08-24 aeb, large parts rewritten
+.\" 2004-08-06 Christoph Lameter <clameter@sgi.com>, SMP note
+.\"
+.TH clock_getres 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+clock_getres, clock_gettime, clock_settime \- clock and time functions
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc ),
+since glibc 2.17
+.P
+Before glibc 2.17,
+Real-time library
+.RI ( librt ", " \-lrt )
+.SH SYNOPSIS
+.nf
+.B #include <time.h>
+.P
+.BI "int clock_getres(clockid_t " clockid ", struct timespec *_Nullable " res );
+.P
+.BI "int clock_gettime(clockid_t " clockid ", struct timespec *" tp );
+.BI "int clock_settime(clockid_t " clockid ", const struct timespec *" tp );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR clock_getres (),
+.BR clock_gettime (),
+.BR clock_settime ():
+.nf
+    _POSIX_C_SOURCE >= 199309L
+.fi
+.SH DESCRIPTION
+The function
+.BR clock_getres ()
+finds the resolution (precision) of the specified clock
+.IR clockid ,
+and, if
+.I res
+is non-NULL, stores it in the \fIstruct timespec\fP pointed to by
+.IR res .
+The resolution of clocks depends on the implementation and cannot be
+configured by a particular process.
+If the time value pointed to by the argument
+.I tp
+of
+.BR clock_settime ()
+is not a multiple of
+.IR res ,
+then it is truncated to a multiple of
+.IR res .
+.P
+The functions
+.BR clock_gettime ()
+and
+.BR clock_settime ()
+retrieve and set the time of the specified clock
+.IR clockid .
+.P
+The
+.I res
+and
+.I tp
+arguments are
+.BR timespec (3)
+structures.
+.P
+The
+.I clockid
+argument is the identifier of the particular clock on which to act.
+A clock may be system-wide and hence visible for all processes, or
+per-process if it measures time only within a single process.
+.P
+All implementations support the system-wide real-time clock,
+which is identified by
+.BR CLOCK_REALTIME .
+Its time represents seconds and nanoseconds since the Epoch.
+When its time is changed, timers for a relative interval are
+unaffected, but timers for an absolute point in time are affected.
+.P
+More clocks may be implemented.
+The interpretation of the
+corresponding time values and the effect on timers is unspecified.
+.P
+Sufficiently recent versions of glibc and the Linux kernel
+support the following clocks:
+.TP
+.B CLOCK_REALTIME
+A settable system-wide clock that measures real (i.e., wall-clock) time.
+Setting this clock requires appropriate privileges.
+This clock is affected by discontinuous jumps in the system time
+(e.g., if the system administrator manually changes the clock),
+and by frequency adjustments performed by NTP and similar applications via
+.BR adjtime (3),
+.BR adjtimex (2),
+.BR clock_adjtime (2),
+and
+.BR ntp_adjtime (3).
+This clock normally counts the number of seconds since
+1970-01-01 00:00:00 Coordinated Universal Time (UTC)
+except that it ignores leap seconds;
+near a leap second it is typically adjusted by NTP
+to stay roughly in sync with UTC.
+.TP
+.BR CLOCK_REALTIME_ALARM " (since Linux 3.0; Linux-specific)"
+Like
+.BR CLOCK_REALTIME ,
+but not settable.
+See
+.BR timer_create (2)
+for further details.
+.TP
+.BR CLOCK_REALTIME_COARSE " (since Linux 2.6.32; Linux-specific)"
+.\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
+A faster but less precise version of
+.BR CLOCK_REALTIME .
+This clock is not settable.
+Use when you need very fast, but not fine-grained timestamps.
+Requires per-architecture support,
+and probably also architecture support for this flag in the
+.BR vdso (7).
+.TP
+.BR CLOCK_TAI " (since Linux 3.10; Linux-specific)"
+.\" commit 1ff3c9677bff7e468e0c487d0ffefe4e901d33f4
+A nonsettable system-wide clock derived from wall-clock time
+but counting leap seconds.
+This clock does
+not experience discontinuities or frequency adjustments caused by
+inserting leap seconds as
+.B CLOCK_REALTIME
+does.
+.IP
+The acronym TAI refers to International Atomic Time.
+.TP
+.B CLOCK_MONOTONIC
+A nonsettable system-wide clock that
+represents monotonic time since\[em]as described
+by POSIX\[em]"some unspecified point in the past".
+On Linux, that point corresponds to the number of seconds that the system
+has been running since it was booted.
+.IP
+The
+.B CLOCK_MONOTONIC
+clock is not affected by discontinuous jumps in the system time
+(e.g., if the system administrator manually changes the clock),
+but is affected by frequency adjustments.
+This clock does not count time that the system is suspended.
+All
+.B CLOCK_MONOTONIC
+variants guarantee that the time returned by consecutive calls will not go
+backwards, but successive calls may\[em]depending on the architecture\[em]return
+identical (not-increased) time values.
+.TP
+.BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)"
+.\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3
+A faster but less precise version of
+.BR CLOCK_MONOTONIC .
+Use when you need very fast, but not fine-grained timestamps.
+Requires per-architecture support,
+and probably also architecture support for this flag in the
+.BR vdso (7).
+.TP
+.BR CLOCK_MONOTONIC_RAW " (since Linux 2.6.28; Linux-specific)"
+.\" Added in commit 2d42244ae71d6c7b0884b5664cf2eda30fb2ae68, John Stultz
+Similar to
+.BR CLOCK_MONOTONIC ,
+but provides access to a raw hardware-based time
+that is not subject to frequency adjustments.
+This clock does not count time that the system is suspended.
+.TP
+.BR CLOCK_BOOTTIME " (since Linux 2.6.39; Linux-specific)"
+.\" commit 7fdd7f89006dd5a4c702fa0ce0c272345fa44ae0
+.\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0
+A nonsettable system-wide clock that is identical to
+.BR CLOCK_MONOTONIC ,
+except that it also includes any time that the system is suspended.
+This allows applications to get a suspend-aware monotonic clock
+without having to deal with the complications of
+.BR CLOCK_REALTIME ,
+which may have discontinuities if the time is changed using
+.BR settimeofday (2)
+or similar.
+.TP
+.BR CLOCK_BOOTTIME_ALARM " (since Linux 3.0; Linux-specific)"
+Like
+.BR CLOCK_BOOTTIME .
+See
+.BR timer_create (2)
+for further details.
+.TP
+.BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)"
+This is a clock that measures CPU time consumed by this process
+(i.e., CPU time consumed by all threads in the process).
+On Linux, this clock is not settable.
+.TP
+.BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
+This is a clock that measures CPU time consumed by this thread.
+On Linux, this clock is not settable.
+.P
+Linux also implements dynamic clock instances as described below.
+.SS Dynamic clocks
+In addition to the hard-coded System-V style clock IDs described above,
+Linux also supports
+POSIX clock operations on certain character devices.
+Such devices are
+called "dynamic" clocks, and are supported since Linux 2.6.39.
+.P
+Using the appropriate macros, open file
+descriptors may be converted into clock IDs and passed to
+.BR clock_gettime (),
+.BR clock_settime (),
+and
+.BR clock_adjtime (2).
+The following example shows how to convert a file descriptor into a
+dynamic clock ID.
+.P
+.in +4n
+.EX
+#define CLOCKFD 3
+#define FD_TO_CLOCKID(fd)   ((\[ti](clockid_t) (fd) << 3) | CLOCKFD)
+#define CLOCKID_TO_FD(clk)  ((unsigned int) \[ti]((clk) >> 3))
+\&
+struct timespec ts;
+clockid_t clkid;
+int fd;
+\&
+fd = open("/dev/ptp0", O_RDWR);
+clkid = FD_TO_CLOCKID(fd);
+clock_gettime(clkid, &ts);
+.EE
+.in
+.SH RETURN VALUE
+.BR clock_gettime (),
+.BR clock_settime (),
+and
+.BR clock_getres ()
+return 0 for success.
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+.BR clock_settime ()
+does not have write permission for the dynamic POSIX
+clock device indicated.
+.TP
+.B EFAULT
+.I tp
+points outside the accessible address space.
+.TP
+.B EINVAL
+The
+.I clockid
+specified is invalid for one of two reasons.
+Either the System-V style
+hard coded positive value is out of range, or the dynamic clock ID
+does not refer to a valid instance of a clock object.
+.\" Linux also gives this error on attempts to set CLOCK_PROCESS_CPUTIME_ID
+.\" and CLOCK_THREAD_CPUTIME_ID, when probably the proper error should be
+.\" EPERM.
+.TP
+.B EINVAL
+.RB ( clock_settime ()):
+.I tp.tv_sec
+is negative or
+.I tp.tv_nsec
+is outside the range [0, 999,999,999].
+.TP
+.B EINVAL
+The
+.I clockid
+specified in a call to
+.BR clock_settime ()
+is not a settable clock.
+.TP
+.BR EINVAL " (since Linux 4.3)"
+.\" commit e1d7ba8735551ed79c7a0463a042353574b96da3
+A call to
+.BR clock_settime ()
+with a
+.I clockid
+of
+.B CLOCK_REALTIME
+attempted to set the time to a value less than
+the current value of the
+.B CLOCK_MONOTONIC
+clock.
+.TP
+.B ENODEV
+The hot-pluggable device (like USB for example) represented by a
+dynamic
+.I clk_id
+has disappeared after its character device was opened.
+.TP
+.B ENOTSUP
+The operation is not supported by the dynamic POSIX clock device
+specified.
+.TP
+.B EOVERFLOW
+The timestamp would not fit in
+.I time_t
+range.
+This can happen if an executable with 32-bit
+.I time_t
+is run on a 64-bit kernel when the time is 2038-01-19 03:14:08 UTC or later.
+However, when the system time is out of
+.I time_t
+range in other situations, the behavior is undefined.
+.TP
+.B EPERM
+.BR clock_settime ()
+does not have permission to set the clock indicated.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR clock_getres (),
+.BR clock_gettime (),
+.BR clock_settime ()
+T}	Thread safety	MT-Safe
+.TE
+.SH VERSIONS
+POSIX.1 specifies the following:
+.RS
+.P
+Setting the value of the
+.B CLOCK_REALTIME
+clock via
+.BR clock_settime ()
+shall have no effect on threads that are blocked waiting for a relative time
+service based upon this clock, including the
+.BR nanosleep ()
+function; nor on the expiration of relative timers based upon this clock.
+Consequently, these time services shall expire when the requested relative
+interval elapses, independently of the new or old value of the clock.
+.RE
+.P
+According to POSIX.1-2001, a process with "appropriate privileges" may set the
+.B CLOCK_PROCESS_CPUTIME_ID
+and
+.B CLOCK_THREAD_CPUTIME_ID
+clocks using
+.BR clock_settime ().
+On Linux, these clocks are not settable
+(i.e., no process has "appropriate privileges").
+.\" See http://bugzilla.kernel.org/show_bug.cgi?id=11972
+.SS C library/kernel differences
+On some architectures, an implementation of
+.BR clock_gettime ()
+is provided in the
+.BR vdso (7).
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SUSv2.
+Linux 2.6.
+.P
+On POSIX systems on which these functions are available, the symbol
+.B _POSIX_TIMERS
+is defined in \fI<unistd.h>\fP to a value greater than 0.
+POSIX.1-2008 makes these functions mandatory.
+.P
+The symbols
+.BR _POSIX_MONOTONIC_CLOCK ,
+.BR _POSIX_CPUTIME ,
+.B _POSIX_THREAD_CPUTIME
+indicate that
+.BR CLOCK_MONOTONIC ,
+.BR CLOCK_PROCESS_CPUTIME_ID ,
+.B CLOCK_THREAD_CPUTIME_ID
+are available.
+(See also
+.BR sysconf (3).)
+.\"
+.SS Historical note for SMP systems
+Before Linux added kernel support for
+.B CLOCK_PROCESS_CPUTIME_ID
+and
+.BR CLOCK_THREAD_CPUTIME_ID ,
+glibc implemented these clocks on many platforms using timer
+registers from the CPUs
+(TSC on i386, AR.ITC on Itanium).
+These registers may differ between CPUs and as a consequence
+these clocks may return
+.B bogus results
+if a process is migrated to another CPU.
+.P
+If the CPUs in an SMP system have different clock sources, then
+there is no way to maintain a correlation between the timer registers since
+each CPU will run at a slightly different frequency.
+If that is the case, then
+.I clock_getcpuclockid(0)
+will return
+.B ENOENT
+to signify this condition.
+The two clocks will then be useful only if it
+can be ensured that a process stays on a certain CPU.
+.P
+The processors in an SMP system do not start all at exactly the same
+time and therefore the timer registers are typically running at an offset.
+Some architectures include code that attempts to limit these offsets on bootup.
+However, the code cannot guarantee to accurately tune the offsets.
+glibc contains no provisions to deal with these offsets (unlike the Linux
+Kernel).
+Typically these offsets are small and therefore the effects may be
+negligible in most cases.
+.P
+Since glibc 2.4,
+the wrapper functions for the system calls described in this page avoid
+the abovementioned problems by employing the kernel implementation of
+.B CLOCK_PROCESS_CPUTIME_ID
+and
+.BR CLOCK_THREAD_CPUTIME_ID ,
+on systems that provide such an implementation
+(i.e., Linux 2.6.12 and later).
+.SH EXAMPLES
+The program below demonstrates the use of
+.BR clock_gettime ()
+and
+.BR clock_getres ()
+with various clocks.
+This is an example of what we might see when running the program:
+.P
+.in +4n
+.EX
+$ \fB./clock_times x\fP
+CLOCK_REALTIME : 1585985459.446 (18356 days +  7h 30m 59s)
+     resolution:          0.000000001
+CLOCK_TAI      : 1585985496.447 (18356 days +  7h 31m 36s)
+     resolution:          0.000000001
+CLOCK_MONOTONIC:      52395.722 (14h 33m 15s)
+     resolution:          0.000000001
+CLOCK_BOOTTIME :      72691.019 (20h 11m 31s)
+     resolution:          0.000000001
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (clock_getres.c)
+.EX
+/* clock_times.c
+\&
+   Licensed under GNU General Public License v2 or later.
+*/
+#define _XOPEN_SOURCE 600
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+\&
+#define SECS_IN_DAY (24 * 60 * 60)
+\&
+static void
+displayClock(clockid_t clock, const char *name, bool showRes)
+{
+    long             days;
+    struct timespec  ts;
+\&
+    if (clock_gettime(clock, &ts) == \-1) {
+        perror("clock_gettime");
+        exit(EXIT_FAILURE);
+    }
+\&
+    printf("%\-15s: %10jd.%03ld (", name,
+           (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
+\&
+    days = ts.tv_sec / SECS_IN_DAY;
+    if (days > 0)
+        printf("%ld days + ", days);
+\&
+    printf("%2dh %2dm %2ds",
+           (int) (ts.tv_sec % SECS_IN_DAY) / 3600,
+           (int) (ts.tv_sec % 3600) / 60,
+           (int) ts.tv_sec % 60);
+    printf(")\en");
+\&
+    if (clock_getres(clock, &ts) == \-1) {
+        perror("clock_getres");
+        exit(EXIT_FAILURE);
+    }
+\&
+    if (showRes)
+        printf("     resolution: %10jd.%09ld\en",
+               (intmax_t) ts.tv_sec, ts.tv_nsec);
+}
+\&
+int
+main(int argc, char *argv[])
+{
+    bool showRes = argc > 1;
+\&
+    displayClock(CLOCK_REALTIME, "CLOCK_REALTIME", showRes);
+#ifdef CLOCK_TAI
+    displayClock(CLOCK_TAI, "CLOCK_TAI", showRes);
+#endif
+    displayClock(CLOCK_MONOTONIC, "CLOCK_MONOTONIC", showRes);
+#ifdef CLOCK_BOOTTIME
+    displayClock(CLOCK_BOOTTIME, "CLOCK_BOOTTIME", showRes);
+#endif
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR date (1),
+.BR gettimeofday (2),
+.BR settimeofday (2),
+.BR time (2),
+.BR adjtime (3),
+.BR clock_getcpuclockid (3),
+.BR ctime (3),
+.BR ftime (3),
+.BR pthread_getcpuclockid (3),
+.BR sysconf (3),
+.BR timespec (3),
+.BR time (7),
+.BR time_namespaces (7),
+.BR vdso (7),
+.BR hwclock (8)