getitimer(3C)                                                 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


   7/91                                                                 Page 1

   getitimer(3C)                                                 getitimer(3C)


                           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.

   RETURN VALUE
         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.

   ERRORS
         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.

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

   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                                                                 7/91