]>
Commit | Line | Data |
---|---|---|
944f8a69 MK |
1 | .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
944f8a69 MK |
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. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
07ee7db9 | 25 | .\" |
f55a6d59 | 26 | .TH TIMER_CREATE 2 2017-07-13 Linux "Linux Programmer's Manual" |
944f8a69 MK |
27 | .SH NAME |
28 | timer_create \- create a POSIX per-process timer | |
29 | .SH SYNOPSIS | |
30 | .nf | |
31 | .B #include <signal.h> | |
32 | .B #include <time.h> | |
dbfe9c70 | 33 | .PP |
0d5f6a62 | 34 | .BI "int timer_create(clockid_t " clockid ", struct sigevent *" sevp , |
944f8a69 MK |
35 | .BI " timer_t *" timerid ); |
36 | .fi | |
dbfe9c70 | 37 | .PP |
702cbe15 | 38 | Link with \fI\-lrt\fP. |
68e4db0a | 39 | .PP |
944f8a69 MK |
40 | .in -4n |
41 | Feature Test Macro Requirements for glibc (see | |
42 | .BR feature_test_macros (7)): | |
43 | .in | |
68e4db0a | 44 | .PP |
944f8a69 | 45 | .BR timer_create (): |
98dbe7af | 46 | _POSIX_C_SOURCE\ >=\ 199309L |
944f8a69 MK |
47 | .SH DESCRIPTION |
48 | .BR timer_create () | |
49 | creates a new per-process interval timer. | |
50 | The ID of the new timer is returned in the buffer pointed to by | |
51 | .IR timerid , | |
b437fdd9 | 52 | which must be a non-null pointer. |
944f8a69 MK |
53 | This ID is unique within the process, until the timer is deleted. |
54 | The new timer is initially disarmed. | |
55 | ||
56 | The | |
57 | .I clockid | |
58 | argument specifies the clock that the new timer uses to measure time. | |
59 | It can be specified as one of the following values: | |
60 | .TP | |
61 | .B CLOCK_REALTIME | |
62 | A settable system-wide real-time clock. | |
63 | .TP | |
64 | .B CLOCK_MONOTONIC | |
24b74457 | 65 | A nonsettable monotonically increasing clock that measures time |
944f8a69 MK |
66 | from some unspecified point in the past that does not change |
67 | after system startup. | |
68 | .\" Note: the CLOCK_MONOTONIC_RAW clock added for clock_gettime() | |
69 | .\" in 2.6.28 is not supported for POSIX timers -- mtk, Feb 2009 | |
70 | .TP | |
71 | .BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)" | |
72 | A clock that measures (user and system) CPU time consumed by | |
73 | (all of the threads in) the calling process. | |
74 | .TP | |
75 | .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)" | |
76 | A clock that measures (user and system) CPU time consumed by | |
77 | the calling thread. | |
78 | .\" The CLOCK_MONOTONIC_RAW that was added in 2.6.28 can't be used | |
79 | .\" to create a timer -- mtk, Feb 2009 | |
39c97bde MK |
80 | .TP |
81 | .BR CLOCK_BOOTTIME " (Since Linux 2.6.39)" | |
82 | .\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0 | |
83 | Like | |
84 | .BR CLOCK_MONOTONIC , | |
85 | this is a monotonically increasing clock. | |
86 | However, whereas the | |
87 | .BR CLOCK_MONOTONIC | |
88 | clock does not measure the time while a system is suspended, the | |
89 | .BR CLOCK_BOOTTIME | |
90 | clock does include the time during which the system is suspended. | |
91 | This is useful for applications that need to be suspend-aware. | |
92 | .BR CLOCK_REALTIME | |
93 | is not suitable for such applications, since that clock is affected | |
94 | by discontinuous changes to the system clock. | |
8b047fe2 MK |
95 | .TP |
96 | .BR CLOCK_REALTIME_ALARM " (since Linux 3.0)" | |
97 | .\" commit 9a7adcf5c6dea63d2e47e6f6d2f7a6c9f48b9337 | |
98 | This clock is like | |
99 | .BR CLOCK_REALTIME , | |
100 | but will wake the system if it is suspended. | |
101 | The caller must have the | |
102 | .B CAP_WAKE_ALARM | |
103 | capability in order to set a timer against this clock. | |
104 | .TP | |
105 | .BR CLOCK_BOOTTIME_ALARM " (since Linux 3.0)" | |
106 | .\" commit 9a7adcf5c6dea63d2e47e6f6d2f7a6c9f48b9337 | |
107 | This clock is like | |
108 | .BR CLOCK_BOOTTIME , | |
109 | but will wake the system if it is suspended. | |
110 | The caller must have the | |
111 | .B CAP_WAKE_ALARM | |
112 | capability in order to set a timer against this clock. | |
944f8a69 MK |
113 | .PP |
114 | As well as the above values, | |
115 | .I clockid | |
116 | can be specified as the | |
117 | .I clockid | |
118 | returned by a call to | |
119 | .BR clock_getcpuclockid (3) | |
120 | or | |
121 | .BR pthread_getcpuclockid (3). | |
122 | ||
123 | The | |
0d5f6a62 | 124 | .I sevp |
944f8a69 MK |
125 | argument points to a |
126 | .I sigevent | |
127 | structure that specifies how the caller | |
128 | should be notified when the timer expires. | |
0e39ed97 MK |
129 | For the definition and general details of this structure, see |
130 | .BR sigevent (7). | |
944f8a69 | 131 | |
0e39ed97 | 132 | The |
0d5f6a62 | 133 | .I sevp.sigev_notify |
0e39ed97 | 134 | field can have the following values: |
944f8a69 MK |
135 | .TP |
136 | .BR SIGEV_NONE | |
137 | Don't asynchronously notify when the timer expires. | |
138 | Progress of the timer can be monitored using | |
139 | .BR timer_gettime (2). | |
140 | .TP | |
141 | .BR SIGEV_SIGNAL | |
142 | Upon timer expiration, generate the signal | |
143 | .I sigev_signo | |
144 | for the process. | |
0e39ed97 MK |
145 | See |
146 | .BR sigevent (7) | |
147 | for general details. | |
148 | The | |
149 | .I si_code | |
150 | field of the | |
151 | .I siginfo_t | |
152 | structure will be set to | |
153 | .BR SI_TIMER . | |
944f8a69 MK |
154 | At any point in time, |
155 | at most one signal is queued to the process for a given timer; see | |
156 | .BR timer_getoverrun (2) | |
157 | for more details. | |
158 | .TP | |
159 | .BR SIGEV_THREAD | |
160 | Upon timer expiration, invoke | |
161 | .I sigev_notify_function | |
162 | as if it were the start function of a new thread. | |
0e39ed97 MK |
163 | See |
164 | .BR sigevent (7) | |
165 | for details. | |
944f8a69 MK |
166 | .TP |
167 | .BR SIGEV_THREAD_ID " (Linux-specific)" | |
168 | As for | |
169 | .BR SIGEV_SIGNAL , | |
170 | but the signal is targeted at the thread whose ID is given in | |
171 | .IR sigev_notify_thread_id , | |
172 | which must be a thread in the same process as the caller. | |
173 | The | |
174 | .IR sigev_notify_thread_id | |
175 | field specifies a kernel thread ID, that is, the value returned by | |
176 | .BR clone (2) | |
177 | or | |
178 | .BR gettid (2). | |
33a0ccb2 | 179 | This flag is intended only for use by threading libraries. |
944f8a69 MK |
180 | .PP |
181 | Specifying | |
0d5f6a62 | 182 | .I sevp |
944f8a69 MK |
183 | as NULL is equivalent to specifying a pointer to a |
184 | .I sigevent | |
185 | structure in which | |
186 | .I sigev_notify | |
187 | is | |
188 | .BR SIGEV_SIGNAL , | |
189 | .I sigev_signo | |
190 | is | |
191 | .BR SIGALRM , | |
192 | and | |
193 | .I sigev_value.sival_int | |
194 | is the timer ID. | |
195 | .SH RETURN VALUE | |
196 | On success, | |
197 | .BR timer_create () | |
198 | returns 0, and the ID of the new timer is placed in | |
199 | .IR *timerid . | |
200 | On failure, \-1 is returned, and | |
201 | .I errno | |
202 | is set to indicate the error. | |
203 | .SH ERRORS | |
204 | .TP | |
205 | .B EAGAIN | |
206 | Temporary error during kernel allocation of timer structures. | |
207 | .TP | |
208 | .B EINVAL | |
209 | Clock ID, | |
210 | .IR sigev_notify , | |
211 | .IR sigev_signo , | |