Index for Section 3

Alphabetical listing for T

Bottom of page

timer_settime(3)
NAME
  timer_settime, timer_gettime - Obtains or sets 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);

LIBRARY
  Realtime Library (librt.so, librt.a)

PARAMETERS
  timerid
      Specifies the timer ID for the timer whose expiration time is set or
      returned.

  options
      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 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 option determines
  whether the timer is an absolute or relative timer. If the TIMER_ABSTIME
  option is not set (options=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 option 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 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.

SEE ALSO
  Functions: clock_gettime(3), timer_create(3)

  Guide to Realtime Programming

Index for Section 3

Alphabetical listing for T

Top of page