DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

getitimer(S-osr5)


getitimer, setitimer -- get and set value of interval timers

Syntax

cc . . . -lc

#include  <sys/select.h>
#include  <sys/itimer.h>

getitimer(which, value) int which; struct itimerval *value);

setitimer(which, value, ovalue) int which; const struct itimerval *value; struct itimerval *ovalue;

Description

Each process has three interval timers or ``itimers'' associated with it. At the expiration of a programmed amount of time, an interval timer signals the process and (optionally) automatically reloads itself to re-interrupt the process at programmed intervals. Each itimer counts a different type of time, and generates a different signal upon expiration:


ITIMER_REAL
Counts in real (wall-clock) time. A SIGALRM is generated when this itimer expires. alarm(S-osr5) is a lower-precision non-reloading ITIMER_REAL; a process may have either an alarm, a ITIMER_REAL, or neither, but never both simultaneously.

ITIMER_VIRT
Counts in process-virtual time. It runs only when the process is executing in user mode. A SIGVTALRM is generated when this itimer expires.

ITIMER_PROF
Counts in both process-virtual time and the time when the system is running on behalf of the process. A SIGPROF is generated when this itimer expires.

Each itimer counts by decrementing the programmed amount towards zero.

The getitimer function returns the current value for the itimer specified by the which parameter in the structure pointed to by the value parameter.

The setitimer function programs the which itimer to the specified value. If the ovalue pointer is not NULL, the previous setting is returned in the itimerval structure pointed to by ovalue.

An itimer is defined by the itimerval structure defined in <sys/itimer.h> and the timeval structure defined in <sys/select.h>:

   struct itimerval {
           struct timeval  it_interval;    /* timer interval */
           struct timeval  it_value;       /* current value */
   }
   

struct timeval { long tv_sec; /* seconds */ long tv_usec; /* and microseconds */ }

If the it_value member is nonzero, it indicates the time to the next itimer expiration. This member is decremented as time advances. If the it_interval member is nonzero, it specifies a value to be used in reloading it_value when the itimer expires.

Setting it_value to zero disables an itimer. Setting it_interval to zero causes an itimer to be disabled after its next expiration (assuming it_value is nonzero).

The child process does not inherit its parent's itimers after a fork(S-osr5); that is, all of the child's itimers are disabled. Interval timer settings are not changed by exec(S-osr5).

Both the it_value and it_interval members have microsecond precision. The tv_sec member indicates the number of seconds, and tv_usec the millionths of a second. A timeval structure is zero only when both tv_sec and tv_usec are zero.

The accuracy of an itimer depends on the system's load; the busier the system, the greater the delay between the generation of the signal and its delivery to the process. An itimer never expires before it is programmed to expire, but on sufficiently busy systems (or with very short itimer intervals), a signal may not be delivered before the subsequent one is generated. Signals do not't queue, so only one signal will be delivered. The system compensates and does not allow the itimer to drift; each successive signal is generated when it is programmed to occur and is not dependent on whether or when the prior signal was delivered.

Four macros are defined in <sys/itimer.h> for manipulating timeval structures:

   timercopy(
           const struct timeval    source,
           struct timeval          destination
   )

The timercopy macro copies the structure pointed to by source to that pointed to by destination .

   timerisset(
           const struct timeval    timvalptr
   )

The timerisset macro is nonzero (true) if the structure pointed to by timvalptr is nonzero.

   timerclear(
           struct timeval  timvalptr
   )

The timerclear macro zeros the structure pointed to by timvalptr .

   timercmp(
           const struct timeval    leftvptr,
           const struct timeval    rightvptr,
           operator
   )

The timercmp macro compares the two intervals defined by the structures pointed to by lefttvptr and righttvptr according to the specified operator
(<, ==, !=, or >):

   (lefttvptr's interval) operator (righttvptr's interval)
The <= and >= operators do not work with the timercmp macro.

The getitimer( ) system call fails if one or more of the following is true:


[EINVAL]
which is not ITIMER_REAL, ITIMER_VIRT, or ITIMER_PROF.

[EINVAL]
value is NULL.

[EFAULT]
value points outside the allocated address space of the process.

[ENOSYS]
Interval timers are either not installed or not supported on this system; a SIGSYS signal is also generated.

The setitimer( ) system call fails if one of more of the following is true, and the current itimer setting is not changed:


[EINVAL]
which is not ITIMER_REAL, ITIMER_VIRT, or ITIMER_PROF.

[EINVAL]
value is NULL.

[EINVAL]
Either value ->it_value or value ->it_interval is not normalized: Either ``tv_sec'' is negative or over ten million seconds, or ``tv_usec'' is negative or over 999,999 microseconds.

[EFAULT]
Either ovalue or value points outside the allocated address space of the process.

[ENOMEM]
There are insufficient system resources to program the itimer. In this case the current which itimer setting is lost, disabling that itimer.

[ENOSYS]
Interval timers are either not installed or not supported on this system; a SIGSYS signal is also generated.

Diagnostics

Upon successful completion, a value of zero is returned. Otherwise, a value of -1 is returned, and errno is set to indicate the error.

Notes

Older systems do not have itimers, and itimers may be deconfigured (not present) in newer systems (by disabling the itimer pseudo-driver). If either the getitimer( ) or setitimer( ) system call is attempted when itimers are not available, a SIGSYS signal results. The itimer pseudo-driver will not function in older systems.

Other vendors' systems may use the <sys/time.h> header file instead of <sys/itimer.h>.

Any call to alarm( ) disables the ITIMER_REAL. Any (successful) call to setitimer( ) disables any alarm. getitimer( ) returns information about whichever of alarm( ) and ITIMER_REAL. is currently enabled.

Older versions of sleep(S-osr5) may inadvertently convert a ITIMER_REAL into an alarm, which has only seconds precision and is not reloaded when it expires.

The ITIMER_PROF interval timer is traditionally used by interpreters to statistically profile interpreted code. The generated SIGPROF may interrupt in-progress system calls. There is no facility to restart such interrupted system calls, so this itimer may not be very useful for such profiling.

Differences between versions

The resolution of getitimer( ) and setitimer( ) is improved by the high-precision system clock implemented for SCO OpenServer Release 5.0.6 and later releases; see clock(HW) for more information. The following notes apply to using these calls on earlier releases of the operating system that do not support the high-precision system clock:

See Also

alarm(S-osr5), clock(HW), exec(S-osr5), fork(S-osr5), gethz(S-osr5), sigaction(S-osr5), signal(M), signal(S-osr5), sleep(S-osr5), sysconf(S-osr5)

Standards conformance

getitimer and setitimer are not part of any currently supported standard; they were developed at the University of California at Berkeley and are used by permission.
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 -- 02 June 2005