timer_settime(2) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
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 specified in the tim argument.  If the value is
     0, the timer is disarmed.  If the argument otim is not NULL the old timer
     settingas 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 difference between the clock associated with this
     timer, and the value specified 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
     argment 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 2.0.2                  September 13, 2003                  NetBSD 2.0.2