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