.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
-.\" License along with this manual; if not, write to the Free
-.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
-.\" USA.
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
.\"
-.TH UALARM 3 2007-07-26 "" "Linux Programmer's Manual"
+.TH UALARM 3 2017-09-15 "" "Linux Programmer's Manual"
.SH NAME
ualarm \- schedule signal after given number of microseconds
.SH SYNOPSIS
.nf
.B "#include <unistd.h>"
-.sp
+.PP
.BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval );
.fi
-.sp
+.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
-.sp
+.PP
.BR ualarm ():
+.ad l
+.RS 4
+.PD 0
+.TP 4
+Since glibc 2.12:
+.nf
+(_XOPEN_SOURCE\ >=\ 500) && ! (_POSIX_C_SOURCE\ >=\ 200809L)
+ || /* Glibc since 2.19: */ _DEFAULT_SOURCE
+ || /* Glibc versions <= 2.19: */ _BSD_SOURCE
+.TP 4
+.fi
+Before glibc 2.12:
_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
+.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
+.PD
+.RE
+.ad b
.SH DESCRIPTION
The
.BR ualarm ()
The delay may be lengthened slightly by any system activity
or by the time spent processing the call or by the
granularity of system timers.
-.LP
+.PP
Unless caught or ignored, the
.B SIGALRM
signal will terminate the process.
-.LP
+.PP
If the
.I interval
-argument is non-zero, further
+argument is nonzero, further
.B SIGALRM
signals will be sent every
.I interval
microseconds after the first.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
This function returns the number of microseconds remaining for
any alarm that was previously set, or 0 if no alarm was pending.
.SH ERRORS
.TP
.B EINTR
-Interrupted by a signal.
+Interrupted by a signal; see
+.BR signal (7).
.TP
.B EINVAL
\fIusecs\fP or \fIinterval\fP is not smaller than 1000000.
(On systems where that is considered an error.)
-.SH "CONFORMING TO"
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR ualarm ()
+T} Thread safety MT-Safe
+.TE
+.SH CONFORMING TO
4.3BSD, POSIX.1-2001.
POSIX.1-2001 marks
.BR ualarm ()
as obsolete.
-.\" FIXME . Mar 08: The next POSIX.1 revision removes ualarm().
+POSIX.1-2008 removes the specification of
+.BR ualarm ().
4.3BSD, SUSv2, and POSIX do not define any errors.
.SH NOTES
+POSIX.1-2001 does not specify what happens if the
+.I usecs
+argument is 0.
+.\" This case is not documented in HP-US, Solar, FreeBSD, NetBSD, or OpenBSD!
+On Linux (and probably most other systems),
+the effect is to cancel any pending alarm.
+.PP
The type
.I useconds_t
is an unsigned integer type capable of holding integers
Programs will be more portable if they never mention
.I useconds_t
explicitly.
-.LP
+.PP
The interaction of this function with
other timer functions such as
.BR alarm (2),
.BR sleep (3),
.BR nanosleep (2),
.BR setitimer (2),
-.BR timer_create (3),
-.BR timer_delete (3),
-.BR timer_getoverrun (3),
-.BR timer_gettime (3),
-.BR timer_settime (3),
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_gettime (2),
+.BR timer_settime (2),
.BR usleep (3)
is unspecified.
-.LP
+.PP
This function is obsolete.
Use
.BR setitimer (2)
or POSIX interval timers
-.RB ( timer_create (3),
+.RB ( timer_create (2),
etc.)
instead.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR alarm (2),
.BR getitimer (2),
.BR nanosleep (2),