diff options
Diffstat (limited to 'man/man2/clock_getres.2')
| -rw-r--r-- | man/man2/clock_getres.2 | 539 |
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 000000000..9c98d12e9 --- /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 (date) "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) |