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