Debian Codegraph @

upstream/debian-unstable/man3/ualarm.3

raw
1 '\" t
2 .\" Copyright 2003, Andries E. Brouwer <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH ualarm 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 ualarm \- schedule signal after given number of microseconds
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B "#include <unistd.h>"
16 .P
17 .BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval );
18 .fi
19 .P
20 .RS -4
21 Feature Test Macro Requirements for glibc (see
22 .BR feature_test_macros (7)):
23 .RE
24 .P
25 .BR ualarm ():
26 .nf
27 Since glibc 2.12:
28 (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
29 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
30 || /* glibc <= 2.19: */ _BSD_SOURCE
31 Before glibc 2.12:
32 _BSD_SOURCE || _XOPEN_SOURCE >= 500
33 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
34 .fi
35 .SH DESCRIPTION
36 The
37 .BR ualarm ()
38 function causes the signal
39 .B SIGALRM
40 to be sent to the invoking process after (not less than)
41 .I usecs
42 microseconds.
43 The delay may be lengthened slightly by any system activity
44 or by the time spent processing the call or by the
45 granularity of system timers.
46 .P
47 Unless caught or ignored, the
48 .B SIGALRM
49 signal will terminate the process.
50 .P
51 If the
52 .I interval
53 argument is nonzero, further
54 .B SIGALRM
55 signals will be sent every
56 .I interval
57 microseconds after the first.
58 .SH RETURN VALUE
59 This function returns the number of microseconds remaining for
60 any alarm that was previously set, or 0 if no alarm was pending.
61 .SH ERRORS
62 .TP
63 .B EINTR
64 Interrupted by a signal;
65 see
66 .BR signal (7).
67 .TP
68 .B EINVAL
69 .I usecs
70 or
71 .I interval
72 is not smaller than
73 .BR 1000000 .
74 (On systems where that is considered an error.)
75 .SH ATTRIBUTES
76 For an explanation of the terms used in this section, see
77 .BR attributes (7).
78 .TS
79 allbox;
80 lbx lb lb
81 l l l.
82 Interface Attribute Value
83 T{
84 .na
85 .nh
86 .BR ualarm ()
87 T} Thread safety MT-Safe
88 .TE
89 .SH STANDARDS
90 None.
91 .SH HISTORY
92 4.3BSD, POSIX.1-2001.
93 POSIX.1-2001 marks it as obsolete.
94 Removed in POSIX.1-2008.
95 .P
96 4.3BSD, SUSv2, and POSIX do not define any errors.
97 .P
98 POSIX.1-2001 does not specify what happens if the
99 .I usecs
100 argument is 0.
101 .\" This case is not documented in HP-US, Solar, FreeBSD, NetBSD, or OpenBSD!
102 On Linux (and probably most other systems),
103 the effect is to cancel any pending alarm.
104 .P
105 The type
106 .I useconds_t
107 is an unsigned integer type capable of holding integers
108 in the range [0,1000000].
109 On the original BSD implementation, and in glibc before glibc 2.1,
110 the arguments to
111 .BR ualarm ()
112 were instead typed as
113 .IR "unsigned int" .
114 Programs will be more portable if they never mention
115 .I useconds_t
116 explicitly.
117 .P
118 The interaction of this function with
119 other timer functions such as
120 .BR alarm (2),
121 .BR sleep (3),
122 .BR nanosleep (2),
123 .BR setitimer (2),
124 .BR timer_create (2),
125 .BR timer_delete (2),
126 .BR timer_getoverrun (2),
127 .BR timer_gettime (2),
128 .BR timer_settime (2),
129 .BR usleep (3)
130 is unspecified.
131 .P
132 This function is obsolete.
133 Use
134 .BR setitimer (2)
135 or POSIX interval timers
136 .RB ( timer_create (2),
137 etc.)
138 instead.
139 .SH SEE ALSO
140 .BR alarm (2),
141 .BR getitimer (2),
142 .BR nanosleep (2),
143 .BR select (2),
144 .BR setitimer (2),
145 .BR usleep (3),
146 .BR time (7)