Debian Codegraph @

upstream/debian-unstable/man2/timer_create.2

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