setitimer(2)

NAME

     getitimer, setitimer - get or set value of interval timer

SYNOPSIS

     #include <sys/time.h>

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

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

DESCRIPTION

     The system provides each process with four interval  timers,
     defined  in  sys/time.h. The getitimer() function stores the
     current value of the  timer  specified  by  which  into  the
     structure pointed to by value. The setitimer() function 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 */

     The it_value member indicates the time  to  the  next  timer
     expiration.  The  it_interval member specifies a value to be
     used in reloading it_value when the timer  expires.  Setting
     it_value  to  0 disables a timer, regardless of the value of
     it_interval. Setting it_interval to 0 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 the resolution of the system clock, except
     for  ITIMER_REALPROF, whose values are  rounded  up  to  the
     resolution  of  the  profiling clock. The four timers are as
     follows:

     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 timer expires, the SIGPROF signal
           is  delivered.  Because  this signal may interrupt in-
           progress functions, programs using this timer must  be
           prepared to restart interrupted functions.

     ITIMER_REALPROF
           Decrements in real time. It is designed to be used for
           real-time  profiling  of  multithreaded programs. Each
           time the ITIMER_REALPROF timer expires, one counter in
           a  set  of  counters maintained by the system for each
           lightweight process (lwp) is incremented. The  counter
           corresponds to the state of the lwp at the time of the
           timer tick. All lwps executing in user mode  when  the
           timer  expires  are interrupted into system mode. When
           each lwp resumes execution in user mode, if any of the
           elements in its set of counters are non-zero, the SIG-
           PROF signal is delivered to the lwp. The SIGPROF  sig-
           nal  is  delivered before any other signal except SIG-
           KILL.  This signal does not interrupt any  in-progress
           function.    A     siginfo   structure,   defined   in
           <sys/siginfo.h>, is associated with  the  delivery  of
           the   SIGPROF   signal,  and  includes  the  following
           members:

           si_tstamp;      /* high resolution timestamp */
           si_syscall;     /* current syscall */
           si_nsysarg;     /* number of syscall arguments */
           si_sysarg[];     /* actual syscall arguments */
           si_fault;       /* last fault type */
           si_faddr;       /* last fault address */
           si_mstate[];     /* ticks in each microstate */

           The   enumeration   of   microstates   (indices   into
           si_mstate) is defined in <sys/msacct.h>.

RETURN VALUES

     Upon successful completion, 0 is returned. Otherwise, -1  is
     returned and errno is set to indicate the error.

ERRORS

     The getitimer() and setitimer() functions will fail if:

     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  argument  is
           unrecognized.

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO

     alarm(2), gettimeofday(3C), sleep(3C),  sysconf(3C),  attri-
     butes(5), standards(5)

NOTES

     The microseconds field should not be  equal  to  or  greater
     than one second.

     The setitimer() function is independent of the alarm() func-
     tion.

     Do not use setitimer(ITIMER_REAL) with the sleep()  routine.
     A  sleep(3C)  call  wipes  out  knowledge of the user signal
     handler for SIGALRM.

     The ITIMER_PROF and ITIMER_REALPROF timers deliver the  same
     signal  and  have  different  semantics. They cannot be used
     together.

     The  granularity  of  the  resolution  of  alarm   time   is
     platform-dependent.