clock_settime(2)

NAME
     clock_settime, clock_gettime, clock_getres - get/set date and time
     (POSIX)

C SYNOPSIS
     #include <time.h>

     int clock_settime(clockid_t clock_id, const struct timespec *tp);
     int clock_gettime(clockid_t clock_id, struct timespec *tp);
     int clock_getres(clockid_t clock_id, struct timespec *res);

DESCRIPTION
     The clock_settime() function sets the specific clock, clock_id, to the
     value specified by 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.

     The clock_gettime() function returns the current value tp for the
     specified clock, clock_id. Depending on the clocks resolution, it may be
     possible to obtain the same time value with consecutive reads of the
     clock.  The time value may also have a higher precision then the
     resolution of the clock.

     The resolution of any clock can be obtained by calling the clock_getres()
     function. The resolution of the clock will be returned in res. If res is
     NULL, then the resolution of the clock will not be returned.

CLOCKS
     Supported clocks for clock_id are

     CLOCK_REALTIME 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)).

     CLOCK_SGI_CYCLE
                    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 syssgi() with the SGI_CYCLECNTR_SIZE request.  This
                    clock only is usable as a clock_id for the clock_gettime()
                    and clock_getres() functions. This clock is SGI specific
                    and is not portable.
     CLOCK_SGI_FAST This clock has a higher resolution than CLOCK_REALTIME and
                    is available to privileged users only.  This clock only is
                    usable as a clock_id. for the clock_getres() and
                    timer_create() functions. This clock is SGI specific and
                    is not portable.

SEE ALSO
     date(1), time(2), stime(2), ctime(3C), gettimeofday(3c),
     settimeofday(3c), and syssgi(2).


DIAGNOSTICS
     The clock_settime(), clock_gettime(), and clock_getres() 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 errno to indicate the
     error

     [EINVAL]       The clock_id argument is not a know clock.

     The clock_settime() call also supports the following values for errno

     [EINVAL]       The tp argument is outside the range for the given
                    clock_id , or the tp argument specified a nanosecond value
                    less then zero  or greater then or equal to 1000 million

     [EPERM]        The requesting process does not have the appropriate
                    privilege to set the specified clock.