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  2013-12-23 "" "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 .sp
  31 .BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval );
  32 .fi
  33 .sp
  34 .in -4n
  35 Feature Test Macro Requirements for glibc (see
  36 .BR feature_test_macros (7)):
  37 .in
  38 .sp
  39 .BR ualarm ():
  40 .ad l
  41 .RS 4
  42 .PD 0
  43 .TP 4
  44 Since glibc 2.12:
  45 .nf
  46 _BSD_SOURCE ||
  47     (_XOPEN_SOURCE\ >=\ 500 ||
  48         _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
  49     !(_POSIX_C_SOURCE\ >=\ 200809L || _XOPEN_SOURCE\ >=\ 700)
  50 .TP 4
  51 .fi
  52 Before glibc 2.12:
  53 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  54 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  55 .PD
  56 .RE
  57 .ad b
  58 .SH DESCRIPTION
  59 The
  60 .BR ualarm ()
  61 function causes the signal
  62 .B SIGALRM
  63 to be sent to the invoking process after (not less than)
  64 .I usecs
  65 microseconds.
  66 The delay may be lengthened slightly by any system activity
  67 or by the time spent processing the call or by the
  68 granularity of system timers.
  69 .LP
  70 Unless caught or ignored, the
  71 .B SIGALRM
  72 signal will terminate the process.
  73 .LP
  74 If the
  75 .I interval
  76 argument is nonzero, further
  77 .B SIGALRM
  78 signals will be sent every
  79 .I interval
  80 microseconds after the first.
  81 .SH RETURN VALUE
  82 This function returns the number of microseconds remaining for
  83 any alarm that was previously set, or 0 if no alarm was pending.
  84 .SH ERRORS
  85 .TP
  86 .B EINTR
  87 Interrupted by a signal.
  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 .SS Multithreading (see pthreads(7))
  94 The
  95 .BR ualarm ()
  96 function is thread-safe.
  97 .SH CONFORMING TO
  98 4.3BSD, POSIX.1-2001.
  99 POSIX.1-2001 marks
 100 .BR ualarm ()
 101 as obsolete.
 102 POSIX.1-2008 removes the specification of
 103 .BR ualarm ().
 104 4.3BSD, SUSv2, and POSIX do not define any errors.
 105 .SH NOTES
 106 POSIX.1-2001 does not specify what happens if the
 107 .I usecs
 108 argument is 0.
 109 .\" This case is not documented in HP-US, Solar, FreeBSD, NetBSD, or OpenBSD!
 110 On Linux (and probably most other systems),
 111 the effect is to cancel any pending alarm.
 112
 113 The type
 114 .I useconds_t
 115 is an unsigned integer type capable of holding integers
 116 in the range [0,1000000].
 117 On the original BSD implementation, and in glibc before version 2.1,
 118 the arguments to
 119 .BR ualarm ()
 120 were instead typed as
 121 .IR "unsigned int" .
 122 Programs will be more portable if they never mention
 123 .I useconds_t
 124 explicitly.
 125 .LP
 126 The interaction of this function with
 127 other timer functions such as
 128 .BR alarm (2),
 129 .BR sleep (3),
 130 .BR nanosleep (2),
 131 .BR setitimer (2),
 132 .BR timer_create (2),
 133 .BR timer_delete (2),
 134 .BR timer_getoverrun (2),
 135 .BR timer_gettime (2),
 136 .BR timer_settime (2),
 137 .BR usleep (3)
 138 is unspecified.
 139 .LP
 140 This function is obsolete.
 141 Use
 142 .BR setitimer (2)
 143 or POSIX interval timers
 144 .RB ( timer_create (2),
 145 etc.)
 146 instead.
 147 .SH SEE ALSO
 148 .BR alarm (2),
 149 .BR getitimer (2),
 150 .BR nanosleep (2),
 151 .BR select (2),
 152 .BR setitimer (2),
 153 .BR usleep (3),
 154 .BR time (7)