.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH alarm 2 (date) "Linux man-pages (unreleased)"
.SH NAME
alarm \- set an alarm clock for delivery of a signal
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.B #include <unistd.h>
.P
.BI "unsigned int alarm(unsigned int " seconds );
.fi
.SH DESCRIPTION
.BR alarm ()
arranges for a
.B SIGALRM
signal to be delivered to the calling process in
.I seconds
seconds.
.P
If
.I seconds
is zero, any pending alarm is canceled.
.P
In any event any previously set
.BR alarm ()
is canceled.
.SH RETURN VALUE
.BR alarm ()
returns the number of seconds remaining until any previously scheduled
alarm was due to be delivered, or zero if there was no previously
scheduled alarm.
.SH STANDARDS
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, SVr4, 4.3BSD.
.SH NOTES
.BR alarm ()
and
.BR setitimer (2)
share the same timer; calls to one will interfere with use of the
other.
.P
Alarms created by
.BR alarm ()
are preserved across
.BR execve (2)
and are not inherited by children created via
.BR fork (2).
.P
.BR sleep (3)
may be implemented using
.BR SIGALRM ;
mixing calls to
.BR alarm ()
and
.BR sleep (3)
is a bad idea.
.P
Scheduling delays can, as ever, cause the execution of the process to
be delayed by an arbitrary amount of time.
.SH SEE ALSO
.BR gettimeofday (2),
.BR pause (2),
.BR select (2),
.BR setitimer (2),
.BR sigaction (2),
.BR signal (2),
.BR timer_create (2),
.BR timerfd_create (2),
.BR sleep (3),
.BR time (7)