timer_settime(3)					     Library Functions Manual						  timer_settime(3)

NAME

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

LIBRARY

       Realtime Library (librt.so, librt.a)

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	   Specifies 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	   Specifies a pointer to an itimerspec data structure.

       *ovalue	   Specifies 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 rel-
       ative 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 deter-
       mines 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 mem-
       ber 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  reso-
       lution.

       To disarm a timer, specify a value of 0 (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 (zero) 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 condition:

       [EINVAL]       The timerid argument does not correspond to an ID returned by timer_create and not yet removed by timer_delete.

		      Additionally, 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)

       Guide to Realtime Programming delim off

																  timer_settime(3)