.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
.\"             and Copyright (C) 1993 Michael Haardt, Ian Jackson.
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" Modified Wed Jul 21 19:42:57 1993 by Rik Faith <faith@cs.unc.edu>
.\" Modified Sun Jul 21 21:25:26 1996 by Andries Brouwer <aeb@cwi.nl>
.\" Modified Wed Nov  6 03:46:05 1996 by Eric S. Raymond <esr@thyrsus.com>
.\"
.TH alarm 2 2023-03-30 "Linux man-pages 6.05.01"
.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>
.PP
.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.
.PP
If
.I seconds
is zero, any pending alarm is canceled.
.PP
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.
.PP
Alarms created by
.BR alarm ()
are preserved across
.BR execve (2)
and are not inherited by children created via
.BR fork (2).
.PP
.BR sleep (3)
may be implemented using
.BR SIGALRM ;
mixing calls to
.BR alarm ()
and
.BR sleep (3)
is a bad idea.
.PP
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)