man2/timer_create.2

   1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH TIMER_CREATE 2 2021-03-22 Linux "Linux Programmer's Manual"
   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 .PP
  17 .BI "int timer_create(clockid_t " clockid ", struct sigevent *restrict " sevp ,
  18 .BI "                 timer_t *restrict " timerid );
  19 .fi
  20 .PP
  21 .RS -4
  22 Feature Test Macro Requirements for glibc (see
  23 .BR feature_test_macros (7)):
  24 .RE
  25 .PP
  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 .PP
  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 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 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 .BR CLOCK_MONOTONIC
  71 clock does not measure the time while a system is suspended, the
  72 .BR 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 .BR 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 ignoring leap seconds.
  99 .PP
 100 See
 101 .BR clock_getres (2)
 102 for some further details on the above clocks.
 103 .PP
 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 .PP
 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 (7).
 121 .PP
 122 The
 123 .I sevp.sigev_notify
 124 field can have the following values:
 125 .TP
 126 .BR 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 .BR SIGEV_SIGNAL
 132 Upon timer expiration, generate the signal
 133 .I sigev_signo
 134 for the process.
 135 See
 136 .BR sigevent (7)
 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 for a given timer; see
 146 .BR timer_getoverrun (2)
 147 for more details.
 148 .TP
 149 .BR SIGEV_THREAD
 150 Upon timer expiration, invoke
 151 .I sigev_notify_function
 152 as if it were the start function of a new thread.
 153 See
 154 .BR sigevent (7)
 155 for details.
 156 .TP
 157 .BR SIGEV_THREAD_ID " (Linux-specific)"
 158 As for
 159 .BR SIGEV_SIGNAL ,
 160 but the signal is targeted at the thread whose ID is given in
 161 .IR sigev_notify_thread_id ,
 162 which must be a thread in the same process as the caller.
 163 The
 164 .IR sigev_notify_thread_id
 165 field specifies a kernel thread ID, that is, the value returned by
 166 .BR clone (2)
 167 or
 168 .BR gettid (2).
 169 This flag is intended only for use by threading libraries.
 170 .PP
 171 Specifying
 172 .I sevp
 173 as NULL is equivalent to specifying a pointer to a
 174 .I sigevent
 175 structure in which
 176 .I sigev_notify
 177 is
 178 .BR SIGEV_SIGNAL ,
 179 .I sigev_signo
 180 is
 181 .BR SIGALRM ,
 182 and
 183 .I sigev_value.sival_int
 184 is the timer ID.
 185 .SH RETURN VALUE
 186 On success,
 187 .BR timer_create ()
 188 returns 0, and the ID of the new timer is placed in
 189 .IR *timerid .
 190 On failure, \-1 is returned, and
 191 .I errno
 192 is set to indicate the error.
 193 .SH ERRORS
 194 .TP
 195 .B EAGAIN
 196 Temporary error during kernel allocation of timer structures.
 197 .TP
 198 .B EINVAL
 199 Clock ID,
 200 .IR sigev_notify ,
 201 .IR sigev_signo ,
 202 or
 203 .IR sigev_notify_thread_id
 204 is invalid.
 205 .TP
 206 .B ENOMEM
 207 .\" glibc layer: malloc()
 208 Could not allocate memory.
 209 .TP
 210 .B ENOTSUP
 211 The kernel does not support creating a timer against this
 212 .IR clockid .
 213 .TP
 214 .B EPERM
 215 .I clockid
 216 was
 217 .BR CLOCK_REALTIME_ALARM
 218 or
 219 .BR CLOCK_BOOTTIME_ALARM
 220 but the caller did not have the
 221 .BR CAP_WAKE_ALARM
 222 capability.
 223 .SH VERSIONS
 224 This system call is available since Linux 2.6.
 225 .SH CONFORMING TO
 226 POSIX.1-2001, POSIX.1-2008.
 227 .SH NOTES
 228 A program may create multiple interval timers using
 229 .BR timer_create ().
 230 .PP
 231 Timers are not inherited by the child of a
 232 .BR fork (2),
 233 and are disarmed and deleted during an
 234 .BR execve (2).
 235 .PP
 236 The kernel preallocates a "queued real-time signal"
 237 for each timer created using
 238 .BR timer_create ().
 239 Consequently, the number of timers is limited by the
 240 .BR RLIMIT_SIGPENDING
 241 resource limit (see
 242 .BR setrlimit (2)).
 243 .PP
 244 The timers created by
 245 .BR timer_create ()
 246 are commonly known as "POSIX (interval) timers".
 247 The POSIX timers API consists of the following interfaces:
 248 .IP * 3
 249 .BR timer_create ():
 250 Create a timer.
 251 .IP *
 252 .BR timer_settime (2):
 253 Arm (start) or disarm (stop) a timer.
 254 .IP *
 255 .BR timer_gettime (2):
 256 Fetch the time remaining until the next expiration of a timer,
 257 along with the interval setting of the timer.
 258 .IP *
 259 .BR timer_getoverrun (2):
 260 Return the overrun count for the last timer expiration.
 261 .IP *
 262 .BR timer_delete (2):
 263 Disarm and delete a timer.
 264 .PP
 265 Since Linux 3.10, the
 266 .IR /proc/[pid]/timers
 267 file can be used to list the POSIX timers for the process with PID
 268 .IR pid .
 269 See
 270 .BR proc (5)
 271 for further information.
 272 .PP
 273 Since Linux 4.10,
 274 .\" baa73d9e478ff32d62f3f9422822b59dd9a95a21
 275 support for POSIX timers is a configurable option that is enabled by default.
 276 Kernel support can be disabled via the
 277 .BR CONFIG_POSIX_TIMERS
 278 option.
 279 .\"
 280 .SS C library/kernel differences
 281 Part of the implementation of the POSIX timers API is provided by glibc.
 282 .\" See nptl/sysdeps/unix/sysv/linux/timer_create.c
 283 In particular:
 284 .IP * 3
 285 Much of the functionality for
 286 .BR SIGEV_THREAD
 287 is implemented within glibc, rather than the kernel.
 288 (This is necessarily so,
 289 since the thread involved in handling the notification is one
 290 that must be managed by the C library POSIX threads implementation.)
 291 Although the notification delivered to the process is via a thread,
 292 internally the NPTL implementation uses a
 293 .I sigev_notify
 294 value of
 295 .BR SIGEV_THREAD_ID
 296 along with a real-time signal that is reserved by the implementation (see
 297 .BR nptl (7)).
 298 .IP *
 299 The implementation of the default case where
 300 .I evp
 301 is NULL is handled inside glibc,
 302 which invokes the underlying system call with a suitably populated
 303 .I sigevent
 304 structure.
 305 .IP *
 306 The timer IDs presented at user level are maintained by glibc,
 307 which maps these IDs to the timer IDs employed by the kernel.
 308 .\" See the glibc source file kernel-posix-timers.h for the structure
 309 .\" that glibc uses to map user-space timer IDs to kernel timer IDs
 310 .\" The kernel-level timer ID is exposed via siginfo.si_tid.
 311 .PP
 312 The POSIX timers system calls first appeared in Linux 2.6.
 313 Prior to this,
 314 glibc provided an incomplete user-space implementation
 315 .RB ( CLOCK_REALTIME
 316 timers only) using POSIX threads,
 317 and in glibc versions before 2.17,
 318 .\" glibc commit 93a78ac437ba44f493333d7e2a4b0249839ce460
 319 the implementation falls back to this technique on systems
 320 running pre-2.6 Linux kernels.
 321 .SH EXAMPLES
 322 The program below takes two arguments: a sleep period in seconds,
 323 and a timer frequency in nanoseconds.
 324 The program establishes a handler for the signal it uses for the timer,
 325 blocks that signal,
 326 creates and arms a timer that expires with the given frequency,
 327 sleeps for the specified number of seconds,
 328 and then unblocks the timer signal.
 329 Assuming that the timer expired at least once while the program slept,
 330 the signal handler will be invoked,
 331 and the handler displays some information about the timer notification.
 332 The program terminates after one invocation of the signal handler.
 333 .PP
 334 In the following example run, the program sleeps for 1 second,
 335 after creating a timer that has a frequency of 100 nanoseconds.
 336 By the time the signal is unblocked and delivered,
 337 there have been around ten million overruns.
 338 .PP
 339 .in +4n
 340 .EX
 341 $ \fB./a.out 1 100\fP
 342 Establishing handler for signal 34
 343 Blocking signal 34
 344 timer ID is 0x804c008
 345 Sleeping for 1 seconds
 346 Unblocking signal 34
 347 Caught signal 34
 348     sival_ptr = 0xbfb174f4;     *sival_ptr = 0x804c008
 349     overrun count = 10004886
 350 .EE
 351 .in
 352 .SS Program source
 353 \&
 354 .EX
 355 #include <stdint.h>
 356 #include <stdlib.h>
 357 #include <unistd.h>
 358 #include <stdio.h>
 359 #include <signal.h>
 360 #include <time.h>
 361
 362 #define CLOCKID CLOCK_REALTIME
 363 #define SIG SIGRTMIN
 364
 365 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 366                         } while (0)
 367
 368 static void
 369 print_siginfo(siginfo_t *si)
 370 {
 371     timer_t *tidp;
 372     int or;
 373
 374     tidp = si\->si_value.sival_ptr;
 375
 376     printf("    sival_ptr = %p; ", si\->si_value.sival_ptr);
 377     printf("    *sival_ptr = %#jx\en", (uintmax_t) *tidp);
 378
 379     or = timer_getoverrun(*tidp);
 380     if (or == \-1)
 381         errExit("timer_getoverrun");
 382     else
 383         printf("    overrun count = %d\en", or);
 384 }
 385
 386 static void
 387 handler(int sig, siginfo_t *si, void *uc)
 388 {
 389     /* Note: calling printf() from a signal handler is not safe
 390        (and should not be done in production programs), since
 391        printf() is not async\-signal\-safe; see signal\-safety(7).
 392        Nevertheless, we use printf() here as a simple way of
 393        showing that the handler was called. */
 394
 395     printf("Caught signal %d\en", sig);
 396     print_siginfo(si);
 397     signal(sig, SIG_IGN);
 398 }
 399
 400 int
 401 main(int argc, char *argv[])
 402 {
 403     timer_t timerid;
 404     struct sigevent sev;
 405     struct itimerspec its;
 406     long long freq_nanosecs;
 407     sigset_t mask;
 408     struct sigaction sa;
 409
 410     if (argc != 3) {
 411         fprintf(stderr, "Usage: %s <sleep\-secs> <freq\-nanosecs>\en",
 412                 argv[0]);
 413         exit(EXIT_FAILURE);
 414     }
 415
 416     /* Establish handler for timer signal. */
 417
 418     printf("Establishing handler for signal %d\en", SIG);
 419     sa.sa_flags = SA_SIGINFO;
 420     sa.sa_sigaction = handler;
 421     sigemptyset(&sa.sa_mask);
 422     if (sigaction(SIG, &sa, NULL) == \-1)
 423         errExit("sigaction");
 424
 425     /* Block timer signal temporarily. */
 426
 427     printf("Blocking signal %d\en", SIG);
 428     sigemptyset(&mask);
 429     sigaddset(&mask, SIG);
 430     if (sigprocmask(SIG_SETMASK, &mask, NULL) == \-1)
 431         errExit("sigprocmask");
 432
 433     /* Create the timer. */
 434
 435     sev.sigev_notify = SIGEV_SIGNAL;
 436     sev.sigev_signo = SIG;
 437     sev.sigev_value.sival_ptr = &timerid;
 438     if (timer_create(CLOCKID, &sev, &timerid) == \-1)
 439         errExit("timer_create");
 440
 441     printf("timer ID is %#jx\en", (uintmax_t) timerid);
 442
 443     /* Start the timer. */
 444
 445     freq_nanosecs = atoll(argv[2]);
 446     its.it_value.tv_sec = freq_nanosecs / 1000000000;
 447     its.it_value.tv_nsec = freq_nanosecs % 1000000000;
 448     its.it_interval.tv_sec = its.it_value.tv_sec;
 449     its.it_interval.tv_nsec = its.it_value.tv_nsec;
 450
 451     if (timer_settime(timerid, 0, &its, NULL) == \-1)
 452          errExit("timer_settime");
 453
 454     /* Sleep for a while; meanwhile, the timer may expire
 455        multiple times. */
 456
 457     printf("Sleeping for %d seconds\en", atoi(argv[1]));
 458     sleep(atoi(argv[1]));
 459
 460     /* Unlock the timer signal, so that timer notification
 461        can be delivered. */
 462
 463     printf("Unblocking signal %d\en", SIG);
 464     if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == \-1)
 465         errExit("sigprocmask");
 466
 467     exit(EXIT_SUCCESS);
 468 }
 469 .EE
 470 .SH SEE ALSO
 471 .ad l
 472 .nh
 473 .BR clock_gettime (2),
 474 .BR setitimer (2),
 475 .BR timer_delete (2),
 476 .BR timer_getoverrun (2),
 477 .BR timer_settime (2),
 478 .BR timerfd_create (2),
 479 .BR clock_getcpuclockid (3),
 480 .BR pthread_getcpuclockid (3),
 481 .BR pthreads (7),
 482 .BR sigevent (7),
 483 .BR signal (7),
 484 .BR time (7)