Clean up this new manual page. This delta includes content and

whitespace changes, which should not be a problem because this
is only the second revision of the file and translators are
unlikely to have gotten started yet.

Reviewed by:	abial

1 files changed, 234 insertions, 173 deletions

diff --git a/share/man/man9/sysctl_add_oid.9 b/share/man/man9/sysctl_add_oid.9
index a4e5788aeb48..0a8476cae3d7 100644
--- a/share/man/man9/sysctl_add_oid.9
+++ b/share/man/man9/sysctl_add_oid.9
@@ -28,8 +28,8 @@
 .\" $FreeBSD$
 .\"
 .Dd Jul 15, 2000
-.Dt sysctl_add_oid 9
-.Os FreeBSD 5.0
+.Dt SYSCTL_ADD_OID 9
+.Os
 .Sh NAME
 .Nm sysctl_add_oid ,
 .Nm sysctl_remove_oid
@@ -177,221 +177,280 @@
 .Fa "char *descr"
 .Fc
 .Sh DESCRIPTION
-These two functions and set of macros allow to create and delete sysctl
-oids during runtime (e.g. during lifetime of a module). Alternative method,
+These functions and macros provide an interface
+for creating and deleting sysctl oids at runtime
+(e.g. during lifetime of a module).
+The alternative method,
 based on linker sets (see
 .Aq sys/linker_set.h
 and
-.Pa sys/kern/kern_sysctl.c
-for details), allows only to create and delete them on module load/unload.
+.\" XXX Manual pages should avoid referencing source files
+.Pa src/sys/kern/kern_sysctl.c
+for details), only allows creation and deletion
+on module load and unload respectively.
 .Pp
-Dynamic oids of type CTLTYPE_NODE are reusable, so that several
-code sections can create and delete them, but in reality they are allocated
-and freed based on their reference count. As a consequence, it's possible
-for two or more code sections to create partially overlapping trees that
-they both can use. It's not possible to create overlapping leaves, or
-to create different child type with the same parent and the same name as
-one of already existing children.
+Dynamic oids of type
+.Dv CTLTYPE_NODE
+are reusable
+so that several code sections can create and delete them,
+but in reality they are allocated and freed
+based on their reference count.
+As a consequence,
+it is possible for two or more code sections
+to create partially overlapping trees that they both can use.
+It is not possible to create overlapping leaves,
+nor to create different child types with the name name and parent.
 .Pp
-Newly created oids are connected to their parent nodes. In all functions
-and macros one of the required parameters is
-.Va "struct sysctl_oid_list *parent"
-that points to the list of children of the parent node.
+Newly created oids are connected to their parent nodes.
+In all these functions and macros
+(with the exception of
+.Fn sysctl_remove_oid ) ,
+one of the required parameters is
+.Fa parent ,
+which points to the head of the parent's list of children.
 .Pp
-In case of connecting to already existing static oid (most top level
-categories are created statically), this pointer can be obtained by
-.Fn SYSCTL_STATIC_CHILDREN "NAME"
-macro, where
-.Fa "NAME"
-is name of the parent oid of type CTLTYPE_NODE (the name displayed by
-.Xr sysctl 8
-preceded by underscore, and with all dots replaced by underscores).
+Most top level categories are created statically.
+When connecting to existing static oids,
+this pointer can be obtained with the
+.Fn SYSCTL_STATIC_CHILDREN
+macro, where the
+.Fa OID_NAME
+argumwent is name of the parent oid of type
+.Dv CTLTYPE_NODE
+(i.e. the name displayed by
+.Xr sysctl 8 ,
+preceded by underscore, and with all dots replaced with underscores).
 .Pp
-In case of connecting to already existing dynamic oid, this pointer
-can be obtained through
-.Fn SYSCTL_CHILDREN "struct sysctl_oid *oidp"
-macro, where
-.Fa "oidp"
-points to the parent oid of type CTLTYPE_NODE.
-
+When connecting to an existing dynamic oid, this pointer
+can be obtained with the
+.Fn SYSCTL_CHILDREN
+macro, where the
+.Fa oidp
+argument points to the parent oid of type
+.Dv CTLTYPE_NODE .
+.Pp
+The
 .Fn sysctl_add_oid
