share/man/man9/sysctl_ctx_init.9

   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
  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.
  75 .Pp
  76 The
  77 .Fn sysctl_ctx_init
  78 function initializes a sysctl context.
  79 The
  80 .Fa clist
  81 argument must point to an already allocated variable.
  82 A context
  83 .Em must
  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
  87 .Fa SYSCTL_ADD_*
  88 macros (see
  89 .Xr sysctl_add_oid 9 ) ,
  90 and it will be updated with entries pointing to newly created oids.
  91 .Pp
  92 Internally, the context is represented as a
  93 .Xr queue 3
  94 TAILQ linked list.
  95 The list consists of
  96 .Li struct sysctl_ctx_entry
  97 entries:
  98 .Bd -literal -offset indent
  99 struct sysctl_ctx_entry {
 100         struct sysctl_oid *entry;
 101         TAILQ_ENTRY(sysctl_ctx_entry) link;
 102 };
 103
 104 TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry);
 105 .Ed
 106 .Pp
 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.
 109 .Pp
 110 The
 111 .Fn sysctl_ctx_free
 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)
 116 and freed,
 117 together with all their allocated memory,
 118 and the entries of the context have been freed as well.
 119 .Pp
 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
 124 .Fa del
 125 set to 0, which inhibits the freeing of resources.
 126 If there are no errors during this step,
 127 .Fn sysctl_ctx_free
 128 proceeds to the next step.
 129 If the first step fails,
 130 all unregistered oids associated with the context are registered again.
 131 .Pp
 132 .Em Note :
 133 in most cases, the programmer specifies
 134 .Dv OID_AUTO
 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
 138 greater than or equal to
 139 .Dv CTL_AUTO_START .
 140 If the first step of context deletion fails,
 141 re-registration of the oid does not change the already assigned oid number
 142 (which is different from OID_AUTO).
 143 This ensures that re-registered entries
 144 maintain their original positions in the tree.
 145 .Pp
 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).
 150 .Em Important :
 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.
 154 .Pp
 155 The
 156 .Fn sysctl_ctx_entry_add
 157 function allows the addition of an existing dynamic oid to a context.
 158 .Pp
 159 The
 160 .Fn sysctl_ctx_entry_del
 161 function removes an entry from the context.
 162 .Em Important :
 163 in this case, only the corresponding
 164 .Li struct sysctl_ctx_entry
 165 is freed, but the
 166 .Fa oidp
 167 pointer remains intact.
 168 Thereafter, the programmer is responsible for managing the resources
 169 allocated to this oid.
 170 .Pp
 171 The
 172 .Fn sysctl_ctx_entry_find
 173 function searches for a given
 174 .Fa oidp
 175 within a context list,
 176 either returning a pointer to the
 177 .Fa struct sysctl_ctx_entry
 178 found,
 179 or
 180 .Dv NULL .
 181 .Sh EXAMPLES
 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.
 185 .Bd -literal
 186 #include <sys/sysctl.h>
 187  ...
 188 struct sysctl_ctx_list clist;
 189 struct sysctl_oid *oidp;
 190 int a_int;
 191 const char *string = "dynamic sysctl";
 192  ...
 193
 194 sysctl_ctx_init(&clist);
 195 oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(/* tree top */),
 196         OID_AUTO, "newtree", CTLFLAG_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");
 199  ...
 200 oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(_debug),
 201         OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug");
 202 oidp = 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 */
 206 if (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
 215 This example creates the following subtrees:
 216 .Bd -literal -offset indent
 217 debug.newtree.newstring
 218 newtree.newint
 219 .Ed
 220 .Pp
 221 Note that both trees are removed, and their resources freed,
 222 through one
 223 .Fn sysctl_ctx_free
 224 call, which starts by freeing the newest entries (leaves)
 225 and 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
 233 These functions first appeared in
 234 .Fx 4.2 .
 235 .Sh AUTHORS
 236 .An Andrzej Bialecki Aq abial@FreeBSD.org
 237 .Sh BUGS
 238 The current removal algorithm is somewhat heavy.
 239 In the worst case,
 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.
 244 .Pp
 245 All operations on contexts involve linked list traversal.
 246 For this reason,
 247 creation and removal of entries is relatively costly.