timer_getoverrun, timer_gettime, and timer_settime Subroutine

Purpose

Per-process timers.

Library

Standard C Library (libc.a)

Syntax

#include <time.h>

int timer_getoverrun (timerid)
timer_t timerid;

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

int timer_settime (timerid, flags, value, ovalue)
timer_t timerid;
int flags;
const struct itimerspec *value;
struct itimerspec *ovalue;

Description

The timer_gettime subroutine stores the amount of time until the specified timer, timerid, expires, and stores the reload value of the timer into the space pointed to by the value parameter. The it_value member of the structure contains the amount of time before the timer expires, or zero if the timer is disarmed. This value is returned as the interval until the timer expires, even if the timer was armed with absolute time. The it_interval member of the value parameter contains the reload value last set by the timer_settime subroutine.

The timer_settime subroutine sets the time until the next expiration of the timer specified by the timerid parameter and arms the timer if the it_value member of the value parameter is nonzero. If the specified timer is armed when the timer_settime subroutine is called, the call resets the time until next expiration to the value specified. If the it_value member of the value parameter is zero, the timer is disarmed.

If the TIMER_ABSTIME flag is not set in the flags parameter, the timer_settime subroutine behaves as if the time until next expiration is set to be equal to the interval specified by the it_value member of the value parameter. That is, the timer expires in it_value nanoseconds from when the call is made. If the TIMER_ABSTIME flag is set in the flags parameter, the timer_settime subroutine behaves as if the time until next expiration is set to be equal to the difference between the absolute time specified by the it_value member and the current value of the clock associated with the timerid parameter. That is, the timer expires when the clock reaches the value specified by the it_value member. If the specified time has already passed, the subroutine succeeds and the expiration notification is made.

The reload value of the timer is set to the value specified by the it_interval member of the value parameter. When a timer is armed with a nonzero it_interval, a periodic (or repetitive) timer is specified.

Time values that are between two consecutive non-negative integer multiples of the resolution of the specified timer is rounded up to the larger multiple of the resolution. Quantization error does not cause the timer to expire earlier than the rounded time value.

If the ovalue parameter is not NULL, the timer_settime subroutine stores a value representing the previous amount of time before the timer would have expired, or zero if the timer was disarmed, together with the previous timer reload value. Timers do not expire before their scheduled time.

Only a single signal is queued to the process for a given timer at any point in time. When a timer for which a signal is still pending expires, no signal is queued, and a timer overrun occurs.

Concerning timers based on thread CPU-time clocks, the timer_gettime and timer_settime subroutines can only be called with timerid referencing a timer based on the thread CPU-time clock of the calling thread. In other words, a thread cannot manipulate the thread CPU-time timers created by other threads in the same process.

Parameters

Return Values

If the timer_getoverrun subroutine succeeds, it returns the timer expiration overrun count.

If the timer_gettime or timer_settime subroutines succeed, 0 is returned.

If an error occurs for any of these subroutines, -1 is returned and errno is set to indicate the error.

Error Codes