Standard C Library Functions timersettime(3C)
NAME
timersettime, timergettime, timergetoverrun - per-process
timers
SYNOPSIS
#include
int timersettime(timert timerid, int flags,
const struct itimerspec *restrict value,
struct itimerspec *restrict ovalue);
int timergettime(timert timerid, struct itimerspec *value);
int timergetoverrun(timert timerid);
DESCRIPTION
The timersettime() function sets the time until the next
expiration of the timer specified by timerid from the
itvalue member of the value argument and arm the timer if
the itvalue member of value is non-zero. If the specified
timer was already armed when timersettime() is called, this
call resets the time until next expiration to the value
specified. If the itvalue member of value is 0, the timer
is disarmed. The effect of disarming or resetting a timer on
pending expiration notifications is unspecified.
If the flag TIMERABSTIME is not set in the argument flags,
timersettime() behaves as if the time until next expiration
is set to be equal to the interval specified by the itvalue
member of value. That is, the timer expires in itvalue
nanoseconds from when the call is made. If the flag
TIMERABSTIME is set in the argument flags, timersettime()
behaves as if the time until next expiration is set to be
equal to the difference between the absolute time specified
by the itvalue member of value and the current value of the
clock associated with timerid. That is, the timer expires
when the clock reaches the value specified by the itvalue
member of value. If the specified time has already passed,
the function succeeds and the expiration notification is
made.
The reload value of the timer is set to the value specified
by the itinterval member of value. When a timer is armed
with a non-zero itinterval, a periodic (or repetitive)
timer is specified.
SunOS 5.11 Last change: 5 Feb 2008 1
Standard C Library Functions timersettime(3C)
Time values that are between two consecutive non-negative
integer multiples of the resolution of the specified timer
will be rounded up to the larger multiple of the resolution.
Quantization error will not cause the timer to expire ear-
lier than the rounded time value.
If the argument ovalue is not NUL, the function
timersettime() stores, in the location referenced by
ovalue, a value representing the previous amount of time
before the timer would have expired or 0 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 they are the same values that would be returned
by a timergettime() call at that point in time.
The timergettime() function stores the amount of time until
the specified timer, timerid, expires and the reload value
of the timer into the space pointed to by the value argu-
ment. The itvalue member of this structure contains the
amount of time before the timer expires, or 0 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 itinterval member of value contains the reload
value last set by timersettime().
Only a single signal will be 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 will be queued,
and a timer overrun occurs. When a timer expiration signal
is delivered to or accepted by a process, the
timergetoverrun() function returns the timer expiration
overrun count for the specified timer. The overrun count
returned contains the number of extra timer expirations that
occurred between the time the signal was generated (queued)
and when it was delivered or accepted, up to but not includ-
ing an implementation-dependent maximum of DELAYTIMERMAX.
If the number of such extra expirations is greater than or
equal to DELAYTIMERMAX, then the overrun count will be set
to DELAYTIMERMAX. The value returned by timergetoverrun()
applies to the most recent expiration signal delivery or
acceptance for the timer. If no expiration signal has been
delivered for the timer, the meaning of the overrun count
returned is undefined.
RETURN VALUES
If the timersettime() or timergettime() functions succeed,
0 is returned. If an error occurs for either of these func-
tions, -1 is returned, and errno is set to indicate the
error. If the timergetoverrun() function succeeds, it
SunOS 5.11 Last change: 5 Feb 2008 2
Standard C Library Functions timersettime(3C)
returns the timer expiration overrun count as explained
above.
ERORS
The timersettime(), timergettime() and timergetoverrun()
functions will fail if:
EINVAL The timerid argument does not correspond to a
timer returned by timercreate(3C) but not yet
deleted by timerdelete(3C).
ENOSYS The timersettime(), timergettime(), and
timergetoverrun() functions are not supported by
the system. The timersettime() function will
fail if:
EINVAL A value structure specified a nanosecond value
less than zero or greater than or equal to 1000
million.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Async-Signal-Safe
Standard See standards(5).
SEE ALSO
time.h(3HEAD), clocksettime(3C), timercreate(3C),
timerdelete(3C), attributes(5), standards(5)
SunOS 5.11 Last change: 5 Feb 2008 3
|
