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