1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
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.
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.
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
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
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()?
29 .TH TIMER_CREATE 2 2010-09-27 Linux "Linux Programmer's Manual"
31 timer_create \- create a POSIX per-process timer
34 .B #include <signal.h>
37 .BI "int timer_create(clockid_t " clockid ", struct sigevent *" sevp ,
38 .BI " timer_t *" timerid );
41 Link with \fI\-lrt\fP.
44 Feature Test Macro Requirements for glibc (see
45 .BR feature_test_macros (7)):
49 _POSIX_C_SOURCE\ >=\ 199309L
52 creates a new per-process interval timer.
53 The ID of the new timer is returned in the buffer pointed to by
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.
61 argument specifies the clock that the new timer uses to measure time.
62 It can be specified as one of the following values:
65 A settable system-wide real-time clock.
68 A nonsettable monotonically increasing clock that measures time
69 from some unspecified point in the past that does not change
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
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.
78 .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
79 A clock that measures (user and system) CPU time consumed by
81 .\" The CLOCK_MONOTONIC_RAW that was added in 2.6.28 can't be used
82 .\" to create a timer -- mtk, Feb 2009
84 As well as the above values,
86 can be specified as the
89 .BR clock_getcpuclockid (3)
91 .BR pthread_getcpuclockid (3).
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
104 field can have the following values:
107 Don't asynchronously notify when the timer expires.
108 Progress of the timer can be monitored using
109 .BR timer_gettime (2).
112 Upon timer expiration, generate the signal
122 structure will be set to
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)
130 Upon timer expiration, invoke
131 .I sigev_notify_function
132 as if it were the start function of a new thread.
137 .BR SIGEV_THREAD_ID " (Linux-specific)"
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.
144 .IR sigev_notify_thread_id
145 field specifies a kernel thread ID, that is, the value returned by
149 This flag is only intended for use by threading libraries.
153 as NULL is equivalent to specifying a pointer to a
163 .I sigev_value.sival_int
168 returns 0, and the ID of the new timer is placed in
170 On failure, \-1 is returned, and
172 is set to indicate the error.
176 Temporary error during kernel allocation of timer structures.
183 .IR sigev_notify_thread_id
187 .\" glibc layer: malloc()
188 Could not allocate memory.
190 This system call is available since Linux 2.6.
194 A program may create multiple interval timers using
197 Timers are not inherited by the child of a
199 and are disarmed and deleted during an
202 The kernel preallocates a "queued real-time signal"
203 for each timer created using
205 Consequently, the number of timers is limited by the
206 .BR RLIMIT_SIGPENDING
210 The timers created by
212 are commonly known as "POSIX (interval) timers".
213 The POSIX timers API consists of the following interfaces:
218 .BR timer_settime (2):
219 Arm (start) or disarm (stop) a timer.
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.
225 .BR timer_getoverrun (2):
226 Return the overrun count for the last timer expiration.
228 .BR timer_delete (2):
229 Disarm and delete a timer.
231 Part of the implementation of the POSIX timers API is provided by glibc.
234 The functionality for
236 is implemented within glibc, rather than the kernel.
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 user-space timer IDs to kernel timer IDs
242 .\" The kernel-level timer ID is exposed via siginfo.si_tid.
244 The POSIX timers system calls first appeared in Linux 2.6.
246 glibc provided an incomplete user-space implementation
248 timers only) using POSIX threads,
249 and current glibc falls back to this implementation on systems
250 running pre-2.6 Linux kernels.
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,
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.
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.
271 $ \fB./a.out 1 100\fP
272 Establishing handler for signal 34
274 timer ID is 0x804c008
275 Sleeping for 1 seconds
278 sival_ptr = 0xbfb174f4; *sival_ptr = 0x804c008
279 overrun count = 10004886
291 #define CLOCKID CLOCK_REALTIME
294 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
298 print_siginfo(siginfo_t *si)
303 tidp = si\->si_value.sival_ptr;
305 printf(" sival_ptr = %p; ", si\->si_value.sival_ptr);
306 printf(" *sival_ptr = 0x%lx\\n", (long) *tidp);
308 or = timer_getoverrun(*tidp);
310 errExit("timer_getoverrun");
312 printf(" overrun count = %d\\n", or);
316 handler(int sig, siginfo_t *si, void *uc)
318 /* Note: calling printf() from a signal handler is not
319 strictly correct, since printf() is not async\-signal\-safe;
322 printf("Caught signal %d\\n", sig);
324 signal(sig, SIG_IGN);
328 main(int argc, char *argv[])
332 struct itimerspec its;
333 long long freq_nanosecs;
338 fprintf(stderr, "Usage: %s <sleep\-secs> <freq\-nanosecs>\\n",
343 /* Establish handler for timer signal */
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");
352 /* Block timer signal temporarily */
354 printf("Blocking signal %d\\n", SIG);
356 sigaddset(&mask, SIG);
357 if (sigprocmask(SIG_SETMASK, &mask, NULL) == \-1)
358 errExit("sigprocmask");
360 /* Create the timer */
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");
368 printf("timer ID is 0x%lx\\n", (long) timerid);
370 /* Start the timer */
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;
378 if (timer_settime(timerid, 0, &its, NULL) == \-1)
379 errExit("timer_settime");
381 /* Sleep for a while; meanwhile, the timer may expire
384 printf("Sleeping for %d seconds\\n", atoi(argv[1]));
385 sleep(atoi(argv[1]));
387 /* Unlock the timer signal, so that timer notification
390 printf("Unblocking signal %d\\n", SIG);
391 if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == \-1)
392 errExit("sigprocmask");
400 .BR clock_gettime (2),
402 .BR timer_delete (2),
403 .BR timer_getoverrun (2),
404 .BR timer_settime (2),
405 .BR timerfd_create (2),
406 .BR clock_getcpuclockid (3),
407 .BR pthread_getcpuclockid (3),