alarm.3p (5446B)
- '\" et
- .TH ALARM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .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
- \(em schedule an alarm signal
- .SH SYNOPSIS
- .LP
- .nf
- #include <unistd.h>
- .P
- unsigned alarm(unsigned \fIseconds\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIalarm\fR()
- function shall cause the system to generate a SIGALRM signal for the
- process after the number of realtime seconds specified by
- .IR seconds
- have elapsed. Processor scheduling delays may prevent the process from
- handling the signal as soon as it is generated.
- .P
- If
- .IR seconds
- is 0, a pending alarm request, if any, is canceled.
- .P
- 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.
- .P
- Interactions between
- \fIalarm\fR()
- and
- \fIsetitimer\fR()
- are unspecified.
- .SH "RETURN VALUE"
- If there is a previous
- \fIalarm\fR()
- request with time remaining,
- \fIalarm\fR()
- shall return a non-zero value that is the number of seconds until the
- previous request would have generated a SIGALRM signal. Otherwise,
- \fIalarm\fR()
- shall return 0.
- .SH ERRORS
- The
- \fIalarm\fR()
- function is always successful, and no return value is reserved to
- indicate an error.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- The
- \fIfork\fR()
- function clears pending alarms in the child process. A new process
- image created by one of the
- .IR exec
- functions inherits the time left to an alarm signal in the
- image of the old process.
- .P
- Application developers should note that the type of the argument
- .IR seconds
- and the return value of
- \fIalarm\fR()
- is
- .BR unsigned .
- 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 65\|535, 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
- .BR int
- type, consistently use either
- .BR unsigned
- or
- .BR int .
- .P
- Application developers should be aware of possible interactions when
- the same process uses both the
- \fIalarm\fR()
- and
- \fIsleep\fR()
- functions.
- .SH RATIONALE
- 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
- .IR seconds
- argument as the minimum amount of time they wish to have elapse before
- the signal.
- .P
- The term ``realtime'' here and elsewhere (\c
- \fIsleep\fR(),
- \fItimes\fR())
- 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.
- .P
- In some implementations, including 4.3 BSD, very large values of the
- .IR seconds
- argument are silently rounded down to an implementation-specific maximum
- value. This maximum is large enough (to the order of several months)
- that the effect is not noticeable.
- .P
- 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\fR()
- is the only one that would be active.
- .P
- 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"
- None.
- .SH "SEE ALSO"
- .IR "\fIalarm\fR\^(\|)",
- .IR "\fIexec\fR\^",
- .IR "\fIfork\fR\^(\|)",
- .IR "\fIgetitimer\fR\^(\|)",
- .IR "\fIpause\fR\^(\|)",
- .IR "\fIsigaction\fR\^(\|)",
- .IR "\fIsleep\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<signal.h>\fP",
- .IR "\fB<unistd.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .