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.\" $FreeBSD$ 29.\" 30.Dd November 6, 2015 31.Dt SYSCTL_ADD_OID 9 32.Os 33.Sh NAME 34.Nm sysctl_add_oid , 35.Nm sysctl_move_oid , 36.Nm sysctl_remove_oid , 37.Nm sysctl_remove_name 38.Nd runtime sysctl tree manipulation 39.Sh SYNOPSIS 40.In sys/types.h 41.In sys/sysctl.h 42.Ft struct sysctl_oid * 43.Fo sysctl_add_oid 44.Fa "struct sysctl_ctx_list *ctx" 45.Fa "struct sysctl_oid_list *parent" 46.Fa "int number" 47.Fa "const char *name" 48.Fa "int kind" 49.Fa "void *arg1" 50.Fa "intmax_t arg2" 51.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" 52.Fa "const char *format" 53.Fa "const char *descr" 54.Fc 55.Ft int 56.Fo sysctl_move_oid 57.Fa "struct sysctl_oid *oidp" 58.Fa "struct sysctl_oid_list *parent" 59.Fc 60.Ft int 61.Fo sysctl_remove_oid 62.Fa "struct sysctl_oid *oidp" 63.Fa "int del" 64.Fa "int recurse" 65.Fc 66.Ft int 67.Fo sysctl_remove_name 68.Fa "struct sysctl_oid *oidp" 69.Fa "const char *name" 70.Fa "int del" 71.Fa "int recurse" 72.Fc 73.Sh DESCRIPTION 74These functions provide the interface for creating and deleting sysctl 75OIDs at runtime for example during the lifetime of a module. 76The wrapper macros defined by 77.Xr sysctl 9 78are recommended when creating new OIDs. 79.Fn sysctl_add_oid 80should not be called directly from the code. 81.Pp 82Dynamic OIDs of type 83.Dv CTLTYPE_NODE 84are reusable 85so that several code sections can create and delete them, 86but in reality they are allocated and freed 87based on their reference count. 88As a consequence, 89it is possible for two or more code sections 90to create partially overlapping trees that they both can use. 91It is not possible to create overlapping leaves, 92nor to create different child types with the same name and parent. 93.Pp 94The 95.Fn sysctl_add_oid 96function creates a raw OID of any type and connects it to its parent node, if any. 97If the OID is successfully created, 98the function returns a pointer to it else 99it returns 100.Dv NULL . 101Many of the arguments for 102.Fn sysctl_add_oid 103are common to the wrapper macros defined by 104.Xr sysctl 9 . 105.Pp 106The 107.Fn sysctl_move_oid 108function reparents an existing OID. 109The OID is assigned a new number as if it had been created with 110.Fa number 111set to 112.Dv OID_AUTO . 113.Pp 114The 115.Fn sysctl_remove_oid 116function removes a dynamically created OID from the tree and 117optionally freeing its resources. 118It takes the following arguments: 119.Bl -tag -width recurse 120.It Fa oidp 121A pointer to the dynamic OID to be removed. 122If the OID is not dynamic, or the pointer is 123.Dv NULL , 124the function returns 125.Er EINVAL . 126.It Fa del 127If non-zero, 128.Fn sysctl_remove_oid 129will try to free the OID's resources 130when the reference count of the OID becomes zero. 131However, if 132.Fa del 133is set to 0, 134the routine will only deregister the OID from the tree, 135without freeing its resources. 136This behaviour is useful when the caller expects to rollback 137(possibly partially failed) 138deletion of many OIDs later. 139.It Fa recurse 140If non-zero, attempt to remove the node and all its children. 141If 142.Pa recurse 143is set to 0, 144any attempt to remove a node that contains any children 145will result in a 146.Er ENOTEMPTY 147error. 148.Em WARNING : "use recursive deletion with extreme caution" ! 149Normally it should not be needed if contexts are used. 150Contexts take care of tracking inter-dependencies 151between users of the tree. 152However, in some extreme cases it might be necessary 153to remove part of the subtree no matter how it was created, 154in order to free some other resources. 155Be aware, though, that this may result in a system 156.Xr panic 9 157if other code sections continue to use removed subtrees. 158.El 159.Pp 160The 161.Fn sysctl_remove_name 162function looks up the child node matching the 163.Fa name 164argument and then invokes the 165.Fn sysctl_remove_oid 166function on that node, passing along the 167.Fa del 168and 169.Fa recurse 170arguments. 171If a node having the specified name does not exist an error code of 172.Er ENOENT 173is returned. 174Else the error code from 175.Fn sysctl_remove_oid 176is returned. 177.Pp 178In most cases the programmer should use contexts, 179as described in 180.Xr sysctl_ctx_init 9 , 181to keep track of created OIDs, 182and to delete them later in orderly fashion. 183.Sh SEE ALSO 184.Xr sysctl 8 , 185.Xr sysctl 9 , 186.Xr sysctl_ctx_free 9 , 187.Xr sysctl_ctx_init 9 188.Sh HISTORY 189These functions first appeared in 190.Fx 4.2 . 191.Sh AUTHORS 192.An Andrzej Bialecki Aq Mt abial@FreeBSD.org 193.Sh BUGS 194Sharing nodes between many code sections 195causes interdependencies that sometimes may lock the resources. 196For example, 197if module A hooks up a subtree to an OID created by module B, 198module B will be unable to delete that OID. 199These issues are handled properly by sysctl contexts. 200.Pp 201Many operations on the tree involve traversing linked lists. 202For this reason, OID creation and removal is relatively costly. 203