getitimer(2)							System Calls Manual						      getitimer(2)

NAME

       getitimer(), setitimer() - get and set value of interval timer

SYNOPSIS

DESCRIPTION

       The  function stores the current value of the timer specified by which into the structure pointed to by value.  The function sets the timer
       specified by which to the value specified in the structure pointed to by value, and if ovalue is not a null pointer,  stores  the  previous
       value of the timer in the structure pointed to by ovalue.

       The header declares the structure:

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

       Implementations may place limitations on the granularity of timer values.  For each interval timer, if the requested timer value requires a
       finer granularity than the implementation supports, the actual timer value will be rounded up to the next supported  value.   Timer  values
       smaller	than  the  resolution  of  the system clock are rounded up to this resolution.	The machine-dependent clock resolution is seconds,
       where the constant is defined in To make sure that a process gets at least as much time as requested, the timer value is rounded up to  the
       next  timer  tick  (a timer tick is the smallest supported value).  The timer value is rounded up to the next timer tick, because the timer
       may be initialized somewhere between timer ticks.  If a is followed by a without a timer tick in between, it is	possible  that	the  value
       returned by may be more than the initial value requested by due to this rounding.

       Implementations	may  place  limitations on the timer value.  Timer values larger than an implementation-specific maximum value are rounded
       down to this maximum.  The maximum values for the three interval timers are specified by the constants and defined in  On  all  implementa-
       tions, these values are guaranteed to be at least 31 days (in seconds).

       An XSI-conforming implementation provides each process with at least three interval timers, which are indicated by the which argument:

	      Decrements in real time.	A
				       signal is delivered to the process when this timer expires.

	      Decrements in process virtual time.
				       This  timer  runs  only when the process is executing.  A signal is delivered to the process when the timer
				       expires.

	      Decrements both in process virtual time and when
				       the system is running on behalf of the process.	This timer is designed to be used by interpreters in  sta-
				       tistically  profiling  the  execution  of  interpreted  programs.  Each time the timer expires, a signal is
				       delivered to the process.

       In addition to the above timers, HP-UX provides the following three per-thread interval timers for threads,  which  are	indicated  by  the
       which argument:

	      Decrements in real time.	    A signal is delivered to the thread which set this timer when the timer expires.

	      Decrements in thread virtual time.
					    This timer runs only when the thread is executing.	A signal is delivered to the thread which set this
					    timer when the timer expires.

	      Decrements both in thread virtual time and when the system is running on behalf of the thread.
					    Each time the timer expires, a signal is delivered to the thread which set this timer.

       Since a signal can interrupt in-progress system calls, programs using this timer must be prepared to restart the interrupted system call.

       Interval timers are not inherited by a child process across a but are inherited across an

       Three macros for manipulating time values are defined in

	      Set a time value to zero.

	      Test if a time value is non-zero.

	      Compare two time values.
				  (Beware that and do not work with the macro.)

       The timer used with is also used by (see alarm(2)).  Thus successive calls to and set and return the state of a single timer.  In addition,
       a call to sets the timer interval to zero.

       The interaction between and any of or is unspecified.

RETURN VALUE

       Upon successful completion, or returns 0.  Otherwise, -1 is returned and is set to indicate the error.

ERRORS

       The function will fail if:

	      The	     value  argument  is  not in canonical form.  (In canonical form, the number of microseconds is a non-negative integer
			     less than 1,000,000 and the number of seconds is a non-negative integer.)

       The and functions may fail if:

	      The	     which argument is not recognized.

	      The	     value structure specified a bad address.  Reliable detection of this error is implementation dependent.

EXAMPLES

       The following call to sets the real-time interval timer to expire initially after 10 seconds and every 0.5 seconds thereafter:

AUTHOR

       was developed by the University of California, Berkeley.

SEE ALSO

       alarm(2), exec(2), ualarm(2), usleep(2), pthread_attr_setscope(3T), pthread_create(3T), pthread_sigmask(3T), sleep(3C), signal(5).

CHANGE HISTORY

       First released in Issue 4, Version 2.

																      getitimer(2)