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