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
This commit is contained in:
Sheldon Hearn
parent
269532d987
commit
3ae5a45440
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user