- Uniformly use .In for header file references.
[dragonfly.git] / lib / libc / sys / getitimer.2
CommitLineData
984263bc
MD
1.\" Copyright (c) 1983, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)getitimer.2 8.3 (Berkeley) 5/16/95
33.\" $FreeBSD: src/lib/libc/sys/getitimer.2,v 1.10.2.6 2001/12/14 18:34:00 ru Exp $
44cb301e 34.\" $DragonFly: src/lib/libc/sys/getitimer.2,v 1.3 2006/05/26 19:39:37 swildner Exp $
984263bc
MD
35.\"
36.Dd May 16, 1995
37.Dt GETITIMER 2
38.Os
39.Sh NAME
40.Nm getitimer ,
41.Nm setitimer
42.Nd get/set value of interval timer
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In sys/time.h
47.Fd "#define ITIMER_REAL 0"
48.Fd "#define ITIMER_VIRTUAL 1"
49.Fd "#define ITIMER_PROF 2"
50.Ft int
51.Fn getitimer "int which" "struct itimerval *value"
52.Ft int
53.Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue"
54.Sh DESCRIPTION
55The system provides each process with three interval timers,
56defined in
44cb301e 57.In sys/time.h .
984263bc
MD
58The
59.Fn getitimer
60call returns the current value for the timer specified in
61.Fa which
62in the structure at
63.Fa value .
64The
65.Fn setitimer
66call sets a timer to the specified
67.Fa value
68(returning the previous value of the timer if
69.Fa ovalue
70is non-nil).
71.Pp
72A timer value is defined by the
73.Fa itimerval
74structure:
75.Bd -literal -offset indent
76struct itimerval {
77 struct timeval it_interval; /* timer interval */
78 struct timeval it_value; /* current value */
79};
80.Ed
81.Pp
82If
83.Fa it_value
84is non-zero, it indicates the time to the next timer expiration.
85If
86.Fa it_interval
87is non-zero, it specifies a value to be used in reloading
88.Fa it_value
89when the timer expires.
90Setting
91.Fa it_value
92to 0 disables a timer, regardless of the value of
93.Fa it_interval .
94Setting
95.Fa it_interval
96to 0 causes a timer to be disabled after its next expiration (assuming
97.Fa it_value
98is non-zero).
99.Pp
100Time values smaller than the resolution of the
101system clock are rounded up to this resolution
102(typically 10 milliseconds).
103.Pp
104The
105.Dv ITIMER_REAL
106timer decrements in real time. A
107.Dv SIGALRM
108signal is
109delivered when this timer expires.
110.Pp
111The
112.Dv ITIMER_VIRTUAL
113timer decrements in process virtual time.
114It runs only when the process is executing. A
115.Dv SIGVTALRM
116signal
117is delivered when it expires.
118.Pp
119The
120.Dv ITIMER_PROF
121timer decrements both in process virtual time and
122when the system is running on behalf of the process. It is designed
123to be used by interpreters in statistically profiling the execution
124of interpreted programs.
125Each time the
126.Dv ITIMER_PROF
127timer expires, the
128.Dv SIGPROF
129signal is
130delivered. Because this signal may interrupt in-progress
131system calls, programs using this timer must be prepared to
132restart interrupted system calls.
133.Pp
134The maximum number of seconds allowed for
135.Fa it_interval
136and
137.Fa it_value
138in
139.Fn setitimer
140is 100000000.
141.Sh NOTES
142Three macros for manipulating time values are defined in
44cb301e 143.In sys/time.h .
984263bc
MD
144.Fa Timerclear
145sets a time value to zero,
146.Fa timerisset
147tests if a time value is non-zero, and
148.Fa timercmp
149compares two time values.
150.Sh RETURN VALUES
151.Rv -std
152.Sh ERRORS
153.Fn Getitimer
154and
155.Fn setitimer
156will fail if:
157.Bl -tag -width Er
158.It Bq Er EFAULT
159The
160.Fa value
161parameter specified a bad address.
162.It Bq Er EINVAL
163A
164.Fa value
165parameter specified a time that was too large
166to be handled.
167.El
168.Sh SEE ALSO
169.Xr gettimeofday 2 ,
170.Xr select 2 ,
171.Xr sigvec 2 ,
172.Xr clocks 7
173.Sh HISTORY
174The
175.Fn getitimer
176function call appeared in
177.Bx 4.2 .