diff options
Diffstat (limited to 'man-pages-posix-2003/man3p/alarm.3p')
-rw-r--r-- | man-pages-posix-2003/man3p/alarm.3p | 125 |
1 files changed, 125 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/alarm.3p b/man-pages-posix-2003/man3p/alarm.3p new file mode 100644 index 0000000..dc89a75 --- /dev/null +++ b/man-pages-posix-2003/man3p/alarm.3p @@ -0,0 +1,125 @@ +.\" 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 . |