man2/timer_create.2

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