-is a function to create raw oids of any type. If the oid was successfuly
-created, the function returns a pointer to it, otherwise it returns NULL.
-Many of the arguments that
+function creates raw oids of any type.
+If the oid is successfuly created,
+the function returns a pointer to it;
+otherwise it returns
+.Dv NULL .
+Many of the arguments for
 .Fn sysctl_add_oid
-takes are common also with the macros. The arguments are as follows:
+are common to the macros.
+The arguments are as follows:
 .Bl -tag -width handler
-.It ctx
-The pointer to (optional) sysctl context, or NULL. See
+.It Fa ctx
+A pointer to an optional sysctl context, or
+.Dv NULL .
+See
 .Xr sysctl_ctx_init 9
-for details. It is strongly advised that programmers use
-contexts to organize the dynamic oids they create, unless special
-creation and deletion sequences are required. If
-.Fa "ctx"
-is not NULL, the newly created oid will be added to this context as
-its first entry.
-.It parent
-The pointer to
-.Va sysctl_oid_list
-structure containing all parent's children.
-.It number
-The oid number that will be assigned to this oid. In almost all cases this
-should be set to
-.Va OID_AUTO
-which will result in assigning next available oid number.
-.It name
-Name of the oid. Newly created oid will contain copy of the name.
-.It kind
-The oid kind, specified as OR of type and access values defined in
+for details.
+Programmers are strongly advised to use contexts
+to organize the dynamic oids which they create,
+unless special creation and deletion sequences are required.
+If
+.Fa ctx
+is not
+.Dv NULL ,
+the newly created oid will be added to this context
+as its first entry.
+.It Fa parent
+A pointer to a
+.Li struct sysctl_oid_list ,
+which is the head of the parent's list of children.
+.It Fa number
+The oid number that will be assigned to this oid.
+In almost all cases this should be set to
+.Dv OID_AUTO ,
+which will result in the assignment of the next available oid number.
+.It Fa name
+The name of the oid.
+The newly created oid will contain a copy of the name.
+.It Fa kind
+The kind of oid,
+specified as a bitmask of the type and access values defined in the
 .Aq sys/sysctl.h
-header file. Oids created dynamically always have CTLTYPE_DYN flag set.
-.Pa access
-related flags specify whether this oid is read-only or read-write, and
-who may modify it (all users or superuser only).
-.It arg1
-points to any data that the oid should reference, or is set to NULL.
-.It arg2
-usually contains the information about size of
-.Fa "arg1"
-, or is set to 0.
-.It handler
-points to a function that is responsible for handling read and
-write requests to this oid. There are several standard handlers that
-support operations on nodes, integers, strings and opaque objects.
-It's possible also to define new handlers (cf.
+header file.
+Oids created dynamically always have the
+.Dv CTLTYPE_DYN
+flag set.
+Access flags specify whether this oid is read-only or read-write,
+and whether it may be modified by all users
+or by the supseruser only.
+.It Fa arg1
+A pointer to any data that the oid should reference, or
+.Dv NULL .
+.It Fa arg2
+The size of
+.Fa arg1 ,
+or 0 if
+.Fa arg1
+is
+.Dv NULL .
+.It Fa handler
+A pointer to the function
+that is responsible for handling read and write requests
+to this oid.
+There are several standard handlers
+that support operations on nodes,
+integers, strings and opaque objects.
+It is possible also to define new handlers using the
 .Fn SYSCTL_ADD_PROC
-macro).
-.It format
-Specifies the format of the oid in a symbolic way. This format is
-used as a hint by
+macro.
+.It Fa format
+A pointer to a string
+which specifies the format of the oid symbolically.
+This format is used as a hint by
 .Xr sysctl 8
-to apply proper data formatting for display purposes. Currently used
-format names are:
+to apply proper data formatting for display purposes.
+Currently used format names are:
 .Dq N
 for node, 
 .Dq A
 for
-.Pa "char *"
-,
+.Li "char *" ,
 .Dq I
 for
-.Pa "int"
-,
+.Li "int" ,
 .Dq IU
 for
-.Pa "unsigned int"
-,
+.Li "unsigned int" ,
 .Dq L
 for
