Debian Codegraph @

upstream/debian-trixie/man2/timer_create.2

raw
1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
2 .\" <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH timer_create 2 2024-06-15 "Linux man-pages 6.9.1"
7 .SH NAME
8 timer_create \- create a POSIX per-process timer
9 .SH LIBRARY
10 Real-time library
11 .RI ( librt ", " \-lrt )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <signal.h>" " /* Definition of " SIGEV_* " constants */"
15 .B #include <time.h>
16 .P
17 .BI "int timer_create(clockid_t " clockid ,
18 .BI " struct sigevent *_Nullable restrict " sevp ,
19 .BI " timer_t *restrict " timerid );
20 .fi
21 .P
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 .BR timer_create ():
28 .nf
29 _POSIX_C_SOURCE >= 199309L
30 .fi
31 .SH DESCRIPTION
32 .BR timer_create ()
33 creates a new per-process interval timer.
34 The ID of the new timer is returned in the buffer pointed to by
35 .IR timerid ,
36 which must be a non-null pointer.
37 This ID is unique within the process, until the timer is deleted.
38 The new timer is initially disarmed.
39 .P
40 The
41 .I clockid
42 argument specifies the clock that the new timer uses to measure time.
43 It can be specified as one of the following values:
44 .TP
45 .B CLOCK_REALTIME
46 A settable system-wide real-time clock.
47 .TP
48 .B CLOCK_MONOTONIC
49 A nonsettable monotonically increasing clock that measures time
50 from some unspecified point in the past that does not change
51 after system startup.
52 .\" Note: the CLOCK_MONOTONIC_RAW clock added for clock_gettime()
53 .\" in Linux 2.6.28 is not supported for POSIX timers -- mtk, Feb 2009
54 .TP
55 .BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)"
56 A clock that measures (user and system) CPU time consumed by
57 (all of the threads in) the calling process.
58 .TP
59 .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
60 A clock that measures (user and system) CPU time consumed by
61 the calling thread.
62 .\" The CLOCK_MONOTONIC_RAW that was added in Linux 2.6.28 can't be used
63 .\" to create a timer -- mtk, Feb 2009
64 .TP
65 .BR CLOCK_BOOTTIME " (Since Linux 2.6.39)"
66 .\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0
67 Like
68 .BR CLOCK_MONOTONIC ,
69 this is a monotonically increasing clock.
70 However, whereas the
71 .B CLOCK_MONOTONIC
72 clock does not measure the time while a system is suspended, the
73 .B CLOCK_BOOTTIME
74 clock does include the time during which the system is suspended.
75 This is useful for applications that need to be suspend-aware.
76 .B CLOCK_REALTIME
77 is not suitable for such applications, since that clock is affected
78 by discontinuous changes to the system clock.
79 .TP
80 .BR CLOCK_REALTIME_ALARM " (since Linux 3.0)"
81 .\" commit 9a7adcf5c6dea63d2e47e6f6d2f7a6c9f48b9337
82 This clock is like
83 .BR CLOCK_REALTIME ,
84 but will wake the system if it is suspended.
85 The caller must have the
86 .B CAP_WAKE_ALARM
87 capability in order to set a timer against this clock.
88 .TP
89 .BR CLOCK_BOOTTIME_ALARM " (since Linux 3.0)"
90 .\" commit 9a7adcf5c6dea63d2e47e6f6d2f7a6c9f48b9337
91 This clock is like
92 .BR CLOCK_BOOTTIME ,
93 but will wake the system if it is suspended.
94 The caller must have the
95 .B CAP_WAKE_ALARM
96 capability in order to set a timer against this clock.
97 .TP
98 .BR CLOCK_TAI " (since Linux 3.10)"
99 A system-wide clock derived from wall-clock time but counting leap seconds.
100 .P
101 See
102 .BR clock_getres (2)
103 for some further details on the above clocks.
104 .P
105 As well as the above values,
106 .I clockid
107 can be specified as the
108 .I clockid
109 returned by a call to
110 .BR clock_getcpuclockid (3)
111 or
112 .BR pthread_getcpuclockid (3).
113 .P
114 The
115 .I sevp
116 argument points to a
117 .I sigevent
118 structure that specifies how the caller
119 should be notified when the timer expires.
120 For the definition and general details of this structure, see
121 .BR sigevent (3type).
122 .P
123 The
124 .I sevp.sigev_notify
125 field can have the following values:
126 .TP
127 .B SIGEV_NONE
128 Don't asynchronously notify when the timer expires.
129 Progress of the timer can be monitored using
130 .BR timer_gettime (2).
131 .TP
132 .B SIGEV_SIGNAL
133 Upon timer expiration, generate the signal
134 .I sigev_signo
135 for the process.
136 See
137 .BR sigevent (3type)
138 for general details.
139 The
140 .I si_code
141 field of the
142 .I siginfo_t
143 structure will be set to
144 .BR SI_TIMER .
145 At any point in time,
146 at most one signal is queued to the process for a given timer; see
147 .BR timer_getoverrun (2)
148 for more details.
149 .TP
150 .B SIGEV_THREAD
151 Upon timer expiration, invoke
152 .I sigev_notify_function
153 as if it were the start function of a new thread.
154 See
155 .BR sigevent (3type)
156 for details.
157 .TP
158 .BR SIGEV_THREAD_ID " (Linux-specific)"
159 As for
160 .BR SIGEV_SIGNAL ,
161 but the signal is targeted at the thread whose ID is given in
162 .IR sigev_notify_thread_id ,
163 which must be a thread in the same process as the caller.
164 The
165 .I sigev_notify_thread_id
166 field specifies a kernel thread ID, that is, the value returned by
167 .BR clone (2)
168 or
169 .BR gettid (2).
170 This flag is intended only for use by threading libraries.
171 .P
172 Specifying
173 .I sevp
174 as NULL is equivalent to specifying a pointer to a
175 .I sigevent
176 structure in which
177 .I sigev_notify
178 is
179 .BR SIGEV_SIGNAL ,
180 .I sigev_signo
181 is
182 .BR SIGALRM ,
183 and
184 .I sigev_value.sival_int
185 is the timer ID.
186 .SH RETURN VALUE
187 On success,
188 .BR timer_create ()
189 returns 0, and the ID of the new timer is placed in
190 .IR *timerid .
191 On failure, \-1 is returned, and
192 .I errno
193 is set to indicate the error.
194 .SH ERRORS
195 .TP
196 .B EAGAIN
197 Temporary error during kernel allocation of timer structures.
198 .TP
199 .B EINVAL
200 Clock ID,
201 .IR sigev_notify ,
202 .IR sigev_signo ,
203 or
204 .I sigev_notify_thread_id
205 is invalid.
206 .TP
207 .B ENOMEM
208 .\" glibc layer: malloc()
209 Could not allocate memory.
210 .TP
211 .B ENOTSUP
212 The kernel does not support creating a timer against this
213 .IR clockid .
214 .TP
215 .B EPERM
216 .I clockid
217 was
218 .B CLOCK_REALTIME_ALARM
219 or
220 .B CLOCK_BOOTTIME_ALARM
221 but the caller did not have the
222 .B CAP_WAKE_ALARM
223 capability.
224 .SH VERSIONS
225 .SS C library/kernel differences
226 Part of the implementation of the POSIX timers API is provided by glibc.
227 .\" See nptl/sysdeps/unix/sysv/linux/timer_create.c
228 In particular:
229 .IP \[bu] 3
230 Much of the functionality for
231 .B SIGEV_THREAD
232 is implemented within glibc, rather than the kernel.
233 (This is necessarily so,
234 since the thread involved in handling the notification is one
235 that must be managed by the C library POSIX threads implementation.)
236 Although the notification delivered to the process is via a thread,
237 internally the NPTL implementation uses a
238 .I sigev_notify
239 value of
240 .B SIGEV_THREAD_ID
241 along with a real-time signal that is reserved by the implementation (see
242 .BR nptl (7)).
243 .IP \[bu]
244 The implementation of the default case where
245 .I evp
246 is NULL is handled inside glibc,
247 which invokes the underlying system call with a suitably populated
248 .I sigevent
249 structure.
250 .IP \[bu]
251 The timer IDs presented at user level are maintained by glibc,
252 which maps these IDs to the timer IDs employed by the kernel.
253 .\" See the glibc source file kernel-posix-timers.h for the structure
254 .\" that glibc uses to map user-space timer IDs to kernel timer IDs
255 .\" The kernel-level timer ID is exposed via siginfo.si_tid.
256 .SH STANDARDS
257 POSIX.1-2008.
258 .SH HISTORY
259 Linux 2.6.
260 POSIX.1-2001.
261 .P
262 Prior to Linux 2.6,
263 glibc provided an incomplete user-space implementation
264 .RB ( CLOCK_REALTIME
265 timers only) using POSIX threads,
266 and before glibc 2.17,
267 .\" glibc commit 93a78ac437ba44f493333d7e2a4b0249839ce460
268 the implementation falls back to this technique on systems
269 running kernels older than Linux 2.6.
270 .SH NOTES
271 A program may create multiple interval timers using
272 .BR timer_create ().
273 .P
274 Timers are not inherited by the child of a
275 .BR fork (2),
276 and are disarmed and deleted during an
277 .BR execve (2).
278 .P
279 The kernel preallocates a "queued real-time signal"
280 for each timer created using
281 .BR timer_create ().
282 Consequently, the number of timers is limited by the
283 .B RLIMIT_SIGPENDING
284 resource limit (see
285 .BR setrlimit (2)).
286 .P
287 The timers created by
288 .BR timer_create ()
289 are commonly known as "POSIX (interval) timers".
290 The POSIX timers API consists of the following interfaces:
291 .TP
292 .BR timer_create ()
293 Create a timer.
294 .TP
295 .BR timer_settime (2)
296 Arm (start) or disarm (stop) a timer.
297 .TP
298 .BR timer_gettime (2)
299 Fetch the time remaining until the next expiration of a timer,
300 along with the interval setting of the timer.
301 .TP
302 .BR timer_getoverrun (2)
303 Return the overrun count for the last timer expiration.
304 .TP
305 .BR timer_delete (2)
306 Disarm and delete a timer.
307 .P
308 Since Linux 3.10, the
309 .IR /proc/ pid /timers
310 file can be used to list the POSIX timers for the process with PID
311 .IR pid .
312 See
313 .BR proc (5)
314 for further information.
315 .P
316 Since Linux 4.10,
317 .\" baa73d9e478ff32d62f3f9422822b59dd9a95a21
318 support for POSIX timers is a configurable option that is enabled by default.
319 Kernel support can be disabled via the
320 .B CONFIG_POSIX_TIMERS
321 option.
322 .SH EXAMPLES
323 The program below takes two arguments: a sleep period in seconds,
324 and a timer frequency in nanoseconds.
325 The program establishes a handler for the signal it uses for the timer,
326 blocks that signal,
327 creates and arms a timer that expires with the given frequency,
328 sleeps for the specified number of seconds,
329 and then unblocks the timer signal.
330 Assuming that the timer expired at least once while the program slept,
331 the signal handler will be invoked,
332 and the handler displays some information about the timer notification.
333 The program terminates after one invocation of the signal handler.
334 .P
335 In the following example run, the program sleeps for 1 second,
336 after creating a timer that has a frequency of 100 nanoseconds.
337 By the time the signal is unblocked and delivered,
338 there have been around ten million overruns.
339 .P
340 .in +4n
341 .EX
342 $ \fB./a.out 1 100\fP
343 Establishing handler for signal 34
344 Blocking signal 34
345 timer ID is 0x804c008
346 Sleeping for 1 seconds
347 Unblocking signal 34
348 Caught signal 34
349 sival_ptr = 0xbfb174f4; *sival_ptr = 0x804c008
350 overrun count = 10004886
351 .EE
352 .in
353 .SS Program source
354 \&
355 .\" SRC BEGIN (timer_create.c)
356 .EX
357 #include <signal.h>
358 #include <stdint.h>
359 #include <stdio.h>
360 #include <stdlib.h>
361 #include <time.h>
362 #include <unistd.h>
363 \&
364 #define CLOCKID CLOCK_REALTIME
365 #define SIG SIGRTMIN
366 \&
367 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \[rs]
368 } while (0)
369 \&
370 static void
371 print_siginfo(siginfo_t *si)
372 {
373 int or;
374 timer_t *tidp;
375 \&
376 tidp = si\->si_value.sival_ptr;
377 \&
378 printf(" sival_ptr = %p; ", si\->si_value.sival_ptr);
379 printf(" *sival_ptr = %#jx\[rs]n", (uintmax_t) *tidp);
380 \&
381 or = timer_getoverrun(*tidp);
382 if (or == \-1)
383 errExit("timer_getoverrun");
384 else
385 printf(" overrun count = %d\[rs]n", or);
386 }
387 \&
388 static void
389 handler(int sig, siginfo_t *si, void *uc)
390 {
391 /* Note: calling printf() from a signal handler is not safe
392 (and should not be done in production programs), since
393 printf() is not async\-signal\-safe; see signal\-safety(7).
394 Nevertheless, we use printf() here as a simple way of
395 showing that the handler was called. */
396 \&
397 printf("Caught signal %d\[rs]n", sig);
398 print_siginfo(si);
399 signal(sig, SIG_IGN);
400 }
401 \&
402 int
403 main(int argc, char *argv[])
404 {
405 timer_t timerid;
406 sigset_t mask;
407 long long freq_nanosecs;
408 struct sigevent sev;
409 struct sigaction sa;
410 struct itimerspec its;
411 \&
412 if (argc != 3) {
413 fprintf(stderr, "Usage: %s <sleep\-secs> <freq\-nanosecs>\[rs]n",
414 argv[0]);
415 exit(EXIT_FAILURE);
416 }
417 \&
418 /* Establish handler for timer signal. */
419 \&
420 printf("Establishing handler for signal %d\[rs]n", SIG);
421 sa.sa_flags = SA_SIGINFO;
422 sa.sa_sigaction = handler;
423 sigemptyset(&sa.sa_mask);
424 if (sigaction(SIG, &sa, NULL) == \-1)
425 errExit("sigaction");
426 \&
427 /* Block timer signal temporarily. */
428 \&
429 printf("Blocking signal %d\[rs]n", SIG);
430 sigemptyset(&mask);
431 sigaddset(&mask, SIG);
432 if (sigprocmask(SIG_SETMASK, &mask, NULL) == \-1)
433 errExit("sigprocmask");
434 \&
435 /* Create the timer. */
436 \&
437 sev.sigev_notify = SIGEV_SIGNAL;
438 sev.sigev_signo = SIG;
439 sev.sigev_value.sival_ptr = &timerid;
440 if (timer_create(CLOCKID, &sev, &timerid) == \-1)
441 errExit("timer_create");
442 \&
443 printf("timer ID is %#jx\[rs]n", (uintmax_t) timerid);
444 \&
445 /* Start the timer. */
446 \&
447 freq_nanosecs = atoll(argv[2]);
448 its.it_value.tv_sec = freq_nanosecs / 1000000000;
449 its.it_value.tv_nsec = freq_nanosecs % 1000000000;
450 its.it_interval.tv_sec = its.it_value.tv_sec;
451 its.it_interval.tv_nsec = its.it_value.tv_nsec;
452 \&
453 if (timer_settime(timerid, 0, &its, NULL) == \-1)
454 errExit("timer_settime");
455 \&
456 /* Sleep for a while; meanwhile, the timer may expire
457 multiple times. */
458 \&
459 printf("Sleeping for %d seconds\[rs]n", atoi(argv[1]));
460 sleep(atoi(argv[1]));
461 \&
462 /* Unlock the timer signal, so that timer notification
463 can be delivered. */
464 \&
465 printf("Unblocking signal %d\[rs]n", SIG);
466 if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == \-1)
467 errExit("sigprocmask");
468 \&
469 exit(EXIT_SUCCESS);
470 }
471 .EE
472 .\" SRC END
473 .SH SEE ALSO
474 .ad l
475 .nh
476 .BR clock_gettime (2),
477 .BR setitimer (2),
478 .BR timer_delete (2),
479 .BR timer_getoverrun (2),
480 .BR timer_settime (2),
481 .BR timerfd_create (2),
482 .BR clock_getcpuclockid (3),
483 .BR pthread_getcpuclockid (3),
484 .BR pthreads (7),
485 .BR sigevent (3type),
486 .BR signal (7),
487 .BR time (7)