1.\"	$OpenBSD: ualarm.3,v 1.17 2019/07/26 12:08:18 millert Exp $
2.\"
3.\" Copyright (c) 1986, 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. Neither the name of the University nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.Dd $Mdocdate: July 26 2019 $
31.Dt UALARM 3
32.Os
33.Sh NAME
34.Nm ualarm
35.Nd schedule signal after specified time
36.Sh SYNOPSIS
37.In unistd.h
38.Ft useconds_t
39.Fn ualarm "useconds_t microseconds" "useconds_t interval"
40.Sh DESCRIPTION
41.Bf -symbolic
42This is a simplified interface to
43.Xr setitimer 2 .
44.Ef
45.Pp
46The
47.Fn ualarm
48function waits a count of
49.Fa microseconds
50before asserting the terminating signal
51.Dv SIGALRM .
52System activity or time used in processing the call may cause a slight
53delay.
54.Pp
55If the
56.Fa interval
57argument is non-zero, the
58.Dv SIGALRM
59signal will be sent
60to the process every
61.Fa interval
62microseconds after the timer expires (e.g., after
63.Fa microseconds
64number of microseconds have passed).
65.Sh RETURN VALUES
66When the signal has successfully been caught,
67.Fn ualarm
68returns the amount of time left on the clock.
69The maximum value for
70.Fa microseconds
71allowed
72is 2147483647.
73.Sh SEE ALSO
74.Xr setitimer 2 ,
75.Xr sigaction 2 ,
76.Xr sigsuspend 2 ,
77.Xr alarm 3 ,
78.Xr signal 3 ,
79.Xr sleep 3 ,
80.Xr usleep 3
81.Sh STANDARDS
82The
83.Fn ualarm
84function conforms to
85.St -xpg4.2 .
86.Sh HISTORY
87The
88.Fn ualarm
89function appeared in
90.Bx 4.3 .
91