-.Pa "long"
-,
+.Li "long" ,
 .Dq LU
 for
-.Pa "unsigned long"
+.Li "unsigned long"
 and
 .Dq S,TYPE
 for
-.Pa "struct TYPE"
+.Li "struct TYPE"
 structures.
-.It descr
-Textual description of the oid.
+.It Fa descr
+A pointer to a textual description of the oid.
 .El
 .Pp
-
+The
 .Fn sysctl_remove_oid
-removes dynamically created oid from the tree, optionally freeing
-its resources.  It takes the following arguments:
+function removes a dynamically created oid from the tree,
+optionally freeing its resources.
+It takes the following arguments:
 .Bl -tag -width recurse
-.It oidp
-pointer to the dynamic oid to be removed. If the oid is not dynamic,
-or NULL, the function returns EINVAL error code.
-.It del
-If set to non-zero,
+.It Fa oidp
+A pointer to the dynamic oid to be removed.
+If the oid is not dynamic, or the pointer is
+.Dv NULL ,
+the function returns
+.Er EINVAL .
+.It Fa del
+If non-zero,
 .Fn sysctl_remove_oid
-will try to free the oid's resources, when the reference count of the oid
-becomes zero. However, if
-.Va del
-is set to 0, the routine will only deregister oid from the tree, without
-freeing its resources. This case is useful when the caller wants later
-to rollback (possibly partially failed) deletion of many oids.
-.It recurse
-if set to non-zero, attempt to remove current node and all its children.
+will try to free the oid's resources
+when the reference count of the oid becomes zero.
+However, if
+.Fa del
+is set to 0,
+the routine will only deregister the oid from the tree,
+without freeing its resources.
+This behaviour is useful when the caller expects to rollback
+(possibly partially failed)
+deletion of many oids later.
+.It Fa recurse
+If non-zero, attempt to remove the node and all its children.
 If
 .Pa recurse
-is set to 0, attempt to remove node that contains any children will result
-in ENOTEMPTY error.
-
-\fBWARNING: use recursive delete with extreme caution! Normally it
-shouldn't be needed if you use contexts.\fR Contexts take care of
-tracking inter-dependencies between users of the tree. However, in some
-extreme cases it might be needed to remove part of the subtree no matter
-how it was created, in order to free some other resources. Be aware,
-though, that it may result in system panic if other code section still
-was using removed subtree.
+is set to 0,
+any attempt to remove a node that contains any children
+will result in a
+.Er ENOTEMPTY
+error.
+.Em "WARNING: use recursive deletion with extreme caution!"
+Normally it should not be needed if contexts are used.
+Contexts take care of tracking inter-dependencies
+between users of the tree.
+However, in some extreme cases it might be necessary
+to remove part of the subtree no matter how it was created,
+in order to free some other resources.
+Be aware, though, that this may result in a system
+.Xr panic 9
+if other code sections continue to use removed subtrees.
 .El
 .Pp
-Again, in most cases programmer should use contexts, as described in
-.Xr sysctl_ctx_init 9
-to keep track of created oids, and later to delete them in orderly fashion.
+.\" XXX sheldonh finished up to here
+Again, in most cases the programmer should use contexts,
+as described in
+.Xr sysctl_ctx_init 9 ,
+to keep track of created oids,
+and to delete them later in orderly fashion.
 .Pp
-There is a set of macros defined that helps to create oids of given type.
+There is a set of macros defined
+that helps to create oids of given type.
+.Bl -tag -width SYSCTL_ADD_STRINGXX
 They are as follows:
-.Pp
-.Fn SYSCTL_ADD_OID
-creates raw oid. This macro is functionally equivalent to
+.It Fn SYSCTL_ADD_OID
+creates a raw oid.
+This macro is functionally equivalent to the
 .Fn sysctl_add_oid
 function.
