diff options
author | sheldonh <sheldonh@FreeBSD.org> | 2000-07-18 07:46:14 +0000 |
---|---|---|
committer | sheldonh <sheldonh@FreeBSD.org> | 2000-07-18 07:46:14 +0000 |
commit | d383350bcbf111c0fede546761d1d6be826fc223 (patch) | |
tree | b5cc089a3202fdb1d4313c1b8ac2953695173db1 /share/man/man9/sysctl_add_oid.9 | |
parent | c5e43296676b72e89dd07896950fb452ceb29316 (diff) | |
download | FreeBSD-src-d383350bcbf111c0fede546761d1d6be826fc223.zip FreeBSD-src-d383350bcbf111c0fede546761d1d6be826fc223.tar.gz |
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
Diffstat (limited to 'share/man/man9/sysctl_add_oid.9')
-rw-r--r-- | share/man/man9/sysctl_add_oid.9 | 407 |
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 a4e5788..0a8476c 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. |