126 lines
3.3 KiB
Groff
126 lines
3.3 KiB
Groff
'\"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.
|
|
|
|
|