diff options
Diffstat (limited to 'share/man')
| -rw-r--r-- | share/man/man4/mly.4 | 256 | ||||
| -rw-r--r-- | share/man/man9/sysctl_add_oid.9 | 502 | ||||
| -rw-r--r-- | share/man/man9/sysctl_ctx_init.9 | 244 |
3 files changed, 0 insertions, 1002 deletions
diff --git a/share/man/man4/mly.4 b/share/man/man4/mly.4 deleted file mode 100644 index 40e6e4bbe032e..0000000000000 --- a/share/man/man4/mly.4 +++ /dev/null @@ -1,256 +0,0 @@ -.\" -.\" Copyright (c) 2000 Michael Smith -.\" Copyright (c) 2000 BSDi -.\" 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. 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 ``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 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 August 22, 2000 -.Dt MLY 4 -.Os -.Sh NAME -.Nm mly -.Nd Mylex AcceleRAID/eXtremeRAID family driver -.Sh SYNOPSIS -.Cd device pci -.Cd device mly -.Cd device scbus -.Cd device da -.Sh DESCRIPTION -The -.Nm -driver provides support for Mylex AcceleRAID and eXtremeRAID-family -PCI to SCSI RAID controllers with version 6.00 and later -firmware. -Supported controllers include: -.Bl -bullet -.It -AcceleRAID 160 -.It -AcceleRAID 170 -.It -AcceleRAID 352 -.It -eXtremeRAID 2000 -.It -eXtremeRAID 3000 -.El -.Pp -Compatible Mylex controllers not listed should work, but have not been -verified. -.Pp -Logical devices (array drives) attached to the controller are presented -to the SCSI subsystem as though they were direct-access devices on a -virtual SCSI bus. -Physical devices which are not claimed by a logical -device are presented on SCSI channels which match the physical channels -on the controller. -.Sh DIAGNOSTICS -.Ss Controller initialisation phase -.Bl -diag -.It "mly%d: controller initialisation started" -.It "mly%d: initialisation complete" -.Pp -The controller firmware has started initialisation. -Normally this process is performed by the controller BIOS, -but the driver may need -to do this in cases where the BIOS has failed, or is not compatible -(e.g. on non-x86 systems). -.It "mly%d: drive spinup in progress" -.Pp -Drive startup is in progress; this may take several minutes. -.It "mly%d: mirror race recovery failed, one or more drives offline" -.It "mly%d: mirror race recovery in progress" -.It "mly%d: mirror race recovery on a critical drive" -.Pp -These error codes are undocumented. -.It "mly%d: FATAL MEMORY PARITY ERROR" -.Pp -Firmware detected a fatal memory error; the driver will not attempt to -attach to this controller. -.It "mly%d: unknown initialisation code %x" -.Pp -An unknown error occurred during initialisation; it will be ignored. -.El -.Ss Driver initialisation/shutdown phase -.Bl -diag -.It "mly%d: can't enable busmaster feature" -.It "mly%d: memory window not available" -.It "mly%d: can't allocate register window" -.It "mly%d: can't allocate interrupt" -.It "mly%d: can't set up interrupt" -.Pp -The system's PCI BIOS has not correctly configured the controller's -PCI interface; initialisation has failed and the driver will not -attach to this controller. -.It "mly%d: can't allocate parent DMA tag" -.It "mly%d: can't allocate buffer DMA tag" -.It "mly%d: can't allocate command packet DMA tag" -.It "mly%d: can't allocate scatter/gather DMA tag" -.It "mly%d: can't allocate s/g table" -.It "mly%d: can't allocate memory mailbox DMA tag" -.It "mly%d: can't allocate memory mailbox" -.Pp -A resource allocation error occurred while initialising the driver; -initialisation has failed and the driver will not attach to this -controller. -.It "mly%d: BTL rescan result corrupted" -.Pp -The results of a scan for an attached device were corrupted. -One or more devices may not be correctly reported. -.It "mly%d: flushing cache..." -.Pp -The controller cache is being flushed prior to detach or shutdown. -.El -.Ss Operational diagnostics -.Bl -diag -.It "mly%d: physical device %d:%d online" -.It "mly%d: physical device %d:%d standby" -.It "mly%d: physical device %d:%d automatic rebuild started" -.It "mly%d: physical device %d:%d manual rebuild started" -.It "mly%d: physical device %d:%d rebuild completed" -.It "mly%d: physical device %d:%d rebuild cancelled" -.It "mly%d: physical device %d:%d rebuild failed for unknown reasons" -.It "mly%d: physical device %d:%d rebuild failed due to new physical device" -.It "mly%d: physical device %d:%d rebuild failed due to logical drive failure" -.It "mly%d: physical device %d:%d found" -.It "mly%d: physical device %d:%d gone" -.It "mly%d: physical device %d:%d unconfigured" -.It "mly%d: physical device %d:%d expand capacity started" -.It "mly%d: physical device %d:%d expand capacity completed" -.It "mly%d: physical device %d:%d expand capacity failed" -.It "mly%d: physical device %d:%d parity error" -.It "mly%d: physical device %d:%d soft error" -.It "mly%d: physical device %d:%d miscellaneous error" -.It "mly%d: physical device %d:%d reset" -.It "mly%d: physical device %d:%d active spare found" -.It "mly%d: physical device %d:%d warm spare found" -.It "mly%d: physical device %d:%d initialization started" -.It "mly%d: physical device %d:%d initialization completed" -.It "mly%d: physical device %d:%d initialization failed" -.It "mly%d: physical device %d:%d initialization cancelled" -.It "mly%d: physical device %d:%d write recovery failed" -.It "mly%d: physical device %d:%d scsi bus reset failed" -.It "mly%d: physical device %d:%d double check condition" -.It "mly%d: physical device %d:%d device cannot be accessed" -.It "mly%d: physical device %d:%d gross error on scsi processor" -.It "mly%d: physical device %d:%d bad tag from device" -.It "mly%d: physical device %d:%d command timeout" -.It "mly%d: physical device %d:%d system reset" -.It "mly%d: physical device %d:%d busy status or parity error" -.It "mly%d: physical device %d:%d host set device to failed state" -.It "mly%d: physical device %d:%d selection timeout" -.It "mly%d: physical device %d:%d scsi bus phase error" -.It "mly%d: physical device %d:%d device returned unknown status" -.It "mly%d: physical device %d:%d device not ready" -.It "mly%d: physical device %d:%d device not found at startup" -.It "mly%d: physical device %d:%d COD write operation failed" -.It "mly%d: physical device %d:%d BDT write operation failed" -.It "mly%d: physical device %d:%d missing at startup" -.It "mly%d: physical device %d:%d start rebuild failed due to physical drive too small" -.It "mly%d: physical device %d:%d sense data received" -.It "mly%d: sense key %d asc %02x ascq %02x" -.It "mly%d: info %4D csi %4D" -.It "mly%d: physical device %d:%d offline" -.It "mly%d: sense key %d asc %02x ascq %02x" -.It "mly%d: info %4D csi %4D" -.Pp -The reported event refers to the physical device at the given channel:target -address. -.It "mly%d: logical device %d (%s) consistency check started" -.It "mly%d: logical device %d (%s) consistency check completed" -.It "mly%d: logical device %d (%s) consistency check cancelled" -.It "mly%d: logical device %d (%s) consistency check completed with errors" -.It "mly%d: logical device %d (%s) consistency check failed due to logical drive failure" -.It "mly%d: logical device %d (%s) consistency check failed due to physical device failure" -.It "mly%d: logical device %d (%s) automatic rebuild started" -.It "mly%d: logical device %d (%s) manual rebuild started" -.It "mly%d: logical device %d (%s) rebuild completed" -.It "mly%d: logical device %d (%s) rebuild cancelled" -.It "mly%d: logical device %d (%s) rebuild failed for unknown reasons" -.It "mly%d: logical device %d (%s) rebuild failed due to new physical device" -.It "mly%d: logical device %d (%s) rebuild failed due to logical drive failure" -.It "mly%d: logical device %d (%s) offline" -.It "mly%d: logical device %d (%s) critical" -.It "mly%d: logical device %d (%s) online" -.It "mly%d: logical device %d (%s) initialization started" -.It "mly%d: logical device %d (%s) initialization completed" -.It "mly%d: logical device %d (%s) initialization cancelled" -.It "mly%d: logical device %d (%s) initialization failed" -.It "mly%d: logical device %d (%s) found" -.It "mly%d: logical device %d (%s) gone" -.It "mly%d: logical device %d (%s) expand capacity started" -.It "mly%d: logical device %d (%s) expand capacity completed" -.It "mly%d: logical device %d (%s) expand capacity failed" -.It "mly%d: logical device %d (%s) bad block found" -.It "mly%d: logical device %d (%s) size changed" -.It "mly%d: logical device %d (%s) type changed" -.It "mly%d: logical device %d (%s) bad data block found" -.It "mly%d: logical device %d (%s) read of data block in bdt" -.It "mly%d: logical device %d (%s) write back data for disk block lost" -.Pp -The event report will include the name of the SCSI device which has -attached to the device if possible. -.It "mly%d: enclosure %d fan %d failed" -.It "mly%d: enclosure %d fan %d ok" -.It "mly%d: enclosure %d fan %d not present" -.It "mly%d: enclosure %d power supply %d failed" -.It "mly%d: enclosure %d power supply %d ok" -.It "mly%d: enclosure %d power supply %d not present" -.It "mly%d: enclosure %d temperature sensor %d failed" -.It "mly%d: enclosure %d temperature sensor %d critical" -.It "mly%d: enclosure %d temperature sensor %d ok" -.It "mly%d: enclosure %d temperature sensor %d not present" -.It "mly%d: enclosure %d unit %d access critical" -.It "mly%d: enclosure %d unit %d access ok" -.It "mly%d: enclosure %d unit %d access offline" -.Pp -These events refer to external enclosures by number. -The driver does not attempt to name the enclosures. -.It "mly%d: controller cache write back error" -.It "mly%d: controller battery backup unit found" -.It "mly%d: controller battery backup unit charge level low" -.It "mly%d: controller battery backup unit charge level ok" -.It "mly%d: controller installation aborted" -.It "mly%d: controller mirror race recovery in progress" -.It "mly%d: controller mirror race on critical drive" -.It "mly%d: controller memory soft ecc error" -.It "mly%d: controller memory hard ecc error" -.It "mly%d: controller battery backup unit failed" -.Pp -These events report controller status changes. -.El -.Sh BUGS -The driver does not yet provide an external management interface. -.Pp -Enclosures are not named or otherwise identified in event messages. -.Sh AUTHORS -The -.Nm -driver was written by -.An Michael Smith -.Aq msmith@FreeBSD.org . -.Pp -This manual page was written by -.An Michael Smith -.Aq msmith@FreeBSD.org . - diff --git a/share/man/man9/sysctl_add_oid.9 b/share/man/man9/sysctl_add_oid.9 deleted file mode 100644 index 3d5769b9b4c07..0000000000000 --- a/share/man/man9/sysctl_add_oid.9 +++ /dev/null @@ -1,502 +0,0 @@ -.\" -.\" 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 Jul 15, 2000 -.Dt SYSCTL_ADD_OID 9 -.Os -.Sh NAME -.Nm sysctl_add_oid , -.Nm sysctl_remove_oid -.Nd runtime sysctl tree manipulation -.Sh SYNOPSIS -.Fd #include <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 "char *name" -.Fa "int kind" -.Fa "void *arg1" -.Fa "int arg2" -.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" -.Fa "char *format" -.Fa "char *descr" -.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 "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 "NAME" -.Fa "int kind" -.Fa "void *arg1" -.Fa "int arg2" -.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" -.Fa "char *format" -.Fa "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 "NAME" -.Fa "int access" -.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" -.Fa "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 "NAME" -.Fa "int access" -.Fa "char *arg" -.Fa "0" -.Fa "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 "NAME" -.Fa "int access" -.Fa "int *arg" -.Fa "0" -.Fa "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 "NAME" -.Fa "int access" -.Fa "unsigned int *arg" -.Fa "0" -.Fa "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 "NAME" -.Fa "int access" -.Fa "long *arg" -.Fa "0" -.Fa "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 "NAME" -.Fa "int access" -.Fa "unsigned long *arg" -.Fa "0" -.Fa "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 "NAME" -.Fa "int access" -.Fa "void *arg" -.Fa "size_t *len" -.Fa "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 "NAME" -.Fa "int access" -.Fa "struct TYPE *arg" -.Fa "TYPE" -.Fa "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 "NAME" -.Fa "int access" -.Fa "0" -.Fa "0" -.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" -.Fa "char *format" -.Fa "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 -.Aq 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 name 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 -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 -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 successfuly 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 bitmask of the type and access values defined in the -.Aq sys/sysctl.h -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 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_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_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 -utlity. -.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, CTFLAG_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, CTFLAG_RW, 0, "new tree under debug"); -oidp = SYSCTL_ADD_STRING( NULL, SYSCTL_CHILDREN(root2), - OID_AUTO, newstring, CTLFLAG_R, 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!" -.Pp -.Sh SEE ALSO -.Xr sysctl 8 , -.Xr sysctl_ctx_free 9 , -.Xr sysctl_ctx_init 9 -.Sh HISTORY -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. -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. diff --git a/share/man/man9/sysctl_ctx_init.9 b/share/man/man9/sysctl_ctx_init.9 deleted file mode 100644 index 9d7a8638940c2..0000000000000 --- a/share/man/man9/sysctl_ctx_init.9 +++ /dev/null @@ -1,244 +0,0 @@ -.\" -.\" 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 Jul 15, 2000 -.Dt SYSCTL_CTX_INIT 9 -.Os -.Sh NAME -.Nm sysctl_ctx_init , -.Nm sysctl_ctx_free , -.Nm sysctl_ctx_entry_add , -.Nm sysctl_ctx_entry_find , -.Nm sysctl_ctx_entry_del -.Nd sysctl context for managing dynamically created sysctl oids. -.Sh SYNOPSIS -.Fd #include <sys/sysctl.h> -.Ft int -.Fo sysctl_ctx_init -.Fa "struct sysctl_ctx_list *clist" -.Fc -.Ft int -.Fo sysctl_ctx_free -.Fa "struct sysctl_ctx_list *clist" -.Fc -.Ft struct sysctl_ctx_entry * -.Fo sysctl_ctx_entry_add -.Fa "struct sysctl_ctx_list *clist" -.Fa "struct sysctl_oid *oidp" -.Fc -.Ft struct sysctl_ctx_entry * -.Fo sysctl_ctx_entry_find -.Fa "struct sysctl_ctx_list *clist" -.Fa "struct sysctl_oid *oidp" -.Fc -.Ft int -.Fo sysctl_ctx_entry_del -.Fa "struct sysctl_ctx_list *clist" -.Fa "struct sysctl_oid *oidp" -.Fc -.Sh DESCRIPTION -These functions provide an interface -for managing dynamically created oids. -The sysctl context is responsible for keeping track of created oids, -as well as their proper removal when needed. -It adds a simple transactional aspect to oid removal operations; -i.e. if a removal operation fails part way, -it is possible to roll back the sysctl tree -to its previous state. -.Pp -The -.Fn sysctl_ctx_init -function initializes a sysctl context. -The -.Fa clist -argument must point to an already allocated variable. -A context -.Em must -be initialized before use. -Once it is initialized, -a pointer to the context can be passed as an argument to all the -.Fa SYSCTL_ADD_* -macros (see -.Xr sysctl_add_oid 9 ) , -and it will be updated with entries pointing to newly created oids. -.Pp -Internally, the context is represented as a -.Xr queue 3 -TAILQ linked list. -The list consists of -.Li struct sysctl_ctx_entry -entries: -.Bd -literal -offset indent -struct sysctl_ctx_entry { - struct sysctl_oid *entry; - TAILQ_ENTRY(sysctl_ctx_entry) link; -}; - -TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry); -.Ed -.Pp -Each context entry points to one dynamic oid that it manages. -Newly created oids are always inserted in the front of the list. -.Pp -The -.Fn sysctl_ctx_free -function removes the context and associated oids it manages. -If the function completes successfuly, -all managed oids have been unregistered -(removed from the tree) -and freed, -together with all their allocated memory, -and the entries of the context have been freed as well. -.Pp -The removal operation is performed in two steps. -First, for each context entry, the function -.Xr sysctl_remove_oid 9 -is executed, with parameter -.Fa del -set to 0, which inhibits the freeing of resources. -If there are no errors during this step, -.Fn sysctl_ctx_free -proceeds to the next step. -If the first step fails, -all unregistered oids associated with the context are registered again. -.Pp -.Em Note : -in most cases, the programmer specifies -.Dv OID_AUTO -as the oid number when creating an oid. -However, during registration of the oid in the tree, -this number is changed to the first available number -greater than 99. -If the first step of context deletion fails, -re-registration of the oid does not change the already assigned oid number -(which is different from OID_AUTO). -This ensures that re-registered entries -maintain their original positions in the tree. -.Pp -The second step actually performs the deletion of the dynamic oids. -.Xr sysctl_remove_oid 9 -iterates through the context list, -starting from beginning (i.e. the newest entries). -.Em Important : -this time, the function not only deletes the oids from the tree, -but also frees their memory (provided that oid_refcnt == 0), -as well as the memory of all context entries. -.Pp -The -.Fn sysctl_ctx_entry_add -function allows the addition of an existing dynamic oid to a context. -.Pp -The -.Fn sysctl_ctx_entry_del -function removes an entry from the context. -.Em Important : -in this case, only the corresponding -.Li struct sysctl_ctx_entry -is freed, but the -.Fa oidp -pointer remains intact. -Thereafter, the programmer is responsible for managing the resources -allocated to this oid. -.Pp -The -.Fn sysctl_ctx_entry_find -function searches for a given -.Fa oidp -witin a context list, -either returning a pointer to the -.Fa struct sysctl_ctx_entry -found, -or -.Dv NULL . -.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 uses contexts to keep track of the oids. -.Bd -literal -#include <sys/sysctl.h> - ... -struct sysctl_ctx_list clist; -struct sysctl_oid *oidp; -int a_int; -char *string = "dynamic sysctl"; - ... - -sysctl_ctx_init(&clist); -oidp = SYSCTL_ADD_NODE( &clist, SYSCTL_STATIC_CHILDREN(/* tree top */), - OID_AUTO, newtree, CTFLAG_RW, 0, "new top level tree"); -oidp = SYSCTL_ADD_INT( &clist, SYSCTL_CHILDREN(oidp), - OID_AUTO, newint, CTLFLAG_RW, &a_int, 0, "new int leaf"); - ... -oidp = SYSCTL_ADD_NODE( &clist, SYSCTL_STATIC_CHILDREN(_debug), - OID_AUTO, newtree, CTFLAG_RW, 0, "new tree under debug"); -oidp = SYSCTL_ADD_STRING( &clist, SYSCTL_CHILDREN(oidp), - OID_AUTO, newstring, CTLFLAG_R, string, 0, "new string leaf"); - ... -/* Now we can free up the oids */ -if(sysctl_ctx_free(&clist)) { - printf("can't free this context - other oids depend on it"); - return(ENOTEMPTY); -} else { - printf("Success!\\n"): - return(0); -} -.Ed -.Pp -This example creates the following subtrees: -.Bd -literal -offset indent -debug.newtree.newstring -newtree.newint -.Ed -.Pp -Note that both trees are removed, and their resources freed, -through one -.Fn sysctl_ctx_free -call, which starts by freeing the newest entries (leaves) -and then proceeds to free the older entries (in this case the nodes). -.Sh SEE ALSO -.Xr queue 3 , -.Xr sysctl 8 , -.Xr sysctl_add_oid 9 , -.Xr sysctl_remove_oid 9 -.Sh HISTORY -These functions first appeared in -.Fx 5.0 . -.Sh AUTHORS -.An Andrzej Bialecki Aq abial@FreeBSD.org -.Sh BUGS -The current removal algorithm is somewhat heavy. -In the worst case, -all oids need to be unregistered, registered again, -and then unregistered and deleted. -However, the algorithm does guarantee transactional properties -for removal operations. -.Pp -All operations on contexts involve linked list traversal. -For this reason, -creation and removal of entries is relatively costly. |