Index for Section 2

Alphabetical listing for G

Bottom of page

getitimer(2)
NAME
  getitimer, setitimer - Return or set the value of interval timers

SYNOPSIS
  #include <sys/time.h>

  int getitimer(
	  int which,
	  struct itimerval *value );

  int setitimer(
	  int which,
	  const struct itimerval *value,
	  struct itimerval *ovalue );

  The following definition of the setitimer() function does not conform to
  current standards and is supported only for backward compatibility:

  int setitimer(
	  int which,
	  struct itimerval *value,
	  struct itimerval *ovalue );

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  getitimer(), setitimer(): XSH4.2, XSH5.0

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  which	  Identifies the interval timer. This parameter may be expressed as
	  one of three symbolic constants: ITIMER_REAL, ITIMER_VIRTUAL, and
	  ITIMER_PROF.

  value	  Points to an itimerval structure whose members specify a timer
	  interval and the time left to the end of the interval.

  ovalue  Points to an itimerval structure whose members specify a current
	  timer interval and the time left to the end of the interval.

DESCRIPTION
  The getitimer() function returns the current value for the timer specified
  by the which parameter in the structure pointed to by the value parameter.

  The setitimer() function sets the timer specified by which to the specified
  value (returning the previous value of the timer if ovalue is nonzero).

  A timer value is defined by the itimerval structure:

       struct itimerval {
	 struct	       timeval it_interval;
	 struct	       timeval it_value;
       };

  If the it_value field is nonzero, it indicates the time to the next timer
  expiration. If the it_interval field is nonzero, it specifies a value to be
  used in reloading it_value when the timer expires. Setting it_value to 0
  (zero) disables a timer. Setting it_interval to 0 causes a timer to be
  disabled after its next expiration (assuming it_value is nonzero).

  Time values smaller than the resolution of the system clock are rounded up
  to this resolution.

  The system provides each process with three interval timers, defined in the
  <sys/time.h> header file:

  ITIMER_REAL
	  Decrements in real time. A SIGALRM signal is delivered when this
	  timer expires.

  ITIMER_VIRTUAL
	  Decrements in process virtual time. It runs only when the process
	  is executing. A SIGVTALRM signal is delivered when it expires.

  ITIMER_PROF
	  Decrements both in process virtual time and when the system is
	  running on behalf of the process.  It is designed to be used by
	  interpreters in statistically profiling the execution of
	  interpreted programs. Each time the ITIMER_PROF timer expires, the
	  SIGPROF signal is delivered. Because this signal may interrupt in-
	  progress system calls, programs using this timer must be prepared
	  to restart interrupted system calls.

NOTES
  The following information applies only to the backward-compatible versions
  of the getitimer() and setitimer() functions.

  Three macros for manipulating time values are defined in the <sys/time.h>
  header file. The timerclear() macro sets a time value to zero, the
  timerisset() macro tests if a time value is nonzero, and the timercmp()
  macro compares two time values. Beware that the comparisons >= and <= do
  not work with the timercmp() macro.

RETURN VALUES
  Upon successful completion, the value 0 (zero) is returned. Otherwise, -1
  is returned and errno is set to indicate the error.

ERRORS
  The setitimer() function sets errno to the specified values for the
  following conditions:

  [EFAULT]
	  [Tru64 UNIX]	The value parameter specified a bad address.

  [EINVAL]
	  The value parameter specified a time that was too large to be
	  handled, or was a negative time value, or the which value is not
	  defined.

  The getitimer() function sets errno to the specified values for the
  following conditions:

  [EFAULT]
	  [Tru64 UNIX]	The value parameter specified a bad address.

  [EINVAL]
	  The which value is not defined.

	  [Tru64 UNIX]	The value parameter specified a time that was too
	  large to be handled.

SEE ALSO
  Functions: gettimeofday(2)

  Standards: standards(5)

Index for Section 2

Alphabetical listing for G

Top of page