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