[src/trunk]: src/share/man/man9 Document the CTLTYPEs. In addition, split som...

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/d7a6181f7b5b
branches:  trunk
changeset: 753820:d7a6181f7b5b
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Sun Apr 11 06:50:30 2010 +0000

description:
Document the CTLTYPEs. In addition, split some paragraphs to make the page
less exhaustive to read.

diffstat:

 share/man/man9/sysctl.9 |  69 +++++++++++++++++++++++++++++++++++-------------
 1 files changed, 50 insertions(+), 19 deletions(-)

diffs (173 lines):

diff -r 0d329bc02d67 -r d7a6181f7b5b share/man/man9/sysctl.9
--- a/share/man/man9/sysctl.9   Sun Apr 11 06:36:25 2010 +0000
+++ b/share/man/man9/sysctl.9   Sun Apr 11 06:50:30 2010 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sysctl.9,v 1.14 2009/04/08 12:50:00 joerg Exp $
+.\"    $NetBSD: sysctl.9,v 1.15 2010/04/11 06:50:30 jruoho Exp $
 .\"
 .\" Copyright (c) 2004 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd August 15, 2008
+.Dd April 11, 2010
 .Dt SYSCTL 9
 .Os
 .Sh NAME
@@ -129,6 +129,7 @@
 .Fn sysctl_lookup ,
 or by any helper function will be done with effective superuser
 privileges).
+.Pp
 The
 .Fa oldp
 and
@@ -160,20 +161,21 @@
 long, which is to be located in kernel space, in order to determine
 which function to call to handle the specific request.
 .Pp
+The following algorithm is used by
 .Fn sysctl_dispatch
-uses the following algorithm to determine the function to call:
+to determine the function to call:
 .Pp
-.Bl -bullet
+.Bl -bullet -offset indent
 .It
 Scan the tree using
-.Fn sysctl_locate
+.Fn sysctl_locate .
 .It
 If the node returned has a
 .Dq helper
-function, call it
+function, call it.
 .It
 If the requested node was found but has no function, call
-.Fn sysctl_lookup
+.Fn sysctl_lookup .
 .It
 If the node was not found and
 .Fa name
@@ -182,11 +184,11 @@
 .Fn sysctl_create ,
 or
 .Fn sysctl_destroy ,
-call the appropriate function
+call the appropriate function.
 .It
 If none of these options applies and no other error was yet recorded,
 return
-.Er EOPNOTSUPP
+.Er EOPNOTSUPP .
 .Pp
 .El
 The
@@ -237,8 +239,9 @@
 .Dv NULL ,
 the main tree will be used.
 .Pp
+The
 .Fn sysctl_locate
-scans a tree for the node most specific to a request.
+function scans a tree for the node most specific to a request.
 If the pointer referenced by
 .Fa rnode
 is not
@@ -281,6 +284,7 @@
 .Dv CTL_DESTROY
 when destroying
 a node.
+.Pp
 The
 .Fa newp
 and
@@ -312,7 +316,9 @@
 .Fa log
 argument is not
 .Dv NULL ,
-a sysctllog structure will be allocated and the pointer referenced
+a
+.Em sysctllog
+structure will be allocated and the pointer referenced
 will be changed to address it.
 The same log may be used for any number of nodes, provided they are
 all inserted into the same tree.
@@ -321,6 +327,7 @@
 .Fn sysctl_teardown )
 without the need for any record
 keeping on the caller's part.
+.Pp
 The
 .Fa cflags
 argument is currently unused and must be zero.
@@ -353,12 +360,22 @@
 field, and the current value for
 .Dv SYSCTL_VERSION
 is added in.
-Note: the
-.Dv CTLFLAG_PERMANENT
-flag can only be set from SYSCTL setup routines (see
-.Sx SETUP FUNCTIONS )
-as called by
-.Fn sysctl_init .
+The following types are defined:
+.Bl -tag -width ".Dv CTLTYPE_STRING    " -offset indent
+.It Dv CTLTYPE_NODE
+A node intended to be a parent for other nodes.
+.It Dv CTLTYPE_INT
+A signed integer.
+.It Dv CTLTYPE_STRING
+A NUL-terminated string.
+.It Dv CTLTYPE_QUAD
+An unsigned 64-bit integer.
+.It Dv CTLTYPE_STRUCT
+A structure.
+.It Dv CTLTYPE_BOOL
+A boolean.
+.El
+.Pp
 The
 .Fa namep
 argument is copied into the
@@ -371,7 +388,18 @@
 will be copied if the
 .Dv CTLFLAG_OWNDESC
 flag is set, and will be used as the node's description.
-Note: if
+.Pp
+Two additional remarks:
+.Bl -enum -offset indent
+.It
+The
+.Dv CTLFLAG_PERMANENT
+flag can only be set from SYSCTL setup routines (see
+.Sx SETUP FUNCTIONS )
+as called by
+.Fn sysctl_init .
+.It
+If
 .Fn sysctl_destroyv
 attempts to delete a node that does not own its own description (and
 is not marked as permanent), but the deletion fails, the description
@@ -380,6 +408,7 @@
 will set the
 .Dv CTLFLAG_OWNDESC
 flag.
+.El
 .Pp
 The
 .Fa func
@@ -564,7 +593,9 @@
 The SYSCTL lock must be held when calling this function.
 .Pp
 .Fn sysctl_teardown
-unwinds a sysctllog and deletes the nodes in the opposite order in
+unwinds a
+.Em sysctllog
+and deletes the nodes in the opposite order in
 which they were created.
 .Pp
 .Fn old_sysctl