getitimer(2)                                         getitimer(2)



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

     SYNOPSIS
          #include <sys/time.h>

          #define ITIMER_REAL     0 /*real time intervals*/
          #define ITIMER_VIRTUAL   1 /*virtual time intervals*/
          #define ITIMER_PROF     2 /*user and system virtual
                                     time*/

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

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

     DESCRIPTION
          The system provides each process with three interval timers,
          defined in <sys/time.h>.  The getitimer call returns the
          current value for the timer specified in which in the
          structure at value.  The setitimer call sets a timer 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;  /* timer interval */
               struct    timeval it_value;     /* current value */
          };

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

          Time values smaller than the resolution of the system clock
          are rounded up to this resolution (on the VAX, 10
          milliseconds).

          The ITIMERREAL timer decrements in real time.  A SIGALRM
          signal is delivered when this timer expires.

          The ITIMERVIRTUAL timer decrements in process virtual time.
          It runs only when the process is executing.  A SIGVTALRM
          signal is delivered when it expires.




     Page 1                                        (last mod. 1/14/87)

     getitimer(2)                                         getitimer(2)



          The ITIMERPROF timer 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 ITIMERPROF 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
          Three macros for manipulating time values are defined in
          <sys/time.h>.  timerclear sets a time value to zero,
          timerisset tests if a time value is non-zero, and timercmp
          compares two time values (beware that >= and <= do not work
          with this macro).

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

     ERRORS
          The possible errors are:

          [EFAULT]       The value parameter specified a bad address.

          [EINVAL]       A value parameter specified a time was too
                         large to be handled.

     SEE ALSO
          sigvec(2), gettimeofday(2).
























     Page 2                                        (last mod. 1/14/87)