Tribblix: manual page: clock

CLOCK_NANOSLEEP(3C) Standard C Library Functions CLOCK_NANOSLEEP(3C)

NAME

clock_nanosleep - high resolution sleep with specifiable clock

SYNOPSIS

#include <time.h>

int clock_nanosleep(clockid_t clock_id, int flags,
const struct timespec *rqtp, struct timespec *rmtp);

DESCRIPTION

If the flag TIMER_ABSTIME is not set in the flags argument, the
clock_nanosleep() function causes the current thread to be suspended
from execution until either the time interval specified by the rqtp
argument has elapsed, or a signal is delivered to the calling thread
and its action is to invoke a signal-catching function, or the
process is terminated. The clock used to measure the time is the
clock specified by clock_id.

If the flag TIMER_ABSTIME is set in the flags argument, the
clock_nanosleep() function causes the current thread to be suspended
from execution until either the time value of the clock specified by
clock_id reaches the absolute time specified by the rqtp argument, or
a signal is delivered to the calling thread and its action is to
invoke a signal-catching function, or the process is terminated. If,
at the time of the call, the time value specified by rqtp is less
than or equal to the time value of the specified clock, then
clock_nanosleep() returns immediately and the calling process is not
suspended.

The suspension time caused by this function can be longer than
requested because the argument value is rounded up to an integer
multiple of the sleep resolution, or because of the scheduling of
other activity by the system. But, except for the case of being
interrupted by a signal, the suspension time for the relative
clock_nanosleep() function (that is, with the TIMER_ABSTIME flag not
set) will not be less than the time interval specified by rqtp, as
measured by the corresponding clock. The suspension for the absolute
clock_nanosleep() function (that is, with the TIMER_ABSTIME flag set)
will be in effect at least until the value of the corresponding clock
reaches the absolute time specified by rqtp, except for the case of
being interrupted by a signal.

The use of the clock_nanosleep() function has no effect on the action
or blockage of any signal.

The clock_nanosleep() function fails if the clock_id argument refers
to the CPU-time clock of the calling thread. It is unspecified if
clock_id values of other CPU-time clocks are allowed.

RETURN VALUES

If the clock_nanosleep() function returns because the requested time
has elapsed, its return value is 0.

If the clock_nanosleep() function returns because it has been
interrupted by a signal, it returns the corresponding error value.
For the relative clock_nanosleep() function, if the rmtp argument is
non-null, the timespec structure referenced by it is updated to
contain the amount of time remaining in the interval (the requested
time minus the time actually slept). If the rmtp argument is NULL,
the remaining time is not returned. The absolute clock_nanosleep()
function has no effect on the structure referenced by rmtp.

If clock_nanosleep() fails, it shall return the corresponding error
value.

ERRORS

The clock_nanosleep() function will fail if:

EINTR
The clock_nanosleep() function was interrupted by a
signal.

EINVAL
The rqtp argument specified a nanosecond value less than
zero or greater than or equal to 1,000 million; or the
TIMER_ABSTIME flag was specified in flags and the rqtp
argument is outside the range for the clock specified by
clock_id; or the clock_id argument does not specify a
known clock, or specifies the CPU-time clock of the
calling thread.

ENOTSUP
The clock_id argument specifies a clock for which
clock_nanosleep() is not supported, such as a CPU-time
clock.