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