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 Jul 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.Fd #include <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 successfuly, 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 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 173witin 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 ... 186struct sysctl_ctx_list clist; 187struct sysctl_oid *oidp; 188int a_int; 189char *string = "dynamic sysctl"; 190 ... 191 192sysctl_ctx_init(&clist); 193oidp = SYSCTL_ADD_NODE( &clist, SYSCTL_STATIC_CHILDREN(/* tree top */), 194 OID_AUTO, newtree, CTFLAG_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, CTFLAG_RW, 0, "new tree under debug"); 200oidp = SYSCTL_ADD_STRING( &clist, SYSCTL_CHILDREN(oidp), 201 OID_AUTO, newstring, CTLFLAG_R, 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_add_oid 9 , 228.Xr sysctl_remove_oid 9 229.Sh HISTORY 230These functions first appeared in 231.Fx 5.0 . 232.Sh AUTHORS 233.An Andrzej Bialecki Aq abial@FreeBSD.org 234.Sh BUGS 235The current removal algorithm is somewhat heavy. 236In the worst case, 237all oids need to be unregistered, registered again, 238and then unregistered and deleted. 239However, the algorithm does guarantee transactional properties 240for removal operations. 241.Pp 242All operations on contexts involve linked list traversal. 243For this reason, 244creation and removal of entries is relatively costly. 245