1timer_create(2)               System Calls Manual              timer_create(2)
2
3
4

NAME

6       timer_create - create a POSIX per-process timer
7

LIBRARY

9       Real-time library (librt, -lrt)
10

SYNOPSIS

12       #include <signal.h>           /* Definition of SIGEV_* constants */
13       #include <time.h>
14
15       int timer_create(clockid_t clockid,
16                        struct sigevent *_Nullable restrict sevp,
17                        timer_t *restrict timerid);
18
19   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
20
21       timer_create():
22           _POSIX_C_SOURCE >= 199309L
23

DESCRIPTION

25       timer_create() creates a new per-process interval timer.  The ID of the
26       new timer is returned in the buffer pointed to by timerid,  which  must
27       be a non-null pointer.  This ID is unique within the process, until the
28       timer is deleted.  The new timer is initially disarmed.
29
30       The clockid argument specifies the clock that the  new  timer  uses  to
31       measure time.  It can be specified as one of the following values:
32
33       CLOCK_REALTIME
34              A settable system-wide real-time clock.
35
36       CLOCK_MONOTONIC
37              A  nonsettable monotonically increasing clock that measures time
38              from some unspecified point in the past that does not change af‐
39              ter system startup.
40
41       CLOCK_PROCESS_CPUTIME_ID (since Linux 2.6.12)
42              A  clock  that  measures  (user and system) CPU time consumed by
43              (all of the threads in) the calling process.
44
45       CLOCK_THREAD_CPUTIME_ID (since Linux 2.6.12)
46              A clock that measures (user and system) CPU time consumed by the
47              calling thread.
48
49       CLOCK_BOOTTIME (Since Linux 2.6.39)
50              Like  CLOCK_MONOTONIC, this is a monotonically increasing clock.
51              However, whereas the CLOCK_MONOTONIC clock does not measure  the
52              time  while a system is suspended, the CLOCK_BOOTTIME clock does
53              include the time during which the system is suspended.  This  is
54              useful   for   applications   that  need  to  be  suspend-aware.
55              CLOCK_REALTIME is not suitable for such applications, since that
56              clock is affected by discontinuous changes to the system clock.
57
58       CLOCK_REALTIME_ALARM (since Linux 3.0)
59              This  clock  is like CLOCK_REALTIME, but will wake the system if
60              it is suspended.  The caller must have the CAP_WAKE_ALARM  capa‐
61              bility in order to set a timer against this clock.
62
63       CLOCK_BOOTTIME_ALARM (since Linux 3.0)
64              This  clock  is like CLOCK_BOOTTIME, but will wake the system if
65              it is suspended.  The caller must have the CAP_WAKE_ALARM  capa‐
66              bility in order to set a timer against this clock.
67
68       CLOCK_TAI (since Linux 3.10)
69              A  system-wide  clock  derived from wall-clock time but ignoring
70              leap seconds.
71
72       See clock_getres(2) for some further details on the above clocks.
73
74       As well as the above values, clockid can be specified  as  the  clockid
75       returned   by  a  call  to  clock_getcpuclockid(3)  or  pthread_getcpu‐
76       clockid(3).
77
78       The sevp argument points to a sigevent structure that specifies how the
79       caller  should  be notified when the timer expires.  For the definition
80       and general details of this structure, see sigevent(7).
81
82       The sevp.sigev_notify field can have the following values:
83
84       SIGEV_NONE
85              Don't asynchronously notify when the timer expires.  Progress of
86              the timer can be monitored using timer_gettime(2).
87
88       SIGEV_SIGNAL
89              Upon  timer  expiration, generate the signal sigev_signo for the
90              process.  See sigevent(7)  for  general  details.   The  si_code
91              field  of  the  siginfo_t structure will be set to SI_TIMER.  At
92              any point in time, at most one signal is queued to  the  process
93              for a given timer; see timer_getoverrun(2) for more details.
94
95       SIGEV_THREAD
96              Upon  timer  expiration,  invoke  sigev_notify_function as if it
97              were the start function of a new thread.   See  sigevent(7)  for
98              details.
99
100       SIGEV_THREAD_ID (Linux-specific)
101              As  for  SIGEV_SIGNAL,  but the signal is targeted at the thread
102              whose ID is given in sigev_notify_thread_id,  which  must  be  a
103              thread  in  the  same  process  as  the  caller.   The sigev_no‐
104              tify_thread_id field specifies a kernel thread ID, that is,  the
105              value  returned by clone(2) or gettid(2).  This flag is intended
106              only for use by threading libraries.
107
108       Specifying sevp as NULL is equivalent to  specifying  a  pointer  to  a
109       sigevent  structure  in which sigev_notify is SIGEV_SIGNAL, sigev_signo
110       is SIGALRM, and sigev_value.sival_int is the timer ID.
111

