diff options
Diffstat (limited to 'share/man/man9/sysctl_add_oid.9')
-rw-r--r-- | share/man/man9/sysctl_add_oid.9 | 530 |
1 files changed, 530 insertions, 0 deletions
diff --git a/share/man/man9/sysctl_add_oid.9 b/share/man/man9/sysctl_add_oid.9 new file mode 100644 index 000000000000..43f3112a4d09 --- /dev/null +++ b/share/man/man9/sysctl_add_oid.9 @@ -0,0 +1,530 @@ +.\" +.\" Copyright (c) 2000, Andrzej Bialecki <abial@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 15, 2000 +.Dt SYSCTL_ADD_OID 9 +.Os +.Sh NAME +.Nm sysctl_add_oid , +.Nm sysctl_move_oid , +.Nm sysctl_remove_oid +.Nd runtime sysctl tree manipulation +.Sh SYNOPSIS +.In sys/types.h +.In sys/sysctl.h +.Ft struct sysctl_oid * +.Fo sysctl_add_oid +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int kind" +.Fa "void *arg1" +.Fa "int arg2" +.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" +.Fa "const char *format" +.Fa "const char *descr" +.Fc +.Ft int +.Fo sysctl_move_oid +.Fa "struct sysctl_oid *oidp" +.Fa "struct sysctl_oid_list *parent" +.Fc +.Ft int +.Fo sysctl_remove_oid +.Fa "struct sysctl_oid *oidp" +.Fa "int del" +.Fa "int recurse" +.Fc +.Ft struct sysctl_oid_list * +.Fo SYSCTL_CHILDREN +.Fa "struct sysctl_oid *oidp" +.Fc +.Ft struct sysctl_oid_list * +.Fo SYSCTL_STATIC_CHILDREN +.Fa "struct sysctl_oid_list OID_NAME" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_OID +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int kind" +.Fa "void *arg1" +.Fa "int arg2" +.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" +.Fa "const char *format" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_NODE +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int access" +.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_STRING +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int access" +.Fa "char *arg" +.Fa "int len" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_INT +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int access" +.Fa "int *arg" +.Fa "int len" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_UINT +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int access" +.Fa "unsigned int *arg" +.Fa "int len" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_LONG +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int access" +.Fa "long *arg" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_ULONG +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int access" +.Fa "unsigned long *arg" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_QUAD +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int access" +.Fa "int64_t *arg" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_OPAQUE +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int access" +.Fa "void *arg" +.Fa "int len" +.Fa "const char *format" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_STRUCT +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int access" +.Fa "void *arg" +.Fa STRUCT_NAME +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_PROC +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int access" +.Fa "void *arg1" +.Fa "int arg2" +.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" +.Fa "const char *format" +.Fa "const char *descr" +.Fc +.Sh DESCRIPTION +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 +.In sys/linker_set.h +and +.\" 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 +.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 same name and parent. +.Pp +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 +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 +argument 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 +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 +function creates raw oids of any type. +If the oid is successfully created, +the function returns a pointer to it; +otherwise it returns +.Dv NULL . +Many of the arguments for +.Fn sysctl_add_oid +are common to the macros. +The arguments are as follows: +.Bl -tag -width handler +.It Fa ctx +A pointer to an optional sysctl context, or +.Dv NULL . +See +.Xr sysctl_ctx_init 9 +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 bit mask of the type and access values defined in the +.In sys/sysctl.h +header file. +Oids created dynamically always have the +.Dv CTLFLAG_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 superuser 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 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: +.Dq N +for node, +.Dq A +for +.Li "char *" , +.Dq I +for +.Li "int" , +.Dq IU +for +.Li "unsigned int" , +.Dq L +for +.Li "long" , +.Dq LU +for +.Li "unsigned long" +and +.Dq S,TYPE +for +.Li "struct TYPE" +structures. +.It Fa descr +A pointer to a textual description of the oid. +.El +.Pp +The +.Fn sysctl_move_oid +function reparents an existing oid. +The oid is assigned a new number as if it had been created with +.Fa number +set to +.Dv OID_AUTO . +.Pp +The +.Fn sysctl_remove_oid +function removes a dynamically created oid from the tree, +optionally freeing its resources. +It takes the following arguments: +.Bl -tag -width recurse +.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 +.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, +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 +.\" 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. +.Bl -tag -width SYSCTL_ADD_STRINGXX +They are as follows: +.It Fn SYSCTL_ADD_OID +creates a raw oid. +This macro is functionally equivalent to the +.Fn sysctl_add_oid +function. +.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. +.It Fn SYSCTL_ADD_UINT +creates an oid that handles an +.Li unsigned int +variable. +.It Fn SYSCTL_ADD_LONG +creates an oid that handles a +.Li long +variable. +.It Fn SYSCTL_ADD_ULONG +creates an oid that handles an +.Li unsigned long +variable. +.It Fn SYSCTL_ADD_QUAD +creates an oid that handles an +.Li int64_t +variable. +.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 the +.Xr sysctl 8 +utility. +.It Fn SYSCTL_ADD_PROC +creates an oid with the specified +.Pa handler +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 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> + ... +/* Need to preserve pointers to newly created subtrees, to be able + * to free them later. + */ +struct sysctl_oid *root1, *root2, *oidp; +int a_int; +char *string = "dynamic sysctl"; + ... + +root1 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(/* tree top */), + OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); +oidp = SYSCTL_ADD_INT( NULL, SYSCTL_CHILDREN(root1), + OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); + ... +root2 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(_debug), + OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); +oidp = SYSCTL_ADD_STRING( NULL, SYSCTL_CHILDREN(root2), + OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); +.Ed +.Pp +This example creates the following subtrees: +.Bd -literal -offset indent +debug.newtree.newstring +newtree.newint +.Ed +.Pp +.Em "Care should be taken to free all oids once they are no longer needed!" +.Sh SEE ALSO +.Xr sysctl 8 , +.Xr sysctl 9 , +.Xr sysctl_ctx_free 9 , +.Xr sysctl_ctx_init 9 +.Sh HISTORY +These functions first appeared in +.Fx 4.2 . +.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. +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. |