📄 clock_settime.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-2004 IEEE and 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, 2004 Edition<br>Copyright © 2001-2004 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 andcannot be set by a process. If the argument <i>res</i> is not NULL, the resolution of the specified clock shall be stored in thelocation 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>. Timevalues that are between two consecutive non-negative integer multiples of the resolution of the specified clock shall be truncateddown 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 aprocess). 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, thevalues returned by <i>clock_gettime</i>() and specified by <i>clock_settime</i>() represent the amount of time (in seconds andnanoseconds) since the Epoch. An implementation may also support additional clocks. The interpretation of time values for theseclocks 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 todetermine the time of expiration for absolute time services based upon the CLOCK_REALTIME clock. This applies to the time at whicharmed absolute timers expire. If the absolute time requested at the invocation of such a time service is before the new value ofthe 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 blockedwaiting 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 valueof 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 <ahref="../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 pointin the past (for example, system start-up time, or the Epoch). This point does not change after system start-up time. The value ofthe 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 thanCLOCK_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"> Ifthe value of the CLOCK_REALTIME clock is set via <i>clock_settime</i>(), the new value of the clock shall be used to determine thetime 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 timerequested at the invocation of such a time service is before the new value of the clock, the call shall return immediately as ifthe 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 arelative <a href="../functions/clock_nanosleep.html"><i>clock_nanosleep</i>()</a> call. Consequently, the call shall return whenthe 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 clockof 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>() andspecified by <i>clock_settime</i>() represent the amount of execution time of the process associated with the clock. Changing thevalue 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 clockof 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>() andspecified by <i>clock_settime</i>() shall represent the amount of execution time of the thread associated with the clock. Changingthe value of a CPU-time clock via <i>clock_settime</i>() shall have no effect on the behavior of the sporadic server schedulingpolicy (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 needto set it. Furthermore, realtime applications can rely on the fact that the value of this clock is never set and, therefore, thattime 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 BaseDefinitions 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 Timersoption.</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 foralignment 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> functionwith respect to CLOCK_REALTIME are 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>() sincethe 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 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>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -