original/man2/timer_create.2

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