timer_settime(2) DG/UX 5.4 Rel. 2.01 timer_settime(2)
NAME
timer_settime - set the expiration time for a per-process timer
SYNOPSIS
#include <time.h>
int timersettime (timerid, absrelflag, *newval, *oldval)
timert timerid;
int absrelflag;
struct itimerspec*newval;
struct itimerspec*oldval;
DESCRIPTION
Use timersettime(2) to specify when a per-process timer should
expire and the interval of a periodic timer, or to enable or disable
a timer:
timerid is the timer identifier established by timercreate(2).
absrelflag
is 0 or TIMER_ABSTIME, indicating whether an expiration
value passed in newval.itvalue is relative to the current
time or is an absolute Greenwich Mean Time (GMT) value (see
below).
newval points to a structure containing the values to be used in
setting the expiration of timerid.
oldval points to a structure containing the current (old)
expiration setting of timerid.
The structure pointed to by newval and oldval and a contained
structure are shown below:
struct itimerspec
{
struct timespec itinterval;
struct timespec itvalue;
};
struct timespec
{
timet tvsec;
long tvnsec;
};
Input: Contents of newval
Prior to making this call, set the itvalue and itinterval members
of newval as indicated below.
The itvalue member contains the expiration time for the timer
timerid. Its interpretation depends on absrelflag:
0 timerid will expire in itvalue units (seconds and
Licensed material--property of copyright holder(s) 1
timer_settime(2) DG/UX 5.4 Rel. 2.01 timer_settime(2)
nanoseconds) after the time of this call's successful
completion.
TIMER_ABSTIME
timerid will expire when it reaches the absolute time
indicated by itvalue. If you specify an absolute
expiration time that has already passed, the call will
succeed and the expiration signal will be sent.
Any value of absrelflag other than TIMER_ABSTIME is interpreted the
same as 0. The absrelflag affects only the itvalue member.
To disable a timer timerid, set itvalue to 0; to enable the timer,
set itvalue to >0. Disabling a timer does not affect any pending
signals from the timer, which will still be sent.
What happens to timerid upon expiration depends on the value of
itinterval:
0 timerid is a one-shot timer. Upon expiration, it is disabled.
>0 timerid is a periodic timer. Upon expiration, it begins a new
cycle of itinterval duration.
If the values specified for itinterval and itvalue fall between
consecutive non-negative integer multiples of the timer resolution,
they are rounded up to the larger multiple.
Negative values in itinterval and itvalue (absolute or relative)
are treated as times that have already passed.
Output: Updating of oldval
Pointer oldval may be NULL. If it is, the expiration time and reload
values of timerid that are replaced by this call (when successful)
are not saved. If oldval is not NULL, the structure it points to is
updated in the manner explained in timergettime(2) and repeated
below:
itvalue contains the time remaining until timerid was set to
expire. Even if timerid was enabled with absolute time,
this member contains the interval until next expiration.
A value of 0 indicates that timerid was disabled.
itinterval contains the reload value that was set, rounded up to a
multiple of the timer resolution. A value of 0 indicates
that timerid was set to be disabled upon expiration (a
one-shot timer). A value >0 indicates the timer was set
to begin a new cycle of itinterval duration upon
expiration (a periodic timer).
Note
* This routine is based on POSIX realtime extension document P1003.4
draft 12. It is therefore subject to change.
Licensed material--property of copyright holder(s) 2
timer_settime(2) DG/UX 5.4 Rel. 2.01 timer_settime(2)
* Compilation of a source file using this routine requires that
feature macro _POSIX4_DRAFT_SOURCE be defined. This feature macro
is not enabled by any other feature macro, nor does it enable any
other feature macro.
* The compiled routine must be linked to library librte.a.
RETURN VALUE
If successful, timersettime returns 0. If unsuccessful, the routine
returns -1 and sets ERRNO to one of the following:
EFAULT The caller does not have read access to one or more bytes of
the space pointed to by newval.
EFAULT The caller does not have write access to one or more bytes of
the space pointed to by oldval.
Note that this ERRNO is set even if the timer was actually
set to the contents of newval.
EINVAL The value of timerid is invalid.
EINVAL The value of the itinterval.tvnsec or itvalue.tvnsec
member is out of range (> 1,000,000,000).
EINVAL Rounding the values of newval to the clock resolution caused
the seconds field tvsec of structure timespec to change
sign.
EXAMPLES
The following code fragment creates a timer that goes off in two
hours, then every two seconds thereafter:
newval.itvalue.tvsec = 60 * 60 * 2;
newval.itvalue.tvnsec = 0;
newval.itinterval.tvsec = 2;
newval.itinterval.tvnsec = 0;
timerid = timercreate(CLOCKREALTIME, NULL);
timersettime( timerid, 0, &newval, &oldval );
The following code fragment sets a timer to go off January 1, 1993 at
midnight, then every hour thereafter. To do this you use an absolute
timer, calculate the absolute time (in seconds) to midnight on
January 1, 1993, and specifiy this value as the initial expiration
time. The cyclic timer is simply set to one hour.
The CLOCK_REALTIME clock is based on GMT; i.e. seconds since midnight
on January 1, 1970. The initial absolute time is the number of
seconds from midnight January 1, 1970 to midnight January 1, 1993.
newval.itvalue.tvsec = { secs from 1/1/70 midnight to 1/1/93
midnight };
newval.itvalue.tvnsec = 0;
Licensed material--property of copyright holder(s) 3
timer_settime(2) DG/UX 5.4 Rel. 2.01 timer_settime(2)
newval.itinterval.tvsec = 3600;
newval.itinterval.tvnsec = 0;
timerid = timercreate(CLOCKREALTIME, NULL);
timersettime( timerid, TIMERABSTIME, &newval, &oldval );
SEE ALSO
clockgetres(2), timercreate(2), timerdelete(2), timergettime(2),
timergetoverrun(2).
Licensed material--property of copyright holder(s) 4