kern.clockrate documentation patch

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

kern.clockrate documentation patch

Amit Kulkarni
Hi,

I wanted to know the value of tick, went to man.openbsd.org, and got https://man.openbsd.org/tick

While the answer provided on this page below is accurate, IMHO it is not useful. I had to do a grep on "tick" for the kern.clockrate sysctl. Something like the below would be better.

Thanks

diff --git man9/hz.9 man9/hz.9
index a319266e518..ac5e8f60850 100644
--- man9/hz.9
+++ man9/hz.9
@@ -79,11 +79,11 @@ may be used to skew this increment, but by no more
 than ten times
 .Va tickadj .
 .Pp
-Those systems variables are available as a struct clockinfo from
-.Xr sysctl 2 .
+These system variables are available as kern.clockrate from
+.Xr sysctl 8 .
 .Sh SEE ALSO
 .Xr adjtime 2 ,
 .Xr clock_getres 2 ,
-.Xr sysctl 2 ,
+.Xr sysctl 8 ,
 .Xr hardclock 9 ,
 .Xr microtime 9

Reply | Threaded
Open this post in threaded view
|

Re: kern.clockrate documentation patch

Ted Unangst-6
Amit Kulkarni wrote:

> Hi,
>
> I wanted to know the value of tick, went to man.openbsd.org, and got https://man.openbsd.org/tick
>
> While the answer provided on this page below is accurate, IMHO it is not useful. I had to do a grep on "tick" for the kern.clockrate sysctl. Something like the below would be better.
>
> Thanks
>
> diff --git man9/hz.9 man9/hz.9
> index a319266e518..ac5e8f60850 100644
> --- man9/hz.9
> +++ man9/hz.9
> @@ -79,11 +79,11 @@ may be used to skew this increment, but by no more
>  than ten times
>  .Va tickadj .
>  .Pp
> -Those systems variables are available as a struct clockinfo from
> -.Xr sysctl 2 .
> +These system variables are available as kern.clockrate from
> +.Xr sysctl 8 .

This is meant to be programmer documentation, so I think it makes sense to
keep it referring to sysctl.2. However, it's a good point that you shouldn't
have to grep for clockinfo.

If we mention KERN_CLOCKRATE that makes searching faster and should allow
users to figure out kern.clockrate.


Index: hz.9
===================================================================
RCS file: /cvs/src/share/man/man9/hz.9,v
retrieving revision 1.8
diff -u -p -r1.8 hz.9
--- hz.9 12 Jan 2018 04:36:45 -0000 1.8
+++ hz.9 6 Jan 2019 19:07:27 -0000
@@ -79,7 +79,9 @@ may be used to skew this increment, but
 than ten times
 .Va tickadj .
 .Pp
-Those systems variables are available as a struct clockinfo from
+These system variables are available by reading
+.Va KERN_CLOCKRATE
+from
 .Xr sysctl 2 .
 .Sh SEE ALSO
 .Xr adjtime 2 ,

Reply | Threaded
Open this post in threaded view
|

Re: kern.clockrate documentation patch

Ingo Schwarze
In reply to this post by Amit Kulkarni
Hi,

Amit Kulkarni wrote on Sun, Jan 06, 2019 at 12:16:30PM -0600:

> I wanted to know the value of tick, went to man.openbsd.org,
> and got https://man.openbsd.org/tick
>
> While the answer provided on this page below is accurate,
> IMHO it is not useful. I had to do a grep on "tick" for
> the kern.clockrate sysctl. Something like the below would be better.

No, it wouldn't, for two reasons.

 1. hz(9) is a kernel manual page, so referencing the (low-level)
    system call manual (in section 2) which provides considerable
    detail that kernel hackers may need is better than referencing
    the (high-level) userland manual (in section 8) which doesn't
    even mention clockrate except below EXAMPLES.  That example
    could easily go away one day without hz(9) noticing.

 2. In general, sysctl(8) only documents how the sysctl(8) command
    line user interface works in general, but not the individual
    variables, not even for interactive or shell programming use.
    Individual variables are documented in sysctl(2) - both the
    numeric #defines and the textual names.

Whether to reference "struct clockinfo", "KERN_CLOCKRATE", or
"kern.clockrate" is a question of the colour of the bikeshed.
Looking in sysctl(2) for any of the three, you immediately find
the other two:

     KERN_CLOCKRATE (kern.clockrate)
             A struct clockinfo structure is returned.  This structure

