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