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 .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 .sp 1
  84 .SH STANDARDS
  85 None.
  86 .SH HISTORY
  87 4.3BSD, POSIX.1-2001.
  88 POSIX.1-2001 marks it as obsolete.
  89 Removed in POSIX.1-2008.
  90 .PP
  91 4.3BSD, SUSv2, and POSIX do not define any errors.
  92 .PP
  93 POSIX.1-2001 does not specify what happens if the
  94 .I usecs
  95 argument is 0.
  96 .\" This case is not documented in HP-US, Solar, FreeBSD, NetBSD, or OpenBSD!
  97 On Linux (and probably most other systems),
  98 the effect is to cancel any pending alarm.
  99 .PP
 100 The type
 101 .I useconds_t
 102 is an unsigned integer type capable of holding integers
 103 in the range [0,1000000].
 104 On the original BSD implementation, and in glibc before glibc 2.1,
 105 the arguments to
 106 .BR ualarm ()
 107 were instead typed as
 108 .IR "unsigned int" .
 109 Programs will be more portable if they never mention
 110 .I useconds_t
 111 explicitly.
 112 .PP
 113 The interaction of this function with
 114 other timer functions such as
 115 .BR alarm (2),
 116 .BR sleep (3),
 117 .BR nanosleep (2),
 118 .BR setitimer (2),
 119 .BR timer_create (2),
 120 .BR timer_delete (2),
 121 .BR timer_getoverrun (2),
 122 .BR timer_gettime (2),
 123 .BR timer_settime (2),
 124 .BR usleep (3)
 125 is unspecified.
 126 .PP
 127 This function is obsolete.
 128 Use
 129 .BR setitimer (2)
 130 or POSIX interval timers
 131 .RB ( timer_create (2),
 132 etc.)
 133 instead.
 134 .SH SEE ALSO
 135 .BR alarm (2),
 136 .BR getitimer (2),
 137 .BR nanosleep (2),
 138 .BR select (2),
 139 .BR setitimer (2),
 140 .BR usleep (3),
 141 .BR time (7)