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