A further though on /proc/PID/timens_offsets

A further though on /proc/PID/timens_offsets

[Michael Kerrisk (man-pages)]

Hello Dmitry, Andrei,

Quoting the draft time_namespaces manual page:

       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  off‐
       sets  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.

What was the reason for exposing numeric clock IDs in the
timens_offsets file? In API terms, that seems a little ugly.

I think it would have been much nicer if the clocks were defined
symbolically in this file. I.e., that reading the file would have
shown something like

monotonic    x    y
boottime     x    y

And that records similarly with symbolic clock names could have
been written to the file. Was there a reason not to do this?

Thanks,

Michael

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

Re: A further though on /proc/PID/timens_offsets

[Andrey Vagin]

On Tue, Apr 7, 2020 at 6:24 AM Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:

>        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.
>
> What was the reason for exposing numeric clock IDs in the
> timens_offsets file? In API terms, that seems a little ugly.
>
> I think it would have been much nicer if the clocks were defined
> symbolically in this file. I.e., that reading the file would have
> shown something like
>
> monotonic    x    y
> boottime     x    y
>
> And that records similarly with symbolic clock names could have
> been written to the file. Was there a reason not to do this?

No, there was not except that I haven't thought about this. I agree
that symbolic clock names looks nicer for humans, but numeric clock
IDs are a bit more convenient when we  need to set/read offsets from
code. This interface is in the released kernel, so I think we can't
change the format of the content of this file. But we can add support
of symbolic clock names for setting clock offsets. What do you think?

Thanks,
Andrei

Re: A further though on /proc/PID/timens_offsets

[Eric W. Biederman]

Andrey Vagin <avagin@openvz.org> writes:

> On Tue, Apr 7, 2020 at 6:24 AM Michael Kerrisk (man-pages)
> <mtk.manpages@gmail.com> wrote:
>
>>        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.
>>
>> What was the reason for exposing numeric clock IDs in the
>> timens_offsets file? In API terms, that seems a little ugly.
>>
>> I think it would have been much nicer if the clocks were defined
>> symbolically in this file. I.e., that reading the file would have
>> shown something like
>>
>> monotonic    x    y
>> boottime     x    y
>>
>> And that records similarly with symbolic clock names could have
>> been written to the file. Was there a reason not to do this?
>
> No, there was not except that I haven't thought about this. I agree
> that symbolic clock names looks nicer for humans, but numeric clock
> IDs are a bit more convenient when we  need to set/read offsets from
> code. This interface is in the released kernel, so I think we can't
> change the format of the content of this file. But we can add support
> of symbolic clock names for setting clock offsets. What do you think?

The rule is we can change things as long as userspace doesn't care.  For
very new interfaces like this it is possible there are few enough
userspace programs that nothing cares.

Do you know if someone is using this interface yet?

Eric

Re: A further though on /proc/PID/timens_offsets

[Andrey Vagin]

On Thu, Apr 9, 2020 at 2:35 PM Eric W. Biederman <ebiederm@xmission.com> wrote:
>
> Andrey Vagin <avagin@openvz.org> writes:
>
> > On Tue, Apr 7, 2020 at 6:24 AM Michael Kerrisk (man-pages)
> > <mtk.manpages@gmail.com> wrote:
> >
> >>        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.
> >>
> >> What was the reason for exposing numeric clock IDs in the
> >> timens_offsets file? In API terms, that seems a little ugly.
> >>
> >> I think it would have been much nicer if the clocks were defined
> >> symbolically in this file. I.e., that reading the file would have
> >> shown something like
> >>
> >> monotonic    x    y
> >> boottime     x    y
> >>
> >> And that records similarly with symbolic clock names could have
> >> been written to the file. Was there a reason not to do this?
> >
> > No, there was not except that I haven't thought about this. I agree
> > that symbolic clock names looks nicer for humans, but numeric clock
> > IDs are a bit more convenient when we  need to set/read offsets from
> > code. This interface is in the released kernel, so I think we can't
> > change the format of the content of this file. But we can add support
> > of symbolic clock names for setting clock offsets. What do you think?
>
> The rule is we can change things as long as userspace doesn't care.  For
> very new interfaces like this it is possible there are few enough
> userspace programs that nothing cares.
>
> Do you know if someone is using this interface yet?

