Content-type: text/html Man page of timer_settime

timer_settime

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

timer_settime, timer_gettime - Get or set the expiration time of the specified per-process timer (P1003.1b)  

SYNOPSIS

#include <time.h>

int timer_gettime (
timer_t timerid,
struct itimerspec *value);

int timer_settime (
timer_t timerid,
int flags,
const struct itimerspec *value,
struct itimerspec *ovalue);  

PARAMETERS

timerid
The timer ID for the timer whose expiration time is set or returned.
flags
Specifies whether the timer is to be an absolute or relative timer.
*value
A pointer to an itimerspec data structure.
*ovalue
A pointer to the itimerspec data structure into which the time remaining on the previous timer is returned.
 

DESCRIPTION

The timer_gettime function returns the amount of time remaining in the current time interval before the expiration of the specified timer. The timer_settime function sets the expiration time of the specified per-process timer, determines whether the timer is an absolute or relative timer, returns the time remaining (if any) on the previous specified timer, and arms the timer.

Both the timer_gettime and timer_settime functions use an itimerspec structure, which consists of the following members:

struct
timespec it_interval;
struct
timespec it_value;

Each timespec structure consists of the following members:

time_t
tv_sec;
long
tv_nsec;

Values specified for these members determine the duration of the timer intervals, as well as the start and end times.

Use the timer_gettime function to determine whether a per-process timer is still active. If the timer is disabled, zero is returned.

The timer_settime function sets the expiration time of the specified per-process timer and arms the timer. The TIMER_ABSTIME flag determines whether the timer is an absolute or relative timer. If the TIMER_ABSTIME flag is not set (flags=0), the timer is set relative to the current time (a relative timer). In this case, the time until the next timer expiration equals the interval specified by the it_value member of value. The timer expires in the specified number of seconds and nanoseconds from when the call was made.

If the TIMER_ABSTIME flag is set, the timer is set with a specified starting time (an absolute timer). In this case, the time until the next timer expiration equals the difference between the absolute time specified by the it_value member of value and the current value of the clock associated with the timer ID. The timer expires when the clock reaches the value specified by it_value member.

Times that are between two consecutive non-negative integer multiples of the resolution are rounded up to the larger multiple of the resolution.

To disarm a timer, specify a value of zero for the it_value member and call the timer_settime function.

The reload value to the timer is set to the value specified by the it_interval member of value. If the it_interval is zero, a one-shot timer is specified. If the it_interval is non-zero, a periodic timer is specified.  

RETURN VALUES

On a successful call to the timer_gettime and timer_settime functions, a value of 0 is returned.

On an unsuccessful call, a value of -1 is returned and errno is set to indicate that an error occurred.  

ERRORS

The timer_gettime and timer_settime functions fail under the following conditions:

[EINVAL]
The timerid argument does not correspond to an id returned by timer_create, but not yet removed by timer_delete.

The timer_settime function can fail with this error if a value structure specified a nanosecond value less than zero or greater than or equal to 1000 million.

 

RELATED INFORMATION

Functions: clock_gettime(3), timer_create(3) delim off


 

Index

NAME
SYNOPSIS
PARAMETERS
DESCRIPTION
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:42:30 GMT, October 02, 2010