man3/ualarm.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .TH UALARM 3  2017-09-15 "" "Linux Programmer's Manual"
  25 .SH NAME
  26 ualarm \- schedule signal after given number of microseconds
  27 .SH SYNOPSIS
  28 .nf
  29 .B "#include <unistd.h>"
  30 .PP
  31 .BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval );
  32 .fi
  33 .PP
  34 .in -4n
  35 Feature Test Macro Requirements for glibc (see
  36 .BR feature_test_macros (7)):
  37 .in
  38 .PP
  39 .BR ualarm ():
  40 .ad l
  41 .RS 4
  42 .PD 0
  43 .TP 4
  44 Since glibc 2.12:
  45 .nf
  46 (_XOPEN_SOURCE\ >=\ 500) && ! (_POSIX_C_SOURCE\ >=\ 200809L)
  47     || /* Glibc since 2.19: */ _DEFAULT_SOURCE
  48     || /* Glibc versions <= 2.19: */ _BSD_SOURCE
  49 .TP 4
  50 .fi
  51 Before glibc 2.12:
  52 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
  53 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  54 .PD
  55 .RE
  56 .ad b
  57 .SH DESCRIPTION
  58 The
  59 .BR ualarm ()
  60 function causes the signal
  61 .B SIGALRM
  62 to be sent to the invoking process after (not less than)
  63 .I usecs
  64 microseconds.
  65 The delay may be lengthened slightly by any system activity
  66 or by the time spent processing the call or by the
  67 granularity of system timers.
  68 .PP
  69 Unless caught or ignored, the
  70 .B SIGALRM
  71 signal will terminate the process.
  72 .PP
  73 If the
  74 .I interval
  75 argument is nonzero, further
  76 .B SIGALRM
  77 signals will be sent every
  78 .I interval
  79 microseconds after the first.
  80 .SH RETURN VALUE
  81 This function returns the number of microseconds remaining for
  82 any alarm that was previously set, or 0 if no alarm was pending.
  83 .SH ERRORS
  84 .TP
  85 .B EINTR
  86 Interrupted by a signal; see
  87 .BR signal (7).
  88 .TP
  89 .B EINVAL
  90 \fIusecs\fP or \fIinterval\fP is not smaller than 1000000.
  91 (On systems where that is considered an error.)
  92 .SH ATTRIBUTES
  93 For an explanation of the terms used in this section, see
  94 .BR attributes (7).
  95 .TS
  96 allbox;
  97 lb lb lb
  98 l l l.
  99 Interface       Attribute       Value
 100 T{
 101 .BR ualarm ()
 102 T}      Thread safety   MT-Safe
 103 .TE
 104 .SH CONFORMING TO
 105 4.3BSD, POSIX.1-2001.
 106 POSIX.1-2001 marks
 107 .BR ualarm ()
 108 as obsolete.
 109 POSIX.1-2008 removes the specification of
 110 .BR ualarm ().
 111 4.3BSD, SUSv2, and POSIX do not define any errors.
 112 .SH NOTES
 113 POSIX.1-2001 does not specify what happens if the
 114 .I usecs
 115 argument is 0.
 116 .\" This case is not documented in HP-US, Solar, FreeBSD, NetBSD, or OpenBSD!
 117 On Linux (and probably most other systems),
 118 the effect is to cancel any pending alarm.
 119 .PP
 120 The type
 121 .I useconds_t
 122 is an unsigned integer type capable of holding integers
 123 in the range [0,1000000].
 124 On the original BSD implementation, and in glibc before version 2.1,
 125 the arguments to
 126 .BR ualarm ()
 127 were instead typed as
 128 .IR "unsigned int" .
 129 Programs will be more portable if they never mention
 130 .I useconds_t
 131 explicitly.
 132 .PP
 133 The interaction of this function with
 134 other timer functions such as
 135 .BR alarm (2),
 136 .BR sleep (3),
 137 .BR nanosleep (2),
 138 .BR setitimer (2),
 139 .BR timer_create (2),
 140 .BR timer_delete (2),
 141 .BR timer_getoverrun (2),
 142 .BR timer_gettime (2),
 143 .BR timer_settime (2),
 144 .BR usleep (3)
 145 is unspecified.
 146 .PP
 147 This function is obsolete.
 148 Use
 149 .BR setitimer (2)
 150 or POSIX interval timers
 151 .RB ( timer_create (2),
 152 etc.)
 153 instead.
 154 .SH SEE ALSO
 155 .BR alarm (2),
 156 .BR getitimer (2),
 157 .BR nanosleep (2),
 158 .BR select (2),
 159 .BR setitimer (2),
 160 .BR usleep (3),
 161 .BR time (7)