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 .\" $DragonFly: src/share/man/man9/sysctl_ctx_init.9,v 1.2 2003/06/17 04:37:01 dillon Exp $
  30 .\"
  31 .Dd July 15, 2000
  32 .Dt SYSCTL_CTX_INIT 9
  33 .Os
  34 .Sh NAME
  35 .Nm sysctl_ctx_init ,
  36 .Nm sysctl_ctx_free ,
  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"
  41 .Sh SYNOPSIS
  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 successfuly,
 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 99.
 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 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         printf("can't free this context - other oids depend on it");
 207         return(ENOTEMPTY);
 208 } else {
 209         printf("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_add_oid 9 ,
 229 .Xr sysctl_remove_oid 9
 230 .Sh HISTORY
 231 These functions first appeared in
 232 .Fx 4.2 .
 233 .Sh AUTHORS
 234 .An Andrzej Bialecki Aq abial@FreeBSD.org
 235 .Sh BUGS
 236 The current removal algorithm is somewhat heavy.
 237 In the worst case,
 238 all oids need to be unregistered, registered again,
 239 and then unregistered and deleted.
 240 However, the algorithm does guarantee transactional properties
 241 for removal operations.
 242 .Pp
 243 All operations on contexts involve linked list traversal.
 244 For this reason,
 245 creation and removal of entries is relatively costly.