1TIMER_CREATE(3P) POSIX Programmer's Manual TIMER_CREATE(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 timer_create — create a per-process timer
13
15 #include <signal.h>
16 #include <time.h>
17 int timer_create(clockid_t clockid, struct sigevent *restrict evp,
19 timer_t *restrict timerid);
20
22 The timer_create() function shall create a per-process timer using the
23 specified clock, clock_id, as the timing base. The timer_create() func‐
24 tion shall return, in the location referenced by timerid, a timer ID of
25 type timer_t used to identify the timer in timer requests. This timer
26 ID shall be unique within the calling process until the timer is
27 deleted. The particular clock, clock_id, is defined in <time.h>. The
28 timer whose ID is returned shall be in a disarmed state upon return
29 from timer_create().
30 The evp argument, if non-NULL, points to a sigevent structure. This
32 structure, allocated by the application, defines the asynchronous noti‐
33 fication to occur as specified in Section 2.4.1, Signal Generation and
34 Delivery when the timer expires. If the evp argument is NULL, the
35 effect is as if the evp argument pointed to a sigevent structure with
36 the sigev_notify member having the value SIGEV_SIGNAL, the sigev_signo
37 having a default signal number, and the sigev_value member having the
38 value of the timer ID.
39 Each implementation shall define a set of clocks that can be used as
41 timing bases for per-process timers. All implementations shall support
42 a clock_id of CLOCK_REALTIME. If the Monotonic Clock option is sup‐
43 ported, implementations shall support a clock_id of CLOCK_MONOTONIC.
44 Per-process timers shall not be inherited by a child process across a
46 fork() and shall be disarmed and deleted by an exec.
47 If _POSIX_CPUTIME is defined, implementations shall support clock_id
49 values representing the CPU-time clock of the calling process.
50 If _POSIX_THREAD_CPUTIME is defined, implementations shall support
52 clock_id values representing the CPU-time clock of the calling thread.
53 It is implementation-defined whether a timer_create() function will
55 succeed if the value defined by clock_id corresponds to the CPU-time
56 clock of a process or thread different from the process or thread
57 invoking the function.
58 If evp->sigev_sigev_notify is SIGEV_THREAD and
60 sev->sigev_notify_attributes is not NULL, if the attribute pointed to
61 by sev->sigev_notify_attributes has a thread stack address specified by
62 a call to pthread_attr_setstack(), the results are unspecified if the
63 signal is generated more than once.
64
66 If the call succeeds, timer_create() shall return zero and update the
67 location referenced by timerid to a timer_t, which can be passed to the
68 per-process timer calls. If an error occurs, the function shall return
69 a value of -1 and set errno to indicate the error. The value of timerid
70 is undefined if an error occurs.
71
73 The timer_create() function shall fail if:
74 EAGAIN The system lacks sufficient signal queuing resources to honor
76 the request.
77 EAGAIN The calling process has already created all of the timers it is
79 allowed by this implementation.
80 EINVAL The specified clock ID is not defined.
82 ENOTSUP
84 The implementation does not support the creation of a timer
85 attached to the CPU-time clock that is specified by clock_id and
86 associated with a process or thread different from the process
87 or thread invoking timer_create().
88 The following sections are informative.
90
92 None.
93
95 If a timer is created which has evp->sigev_sigev_notify set to
96 SIGEV_THREAD and the attribute pointed to by
97 evp->sigev_notify_attributes has a thread stack address specified by a
98 call to pthread_attr_setstack(), the memory dedicated as a thread stack
99 cannot be recovered. The reason for this is that the threads created in
100 response to a timer expiration are created detached, or in an unspeci‐
101 fied way if the thread attribute's detachstate is PTHREAD_CREATE_JOIN‐
102 ABLE. In neither case is it valid to call pthread_join(), which makes
103 it impossible to determine the lifetime of the created thread which
104 thus means the stack memory cannot be reused.
105
107 Periodic Timer Overrun and Resource Allocation
108 The specified timer facilities may deliver realtime signals (that is,
109 queued signals) on implementations that support this option. Since
110 realtime applications cannot afford to lose notifications of asynchro‐
111 nous events, like timer expirations or asynchronous I/O completions, it
112 must be possible to ensure that sufficient resources exist to deliver
113 the signal when the event occurs. In general, this is not a difficulty
114 because there is a one-to-one correspondence between a request and a
115 subsequent signal generation. If the request cannot allocate the signal
116 delivery resources, it can fail the call with an [EAGAIN] error.
117 Periodic timers are a special case. A single request can generate an
119 unspecified number of signals. This is not a problem if the requesting
120 process can service the signals as fast as they are generated, thus
121 making the signal delivery resources available for delivery of subse‐
122 quent periodic timer expiration signals. But, in general, this cannot
123 be assured—processing of periodic timer signals may ``overrun''; that
124 is, subsequent periodic timer expirations may occur before the cur‐
125 rently pending signal has been delivered.
126 Also, for signals, according to the POSIX.1‐1990 standard, if subse‐
128 quent occurrences of a pending signal are generated, it is implementa‐
129 tion-defined whether a signal is delivered for each occurrence. This is
130 not adequate for some realtime applications. So a mechanism is required
131 to allow applications to detect how many timer expirations were delayed
132 without requiring an indefinite amount of system resources to store the
133 delayed expirations.
134 The specified facilities provide for an overrun count. The overrun
136 count is defined as the number of extra timer expirations that occurred
137 between the time a timer expiration signal is generated and the time
138 the signal is delivered. The signal-catching function, if it is con‐
139 cerned with overruns, can retrieve this count on entry. With this
140 method, a periodic timer only needs one ``signal queuing resource''
141 that can be allocated at the time of the timer_create() function call.
142 A function is defined to retrieve the overrun count so that an applica‐
144 tion need not allocate static storage to contain the count, and an
145 implementation need not update this storage asynchronously on timer
146 expirations. But, for some high-frequency periodic applications, the
147 overhead of an additional system call on each timer expiration may be
148 prohibitive. The functions, as defined, permit an implementation to
149 maintain the overrun count in user space, associated with the timerid.
150 The timer_getoverrun() function can then be implemented as a macro that
151 uses the timerid argument (which may just be a pointer to a user space
152 structure containing the counter) to locate the overrun count with no
153 system call overhead. Other implementations, less concerned with this
154 class of applications, can avoid the asynchronous update of user space
155 by maintaining the count in a system structure at the cost of the extra
156 system call to obtain it.
157 Timer Expiration Signal Parameters
159 The Realtime Signals Extension option supports an application-specific
160 datum that is delivered to the extended signal handler. This value is
161 explicitly specified by the application, along with the signal number
162 to be delivered, in a sigevent structure. The type of the application-
163 defined value can be either an integer constant or a pointer. This
164 explicit specification of the value, as opposed to always sending the
165 timer ID, was selected based on existing practice.
166 It is common practice for realtime applications (on non-POSIX systems
168 or realtime extended POSIX systems) to use the parameters of event han‐
169 dlers as the case label of a switch statement or as a pointer to an
170 application-defined data structure. Since timer_ids are dynamically
171 allocated by the timer_create() function, they can be used for neither
172 of these functions without additional application overhead in the sig‐
173 nal handler; for example, to search an array of saved timer IDs to as‐
174 sociate the ID with a constant or application data structure.
175
177 None.
178
180 clock_getres(), timer_delete(), timer_getoverrun()
181 The Base Definitions volume of POSIX.1‐2017, <signal.h>, <time.h>
183
185 Portions of this text are reprinted and reproduced in electronic form
186 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
187 table Operating System Interface (POSIX), The Open Group Base Specifi‐
188 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
189 Electrical and Electronics Engineers, Inc and The Open Group. In the
190 event of any discrepancy between this version and the original IEEE and
191 The Open Group Standard, the original IEEE and The Open Group Standard
192 is the referee document. The original Standard can be obtained online
193 at http://www.opengroup.org/unix/online.html .
194 Any typographical or formatting errors that appear in this page are
196 most likely to have been introduced during the conversion of the source
197 files to man page format. To report such errors, see https://www.ker‐
198 nel.org/doc/man-pages/reporting_bugs.html .
199IEEE/The Open Group 2017 TIMER_CREATE(3P)