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 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/types.h 42.In sys/sysctl.h 43.Ft int 44.Fo sysctl_ctx_init 45.Fa "struct sysctl_ctx_list *clist" 46.Fc 47.Ft int 48.Fo sysctl_ctx_free 49.Fa "struct sysctl_ctx_list *clist" 50.Fc 51.Ft struct sysctl_ctx_entry * 52.Fo sysctl_ctx_entry_add 53.Fa "struct sysctl_ctx_list *clist" 54.Fa "struct sysctl_oid *oidp" 55.Fc 56.Ft struct sysctl_ctx_entry * 57.Fo sysctl_ctx_entry_find 58.Fa "struct sysctl_ctx_list *clist" 59.Fa "struct sysctl_oid *oidp" 60.Fc 61.Ft int 62.Fo sysctl_ctx_entry_del 63.Fa "struct sysctl_ctx_list *clist" 64.Fa "struct sysctl_oid *oidp" 65.Fc 66.Sh DESCRIPTION 67These functions provide an interface 68for managing dynamically created oids. 69The sysctl context is responsible for keeping track of created oids, 70as well as their proper removal when needed. 71It adds a simple transactional aspect to oid removal operations; 72i.e. if a removal operation fails part way, 73it is possible to roll back the sysctl tree 74to its previous state. 75.Pp 76The 77.Fn sysctl_ctx_init 78function initializes a sysctl context. 79The 80.Fa clist 81argument must point to an already allocated variable. 82A context 83.Em must 84be initialized before use. 85Once it is initialized, 86a pointer to the context can be passed as an argument to all the 87.Fa SYSCTL_ADD_* 88macros (see 89.Xr sysctl_add_oid 9 ) , 90and it will be updated with entries pointing to newly created oids. 91.Pp 92Internally, the context is represented as a 93.Xr queue 3 94TAILQ linked list. 95The list consists of 96.Li struct sysctl_ctx_entry 97entries: 98.Bd -literal -offset indent 99struct sysctl_ctx_entry { 100 struct sysctl_oid *entry; 101 TAILQ_ENTRY(sysctl_ctx_entry) link; 102}; 103 104TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry); 105.Ed 106.Pp 107Each context entry points to one dynamic oid that it manages. 108Newly created oids are always inserted in the front of the list. 109.Pp 110The 111.Fn sysctl_ctx_free 112function removes the context and associated oids it manages. 113If the function completes successfuly, 114all managed oids have been unregistered 115(removed from the tree) 116and freed, 117together with all their allocated memory, 118and the entries of the context have been freed as well. 119.Pp 120The removal operation is performed in two steps. 121First, for each context entry, the function 122.Xr sysctl_remove_oid 9 123is executed, with parameter 124.Fa del 125set to 0, which inhibits the freeing of resources. 126If there are no errors during this step, 127.Fn sysctl_ctx_free 128proceeds to the next step. 129If the first step fails, 130all unregistered oids associated with the context are registered again. 131.Pp 132.Em Note : 133in most cases, the programmer specifies 134.Dv OID_AUTO 135as the oid number when creating an oid. 136However, during registration of the oid in the tree, 137this number is changed to the first available number 138greater than 99. 139If the first step of context deletion fails, 140re-registration of the oid does not change the already assigned oid number 141(which is different from 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 printf("can't free this context - other oids depend on it"); 207 return(ENOTEMPTY); 208} else { 209 printf("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_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 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