RFC: time_namespaces(7) manual page

[Michael Kerrisk (man-pages)]

On 4/7/20 12:30 PM, Thomas Gleixner wrote:
> Andrei Vagin <avagin at gmail.com> writes:
>> On Sat, Apr 04, 2020 at 01:08:50PM +0200, Michael Kerrisk (man-pages) wrote:
>>>    /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.
> 
> I assume you meant offset-nanosecs :)
> 
> That aside, there are also limitations in place.
> 
>   1) Negative offsets which would offset time into negative space are
>      rejected, i.e. its enforced that
> 
>           now(CLOCK) + offset[CLOCK] >= 0
> 
>      This is necessary as the kernel expects and also enforces that time
>      cannot be negative.
> 
>   2) Positive offsets which would offset time above KTTIME_SEC_MAX / 2 are
>      rejected, i.e. it's enforced that
> 
>           now(CLOCK) + offset[CLOCK] <= KTIME_SEC_MAX / 2
> 
>      That is done to prevent that clocks wrap around if the offset would
>      bring it close enough to the wrap around point.
> 
>      The cutoff value is a pretty arbitrary choice (~146 years). So to
>      hit this you'd need a system which has an uptime of > 146 years,
>      which is pretty much unrealistic.

Thanks Thomas!

I've tried to capture this info, as well some other relevant errors
in the following text. Does it look okay?

       Writes  to  the  timens_offsets  file  can fail with the following
       errors:

       EINVAL An offset-nanosecs value is greater than 999,999,999.

       EINVAL A clock-id value is not valid.

       EPERM  The caller does not have the the CAP_SYS_TIME capability.

       ERANGE An offset-secs value is out of range.  In particular;

              · offset-secs can't be set to a value which would make  the
                current time on the corresponding clock inside the names‐
                pace a negative value; and

              · 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  KTIME_SEC_MAX
                (this  limits  the  clock  value to a maximum of approxi‐
                mately 146 years).

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/