Module Name: src
Committed By: jruoho
Date: Sun Apr 11 06:50:30 UTC 2010
Modified Files:
src/share/man/man9: sysctl.9
Log Message:
Document the CTLTYPEs. In addition, split some paragraphs to make the page
less exhaustive to read.
To generate a diff of this commit:
cvs rdiff -u -r1.14 -r1.15 src/share/man/man9/sysctl.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/sysctl.9
diff -u src/share/man/man9/sysctl.9:1.14 src/share/man/man9/sysctl.9:1.15
--- src/share/man/man9/sysctl.9:1.14 Wed Apr 8 12:50:00 2009
+++ src/share/man/man9/sysctl.9 Sun Apr 11 06:50:30 2010
@@ -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
