1time_namespaces(7)     Miscellaneous Information Manual     time_namespaces(7)
2
3
4

NAME

6       time_namespaces - overview of Linux time namespaces
7

DESCRIPTION

9       Time namespaces virtualize the values of two system clocks:
10
11CLOCK_MONOTONIC (and likewise CLOCK_MONOTONIC_COARSE and CLOCK_MONO‐
12          TONIC_RAW), a  nonsettable  clock  that  represents  monotonic  time
13          since—as  described   by   POSIX—"some   unspecified   point  in the
14          past".
15
16CLOCK_BOOTTIME (and likewise  CLOCK_BOOTTIME_ALARM),  a  nonsettable
17          clock  that is identical to CLOCK_MONOTONIC, except that it also in‐
18          cludes any time that the system is suspended.
19
20       Thus, the processes in a time namespace share per-namespace values  for
21       these  clocks.   This  affects  various APIs that measure against these
22       clocks, including: clock_gettime(2), clock_nanosleep(2),  nanosleep(2),
23       timer_settime(2), timerfd_settime(2), and /proc/uptime.
24
25       Currently,  the  only  way to create a time namespace is by calling un‐
26       share(2) with the CLONE_NEWTIME flag.  This call  creates  a  new  time
27       namespace  but does not place the calling process in the new namespace.
28       Instead, the calling process's subsequently created children are placed
29       in  the  new  namespace.  This allows clock offsets (see below) for the
30       new namespace to be set before the first process is placed in the name‐
31       space.  The /proc/pid/ns/time_for_children symbolic link shows the time
32       namespace in which the children of  a  process  will  be  created.   (A
33       process  can  use  a  file descriptor opened on this symbolic link in a
34       call to setns(2) in order to move into the namespace.)
35
36   /proc/pid/timens_offsets
37       Associated with each time namespace are offsets, expressed with respect
38       to  the initial time namespace, that define the values of the monotonic
39       and boot-time clocks in that namespace.  These offsets are exposed  via
40       the  file  /proc/pid/timens_offsets.  Within this file, the offsets are
41       expressed as lines consisting of three space-delimited fields:
42
43           <clock-id> <offset-secs> <offset-nanosecs>
44
45       The clock-id is a string that identifies the clock  whose  offsets  are
46       being  shown.   This field is either monotonic, for CLOCK_MONOTONIC, or
47       boottime, for CLOCK_BOOTTIME.  The remaining fields express the  offset
48       (seconds plus nanoseconds) for the clock in this time namespace.  These
49       offsets are expressed relative to the clock values in the initial  time
50       namespace.   The offset-secs value can be negative, subject to restric‐
51       tions noted below; offset-nanosecs is an unsigned value.
52
53       In the initial time namespace, the contents of the timens_offsets  file
54       are as follows:
55
56           $ cat /proc/self/timens_offsets
57           monotonic           0         0
58           boottime            0         0
59
60       In  a  new  time  namespace that has had no member processes, the clock
61       offsets can be modified by writing newline-terminated  records  of  the
62       same  form to the timens_offsets file.  The file can be written to mul‐
63       tiple times, but after the first process has been created in or has en‐
64       tered the namespace, write(2)s on this file fail with the error EACCES.
65       In order to write to the timens_offsets file, a process must  have  the
66       CAP_SYS_TIME  capability in the user namespace that owns the time name‐
67       space.
68
69       Writes to the timens_offsets file can fail with the following errors:
70
71       EINVAL An offset-nanosecs value is greater than 999,999,999.
72
73       EINVAL A clock-id value is not valid.
74
75       EPERM  The caller does not have the CAP_SYS_TIME capability.
76
77       ERANGE An offset-secs value is out of range.  In particular;
78
79offset-secs can't be set to a value which would make the cur‐
80                 rent  time  on the corresponding clock inside the namespace a
81                 negative value; and
82
83offset-secs can't be set to a value such that the time on the
84                 corresponding clock inside the namespace would exceed half of
85                 the value of the kernel constant KTIME_SEC_MAX  (this  limits
86                 the clock value to a maximum of approximately 146 years).
87
88       In  a  new  time  namespace  created by unshare(2), the contents of the
89       timens_offsets file are inherited from the time namespace of the creat‐
90       ing process.
91

NOTES

93       Use  of  time  namespaces requires a kernel that is configured with the
94       CONFIG_TIME_NS option.
95
96       Note that time namespaces do not virtualize the  CLOCK_REALTIME  clock.
97       Virtualization  of this clock was avoided for reasons of complexity and
98       overhead within the kernel.
99
100       For compatibility with  the  initial  implementation,  when  writing  a
101       clock-id  to the /proc/pid/timens_offsets file, the numerical values of
102       the IDs can be written instead of the symbolic names show above;  i.e.,
103       1  instead  of  monotonic, and 7 instead of boottime.  For readability,
104       the use of the symbolic names over the numbers is preferred.
105
106       The motivation for adding time namespaces was to  allow  the  monotonic
107       and boot-time clocks to maintain consistent values during container mi‐
108       gration and checkpoint/restore.
109

