1getitimer(2)                     System Calls                     getitimer(2)
2
3
4

NAME

6       getitimer, setitimer - get or set value of interval timer
7

SYNOPSIS

9       #include <sys/time.h>
10
11       int getitimer(int which, struct itimerval *value);
12
13
14       int setitimer(int which, const struct itimerval *value,
15            struct itimerval *ovalue);
16
17

DESCRIPTION

19       The  system provides each process with four interval timers, defined in
20       <sys/time.h>. The getitimer() function stores the current value of  the
21       timer  specified  by  which into the structure pointed to by value. The
22       setitimer() function call sets the value  of  the  timer  specified  by
23       which  to the value specified in the structure pointed to by value, and
24       if ovalue is not NULL, stores the previous value of the  timer  in  the
25       structure pointed to by ovalue.
26
27
28       A  timer  value  is  defined by the itimerval structure (see gettimeof‐
29       day(3C)) for the definition of timeval), which includes  the  following
30       members:
31
32         struct timeval    it_interval;         /* timer interval */
33         struct timeval    it_value;            /* current value */
34
35
36
37       The  it_value  member  indicates the time to the next timer expiration.
38       The it_interval member specifies  a  value  to  be  used  in  reloading
39       it_value  when  the  timer  expires.  Setting  it_value to 0 disables a
40       timer, regardless of the value of it_interval. Setting it_interval to 0
41       disables  a  timer after its next expiration (assuming it_value is non-
42       zero).
43
44
45       Time values smaller than the resolution of the system clock are rounded
46       up  to the resolution of the system clock, except for  ITIMER_REALPROF,
47       whose values are rounded up to the resolution of the  profiling  clock.
48       The four timers are as follows:
49
50       ITIMER_REAL        Decrements in real time.  A SIGALRM signal is deliv‐
51                          ered to the process when this timer expires.
52
53
54       ITIMER_VIRTUAL     Decrements  in  lightweight  process  (lwp)  virtual
55                          time.  It  runs only when the calling lwp is execut‐
56                          ing. A SIGVTALRM signal is delivered to the  calling
57                          lwp when it expires.
58
59
60       ITIMER_PROF        Decrements both in lightweight process (lwp) virtual
61                          time and when the system is running on behalf of the
62                          lwp.   It  is designed to be used by interpreters in
63                          statistically profiling the execution of interpreted
64                          programs.  Each  time the ITIMER_PROF timer expires,
65                          the SIGPROF signal is delivered to the calling  lwp.
66                          Because  this signal may interrupt in-progress func‐
67                          tions, programs using this timer must be prepared to
68                          restart interrupted functions.
69
70
71       ITIMER_REALPROF    Decrements  in  real time. It is designed to be used
72                          for real-time profiling of  multithreaded  programs.
73                          Each  time  the  ITIMER_REALPROF  timer expires, one
74                          counter in a set of counters maintained by the  sys‐
75                          tem  for  each  lightweight  process (lwp) is incre‐
76                          mented. The counter corresponds to the state of  the
77                          lwp  at the time of the timer tick. All lwps execut‐
78                          ing in user mode when the timer expires  are  inter‐
79                          rupted  into system mode. When each lwp resumes exe‐
80                          cution in user mode, if any of the elements  in  its
81                          set  of counters are non-zero, the SIGPROF signal is
82                          delivered to the lwp. The SIGPROF signal  is  deliv‐
83                          ered  before  any  other signal except SIGKILL. This
84                          signal does not interrupt any in-progress  function.
85                          A  siginfo structure, defined in <sys/siginfo.h>, is
86                          associated with the delivery of the SIGPROF  signal,
87                          and includes the following members:
88
89                            si_tstamp;      /* high resolution timestamp */
90                            si_syscall;     /* current syscall */
91                            si_nsysarg;     /* number of syscall arguments */
92                            si_sysarg[];     /* actual syscall arguments */
93                            si_fault;       /* last fault type */
94                            si_faddr;       /* last fault address */
95                            si_mstate[];     /* ticks in each microstate */
96
97                          The   enumeration   of   microstates  (indices  into
98                          si_mstate) is defined in <sys/msacct.h>.
99
100                          Unlike the other interval timers,  the  ITIMER_REAL‐
101                          PROF  interval  timer is not inherited across a call
102                          to one of the exec(2) family of functions.
103
104

RETURN VALUES

106       Upon successful completion, 0 is returned. Otherwise,  −1  is  returned
107       and errno is set to indicate the error.
108

ERRORS

110       The getitimer() and setitimer() functions will fail if:
111
112       EINVAL    The  specified number of seconds is greater than 100,000,000,
113                 the number of  microseconds  is  greater  than  or  equal  to
114                 1,000,000, or the which argument is unrecognized.
115
116

ATTRIBUTES

118       See attributes(5) for descriptions of the following attributes:
119
120
121
122
123       ┌─────────────────────────────┬─────────────────────────────┐
124       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
125       ├─────────────────────────────┼─────────────────────────────┤
126       │Interface Stability          │Standard                     │
127       ├─────────────────────────────┼─────────────────────────────┤
128       │MT-Level                     │MT-Safe                      │
129       └─────────────────────────────┴─────────────────────────────┘
130

SEE ALSO

132       alarm(2),    exec(2),    gettimeofday(3C),    sleep(3C),   sysconf(3C),
133       attributes(5), standards(5)
134

NOTES

136       The setitimer() function is independent of the alarm(2)  and  sleep(3C)
137       functions.
138
139
140       The  ITIMER_PROF and ITIMER_REALPROF timers deliver the same signal and
141       have different semantics. They cannot be used together.
142
143
144       The granularity of the resolution of alarm time is platform-dependent.
145
146
147
148SunOS 5.11                        15 Jun 2009                     getitimer(2)
Impressum