📄 timer_create.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>timer_create</title></head><body bgcolor="white"><script type="text/javascript" language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> <a name="timer_create"></a> <a name="tag_03_776"></a><!-- timer_create --> <!--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_776_01"></a>NAME</h4><blockquote>timer_create - create a per-process timer (<b>REALTIME</b>)</blockquote><h4><a name="tag_03_776_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/signal.h.html">signal.h</a>><br> #include <<a href="../basedefs/time.h.html">time.h</a>><br><br> int timer_create(clockid_t</tt> <i>clockid</i><tt>, struct sigevent *restrict</tt> <i>evp</i><tt>,<br> timer_t *restrict</tt> <i>timerid</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_776_03"></a>DESCRIPTION</h4><blockquote><p>The <i>timer_create</i>() function shall create a per-process timer using the specified clock, <i>clock_id</i>, as the timingbase. The <i>timer_create</i>() function shall return, in the location referenced by <i>timerid</i>, a timer ID of type<b>timer_t</b> used to identify the timer in timer requests. This timer ID shall be unique within the calling process until thetimer is deleted. The particular clock, <i>clock_id</i>, is defined in <a href="../basedefs/time.h.html"><i><time.h></i></a>.The timer whose ID is returned shall be in a disarmed state upon return from <i>timer_create</i>().</p><p>The <i>evp</i> argument, if non-NULL, points to a <b>sigevent</b> structure. This structure, allocated by the application,defines the asynchronous notification to occur as specified in <a href="xsh_chap02_04.html#tag_02_04_01"><i>Signal Generation andDelivery</i></a> when the timer expires. If the <i>evp</i> argument is NULL, the effect is as if the <i>evp</i> argument pointed toa <b>sigevent</b> structure with the <i>sigev_notify</i> member having the value SIGEV_SIGNAL, the <i>sigev_signo</i> having adefault signal number, and the <i>sigev_value</i> member having the value of the timer ID.</p><p>Each implementation shall define a set of clocks that can be used as timing bases for per-process timers. All implementationsshall support a <i>clock_id</i> of CLOCK_REALTIME. <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, implementations shallsupport a <i>clock_id</i> of CLOCK_MONOTONIC. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p><p>Per-process timers shall not be inherited by a child process across a <a href="../functions/fork.html"><i>fork</i>()</a> andshall be disarmed and deleted by an <i><a href="../functions/exec.html">exec</a></i>.</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 <i>clock_id</i> values representing the CPU-time clock of the callingprocess. <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 <i>clock_id</i> values representing the CPU-time clock of thecalling thread. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p><p><sup>[<a href="javascript:open_code('CPT')">CPT|TCT</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> It is implementation-defined whether a <i>timer_create</i>() function will succeed if the value defined by <i>clock_id</i>corresponds to the CPU-time clock of a process or thread different from the process or thread invoking the function. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p><p><sup>[<a href="javascript:open_code('TSA')">TSA</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">If <i>evp</i>-><i>sigev_sigev_notify</i> is SIGEV_THREAD and <i>sev</i>-><i>sigev_notify_attributes</i> is not NULL, if theattribute pointed to by <i>sev</i>-><i>sigev_notify_attributes</i> has a thread stack address specified by a call to <a href="../functions/pthread_attr_setstack.html"><i>pthread_attr_setstack</i>()</a> or <a href="../functions/pthread_attr_setstackaddr.html"><i>pthread_attr_setstackaddr</i>()</a>, the results are unspecified if the signal isgenerated more than once. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p></blockquote><h4><a name="tag_03_776_04"></a>RETURN VALUE</h4><blockquote><p>If the call succeeds, <i>timer_create</i>() shall return zero and update the location referenced by <i>timerid</i> to a<b>timer_t</b>, which can be passed to the per-process timer calls. If an error occurs, the function shall return a value of -1 andset <i>errno</i> to indicate the error. The value of <i>timerid</i> is undefined if an error occurs.</p></blockquote><h4><a name="tag_03_776_05"></a>ERRORS</h4><blockquote><p>The <i>timer_create</i>() function shall fail if:</p><dl compact><dt>[EAGAIN]</dt><dd>The system lacks sufficient signal queuing resources to honor the request.</dd><dt>[EAGAIN]</dt><dd>The calling process has already created all of the timers it is allowed by this implementation.</dd><dt>[EINVAL]</dt><dd>The specified clock ID is not defined.</dd><dt>[ENOTSUP]</dt><dd><sup>[<a href="javascript:open_code('CPT')">CPT|TCT</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> The implementation does not support the creation of a timer attached to the CPU-time clock that is specified by<i>clock_id</i> and associated with a process or thread different from the process or thread invoking <i>timer_create</i>(). <imgsrc="../images/opt-end.gif" alt="[Option End]" border="0"></dd></dl></blockquote><hr><div class="box"><em>The following sections are informative.</em></div><h4><a name="tag_03_776_06"></a>EXAMPLES</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_776_07"></a>APPLICATION USAGE</h4><blockquote><p>If a timer is created which has <i>evp</i>-><i>sigev_sigev_notify</i> set to SIGEV_THREAD and the attribute pointed to by<i>evp</i>-><i>sigev_notify_attributes</i> has a thread stack address specified by a call to either <a href="../functions/pthread_attr_setstack.html"><i>pthread_attr_setstack</i>()</a> or <a href="../functions/pthread_attr_setstackaddr.html"><i>pthread_attr_setstackaddr</i>()</a>, the memory dedicated as a thread stack cannotbe recovered. The reason for this is that the threads created in response to a timer expiration are created detached, or in anunspecified way if the thread attribute's <i>detachstate</i> is PTHREAD_CREATE_JOINABLE. In neither case is it valid to call <ahref="../functions/pthread_join.html"><i>pthread_join</i>()</a>, which makes it impossible to determine the lifetime of the createdthread which thus means the stack memory cannot be reused.<br></p></blockquote><h4><a name="tag_03_776_08"></a>RATIONALE</h4><blockquote><p></p><h5><a name="tag_03_776_08_01"></a>Periodic Timer Overrun and Resource Allocation</h5><p>The specified timer facilities may deliver realtime signals (that is, queued signals) on implementations that support thisoption. Since realtime applications cannot afford to lose notifications of asynchronous events, like timer expirations orasynchronous I/O completions, it must be possible to ensure that sufficient resources exist to deliver the signal when the eventoccurs. In general, this is not a difficulty because there is a one-to-one correspondence between a request and a subsequent signalgeneration. If the request cannot allocate the signal delivery resources, it can fail the call with an [EAGAIN] error.</p><p>Periodic timers are a special case. A single request can generate an unspecified number of signals. This is not a problem if therequesting process can service the signals as fast as they are generated, thus making the signal delivery resources available fordelivery of subsequent periodic timer expiration signals. But, in general, this cannot be assured-processing of periodic timersignals may "overrun''; that is, subsequent periodic timer expirations may occur before the currently pending signal has beendelivered.</p><p>Also, for signals, according to the POSIX.1-1990 standard, if subsequent occurrences of a pending signal are generated, it isimplementation-defined whether a signal is delivered for each occurrence. This is not adequate for some realtime applications. So amechanism is required to allow applications to detect how many timer expirations were delayed without requiring an indefiniteamount of system resources to store the delayed expirations.</p><p>The specified facilities provide for an overrun count. The overrun count is defined as the number of extra timer expirationsthat occurred between the time a timer expiration signal is generated and the time the signal is delivered. The signal-catchingfunction, if it is concerned with overruns, can retrieve this count on entry. With this method, a periodic timer only needs one"signal queuing resource" that can be allocated at the time of the <i>timer_create</i>() function call.</p><p>A function is defined to retrieve the overrun count so that an application need not allocate static storage to contain thecount, and an implementation need not update this storage asynchronously on timer expirations. But, for some high-frequencyperiodic applications, the overhead of an additional system call on each timer expiration may be prohibitive. The functions, asdefined, permit an implementation to maintain the overrun count in user space, associated with the <i>timerid</i>. The <a href="../functions/timer_getoverrun.html"><i>timer_getoverrun</i>()</a> function can then be implemented as a macro that uses the<i>timerid</i> argument (which may just be a pointer to a user space structure containing the counter) to locate the overrun countwith no system call overhead. Other implementations, less concerned with this class of applications, can avoid the asynchronousupdate of user space by maintaining the count in a system structure at the cost of the extra system call to obtain it.</p><h5><a name="tag_03_776_08_02"></a>Timer Expiration Signal Parameters</h5><p>The Realtime Signals Extension option supports an application-specific datum that is delivered to the extended signal handler.This value is explicitly specified by the application, along with the signal number to be delivered, in a <b>sigevent</b>structure. The type of the application-defined value can be either an integer constant or a pointer. This explicit specification ofthe value, as opposed to always sending the timer ID, was selected based on existing practice.</p><p>It is common practice for realtime applications (on non-POSIX systems or realtime extended POSIX systems) to use the parametersof event handlers as the case label of a switch statement or as a pointer to an application-defined data structure. Since<i>timer_id</i>s are dynamically allocated by the <i>timer_create</i>() function, they can be used for neither of these functionswithout additional application overhead in the signal handler; for example, to search an array of saved timer IDs to associate theID with a constant or application data structure.</p></blockquote><h4><a name="tag_03_776_09"></a>FUTURE DIRECTIONS</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_776_10"></a>SEE ALSO</h4><blockquote><p><a href="clock_getres.html"><i>clock_getres</i>()</a>, <a href="timer_delete.html"><i>timer_delete</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_776_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_776_12"></a>Issue 6</h4><blockquote><p>The <i>timer_create</i>() function is 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 Timersoption.</p><p>CPU-time clocks are added for alignment with IEEE Std 1003.1d-1999.</p><p>The DESCRIPTION is updated for alignment with IEEE Std 1003.1j-2000 by adding the requirement for the CLOCK_MONOTONICclock under the Monotonic Clock option.</p><p>The <b>restrict</b> keyword is added to the <i>timer_create</i>() prototype for alignment with the ISO/IEC 9899:1999standard.</p><p>IEEE Std 1003.1-2001/Cor 2-2004, item XSH/TC2/D6/138 is applied, updating the DESCRIPTION and APPLICATION USAGEsections to describe the case when a timer is created with the notification method set to SIGEV_THREAD.</p></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 + -