| blob | 66c73415ca8800c00a5280753e034976278a0acc |
1 .\" $NetBSD: getitimer.2,v 1.28 2011/10/27 16:10:37 christos Exp $
2 .\"
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)getitimer.2 8.3 (Berkeley) 5/16/95
31 .\"
32 .Dd October 27, 2011
33 .Dt GETITIMER 2
34 .Os
35 .Sh NAME
36 .Nm getitimer ,
37 .Nm setitimer
38 .Nd get/set value of interval timer
39 .Sh LIBRARY
40 .Lb libc
41 .Sh SYNOPSIS
42 .In sys/time.h
43 .Ft int
44 .Fn getitimer "int which" "struct itimerval *value"
45 .Ft int
46 .Fn setitimer "int which" "const struct itimerval * restrict value" "struct itimerval * restrict ovalue"
47 .Sh DESCRIPTION
48 The system provides each process with three interval timers,
49 defined in
50 .Ao Pa sys/time.h Ac .
51 The
52 .Fn getitimer
53 call returns the current value for the timer specified in
54 .Fa which
55 in the structure at
56 .Fa value .
57 The
58 .Fn setitimer
59 call sets a timer to the specified
60 .Fa value ,
61 returning the previous value of the timer if
62 .Fa ovalue
63 is not
64 .Dv NULL .
65 .Pp
66 A timer value is defined by the
67 .Fa itimerval
68 structure:
69 .Bd -literal -offset indent
70 struct itimerval {
71 struct timeval it_interval; /* timer interval */
72 struct timeval it_value; /* current value */
73 };
74 .Ed
75 .Pp
76 If
77 .Fa it_value
78 is non-zero, it indicates the time to the next timer expiration.
79 If
80 .Fa it_interval
81 is non-zero, it specifies a value to be used in reloading
82 .Fa it_value
83 when the timer expires.
84 Setting
85 .Fa it_value
86 to 0 disables a timer.
87 Setting
88 .Fa it_interval
89 to 0 causes a timer to be disabled after its next expiration (assuming
90 .Fa it_value
91 is non-zero).
92 .Pp
93 The
94 .Fa which
95 parameter specifies the type of the timer:
96 .Bl -tag -width "ITIMER_MONOTONIC " -offset indent
97 .It Dv ITIMER_REAL
98 timer decrements in real time.
99 This timer is affected by
100 .Xr adjtime 2
101 and
102 .Xr settimeofday 2 .
103 A
104 .Dv SIGALRM
105 signal is
106 delivered when this timer expires.
107 .It Dv ITIMER_VIRTUAL
108 timer decrements in process virtual time.
109 It runs only when the process is executing.
110 A
111 .Dv SIGVTALRM
112 signal
113 is delivered when it expires.
114 .It Dv ITIMER_PROF
115 timer decrements both in process virtual time and
116 when the system is running on behalf of the process.
117 It is designed to be used by interpreters in statistically profiling
118 the execution of interpreted programs.
119 Each time the
120 .Dv ITIMER_PROF
121 timer expires, the
122 .Dv SIGPROF
123 signal is
124 delivered.
125 Because this signal may interrupt in-progress
126 system calls, programs using this timer must be prepared to
127 restart interrupted system calls.
128 .It Dv ITIMER_MONOTONIC
129 timer decrements in monotonic time.
130 This timer is not affected by
131 .Xr adjtime 2
132 and
133 .Xr settimeofday 2 .
134 A
135 .Dv SIGALRM
136 signal is
137 delivered when this timer expires.
138 .El
139 Note that:
140 .Bl -bullet -offset indent
141 .It
142 Time values smaller than the resolution of the
143 system clock are rounded up to this resolution
144 (typically 10 milliseconds).
145 .It
146 The interaction between
147 .Fn setitimer
148 and
149 .Xr alarm 3
150 or
151 .Xr sleep 3
152 is unspecified by the specification.
153 .El
154 .Sh RETURN VALUES
155 If the calls succeed, a value of 0 is returned.
156 If an error occurs, the value \-1 is returned, and a more precise error
157 code is placed in the global variable
158 .Va errno .
159 .Sh ERRORS
160 Both functions may fail if:
161 .Bl -tag -width Er
162 .It Bq Er EFAULT
163 The
164 .Fa value
165 parameter specified a bad address.
166 .It Bq Er EINVAL
167 The
168 .Fa which
169 parameter was not a known timer type, or the
170 .Fa value
171 parameter specified a time that was too large
172 to be handled.
173 .El
174 .Sh SEE ALSO
175 .Xr gettimeofday 2 ,
176 .Xr select 2 ,
177 .Xr sigaction 2 ,
178 .Xr itimerval 3 ,
179 .Xr timeradd 3
180 .Sh STANDARDS
181 The functions conform to
182 .St -p1003.1-2001 .
183 The later
184 .St -p1003.1-2008
185 revision however marked both as obsolescent,
186 recommending the use of
187 .Xr timer_gettime 2
188 and
189 .Xr timer_settime 2
190 instead.
191 .Sh HISTORY
192 The
193 .Fn getitimer
194 function call appeared in
195 .Bx 4.2 .
196 The
197 .Dv ITIMER_MONOTONIC
198 functionality appeared in
199 .Nx 6.0 .