2 .\" Copyright (c) 2000, Andrzej Bialecki <abial@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
28 .\" $FreeBSD: src/share/man/man9/sysctl_ctx_init.9,v 1.2.2.6 2001/12/17 11:30:19 ru Exp $
29 .\" $DragonFly: src/share/man/man9/sysctl_ctx_init.9,v 1.5 2007/05/17 08:19:02 swildner Exp $
37 .Nm sysctl_ctx_entry_add ,
38 .Nm sysctl_ctx_entry_find ,
39 .Nm sysctl_ctx_entry_del
40 .Nd "sysctl context for managing dynamically created sysctl oids"
45 .Fa "struct sysctl_ctx_list *clist"
49 .Fa "struct sysctl_ctx_list *clist"
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"
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"
62 .Fo sysctl_ctx_entry_del
63 .Fa "struct sysctl_ctx_list *clist"
64 .Fa "struct sysctl_oid *oidp"
67 These functions provide an interface
68 for managing dynamically created oids.
69 The sysctl context is responsible for keeping track of created oids,
70 as well as their proper removal when needed.
71 It adds a simple transactional aspect to oid removal operations;
72 i.e. if a removal operation fails part way,
73 it is possible to roll back the sysctl tree
74 to its previous state.
78 function initializes a sysctl context.
81 argument must point to an already allocated variable.
84 be initialized before use.
85 Once it is initialized,
86 a pointer to the context can be passed as an argument to all the
89 .Xr sysctl_add_oid 9 ) ,
90 and it will be updated with entries pointing to newly created oids.
92 Internally, the context is represented as a
96 .Li struct sysctl_ctx_entry
98 .Bd -literal -offset indent
99 struct sysctl_ctx_entry {
100 struct sysctl_oid *entry;
101 TAILQ_ENTRY(sysctl_ctx_entry) link;
104 TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry);
107 Each context entry points to one dynamic oid that it manages.
108 Newly created oids are always inserted in the front of the list.
112 function removes the context and associated oids it manages.
113 If the function completes successfully,
114 all managed oids have been unregistered
115 (removed from the tree)
117 together with all their allocated memory,
118 and the entries of the context have been freed as well.
120 The removal operation is performed in two steps.
121 First, for each context entry, the function
122 .Xr sysctl_remove_oid 9
123 is executed, with parameter
125 set to 0, which inhibits the freeing of resources.
126 If there are no errors during this step,
128 proceeds to the next step.
129 If the first step fails,
130 all unregistered oids associated with the context are registered again.
133 in most cases, the programmer specifies
135 as the oid number when creating an oid.
136 However, during registration of the oid in the tree,
137 this number is changed to the first available number
139 If the first step of context deletion fails,
140 re-registration of the oid does not change the already assigned oid number
141 (which is different from
143 This ensures that re-registered entries
144 maintain their original positions in the tree.
146 The second step actually performs the deletion of the dynamic oids.
147 .Xr sysctl_remove_oid 9
148 iterates through the context list,
149 starting from beginning (i.e. the newest entries).
151 this time, the function not only deletes the oids from the tree,
152 but also frees their memory (provided that oid_refcnt == 0),
153 as well as the memory of all context entries.
156 .Fn sysctl_ctx_entry_add
157 function allows the addition of an existing dynamic oid to a context.
160 .Fn sysctl_ctx_entry_del
161 function removes an entry from the context.
163 in this case, only the corresponding
164 .Li struct sysctl_ctx_entry
167 pointer remains intact.
168 Thereafter, the programmer is responsible for managing the resources
169 allocated to this oid.
172 .Fn sysctl_ctx_entry_find
173 function searches for a given
175 witin a context list,
176 either returning a pointer to the
177 .Fa struct sysctl_ctx_entry
182 The following is an example of how to create a new top-level category
183 and how to hook up another subtree to an existing static node.
184 This example uses contexts to keep track of the oids.
186 #include <sys/sysctl.h>
188 struct sysctl_ctx_list clist;
189 struct sysctl_oid *oidp;
191 char *string = "dynamic sysctl";
194 sysctl_ctx_init(&clist);
195 oidp = SYSCTL_ADD_NODE( &clist, SYSCTL_STATIC_CHILDREN(/* tree top */),
196 OID_AUTO, newtree, CTFLAG_RW, 0, "new top level tree");
197 oidp = SYSCTL_ADD_INT( &clist, SYSCTL_CHILDREN(oidp),
198 OID_AUTO, newint, CTLFLAG_RW, &a_int, 0, "new int leaf");
200 oidp = SYSCTL_ADD_NODE( &clist, SYSCTL_STATIC_CHILDREN(_debug),
201 OID_AUTO, newtree, CTFLAG_RW, 0, "new tree under debug");
202 oidp = SYSCTL_ADD_STRING( &clist, SYSCTL_CHILDREN(oidp),
203 OID_AUTO, newstring, CTLFLAG_R, string, 0, "new string leaf");
205 /* Now we can free up the oids */
206 if(sysctl_ctx_free(&clist)) {
207 kprintf("can't free this context - other oids depend on it");
210 kprintf("Success!\\n"):
215 This example creates the following subtrees:
216 .Bd -literal -offset indent
217 debug.newtree.newstring
221 Note that both trees are removed, and their resources freed,
224 call, which starts by freeing the newest entries (leaves)
225 and then proceeds to free the older entries (in this case the nodes).
230 .Xr sysctl_add_oid 9 ,
231 .Xr sysctl_remove_oid 9
233 These functions first appeared in
236 .An Andrzej Bialecki Aq abial@FreeBSD.org
238 The current removal algorithm is somewhat heavy.
240 all oids need to be unregistered, registered again,
241 and then unregistered and deleted.
242 However, the algorithm does guarantee transactional properties
243 for removal operations.
245 All operations on contexts involve linked list traversal.
247 creation and removal of entries is relatively costly.