draft/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 .\"*******************************************************************
  30 .\"
  31 .\" This file was generated with po4a. Translate the source file.
  32 .\"
  33 .\"*******************************************************************
  34 .TH TIMER_CREATE 2 2010\-09\-27 Linux "Linux Programmer's Manual"
  35 .SH 名前
  36 timer_create \- create a POSIX per\-process timer
  37 .SH 書式
  38 .nf
  39 \fB#include <signal.h>\fP
  40 \fB#include <time.h>\fP
  41
  42 \fBint timer_create(clockid_t \fP\fIclockid\fP\fB, struct sigevent *\fP\fIsevp\fP\fB,\fP
  43 \fB                 timer_t *\fP\fItimerid\fP\fB);\fP
  44 .fi
  45
  46 Link with \fI\-lrt\fP.
  47 .sp
  48 .in -4n
  49 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  50 .in
  51 .sp
  52 \fBtimer_create\fP(): _POSIX_C_SOURCE\ >=\ 199309L
  53 .SH 説明
  54 \fBtimer_create\fP()  creates a new per\-process interval timer.  The ID of the
  55 new timer is returned in the buffer pointed to by \fItimerid\fP, which must be
  56 a non\-NULL pointer.  This ID is unique within the process, until the timer
  57 is deleted.  The new timer is initially disarmed.
  58
  59 The \fIclockid\fP argument specifies the clock that the new timer uses to
  60 measure time.  It can be specified as one of the following values:
  61 .TP
  62 \fBCLOCK_REALTIME\fP
  63 A settable system\-wide real\-time clock.
  64 .TP
  65 \fBCLOCK_MONOTONIC\fP
  66 .\" Note: the CLOCK_MONOTONIC_RAW clock added for clock_gettime()
  67 .\" in 2.6.28 is not supported for POSIX timers -- mtk, Feb 2009
  68 A nonsettable monotonically increasing clock that measures time from some
  69 unspecified point in the past that does not change after system startup.
  70 .TP
  71 \fBCLOCK_PROCESS_CPUTIME_ID\fP (since Linux 2.6.12)
  72 A clock that measures (user and system) CPU time consumed by (all of the
  73 threads in) the calling process.
  74 .TP
  75 \fBCLOCK_THREAD_CPUTIME_ID\fP (since Linux 2.6.12)
  76 .\" The CLOCK_MONOTONIC_RAW that was added in 2.6.28 can't be used
  77 .\" to create a timer -- mtk, Feb 2009
  78 A clock that measures (user and system) CPU time consumed by the calling
  79 thread.
  80 .PP
  81 As well as the above values, \fIclockid\fP can be specified as the \fIclockid\fP
  82 returned by a call to \fBclock_getcpuclockid\fP(3)  or
  83 \fBpthread_getcpuclockid\fP(3).
  84
  85 The \fIsevp\fP argument points to a \fIsigevent\fP structure that specifies how
  86 the caller should be notified when the timer expires.  For the definition
  87 and general details of this structure, see \fBsigevent\fP(7).
  88
  89 The \fIsevp.sigev_notify\fP field can have the following values:
  90 .TP
  91 \fBSIGEV_NONE\fP
  92 Don't asynchronously notify when the timer expires.  Progress of the timer
  93 can be monitored using \fBtimer_gettime\fP(2).
  94 .TP
  95 \fBSIGEV_SIGNAL\fP
  96 Upon timer expiration, generate the signal \fIsigev_signo\fP for the process.
  97 See \fBsigevent\fP(7)  for general details.  The \fIsi_code\fP field of the
  98 \fIsiginfo_t\fP structure will be set to \fBSI_TIMER\fP.  At any point in time, at
  99 most one signal is queued to the process for a given timer; see
 100 \fBtimer_getoverrun\fP(2)  for more details.
 101 .TP
 102 \fBSIGEV_THREAD\fP
 103 Upon timer expiration, invoke \fIsigev_notify_function\fP as if it were the
 104 start function of a new thread.  See \fBsigevent\fP(7)  for details.
 105 .TP
 106 \fBSIGEV_THREAD_ID\fP (Linux\-specific)
 107 As for \fBSIGEV_SIGNAL\fP, but the signal is targeted at the thread whose ID is
 108 given in \fIsigev_notify_thread_id\fP, which must be a thread in the same
 109 process as the caller.  The \fIsigev_notify_thread_id\fP field specifies a
 110 kernel thread ID, that is, the value returned by \fBclone\fP(2)  or
 111 \fBgettid\fP(2).  This flag is only intended for use by threading libraries.
 112 .PP
 113 Specifying \fIsevp\fP as NULL is equivalent to specifying a pointer to a
 114 \fIsigevent\fP structure in which \fIsigev_notify\fP is \fBSIGEV_SIGNAL\fP,
 115 \fIsigev_signo\fP is \fBSIGALRM\fP, and \fIsigev_value.sival_int\fP is the timer ID.
 116 .SH 返り値
 117 On success, \fBtimer_create\fP()  returns 0, and the ID of the new timer is
 118 placed in \fI*timerid\fP.  On failure, \-1 is returned, and \fIerrno\fP is set to
 119 indicate the error.
 120 .SH エラー
 121 .TP
 122 \fBEAGAIN\fP
 123 Temporary error during kernel allocation of timer structures.
 124 .TP
 125 \fBEINVAL\fP
 126 Clock ID, \fIsigev_notify\fP, \fIsigev_signo\fP, or \fIsigev_notify_thread_id\fP is
 127 invalid.
 128 .TP
 129 \fBENOMEM\fP
 130 .\" glibc layer: malloc()
 131 Could not allocate memory.
 132 .SH バージョン
 133 This system call is available since Linux 2.6.
 134 .SH 準拠
 135 POSIX.1\-2001.
 136 .SH 注意
 137 A program may create multiple interval timers using \fBtimer_create\fP().
 138
 139 Timers are not inherited by the child of a \fBfork\fP(2), and are disarmed and
 140 deleted during an \fBexecve\fP(2).
 141
 142 The kernel preallocates a "queued real\-time signal" for each timer created
 143 using \fBtimer_create\fP().  Consequently, the number of timers is limited by
 144 the \fBRLIMIT_SIGPENDING\fP resource limit (see \fBsetrlimit\fP(2)).
 145
 146 The timers created by \fBtimer_create\fP()  are commonly known as "POSIX
 147 (interval) timers".  The POSIX timers API consists of the following
 148 interfaces:
 149 .IP * 3
 150 \fBtimer_create\fP(): Create a timer.
 151 .IP *
 152 \fBtimer_settime\fP(2): Arm (start) or disarm (stop) a timer.
 153 .IP *
 154 \fBtimer_gettime\fP(2): Fetch the time remaining until the next expiration of a
 155 timer, along with the interval setting of the timer.
 156 .IP *
 157 \fBtimer_getoverrun\fP(2): Return the overrun count for the last timer
 158 expiration.
 159 .IP *
 160 \fBtimer_delete\fP(2): Disarm and delete a timer.
 161 .PP
 162 Part of the implementation of the POSIX timers API is provided by glibc.  In
 163 particular:
 164 .IP * 3
 165 The functionality for \fBSIGEV_THREAD\fP is implemented within glibc, rather
 166 than the kernel.
 167 .IP *
 168 .\" See the glibc source file kernel-posix-timers.h for the structure
 169 .\" that glibc uses to map userspace timer IDs to kernel timer IDs
 170 .\" The kernel-level timer ID is exposed via siginfo.si_tid.
 171 The timer IDs presented at user level are maintained by glibc, which maps
 172 these IDs to the timer IDs employed by the kernel.
 173 .PP
 174 The POSIX timers system calls first appeared in Linux 2.6.  Prior to this,
 175 glibc provided an incomplete userspace implementation (\fBCLOCK_REALTIME\fP
 176 timers only) using POSIX threads, and current glibc falls back to this
 177 implementation on systems running pre\-2.6 Linux kernels.
 178 .SH 例
 179 The program below takes two arguments: a sleep period in seconds, and a
 180 timer frequency in nanoseconds.  The program establishes a handler for the
 181 signal it uses for the timer, blocks that signal, creates and arms a timer
 182 that expires with the given frequency, sleeps for the specified number of
 183 seconds, and then unblocks the timer signal.  Assuming that the timer
 184 expired at least once while the program slept, the signal handler will be
 185 invoked, and the handler displays some information about the timer
 186 notification.  The program terminates after one invocation of the signal
 187 handler.
 188
 189 In the following example run, the program sleeps for 1 second, after
 190 creating a timer that has a frequency of 100 nanoseconds.  By the time the
 191 signal is unblocked and delivered, there have been around ten million
 192 overruns.
 193 .in +4n
 194 .nf
 195
 196 $ \fB./a.out 1 100\fP
 197 Establishing handler for signal 34
 198 Blocking signal 34
 199 timer ID is 0x804c008
 200 Sleeping for 1 seconds
 201 Unblocking signal 34
 202 Caught signal 34
 203     sival_ptr = 0xbfb174f4;     *sival_ptr = 0x804c008
 204     overrun count = 10004886
 205 .fi
 206 .in
 207 .SS "Program Source"
 208 \&
 209 .nf
 210 #include <stdlib.h>
 211 #include <unistd.h>
 212 #include <stdio.h>
 213 #include <signal.h>
 214 #include <time.h>
 215
 216 #define CLOCKID CLOCK_REALTIME
 217 #define SIG SIGRTMIN
 218
 219 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 220                         } while (0)
 221
 222 static void
 223 print_siginfo(siginfo_t *si)
 224 {
 225     timer_t *tidp;
 226     int or;
 227
 228     tidp = si\->si_value.sival_ptr;
 229
 230     printf("    sival_ptr = %p; ", si\->si_value.sival_ptr);
 231     printf("    *sival_ptr = 0x%lx\en", (long) *tidp);
 232
 233     or = timer_getoverrun(*tidp);
 234     if (or == \-1)
 235         errExit("timer_getoverrun");
 236     else
 237         printf("    overrun count = %d\en", or);
 238 }
 239
 240 static void
 241 handler(int sig, siginfo_t *si, void *uc)
 242 {
 243     /* Note: calling printf() from a signal handler is not
 244        strictly correct, since printf() is not async\-signal\-safe;
 245        see signal(7) */
 246
 247     printf("Caught signal %d\en", sig);
 248     print_siginfo(si);
 249     signal(sig, SIG_IGN);
 250 }
 251
 252 int
 253 main(int argc, char *argv[])
 254 {
 255     timer_t timerid;
 256     struct sigevent sev;
 257     struct itimerspec its;
 258     long long freq_nanosecs;
 259     sigset_t mask;
 260     struct sigaction sa;
 261
 262     if (argc != 3) {
 263         fprintf(stderr, "Usage: %s <sleep\-secs> <freq\-nanosecs>\en",
 264                 argv[0]);
 265         exit(EXIT_FAILURE);
 266     }
 267
 268     /* Establish handler for timer signal */
 269
 270     printf("Establishing handler for signal %d\en", SIG);
 271     sa.sa_flags = SA_SIGINFO;
 272     sa.sa_sigaction = handler;
 273     sigemptyset(&sa.sa_mask);
 274     if (sigaction(SIG, &sa, NULL) == \-1)
 275         errExit("sigaction");
 276
 277     /* Block timer signal temporarily */
 278
 279     printf("Blocking signal %d\en", SIG);
 280     sigemptyset(&mask);
 281     sigaddset(&mask, SIG);
 282     if (sigprocmask(SIG_SETMASK, &mask, NULL) == \-1)
 283         errExit("sigprocmask");
 284
 285     /* Create the timer */
 286
 287     sev.sigev_notify = SIGEV_SIGNAL;
 288     sev.sigev_signo = SIG;
 289     sev.sigev_value.sival_ptr = &timerid;
 290     if (timer_create(CLOCKID, &sev, &timerid) == \-1)
 291         errExit("timer_create");
 292
 293     printf("timer ID is 0x%lx\en", (long) timerid);
 294
 295     /* Start the timer */
 296
 297     freq_nanosecs = atoll(argv[2]);
 298     its.it_value.tv_sec = freq_nanosecs / 1000000000;
 299     its.it_value.tv_nsec = freq_nanosecs % 1000000000;
 300     its.it_interval.tv_sec = its.it_value.tv_sec;
 301     its.it_interval.tv_nsec = its.it_value.tv_nsec;
 302
 303     if (timer_settime(timerid, 0, &its, NULL) == \-1)
 304          errExit("timer_settime");
 305
 306     /* Sleep for a while; meanwhile, the timer may expire
 307        multiple times */
 308
 309     printf("Sleeping for %d seconds\en", atoi(argv[1]));
 310     sleep(atoi(argv[1]));
 311
 312     /* Unlock the timer signal, so that timer notification
 313        can be delivered */
 314
 315     printf("Unblocking signal %d\en", SIG);
 316     if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == \-1)
 317         errExit("sigprocmask");
 318
 319     exit(EXIT_SUCCESS);
 320 }
 321 .fi
 322 .SH 関連項目
 323 \fBclock_gettime\fP(2), \fBsetitimer\fP(2), \fBtimer_delete\fP(2),
 324 \fBtimer_getoverrun\fP(2), \fBtimer_settime\fP(2), \fBtimerfd_create\fP(2),
 325 \fBclock_getcpuclockid\fP(3), \fBpthread_getcpuclockid\fP(3), \fBpthreads\fP(7),
 326 \fBsigevent\fP(7), \fBsignal\fP(7), \fBtime\fP(7)