.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "ALARM" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" alarm 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
alarm \- schedule an alarm signal
.SH SYNOPSIS
.LP
\fB#include <unistd.h>
.br
.sp
unsigned alarm(unsigned\fP \fIseconds\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
The \fIalarm\fP() function shall cause the system to generate a SIGALRM
signal for the process after the number of realtime
seconds specified by \fIseconds\fP have elapsed. Processor scheduling
delays may prevent the process from handling the signal as
soon as it is generated.
.LP
If \fIseconds\fP is 0, a pending alarm request, if any, is canceled.
.LP
Alarm requests are not stacked; only one SIGALRM generation can be
scheduled in this manner. If the SIGALRM signal has not yet
been generated, the call shall result in rescheduling the time at
which the SIGALRM signal is generated.
.LP
Interactions between \fIalarm\fP() and any of \fIsetitimer\fP(), \fIualarm\fP(),
or \fIusleep\fP() are unspecified. 
.SH RETURN VALUE
.LP
If there is a previous \fIalarm\fP() request with time remaining,
\fIalarm\fP() shall return a non-zero value that is the
number of seconds until the previous request would have generated
a SIGALRM signal. Otherwise, \fIalarm\fP() shall return 0.
.SH ERRORS
.LP
The \fIalarm\fP() function is always successful, and no return value
is reserved to indicate an error.
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
The \fIfork\fP() function clears pending alarms in the child process.
A new process image
created by one of the \fIexec\fP functions inherits the time left
to an alarm signal in the
old process' image.
.LP
Application writers should note that the type of the argument \fIseconds\fP
and the return value of \fIalarm\fP() is
\fBunsigned\fP. That means that a Strictly Conforming POSIX System
Interfaces Application cannot pass a value greater than the
minimum guaranteed value for {UINT_MAX}, which the ISO\ C standard
sets as 65535, and any application passing a larger value is
restricting its portability. A different type was considered, but
historical implementations, including those with a 16-bit
\fBint\fP type, consistently use either \fBunsigned\fP or \fBint\fP.
.LP
Application writers should be aware of possible interactions when
the same process uses both the \fIalarm\fP() and \fIsleep\fP() functions.
.SH RATIONALE
.LP
Many historical implementations (including Version 7 and System V)
allow an alarm to occur up to a second early. Other
implementations allow alarms up to half a second or one clock tick
early or do not allow them to occur early at all. The latter is
considered most appropriate, since it gives the most predictable behavior,
especially since the signal can always be delayed for an
indefinite amount of time due to scheduling. Applications can thus
choose the \fIseconds\fP argument as the minimum amount of time
they wish to have elapse before the signal.
.LP
The term "realtime" here and elsewhere ( \fIsleep\fP(), \fItimes\fP())
is intended to mean "wall clock" time as common English usage, and
has nothing to
do with "realtime operating systems". It is in contrast to \fIvirtual
time\fP, which could be misinterpreted if just \fItime\fP
were used.
.LP
In some implementations, including 4.3 BSD, very large values of the
\fIseconds\fP argument are silently rounded down to an
implementation-defined maximum value. This maximum is large enough
(to the order of several months) that the effect is not
noticeable.
.LP
There were two possible choices for alarm generation in multi-threaded
applications: generation for the calling thread or
generation for the process. The first option would not have been particularly
useful since the alarm state is maintained on a
per-process basis and the alarm that is established by the last invocation
of \fIalarm\fP() is the only one that would be
active.
.LP
Furthermore, allowing generation of an asynchronous signal for a thread
would have introduced an exception to the overall signal
model. This requires a compelling reason in order to be justified.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
alarm, \fIexec\fP(), \fIfork\fP(), \fIgetitimer\fP(), \fIpause\fP(),
\fIsigaction\fP(), \fIsleep\fP(), \fIualarm\fP(),
\fIusleep\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
\fI<signal.h>\fP, \fI<unistd.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .