'\"macro stdmacro
.TH PCLOCK 2
.SH NAME
clock_settime, clock_gettime, clock_getres \- get/set date and time (\s-1POSIX\s+1)
.Op c p a
.SH C SYNOPSIS
.nf
.B #include <time.h>
.PP
.B "int clock_settime(clockid_t clock_id, const struct timespec *tp);
.B "int clock_gettime(clockid_t clock_id, struct timespec *tp);
.B "int clock_getres(clockid_t clock_id, struct timespec *res);
.fi
.PP
.Op
.SH DESCRIPTION
.PP
The
\f4clock_settime()\f1
function sets the specific clock, 
.I clock_id,
to the value
specified by 
.I tp.
Time values that are between two consecutive non-negative integer
multiples of the resolution of the specified clock are truncated down
to the smaller multiple of the resolution.
.PP
.sp
The
\f4clock_gettime()\f1
function returns the current value 
.I tp
for the specified clock,
.I clock_id.
Depending on the clocks resolution, it may be possible to obtain the
same time value with consecutive reads of the clock.
.PP
The resolution of any clock can be obtained by calling the
\f4clock_getres()\f1 function. The resolution of the clock will be
returned in
.I res.
If
.I res
is NULL, then the resolution of the clock will not be returned.
.PP
.SH "CLOCKS"
Supported clocks for 
.I clock_id
are
.TP15
.SM
\%\f4CLOCK_REALTIME\f1
The system's notion of the current time is obtained with this clock.
The time is expressed in seconds and
nanoseconds since midnight (00:00) Coordinated Universal Time (UTC),
January 1, 1970.  The resolution for of this clock is never worse
than 100 HZ (which equals 10 milliseconds).  The actual resolution of
the clock depends on the timer capability of the underlying
hardware(see timers(5)).
.TP15
.SM
\%\f4CLOCK_SGI_CYCLE\f1
This clock allows easy access to the free running hardware counter.
This SGI specific clock maps the counter into the application address
space and returns the current value. Handling of the counter wraps on
machines with small counters
is left to the application. To find the number of bit the counter
supports the application may call \f4syssgi()\f1 with the
\f4SGI_CYCLECNTR_SIZE\f1 request.
This clock only is usable as a 
.I clock_id
for the \f4clock_gettime()\f1 and \f4clock_getres()\f1 functions. 
This clock is SGI specific and is not portable.
.TP15
.SM
\%\f4CLOCK_SGI_FAST\f1
This clock has a higher resolution than \f4CLOCK_REALTIME\fP and is
available to privileged users only.
This clock only is usable as a 
.I clock_id.
for the \f4clock_getres()\f1 and \f4timer_create()\f1 functions. 
This clock is SGI specific and is not portable.
.PP
.SH "SEE ALSO"
date(1), time(2), stime(2), ctime(3C), gettimeofday(3c),
settimeofday(3c), and syssgi(2).

.SH "DIAGNOSTICS"
.PP
The \f3clock_settime()\f1, \f3clock_gettime()\f1, and
\f3clock_getres()\f1
return a value of 0 to the calling process if the operation is
successful; otherwise the functions shall return a value of -1 and
shall set
.I errno
to indicate the error
.TP 15
.SM
\%[EINVAL]
The 
.I clock_id
argument is not a know clock.
.PP
The \f3clock_settime()\f1 call also supports the following values for 
.I errno
.
.TP15
.SM
\%[EINVAL]
The 
.I tp
argument is outside the range for the given 
.I clock_id
, or the 
.I tp
argument specified a nanosecond value less then zero  or greater then
or equal to 1000 million
.TP15
.SM
\%[EPERM]
The requesting process does not have the appropriate privilege to
set the specified clock.