RETURN VALUE

113       On success, timer_create() returns 0, and the ID of the  new  timer  is
114       placed  in  *timerid.   On failure, -1 is returned, and errno is set to
115       indicate the error.
116

ERRORS

118       EAGAIN Temporary error during kernel allocation of timer structures.
119
120       EINVAL Clock ID, sigev_notify, sigev_signo,  or  sigev_notify_thread_id
121              is invalid.
122
123       ENOMEM Could not allocate memory.
124
125       ENOTSUP
126              The  kernel  does  not  support  creating  a  timer against this
127              clockid.
128
129       EPERM  clockid was CLOCK_REALTIME_ALARM or CLOCK_BOOTTIME_ALARM but the
130              caller did not have the CAP_WAKE_ALARM capability.
131

VERSIONS

133   C library/kernel differences
134       Part  of  the  implementation  of  the  POSIX timers API is provided by
135       glibc.  In particular:
136
137       •  Much of the functionality for  SIGEV_THREAD  is  implemented  within
138          glibc,  rather  than the kernel.  (This is necessarily so, since the
139          thread involved in handling the notification is  one  that  must  be
140          managed  by  the  C library POSIX threads implementation.)  Although
141          the notification delivered to the process is via  a  thread,  inter‐
142          nally   the   NPTL  implementation  uses  a  sigev_notify  value  of
143          SIGEV_THREAD_ID along with a real-time signal that  is  reserved  by
144          the implementation (see nptl(7)).
145
146       •  The  implementation of the default case where evp is NULL is handled
147          inside glibc, which invokes the underlying system call with a  suit‐
148          ably populated sigevent structure.
149
150       •  The timer IDs presented at user level are maintained by glibc, which
151          maps these IDs to the timer IDs employed by the kernel.
152

STANDARDS

154       POSIX.1-2008.
155

HISTORY

157       Linux 2.6.  POSIX.1-2001.
158
159       Prior to Linux 2.6, glibc provided an incomplete user-space implementa‐
160       tion (CLOCK_REALTIME timers only) using POSIX threads, and before glibc
161       2.17, the implementation falls back to this technique on  systems  run‐
162       ning kernels older than Linux 2.6.
163

NOTES

165       A program may create multiple interval timers using timer_create().
166
167       Timers  are  not  inherited by the child of a fork(2), and are disarmed
168       and deleted during an execve(2).
169
170       The kernel preallocates a "queued real-time signal" for each timer cre‐
171       ated  using timer_create().  Consequently, the number of timers is lim‐
172       ited by the RLIMIT_SIGPENDING resource limit (see setrlimit(2)).
173
174       The timers created by timer_create() are commonly known as "POSIX  (in‐
175       terval) timers".  The POSIX timers API consists of the following inter‐
176       faces:
177
178       timer_create()
179              Create a timer.
180
181       timer_settime(2)
182              Arm (start) or disarm (stop) a timer.
183
184       timer_gettime(2)
185              Fetch the time remaining until the next expiration of  a  timer,
186              along with the interval setting of the timer.
187
188       timer_getoverrun(2)
189              Return the overrun count for the last timer expiration.
190
191       timer_delete(2)
192              Disarm and delete a timer.
193
194       Since  Linux  3.10,  the  /proc/pid/timers file can be used to list the
195       POSIX timers for the process with PID pid.  See proc(5) for further in‐
196       formation.
197
198       Since  Linux  4.10,  support  for POSIX timers is a configurable option
199       that is enabled by default.  Kernel support can  be  disabled  via  the
200       CONFIG_POSIX_TIMERS option.
201

EXAMPLES

