share/man/man9/sysctl_add_oid.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 August 28, 2014
  31 .Dt SYSCTL_ADD_OID 9
  32 .Os
  33 .Sh NAME
  34 .Nm sysctl_add_oid ,
  35 .Nm sysctl_move_oid ,
  36 .Nm sysctl_remove_oid ,
  37 .Nm sysctl_remove_name
  38 .Nd runtime sysctl tree manipulation
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In sys/sysctl.h
  42 .Ft struct sysctl_oid *
  43 .Fo sysctl_add_oid
  44 .Fa "struct sysctl_ctx_list *ctx"
  45 .Fa "struct sysctl_oid_list *parent"
  46 .Fa "int number"
  47 .Fa "const char *name"
  48 .Fa "int kind"
  49 .Fa "void *arg1"
  50 .Fa "intptr_t arg2"
  51 .Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
  52 .Fa "const char *format"
  53 .Fa "const char *descr"
  54 .Fc
  55 .Ft int
  56 .Fo sysctl_move_oid
  57 .Fa "struct sysctl_oid *oidp"
  58 .Fa "struct sysctl_oid_list *parent"
  59 .Fc
  60 .Ft int
  61 .Fo sysctl_remove_oid
  62 .Fa "struct sysctl_oid *oidp"
  63 .Fa "int del"
  64 .Fa "int recurse"
  65 .Fc
  66 .Ft int
  67 .Fo sysctl_remove_name
  68 .Fa "struct sysctl_oid *oidp"
  69 .Fa "const char *name"
  70 .Fa "int del"
  71 .Fa "int recurse"
  72 .Fc
  73 .Sh DESCRIPTION
  74 These functions provide the interface for creating and deleting sysctl
  75 OIDs at runtime for example during the lifetime of a module.
  76 The wrapper macros defined by
  77 .Xr sysctl 9
  78 are recommended when creating new OIDs.
  79 .Fn sysctl_add_oid
  80 should not be called directly from the code.
  81 .Pp
  82 Dynamic OIDs of type
  83 .Dv CTLTYPE_NODE
  84 are reusable
  85 so that several code sections can create and delete them,
  86 but in reality they are allocated and freed
  87 based on their reference count.
  88 As a consequence,
  89 it is possible for two or more code sections
  90 to create partially overlapping trees that they both can use.
  91 It is not possible to create overlapping leaves,
  92 nor to create different child types with the same name and parent.
  93 .Pp
  94 The
  95 .Fn sysctl_add_oid
  96 function creates a raw OID of any type and connects it to its parent node, if any.
  97 If the OID is successfully created,
  98 the function returns a pointer to it else
  99 it returns
 100 .Dv NULL .
 101 Many of the arguments for
 102 .Fn sysctl_add_oid
 103 are common to the wrapper macros defined by
 104 .Xr sysctl 9 .
 105 .Pp
 106 The
 107 .Fn sysctl_move_oid
 108 function reparents an existing OID.
 109 The OID is assigned a new number as if it had been created with
 110 .Fa number
 111 set to
 112 .Dv OID_AUTO .
 113 .Pp
 114 The
 115 .Fn sysctl_remove_oid
 116 function removes a dynamically created OID from the tree and
 117 optionally freeing its resources.
 118 It takes the following arguments:
 119 .Bl -tag -width recurse
 120 .It Fa oidp
 121 A pointer to the dynamic OID to be removed.
 122 If the OID is not dynamic, or the pointer is
 123 .Dv NULL ,
 124 the function returns
 125 .Er EINVAL .
 126 .It Fa del
 127 If non-zero,
 128 .Fn sysctl_remove_oid
 129 will try to free the OID's resources
 130 when the reference count of the OID becomes zero.
 131 However, if
 132 .Fa del
 133 is set to 0,
 134 the routine will only deregister the OID from the tree,
 135 without freeing its resources.
 136 This behaviour is useful when the caller expects to rollback
 137 (possibly partially failed)
 138 deletion of many OIDs later.
 139 .It Fa recurse
 140 If non-zero, attempt to remove the node and all its children.
 141 If
 142 .Pa recurse
 143 is set to 0,
 144 any attempt to remove a node that contains any children
 145 will result in a
 146 .Er ENOTEMPTY
 147 error.
 148 .Em WARNING : "use recursive deletion with extreme caution" !
 149 Normally it should not be needed if contexts are used.
 150 Contexts take care of tracking inter-dependencies
 151 between users of the tree.
 152 However, in some extreme cases it might be necessary
 153 to remove part of the subtree no matter how it was created,
 154 in order to free some other resources.
 155 Be aware, though, that this may result in a system
 156 .Xr panic 9
 157 if other code sections continue to use removed subtrees.
 158 .El
 159 .Pp
 160 The
 161 .Fn sysctl_remove_name
 162 function looks up the child node matching the
 163 .Fa name
 164 argument and then invokes the
 165 .Fn sysctl_remove_oid
 166 function on that node, passing along the
 167 .Fa del
 168 and
 169 .Fa recurse
 170 arguments.
 171 If a node having the specified name does not exist an error code of
 172 .Er ENOENT
 173 is returned.
 174 Else the error code from
 175 .Fn sysctl_remove_oid
 176 is returned.
 177 .Pp
 178 In most cases the programmer should use contexts,
 179 as described in
 180 .Xr sysctl_ctx_init 9 ,
 181 to keep track of created OIDs,
 182 and to delete them later in orderly fashion.
 183 .Sh SEE ALSO
 184 .Xr sysctl 8 ,
 185 .Xr sysctl 9 ,
 186 .Xr sysctl_ctx_free 9 ,
 187 .Xr sysctl_ctx_init 9
 188 .Sh HISTORY
 189 These functions first appeared in
 190 .Fx 4.2 .
 191 .Sh AUTHORS
 192 .An Andrzej Bialecki Aq Mt abial@FreeBSD.org
 193 .Sh BUGS
 194 Sharing nodes between many code sections
 195 causes interdependencies that sometimes may lock the resources.
 196 For example,
 197 if module A hooks up a subtree to an OID created by module B,
 198 module B will be unable to delete that OID.
 199 These issues are handled properly by sysctl contexts.
 200 .Pp
 201 Many operations on the tree involve traversing linked lists.
 202 For this reason, OID creation and removal is relatively costly.