man3/ualarm.3

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