Hello Andrei,
On 4/7/20 5:23 AM, Andrei Vagin wrote:
> Hi Michael,
>
> The man page looks good to me. A few comments are inline.
Thanks for looking the page over!
> On Sat, Apr 04, 2020 at 01:08:50PM +0200, Michael Kerrisk (man-pages) wrote:
>> Hello Dmitry, Andrei, et al.
>>
>> I have written a manual page to document time namespaces.
>> Could you please take a look and let me know of any
>> corrections, improvements, etc.
>>
>> The rendered page is shown below. Th epage source is at the foot of
>> this mail.
>>
>> Thanks,
>>
>> Michael
>>
>>
>> NAME
>> time_namespaces - overview of Linux time namespaces
>>
>> DESCRIPTION
>> Time namespaces virtualize the values of two system clocks:
>>
>> · CLOCK_MONOTONIC (and likewise CLOCK_MONOTONIC_COARSE and
>> CLOCK_MONOTONIC_RAW), a nonsettable clock that represents mono‐
>> tonic time since—as described by POSIX—"some unspecified
>> point in the past".
>>
>> · CLOCK_BOOTTIME (and likewise CLOCK_BOOTTIME_ALARM), a clock that
>> is identical to CLOCK_MONOTONIC, except that it also includes
>> any time that the system is suspended.
>>
>> Thus, the processes in a time namespace share per-namespace values
>> for these clocks. This affects various APIs that measure against
>> these clocks, including: clock_nanosleep(2), nanosleep(2),
>> clock_gettime(2), and /proc/uptime.
>
> timer_settime, timerfd_settime
Added.
>> Currently, the only way to create a time namespace is by calling
>> unshare(2) with the CLONE_NEWTIME flag. This call creates a new
>> time namespace but does 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 off‐
>> sets (see below) for the new namespace to be set before the first
>> process is placed in the namespace. The
>> /proc/[pid]/ns/time_for_children symbolic link shows the time
>> namespace in which the children of a process will be created.
>
> We can mention that the current process can enter the namespace if it
> call setns on /proc/self/ns/time_for_children.
Yes, thanks. I overlooked that, and I was puzzled about how setns() could
be useful before the first process was created in a time NS.
I added:
(A process can use a file descriptor opened on this symbolic
link in a call to setns(2) in order to move into the namespace.)
>> /proc/PID/timens_offsets
>> Associated with each time namespace are offsets, expressed with
>> respect to the initial time namespace, that define the values of
>> the monotonic and boot clocks in that namespace. These offsets
>> are exposed via the file /proc/PID/timens_offsets. Within this
>> file, the offsets are expressed as lines consisting of three
>> space-delimited fields:
>>
>> <clock-id> <offset-secs> <offset-nanosecs>
>>
>> The clock-id identifies the clock whose offsets are being shown.
>> This field is either 1, for CLOCK_MONOTONIC, or 7, for CLOCK_BOOT‐
>> TIME. 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. In the initial time namespace, the contents of this
>> file are as follows:
>
> I think we can mention that offset-secs can be negative, but
> offset-nanosleep has to be 0 or positive.
Thanks. See my upcoming reply to Thomas.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