EXAMPLES

111       The following shell session demonstrates the operation  of  time  name‐
112       spaces.   We begin by displaying the inode number of the time namespace
113       of a shell in the initial time namespace:
114
115           $ readlink /proc/$$/ns/time
116           time:[4026531834]
117
118       Continuing in the initial time namespace, we display the system  uptime
119       using  uptime(1)  and  use  the  clock_times  example  program shown in
120       clock_getres(2) to display the values of various clocks:
121
122           $ uptime --pretty
123           up 21 hours, 17 minutes
124           $ ./clock_times
125           CLOCK_REALTIME : 1585989401.971 (18356 days +  8h 36m 41s)
126           CLOCK_TAI      : 1585989438.972 (18356 days +  8h 37m 18s)
127           CLOCK_MONOTONIC:      56338.247 (15h 38m 58s)
128           CLOCK_BOOTTIME :      76633.544 (21h 17m 13s)
129
130       We then use unshare(1) to create a time namespace and execute a bash(1)
131       shell.   From  the new shell, we use the built-in echo command to write
132       records to  the  timens_offsets  file  adjusting  the  offset  for  the
133       CLOCK_MONOTONIC clock forward 2 days and the offset for the CLOCK_BOOT‐
134       TIME clock forward 7 days:
135
136           $ PS1="ns2# " sudo unshare -T -- bash --norc
137           ns2# echo "monotonic $((2*24*60*60)) 0" > /proc/$$/timens_offsets
138           ns2# echo "boottime  $((7*24*60*60)) 0" > /proc/$$/timens_offsets
139
140       Above, we started the bash(1) shell with the --norc option so  that  no
141       start-up  scripts  were executed.  This ensures that no child processes
142       are created from the shell before  we  have  a  chance  to  update  the
143       timens_offsets file.
144
145       We  then use cat(1) to display the contents of the timens_offsets file.
146       The execution of cat(1) creates the first process in the new time name‐
147       space,  after  which further attempts to update the timens_offsets file
148       produce an error.
149
150           ns2# cat /proc/$$/timens_offsets
151           monotonic      172800         0
152           boottime       604800         0
153           ns2# echo "boottime $((9*24*60*60)) 0" > /proc/$$/timens_offsets
154           bash: echo: write error: Permission denied
155
156       Continuing  in  the  new  namespace,  we  execute  uptime(1)  and   the
157       clock_times example program:
158
159           ns2# uptime --pretty
160           up 1 week, 21 hours, 18 minutes
161           ns2# ./clock_times
162           CLOCK_REALTIME : 1585989457.056 (18356 days +  8h 37m 37s)
163           CLOCK_TAI      : 1585989494.057 (18356 days +  8h 38m 14s)
164           CLOCK_MONOTONIC:     229193.332 (2 days + 15h 39m 53s)
165           CLOCK_BOOTTIME :     681488.629 (7 days + 21h 18m  8s)
166
167       From  the  above  output,  we  can see that the monotonic and boot-time
168       clocks have different values in the new time namespace.
169
170       Examining the /proc/pid/ns/time and /proc/pid/ns/time_for_children sym‐
171       bolic  links,  we  see  that  the shell is a member of the initial time
172       namespace, but its children are created in the new namespace.
173
174           ns2# readlink /proc/$$/ns/time
175           time:[4026531834]
176           ns2# readlink /proc/$$/ns/time_for_children
177           time:[4026532900]
178           ns2# readlink /proc/self/ns/time   # Creates a child process
179           time:[4026532900]
180
181       Returning to the shell in the initial time namespace, we see  that  the
182       monotonic  and  boot-time  clocks  are unaffected by the timens_offsets
183       changes that were made in the other time namespace:
184
185           $ uptime --pretty
186           up 21 hours, 19 minutes
187           $ ./clock_times
188           CLOCK_REALTIME : 1585989401.971 (18356 days +  8h 38m 51s)
189           CLOCK_TAI      : 1585989438.972 (18356 days +  8h 39m 28s)
190           CLOCK_MONOTONIC:      56338.247 (15h 41m  8s)
191           CLOCK_BOOTTIME :      76633.544 (21h 19m 23s)
192

SEE ALSO

194       nsenter(1), unshare(1), clock_settime(2), setns(2),  unshare(2),  name‐
195       spaces(7), time(7)
196
197
198
199Linux man-pages 6.05              2023-03-12                time_namespaces(7)
Impressum