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 1/HZ (from
     <sys/param.h>).  Time values that are not a multiple of 1/HZ will be
     rounded up a multiple.

     For ITIMER_REAL, the timer resolution is 1/HZ for normal processes, for a
     default of 10 milliseconds.  For processes with a real-time scheduling
     policy (see sched_setscheduler(2)), the resolution is determined by the
     variable fasthz (see systune(1M)).  The default fasthz is 1000, which
     produces a 1 millisecond resolution.  The requested interval time is
     adjusted by rounding up to the next higher multiple of the appropriate
     resolution.  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 as much as 6-8% system overhead on slower
     systems, such as the 4D/70 or 4D/20, less on faster systems.

     High resolution timers are not used if the requested time is an integral
     multiple of 1/HZ.

     Note, for the Challenge/Onyx hardware family, all processes (whether they
     execute at a non-degrading priority or not) enjoy a fasthz resolution,
     although only non-degrading processes can specify an absolute value less
     than 1/HZ.

     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.