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