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: src/share/man/man9/sysctl_ctx_init.9,v 1.2.2.6 2001/12/17 11:30:19 ru Exp $
  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/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
  66 These functions provide an interface
  67 for managing dynamically created oids.
  68 The sysctl context is responsible for keeping track of created oids,
  69 as well as their proper removal when needed.
  70 It adds a simple transactional aspect to oid removal operations;
  71 i.e. if a removal operation fails part way,
  72 it is possible to roll back the sysctl tree
  73 to its previous state.
  74 .Pp
  75 The
  76 .Fn sysctl_ctx_init
  77 function initializes a sysctl context.
  78 The
  79 .Fa clist
  80 argument must point to an already allocated variable.
  81 A context
  82 .Em must
  83 be initialized before use.
  84 Once it is initialized,
  85 a pointer to the context can be passed as an argument to all the
  86 .Fa SYSCTL_ADD_*
  87 macros (see
  88 .Xr sysctl_add_oid 9 ) ,
  89 and it will be updated with entries pointing to newly created oids.
  90 .Pp
  91 Internally, the context is represented as a
  92 .Xr queue 3
  93 TAILQ linked list.
  94 The list consists of
  95 .Li struct sysctl_ctx_entry
  96 entries:
  97 .Bd -literal -offset indent
  98 struct sysctl_ctx_entry {
  99         struct sysctl_oid *entry;
 100         TAILQ_ENTRY(sysctl_ctx_entry) link;
 101 };
 102
 103 TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry);
 104 .Ed
 105 .Pp
 106 Each context entry points to one dynamic oid that it manages.
 107 Newly created oids are always inserted in the front of the list.
 108 .Pp
 109 The
 110 .Fn sysctl_ctx_free
 111 function removes the context and associated oids it manages.
 112 If the function completes successfully,
 113 all managed oids have been unregistered
 114 (removed from the tree)
 115 and freed,
 116 together with all their allocated memory,
 117 and the entries of the context have been freed as well.
 118 .Pp
 119 The removal operation is performed in two steps.
 120 First, for each context entry, the function
 121 .Xr sysctl_remove_oid 9
 122 is executed, with parameter
 123 .Fa del
 124 set to 0, which inhibits the freeing of resources.
 125 If there are no errors during this step,
 126 .Fn sysctl_ctx_free
 127 proceeds to the next step.
 128 If the first step fails,
 129 all unregistered oids associated with the context are registered again.
 130 .Pp
 131 .Em Note :
 132 in most cases, the programmer specifies
 133 .Dv OID_AUTO
 134 as the oid number when creating an oid.
 135 However, during registration of the oid in the tree,
 136 this number is changed to the first available number
 137 greater than 99.
 138 If the first step of context deletion fails,
 139 re-registration of the oid does not change the already assigned oid number
 140 (which is different from
 141 .Dv OID_AUTO ) .
 142 This ensures that re-registered entries
 143 maintain their original positions in the tree.
 144 .Pp
 145 The second step actually performs the deletion of the dynamic oids.
 146 .Xr sysctl_remove_oid 9
 147 iterates through the context list,
 148 starting from beginning (i.e. the newest entries).
 149 .Em Important :
 150 this time, the function not only deletes the oids from the tree,
 151 but also frees their memory (provided that oid_refcnt == 0),
 152 as well as the memory of all context entries.
 153 .Pp
 154 The
 155 .Fn sysctl_ctx_entry_add
 156 function allows the addition of an existing dynamic oid to a context.
 157 .Pp
 158 The
 159 .Fn sysctl_ctx_entry_del
 160 function removes an entry from the context.
 161 .Em Important :
 162 in this case, only the corresponding
 163 .Li struct sysctl_ctx_entry
 164 is freed, but the
 165 .Fa oidp
 166 pointer remains intact.
 167 Thereafter, the programmer is responsible for managing the resources
 168 allocated to this oid.
 169 .Pp
 170 The
 171 .Fn sysctl_ctx_entry_find
 172 function searches for a given
 173 .Fa oidp
 174 witin a context list,
 175 either returning a pointer to the
 176 .Fa struct sysctl_ctx_entry
 177 found,
 178 or
 179 .Dv NULL .
 180 .Sh EXAMPLES
 181 The following is an example of how to create a new top-level category
 182 and how to hook up another subtree to an existing static node.
 183 This example uses contexts to keep track of the oids.
 184 .Bd -literal
 185 #include <sys/sysctl.h>
 186  ...
 187 struct sysctl_ctx_list clist;
 188 struct sysctl_oid *oidp;
 189 int a_int;
 190 char *string = "dynamic sysctl";
 191  ...
 192
 193 sysctl_ctx_init(&clist);
 194 oidp = SYSCTL_ADD_NODE( &clist, SYSCTL_STATIC_CHILDREN(/* tree top */),
 195         OID_AUTO, newtree, CTFLAG_RW, 0, "new top level tree");
 196 oidp = SYSCTL_ADD_INT( &clist, SYSCTL_CHILDREN(oidp),
 197         OID_AUTO, newint, CTLFLAG_RW, &a_int, 0, "new int leaf");
 198  ...
 199 oidp = SYSCTL_ADD_NODE( &clist, SYSCTL_STATIC_CHILDREN(_debug),
 200         OID_AUTO, newtree, CTFLAG_RW, 0, "new tree under debug");
 201 oidp = 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 */
 205 if(sysctl_ctx_free(&clist)) {
 206         kprintf("can't free this context - other oids depend on it");
 207         return(ENOTEMPTY);
 208 } else {
 209         kprintf("Success!\\n"):
 210         return(0);
 211 }
 212 .Ed
 213 .Pp
 214 This example creates the following subtrees:
 215 .Bd -literal -offset indent
 216 debug.newtree.newstring
 217 newtree.newint
 218 .Ed
 219 .Pp
 220 Note that both trees are removed, and their resources freed,
 221 through one
 222 .Fn sysctl_ctx_free
 223 call, which starts by freeing the newest entries (leaves)
 224 and 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 9 ,
 229 .Xr sysctl_add_oid 9 ,
 230 .Xr sysctl_remove_oid 9
 231 .Sh HISTORY
 232 These functions first appeared in
 233 .Fx 4.2 .
 234 .Sh AUTHORS
 235 .An Andrzej Bialecki Aq Mt abial@FreeBSD.org
 236 .Sh BUGS
 237 The current removal algorithm is somewhat heavy.
 238 In the worst case,
 239 all oids need to be unregistered, registered again,
 240 and then unregistered and deleted.
 241 However, the algorithm does guarantee transactional properties
 242 for removal operations.
 243 .Pp
 244 All operations on contexts involve linked list traversal.
 245 For this reason,
 246 creation and removal of entries is relatively costly.