[apple/libc.git] / gen / ualarm.3

.\" Copyright (c) 1986, 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.
.\"
.\"     From: @(#)ualarm.3	8.2 (Berkeley) 4/19/94
.\" $FreeBSD: src/lib/libc/gen/ualarm.3,v 1.19 2004/07/02 23:52:10 ru Exp $
.\"
.Dd April 19, 1994
.Dt UALARM 3
.Os
.Sh NAME
.Nm ualarm
.Nd schedule signal after specified time
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft useconds_t
.Fo ualarm
.Fa "useconds_t useconds"
.Fa "useconds_t interval"
.Fc
.Sh DESCRIPTION
.Bf -symbolic
This is a simplified interface to
.Xr setitimer 2 .
.Ef
.Pp
The
.Fn ualarm
function
waits a count of
.Fa useconds
before asserting the terminating signal
.Dv SIGALRM .
System activity or time used in processing the call may cause a slight
delay.
.Pp
If the
.Fa interval
argument is non-zero, the
.Dv SIGALRM
signal will be sent
to the process every
.Fa interval
microseconds after the timer expires (e.g., after
.Fa useconds
number of microseconds have passed).
.Pp
Due to a
.Xr setitimer 2
restriction, the maximum number of
.Fa useconds
and
.Fa interval
is limited to 100,000,000,000,000
(in case this value fits in the unsigned integer).
.Sh RETURN VALUES
When the signal has successfully been caught,
.Fn ualarm
returns the amount of time left on the clock.
.Sh NOTES
A microsecond is 0.000001 seconds.
.Sh SEE ALSO
.Xr getitimer 2 ,
.Xr setitimer 2 ,
.Xr sigpause 2 ,
.Xr sigvec 2 ,
.Xr alarm 3 ,
.Xr signal 3 ,
.Xr sleep 3 ,
.Xr usleep 3
.Sh HISTORY
The
.Fn ualarm
function appeared in
.Bx 4.3 .
Commit	Line	Data
224c7076	1	.\" Copyright (c) 1986, 1991, 1993
e9ce8d39 A	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	.\"
224c7076 A	32	.\" From: @(#)ualarm.3 8.2 (Berkeley) 4/19/94
224c7076 A	33	.\" $FreeBSD: src/lib/libc/gen/ualarm.3,v 1.19 2004/07/02 23:52:10 ru Exp $
e9ce8d39	34	.\"
224c7076 A	35	.Dd April 19, 1994
224c7076 A	36	.Dt UALARM 3
e9ce8d39 A	37	.Os
e9ce8d39 A	38	.Sh NAME
224c7076 A	39	.Nm ualarm
224c7076 A	40	.Nd schedule signal after specified time
e9ce8d39 A	41	.Sh LIBRARY
	42	.Lb libc
	43	.Sh SYNOPSIS
5b2abdfb	44	.In unistd.h
224c7076 A	45	.Ft useconds_t
	46	.Fo ualarm
	47	.Fa "useconds_t useconds"
	48	.Fa "useconds_t interval"
	49	.Fc
e9ce8d39	50	.Sh DESCRIPTION
5b2abdfb	51	.Bf -symbolic
224c7076 A	52	This is a simplified interface to
	53	.Xr setitimer 2 .
	54	.Ef
	55	.Pp
e9ce8d39	56	The
224c7076	57	.Fn ualarm
5b2abdfb	58	function
224c7076 A	59	waits a count of
	60	.Fa useconds
	61	before asserting the terminating signal
	62	.Dv SIGALRM .
	63	System activity or time used in processing the call may cause a slight
	64	delay.
	65	.Pp
	66	If the
	67	.Fa interval
	68	argument is non-zero, the
	69	.Dv SIGALRM
	70	signal will be sent
	71	to the process every
	72	.Fa interval
	73	microseconds after the timer expires (e.g., after
	74	.Fa useconds
	75	number of microseconds have passed).
	76	.Pp
	77	Due to a
	78	.Xr setitimer 2
	79	restriction, the maximum number of
	80	.Fa useconds
	81	and
	82	.Fa interval
	83	is limited to 100,000,000,000,000
	84	(in case this value fits in the unsigned integer).
e9ce8d39	85	.Sh RETURN VALUES
224c7076 A	86	When the signal has successfully been caught,
	87	.Fn ualarm
	88	returns the amount of time left on the clock.
	89	.Sh NOTES
	90	A microsecond is 0.000001 seconds.
	91	.Sh SEE ALSO
	92	.Xr getitimer 2 ,
	93	.Xr setitimer 2 ,
	94	.Xr sigpause 2 ,
	95	.Xr sigvec 2 ,
	96	.Xr alarm 3 ,
	97	.Xr signal 3 ,
	98	.Xr sleep 3 ,
	99	.Xr usleep 3
e9ce8d39 A	100	.Sh HISTORY
e9ce8d39 A	101	The
224c7076	102	.Fn ualarm
5b2abdfb	103	function appeared in
224c7076	104	.Bx 4.3 .