[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>
.Pp
.Fd #define ITIMER_REAL		0
.Fd #define ITIMER_VIRTUAL	1
.Fd #define ITIMER_PROF		2
.Ft int
.Fo getitimer
.Fa "int which"
.Fa "struct itimerval *value"
.Fc
.Ft int
.Fo setitimer
.Fa "int which"
.Fa "const struct itimerval *restrict value"
.Fa "struct itimerval *restrict ovalue"
.Fc
.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
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and the global integer variable
.Va errno
is set to indicate the error.
.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
The
.Fa value
parameter specified a time that was too large to be handled
or not in the canonical form.
.\" ==========
.It Bq Er EINVAL
The
.Fa which
parameter was invalid.
.El
.Sh SEE ALSO
.Xr gettimeofday 2 ,
.Xr select 2 ,
.Xr sigaction 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>
2d21ac55	45	.Pp
9bccf70c A	46	.Fd #define ITIMER_REAL 0
	47	.Fd #define ITIMER_VIRTUAL 1
	48	.Fd #define ITIMER_PROF 2
	49	.Ft int
2d21ac55 A	50	.Fo getitimer
	51	.Fa "int which"
	52	.Fa "struct itimerval *value"
	53	.Fc
9bccf70c	54	.Ft int
2d21ac55 A	55	.Fo setitimer
	56	.Fa "int which"
	57	.Fa "const struct itimerval *restrict value"
	58	.Fa "struct itimerval *restrict ovalue"
	59	.Fc
9bccf70c A	60	.Sh DESCRIPTION
	61	The system provides each process with three interval timers,
	62	defined in
	63	.Ao Pa sys/time.h Ac .
	64	The
	65	.Fn getitimer
	66	call returns the current value for the timer specified in
	67	.Fa which
	68	in the structure at
	69	.Fa value .
	70	The
	71	.Fn setitimer
	72	call sets a timer to the specified
	73	.Fa value
	74	(returning the previous value of the timer if
	75	.Fa ovalue
	76	is non-nil).
	77	.Pp
	78	A timer value is defined by the
	79	.Fa itimerval
	80	structure:
	81	.Bd -literal -offset indent
	82	struct itimerval {
	83	struct timeval it_interval; /* timer interval */
	84	struct timeval it_value; /* current value */
	85	};
	86	.Ed
	87	.Pp
	88	If
	89	.Fa it_value
	90	is non-zero, it indicates the time to the next timer expiration.
	91	If
	92	.Fa it_interval
	93	is non-zero, it specifies a value to be used in reloading
	94	.Fa it_value
	95	when the timer expires.
	96	Setting
	97	.Fa it_value
	98	to 0 disables a timer. Setting
	99	.Fa it_interval
	100	to 0 causes a timer to be disabled after its next expiration (assuming
	101	.Fa it_value
	102	is non-zero).
	103	.Pp
	104	Time values smaller than the resolution of the
	105	system clock are rounded up to this resolution
	106	(typically 10 milliseconds).
	107	.Pp
	108	The
	109	.Dv ITIMER_REAL
	110	timer decrements in real time. A
	111	.Dv SIGALRM
	112	signal is
	113	delivered when this timer expires.
	114	.Pp
	115	The
	116	.Dv ITIMER_VIRTUAL
	117	timer decrements in process virtual time.
	118	It runs only when the process is executing. A
	119	.Dv SIGVTALRM
	120	signal
	121	is delivered when it expires.
	122	.Pp
	123	The
124	.Dv ITIMER_PROF
125	timer decrements both in process virtual time and
126	when the system is running on behalf of the process. It is designed
127	to be used by interpreters in statistically profiling the execution
128	of interpreted programs.
129	Each time the
130	.Dv ITIMER_PROF
131	timer expires, the
132	.Dv SIGPROF
133	signal is
134	delivered. Because this signal may interrupt in-progress
135	system calls, programs using this timer must be prepared to
136	restart interrupted system calls.
137	.Sh NOTES
138	Three macros for manipulating time values are defined in
139	.Ao Pa sys/time.h Ac .
140	.Fa Timerclear
141	sets a time value to zero,
142	.Fa timerisset
143	tests if a time value is non-zero, and
144	.Fa timercmp
145	compares two time values (beware that >= and <= do not
146	work with this macro).
147	.Sh RETURN VALUES
2d21ac55 A	148	Upon successful completion, a value of 0 is returned.
	149	Otherwise, a value of -1 is returned and the global integer variable
	150	.Va errno
	151	is set to indicate the error.
9bccf70c A	152	.Sh ERRORS
	153	.Fn Getitimer
	154	and
	155	.Fn setitimer
	156	will fail if:
	157	.Bl -tag -width Er
2d21ac55	158	.\" ==========
9bccf70c A	159	.It Bq Er EFAULT
	160	The
	161	.Fa value
	162	parameter specified a bad address.
2d21ac55	163	.\" ==========
9bccf70c	164	.It Bq Er EINVAL
2d21ac55	165	The
9bccf70c	166	.Fa value
2d21ac55 A	167	parameter specified a time that was too large to be handled
	168	or not in the canonical form.
	169	.\" ==========
	170	.It Bq Er EINVAL
	171	The
	172	.Fa which
	173	parameter was invalid.
9bccf70c A	174	.El
9bccf70c A	175	.Sh SEE ALSO
2d21ac55	176	.Xr gettimeofday 2 ,
9bccf70c	177	.Xr select 2 ,
2d21ac55	178	.Xr sigaction 2
9bccf70c A	179	.Sh HISTORY
	180	The
	181	.Fn getitimer
	182	function call appeared in
	183	.Bx 4.2 .