gettimer, settimer, restimer, stime, or time Subroutine

Purpose

Gets or sets the current value for the specified systemwide timer.

Library

Standard C Library (libc.a)

Syntax

#include <sys/time.h>
#include <sys/types.h>

int gettimer( TimerType,  Value)
timer_t TimerType;
struct timestruc_t * Value;

#include <sys/timers.h>
#include <sys/types.h>

int gettimer( TimerType,  Value)
timer_t TimerType;
struct itimerspec * Value;

int settimer(TimerType,  TimePointer)
int TimerType;
const struct timestruc_t *TimePointer;

int restimer(TimerType,  Resolution,  MaximumValue)
int TimerType;
struct timestruc_t *Resolution, *MaximumValue;

int stime( Tp)
long *Tp;

#include <sys/types.h>
time_t time(Tp)
time_t *Tp; 

Description

The settimer subroutine is used to set the current value of the TimePointer parameter for the systemwide timer, specified by the TimerType parameter.

When the gettimer subroutine is used with the function prototype in sys/timers.h, then except for the parameters, the gettimer subroutine is identical to the getinterval (getinterval, incinterval, absinterval, resinc, resabs, alarm, ualarm, getitimer or setitimer Subroutine) subroutine. Use of the getinterval subroutine is recommended, unless the gettimer subroutine is required for a standards-conformant application. The description and semantics of the gettimer subroutine are subject to change between releases, pending changes in the draft standard upon which the current gettimer subroutine description is based.

When the gettimer subroutine is used with the function prototype in /sys/timers.h, the gettimer subroutine returns an itimerspec structure to the pointer specified by the Value parameter. The it_value member of the itimerspec structure represents the amount of time in the current interval before the timer (specified by the TimerType parameter) expires, or a zero interval if the timer is disabled. The members of the pointer specified by the Value parameter are subject to the resolution of the timer.

When the gettimer subroutine is used with the function prototype in sys/time.h, the gettimer subroutine returns a timestruc structure to the pointer specified by the Value parameter. This structure holds the current value of the system wide timer specified by the Value parameter.

The resolution of any timer can be obtained by the restimer subroutine. The Resolution parameter represents the resolution of the specified timer. The MaximumValue parameter represents the maximum possible timer value. The value of these parameters are the resolution accepted by the settimer subroutine.

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 time subroutine returns the time in seconds since the Epoch (that is, 00:00:00 GMT, January 1, 1970). The Tp parameter points to an area where the return value is also stored. If the Tp parameter is a null pointer, no value is stored.

The stime subroutine is implemented to provide compatibility with older AIX®, AT&T System V, and BSD systems. It calls the settimer subroutine using the TIMEOFDAY timer.

Parameters

Item Description
Value Points to a structure of type itimerspec.
TimerType Specifies the systemwide timer:
TIMEOFDAY
(POSIX system clock timer) This timer represents the time-of-day clock for the system. For this timer, the values returned by the gettimer subroutine and specified by the settimer subroutine represent the amount of time since 00:00:00 GMT, January 1, 1970.
TimePointer Points to a structure of type struct timestruc_t.
Resolution The resolution of a specified timer.
MaximumValue The maximum possible timer value.
Tp Points to a structure containing the time in seconds.

Return Values

The gettimer, settimer, restimer, and stime subroutines return a value of 0 (zero) if the call is successful. A return value of -1 indicates an error occurred, and errno is set.

The time subroutine returns the value of time in seconds since Epoch. Otherwise, a value of ((time_t) - 1) is returned and the errno global variable is set to indicate the error.

Error Codes

If an error occurs in the gettimer, settimer, restimer, or stime subroutine, a return value of - 1 is received and the errno global variable is set to one of the following error codes:

Item Description
EINVAL The TimerType parameter does not specify a known systemwide timer, or the TimePointer parameter of the settimer subroutine is outside the range for the specified systemwide timer.
EFAULT A parameter address referenced memory that was not valid.
EIO An error occurred while accessing the timer device.
EPERM The requesting process does not have the appropriate privilege to set the specified timer.

If the time subroutine is unsuccessful, a return value of -1 is received and the errno global variable is set to the following:

Item Description
EFAULT A parameter address referenced memory that was not valid.