summaryrefslogtreecommitdiffstats
path: root/man7/time_namespaces.7
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man7/time_namespaces.756
1 files changed, 28 insertions, 28 deletions
diff --git a/man7/time_namespaces.7 b/man7/time_namespaces.7
index 6e29996..4c85001 100644
--- a/man7/time_namespaces.7
+++ b/man7/time_namespaces.7
@@ -3,7 +3,7 @@
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\"
-.TH time_namespaces 7 2023-03-12 "Linux man-pages 6.05.01"
+.TH time_namespaces 7 2023-10-31 "Linux man-pages 6.7"
.SH NAME
time_namespaces \- overview of Linux time namespaces
.SH DESCRIPTION
@@ -23,7 +23,7 @@ described by POSIX\[em]"some unspecified point in the past".
a nonsettable clock that is identical to
.BR CLOCK_MONOTONIC ,
except that it also includes any time that the system is suspended.
-.PP
+.P
Thus, the processes in a time namespace share per-namespace values
for these clocks.
This affects various APIs that measure against these clocks, including:
@@ -34,7 +34,7 @@ This affects various APIs that measure against these clocks, including:
.BR timerfd_settime (2),
and
.IR /proc/uptime .
-.PP
+.P
Currently, the only way to create a time namespace is by calling
.BR unshare (2)
with the
@@ -66,13 +66,13 @@ These offsets are exposed via the file
Within this file,
the offsets are expressed as lines consisting of
three space-delimited fields:
-.PP
+.P
.in +4n
.EX
<clock-id> <offset-secs> <offset-nanosecs>
.EE
.in
-.PP
+.P
The
.I clock-id
is a string that identifies the clock whose offsets are being shown.
@@ -93,11 +93,11 @@ The
value can be negative, subject to restrictions noted below;
.I offset-nanosecs
is an unsigned value.
-.PP
+.P
In the initial time namespace, the contents of the
.I timens_offsets
file are as follows:
-.PP
+.P
.in +4n
.EX
$ \fBcat /proc/self/timens_offsets\fP
@@ -105,7 +105,7 @@ monotonic 0 0
boottime 0 0
.EE
.in
-.PP
+.P
In a new time namespace that has had no member processes,
the clock offsets can be modified by writing newline-terminated
records of the same form to the
@@ -121,7 +121,7 @@ In order to write to the
file, a process must have the
.B CAP_SYS_TIME
capability in the user namespace that owns the time namespace.
-.PP
+.P
Writes to the
.I timens_offsets
file can fail with the following errors:
@@ -158,7 +158,7 @@ inside the namespace would exceed half of the value of the kernel constant
.B KTIME_SEC_MAX
(this limits the clock value to a maximum of approximately 146 years).
.RE
-.PP
+.P
In a new time namespace created by
.BR unshare (2),
the contents of the
@@ -168,13 +168,13 @@ file are inherited from the time namespace of the creating process.
Use of time namespaces requires a kernel that is configured with the
.B CONFIG_TIME_NS
option.
-.PP
+.P
Note that time namespaces do not virtualize the
.B CLOCK_REALTIME
clock.
Virtualization of this clock was avoided for reasons of complexity
and overhead within the kernel.
-.PP
+.P
For compatibility with the initial implementation, when writing a
.I clock-id
to the
@@ -185,7 +185,7 @@ instead of the symbolic names show above; i.e., 1 instead of
and 7 instead of
.IR boottime .
For readability, the use of the symbolic names over the numbers is preferred.
-.PP
+.P
The motivation for adding time namespaces was to allow
the monotonic and boot-time clocks to maintain consistent values
during container migration and checkpoint/restore.
@@ -193,14 +193,14 @@ during container migration and checkpoint/restore.
The following shell session demonstrates the operation of time namespaces.
We begin by displaying the inode number of the time namespace
of a shell in the initial time namespace:
-.PP
+.P
.in +4n
.EX
$ \fBreadlink /proc/$$/ns/time\fP
time:[4026531834]
.EE
.in
-.PP
+.P
Continuing in the initial time namespace, we display the system uptime using
.BR uptime (1)
and use the
@@ -208,7 +208,7 @@ and use the
example program shown in
.BR clock_getres (2)
to display the values of various clocks:
-.PP
+.P
.in +4n
.EX
$ \fBuptime \-\-pretty\fP
@@ -220,7 +220,7 @@ CLOCK_MONOTONIC: 56338.247 (15h 38m 58s)
CLOCK_BOOTTIME : 76633.544 (21h 17m 13s)
.EE
.in
-.PP
+.P
We then use
.BR unshare (1)
to create a time namespace and execute a
@@ -236,7 +236,7 @@ clock forward 2 days
and the offset for the
.B CLOCK_BOOTTIME
clock forward 7 days:
-.PP
+.P
.in +4n
.EX
$ \fBPS1="ns2# " sudo unshare \-T \-\- bash \-\-norc\fP
@@ -244,7 +244,7 @@ ns2# \fBecho "monotonic $((2*24*60*60)) 0" > /proc/$$/timens_offsets\fP
ns2# \fBecho "boottime $((7*24*60*60)) 0" > /proc/$$/timens_offsets\fP
.EE
.in
-.PP
+.P
Above, we started the
.BR bash (1)
shell with the
@@ -254,7 +254,7 @@ This ensures that no child processes are created from the
shell before we have a chance to update the
.I timens_offsets
file.
-.PP
+.P
We then use
.BR cat (1)
to display the contents of the
@@ -266,7 +266,7 @@ creates the first process in the new time namespace,
after which further attempts to update the
.I timens_offsets
file produce an error.
-.PP
+.P
.in +4n
.EX
ns2# \fBcat /proc/$$/timens_offsets\fP
@@ -276,13 +276,13 @@ ns2# \fBecho "boottime $((9*24*60*60)) 0" > /proc/$$/timens_offsets\fP
bash: echo: write error: Permission denied
.EE
.in
-.PP
+.P
Continuing in the new namespace, we execute
.BR uptime (1)
and the
.I clock_times
example program:
-.PP
+.P
.in +4n
.EX
ns2# \fBuptime \-\-pretty\fP
@@ -294,17 +294,17 @@ CLOCK_MONOTONIC: 229193.332 (2 days + 15h 39m 53s)
CLOCK_BOOTTIME : 681488.629 (7 days + 21h 18m 8s)
.EE
.in
-.PP
+.P
From the above output, we can see that the monotonic
and boot-time clocks have different values in the new time namespace.
-.PP
+.P
Examining the
.IR /proc/ pid /ns/time
and
.IR /proc/ pid /ns/time_for_children
symbolic links, we see that the shell is a member of the initial time
namespace, but its children are created in the new namespace.
-.PP
+.P
.in +4n
.EX
ns2# \fBreadlink /proc/$$/ns/time\fP
@@ -315,13 +315,13 @@ ns2# \fBreadlink /proc/self/ns/time\fP # Creates a child process
time:[4026532900]
.EE
.in
-.PP
+.P
Returning to the shell in the initial time namespace,
we see that the monotonic and boot-time clocks
are unaffected by the
.I timens_offsets
changes that were made in the other time namespace:
-.PP
+.P
.in +4n
.EX
$ \fBuptime \-\-pretty\fP