290 lines
15 KiB
HTML
290 lines
15 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>clock_getres</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="clock_getres"></a> <a name="tag_03_76"></a><!-- clock_getres -->
|
|
<!--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_76_01"></a>NAME</h4>
|
|
|
|
<blockquote>clock_getres, clock_gettime, clock_settime - clock and timer functions (<b>REALTIME</b>)</blockquote>
|
|
|
|
<h4><a name="tag_03_76_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 clock_getres(clockid_t</tt> <i>clock_id</i><tt>, struct timespec *</tt><i>res</i><tt>);<br>
|
|
int clock_gettime(clockid_t</tt> <i>clock_id</i><tt>, struct timespec *</tt><i>tp</i><tt>);<br>
|
|
int clock_settime(clockid_t</tt> <i>clock_id</i><tt>, const struct timespec *</tt><i>tp</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_76_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>clock_getres</i>() function shall return the resolution of any clock. Clock resolutions are implementation-defined and
|
|
cannot be set by a process. If the argument <i>res</i> is not NULL, the resolution of the specified clock shall be stored in the
|
|
location pointed to by <i>res</i>. If <i>res</i> is NULL, the clock resolution is not returned. If the <i>time</i> argument of
|
|
<i>clock_settime</i>() is not a multiple of <i>res</i>, then the value is truncated to a multiple of <i>res</i>.</p>
|
|
|
|
<p>The <i>clock_gettime</i>() function shall return the current value <i>tp</i> for the specified clock, <i>clock_id</i>.</p>
|
|
|
|
<p>The <i>clock_settime</i>() function shall set the specified clock, <i>clock_id</i>, to the value specified by <i>tp</i>. Time
|
|
values that are between two consecutive non-negative integer multiples of the resolution of the specified clock shall be truncated
|
|
down to the smaller multiple of the resolution.</p>
|
|
|
|
<p>A clock may be system-wide (that is, visible to all processes) or per-process (measuring time that is meaningful only within a
|
|
process). All implementations shall support a <i>clock_id</i> of CLOCK_REALTIME as defined in <a href=
|
|
"../basedefs/time.h.html"><i><time.h></i></a>. This clock represents the realtime clock for the system. For this clock, the
|
|
values returned by <i>clock_gettime</i>() and specified by <i>clock_settime</i>() represent the amount of time (in seconds and
|
|
nanoseconds) since the Epoch. An implementation may also support additional clocks. The interpretation of time values for these
|
|
clocks is unspecified.</p>
|
|
|
|
<p>If the value of the CLOCK_REALTIME clock is set via <i>clock_settime</i>(), the new value of the clock shall be used to
|
|
determine the time of expiration for absolute time services based upon the CLOCK_REALTIME clock. This applies to the time at which
|
|
armed absolute timers expire. If the absolute time requested at the invocation of such a time service is before the new value of
|
|
the clock, the time service shall expire immediately as if the clock had reached the requested time normally.</p>
|
|
|
|
<p>Setting the value of the CLOCK_REALTIME clock via <i>clock_settime</i>() shall have no effect on threads that are blocked
|
|
waiting for a relative time service based upon this clock, including the <a href=
|
|
"../functions/nanosleep.html"><i>nanosleep</i>()</a> function; nor on the expiration of relative timers based upon this clock.
|
|
Consequently, these time services shall expire when the requested relative interval elapses, independently of the new or old value
|
|
of the clock.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('MON')">MON</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If the Monotonic Clock option is supported, all implementations shall support a <i>clock_id</i> of CLOCK_MONOTONIC defined in <a
|
|
href="../basedefs/time.h.html"><i><time.h></i></a>. This clock represents the monotonic clock for the system. For this clock,
|
|
the value returned by <i>clock_gettime</i>() represents the amount of time (in seconds and nanoseconds) since an unspecified point
|
|
in the past (for example, system start-up time, or the Epoch). This point does not change after system start-up time. The value of
|
|
the CLOCK_MONOTONIC clock cannot be set via <i>clock_settime</i>(). This function shall fail if it is invoked with a
|
|
<i>clock_id</i> argument of CLOCK_MONOTONIC. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>The effect of setting a clock via <i>clock_settime</i>() on armed per-process timers associated with a clock other than
|
|
CLOCK_REALTIME is implementation-defined.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('CS')">CS</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> If
|
|
the value of the CLOCK_REALTIME clock is set via <i>clock_settime</i>(), the new value of the clock shall be used to determine the
|
|
time at which the system shall awaken a thread blocked on an absolute <a href=
|
|
"../functions/clock_nanosleep.html"><i>clock_nanosleep</i>()</a> call based upon the CLOCK_REALTIME clock. If the absolute time
|
|
requested at the invocation of such a time service is before the new value of the clock, the call shall return immediately as if
|
|
the clock had reached the requested time normally.</p>
|
|
|
|
<p>Setting the value of the CLOCK_REALTIME clock via <i>clock_settime</i>() shall have no effect on any thread that is blocked on a
|
|
relative <a href="../functions/clock_nanosleep.html"><i>clock_nanosleep</i>()</a> call. Consequently, the call shall return when
|
|
the requested relative interval elapses, independently of the new or old value of the clock. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></p>
|
|
|
|
<p>The appropriate privilege to set a particular clock is implementation-defined.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('CPT')">CPT</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If _POSIX_CPUTIME is defined, implementations shall support clock ID values obtained by invoking <a href=
|
|
"../functions/clock_getcpuclockid.html"><i>clock_getcpuclockid</i>()</a>, which represent the CPU-time clock of a given process.
|
|
Implementations shall also support the special <b>clockid_t</b> value CLOCK_PROCESS_CPUTIME_ID, which represents the CPU-time clock
|
|
of the calling process when invoking one of the <a href="../functions/clock_gettime.html"><i>clock_*</i>()</a> or <a href=
|
|
"../functions/timer_create.html"><i>timer_*</i>()</a> functions. For these clock IDs, the values returned by <i>clock_gettime</i>() and
|
|
specified by <i>clock_settime</i>() represent the amount of execution time of the process associated with the clock. Changing the
|
|
value of a CPU-time clock via <i>clock_settime</i>() shall have no effect on the behavior of the sporadic server scheduling policy
|
|
(see <a href="xsh_chap02_08.html#tag_02_08_04_01"><i>Scheduling Policies</i></a> ). <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('TCT')">TCT</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If _POSIX_THREAD_CPUTIME is defined, implementations shall support clock ID values obtained by invoking <a href=
|
|
"../functions/pthread_getcpuclockid.html"><i>pthread_getcpuclockid</i>()</a>, which represent the CPU-time clock of a given thread.
|
|
Implementations shall also support the special <b>clockid_t</b> value CLOCK_THREAD_CPUTIME_ID, which represents the CPU-time clock
|
|
of the calling thread when invoking one of the <a href="../functions/clock_gettime.html"><i>clock_*</i>()</a> or <a href=
|
|
"../functions/timer_create.html"><i>timer_*</i>()</a> functions. For these clock IDs, the values returned by <i>clock_gettime</i>() and
|
|
specified by <i>clock_settime</i>() shall represent the amount of execution time of the thread associated with the clock. Changing
|
|
the value of a CPU-time clock via <i>clock_settime</i>() shall have no effect on the behavior of the sporadic server scheduling
|
|
policy (see <a href="xsh_chap02_08.html#tag_02_08_04_01"><i>Scheduling Policies</i></a> ). <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_76_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>A return value of 0 shall indicate that the call succeeded. A return value of -1 shall indicate that an error occurred, and
|
|
<i>errno</i> shall be set to indicate the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_76_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>clock_getres</i>(), <i>clock_gettime</i>(), and <i>clock_settime</i>() functions shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The <i>clock_id</i> argument does not specify a known clock.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>clock_settime</i>() function shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The <i>tp</i> argument to <i>clock_settime</i>() is outside the range for the given clock ID.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The <i>tp</i> argument specified a nanosecond value less than zero or greater than or equal to 1000 million.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('MON')">MON</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The value of the <i>clock_id</i> argument is CLOCK_MONOTONIC. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
</dl>
|
|
|
|
<p>The <i>clock_settime</i>() function may fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EPERM]</dt>
|
|
|
|
<dd>The requesting process does not have the appropriate privilege to set the specified clock.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_76_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_76_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>These functions are part of the Timers option and need not be available on all implementations.</p>
|
|
|
|
<p>Note that the absolute value of the monotonic clock is meaningless (because its origin is arbitrary), and thus there is no need
|
|
to set it. Furthermore, realtime applications can rely on the fact that the value of this clock is never set and, therefore, that
|
|
time intervals measured with this clock will not be affected by calls to <i>clock_settime</i>().</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_76_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_76_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_76_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="clock_getcpuclockid.html"><i>clock_getcpuclockid</i>()</a> , <a href=
|
|
"clock_nanosleep.html"><i>clock_nanosleep</i>()</a> , <a href="ctime.html"><i>ctime</i>()</a> , <a href=
|
|
"mq_timedreceive.html"><i>mq_timedreceive</i>()</a> , <a href="mq_timedsend.html"><i>mq_timedsend</i>()</a> , <a href=
|
|
"nanosleep.html"><i>nanosleep</i>()</a> , <a href="pthread_mutex_timedlock.html"><i>pthread_mutex_timedlock</i>()</a> , <a href=
|
|
"sem_timedwait.html"><i>sem_timedwait</i>()</a> , <a href="time.html"><i>time</i>()</a> , <a href=
|
|
"timer_create.html"><i>timer_create</i>()</a> , <a href="timer_getoverrun.html"><i>timer_getoverrun</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_76_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_76_12"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<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 APPLICATION USAGE section is added.</p>
|
|
|
|
<p>The following changes were made to align with the IEEE P1003.1a draft standard:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Clarification is added of the effect of resetting the clock resolution.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>CPU-time clocks and the <a href="../functions/clock_getcpuclockid.html"><i>clock_getcpuclockid</i>()</a> function are added for
|
|
alignment with IEEE Std 1003.1d-1999.</p>
|
|
|
|
<p>The following changes are added for alignment with IEEE Std 1003.1j-2000:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The DESCRIPTION is updated as follows:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The value returned by <i>clock_gettime</i>() for CLOCK_MONOTONIC is specified.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <i>clock_settime</i>() function failing for CLOCK_MONOTONIC is specified.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The effects of <i>clock_settime</i>() on the <a href="../functions/clock_nanosleep.html"><i>clock_nanosleep</i>()</a> function
|
|
with respect to CLOCK_REALTIME is specified.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<p>An [EINVAL] error is added to the ERRORS section, indicating that <i>clock_settime</i>() fails for CLOCK_MONOTONIC.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The APPLICATION USAGE section notes that the CLOCK_MONOTONIC clock need not and shall not be set by <i>clock_settime</i>() since
|
|
the absolute value of the CLOCK_MONOTONIC clock is meaningless.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <a href="../functions/clock_nanosleep.html"><i>clock_nanosleep</i>()</a>, <a href=
|
|
"../functions/mq_timedreceive.html"><i>mq_timedreceive</i>()</a>, <a href=
|
|
"../functions/mq_timedsend.html"><i>mq_timedsend</i>()</a>, <a href=
|
|
"../functions/pthread_mutex_timedlock.html"><i>pthread_mutex_timedlock</i>()</a>, <a href=
|
|
"../functions/sem_timedwait.html"><i>sem_timedwait</i>()</a>, <a href="../functions/timer_create.html"><i>timer_create</i>()</a>,
|
|
and <a href="../functions/timer_settime.html"><i>timer_settime</i>()</a> functions are added to the SEE ALSO section.</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>
|
|
|