diff options
Diffstat (limited to 'upstream/archlinux/man3p/alarm.3p')
| -rw-r--r-- | upstream/archlinux/man3p/alarm.3p | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/alarm.3p b/upstream/archlinux/man3p/alarm.3p new file mode 100644 index 00000000..99fb0ab3 --- /dev/null +++ b/upstream/archlinux/man3p/alarm.3p @@ -0,0 +1,165 @@ +'\" 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 . |