1timer_create(2) System Calls Manual timer_create(2)
2
6 timer_create - create a POSIX per-process timer
7
9 Real-time library (librt, -lrt)
10
12 #include <signal.h> /* Definition of SIGEV_* constants */
13 #include <time.h>
14 int timer_create(clockid_t clockid,
16 struct sigevent *_Nullable restrict sevp,
17 timer_t *restrict timerid);
18 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
20 timer_create():
22 _POSIX_C_SOURCE >= 199309L
23
25 timer_create() creates a new per-process interval timer. The ID of the
26 new timer is returned in the buffer pointed to by timerid, which must
27 be a non-null pointer. This ID is unique within the process, until the
28 timer is deleted. The new timer is initially disarmed.
29 The clockid argument specifies the clock that the new timer uses to
31 measure time. It can be specified as one of the following values:
32 CLOCK_REALTIME
34 A settable system-wide real-time clock.
35 CLOCK_MONOTONIC
37 A nonsettable monotonically increasing clock that measures time
38 from some unspecified point in the past that does not change af‐
39 ter system startup.
40 CLOCK_PROCESS_CPUTIME_ID (since Linux 2.6.12)
42 A clock that measures (user and system) CPU time consumed by
43 (all of the threads in) the calling process.
44 CLOCK_THREAD_CPUTIME_ID (since Linux 2.6.12)
46 A clock that measures (user and system) CPU time consumed by the
47 calling thread.
48 CLOCK_BOOTTIME (Since Linux 2.6.39)
50 Like CLOCK_MONOTONIC, this is a monotonically increasing clock.
51 However, whereas the CLOCK_MONOTONIC clock does not measure the
52 time while a system is suspended, the CLOCK_BOOTTIME clock does
53 include the time during which the system is suspended. This is
54 useful for applications that need to be suspend-aware.
55 CLOCK_REALTIME is not suitable for such applications, since that
56 clock is affected by discontinuous changes to the system clock.
57 CLOCK_REALTIME_ALARM (since Linux 3.0)
59 This clock is like CLOCK_REALTIME, but will wake the system if
60 it is suspended. The caller must have the CAP_WAKE_ALARM capa‐
61 bility in order to set a timer against this clock.
62 CLOCK_BOOTTIME_ALARM (since Linux 3.0)
64 This clock is like CLOCK_BOOTTIME, but will wake the system if
65 it is suspended. The caller must have the CAP_WAKE_ALARM capa‐
66 bility in order to set a timer against this clock.
67 CLOCK_TAI (since Linux 3.10)
69 A system-wide clock derived from wall-clock time but ignoring
70 leap seconds.
71 See clock_getres(2) for some further details on the above clocks.
73 As well as the above values, clockid can be specified as the clockid
75 returned by a call to clock_getcpuclockid(3) or pthread_getcpu‐
76 clockid(3).
77 The sevp argument points to a sigevent structure that specifies how the
79 caller should be notified when the timer expires. For the definition
80 and general details of this structure, see sigevent(7).
81 The sevp.sigev_notify field can have the following values:
83 SIGEV_NONE
85 Don't asynchronously notify when the timer expires. Progress of
86 the timer can be monitored using timer_gettime(2).
87 SIGEV_SIGNAL
89 Upon timer expiration, generate the signal sigev_signo for the
90 process. See sigevent(7) for general details. The si_code
91 field of the siginfo_t structure will be set to SI_TIMER. At
92 any point in time, at most one signal is queued to the process
93 for a given timer; see timer_getoverrun(2) for more details.
94 SIGEV_THREAD
96 Upon timer expiration, invoke sigev_notify_function as if it
97 were the start function of a new thread. See sigevent(7) for
98 details.
99 SIGEV_THREAD_ID (Linux-specific)
101 As for SIGEV_SIGNAL, but the signal is targeted at the thread
102 whose ID is given in sigev_notify_thread_id, which must be a
103 thread in the same process as the caller. The sigev_no‐
104 tify_thread_id field specifies a kernel thread ID, that is, the
105 value returned by clone(2) or gettid(2). This flag is intended
106 only for use by threading libraries.
107 Specifying sevp as NULL is equivalent to specifying a pointer to a
109 sigevent structure in which sigev_notify is SIGEV_SIGNAL, sigev_signo
110 is SIGALRM, and sigev_value.sival_int is the timer ID.
111
113 On success, timer_create() returns 0, and the ID of the new timer is
114 placed in *timerid. On failure, -1 is returned, and errno is set to
115 indicate the error.
116
118 EAGAIN Temporary error during kernel allocation of timer structures.
119 EINVAL Clock ID, sigev_notify, sigev_signo, or sigev_notify_thread_id
121 is invalid.
122 ENOMEM Could not allocate memory.
124 ENOTSUP
126 The kernel does not support creating a timer against this
127 clockid.
128 EPERM clockid was CLOCK_REALTIME_ALARM or CLOCK_BOOTTIME_ALARM but the
130 caller did not have the CAP_WAKE_ALARM capability.
131
133 C library/kernel differences
134 Part of the implementation of the POSIX timers API is provided by
135 glibc. In particular:
136 • Much of the functionality for SIGEV_THREAD is implemented within
138 glibc, rather than the kernel. (This is necessarily so, since the
139 thread involved in handling the notification is one that must be
140 managed by the C library POSIX threads implementation.) Although
141 the notification delivered to the process is via a thread, inter‐
142 nally the NPTL implementation uses a sigev_notify value of
143 SIGEV_THREAD_ID along with a real-time signal that is reserved by
144 the implementation (see nptl(7)).
145 • The implementation of the default case where evp is NULL is handled
147 inside glibc, which invokes the underlying system call with a suit‐
148 ably populated sigevent structure.
149 • The timer IDs presented at user level are maintained by glibc, which
151 maps these IDs to the timer IDs employed by the kernel.
152
154 POSIX.1-2008.
155
157 Linux 2.6. POSIX.1-2001.
158 Prior to Linux 2.6, glibc provided an incomplete user-space implementa‐
160 tion (CLOCK_REALTIME timers only) using POSIX threads, and before glibc
161 2.17, the implementation falls back to this technique on systems run‐
162 ning kernels older than Linux 2.6.
163
165 A program may create multiple interval timers using timer_create().
166 Timers are not inherited by the child of a fork(2), and are disarmed
168 and deleted during an execve(2).
169 The kernel preallocates a "queued real-time signal" for each timer cre‐
171 ated using timer_create(). Consequently, the number of timers is lim‐
172 ited by the RLIMIT_SIGPENDING resource limit (see setrlimit(2)).
173 The timers created by timer_create() are commonly known as "POSIX (in‐
175 terval) timers". The POSIX timers API consists of the following inter‐
176 faces:
177 timer_create()
179 Create a timer.
180 timer_settime(2)
182 Arm (start) or disarm (stop) a timer.
183 timer_gettime(2)
185 Fetch the time remaining until the next expiration of a timer,
186 along with the interval setting of the timer.
187 timer_getoverrun(2)
189 Return the overrun count for the last timer expiration.
190 timer_delete(2)
192 Disarm and delete a timer.
193 Since Linux 3.10, the /proc/pid/timers file can be used to list the
195 POSIX timers for the process with PID pid. See proc(5) for further in‐
196 formation.
197 Since Linux 4.10, support for POSIX timers is a configurable option
199 that is enabled by default. Kernel support can be disabled via the
200 CONFIG_POSIX_TIMERS option.
201
203 The program below takes two arguments: a sleep period in seconds, and a
204 timer frequency in nanoseconds. The program establishes a handler for
205 the signal it uses for the timer, blocks that signal, creates and arms
206 a timer that expires with the given frequency, sleeps for the specified
207 number of seconds, and then unblocks the timer signal. Assuming that
208 the timer expired at least once while the program slept, the signal
209 handler will be invoked, and the handler displays some information
210 about the timer notification. The program terminates after one invoca‐
211 tion of the signal handler.
212 In the following example run, the program sleeps for 1 second, after
214 creating a timer that has a frequency of 100 nanoseconds. By the time
215 the signal is unblocked and delivered, there have been around ten mil‐
216 lion overruns.
217 $ ./a.out 1 100
219 Establishing handler for signal 34
220 Blocking signal 34
221 timer ID is 0x804c008
222 Sleeping for 1 seconds
223 Unblocking signal 34
224 Caught signal 34
225 sival_ptr = 0xbfb174f4; *sival_ptr = 0x804c008
226 overrun count = 10004886
227 Program source
229 #include <signal.h>
231 #include <stdint.h>
232 #include <stdio.h>
233 #include <stdlib.h>
234 #include <time.h>
235 #include <unistd.h>
236 #define CLOCKID CLOCK_REALTIME
238 #define SIG SIGRTMIN
239 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
241 } while (0)
242 static void
244 print_siginfo(siginfo_t *si)
245 {
246 int or;
247 timer_t *tidp;
248 tidp = si->si_value.sival_ptr;
250 printf(" sival_ptr = %p; ", si->si_value.sival_ptr);
252 printf(" *sival_ptr = %#jx\n", (uintmax_t) *tidp);
253 or = timer_getoverrun(*tidp);
255 if (or == -1)
256 errExit("timer_getoverrun");
257 else
258 printf(" overrun count = %d\n", or);
259 }
260 static void
262 handler(int sig, siginfo_t *si, void *uc)
263 {
264 /* Note: calling printf() from a signal handler is not safe
265 (and should not be done in production programs), since
266 printf() is not async-signal-safe; see signal-safety(7).
267 Nevertheless, we use printf() here as a simple way of
268 showing that the handler was called. */
269 printf("Caught signal %d\n", sig);
271 print_siginfo(si);
272 signal(sig, SIG_IGN);
273 }
274 int
276 main(int argc, char *argv[])
277 {
278 timer_t timerid;
279 sigset_t mask;
280 long long freq_nanosecs;
281 struct sigevent sev;
282 struct sigaction sa;
283 struct itimerspec its;
284 if (argc != 3) {
286 fprintf(stderr, "Usage: %s <sleep-secs> <freq-nanosecs>\n",
287 argv[0]);
288 exit(EXIT_FAILURE);
289 }
290 /* Establish handler for timer signal. */
292 printf("Establishing handler for signal %d\n", SIG);
294 sa.sa_flags = SA_SIGINFO;
295 sa.sa_sigaction = handler;
296 sigemptyset(&sa.sa_mask);
297 if (sigaction(SIG, &sa, NULL) == -1)
298 errExit("sigaction");
299 /* Block timer signal temporarily. */
301 printf("Blocking signal %d\n", SIG);
303 sigemptyset(&mask);
304 sigaddset(&mask, SIG);
305 if (sigprocmask(SIG_SETMASK, &mask, NULL) == -1)
306 errExit("sigprocmask");
307 /* Create the timer. */
309 sev.sigev_notify = SIGEV_SIGNAL;
311 sev.sigev_signo = SIG;
312 sev.sigev_value.sival_ptr = &timerid;
313 if (timer_create(CLOCKID, &sev, &timerid) == -1)
314 errExit("timer_create");
315 printf("timer ID is %#jx\n", (uintmax_t) timerid);
317 /* Start the timer. */
319 freq_nanosecs = atoll(argv[2]);
321 its.it_value.tv_sec = freq_nanosecs / 1000000000;
322 its.it_value.tv_nsec = freq_nanosecs % 1000000000;
323 its.it_interval.tv_sec = its.it_value.tv_sec;
324 its.it_interval.tv_nsec = its.it_value.tv_nsec;
325 if (timer_settime(timerid, 0, &its, NULL) == -1)
327 errExit("timer_settime");
328 /* Sleep for a while; meanwhile, the timer may expire
330 multiple times. */
331 printf("Sleeping for %d seconds\n", atoi(argv[1]));
333 sleep(atoi(argv[1]));
334 /* Unlock the timer signal, so that timer notification
336 can be delivered. */
337 printf("Unblocking signal %d\n", SIG);
339 if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == -1)
340 errExit("sigprocmask");
341 exit(EXIT_SUCCESS);
343 }
344
346 clock_gettime(2), setitimer(2), timer_delete(2), timer_getoverrun(2),
347 timer_settime(2), timerfd_create(2), clock_getcpuclockid(3),
348 pthread_getcpuclockid(3), pthreads(7), sigevent(7), signal(7), time(7)
349Linux man-pages 6.04 2023-03-30 timer_create(2)