On 2004-04-09 wrstuden@NetBSD.org wrote:

> What you propose means going back to having the info in two places, and
> revisiting all of the issues we had before.

  You do not need to compile the info into sysctl to have sysctl report
it.  Provide a simple text file that looks something like this:
foo.bar:
Short description (one line)
Long description

foo.stuff.*:
Short/long description of what nodes under foo.stuff mean

foo.stuff.*.a:
Description of the a node for each node under foo.suff

  Install this file in a directory in SYSCTLDOC or such and sysctl can
load the files and use them to describe existing nodes.  You can even
write a simple script to generate the equivalent section of the man page.
Something is seriously wrong if you can't tell what a sysctl node means
with basic regular expressions before it is actually created.

> > >i'd like to point out, again, that this is an option.
> >
> > As was already pointed out, "this is an option" is not an interesting
> > point. It is by essence something that users will become very aware of,
> > and it is thus not a feature that can just come and go depending on the
> > available amount of memory of the machine and the mood or habits of the
> > person compiling the kernels for it.
>
> Oh, come on! :-) If users become aware of this and they decide they want
> it, that means they feel it is more important than the X k of memory it
> costs. I'm accepting Andrew's analysis that as we add more descriptions we
> may grow from the ~5k noted so far.

  "If you want sysctl descriptions, include option X or grep the source."

  5k and growing is a high cost for mindless repetition like the example
below.  Actual documentation would take more space, and should be
available.  I think the idea of having sysctl able to document the nodes
is a good idea, but it should be actual documentation and it should be in
userland.

> > >        /* SYSCTL_DESCR: kern.securelevel: System security level */
> >
> > Why not? I would even not mind at all to see semantically equivalent
> > text appended to a man page or any other form of database, instead of
> > right inside the kernel source.
> >
> > Another point is that most variables are already very often
> > self-documenting and unless you are going to add big descriptions the
> > user will not win much. The example you give is particularly
> > well-chosen in that respect.
> >
> > Another thing I pointed out is that if we do this with sysctl, why not
> > do it with event counters, or with filesystems (there aren't that many
> > after all), or with system calls? I must say that I much more often
> > need to know what a system call does than a sysctl variable. And they
> > can also come and go through lkms.
>
> Actually, we kinda have done it with file systems. Way back when, you
> picked a file system for mounting by number. Now you pick it by name.

  Sysctl nodes already have names.  Names as identifiers make sense
because it is much easier to generate a unique name in isolation than it
is to generate a unique small integer, and you get a small bit of self
documentation as well or at least a memory jog.  Anything more should be
in userland.

Matthew Orgass
darkstar@city-net.com