Index for Section 3

Alphabetical listing for T

Bottom of page

timer_settime(3)
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)

Index for Section 3

Alphabetical listing for T

Top of page