[apple/xnu.git] / bsd / man / man2 / getitimer.2

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