1TIMER_CREATE(P) POSIX Programmer's Manual TIMER_CREATE(P)
2
6 timer_create - create a per-process timer (REALTIME)
7
9 #include <signal.h>
10 #include <time.h>
11 int timer_create(clockid_t clockid, struct sigevent *restrict evp,
13 timer_t *restrict timerid);
14
17 The timer_create() function shall create a per-process timer using the
18 specified clock, clock_id, as the timing base. The timer_create() func‐
19 tion shall return, in the location referenced by timerid, a timer ID of
20 type timer_t used to identify the timer in timer requests. This timer
21 ID shall be unique within the calling process until the timer is
22 deleted. The particular clock, clock_id, is defined in <time.h>. The
23 timer whose ID is returned shall be in a disarmed state upon return
24 from timer_create().
25 The evp argument, if non-NULL, points to a sigevent structure. This
27 structure, allocated by the application, defines the asynchronous noti‐
28 fication to occur as specified in Signal Generation and Delivery when
29 the timer expires. If the evp argument is NULL, the effect is as if the
30 evp argument pointed to a sigevent structure with the sigev_notify mem‐
31 ber having the value SIGEV_SIGNAL, the sigev_signo having a default
32 signal number, and the sigev_value member having the value of the timer
33 ID.
34 Each implementation shall define a set of clocks that can be used as
36 timing bases for per-process timers. All implementations shall support
37 a clock_id of CLOCK_REALTIME. If the Monotonic Clock option is sup‐
38 ported, implementations shall support a clock_id of CLOCK_MONOTONIC.
39 Per-process timers shall not be inherited by a child process across a
41 fork() and shall be disarmed and deleted by an exec.
42 If _POSIX_CPUTIME is defined, implementations shall support clock_id
44 values representing the CPU-time clock of the calling process.
45 If _POSIX_THREAD_CPUTIME is defined, implementations shall support
47 clock_id values representing the CPU-time clock of the calling thread.
48 It is implementation-defined whether a timer_create() function will
50 succeed if the value defined by clock_id corresponds to the CPU-time
51 clock of a process or thread different from the process or thread
52 invoking the function.
53
55 If the call succeeds, timer_create() shall return zero and update the
56 location referenced by timerid to a timer_t, which can be passed to the
57 per-process timer calls. If an error occurs, the function shall return
58 a value of -1 and set errno to indicate the error. The value of timerid
59 is undefined if an error occurs.
60
62 The timer_create() function shall fail if:
63 EAGAIN The system lacks sufficient signal queuing resources to honor
65 the request.
66 EAGAIN The calling process has already created all of the timers it is
68 allowed by this implementation.
69 EINVAL The specified clock ID is not defined.
71 ENOTSUP
73 The implementation does not support the creation of a timer
74 attached to the CPU-time clock that is specified by clock_id and
75 associated with a process or thread different from the process
76 or thread invoking timer_create().
77 The following sections are informative.
80
82 None.
83
85 None.
86
88 Periodic Timer Overrun and Resource Allocation
89 The specified timer facilities may deliver realtime signals (that is,
90 queued signals) on implementations that support this option. Since
91 realtime applications cannot afford to lose notifications of asynchro‐
92 nous events, like timer expirations or asynchronous I/O completions, it
93 must be possible to ensure that sufficient resources exist to deliver
94 the signal when the event occurs. In general, this is not a difficulty
95 because there is a one-to-one correspondence between a request and a
96 subsequent signal generation. If the request cannot allocate the signal
97 delivery resources, it can fail the call with an [EAGAIN] error.
98 Periodic timers are a special case. A single request can generate an
100 unspecified number of signals. This is not a problem if the requesting
101 process can service the signals as fast as they are generated, thus
102 making the signal delivery resources available for delivery of subse‐
103 quent periodic timer expiration signals. But, in general, this cannot
104 be assured-processing of periodic timer signals may "overrun''; that
105 is, subsequent periodic timer expirations may occur before the cur‐
106 rently pending signal has been delivered.
107 Also, for signals, according to the POSIX.1-1990 standard, if subse‐
109 quent occurrences of a pending signal are generated, it is implementa‐
110 tion-defined whether a signal is delivered for each occurrence. This
111 is not adequate for some realtime applications. So a mechanism is
112 required to allow applications to detect how many timer expirations
113 were delayed without requiring an indefinite amount of system resources
114 to store the delayed expirations.
115 The specified facilities provide for an overrun count. The overrun
117 count is defined as the number of extra timer expirations that occurred
118 between the time a timer expiration signal is generated and the time
119 the signal is delivered. The signal-catching function, if it is con‐
120 cerned with overruns, can retrieve this count on entry. With this
121 method, a periodic timer only needs one "signal queuing resource" that
122 can be allocated at the time of the timer_create() function call.
123 A function is defined to retrieve the overrun count so that an applica‐
125 tion need not allocate static storage to contain the count, and an
126 implementation need not update this storage asynchronously on timer
127 expirations. But, for some high-frequency periodic applications, the
128 overhead of an additional system call on each timer expiration may be
129 prohibitive. The functions, as defined, permit an implementation to
130 maintain the overrun count in user space, associated with the timerid.
131 The timer_getoverrun() function can then be implemented as a macro that
132 uses the timerid argument (which may just be a pointer to a user space
133 structure containing the counter) to locate the overrun count with no
134 system call overhead. Other implementations, less concerned with this
135 class of applications, can avoid the asynchronous update of user space
136 by maintaining the count in a system structure at the cost of the extra
137 system call to obtain it.
138 Timer Expiration Signal Parameters
140 The Realtime Signals Extension option supports an application-specific
141 datum that is delivered to the extended signal handler. This value is
142 explicitly specified by the application, along with the signal number
143 to be delivered, in a sigevent structure. The type of the application-
144 defined value can be either an integer constant or a pointer. This
145 explicit specification of the value, as opposed to always sending the
146 timer ID, was selected based on existing practice.
147 It is common practice for realtime applications (on non-POSIX systems
149 or realtime extended POSIX systems) to use the parameters of event han‐
150 dlers as the case label of a switch statement or as a pointer to an
151 application-defined data structure. Since timer_ids are dynamically
152 allocated by the timer_create() function, they can be used for neither
153 of these functions without additional application overhead in the sig‐
154 nal handler; for example, to search an array of saved timer IDs to as‐
155 sociate the ID with a constant or application data structure.
156
158 None.
159
161 clock_getres() , timer_delete() , timer_getoverrun() , the Base Defini‐
162 tions volume of IEEE Std 1003.1-2001, <time.h>
163
165 Portions of this text are reprinted and reproduced in electronic form
166 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
167 -- Portable Operating System Interface (POSIX), The Open Group Base
168 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
169 Electrical and Electronics Engineers, Inc and The Open Group. In the
170 event of any discrepancy between this version and the original IEEE and
171 The Open Group Standard, the original IEEE and The Open Group Standard
172 is the referee document. The original Standard can be obtained online
173 at http://www.opengroup.org/unix/online.html .
174IEEE/The Open Group 2003 TIMER_CREATE(P)