setitimer

setitimer

Define an Interval Timer

Portability: UNIX compatible

SYNOPSIS
DESCRIPTION
RETURN VALUE
USAGE NOTES
RELATED FUNCTIONS

SYNOPSIS

#include <sys/time.h>
int setitimer(int kind,
              const struct itimerval *ival,
              struct itimerval *oval);

DESCRIPTION

The setitimer function defines an interval timer, that is, a timer which generates a signal each time a specified time interval expires. Three different forms of time measurement may be specified.

The kind argument is a symbolic constant specifying the type of time interval required. The permitted values are:

ITIMER_REAL - Specifies a real time interval. Each time the interval expires, a SIGALRM signal is generated.
Note: A call to the alarm function will cancel a real time interval defined by setitimer , and similarly, a call to setitimer specifying ITIMER_REAL will cancel an outstanding alarm .
ITIMER_VIRTUAL - Specifies a virtual (CPU) time interval. Each time the interval expires, a SIGVTALRM signal is generated.
ITIMER_PROF - Specifies a profiling interval, measuring CPU time plus system time used in behalf of this process. Each time the interval expires, a SIGPROF signal is generated.

The ival argument specifies the time values controlling the timer. This argument is a pointer to an itimerval structure, which contains two fields defined as follows:

it_value - the time until the next expiration of the timer
it_interval - the time between successive timer expirations.

In other words, the it_value field specifies the amount of time between the setitimer call and the first expiration, while the it_interval field specifies the time between successive expirations. If it_value is specified as zero when setitimer is called, any existing interval is immediately cancelled. If it_interval is specified as zero, the timer will expire once, and then be cancelled.

The it_value and it_interval fields both have type struct timeval , which allows a time value to be specified to an accuracy of a microsecond. The structure has two fields:

tv_sec - the number of seconds in the interval
tv_usec - the number of microseconds to be added to the interval.

The oval argument to setitimer is a pointer to a struct itimerval in which the current interval timer values are to be stored. oval may be specified as NULL , in which case, this information is not stored.

RETURN VALUE

setitimer returns 0 if successful, or -1 if unsuccessful.

USAGE NOTES

The setitimer function can only be used with MVS 5.2.2 or a later release.

Programs which are not invoked from the shell must call the oesigsetup function to enable handling of the timer signals before invoking setitimer .

RELATED FUNCTIONS

getitimer

Chapter Contents
Previous
Next
Top of Page