And there aren't even false positives for any of the three in sysctl(2),
so it is impossible to miss the right place.

Besides, it kind of makes sense for the kernel manual to reference
the struct rather than the textual name, because i guess the struct
is what a kernel hacker will more often deal with than with the name.

People who are not kernel hackers rarely need to worry about about
ticks in the first place, but even they can readily find the
information in sysctl(2) with the existing text.

Yours,
  Ingo


> diff --git man9/hz.9 man9/hz.9
> index a319266e518..ac5e8f60850 100644
> --- man9/hz.9
> +++ man9/hz.9
> @@ -79,11 +79,11 @@ may be used to skew this increment, but by no more
>  than ten times
>  .Va tickadj .
>  .Pp
> -Those systems variables are available as a struct clockinfo from
> -.Xr sysctl 2 .
> +These system variables are available as kern.clockrate from
> +.Xr sysctl 8 .
>  .Sh SEE ALSO
>  .Xr adjtime 2 ,
>  .Xr clock_getres 2 ,
> -.Xr sysctl 2 ,
> +.Xr sysctl 8 ,
>  .Xr hardclock 9 ,
>  .Xr microtime 9
>

Reply | Threaded
Open this post in threaded view
|

Re: kern.clockrate documentation patch

Ingo Schwarze
In reply to this post by Ted Unangst-6
Hi Ted,

i only saw your reply after sending mine.

Ted Unangst wrote on Sun, Jan 06, 2019 at 02:10:40PM -0500:

> This is meant to be programmer documentation, so I think it makes sense to
> keep it referring to sysctl.2. However, it's a good point that you shouldn't
> have to grep for clockinfo.
>
> If we mention KERN_CLOCKRATE that makes searching faster and should allow
> users to figure out kern.clockrate.

Arguably, since

  $ man -O tag=struct_clockinfo 2 sysctl

works whereas

  $ man -O tag=clockinfo 2 sysctl

does not.  (However, now that i think about it, i think that
tag=clockinfo probably ought to work as well, and i have some ideas
how to make it work.)

Anyway, i'm not opposed to your version of the patch.  But if you decide
to commit it, please make it

  .Dv KERN_CLOCKRATE

because that's a #define'ed constant, not a placeholder where the user
has to substitute something else.

Yours,
  Ingo


> Index: hz.9
> ===================================================================
> RCS file: /cvs/src/share/man/man9/hz.9,v
> retrieving revision 1.8
> diff -u -p -r1.8 hz.9
> --- hz.9 12 Jan 2018 04:36:45 -0000 1.8
> +++ hz.9 6 Jan 2019 19:07:27 -0000
> @@ -79,7 +79,9 @@ may be used to skew this increment, but
>  than ten times
>  .Va tickadj .
>  .Pp
> -Those systems variables are available as a struct clockinfo from
> +These system variables are available by reading
> +.Va KERN_CLOCKRATE
> +from
>  .Xr sysctl 2 .
>  .Sh SEE ALSO
>  .Xr adjtime 2 ,
>

Reply | Threaded
Open this post in threaded view
|

Re: kern.clockrate documentation patch

Amit Kulkarni
On Sun, 6 Jan 2019 20:40:17 +0100
Ingo Schwarze <[hidden email]> wrote:

> Hi Ted,
>
> i only saw your reply after sending mine.
>
> Ted Unangst wrote on Sun, Jan 06, 2019 at 02:10:40PM -0500:
>
> > This is meant to be programmer documentation, so I think it makes sense to
> > keep it referring to sysctl.2. However, it's a good point that you shouldn't
> > have to grep for clockinfo.
> >
> > If we mention KERN_CLOCKRATE that makes searching faster and should allow
> > users to figure out kern.clockrate.
>
> Arguably, since
>
>   $ man -O tag=struct_clockinfo 2 sysctl
>
> works whereas
>
>   $ man -O tag=clockinfo 2 sysctl
>
> does not.  (However, now that i think about it, i think that
> tag=clockinfo probably ought to work as well, and i have some ideas
> how to make it work.)
>
> Anyway, i'm not opposed to your version of the patch.  But if you decide
> to commit it, please make it
>
>   .Dv KERN_CLOCKRATE
>
> because that's a #define'ed constant, not a placeholder where the user
> has to substitute something else.
>

Thanks for the clue stick and feedback!