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