diff options
Diffstat (limited to 'man3/clock_getres.3')
| -rw-r--r-- | man3/clock_getres.3 | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/man3/clock_getres.3 b/man3/clock_getres.3 new file mode 100644 index 000000000..407e85793 --- /dev/null +++ b/man3/clock_getres.3 @@ -0,0 +1,195 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" +.\" Copyright (c) 2003 Nick Clifford (zaf@nrc.co.nz), Jan 25, 2003 +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl), Aug 24, 2003 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 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 3 2003-08-24 "" "Linux Programmer's Manual" +.SH NAME +clock_getres, clock_gettime, clock_settime \- clock and time functions +.SH SYNOPSIS +.B #include <time.h> +.sp +.BI "int clock_getres(clockid_t " clk_id ", struct timespec *" res ); +.br +.BI "int clock_gettime(clockid_t " clk_id ", struct timespec *" tp ); +.br +.BI "int clock_settime(clockid_t " clk_id ", const struct timespec *" tp ); +.SH DESCRIPTION +The function +.BR clock_getres () +finds the resolution (precision) of the specified clock +.IR clk_id , +and, if +.I res +is non-NULL, stores it in the struct timespec 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 . +.PP +The functions +.BR clock_gettime () +and +.BR clock_settime () +retrieve and set the time of the specified clock +.IR clk_id . +.PP +The +.I res +and +.I tp +arguments are +.B timespec +structs, as specified in +.IR <time.h> : +.sp +.nf +struct timespec { +.in +8 +time_t tv_sec; /* seconds */ +long tv_nsec; /* nanoseconds */ +.in -8 +}; +.fi +.PP +The +.I clk_id +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. +.LP +All implementations support the system-wide realtime 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. +.LP +More clocks may be implemented. The interpretation of the +corresponding time values and the effect on timers is unspecified. +.LP +Sufficiently recent versions of GNU libc and the Linux kernel +support the following clocks: +.TP +.B CLOCK_REALTIME +System-wide realtime clock. +Setting this clock requires appropriate privileges. +.TP +.B CLOCK_MONOTONIC +Clock that cannot be set and represents monotonic time since +some unspecified starting point. +.TP +.B CLOCK_PROCESS_CPUTIME_ID +High-resolution per-process timer from the CPU. +.TP +.B CLOCK_THREAD_CPUTIME_ID +Thread-specific CPU-time clock. +.SH "RETURN VALUE" +.BR clock_gettime "(), " clock_settime () +and +.BR clock_getres () +return 0 for success, or \-1 for failure (in which case +.I errno +is set appropriately). +.SH ERRORS +.TP +.B EFAULT +.I tp +points outside the accessible address space. +.TP +.B EINVAL +The +.I clk_id +specified is not supported on this system. +.TP +.B EPERM +.BR clock_settime () +does not have permission to set the clock indicated. +.SH NOTE +Most systems require the program be linked with the librt +library to use these functions. +.SH NOTE for SMP systems +The +.B CLOCK_PROCESS_CPUTIME_ID +and +.B CLOCK_THREAD_CPUTIME_ID +clocks are realized on many platforms using timers 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. +.PP +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 only be useful if it +can be ensured that a process stays on a certain CPU. +.PP +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. +.SH AVAILABILITY +On POSIX systems on which these functions are available, the symbol +.B _POSIX_TIMERS +is defined in <unistd.h> to a value greater than 0. +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).) +.SH "CONFORMING TO" +SUSv2, POSIX 1003.1-2001. +.SH "SEE ALSO" +.BR date (1), +.BR adjtimex (2), +.BR gettimeofday (2), +.BR settimeofday (2), +.BR time (2), +.BR ctime (3), +.BR ftime (3), +.BR sysconf (3) |