| 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) |