CRIU has the support of time namespace, but these changes are in the
devel branch and have not been released yet.

I know two more project:
* The util-linux (unshare and nsenter tools):
https://github.com/karelzak/util-linux/commit/7f1f0584c24a77909a7c96e62e30f63f4c1b10ad
https://github.com/karelzak/util-linux/commit/ef0341c9be441b834848d260ba0dbeb47a20f7a3

The last release of util-linux was at the end of January, so these
changes have not been released.

* crun
https://github.com/containers/crun/commit/a669dc64f70f71423a0ee1bb977f2d77e473649a

These changes have been released in the crun v0.13.

All these projects only set offsets, so I think following the rule
that you described, we can start showing symbolic clock names and
accept both variants for setting offsets. If everyone agrees with
this, I can prepare a patch tomorrow.

Thanks,
Andrei

Re: A further though on /proc/PID/timens_offsets

[Michael Kerrisk (man-pages)]

Hello Andrei

On Fri, 10 Apr 2020 at 07:24, Andrey Vagin <avagin@openvz.org> wrote:
>
> On Thu, Apr 9, 2020 at 2:35 PM Eric W. Biederman <ebiederm@xmission.com> wrote:
> >
> > Andrey Vagin <avagin@openvz.org> writes:
> >
> > > On Tue, Apr 7, 2020 at 6:24 AM Michael Kerrisk (man-pages)
> > > <mtk.manpages@gmail.com> wrote:
> > >
> > >>        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.
> > >>
> > >> What was the reason for exposing numeric clock IDs in the
> > >> timens_offsets file? In API terms, that seems a little ugly.
> > >>
> > >> I think it would have been much nicer if the clocks were defined
> > >> symbolically in this file. I.e., that reading the file would have
> > >> shown something like
> > >>
> > >> monotonic    x    y
> > >> boottime     x    y
> > >>
> > >> And that records similarly with symbolic clock names could have
> > >> been written to the file. Was there a reason not to do this?
> > >
> > > No, there was not except that I haven't thought about this. I agree
> > > that symbolic clock names looks nicer for humans, but numeric clock
> > > IDs are a bit more convenient when we  need to set/read offsets from
> > > code. This interface is in the released kernel, so I think we can't
> > > change the format of the content of this file. But we can add support
> > > of symbolic clock names for setting clock offsets. What do you think?
> >
> > The rule is we can change things as long as userspace doesn't care.  For
> > very new interfaces like this it is possible there are few enough
> > userspace programs that nothing cares.
> >
> > Do you know if someone is using this interface yet?
>
> CRIU has the support of time namespace, but these changes are in the
> devel branch and have not been released yet.
>
> I know two more project:
> * The util-linux (unshare and nsenter tools):
> https://github.com/karelzak/util-linux/commit/7f1f0584c24a77909a7c96e62e30f63f4c1b10ad
> https://github.com/karelzak/util-linux/commit/ef0341c9be441b834848d260ba0dbeb47a20f7a3
>
> The last release of util-linux was at the end of January, so these
> changes have not been released.
>
> * crun
> https://github.com/containers/crun/commit/a669dc64f70f71423a0ee1bb977f2d77e473649a
>
> These changes have been released in the crun v0.13.
>
> All these projects only set offsets, so I think following the rule
> that you described, we can start showing symbolic clock names and
> accept both variants for setting offsets. If everyone agrees with
> this, I can prepare a patch tomorrow.

That would be great! Thank you!

Cheers,

Michael



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