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 .P
  16 .BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval );
  17 .fi
  18 .P
  19 .RS -4
  20 Feature Test Macro Requirements for glibc (see
  21 .BR feature_test_macros (7)):
  22 .RE
  23 .P
  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 .P
  46 Unless caught or ignored, the
  47 .B SIGALRM
  48 signal will terminate the process.
  49 .P
  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 .TS
  73 allbox;
  74 lbx lb lb
  75 l l l.
  76 Interface       Attribute       Value
  77 T{
  78 .na
  79 .nh
  80 .BR ualarm ()
  81 T}      Thread safety   MT-Safe
  82 .TE
  83 .SH STANDARDS
  84 None.
  85 .SH HISTORY
  86 4.3BSD, POSIX.1-2001.
  87 POSIX.1-2001 marks it as obsolete.
  88 Removed in POSIX.1-2008.
  89 .P
  90 4.3BSD, SUSv2, and POSIX do not define any errors.
  91 .P
  92 POSIX.1-2001 does not specify what happens if the
  93 .I usecs
  94 argument is 0.
  95 .\" This case is not documented in HP-US, Solar, FreeBSD, NetBSD, or OpenBSD!
  96 On Linux (and probably most other systems),
  97 the effect is to cancel any pending alarm.
  98 .P
  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 glibc 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 .P
 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 .P
 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)