diff options
Diffstat (limited to 'man2/clock_getres.2')
| -rw-r--r-- | man2/clock_getres.2 | 539 |
1 files changed, 0 insertions, 539 deletions
diff --git a/man2/clock_getres.2 b/man2/clock_getres.2 deleted file mode 100644 index 9c98d12e9..000000000 --- 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 (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) |