-.Pp
-.Fn SYSCTL_ADD_NODE
-creates oid of type CTLFLAG_NODE, to which you can add children oids.
-.Pp
-.Fn SYSCTL_ADD_STRING
-creates oid that handles a zero-terminated string.
-.Pp
-.Fn SYSCTL_ADD_INT
-creates oid that handles
-.Va int
+.It Fn SYSCTL_ADD_NODE
+creates an oid of type
+.Dv CTLTYPE_NODE ,
+to which child oids may be added.
+.It Fn SYSCTL_ADD_STRING
+creates an oid that handles a zero-terminated character string.
+.It Fn SYSCTL_ADD_INT
+creates an oid that handles an
+.Li int
 variable.
-.Pp
-.Fn SYSCTL_ADD_UINT
-creates oid that handles
-.Va unsigned int
+.It Fn SYSCTL_ADD_UINT
+creates an oid that handles an
+.Li unsigned int
 variable.
-.Pp
-.Fn SYSCTL_ADD_LONG
-creates oid that handles
-.Va long
+.It Fn SYSCTL_ADD_LONG
+creates an oid that handles a
+.Li long
 variable.
-.Pp
-.Fn SYSCTL_ADD_ULONG
-creates oid that handles
-.Va unsigned long
+.It Fn SYSCTL_ADD_ULONG
+creates an oid that handles an
+.Li unsigned long
 variable.
-.Pp
-.Fn SYSCTL_ADD_OPAQUE
-creates oid that handles any chunk of opaque data of specified size.
-.Pp
-.Fn SYSCTL_ADD_STRUCT
-creates oid that handles
-.Va "struct TYPE"
-structure. The
-.Pa format
+.It Fn SYSCTL_ADD_OPAQUE
+creates an oid that handles any chunk of opaque data
+of the size specified by the
+.Fa len
+argument,
+which is a pointer to a
+.Li "size_t *" .
+.It Fn SYSCTL_ADD_STRUCT
+creates an oid that handles a
+.Li "struct TYPE"
+structure.
+The
+.Fa format
 parameter will be set to
 .Dq S,TYPE
-to provide proper hints to
+to provide proper hints to the
 .Xr sysctl 8
 utlity.
-.Pp
-.Fn SYSCTL_ADD_PROC
-creates oid with specified
+.It Fn SYSCTL_ADD_PROC
+creates an oid with the specified
 .Pa handler
-function. The handler is responsible to handle read and write requests
-to the oid. This oid type is especially useful if the kernel data is not
-easily accessible, or needs to be processed before exporting.
-.Pp
+function.
+The handler is responsible for handling read and write requests
+to the oid.
+This oid type is especially useful
+if the kernel data is not easily accessible,
+or needs to be processed before exporting.
+.El
 .Sh EXAMPLES
-The following code example shows how to create new top-level category
-and how to hook up another subtree to already existing (static) node:
+The following is an example of
+how to create a new top-level category
+and how to hook up another subtree to an existing static node.
+This example does not use contexts,
+which results in tedious management of all intermediate oids,
+as they need to be freed later on:
 .Bd -literal
 #include <sys/sysctl.h>
  ...
@@ -420,22 +479,24 @@ debug.newtree.newstring
 newtree.newint
 .Ed
 .Pp
-Don't forget to free all oids when you don't need them!
+.Em "Care should be taken to free all oids once they are no longer needed!"
 .Pp
 .Sh SEE ALSO
 .Xr sysctl_ctx_init 9 ,
 .Xr sysctl_ctx_free 9 ,
 .Xr sysctl 8
 .Sh HISTORY
-These functions appeared in
+These functions first appeared in
 .Fx 5.0 .
 .Sh AUTHORS
 .An Andrzej Bialecki Aq abial@FreeBSD.org
 .Sh BUGS
-Sharing nodes between many code sections causes interdependencies that
-sometimes may lock the resources (e.g. it will be impossible to
-delete some oids, if other module hooked up its subtree to oids created
-by this module).  These issues are handled properly by sysctl contexts.
-
-Many operations on the tree involve traversing linked lists. For this
-reason oid creation and removal is relatively costly.
+Sharing nodes between many code sections
+causes interdependencies that sometimes may lock the resources.
+For example,
+if module A hooks up a subtree to an oid created by module B,
+module B will be unable to delete that oid.
+These issues are handled properly by sysctl contexts.
+.Pp
+Many operations on the tree involve traversing linked lists.
+For this reason, oid creation and removal is relatively costly.