Technical Reference: Base Operating System and Extensions, Volume 1

getinterval, incinterval, absinterval, resinc, resabs, alarm, ualarm, getitimer or setitimer Subroutine

Purpose

Manipulates the expiration time of interval timers.

Library

Standard C Library (libc.a)

Syntax

#include <sys/time.h> int getinterval ( TimerID, Value) timer_t TimerID; struct itimerstruc_t *Value; int incinterval (TimerID, Value, OValue) timer_t TimerID; struct itimerstruc_t *Value, *OValue; int absinterval (TimerID, Value, OValue) timer_t TimerID; struct itimerstruc_t *Value, *OValue; int resabs (TimerID, Resolution, Maximum) timer_t TimerID; struct timestruc_t *Resolution, *Maximum; int resinc (TimerID, Resolution, Maximum) timer_t TimerID; struct timestruc_t *Resolution, *Maximum;

#include <unistd.h>

unsigned int alarm ( Seconds) unsigned int Seconds; useconds_t ualarm (Value, Interval) useconds_t Value, Interval; int setitimer ( Which, Value, OValue) int Which; struct itimerval *Value, *OValue; int getitimer (Which, Value) int Which; struct itimerval *Value;

Description

The getinterval, incinterval, and absinterval subroutines manipulate the expiration time of interval timers. These functions use a timer value defined by the struct itimerstruc_t structure, which includes the following fields:

struct timestruc_t it_interval;   /* timer interval period      */
struct timestruc_t it_value;      /* timer interval expiration  */

If the it_value field is nonzero, it indicates the time to the next timer expiration. If it_value is 0, the per-process timer is disabled. If the it_interval member is nonzero, it specifies a value to be used in reloading the it_value field when the timer expires. If it_interval is 0, the timer is to be disabled after its next expiration (assuming it_value is nonzero).

The getinterval subroutine returns a value from the struct itimerstruc_t structure to the Value parameter. The it_value field of this structure represents the amount of time in the current interval before the timer expires, should one exist for the per-process timer specified in the TimerID parameter. The it_interval field has the value last set by the incinterval or absinterval subroutine. The fields of the Value parameter are subject to the resolution of the timer.

The incinterval subroutine sets the value of a per-process timer to a given offset from the current timer setting. The absinterval subroutine sets the value of the per-process timer to a given absolute value. If the specified absolute time has already expired, the absinterval subroutine will succeed and the expiration notification will be made. Both subroutines update the interval timer period. Time values smaller than the resolution of the specified timer are rounded up to this resolution. Time values larger than the maximum value of the specified timer are rounded down to the maximum value.

The resinc and resabs subroutines return the resolution and maximum value of the interval timer contained in the TimerID parameter. The resolution of the interval timer is contained in the Resolution parameter, and the maximum value is contained in the Maximum parameter. These values might not be the same as the values returned by the corresponding system timer, the gettimer subroutine. In addition, it is likely that the maximum values returned by the resinc and resabs subroutines will be different.

Note

If a nonprivileged user attempts to submit a fine granularity timer (that is, a timer request of less than 10 milliseconds), the timer request is raised to 10 milliseconds.

The alarm subroutine causes the system to send the calling thread's process a SIGALRM signal after the number of real-time seconds specified by the Seconds parameter have elapsed. Since the signal is sent to the process, in a multi-threaded process another thread than the one that called the alarm subroutine may receive the SIGALRM signal. Processor scheduling delays may prevent the process from handling the signal as soon as it is generated. If the value of the Seconds parameter is 0, a pending alarm request, if any, is canceled. Alarm requests are not stacked. Only one SIGALRM generation can be scheduled in this manner. If the SIGALRM signal has not yet been generated, the call results in rescheduling the time at which the SIGALRM signal is generated. If several threads in a process call the alarm subroutine, only the last call will be effective.

The ualarm subroutine sends a SIGALRM signal to the invoking process in a specified number of seconds. The getitimer subroutine gets the value of an interval timer. The setitimer subroutine sets the value of an interval timer.

Parameters

TimerID	Specifies the ID of the interval timer.
Value	Points to a struct itimerstruc_t structure.
OValue	Represents the previous time-out period.
Resolution	Resolution of the timer.
Maximum	Indicates the maximum value of the interval timer.
Seconds	Specifies the number of real-time seconds to elapse before the first SIGALRM signal.
Interval	Specifies the number of microseconds between subsequent periodic SIGALRM signals. If a nonprivileged user attempts to submit a fine granularity timer (that is, a timer request of less than 10 milliseconds), the timer request interval is automatically raised to 10 milliseconds.
Which	Identifies the type of timer. Valid values are: ITIMER_REAL Decrements in real time. A SIGALRM signal occurs when this timer expires. ITIMER_VIRTUAL Decrements in process virtual time. It runs only during process execution. A SIGVTALRM signal occurs when it expires. ITIMER_PROF Decrements in process virtual time and when the system runs on behalf of the process. It is designed for use by interpreters in statistically profiling the execution of interpreted programs. Each time the ITIMER_PROF timer expires, the SIGPROF signal occurs. Because this signal may interrupt in-progress system calls, programs using this timer must be prepared to restart interrupted system calls.

Return Values

If these subroutines are successful, a value of 0 is returned. If an error occurs, a value of -1 is returned and the errno global variable is set.

The alarm subroutine returns the amount of time (in seconds) remaining before the system is scheduled to generate the SIGALARM signal from the previous call to alarm. It returns a 0 if there was no previous alarm request.

The ualarm subroutine returns the number of microseconds previously remaining in the alarm clock.

Error Codes

If the getinterval, incinterval, absinterval, resinc, resabs, setitimer, getitimer, or setitimer subroutine is unsuccessful , a value of -1 is returned and the errno global variable is set to one of the following error codes:

EINVAL	Indicates that the TimerID parameter does not correspond to an ID returned by the gettimerid subroutine, or a value structure specified a nanosecond value less than 0 or greater than or equal to one thousand million (1,000,000,000).
EIO	Indicates that an error occurred while accessing the timer device.
EFAULT	Indicates that a parameter address has referenced invalid memory.

The alarm subroutine is always successful. No return value is reserved to indicate an error for it.

Related Information

The gettimer (gettimer, settimer, restimer, stime, or time Subroutine) subroutine, gettimerid (gettimerid Subroutine) subroutine, sigaction, sigvec, or signal subroutine.

List of Time Data Manipulation Services in AIX 5L Version 5.2 System Management Concepts: Operating System and Devices.

Subroutines Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

Signal Management in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs provides more information about signal management in multi-threaded processes.