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