171 lines
7.8 KiB
HTML
171 lines
7.8 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>alarm</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="alarm"></a> <a name="tag_03_21"></a><!-- alarm -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_21_01"></a>NAME</h4>
|
|
|
|
<blockquote>alarm - schedule an alarm signal</blockquote>
|
|
|
|
<h4><a name="tag_03_21_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/unistd.h.html">unistd.h</a>><br>
|
|
<br>
|
|
unsigned alarm(unsigned</tt> <i>seconds</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_21_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>alarm</i>() function shall cause the system to generate a SIGALRM signal for the process after the number of realtime
|
|
seconds specified by <i>seconds</i> have elapsed. Processor scheduling delays may prevent the process from handling the signal as
|
|
soon as it is generated.</p>
|
|
|
|
<p>If <i>seconds</i> is 0, a pending alarm request, if any, is canceled.</p>
|
|
|
|
<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>
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Interactions between <i>alarm</i>() and any of <a href="../functions/setitimer.html"><i>setitimer</i>()</a>, <a href=
|
|
"../functions/ualarm.html"><i>ualarm</i>()</a>, or <a href="../functions/usleep.html"><i>usleep</i>()</a> are unspecified. <img
|
|
src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_21_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>If there is a previous <i>alarm</i>() request with time remaining, <i>alarm</i>() shall return a non-zero value that is the
|
|
number of seconds until the previous request would have generated a SIGALRM signal. Otherwise, <i>alarm</i>() shall return 0.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_21_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>alarm</i>() function is always successful, and no return value is reserved to indicate an error.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_21_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_21_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <a href="../functions/fork.html"><i>fork</i>()</a> function clears pending alarms in the child process. A new process image
|
|
created by one of the <i><a href="../functions/exec.html">exec</a></i> functions inherits the time left to an alarm signal in the
|
|
old process' image.</p>
|
|
|
|
<p>Application writers should note that the type of the argument <i>seconds</i> and the return value of <i>alarm</i>() is
|
|
<b>unsigned</b>. 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
|
|
<b>int</b> type, consistently use either <b>unsigned</b> or <b>int</b>.</p>
|
|
|
|
<p>Application writers should be aware of possible interactions when the same process uses both the <i>alarm</i>() and <a href=
|
|
"../functions/sleep.html"><i>sleep</i>()</a> functions.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_21_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>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 <i>seconds</i> argument as the minimum amount of time
|
|
they wish to have elapse before the signal.</p>
|
|
|
|
<p>The term "realtime" here and elsewhere ( <a href="../functions/sleep.html"><i>sleep</i>()</a>, <a href=
|
|
"../functions/times.html"><i>times</i>()</a>) 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 <i>virtual time</i>, which could be misinterpreted if just <i>time</i>
|
|
were used.</p>
|
|
|
|
<p>In some implementations, including 4.3 BSD, very large values of the <i>seconds</i> 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.</p>
|
|
|
|
<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 <i>alarm</i>() is the only one that would be
|
|
active.</p>
|
|
|
|
<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.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_21_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_21_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="#">alarm</a> , <a href="exec.html"><i><a href="../functions/exec.html">exec</a></i>()</a> , <a href=
|
|
"fork.html"><i>fork</i>()</a> , <a href="getitimer.html"><i>getitimer</i>()</a> , <a href="pause.html"><i>pause</i>()</a> , <a
|
|
href="sigaction.html"><i>sigaction</i>()</a> , <a href="sleep.html"><i>sleep</i>()</a> , <a href="ualarm.html"><i>ualarm</i>()</a>
|
|
, <a href="usleep.html"><i>usleep</i>()</a> , the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/signal.h.html"><i><signal.h></i></a>, <a href="../basedefs/unistd.h.html"><i><unistd.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_21_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 1. Derived from Issue 1 of the SVID.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_21_12"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The DESCRIPTION is updated to indicate that interactions with the <a href="../functions/setitimer.html"><i>setitimer</i>()</a>,
|
|
<a href="../functions/ualarm.html"><i>ualarm</i>()</a>, and <a href="../functions/usleep.html"><i>usleep</i>()</a> functions are
|
|
unspecified.</p>
|
|
</li>
|
|
</ul>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|