diff options
Diffstat (limited to 'man7/time_namespaces.7')
| -rw-r--r-- | man7/time_namespaces.7 | 345 |
1 files changed, 0 insertions, 345 deletions
diff --git a/man7/time_namespaces.7 b/man7/time_namespaces.7 deleted file mode 100644 index 8a2817be5..000000000 --- a/man7/time_namespaces.7 +++ /dev/null @@ -1,345 +0,0 @@ -.\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" -.TH time_namespaces 7 (date) "Linux man-pages (unreleased)" -.SH NAME -time_namespaces \- overview of Linux time namespaces -.SH DESCRIPTION -Time namespaces virtualize the values of two system clocks: -.IP \[bu] 3 -.B CLOCK_MONOTONIC -(and likewise -.B CLOCK_MONOTONIC_COARSE -and -.BR CLOCK_MONOTONIC_RAW ), -a nonsettable clock that represents monotonic time since\[em]as -described by POSIX\[em]"some unspecified point in the past". -.IP \[bu] -.B CLOCK_BOOTTIME -(and likewise -.BR CLOCK_BOOTTIME_ALARM ), -a nonsettable clock that is identical to -.BR CLOCK_MONOTONIC , -except that it also includes any time that the system is suspended. -.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: -.BR clock_gettime (2), -.BR clock_nanosleep (2), -.BR nanosleep (2), -.BR timer_settime (2), -.BR timerfd_settime (2), -and -.IR /proc/uptime . -.P -Currently, the only way to create a time namespace is by calling -.BR unshare (2) -with the -.B CLONE_NEWTIME -flag. -This call creates a new time namespace but does -.I not -place the calling process in the new namespace. -Instead, the calling process's -subsequently created children are placed in the new namespace. -This allows clock offsets (see below) for the new namespace -to be set before the first process is placed in the namespace. -The -.IR /proc/ pid /ns/time_for_children -symbolic link shows the time namespace in which -the children of a process will be created. -(A process can use a file descriptor opened on -this symbolic link in a call to -.BR setns (2) -in order to move into the namespace.) -.\" -.SS \fI/proc/\fPpid\fI/timens_offsets\fP -Associated with each time namespace are offsets, -expressed with respect to the initial time namespace, -that define the values of the monotonic and -boot-time clocks in that namespace. -These offsets are exposed via the file -.IR /proc/ pid /timens_offsets . -Within this file, -the offsets are expressed as lines consisting of -three space-delimited fields: -.P -.in +4n -.EX -<clock-id> <offset-secs> <offset-nanosecs> -.EE -.in -.P -The -.I clock-id -is a string that identifies the clock whose offsets are being shown. -This field is either -.IR monotonic , -for -.BR CLOCK_MONOTONIC , -or -.IR boottime , -for -.BR CLOCK_BOOTTIME . -The remaining fields express the offset (seconds plus nanoseconds) for the -clock in this time namespace. -These offsets are expressed relative to the clock values in -the initial time namespace. -The -.I offset-secs -value can be negative, subject to restrictions noted below; -.I offset-nanosecs -is an unsigned value. -.P -In the initial time namespace, the contents of the -.I timens_offsets -file are as follows: -.P -.in +4n -.EX -$ \fBcat /proc/self/timens_offsets\fP -monotonic 0 0 -boottime 0 0 -.EE -.in -.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 -.I timens_offsets -file. -The file can be written to multiple times, -but after the first process has been created in or has entered the namespace, -.BR write (2)s -on this file fail with the error -.BR EACCES . -In order to write to the -.I timens_offsets -file, a process must have the -.B CAP_SYS_TIME -capability in the user namespace that owns the time namespace. -.P -Writes to the -.I timens_offsets -file can fail with the following errors: -.TP -.B EINVAL -An -.I offset-nanosecs -value is greater than 999,999,999. -.TP -.B EINVAL -A -.I clock-id -value is not valid. -.TP -.B EPERM -The caller does not have the -.B CAP_SYS_TIME -capability. -.TP -.B ERANGE -An -.I offset-secs -value is out of range. -In particular; -.RS -.IP \[bu] 3 -.I offset-secs -can't be set to a value which would make the current -time on the corresponding clock inside the namespace a negative value; and -.IP \[bu] -.I offset-secs -can't be set to a value such that the time on the corresponding clock -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 -.P -In a new time namespace created by -.BR unshare (2), -the contents of the -.I timens_offsets -file are inherited from the time namespace of the creating process. -.SH NOTES -Use of time namespaces requires a kernel that is configured with the -.B CONFIG_TIME_NS -option. -.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. -.P -For compatibility with the initial implementation, when writing a -.I clock-id -to the -.IR /proc/ pid /timens_offsets -file, the numerical values of the IDs can be written -instead of the symbolic names show above; i.e., 1 instead of -.IR monotonic , -and 7 instead of -.IR boottime . -For readability, the use of the symbolic names over the numbers is preferred. -.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. -.SH EXAMPLES -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: -.P -.in +4n -.EX -$ \fBreadlink /proc/$$/ns/time\fP -time:[4026531834] -.EE -.in -.P -Continuing in the initial time namespace, we display the system uptime using -.BR uptime (1) -and use the -.I clock_times -example program shown in -.BR clock_getres (2) -to display the values of various clocks: -.P -.in +4n -.EX -$ \fBuptime \-\-pretty\fP -up 21 hours, 17 minutes -$ \fB./clock_times\fP -CLOCK_REALTIME : 1585989401.971 (18356 days + 8h 36m 41s) -CLOCK_TAI : 1585989438.972 (18356 days + 8h 37m 18s) -CLOCK_MONOTONIC: 56338.247 (15h 38m 58s) -CLOCK_BOOTTIME : 76633.544 (21h 17m 13s) -.EE -.in -.P -We then use -.BR unshare (1) -to create a time namespace and execute a -.BR bash (1) -shell. -From the new shell, we use the built-in -.B echo -command to write records to the -.I timens_offsets -file adjusting the offset for the -.B CLOCK_MONOTONIC -clock forward 2 days -and the offset for the -.B CLOCK_BOOTTIME -clock forward 7 days: -.P -.in +4n -.EX -$ \fBPS1="ns2# " sudo unshare \-T \-\- bash \-\-norc\fP -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 -.P -Above, we started the -.BR bash (1) -shell with the -.B \-\-norc -option so that no start-up scripts were executed. -This ensures that no child processes are created from the -shell before we have a chance to update the -.I timens_offsets -file. -.P -We then use -.BR cat (1) -to display the contents of the -.I timens_offsets -file. -The execution of -.BR cat (1) -creates the first process in the new time namespace, -after which further attempts to update the -.I timens_offsets -file produce an error. -.P -.in +4n -.EX -ns2# \fBcat /proc/$$/timens_offsets\fP -monotonic 172800 0 -boottime 604800 0 -ns2# \fBecho "boottime $((9*24*60*60)) 0" > /proc/$$/timens_offsets\fP -bash: echo: write error: Permission denied -.EE -.in -.P -Continuing in the new namespace, we execute -.BR uptime (1) -and the -.I clock_times -example program: -.P -.in +4n -.EX -ns2# \fBuptime \-\-pretty\fP -up 1 week, 21 hours, 18 minutes -ns2# \fB./clock_times\fP -CLOCK_REALTIME : 1585989457.056 (18356 days + 8h 37m 37s) -CLOCK_TAI : 1585989494.057 (18356 days + 8h 38m 14s) -CLOCK_MONOTONIC: 229193.332 (2 days + 15h 39m 53s) -CLOCK_BOOTTIME : 681488.629 (7 days + 21h 18m 8s) -.EE -.in -.P -From the above output, we can see that the monotonic -and boot-time clocks have different values in the new time namespace. -.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. -.P -.in +4n -.EX -ns2# \fBreadlink /proc/$$/ns/time\fP -time:[4026531834] -ns2# \fBreadlink /proc/$$/ns/time_for_children\fP -time:[4026532900] -ns2# \fBreadlink /proc/self/ns/time\fP # Creates a child process -time:[4026532900] -.EE -.in -.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: -.P -.in +4n -.EX -$ \fBuptime \-\-pretty\fP -up 21 hours, 19 minutes -$ \fB./clock_times\fP -CLOCK_REALTIME : 1585989401.971 (18356 days + 8h 38m 51s) -CLOCK_TAI : 1585989438.972 (18356 days + 8h 39m 28s) -CLOCK_MONOTONIC: 56338.247 (15h 41m 8s) -CLOCK_BOOTTIME : 76633.544 (21h 19m 23s) -.EE -.in -.SH SEE ALSO -.BR nsenter (1), -.BR unshare (1), -.BR clock_settime (2), -.\" clone3() support for time namespaces is a work in progress -.\" .BR clone3 (2), -.BR setns (2), -.BR unshare (2), -.BR namespaces (7), -.BR time (7) |