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