1timer_create(3C) Standard C Library Functions timer_create(3C)
2
3
4
6 timer_create - create a timer
7
9 #include <signal.h>
10 #include <time.h>
11
12 int timer_create(clockid_t clock_id,
13 struct sigevent *restrict evp, timer_t *restrict timerid);
14
15
17 The timer_create() function creates a timer using the specified clock,
18 clock_id, as the timing base. The timer_create() function returns, in
19 the location referenced by timerid, a timer ID of type timer_t used to
20 identify the timer in timer requests. This timer ID will be unique
21 within the calling process until the timer is deleted. The particular
22 clock, clock_id, is defined in <time.h>. The timer whose ID is returned
23 will be in a disarmed state upon return from timer_create().
24
25
26 The evp argument, if non-null, points to a sigevent structure. This
27 structure, allocated by the application, defines the asynchronous noti‐
28 fication that will occur when the timer expires (see signal.h(3HEAD)
29 for event notification details). If the evp argument is NULL, the
30 effect is as if the evp argument pointed to a sigevent structure with
31 the sigev_notify member having the value SIGEV_SIGNAL, the sigev_signo
32 having the value SIGALARM, and the sigev_value member having the value
33 of the timer ID.
34
35
36 The system defines a set of clocks that can be used as timing bases for
37 per-process timers. The following values for clock_id are supported:
38
39 CLOCK_REALTIME wall clock
40
41
42 CLOCK_VIRTUAL user CPU usage clock
43
44
45 CLOCK_PROF user and system CPU usage clock
46
47
48 CLOCK_HIGHRES non-adjustable, high-resolution clock
49
50
51
52 For timers created with a clock_id of CLOCK_HIGHRES, the system will
53 attempt to use an optimal hardware source. This may include, but is not
54 limited to, per-CPU timer sources. The actual hardware source used is
55 transparent to the user and may change over the lifetime of the timer.
56 For example, if the caller that created the timer were to change its
57 processor binding or its processor set, the system may elect to drive
58 the timer with a hardware source that better reflects the new binding.
59 Timers based on a clock_id of CLOCK_HIGHRES are ideally suited for
60 interval timers that have minimal jitter tolerence.
61
62
63 Timers are not inherited by a child process across a fork(2) and are
64 disarmed and deleted by a call to one of the exec functions (see
65 exec(2)).
66
68 Upon successful completion, timer_create() returns 0 and updates the
69 location referenced by timerid to a timer_t, which can be passed to the
70 per-process timer calls. If an error occurs, the function returns −1
71 and sets errno to indicate the error. The value of timerid is undefined
72 if an error occurs.
73
75 The timer_create() function will fail if:
76
77 EAGAIN The system lacks sufficient signal queuing resources to honor
78 the request, or the calling process has already created all
79 of the timers it is allowed by the system.
80
81
82 EINVAL The specified clock ID, clock_id, is not defined.
83
84
85 EPERM The specified clock ID, clock_id, is CLOCK_HIGHRES and the
86 {PRIV_PROC_CLOCK_HIGHRES} is not asserted in the effective
87 set of the calling process.
88
89
91 See attributes(5) for descriptions of the following attributes:
92
93
94
95
96 ┌─────────────────────────────┬─────────────────────────────┐
97 │ATTRIBUTE TYPE │ATTRIBUTE VALUE │
98 ├─────────────────────────────┼─────────────────────────────┤
99 │Interface Stability │Committed │
100 ├─────────────────────────────┼─────────────────────────────┤
101 │MT-Level │MT-Safe with exceptions │
102 ├─────────────────────────────┼─────────────────────────────┤
103 │Standard │See standards(5). │
104 └─────────────────────────────┴─────────────────────────────┘
105
107 exec(2), fork(2), time(2), clock_settime(3C), signal(3C), sig‐
108 nal.h(3HEAD), timer_delete(3C), timer_settime(3C), attributes(5), priv‐
109 ileges(5), standards(5)
110
111
112
113SunOS 5.11 5 Feb 2008 timer_create(3C)