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