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