man3/ualarm.3

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