'\" et
.TH CLOCK_GETRES "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.

.SH NAME
clock_getres,
clock_gettime,
clock_settime
\(em clock and timer functions
.SH SYNOPSIS
.LP
.nf
#include <time.h>
.P
int clock_getres(clockid_t \fIclock_id\fP, struct timespec *\fIres\fP);
int clock_gettime(clockid_t \fIclock_id\fP, struct timespec *\fItp\fP);
int clock_settime(clockid_t \fIclock_id\fP, const struct timespec *\fItp\fP);
.fi
.SH DESCRIPTION
The
\fIclock_getres\fR()
function shall return the resolution of any clock. Clock resolutions
are implementation-defined and cannot be set by a process. If the
argument
.IR res
is not NULL, the resolution of the specified clock shall be stored in the
location pointed to by
.IR res .
If
.IR res
is NULL, the clock resolution is not returned. If the
.IR time
argument of
\fIclock_settime\fR()
is not a multiple of
.IR res ,
then the value is truncated to a multiple of
.IR res .
.P
The
\fIclock_gettime\fR()
function shall return the current value
.IR tp
for the specified clock,
.IR clock_id .
.P
The
\fIclock_settime\fR()
function shall set the specified clock,
.IR clock_id ,
to the value specified by
.IR tp .
Time values that are between two consecutive non-negative integer
multiples of the resolution of the specified clock shall be truncated
down to the smaller multiple of the resolution.
.P
A clock may be system-wide (that is, visible to all processes) or
per-process (measuring time that is meaningful only within a process).
All implementations shall support a
.IR clock_id
of CLOCK_REALTIME as defined in
.IR <time.h> .
This clock represents the clock measuring real time for the system.
For this clock, the values returned by
\fIclock_gettime\fR()
and specified by
\fIclock_settime\fR()
represent the amount of time (in seconds and nanoseconds) since the
Epoch. An implementation may also support additional clocks. The
interpretation of time values for these clocks is unspecified.
.P
If the value of the CLOCK_REALTIME clock is set via
\fIclock_settime\fR(),
the new value of the clock shall be used to determine the time of
expiration for absolute time services based upon the CLOCK_REALTIME
clock. This applies to the time at which armed absolute timers expire.
If the absolute time requested at the invocation of such a time service
is before the new value of the clock, the time service shall expire
immediately as if the clock had reached the requested time normally.
.P
Setting the value of the CLOCK_REALTIME clock via
\fIclock_settime\fR()
shall have no effect on threads that are blocked waiting for a relative
time service based upon this clock, including the
\fInanosleep\fR()
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.
.P
If the Monotonic Clock option is supported, all implementations shall
support a
.IR clock_id
of CLOCK_MONOTONIC defined in
.IR <time.h> .
This clock represents the monotonic clock for the system. For this
clock, the value returned by
\fIclock_gettime\fR()
represents the amount of time (in seconds and nanoseconds) since an
unspecified point in the past (for example, system start-up time, or the
Epoch). This point does not change after system start-up time. The value
of the CLOCK_MONOTONIC clock cannot be set via
\fIclock_settime\fR().
This function shall fail if it is invoked with a
.IR clock_id
argument of CLOCK_MONOTONIC.
.P
The effect of setting a clock via
\fIclock_settime\fR()
on armed per-process timers associated with a clock other than
CLOCK_REALTIME is implementation-defined.
.P
If the value of the CLOCK_REALTIME clock is set via
\fIclock_settime\fR(),
the new value of the clock shall be used to determine the time at which
the system shall awaken a thread blocked on an absolute
\fIclock_nanosleep\fR()
call based upon the CLOCK_REALTIME clock. If the absolute time
requested at the invocation of such a time service is before the new
value of the clock, the call shall return immediately as if the clock
had reached the requested time normally.
.P
Setting the value of the CLOCK_REALTIME clock via
\fIclock_settime\fR()
shall have no effect on any thread that is blocked on a relative
\fIclock_nanosleep\fR()
call. Consequently, the call shall return when the requested relative
interval elapses, independently of the new or old value of the clock.
.P
Appropriate privileges to set a particular clock are
implementation-defined.
.P
If _POSIX_CPUTIME is defined, implementations shall support clock ID
values obtained by invoking
\fIclock_getcpuclockid\fR(),
which represent the CPU-time clock of a given process. Implementations
shall also support the special
.BR clockid_t
value CLOCK_PROCESS_CPUTIME_ID, which represents the CPU-time clock of
the calling process when invoking one of the
.IR clock_* (\|)
or
.IR timer_* (\|)
functions. For these clock IDs, the values returned by
\fIclock_gettime\fR()
and specified by
\fIclock_settime\fR()
represent the amount of execution time of the process associated with
the clock. Changing the value of a CPU-time clock via
\fIclock_settime\fR()
shall have no effect on the behavior of the sporadic server scheduling
policy (see
.IR "Scheduling Policies").
.P
If _POSIX_THREAD_CPUTIME is defined, implementations shall support
clock ID values obtained by invoking
\fIpthread_getcpuclockid\fR(),
which represent the CPU-time clock of a given thread. Implementations
shall also support the special
.BR clockid_t
value CLOCK_THREAD_CPUTIME_ID, which represents the CPU-time clock of
the calling thread when invoking one of the
.IR clock_* (\|)
or
.IR timer_* (\|)
functions. For these clock IDs, the values returned by
\fIclock_gettime\fR()
and specified by
\fIclock_settime\fR()
shall represent the amount of execution time of the thread associated
with the clock. Changing the value of a CPU-time clock via
\fIclock_settime\fR()
shall have no effect on the behavior of the sporadic server scheduling
policy (see
.IR "Scheduling Policies").
.SH "RETURN VALUE"
A return value of 0 shall indicate that the call succeeded. A return
value of \(mi1 shall indicate that an error occurred, and
.IR errno
shall be set to indicate the error.
.SH ERRORS
The
\fIclock_getres\fR(),
\fIclock_gettime\fR(),
and
\fIclock_settime\fR()
functions shall fail if:
.TP
.BR EINVAL
The
.IR clock_id
argument does not specify a known clock.
.P
The
\fIclock_gettime\fR()
function shall fail if:
.TP
.BR EOVERFLOW
The number of seconds will not fit in an object of type
.BR time_t .
.P
The
\fIclock_settime\fR()
function shall fail if:
.TP
.BR EINVAL
The
.IR tp
argument to
\fIclock_settime\fR()
is outside the range for the given clock ID.
.TP
.BR EINVAL
The
.IR tp
argument specified a nanosecond value less than zero or greater than or
equal to 1\|000 million.
.TP
.BR EINVAL
The value of the
.IR clock_id
argument is CLOCK_MONOTONIC.
.P
The
\fIclock_settime\fR()
function may fail if:
.TP
.BR EPERM
The requesting process does not have appropriate privileges
to set the specified clock.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
Note that the absolute value of the monotonic clock is meaningless
(because its origin is arbitrary), and thus there is no need to set it.
Furthermore, realtime applications can rely on the fact that the value
of this clock is never set and, therefore, that time intervals measured
with this clock will not be affected by calls to
\fIclock_settime\fR().
.SH RATIONALE
None.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.ad l
.IR "Scheduling Policies",
.IR "\fIclock_getcpuclockid\fR\^(\|)",
.IR "\fIclock_nanosleep\fR\^(\|)",
.IR "\fIctime\fR\^(\|)",
.IR "\fImq_receive\fR\^(\|)",
.IR "\fImq_send\fR\^(\|)",
.IR "\fInanosleep\fR\^(\|)",
.IR "\fIpthread_mutex_timedlock\fR\^(\|)",
.IR "\fIsem_timedwait\fR\^(\|)",
.IR "\fItime\fR\^(\|)",
.IR "\fItimer_create\fR\^(\|)",
.IR "\fItimer_getoverrun\fR\^(\|)"
.ad b
.P
The Base Definitions volume of POSIX.1\(hy2008,
.IR "\fB<time.h>\fP"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, Copyright (C) 2013 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.unix.org/online.html .

Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .