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