Debian Codegraph @

upstream/debian-unstable/man7/time_namespaces.7

raw
1 .\" Copyright 2020, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH time_namespaces 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 time_namespaces \- overview of Linux time namespaces
9 .SH DESCRIPTION
10 Time namespaces virtualize the values of two system clocks:
11 .IP \[bu] 3
12 .B CLOCK_MONOTONIC
13 (and likewise
14 .B CLOCK_MONOTONIC_COARSE
15 and
16 .BR CLOCK_MONOTONIC_RAW ),
17 a nonsettable clock that represents monotonic time since
18 \[em]as described by POSIX\[em]
19 "some unspecified point in the past".
20 .IP \[bu]
21 .B CLOCK_BOOTTIME
22 (and likewise
23 .BR CLOCK_BOOTTIME_ALARM ),
24 a nonsettable clock that is identical to
25 .BR CLOCK_MONOTONIC ,
26 except that it also includes any time that the system is suspended.
27 .P
28 Thus, the processes in a time namespace share per-namespace values
29 for these clocks.
30 This affects various APIs that measure against these clocks, including:
31 .BR clock_gettime (2),
32 .BR clock_nanosleep (2),
33 .BR nanosleep (2),
34 .BR timer_settime (2),
35 .BR timerfd_settime (2),
36 and
37 .IR /proc/uptime .
38 .P
39 Currently, the only way to create a time namespace is by calling
40 .BR unshare (2)
41 with the
42 .B CLONE_NEWTIME
43 flag.
44 This call creates a new time namespace but does
45 .I not
46 place the calling process in the new namespace.
47 Instead, the calling process's
48 subsequently created children are placed in the new namespace.
49 This allows clock offsets (see below) for the new namespace
50 to be set before the first process is placed in the namespace.
51 The
52 .IR /proc/ pid /ns/time_for_children
53 symbolic link shows the time namespace in which
54 the children of a process will be created.
55 (A process can use a file descriptor opened on
56 this symbolic link in a call to
57 .BR setns (2)
58 in order to move into the namespace.)
59 .\"
60 .SS \f[I]/proc/\f[]pid\f[I]/timens_offsets\f[]
61 Associated with each time namespace are offsets,
62 expressed with respect to the initial time namespace,
63 that define the values of the monotonic and
64 boot-time clocks in that namespace.
65 These offsets are exposed via the file
66 .IR /proc/ pid /timens_offsets .
67 Within this file,
68 the offsets are expressed as lines consisting of
69 three space-delimited fields:
70 .P
71 .in +4n
72 .EX
73 <clock-id> <offset-secs> <offset-nanosecs>
74 .EE
75 .in
76 .P
77 The
78 .I clock-id
79 is a string that identifies the clock whose offsets are being shown.
80 This field is either
81 .IR monotonic ,
82 for
83 .BR CLOCK_MONOTONIC ,
84 or
85 .IR boottime ,
86 for
87 .BR CLOCK_BOOTTIME .
88 The remaining fields express the offset (seconds plus nanoseconds) for the
89 clock in this time namespace.
90 These offsets are expressed relative to the clock values in
91 the initial time namespace.
92 The
93 .I offset-secs
94 value can be negative, subject to restrictions noted below;
95 .I offset-nanosecs
96 is an unsigned value.
97 .P
98 In the initial time namespace, the contents of the
99 .I timens_offsets
100 file are as follows:
101 .P
102 .in +4n
103 .EX
104 .RB $ " cat /proc/self/timens_offsets"
105 monotonic 0 0
106 boottime 0 0
107 .EE
108 .in
109 .P
110 In a new time namespace that has had no member processes,
111 the clock offsets can be modified by writing newline-terminated
112 records of the same form to the
113 .I timens_offsets
114 file.
115 The file can be written to multiple times,
116 but after the first process has been created in or has entered the namespace,
117 .BR write (2)s
118 on this file fail with the error
119 .BR EACCES .
120 In order to write to the
121 .I timens_offsets
122 file, a process must have the
123 .B CAP_SYS_TIME
124 capability in the user namespace that owns the time namespace.
125 .P
126 Writes to the
127 .I timens_offsets
128 file can fail with the following errors:
129 .TP
130 .B EINVAL
131 An
132 .I offset-nanosecs
133 value is greater than 999,999,999.
134 .TP
135 .B EINVAL
136 A
137 .I clock-id
138 value is not valid.
139 .TP
140 .B EPERM
141 The caller does not have the
142 .B CAP_SYS_TIME
143 capability.
144 .TP
145 .B ERANGE
146 An
147 .I offset-secs
148 value is out of range.
149 In particular;
150 .RS
151 .IP \[bu] 3
152 .I offset-secs
153 can't be set to a value which would make the current
154 time on the corresponding clock inside the namespace a negative value;
155 and
156 .IP \[bu]
157 .I offset-secs
158 can't be set to a value such that the time on the corresponding clock
159 inside the namespace would exceed half of the value of the kernel constant
160 .B KTIME_SEC_MAX
161 (this limits the clock value to a maximum of approximately 146 years).
162 .RE
163 .P
164 In a new time namespace created by
165 .BR unshare (2),
166 the contents of the
167 .I timens_offsets
168 file are inherited from the time namespace of the creating process.
169 .SH NOTES
170 Use of time namespaces requires a kernel that is configured with the
171 .B CONFIG_TIME_NS
172 option.
173 .P
174 Note that time namespaces do not virtualize the
175 .B CLOCK_REALTIME
176 clock.
177 Virtualization of this clock was avoided for reasons of complexity
178 and overhead within the kernel.
179 .P
180 For compatibility with the initial implementation, when writing a
181 .I clock-id
182 to the
183 .IR /proc/ pid /timens_offsets
184 file, the numerical values of the IDs can be written
185 instead of the symbolic names show above; i.e., 1 instead of
186 .IR monotonic ,
187 and 7 instead of
188 .IR boottime .
189 For readability, the use of the symbolic names over the numbers is preferred.
190 .P
191 The motivation for adding time namespaces was to allow
192 the monotonic and boot-time clocks to maintain consistent values
193 during container migration and checkpoint/restore.
194 .SH EXAMPLES
195 The following shell session demonstrates the operation of time namespaces.
196 We begin by displaying the inode number of the time namespace
197 of a shell in the initial time namespace:
198 .P
199 .in +4n
200 .EX
201 .RB $ " readlink /proc/$$/ns/time"
202 time:[4026531834]
203 .EE
204 .in
205 .P
206 Continuing in the initial time namespace, we display the system uptime using
207 .BR uptime (1)
208 and use the
209 .I clock_times
210 example program shown in
211 .BR clock_getres (2)
212 to display the values of various clocks:
213 .P
214 .in +4n
215 .EX
216 .RB $ " uptime \-\-pretty"
217 up 21 hours, 17 minutes
218 .RB $ " ./clock_times"
219 CLOCK_REALTIME : 1585989401.971 (18356 days + 8h 36m 41s)
220 CLOCK_TAI : 1585989438.972 (18356 days + 8h 37m 18s)
221 CLOCK_MONOTONIC: 56338.247 (15h 38m 58s)
222 CLOCK_BOOTTIME : 76633.544 (21h 17m 13s)
223 .EE
224 .in
225 .P
226 We then use
227 .BR unshare (1)
228 to create a time namespace and execute a
229 .BR bash (1)
230 shell.
231 From the new shell, we use the built-in
232 .B echo
233 command to write records to the
234 .I timens_offsets
235 file adjusting the offset for the
236 .B CLOCK_MONOTONIC
237 clock forward 2 days
238 and the offset for the
239 .B CLOCK_BOOTTIME
240 clock forward 7 days:
241 .P
242 .in +4n
243 .EX
244 .RB $ " PS1="ns2# " sudo unshare \-T \-\- bash \-\-norc"
245 .RB ns2# " echo "monotonic $((2*24*60*60)) 0" > /proc/$$/timens_offsets"
246 .RB ns2# " echo "boottime $((7*24*60*60)) 0" > /proc/$$/timens_offsets"
247 .EE
248 .in
249 .P
250 Above, we started the
251 .BR bash (1)
252 shell with the
253 .B \-\-norc
254 option so that no start-up scripts were executed.
255 This ensures that no child processes are created from the
256 shell before we have a chance to update the
257 .I timens_offsets
258 file.
259 .P
260 We then use
261 .BR cat (1)
262 to display the contents of the
263 .I timens_offsets
264 file.
265 The execution of
266 .BR cat (1)
267 creates the first process in the new time namespace,
268 after which further attempts to update the
269 .I timens_offsets
270 file produce an error.
271 .P
272 .in +4n
273 .EX
274 .RB ns2# " cat /proc/$$/timens_offsets"
275 monotonic 172800 0
276 boottime 604800 0
277 .RB ns2# " echo \[dq]boottime $((9*24*60*60)) 0\[dq] > /proc/$$/timens_offsets"
278 bash: echo: write error: Permission denied
279 .EE
280 .in
281 .P
282 Continuing in the new namespace, we execute
283 .BR uptime (1)
284 and the
285 .I clock_times
286 example program:
287 .P
288 .in +4n
289 .EX
290 .RB ns2# " uptime \-\-pretty"
291 up 1 week, 21 hours, 18 minutes
292 .RB ns2# " ./clock_times"
293 CLOCK_REALTIME : 1585989457.056 (18356 days + 8h 37m 37s)
294 CLOCK_TAI : 1585989494.057 (18356 days + 8h 38m 14s)
295 CLOCK_MONOTONIC: 229193.332 (2 days + 15h 39m 53s)
296 CLOCK_BOOTTIME : 681488.629 (7 days + 21h 18m 8s)
297 .EE
298 .in
299 .P
300 From the above output, we can see that the monotonic
301 and boot-time clocks have different values in the new time namespace.
302 .P
303 Examining the
304 .IR /proc/ pid /ns/time
305 and
306 .IR /proc/ pid /ns/time_for_children
307 symbolic links, we see that the shell is a member of the initial time
308 namespace, but its children are created in the new namespace.
309 .P
310 .in +4n
311 .EX
312 .RB ns2# " readlink /proc/$$/ns/time"
313 time:[4026531834]
314 .RB ns2# " readlink /proc/$$/ns/time_for_children"
315 time:[4026532900]
316 .RB ns2# " readlink /proc/self/ns/time" " # Creates a child process"
317 time:[4026532900]
318 .EE
319 .in
320 .P
321 Returning to the shell in the initial time namespace,
322 we see that the monotonic and boot-time clocks
323 are unaffected by the
324 .I timens_offsets
325 changes that were made in the other time namespace:
326 .P
327 .in +4n
328 .EX
329 .RB $ " uptime \-\-pretty"
330 up 21 hours, 19 minutes
331 .RB $ " ./clock_times"
332 CLOCK_REALTIME : 1585989401.971 (18356 days + 8h 38m 51s)
333 CLOCK_TAI : 1585989438.972 (18356 days + 8h 39m 28s)
334 CLOCK_MONOTONIC: 56338.247 (15h 41m 8s)
335 CLOCK_BOOTTIME : 76633.544 (21h 19m 23s)
336 .EE
337 .in
338 .SH SEE ALSO
339 .BR nsenter (1),
340 .BR unshare (1),
341 .BR clock_settime (2),
342 .\" clone3() support for time namespaces is a work in progress
343 .\" .BR clone3 (2),
344 .BR setns (2),
345 .BR unshare (2),
346 .BR namespaces (7),
347 .BR time (7)