1.\" 2.\" Copyright (c) 2000, Andrzej Bialecki <abial@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. The name of the author may not be used to endorse or promote products 14.\" derived from this software without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd December 13, 2016 29.Dt SYSCTL_ADD_OID 9 30.Os 31.Sh NAME 32.Nm sysctl_add_oid , 33.Nm sysctl_move_oid , 34.Nm sysctl_remove_oid , 35.Nm sysctl_remove_name 36.Nd runtime sysctl tree manipulation 37.Sh SYNOPSIS 38.In sys/types.h 39.In sys/sysctl.h 40.Ft struct sysctl_oid * 41.Fo sysctl_add_oid 42.Fa "struct sysctl_ctx_list *ctx" 43.Fa "struct sysctl_oid_list *parent" 44.Fa "int number" 45.Fa "const char *name" 46.Fa "int kind" 47.Fa "void *arg1" 48.Fa "intmax_t arg2" 49.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" 50.Fa "const char *format" 51.Fa "const char *descr" 52.Fa "const char *label" 53.Fc 54.Ft int 55.Fo sysctl_move_oid 56.Fa "struct sysctl_oid *oidp" 57.Fa "struct sysctl_oid_list *parent" 58.Fc 59.Ft int 60.Fo sysctl_remove_oid 61.Fa "struct sysctl_oid *oidp" 62.Fa "int del" 63.Fa "int recurse" 64.Fc 65.Ft int 66.Fo sysctl_remove_name 67.Fa "struct sysctl_oid *oidp" 68.Fa "const char *name" 69.Fa "int del" 70.Fa "int recurse" 71.Fc 72.Sh DESCRIPTION 73These functions provide the interface for creating and deleting sysctl 74OIDs at runtime for example during the lifetime of a module. 75The wrapper macros defined by 76.Xr sysctl 9 77are recommended when creating new OIDs. 78.Fn sysctl_add_oid 79should not be called directly from the code. 80.Pp 81Dynamic OIDs of type 82.Dv CTLTYPE_NODE 83are reusable 84so that several code sections can create and delete them, 85but in reality they are allocated and freed 86based on their reference count. 87As a consequence, 88it is possible for two or more code sections 89to create partially overlapping trees that they both can use. 90It is not possible to create overlapping leaves, 91nor to create different child types with the same name and parent. 92.Pp 93The 94.Fn sysctl_add_oid 95function creates a raw OID of any type and connects it to its parent node, if any. 96If the OID is successfully created, 97the function returns a pointer to it else 98it returns 99.Dv NULL . 100Many of the arguments for 101.Fn sysctl_add_oid 102are common to the wrapper macros defined by 103.Xr sysctl 9 . 104.Pp 105The 106.Fn sysctl_move_oid 107function reparents an existing OID. 108The OID is assigned a new number as if it had been created with 109.Fa number 110set to 111.Dv OID_AUTO . 112.Pp 113The 114.Fn sysctl_remove_oid 115function removes a dynamically created OID from the tree and 116optionally freeing its resources. 117It takes the following arguments: 118.Bl -tag -width recurse 119.It Fa oidp 120A pointer to the dynamic OID to be removed. 121If the OID is not dynamic, or the pointer is 122.Dv NULL , 123the function returns 124.Er EINVAL . 125.It Fa del 126If non-zero, 127.Fn sysctl_remove_oid 128will try to free the OID's resources 129when the reference count of the OID becomes zero. 130However, if 131.Fa del 132is set to 0, 133the routine will only deregister the OID from the tree, 134without freeing its resources. 135This behaviour is useful when the caller expects to rollback 136(possibly partially failed) 137deletion of many OIDs later. 138.It Fa recurse 139If non-zero, attempt to remove the node and all its children. 140If 141.Pa recurse 142is set to 0, 143any attempt to remove a node that contains any children 144will result in a 145.Er ENOTEMPTY 146error. 147.Em WARNING : "use recursive deletion with extreme caution" ! 148Normally it should not be needed if contexts are used. 149Contexts take care of tracking inter-dependencies 150between users of the tree. 151However, in some extreme cases it might be necessary 152to remove part of the subtree no matter how it was created, 153in order to free some other resources. 154Be aware, though, that this may result in a system 155.Xr panic 9 156if other code sections continue to use removed subtrees. 157.El 158.Pp 159The 160.Fn sysctl_remove_name 161function looks up the child node matching the 162.Fa name 163argument and then invokes the 164.Fn sysctl_remove_oid 165function on that node, passing along the 166.Fa del 167and 168.Fa recurse 169arguments. 170If a node having the specified name does not exist an error code of 171.Er ENOENT 172is returned. 173Else the error code from 174.Fn sysctl_remove_oid 175is returned. 176.Pp 177In most cases the programmer should use contexts, 178as described in 179.Xr sysctl_ctx_init 9 , 180to keep track of created OIDs, 181and to delete them later in orderly fashion. 182.Sh SEE ALSO 183.Xr sysctl 8 , 184.Xr sysctl 9 , 185.Xr sysctl_ctx_free 9 , 186.Xr sysctl_ctx_init 9 187.Sh HISTORY 188These functions first appeared in 189.Fx 4.2 . 190.Sh AUTHORS 191.An Andrzej Bialecki Aq Mt abial@FreeBSD.org 192.Sh BUGS 193Sharing nodes between many code sections 194causes interdependencies that sometimes may lock the resources. 195For example, 196if module A hooks up a subtree to an OID created by module B, 197module B will be unable to delete that OID. 198These issues are handled properly by sysctl contexts. 199.Pp 200Many operations on the tree involve traversing linked lists. 201For this reason, OID creation and removal is relatively costly. 202