summaryrefslogtreecommitdiffstats
path: root/man2/clock_getres.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/clock_getres.2')
-rw-r--r--man2/clock_getres.2539
1 files changed, 0 insertions, 539 deletions
diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
deleted file mode 100644
index ec1e327..0000000
--- a/man2/clock_getres.2
+++ /dev/null
@@ -1,539 +0,0 @@
-'\" 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-03-05 "Linux man-pages 6.7"
-.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)