208 lines
11 KiB
HTML
208 lines
11 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>timer_getoverrun</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="timer_getoverrun"></a> <a name="tag_03_778"></a><!-- timer_getoverrun -->
|
|
<!--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_778_01"></a>NAME</h4>
|
|
|
|
<blockquote>timer_getoverrun, timer_gettime, timer_settime - per-process timers (<b>REALTIME</b>)</blockquote>
|
|
|
|
<h4><a name="tag_03_778_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('TMR')">TMR</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> #include <<a href="../basedefs/time.h.html">time.h</a>><br>
|
|
<br>
|
|
int timer_getoverrun(timer_t</tt> <i>timerid</i><tt>);<br>
|
|
int timer_gettime(timer_t</tt> <i>timerid</i><tt>, struct itimerspec *</tt><i>value</i><tt>);<br>
|
|
int timer_settime(timer_t</tt> <i>timerid</i><tt>, int</tt> <i>flags</i><tt>,<br>
|
|
const struct itimerspec *restrict</tt> <i>value</i><tt>,<br>
|
|
struct itimerspec *restrict</tt> <i>ovalue</i><tt>); <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_778_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>timer_gettime</i>() function shall store the amount of time until the specified timer, <i>timerid</i>, expires and the
|
|
reload value of the timer into the space pointed to by the <i>value</i> argument. The <i>it_value</i> member of this structure
|
|
shall contain the amount of time before the timer expires, or zero if the timer is disarmed. This value is returned as the interval
|
|
until timer expiration, even if the timer was armed with absolute time. The <i>it_interval</i> member of <i>value</i> shall contain
|
|
the reload value last set by <i>timer_settime</i>().</p>
|
|
|
|
<p>The <i>timer_settime</i>() function shall set the time until the next expiration of the timer specified by <i>timerid</i> from
|
|
the <i>it_value</i> member of the <i>value</i> argument and arm the timer if the <i>it_value</i> member of <i>value</i> is
|
|
non-zero. If the specified timer was already armed when <i>timer_settime</i>() is called, this call shall reset the time until next
|
|
expiration to the <i>value</i> specified. If the <i>it_value</i> member of <i>value</i> is zero, the timer shall be disarmed. The
|
|
effect of disarming or resetting a timer with pending expiration notifications is unspecified.</p>
|
|
|
|
<p>If the flag TIMER_ABSTIME is not set in the argument <i>flags</i>, <i>timer_settime</i>() shall behave as if the time until next
|
|
expiration is set to be equal to the interval specified by the <i>it_value</i> member of <i>value</i>. That is, the timer shall
|
|
expire in <i>it_value</i> nanoseconds from when the call is made. If the flag TIMER_ABSTIME is set in the argument <i>flags</i>,
|
|
<i>timer_settime</i>() shall behave as if the time until next expiration is set to be equal to the difference between the absolute
|
|
time specified by the <i>it_value</i> member of <i>value</i> and the current value of the clock associated with <i>timerid</i>.
|
|
That is, the timer shall expire when the clock reaches the value specified by the <i>it_value</i> member of <i>value</i>. If the
|
|
specified time has already passed, the function shall succeed and the expiration notification shall be made.</p>
|
|
|
|
<p>The reload value of the timer shall be set to the value specified by the <i>it_interval</i> member of <i>value</i>. When a timer
|
|
is armed with a non-zero <i>it_interval</i>, a periodic (or repetitive) timer is specified.</p>
|
|
|
|
<p>Time values that are between two consecutive non-negative integer multiples of the resolution of the specified timer shall be
|
|
rounded up to the larger multiple of the resolution. Quantization error shall not cause the timer to expire earlier than the
|
|
rounded time value.</p>
|
|
|
|
<p>If the argument <i>ovalue</i> is not NULL, the <i>timer_settime</i>() function shall store, in the location referenced by
|
|
<i>ovalue</i>, a value representing the previous amount of time before the timer would have expired, or zero if the timer was
|
|
disarmed, together with the previous timer reload value. Timers shall not expire before their scheduled time.</p>
|
|
|
|
<p>Only a single signal shall be queued to the process for a given timer at any point in time. When a timer for which a signal is
|
|
still pending expires, no signal shall be queued, and a timer overrun shall occur. <sup>[<a href=
|
|
"javascript:open_code('RTS')">RTS</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> When a timer
|
|
expiration signal is delivered to or accepted by a process, if the implementation supports the Realtime Signals Extension, the
|
|
<i>timer_getoverrun</i>() function shall return the timer expiration overrun count for the specified timer. The overrun count
|
|
returned contains the number of extra timer expirations that occurred between the time the signal was generated (queued) and when
|
|
it was delivered or accepted, up to but not including an implementation-defined maximum of {DELAYTIMER_MAX}. If the number of such
|
|
extra expirations is greater than or equal to {DELAYTIMER_MAX}, then the overrun count shall be set to {DELAYTIMER_MAX}. The value
|
|
returned by <i>timer_getoverrun</i>() shall apply to the most recent expiration signal delivery or acceptance for the timer. <img
|
|
src="../images/opt-end.gif" alt="[Option End]" border="0"> If no expiration signal has been delivered for the timer, or if the
|
|
Realtime Signals Extension is not supported, the return value of <i>timer_getoverrun</i>() is unspecified.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_778_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>If the <i>timer_getoverrun</i>() function succeeds, it shall return the timer expiration overrun count as explained above.</p>
|
|
|
|
<p>If the <i>timer_gettime</i>() or <i>timer_settime</i>() functions succeed, a value of 0 shall be returned.</p>
|
|
|
|
<p>If an error occurs for any of these functions, the value -1 shall be returned, and <i>errno</i> set to indicate the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_778_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>timer_getoverrun</i>(), <i>timer_gettime</i>(), and <i>timer_settime</i>() functions shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The <i>timerid</i> argument does not correspond to an ID returned by <a href=
|
|
"../functions/timer_create.html"><i>timer_create</i>()</a> but not yet deleted by <a href=
|
|
"../functions/timer_delete.html"><i>timer_delete</i>()</a>.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>timer_settime</i>() function shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>A <i>value</i> structure specified a nanosecond value less than zero or greater than or equal to 1000 million, and the
|
|
<i>it_value</i> member of that structure did not specify zero seconds and nanoseconds.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_778_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_778_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_778_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>Practical clocks tick at a finite rate, with rates of 100 hertz and 1000 hertz being common. The inverse of this tick rate is
|
|
the clock resolution, also called the clock granularity, which in either case is expressed as a time duration, being 10
|
|
milliseconds and 1 millisecond respectively for these common rates. The granularity of practical clocks implies that if one reads a
|
|
given clock twice in rapid succession, one may get the same time value twice; and that timers must wait for the next clock tick
|
|
after the theoretical expiration time, to ensure that a timer never returns too soon. Note also that the granularity of the clock
|
|
may be significantly coarser than the resolution of the data format used to set and get time and interval values. Also note that
|
|
some implementations may choose to adjust time and/or interval values to exactly match the ticks of the underlying clock.</p>
|
|
|
|
<p>This volume of IEEE Std 1003.1-2001 defines functions that allow an application to determine the
|
|
implementation-supported resolution for the clocks and requires an implementation to document the resolution supported for timers
|
|
and <a href="../functions/nanosleep.html"><i>nanosleep</i>()</a> if they differ from the supported clock resolution. This is more
|
|
of a procurement issue than a runtime application issue.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_778_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_778_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="clock_getres.html"><i>clock_getres</i>()</a> , <a href="timer_create.html"><i>timer_create</i>()</a> , the Base
|
|
Definitions volume of IEEE Std 1003.1-2001, <a href="../basedefs/time.h.html"><i><time.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_778_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 5. Included for alignment with the POSIX Realtime Extension.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_778_12"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>timer_getoverrun</i>(), <i>timer_gettime</i>(), and <i>timer_settime</i>() functions are marked as part of the Timers
|
|
option.</p>
|
|
|
|
<p>The [ENOSYS] error condition has been removed as stubs need not be provided if an implementation does not support the Timers
|
|
option.</p>
|
|
|
|
<p>The [EINVAL] error condition is updated to include the following: "and the <i>it_value</i> member of that structure did not
|
|
specify zero seconds and nanoseconds." This change is for IEEE PASC Interpretation 1003.1 #89.</p>
|
|
|
|
<p>The DESCRIPTION for <i>timer_getoverrun</i>() is updated to clarify that "If no expiration signal has been delivered for the
|
|
timer, or if the Realtime Signals Extension is not supported, the return value of <i>timer_getoverrun</i>() is unspecified".</p>
|
|
|
|
<p>The <b>restrict</b> keyword is added to the <i>timer_settime</i>() prototype for alignment with the ISO/IEC 9899:1999
|
|
standard.</p>
|
|
</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>
|
|
|