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

     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 returns the current value for the timer
     specified in which, while the setitimer call sets the value of a timer
     (optionally returning the previous value of the timer).

     A timer value is defined by the itimerval structure:

          struct itimerval {
               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 and not the time the timer was set originally.  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 a timer.  Setting
     it_interval to 0 causes a timer to be disabled after its next expiration
     (assuming it_value is non-zero).

     For ITIMER_VIRTUAL and ITIMER_PROF, the timer resolution is 100 HZ (which
     equals 10 milliseconds). Time values that are not a multiple of 100 HZ
     will be rounded to a multiple.

     For ITIMER_REAL, the timer resolution is 100 HZ (which equals 10
     milliseconds) for normal processes. For processes with a real time
     scheduling policy (see sched setscheduler (2)), actual resolution of the
     clock depends on the timer capability of the underlying hardware (see
     timers (5)).  To avoid a reduction in overall system performance, normal
     processes are not permitted to use the high resolution timers, since fast
     itimer requests can add considerable system overhead.

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


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

     The ITIMER_PROF 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 ITIMER_PROF 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).

SEE ALSO
     ftimer(1), lboot(1M), npri(1), systune(1M), schedctl(2), sigset(2),
     timers(5).

FILES
     /var/sysgen/mtune/kernel fast itimer configuration variables.

DIAGNOSTICS
     If the calls succeed, a value of 0 is returned.  If an error occurs, the
     value -1 is returned, and errno will be set.  setitimer and getitimer
     will fail if any of the following are true:

     [EFAULT]       The value or ovalue structure specified a bad address.

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

BUGS
     setitimer calls reset the alarm clock (see alarm(2)) of the calling
     process.

     Programs cannot use getitimer(2) to accurately determine how much time
     remains until the timer expires.  On the Challenge/Onyx hardware family,
     it_value is not updated at a constant rate.


                                                                        Page 2