timers(2) System Calls Manual timers(2)
NAME
timers: timer_create(), timer_delete(), timer_getoverrun(), timer_gettime(), timer_settime() - timer operations
SYNOPSIS
DESCRIPTION
timer_create()
The function creates a per-process timer using the specified clock, clock_id, as the timing base. The function returns, in the location
referenced by timerid, a timer ID of type timer_t used to identify the timer in timer requests. This timer ID will be unique within the
calling process until the timer is deleted. The particular clock, clock_id, is defined in The timer whose ID is returned will be in a dis-
armed state upon return from
The evp argument, if non-NULL, points to a sigevent structure. If the sigev_notify member of evp is then the structure should also specify
the signal number to be sent to the process on timer expiration. The signal to be sent is specified in the sigev_signo field of evp. If
the sigev_notify member of evp is no notification is sent. If evp is NULL, then a default signal is sent to the process. The defaults for
the clocks and are and
Per-process timers are not inherited by a child process across a and are disarmed and deleted by an
timer_delete()
The function deletes the specified timer, previously created by the function. If the timer is armed when is called, the behavior is as if
the timer is automatically disarmed before removal. Any pending notifications from the timer remain.
timer_settime()
The function sets the time until the next expiration of the timer specified by timerid from the it_value member of the value argument and
arms the timer if the it_value member of value is non-zero. If the specified timer was already armed when is called, this call resets the
time until next expiration to the value specified. If the it_value member of value is zero, the timer is disarmed. Any pending notifica-
tions from the timer remain.
If the flag is not set in the argument flags, behaves as if the time until next expiration is set equal to the interval specified by the
it_value member of value. That is, the timer will expire in it_value nanoseconds from when the call is made.
If the flag is set in the argument flags, behaves as if the time until next expiration is set equal to the difference between the absolute
time specified by the it_value member of value and the current value of the clock associated with timerid. That is, the timer will expire
when the clock reaches the value specified by the it_value member of value. If the specified time has already passed, the function will
succeed and the expiration notification is made.
The reload value of the timer is set to the value specified by the it_interval member of value. When a timer is armed with a non-zero
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 are rounded up to the
larger multiple of the resolution. A quantization error will not cause the timer to expire earlier than the rounded-up time value.
If the argument ovalue is not NULL, the function stores, in the location referenced by ovalue, 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. The members of
ovalue are subject to the resolution of the timer, and are the same values that would be returned by a call at that point in time.
timer_gettime()
The function stores the amount of time until the specified timer, timerid, expires and the timer's reload value into the space pointed to
by the value argument. The it_value member of this structure will contain the amount of time before the timer expires, or zero if the
timer is disarmed. This value is returned as the interval until timer expiration, even if the timer was armed with absolute time. The
it_interval member of value will contain the reload value last set by
timer_getoverrun()
Only a single signal is delivered 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 delivered, and a timer overrun has occurred. When a timer expiration signal is delivered to a process, the function
returns the timer expiration count for the specified timer. The overrun count returned contains the number of extra timer expirations
which occurred between the time the signal was generated and when it was delivered, up to but not including an implementation defined maxi-
mum of If the number of such extra expirations is greater than or equal to then the overrun count is set to The value returned by applies
to the most recent expiration signal delivery for the timer. If no expiration signal has been delivered for the timer, the meaning of the
overrun count returned is undefined.
RETURN VALUE
Upon successful completion, returns zero and updates the location referenced by timerid to a timer_t which can be passed to the per-process
timer calls. Otherwise, returns -1 and sets to indicate the error. The value of timerid is undefined if an error occurs.
Upon successful completion, returns zero. Otherwise, returns -1 and sets to indicate the error.
Upon successful completion, returns zero and updates the location referenced by ovalue, if ovalue is non-NULL.
Upon successful completion, returns zero and updates the location referenced by value, if ovalue is non-NULL. Otherwise, returns -1 and
sets to indicate the error.
Upon successful completion, returns the timer expiration overrun count as explained above. Otherwise, returns -1 and sets to indicate the
error.
ERRORS
If any of the following conditions occur, the function returns -1 and sets (see errno(2)) to the corresponding value:
The system lacks sufficient signal queuing resources to honor the request.
The calling process has already created all of the
timers it is allowed by this implementation.
The specified clock
ID is not defined.
The timerid or evp argument points to an invalid address.
The function
is not supported by this implementation.
If any of the following conditions occur, the function returns -1 and sets to the corresponding value:
The timer ID specified by timerid is not a valid timer ID.
The function
is not supported by this implementation.
If any of the following conditions occur, the and functions return -1 and set to the corresponding value:
The timerid argument does not correspond to an ID returned by but not yet deleted by
The value structure passed to specified a nanosecond value less than zero or greater than or equal to 1000 million.
The value or ovalue argument points to an invalid address.
The and functions are not supported by this implementation.
EXAMPLES
Create a timer, set it to go off in one minute, and deliver a signal:
AUTHOR
and were derived from the proposed IEEE POSIX P1003.4 standard, draft 14.
SEE ALSO
clocks(2), getitimer(2).
STANDARDS CONFORMANCE
timers(2)