203       The program below takes two arguments: a sleep period in seconds, and a
204       timer frequency in nanoseconds.  The program establishes a handler  for
205       the  signal it uses for the timer, blocks that signal, creates and arms
206       a timer that expires with the given frequency, sleeps for the specified
207       number  of  seconds, and then unblocks the timer signal.  Assuming that
208       the timer expired at least once while the  program  slept,  the  signal
209       handler  will  be  invoked,  and  the handler displays some information
210       about the timer notification.  The program terminates after one invoca‐
211       tion of the signal handler.
212
213       In  the  following  example run, the program sleeps for 1 second, after
214       creating a timer that has a frequency of 100 nanoseconds.  By the  time
215       the  signal is unblocked and delivered, there have been around ten mil‐
216       lion overruns.
217
218           $ ./a.out 1 100
219           Establishing handler for signal 34
220           Blocking signal 34
221           timer ID is 0x804c008
222           Sleeping for 1 seconds
223           Unblocking signal 34
224           Caught signal 34
225               sival_ptr = 0xbfb174f4;     *sival_ptr = 0x804c008
226               overrun count = 10004886
227
228   Program source
229
230       #include <signal.h>
231       #include <stdint.h>
232       #include <stdio.h>
233       #include <stdlib.h>
234       #include <time.h>
235       #include <unistd.h>
236
237       #define CLOCKID CLOCK_REALTIME
238       #define SIG SIGRTMIN
239
240       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
241                               } while (0)
242
243       static void
244       print_siginfo(siginfo_t *si)
245       {
246           int      or;
247           timer_t  *tidp;
248
249           tidp = si->si_value.sival_ptr;
250
251           printf("    sival_ptr = %p; ", si->si_value.sival_ptr);
252           printf("    *sival_ptr = %#jx\n", (uintmax_t) *tidp);
253
254           or = timer_getoverrun(*tidp);
255           if (or == -1)
256               errExit("timer_getoverrun");
257           else
258               printf("    overrun count = %d\n", or);
259       }
260
261       static void
262       handler(int sig, siginfo_t *si, void *uc)
263       {
264           /* Note: calling printf() from a signal handler is not safe
265              (and should not be done in production programs), since
266              printf() is not async-signal-safe; see signal-safety(7).
267              Nevertheless, we use printf() here as a simple way of
268              showing that the handler was called. */
269
270           printf("Caught signal %d\n", sig);
271           print_siginfo(si);
272           signal(sig, SIG_IGN);
273       }
274
275       int
276       main(int argc, char *argv[])
277       {
278           timer_t            timerid;
279           sigset_t           mask;
280           long long          freq_nanosecs;
281           struct sigevent    sev;
282           struct sigaction   sa;
283           struct itimerspec  its;
284
285           if (argc != 3) {
286               fprintf(stderr, "Usage: %s <sleep-secs> <freq-nanosecs>\n",
287                       argv[0]);
288               exit(EXIT_FAILURE);
289           }
290
291           /* Establish handler for timer signal. */
292
293           printf("Establishing handler for signal %d\n", SIG);
294           sa.sa_flags = SA_SIGINFO;
295           sa.sa_sigaction = handler;
296           sigemptyset(&sa.sa_mask);
297           if (sigaction(SIG, &sa, NULL) == -1)
298               errExit("sigaction");
299
300           /* Block timer signal temporarily. */
301
302           printf("Blocking signal %d\n", SIG);
303           sigemptyset(&mask);
304           sigaddset(&mask, SIG);
305           if (sigprocmask(SIG_SETMASK, &mask, NULL) == -1)
306               errExit("sigprocmask");
307
308           /* Create the timer. */
309
310           sev.sigev_notify = SIGEV_SIGNAL;
311           sev.sigev_signo = SIG;
312           sev.sigev_value.sival_ptr = &timerid;
313           if (timer_create(CLOCKID, &sev, &timerid) == -1)
314               errExit("timer_create");
315
316           printf("timer ID is %#jx\n", (uintmax_t) timerid);
317
318           /* Start the timer. */
319
320           freq_nanosecs = atoll(argv[2]);
321           its.it_value.tv_sec = freq_nanosecs / 1000000000;
322           its.it_value.tv_nsec = freq_nanosecs % 1000000000;
323           its.it_interval.tv_sec = its.it_value.tv_sec;
324           its.it_interval.tv_nsec = its.it_value.tv_nsec;
325
326           if (timer_settime(timerid, 0, &its, NULL) == -1)
327                errExit("timer_settime");
328
329           /* Sleep for a while; meanwhile, the timer may expire
330              multiple times. */
331
332           printf("Sleeping for %d seconds\n", atoi(argv[1]));
333           sleep(atoi(argv[1]));
334
335           /* Unlock the timer signal, so that timer notification
336              can be delivered. */
337
338           printf("Unblocking signal %d\n", SIG);
339           if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == -1)
340               errExit("sigprocmask");
341
342           exit(EXIT_SUCCESS);
343       }
344

SEE ALSO

346       clock_gettime(2), setitimer(2), timer_delete(2), timer_getoverrun(2),
347       timer_settime(2), timerfd_create(2), clock_getcpuclockid(3),
348       pthread_getcpuclockid(3), pthreads(7), sigevent(7), signal(7), time(7)
349
350
351
352Linux man-pages 6.04              2023-03-30                   timer_create(2)
Impressum