-.\" 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 2008-08-11 "" "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 );
-
-.BI "int clock_gettime(clockid_t " clk_id ", struct timespec *" tp );
-
-.BI "int clock_settime(clockid_t " clk_id ", const struct timespec *" tp );
-.sp
-.in -4n
-Feature Test Macro Requirements for glibc (see
-.BR feature_test_macros (7)):
-.in
-.sp
-.ad l
-.BR clock_getres (),
-.BR clock_gettime (),
-.BR clock_settime ():
-_POSIX_C_SOURCE\ >=\ 199309L
-.ad b
-.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 \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 .
-.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
-.I timespec
-structs, as specified in
-.IR <time.h> :
-.sp
-.in +4n
-.nf
-struct timespec {
- time_t tv_sec; /* seconds */
- long tv_nsec; /* nanoseconds */
-};
-.fi
-.in
-.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 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.
-.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 glibc and the Linux kernel
-support the following clocks:
-.TP
-.B CLOCK_REALTIME
-System-wide real-time 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 (),
-.BR 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 "CONFORMING TO"
-SUSv2, POSIX.1-2001.
-.SH AVAILABILITY
-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.
-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 NOTES
-Most systems require the program be linked with the librt
-library to use these functions.
-.SS 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 "SEE ALSO"
-.BR date (1),
-.BR adjtimex (2),
-.BR gettimeofday (2),
-.BR settimeofday (2),
-.BR time (2),
-.BR clock_getcpuclockid (3),
-.BR ctime (3),
-.BR ftime (3),
-.BR sysconf (3),
-.BR time (7)
+.so man2/clock_getres.2
+.\" This link provided in Section 3 because, by historical accident,
+.\" the page was originally in Section 3 -- mtk, Feb 2009
projects / thirdparty / man-pages.git / blobdiff