timers(5)

NAME
     timers - timers and process time accounting information

SYNOPSIS
     #include <sys/time.h>

DESCRIPTION
     The timing facilities under IRIX consist of interval timers, event
     timing, process execution time accounting, and time of day reporting.

     Interval timers consist of POSIX timers (see timer_create (3c)), and
     itimers that were introduced in BSD4.2 (see getitimer(2)).  Use of the
     POSIX timers is strongly recommended for new applications.  The IRIX-
     unique BSD4.2 itimers are supported only to provide compatibility for
     older applications.

     On Silicon Graphics machines there are two independent timers per
     processor.  The first interrupts the processor at a regular interval of
     10 milliseconds and is used for scheduling and statistics gathering.  The
     second interrupts the processor at fasthz frequency and is used to
     support the high resolution POSIX and itimer capabilities.  On
     multiprocessor machines, one processor is used to maintain system time
     and is labeled the clock processor.  One additional processor is required
     to service the POSIX timer and itimer requests and is labeled the fast
     clock processor.  The mpadmin(1) command can be used to bind the clock
     and fast clock to a particular physical processor.

     A realtime process (one with priority between NDPHIMAX and NDPHIMIN) may
     make POSIX timer requests, or itimer requests with a resolution greater
     than 10 milliseconds when using the realtime timer.  The limit on the
     resolution depends on the underlying hardware and can be dynamically
     determined by examining the variable fasthz using systune(1M) or by
     opening /dev/kmem and reading fasthz as a 4 byte word.  The fasthz
     variable can also be modified using systune(1M).

     On the Indigo, Indy, Indigo2, O2, and Octane products, acceptable values
     for fasthz are 500, 1000, and 2500 Hz.  If the requested value is not one
     of these values, then the default value of 1000 Hz is used.  On the
     Challenge Series, the resolution of the hardware timer is 21 nanoseconds
     and therefore any value smaller than 47MHz is possible.  For realistic
     results, no fasthz value larger than 2000 Hz should be specified because
     the kernel cannot reliably deliver itimer signals at a greater rate.

     On Onyx2, Onyx3, and Origin Systems, fasthz has a value of 1250 Hz which
     gives a resolution of 0.8 microseconds.  For processes running with
     either the FIFO or RR scheduling policies, both POSIX timers with
     CLOCK_SGI_FAST, and itimers with ITIMER_REAL have a resolution of 0.8
     microseconds.  This does not necessarily mean that timer interrupts can
     be received at that frequency, the timers simply have that resolution.
     It is not possible to achieve better than 10 millisecond timer accuracy
     when running without either a FIFO or RR scheduling policy.  To take low
     latency timestamps with maximum resolution on Onyx2, Onyx3 and Origin
     systems, clock_gettime (CLOCK_SGI_CYCLE) should be used.  This will give
     a timer resolution of 0.8 microseconds.

     Event timing is typically used by the programmer to measure the elapsed
     time between events.  By examining the time before and after an operation
     and then computing the difference, the application can calculate the
     elapsed time of the operation.  The POSIX clock_gettime(2), the System V
     time(2), times(2) and Berkeley gettimeofday(3B) calls may be used to that
     end.  IRIX also allows the user to map a hardware counter into the user
     address space and read it directly for low overhead time snapshots.
     Information about the address and rate of the hardware counter is
     available through the SGI_QUERY_CYCLECNTR request to the syssgi(2) system
     call.  The mmap(2) system call can then be used to make the counter
     directly available to the user process.

     Process execution time accounting is typically measured under System V
     with the times(2) system call and under Berkeley with the getrusage(3)
     system call.  Traditionally under UNIX, the time reported by these system
     calls is measured by the scheduling clock.  On each clock tick the kernel
     examines the processor status word and charges the running process a
     tick's worth of execution time in user or system mode.  The most
     significant drawback of this scheme is limited precision.  Under IRIX,
     the kernel keeps track of process state transitions between user and
     system modes and accumulates the elapsed time between state transitions.
     This information is available through the times(2) and getrusage(2)
     system calls.

     System time of day can be obtained via the gettimeofday(3B) system call.
     On the Challenge Series, there is a 64 bit counter that is used to
     maintain system time.  The system initializes a timebase at startup using
     the battery backed time of day clock and associates a counter value with
     that timebase.  Subsequent gettimeofday() calls will return the original
     timebase plus the difference between the current counter value and the
     original startup counter value.  The resolution of this 64 bit counter is
     21 nanoseconds.  A gettimeofday() call causes the kernel to report the
     current time plus the difference between the current counter value and
     the last snapshot value of the counter from the scheduling clock.  On
     some other Silicon Graphics machines, there is a 64 bit data structure
     that is maintained by the clock processor.  On every clock tick, the
     kernel updates that data structure by an amount equal to the clock tick
     (typically 10 milliseconds).  A gettimeofday() call will return the
     current value of that structure.  When timed(1M) is running, the
     gettimeofday() and time(2) results will be adjusted to match time of
     other machines running timed within a local area.

     On Challenge Series machines timers live on the processor where the
     program that created them was running at the time they were created.  A
     timer stays connected to that processor until it expires, is disabled or
     the user restricts or isolates the processor with the timer.  If a user
     restricts or isolates a processor with timers, all of the timers are
     moved to the processor that owns the clock as reported by sysmp(2).

SEE ALSO
     clock_gettime(), clock_settime(), clock_getres(), getitimer(2), sysmp(2),
     syssgi(2), time(2), timer_create(3C), timer_delete(3C),
     timer_getoverrun(3C), timer_gettime(3C), times(2), getrusage(3),
     gettimeofday(3B)