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_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 successfully, 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 or equal to 139.Dv CTL_AUTO_START . 140If the first step of context deletion fails, 141re-registration of the OID does not change the already assigned OID number 142(which is different from OID_AUTO). 143This ensures that re-registered entries 144maintain their original positions in the tree. 145.Pp 146The second step actually performs the deletion of the dynamic OIDs. 147.Xr sysctl_remove_oid 9 148iterates through the context list, 149starting from beginning (i.e., the newest entries). 150.Em Important : 151this time, the function not only deletes the OIDs from the tree, 152but also frees their memory (provided that oid_refcnt == 0), 153as well as the memory of all context entries. 154.Pp 155The 156.Fn sysctl_ctx_entry_add 157function allows the addition of an existing dynamic OID to a context. 158.Pp 159The 160.Fn sysctl_ctx_entry_del 161function removes an entry from the context. 162.Em Important : 163in this case, only the corresponding 164.Li struct sysctl_ctx_entry 165is freed, but the 166.Fa oidp 167pointer remains intact. 168Thereafter, the programmer is responsible for managing the resources 169allocated to this OID. 170.Pp 171The 172.Fn sysctl_ctx_entry_find 173function searches for a given 174.Fa oidp 175within a context list, 176either returning a pointer to the 177.Fa struct sysctl_ctx_entry 178found, 179or 180.Dv NULL . 181.Sh EXAMPLES 182The following is an example of how to create a new top-level category 183and how to hook up another subtree to an existing static node. 184This example uses contexts to keep track of the OIDs. 185.Bd -literal 186#include <sys/sysctl.h> 187 ... 188static struct sysctl_ctx_list clist; 189static struct sysctl_oid *oidp; 190static int a_int; 191static const char *string = "dynamic sysctl"; 192 ... 193 194sysctl_ctx_init(&clist); 195oidp = SYSCTL_ADD_ROOT_NODE(&clist, 196 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); 197oidp = SYSCTL_ADD_INT(&clist, SYSCTL_CHILDREN(oidp), 198 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); 199 ... 200oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(_debug), 201 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); 202oidp = SYSCTL_ADD_STRING(&clist, SYSCTL_CHILDREN(oidp), 203 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); 204 ... 205/* Now we can free up the OIDs */ 206if (sysctl_ctx_free(&clist)) { 207 printf("can't free this context - other OIDs depend on it"); 208 return (ENOTEMPTY); 209} else { 210 printf("Success!\\n"); 211 return (0); 212} 213.Ed 214.Pp 215This example creates the following subtrees: 216.Bd -literal -offset indent 217debug.newtree.newstring 218newtree.newint 219.Ed 220.Pp 221Note that both trees are removed, and their resources freed, 222through one 223.Fn sysctl_ctx_free 224call, which starts by freeing the newest entries (leaves) 225and then proceeds to free the older entries (in this case the nodes). 226.Sh SEE ALSO 227.Xr queue 3 , 228.Xr sysctl 8 , 229.Xr sysctl 9 , 230.Xr sysctl_add_oid 9 , 231.Xr sysctl_remove_oid 9 232.Sh HISTORY 233These functions first appeared in 234.Fx 4.2 . 235.Sh AUTHORS 236.An Andrzej Bialecki Aq Mt abial@FreeBSD.org 237.Sh BUGS 238The current removal algorithm is somewhat heavy. 239In the worst case, 240all OIDs need to be unregistered, registered again, 241and then unregistered and deleted. 242However, the algorithm does guarantee transactional properties 243for removal operations. 244.Pp 245All operations on contexts involve linked list traversal. 246For this reason, 247creation and removal of entries is relatively costly. 248