timer_gettime(2) - NetBSD Manual Pages

TIMER_SETTIME(2)          NetBSD System Calls Manual          TIMER_SETTIME(2)


NAME

     timer_settime, timer_gettime, timer_getoverrun -- process timer manipula-
     tion


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <time.h>

     int
     timer_settime(timer_t timerid, int flags,
         const struct itimerspec * restrict tim,
         struct itimerspec * restrict otim);

     int
     timer_gettime(timer_t timerid, struct itimerspec *tim);

     int
     timer_getoverrun(timer_t timerid);


DESCRIPTION

     The timer_settime() sets the next expiration time of the timer with ID
     timerid to the it_value (see itimerspec(3)) specified in the tim argu-
     ment.  If the value is 0, the timer is disarmed.  If the argument otim is
     not NULL the old timer settings are returned.

     If the flags argument is set to TIMER_RELTIME then the expiration time is
     set to the value in nanoseconds specified in the tim argument from the
     time the call to timer_settime() was made.  If the flags argument is set
     to TIMER_ABSTIME then the expiration time is set to be equal to the dif-
     ference between the clock associated with this timer, and the value spec-
     ified in the tim argument.  If that time has already passed, then the
     call succeeds, and the expiration notification occurs.

     If the it_interval of the tim argument is non-zero, then the timer
     reloads upon expiration.

     The timer_gettime() function returns the current settings of the timer
     specified by the timerid argument in the tim argument.

     Only one notification event (signal) can be pending for a given timer and
     process.  If a timer expires while the signal is still queued for deliv-
     ery, then the overrun counter for that timer is increased.  The counter
     can store values up to DELAYTIMER_MAX.  When the signal is finally deliv-
     ered to the process, then the timer_getoverrun() function can be used to
     retrieve the overrun counter for the timer specified in the timerid argu-
     ment.


NOTES

     Expiration time values are always rounded up to the resolution of the
     timer, so a notification will never be sent before the requested time.
     Values returned in the otim argument of timer_settime() or in the tim
     argument of timer_gettime() are subject to the above rounding effect and
     might not exactly match the requested values by the user.


RETURN VALUES

     If successful, the timer_gettime() and timer_settime() functions return
     0, and the timer_getoverrun() function returns the expiration overrun
     count for the specified timer.  Otherwise, the functions return -1, and
     set errno to indicate the error.


ERRORS

     The timer_gettime(), timer_getoverrun(), and timer_settime() functions
     will fail if:

     [EINVAL]           The argument timerid does not correspond to a valid
                        timer id as returned by timer_create() or that timer
                        id has been deleted by timer_delete().

     The timer_settime() function will fail if:

     [EINVAL]           A nanosecond field in the tim structure specified a
                        value less than zero or greater than or equal to 10e9.


SEE ALSO

     clock_gettime(2), timer_create(2), timer_delete(2)


STANDARDS

     IEEE Std 1003.1b-1993 (``POSIX.1''), IEEE Std 1003.1i-1995 (``POSIX.1'')

NetBSD 9.3                       May 17, 2010                       NetBSD 9.3