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 July 31, 2014 29.Dt SYSCTL_CTX_INIT 9 30.Os 31.Sh NAME 32.Nm sysctl_ctx_init , 33.Nm sysctl_ctx_free , 34.Nm sysctl_ctx_entry_add , 35.Nm sysctl_ctx_entry_find , 36.Nm sysctl_ctx_entry_del 37.Nd "sysctl context for managing dynamically created sysctl OIDs" 38.Sh SYNOPSIS 39.In sys/types.h 40.In sys/sysctl.h 41.Ft int 42.Fo sysctl_ctx_init 43.Fa "struct sysctl_ctx_list *clist" 44.Fc 45.Ft int 46.Fo sysctl_ctx_free 47.Fa "struct sysctl_ctx_list *clist" 48.Fc 49.Ft struct sysctl_ctx_entry * 50.Fo sysctl_ctx_entry_add 51.Fa "struct sysctl_ctx_list *clist" 52.Fa "struct sysctl_oid *oidp" 53.Fc 54.Ft struct sysctl_ctx_entry * 55.Fo sysctl_ctx_entry_find 56.Fa "struct sysctl_ctx_list *clist" 57.Fa "struct sysctl_oid *oidp" 58.Fc 59.Ft int 60.Fo sysctl_ctx_entry_del 61.Fa "struct sysctl_ctx_list *clist" 62.Fa "struct sysctl_oid *oidp" 63.Fc 64.Sh DESCRIPTION 65These functions provide an interface 66for managing dynamically created OIDs. 67The sysctl context is responsible for keeping track of created OIDs, 68as well as their proper removal when needed. 69It adds a simple transactional aspect to OID removal operations; 70i.e., if a removal operation fails part way, 71it is possible to roll back the sysctl tree 72to its previous state. 73.Pp 74The 75.Fn sysctl_ctx_init 76function initializes a sysctl context. 77The 78.Fa clist 79argument must point to an already allocated variable. 80A context 81.Em must 82be initialized before use. 83Once it is initialized, 84a pointer to the context can be passed as an argument to all the 85.Fa SYSCTL_ADD_* 86macros (see 87.Xr sysctl_add_oid 9 ) , 88and it will be updated with entries pointing to newly created OIDS. 89.Pp 90Internally, the context is represented as a 91.Xr queue 3 92TAILQ linked list. 93The list consists of 94.Li struct sysctl_ctx_entry 95entries: 96.Bd -literal -offset indent 97struct sysctl_ctx_entry { 98 struct sysctl_oid *entry; 99 TAILQ_ENTRY(sysctl_ctx_entry) link; 100}; 101 102TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry); 103.Ed 104.Pp 105Each context entry points to one dynamic OID that it manages. 106Newly created OIDs are always inserted in the front of the list. 107.Pp 108The 109.Fn sysctl_ctx_free 110function removes the context and associated OIDs it manages. 111If the function completes successfully, 112all managed OIDs have been unregistered 113(removed from the tree) 114and freed, 115together with all their allocated memory, 116and the entries of the context have been freed as well. 117.Pp 118The removal operation is performed in two steps. 119First, for each context entry, the function 120.Xr sysctl_remove_oid 9 121is executed, with parameter 122.Fa del 123set to 0, which inhibits the freeing of resources. 124If there are no errors during this step, 125.Fn sysctl_ctx_free 126proceeds to the next step. 127If the first step fails, 128all unregistered OIDs associated with the context are registered again. 129.Pp 130.Em Note : 131in most cases, the programmer specifies 132.Dv OID_AUTO 133as the OID number when creating an OID. 134However, during registration of the OID in the tree, 135this number is changed to the first available number 136greater than or equal to 137.Dv CTL_AUTO_START . 138If the first step of context deletion fails, 139re-registration of the OID does not change the already assigned OID number 140(which is different from OID_AUTO). 141This ensures that re-registered entries 142maintain their original positions in the tree. 143.Pp 144The second step actually performs the deletion of the dynamic OIDs. 145.Xr sysctl_remove_oid 9 146iterates through the context list, 147starting from beginning (i.e., the newest entries). 148.Em Important : 149this time, the function not only deletes the OIDs from the tree, 150but also frees their memory (provided that oid_refcnt == 0), 151as well as the memory of all context entries. 152.Pp 153The 154.Fn sysctl_ctx_entry_add 155function allows the addition of an existing dynamic OID to a context. 156.Pp 157The 158.Fn sysctl_ctx_entry_del 159function removes an entry from the context. 160.Em Important : 161in this case, only the corresponding 162.Li struct sysctl_ctx_entry 163is freed, but the 164.Fa oidp 165pointer remains intact. 166Thereafter, the programmer is responsible for managing the resources 167allocated to this OID. 168.Pp 169The 170.Fn sysctl_ctx_entry_find 171function searches for a given 172.Fa oidp 173within a context list, 174either returning a pointer to the 175.Fa struct sysctl_ctx_entry 176found, 177or 178.Dv NULL . 179.Sh EXAMPLES 180The following is an example of how to create a new top-level category 181and how to hook up another subtree to an existing static node. 182This example uses contexts to keep track of the OIDs. 183.Bd -literal 184#include <sys/sysctl.h> 185 ... 186static struct sysctl_ctx_list clist; 187static struct sysctl_oid *oidp; 188static int a_int; 189static const char *string = "dynamic sysctl"; 190 ... 191 192sysctl_ctx_init(&clist); 193oidp = SYSCTL_ADD_ROOT_NODE(&clist, 194 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); 195oidp = SYSCTL_ADD_INT(&clist, SYSCTL_CHILDREN(oidp), 196 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); 197 ... 198oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(_debug), 199 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); 200oidp = SYSCTL_ADD_STRING(&clist, SYSCTL_CHILDREN(oidp), 201 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); 202 ... 203/* Now we can free up the OIDs */ 204if (sysctl_ctx_free(&clist)) { 205 printf("can't free this context - other OIDs depend on it"); 206 return (ENOTEMPTY); 207} else { 208 printf("Success!\\n"); 209 return (0); 210} 211.Ed 212.Pp 213This example creates the following subtrees: 214.Bd -literal -offset indent 215debug.newtree.newstring 216newtree.newint 217.Ed 218.Pp 219Note that both trees are removed, and their resources freed, 220through one 221.Fn sysctl_ctx_free 222call, which starts by freeing the newest entries (leaves) 223and then proceeds to free the older entries (in this case the nodes). 224.Sh SEE ALSO 225.Xr queue 3 , 226.Xr sysctl 8 , 227.Xr sysctl 9 , 228.Xr sysctl_add_oid 9 , 229.Xr sysctl_remove_oid 9 230.Sh HISTORY 231These functions first appeared in 232.Fx 4.2 . 233.Sh AUTHORS 234.An Andrzej Bialecki Aq Mt abial@FreeBSD.org 235.Sh BUGS 236The current removal algorithm is somewhat heavy. 237In the worst case, 238all OIDs need to be unregistered, registered again, 239and then unregistered and deleted. 240However, the algorithm does guarantee transactional properties 241for removal operations. 242.Pp 243All operations on contexts involve linked list traversal. 244For this reason, 245creation and removal of entries is relatively costly. 246