NAME

       dtk_nanosleep - high-resolution sleep

SYNOPSIS

       #include <dtk_time.h>

       int dtk_nanosleep(int abs, const struct dtk_timespec* req,
                                  struct dtk_timespec* rem);

DESCRIPTION

       The  function  dtk_nanosleep()  allows the caller to sleep for an interval with nanosecond
       precision. If the argument abs is zero, the  specified  interval  is  interpretated  as  a
       relative value, otherwise an absolute value. The interval is specified by the req argument
       which is a pointer to a dtk_timespec structure defined as:

           struct dtk_timespec {
               long sec;    /* seconds */
               long nsec;   /* nanoseconds */
           };

       If interpreted as an absolute value, it  represents  seconds  and  nanoseconds  since  the
       Epoch, 1970-01-01 00:00:00 +0000  (UTC).

       dtk_nanosleep()  suspends  the  execution  of the calling thread until either at least the
       time specified by req has elapsed, or a signal is delivered that causes a  signal  handler
       to be called or that terminates the process.

       If the call is interrupted by a signal handler, dtk_nanosleep() returns -1, and sets errno
       to EINTR. In addition, if rem is not NULL, and abs  is  zero,  it  returns  the  remaining
       unslept  time  in  rem.  This  value  can  then  be used to call dtk_nanosleep() again and
       complete a (relative) sleep.

RETURN VALUE

       On successfully sleeping for the requested interval, dtk_nanosleep()  returns  0.  If  the
       call  is  interrupted  by  a signal handler or encounters an error, then it returns -1 and
       errno is set appropriately.

ERRORS

       dtk_nanosleep() will fail if:

       EINTR  The sleep was interrupted by a signal handler.

       EINVAL The value in the nsec field was not  in  the  range  0  to  999999999  or  sec  was
              negative.

NOTE

       This  function  is  a  wrapper  to  clock_nanosleep(2)  if  it  is provided by the system.
       Otherwise, it implements the function  by  using  the  sleep  function  with  the  highest
       precision available on the system.

SEE ALSO

       dtk_nanosleep(3), clock_nanosleep(2)