getitimer(3C)                    UNIX System V                    getitimer(3C)


NAME
      getitimer, setitimer - get/set value of interval timer

SYNOPSIS
      #include <sys/time.h>

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

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

DESCRIPTION
      The system provides each process with three interval timers, defined in
      sys/time.h.  The getitimer call stores the current value of the timer
      specified by which into the structure pointed to by value.  The setitimer
      call sets the value of the timer specified by which to the value
      specified in the structure pointed to by value, and if ovalue is not
      NULL, stores the previous value of the timer in the structure pointed to
      by ovalue.

      A timer value is defined by the itimerval structure [see gettimeofday(3C)
      for the definition of timeval], which includes the following members:

     struct timeval    it_interval;      /* timer interval */
     struct timeval    it_value;         /* current value */

      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 zero
      disables a timer, regardless of the value of it_interval.  Setting
      it_interval to zero disables a timer after its next expiration (assuming
      it_value is non-zero).

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

      The three timers are:

      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


10/89                                                                    Page 1

getitimer(3C)                    UNIX System V                    getitimer(3C)


                        be prepared to restart interrupted system calls.

SEE ALSO
      alarm(2), gettimeofday(3C).

DIAGNOSTICS
      If the calls succeed, a value of 0 is returned.  If an error occurs, the
      value -1 is returned, and an error code is placed in the global variable
      errno.

      Under the following conditions, the functions getitimer and setitimer
      fail and set errno to:

      EINVAL    The specified number of seconds is greater than 100,000,000,
                the number of microseconds is greater than or equal to
                1,000,000, or the which parameter is unrecognized.

NOTES
      The microseconds field should not be equal to or greater than one second.

      setitimer is independent of the alarm system call.

      Do not use setitimer with the sleep routine.  A sleep following a
      setitimer wipes out knowledge of the user signal handler.






























Page 2                                                                    10/89