getitimer

GETITIMER(2)		  Linux Programmer’s Manual		 GETITIMER(2)



NAME
       getitimer, setitimer - get or set value of an interval timer

SYNOPSIS
       #include <sys/time.h>

       int getitimer(int which, struct itimerval *value);
       int setitimer(int which, const struct itimerval *value, struct itimer-
	      val *ovalue);

DESCRIPTION
       The system provides each process	 with  three  interval	timers,	 each
       decrementing  in	 a  distinct  time domain.  When any timer expires, a
       signal is sent to the process, and the timer (potentially) restarts.

       ITIMER_REAL    decrements in real  time,	 and  delivers	SIGALRM	 upon
		      expiration.

       ITIMER_VIRTUAL decrements  only	when  the  process  is executing, and
		      delivers SIGVTALRM upon expiration.

       ITIMER_PROF    decrements both when the process executes and when  the
		      system  is executing on behalf of the process.  Coupled
		      with ITIMER_VIRTUAL, this timer is usually used to pro-
		      file the time spent by the application in user and ker-
		      nel space.  SIGPROF is delivered upon expiration.

       Timer values are defined by the following structures:
	    struct itimerval {
		struct timeval it_interval; /* next value */
		struct timeval it_value;    /* current value */
	    };
	    struct timeval {
		long tv_sec;		    /* seconds */
		long tv_usec;		    /* microseconds */
	    };

       The function getitimer fills the structure indicated by value with the
       current	setting for the timer indicated by which (one of ITIMER_REAL,
       ITIMER_VIRTUAL, or ITIMER_PROF).	 The element it_value is set  to  the
       amount  of  time	 remaining on the timer, or zero if the timer is dis-
       abled.  Similarly, it_interval is set to the reset value.   The	func-
       tion  setitimer	sets  the  indicated timer to the value in value.  If
       ovalue is nonzero, the old value of the timer is stored there.

       Timers decrement from it_value to zero, generate a signal,  and	reset
       to it_interval.	A timer which is set to zero (it_value is zero or the
       timer expires and it_interval is zero) stops.

       Both tv_sec and tv_usec are significant in determining the duration of
       a timer.

       Timers  will  never expire before the requested time, instead expiring
       some short, constant time afterwards, dependent on  the	system	timer
       resolution (currently 10ms).  Upon expiration, a signal will be gener-
       ated and the timer reset.  If the timer expires while the  process  is
       active  (always	true  for  ITIMER_VIRT)	 the signal will be delivered
       immediately when generated.  Otherwise the delivery will be offset  by
       a small time dependent on the system loading.


RETURN VALUE
       On  success, zero is returned.  On error, -1 is returned, and errno is
       set appropriately.

ERRORS
       EFAULT value or ovalue are not valid pointers.

       EINVAL which is not one of ITIMER_REAL, ITIMER_VIRT, or ITIMER_PROF.

CONFORMING TO
       SVr4, 4.4BSD (This call first appeared in 4.2BSD).

SEE ALSO
       gettimeofday(2), sigaction(2), signal(2)

BUGS
       Under Linux, the generation and delivery of a signal are distinct, and
       there  each  signal  is	permitted  only	 one outstanding event.	 It’s
       therefore  conceivable  that  under  pathologically   heavy   loading,
       ITIMER_REAL  will  expire before the signal from a previous expiration
       has been delivered.  The second signal in such an event will be	lost.



Linux 0.99.11			  1993-08-05			 GETITIMER(2)