1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .\" FIXME: Linux 2.6.39 adds CLOCK_BOOTTIME
27 .\" Does this also affect timerfd_create()?
28 .\" FIXME: Linux 2.3.0 adds CLOCK_BOOTTIME_ALARM and CLOCK_REALTIME_ALARM
29 .\" Does this also affect timerfd_create()?
31 .TH TIMER_CREATE 2 2014-01-20 Linux "Linux Programmer's Manual"
33 timer_create \- create a POSIX per-process timer
36 .B #include <signal.h>
39 .BI "int timer_create(clockid_t " clockid ", struct sigevent *" sevp ,
40 .BI " timer_t *" timerid );
43 Link with \fI\-lrt\fP.
46 Feature Test Macro Requirements for glibc (see
47 .BR feature_test_macros (7)):
51 _POSIX_C_SOURCE\ >=\ 199309L
54 creates a new per-process interval timer.
55 The ID of the new timer is returned in the buffer pointed to by
57 which must be a non-null pointer.
58 This ID is unique within the process, until the timer is deleted.
59 The new timer is initially disarmed.
63 argument specifies the clock that the new timer uses to measure time.
64 It can be specified as one of the following values:
67 A settable system-wide real-time clock.
70 A nonsettable monotonically increasing clock that measures time
71 from some unspecified point in the past that does not change
73 .\" Note: the CLOCK_MONOTONIC_RAW clock added for clock_gettime()
74 .\" in 2.6.28 is not supported for POSIX timers -- mtk, Feb 2009
76 .BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)"
77 A clock that measures (user and system) CPU time consumed by
78 (all of the threads in) the calling process.
80 .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
81 A clock that measures (user and system) CPU time consumed by
83 .\" The CLOCK_MONOTONIC_RAW that was added in 2.6.28 can't be used
84 .\" to create a timer -- mtk, Feb 2009
86 As well as the above values,
88 can be specified as the
91 .BR clock_getcpuclockid (3)
93 .BR pthread_getcpuclockid (3).
99 structure that specifies how the caller
100 should be notified when the timer expires.
101 For the definition and general details of this structure, see
106 field can have the following values:
109 Don't asynchronously notify when the timer expires.
110 Progress of the timer can be monitored using
111 .BR timer_gettime (2).
114 Upon timer expiration, generate the signal
124 structure will be set to
126 At any point in time,
127 at most one signal is queued to the process for a given timer; see
128 .BR timer_getoverrun (2)
132 Upon timer expiration, invoke
133 .I sigev_notify_function
134 as if it were the start function of a new thread.
139 .BR SIGEV_THREAD_ID " (Linux-specific)"
142 but the signal is targeted at the thread whose ID is given in
143 .IR sigev_notify_thread_id ,
144 which must be a thread in the same process as the caller.
146 .IR sigev_notify_thread_id
147 field specifies a kernel thread ID, that is, the value returned by
151 This flag is intended only for use by threading libraries.
155 as NULL is equivalent to specifying a pointer to a
165 .I sigev_value.sival_int
170 returns 0, and the ID of the new timer is placed in
172 On failure, \-1 is returned, and
174 is set to indicate the error.
178 Temporary error during kernel allocation of timer structures.
185 .IR sigev_notify_thread_id
189 .\" glibc layer: malloc()
190 Could not allocate memory.
192 This system call is available since Linux 2.6.
196 A program may create multiple interval timers using
199 Timers are not inherited by the child of a
201 and are disarmed and deleted during an
204 The kernel preallocates a "queued real-time signal"
205 for each timer created using
207 Consequently, the number of timers is limited by the
208 .BR RLIMIT_SIGPENDING
212 The timers created by
214 are commonly known as "POSIX (interval) timers".
215 The POSIX timers API consists of the following interfaces:
220 .BR timer_settime (2):
221 Arm (start) or disarm (stop) a timer.
223 .BR timer_gettime (2):
224 Fetch the time remaining until the next expiration of a timer,
225 along with the interval setting of the timer.
227 .BR timer_getoverrun (2):
228 Return the overrun count for the last timer expiration.
230 .BR timer_delete (2):
231 Disarm and delete a timer.
233 Part of the implementation of the POSIX timers API is provided by glibc.
236 The functionality for
238 is implemented within glibc, rather than the kernel.
240 The timer IDs presented at user level are maintained by glibc,
241 which maps these IDs to the timer IDs employed by the kernel.
242 .\" See the glibc source file kernel-posix-timers.h for the structure
243 .\" that glibc uses to map user-space timer IDs to kernel timer IDs
244 .\" The kernel-level timer ID is exposed via siginfo.si_tid.
246 The POSIX timers system calls first appeared in Linux 2.6.
248 glibc provided an incomplete user-space implementation
250 timers only) using POSIX threads,
251 and current glibc falls back to this implementation on systems
252 running pre-2.6 Linux kernels.
254 Since Linux 3.10, the
255 .IR /proc/[pid]/timers
256 file can be used to list the POSIX timers for the process with PID
260 for further information.
262 The program below takes two arguments: a sleep period in seconds,
263 and a timer frequency in nanoseconds.
264 The program establishes a handler for the signal it uses for the timer,
266 creates and arms a timer that expires with the given frequency,
267 sleeps for the specified number of seconds,
268 and then unblocks the timer signal.
269 Assuming that the timer expired at least once while the program slept,
270 the signal handler will be invoked,
271 and the handler displays some information about the timer notification.
272 The program terminates after one invocation of the signal handler.
274 In the following example run, the program sleeps for 1 second,
275 after creating a timer that has a frequency of 100 nanoseconds.
276 By the time the signal is unblocked and delivered,
277 there have been around ten million overruns.
281 $ \fB./a.out 1 100\fP
282 Establishing handler for signal 34
284 timer ID is 0x804c008
285 Sleeping for 1 seconds
288 sival_ptr = 0xbfb174f4; *sival_ptr = 0x804c008
289 overrun count = 10004886
301 #define CLOCKID CLOCK_REALTIME
304 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
308 print_siginfo(siginfo_t *si)
313 tidp = si\->si_value.sival_ptr;
315 printf(" sival_ptr = %p; ", si\->si_value.sival_ptr);
316 printf(" *sival_ptr = 0x%lx\\n", (long) *tidp);
318 or = timer_getoverrun(*tidp);
320 errExit("timer_getoverrun");
322 printf(" overrun count = %d\\n", or);
326 handler(int sig, siginfo_t *si, void *uc)
328 /* Note: calling printf() from a signal handler is not
329 strictly correct, since printf() is not async\-signal\-safe;
332 printf("Caught signal %d\\n", sig);
334 signal(sig, SIG_IGN);
338 main(int argc, char *argv[])
342 struct itimerspec its;
343 long long freq_nanosecs;
348 fprintf(stderr, "Usage: %s <sleep\-secs> <freq\-nanosecs>\\n",
353 /* Establish handler for timer signal */
355 printf("Establishing handler for signal %d\\n", SIG);
356 sa.sa_flags = SA_SIGINFO;
357 sa.sa_sigaction = handler;
358 sigemptyset(&sa.sa_mask);
359 if (sigaction(SIG, &sa, NULL) == \-1)
360 errExit("sigaction");
362 /* Block timer signal temporarily */
364 printf("Blocking signal %d\\n", SIG);
366 sigaddset(&mask, SIG);
367 if (sigprocmask(SIG_SETMASK, &mask, NULL) == \-1)
368 errExit("sigprocmask");
370 /* Create the timer */
372 sev.sigev_notify = SIGEV_SIGNAL;
373 sev.sigev_signo = SIG;
374 sev.sigev_value.sival_ptr = &timerid;
375 if (timer_create(CLOCKID, &sev, &timerid) == \-1)
376 errExit("timer_create");
378 printf("timer ID is 0x%lx\\n", (long) timerid);
380 /* Start the timer */
382 freq_nanosecs = atoll(argv[2]);
383 its.it_value.tv_sec = freq_nanosecs / 1000000000;
384 its.it_value.tv_nsec = freq_nanosecs % 1000000000;
385 its.it_interval.tv_sec = its.it_value.tv_sec;
386 its.it_interval.tv_nsec = its.it_value.tv_nsec;
388 if (timer_settime(timerid, 0, &its, NULL) == \-1)
389 errExit("timer_settime");
391 /* Sleep for a while; meanwhile, the timer may expire
394 printf("Sleeping for %d seconds\\n", atoi(argv[1]));
395 sleep(atoi(argv[1]));
397 /* Unlock the timer signal, so that timer notification
400 printf("Unblocking signal %d\\n", SIG);
401 if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == \-1)
402 errExit("sigprocmask");
410 .BR clock_gettime (2),
412 .BR timer_delete (2),
413 .BR timer_getoverrun (2),
414 .BR timer_settime (2),
415 .BR timerfd_create (2),
416 .BR clock_getcpuclockid (3),
417 .BR pthread_getcpuclockid (3),
423 This page is part of release 3.68 of the Linux
426 A description of the project,
427 information about reporting bugs,
428 and the latest version of this page,
430 \%http://www.kernel.org/doc/man\-pages/.