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.
23 .TH TIMER_CREATE 2 2010-09-27 Linux "Linux Programmer's Manual"
25 timer_create \- create a POSIX per-process timer
28 .B #include <signal.h>
31 .BI "int timer_create(clockid_t " clockid ", struct sigevent *" sevp ,
32 .BI " timer_t *" timerid );
35 Link with \fI\-lrt\fP.
38 Feature Test Macro Requirements for glibc (see
39 .BR feature_test_macros (7)):
43 _POSIX_C_SOURCE\ >=\ 199309L
46 creates a new per-process interval timer.
47 The ID of the new timer is returned in the buffer pointed to by
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.
55 argument specifies the clock that the new timer uses to measure time.
56 It can be specified as one of the following values:
59 A settable system-wide real-time clock.
62 A nonsettable monotonically increasing clock that measures time
63 from some unspecified point in the past that does not change
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
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.
72 .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
73 A clock that measures (user and system) CPU time consumed by
75 .\" The CLOCK_MONOTONIC_RAW that was added in 2.6.28 can't be used
76 .\" to create a timer -- mtk, Feb 2009
78 As well as the above values,
80 can be specified as the
83 .BR clock_getcpuclockid (3)
85 .BR pthread_getcpuclockid (3).
91 structure that specifies how the caller
92 should be notified when the timer expires.
93 For the definition and general details of this structure, see
98 field can have the following values:
101 Don't asynchronously notify when the timer expires.
102 Progress of the timer can be monitored using
103 .BR timer_gettime (2).
106 Upon timer expiration, generate the signal
116 structure will be set to
118 At any point in time,
119 at most one signal is queued to the process for a given timer; see
120 .BR timer_getoverrun (2)
124 Upon timer expiration, invoke
125 .I sigev_notify_function
126 as if it were the start function of a new thread.
131 .BR SIGEV_THREAD_ID " (Linux-specific)"
134 but the signal is targeted at the thread whose ID is given in
135 .IR sigev_notify_thread_id ,
136 which must be a thread in the same process as the caller.
138 .IR sigev_notify_thread_id
139 field specifies a kernel thread ID, that is, the value returned by
143 This flag is only intended for use by threading libraries.
147 as NULL is equivalent to specifying a pointer to a
157 .I sigev_value.sival_int
162 returns 0, and the ID of the new timer is placed in
164 On failure, \-1 is returned, and
166 is set to indicate the error.
170 Temporary error during kernel allocation of timer structures.
177 .IR sigev_notify_thread_id
181 .\" glibc layer: malloc()
182 Could not allocate memory.
184 This system call is available since Linux 2.6.
188 A program may create multiple interval timers using
191 Timers are not inherited by the child of a
193 and are disarmed and deleted during an
196 The kernel preallocates a "queued real-time signal"
197 for each timer created using
199 Consequently, the number of timers is limited by the
200 .BR RLIMIT_SIGPENDING
204 The timers created by
206 are commonly known as "POSIX (interval) timers".
207 The POSIX timers API consists of the following interfaces:
212 .BR timer_settime (2):
213 Arm (start) or disarm (stop) a timer.
215 .BR timer_gettime (2):
216 Fetch the time remaining until the next expiration of a timer,
217 along with the interval setting of the timer.
219 .BR timer_getoverrun (2):
220 Return the overrun count for the last timer expiration.
222 .BR timer_delete (2):
223 Disarm and delete a timer.
225 Part of the implementation of the POSIX timers API is provided by glibc.
228 The functionality for
230 is implemented within glibc, rather than the kernel.
232 The timer IDs presented at user level are maintained by glibc,
233 which maps these IDs to the timer IDs employed by the kernel.
234 .\" See the glibc source file kernel-posix-timers.h for the structure
235 .\" that glibc uses to map userspace timer IDs to kernel timer IDs
236 .\" The kernel-level timer ID is exposed via siginfo.si_tid.
238 The POSIX timers system calls first appeared in Linux 2.6.
240 glibc provided an incomplete userspace implementation
242 timers only) using POSIX threads,
243 and current glibc falls back to this implementation on systems
244 running pre-2.6 Linux kernels.
246 The program below takes two arguments: a sleep period in seconds,
247 and a timer frequency in nanoseconds.
248 The program establishes a handler for the signal it uses for the timer,
250 creates and arms a timer that expires with the given frequency,
251 sleeps for the specified number of seconds,
252 and then unblocks the timer signal.
253 Assuming that the timer expired at least once while the program slept,
254 the signal handler will be invoked,
255 and the handler displays some information about the timer notification.
256 The program terminates after one invocation of the signal handler.
258 In the following example run, the program sleeps for 1 second,
259 after creating a timer that has a frequency of 100 nanoseconds.
260 By the time the signal is unblocked and delivered,
261 there have been around ten million overruns.
266 Establishing handler for signal 34
268 timer ID is 0x804c008
269 Sleeping for 1 seconds
272 sival_ptr = 0xbfb174f4; *sival_ptr = 0x804c008
273 overrun count = 10004886
285 #define CLOCKID CLOCK_REALTIME
288 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
292 print_siginfo(siginfo_t *si)
297 tidp = si\->si_value.sival_ptr;
299 printf(" sival_ptr = %p; ", si\->si_value.sival_ptr);
300 printf(" *sival_ptr = 0x%lx\\n", (long) *tidp);
302 or = timer_getoverrun(*tidp);
304 errExit("timer_getoverrun");
306 printf(" overrun count = %d\\n", or);
310 handler(int sig, siginfo_t *si, void *uc)
312 /* Note: calling printf() from a signal handler is not
313 strictly correct, since printf() is not async\-signal\-safe;
316 printf("Caught signal %d\\n", sig);
318 signal(sig, SIG_IGN);
322 main(int argc, char *argv[])
326 struct itimerspec its;
327 long long freq_nanosecs;
332 fprintf(stderr, "Usage: %s <sleep\-secs> <freq\-nanosecs>\\n",
337 /* Establish handler for timer signal */
339 printf("Establishing handler for signal %d\\n", SIG);
340 sa.sa_flags = SA_SIGINFO;
341 sa.sa_sigaction = handler;
342 sigemptyset(&sa.sa_mask);
343 if (sigaction(SIG, &sa, NULL) == \-1)
344 errExit("sigaction");
346 /* Block timer signal temporarily */
348 printf("Blocking signal %d\\n", SIG);
350 sigaddset(&mask, SIG);
351 if (sigprocmask(SIG_SETMASK, &mask, NULL) == \-1)
352 errExit("sigprocmask");
354 /* Create the timer */
356 sev.sigev_notify = SIGEV_SIGNAL;
357 sev.sigev_signo = SIG;
358 sev.sigev_value.sival_ptr = &timerid;
359 if (timer_create(CLOCKID, &sev, &timerid) == \-1)
360 errExit("timer_create");
362 printf("timer ID is 0x%lx\\n", (long) timerid);
364 /* Start the timer */
366 freq_nanosecs = atoll(argv[2]);
367 its.it_value.tv_sec = freq_nanosecs / 1000000000;
368 its.it_value.tv_nsec = freq_nanosecs % 1000000000;
369 its.it_interval.tv_sec = its.it_value.tv_sec;
370 its.it_interval.tv_nsec = its.it_value.tv_nsec;
372 if (timer_settime(timerid, 0, &its, NULL) == \-1)
373 errExit("timer_settime");
375 /* Sleep for a while; meanwhile, the timer may expire
378 printf("Sleeping for %d seconds\\n", atoi(argv[1]));
379 sleep(atoi(argv[1]));
381 /* Unlock the timer signal, so that timer notification
384 printf("Unblocking signal %d\\n", SIG);
385 if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == \-1)
386 errExit("sigprocmask");
392 .BR clock_gettime (2),
394 .BR timer_delete (2),
395 .BR timer_getoverrun (2),
396 .BR timer_settime (2),
397 .BR timerfd_create (2),
398 .BR clock_getcpuclockid (3),
399 .BR pthread_getcpuclockid (3),