diff options
Diffstat (limited to 'man7/time_namespaces.7')
| -rw-r--r-- | man7/time_namespaces.7 | 56 |
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 |