TIMER_SETTIME(2)

TIMER_SETTIME(2) | System Calls Manual | TIMER_SETTIME(2)

# NAME

`timer_settime`, `timer_gettime`, `timer_getoverrun` —
process timer manipulation

# 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 argument. 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 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 delivery, then the overrun counter for that timer is increased. The counter can store values up to `DELAYTIMER_MAX`. When the signal is finally delivered to the process, then the `timer_getoverrun`() function can be used to retrieve the overrun counter for the timer specified in the timerid argument.

# 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 10^9.

# SEE ALSO

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

# STANDARDS

IEEE Std 1003.1b-1993 (“POSIX.1b”), IEEE Std 1003.1i-1995 (“POSIX.1i”)

May 17, 2010 | NetBSD 10.1