Manual Pages for UNIX Operating System command usage for man setitimer

System Calls                                         getitimer(2)



NAME
     getitimer, setitimer - get or set value of interval timer

SYNOPSIS
     #include 

     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 . 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  sig-
                        nal is delivered to the process when this
                        timer expires.





SunOS 5.11          Last change: 15 Jun 2009                    1






System Calls                                         getitimer(2)



     ITIMER_VIRTUAL     Decrements in lightweight  process  (lwp)
                        virtual  time. It runs only when the cal-
                        ling lwp is executing. A SIGVTALRM signal
                        is  delivered  to the calling lwp when it
                        expires.


     ITIMER_PROF        Decrements both  in  lightweight  process
                        (lwp) virtual time and when the system is
                        running on behalf  of  the  lwp.   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 to the calling lwp.
                        Because this  signal  may  interrupt  in-
                        progress  functions,  programs using this
                        timer must be prepared to restart  inter-
                        rupted 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 pro-
                        cess (lwp) is  incremented.  The  counter
                        corresponds  to  the  state of the lwp at
                        the time of the timer tick. All lwps exe-
                        cuting   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 SIGPROF
                        signal is delivered to the lwp. The  SIG-
                        PROF signal is delivered before any other
                        signal except SIGKILL. This  signal  does
                        not interrupt any in-progress function. A
                        siginfo     structure,     defined     in
                        ,  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 */




SunOS 5.11          Last change: 15 Jun 2009                    2






System Calls                                         getitimer(2)



                        The enumeration of  microstates  (indices
                        into     si_mstate)    is    defined   in
                        .

                        Unlike the  other  interval  timers,  the
                        ITIMER_REALPROF  interval  timer  is  not
                        inherited across a call  to  one  of  the
                        exec(2) family of functions.


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       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


SEE ALSO
     alarm(2), exec(2), gettimeofday(3C), sleep(3C), sysconf(3C),
     attributes(5), standards(5)

NOTES
     The setitimer() function is independent of the alarm(2)  and
     sleep(3C) functions.


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



SunOS 5.11          Last change: 15 Jun 2009                    3






System Calls                                         getitimer(2)



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





















































SunOS 5.11          Last change: 15 Jun 2009                    4