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: src/share/man/man9/sysctl_add_oid.9,v 1.3.2.10 2001/12/17 11:30:19 ru Exp $
  29 .\" $DragonFly: src/share/man/man9/sysctl_add_oid.9,v 1.2 2003/06/17 04:37:01 dillon Exp $
  30 .\"
  31 .Dd July 15, 2000
  32 .Dt SYSCTL_ADD_OID 9
  33 .Os
  34 .Sh NAME
  35 .Nm sysctl_add_oid ,
  36 .Nm sysctl_remove_oid
  37 .Nd runtime sysctl tree manipulation
  38 .Sh SYNOPSIS
  39 .In sys/sysctl.h
  40 .Ft struct sysctl_oid *
  41 .Fo sysctl_add_oid
  42 .Fa "struct sysctl_ctx_list *ctx"
  43 .Fa "struct sysctl_oid_list *parent"
  44 .Fa "int number"
  45 .Fa "char *name"
  46 .Fa "int kind"
  47 .Fa "void *arg1"
  48 .Fa "int arg2"
  49 .Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
  50 .Fa "char *format"
  51 .Fa "char *descr"
  52 .Fc
  53 .Ft int
  54 .Fo sysctl_remove_oid
  55 .Fa "struct sysctl_oid *oidp"
  56 .Fa "int del"
  57 .Fa "int recurse"
  58 .Fc
  59 .Ft struct sysctl_oid_list *
  60 .Fo SYSCTL_CHILDREN
  61 .Fa "struct sysctl_oid *oidp"
  62 .Fc
  63 .Ft struct sysctl_oid_list *
  64 .Fo SYSCTL_STATIC_CHILDREN
  65 .Fa "OID_NAME"
  66 .Fc
  67 .Ft struct sysctl_oid *
  68 .Fo SYSCTL_ADD_OID
  69 .Fa "struct sysctl_ctx_list *ctx"
  70 .Fa "struct sysctl_oid_list *parent"
  71 .Fa "int number"
  72 .Fa "NAME"
  73 .Fa "int kind"
  74 .Fa "void *arg1"
  75 .Fa "int arg2"
  76 .Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
  77 .Fa "char *format"
  78 .Fa "char *descr"
  79 .Fc
  80 .Ft struct sysctl_oid *
  81 .Fo SYSCTL_ADD_NODE
  82 .Fa "struct sysctl_ctx_list *ctx"
  83 .Fa "struct sysctl_oid_list *parent"
  84 .Fa "int number"
  85 .Fa "NAME"
  86 .Fa "int access"
  87 .Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
  88 .Fa "char *descr"
  89 .Fc
  90 .Ft struct sysctl_oid *
  91 .Fo SYSCTL_ADD_STRING
  92 .Fa "struct sysctl_ctx_list *ctx"
  93 .Fa "struct sysctl_oid_list *parent"
  94 .Fa "int number"
  95 .Fa "NAME"
  96 .Fa "int access"
  97 .Fa "char *arg"
  98 .Fa "0"
  99 .Fa "char *descr"
 100 .Fc
 101 .Ft struct sysctl_oid *
 102 .Fo SYSCTL_ADD_INT
 103 .Fa "struct sysctl_ctx_list *ctx"
 104 .Fa "struct sysctl_oid_list *parent"
 105 .Fa "int number"
 106 .Fa "NAME"
 107 .Fa "int access"
 108 .Fa "int *arg"
 109 .Fa "0"
 110 .Fa "char *descr"
 111 .Fc
 112 .Ft struct sysctl_oid *
 113 .Fo SYSCTL_ADD_UINT
 114 .Fa "struct sysctl_ctx_list *ctx"
 115 .Fa "struct sysctl_oid_list *parent"
 116 .Fa "int number"
 117 .Fa "NAME"
 118 .Fa "int access"
 119 .Fa "unsigned int *arg"
 120 .Fa "0"
 121 .Fa "char *descr"
 122 .Fc
 123 .Ft struct sysctl_oid *
 124 .Fo SYSCTL_ADD_LONG
 125 .Fa "struct sysctl_ctx_list *ctx"
 126 .Fa "struct sysctl_oid_list *parent"
 127 .Fa "int number"
 128 .Fa "NAME"
 129 .Fa "int access"
 130 .Fa "long *arg"
 131 .Fa "0"
 132 .Fa "char *descr"
 133 .Fc
 134 .Ft struct sysctl_oid *
 135 .Fo SYSCTL_ADD_ULONG
 136 .Fa "struct sysctl_ctx_list *ctx"
 137 .Fa "struct sysctl_oid_list *parent"
 138 .Fa "int number"
 139 .Fa "NAME"
 140 .Fa "int access"
 141 .Fa "unsigned long *arg"
 142 .Fa "0"
 143 .Fa "char *descr"
 144 .Fc
 145 .Ft struct sysctl_oid *
 146 .Fo SYSCTL_ADD_OPAQUE
 147 .Fa "struct sysctl_ctx_list *ctx"
 148 .Fa "struct sysctl_oid_list *parent"
 149 .Fa "int number"
 150 .Fa "NAME"
 151 .Fa "int access"
 152 .Fa "void *arg"
 153 .Fa "size_t *len"
 154 .Fa "char *descr"
 155 .Fc
 156 .Ft struct sysctl_oid *
 157 .Fo SYSCTL_ADD_STRUCT
 158 .Fa "struct sysctl_ctx_list *ctx"
 159 .Fa "struct sysctl_oid_list *parent"
 160 .Fa "int number"
 161 .Fa "NAME"
 162 .Fa "int access"
 163 .Fa "struct TYPE *arg"
 164 .Fa "TYPE"
 165 .Fa "char *descr"
 166 .Fc
 167 .Ft struct sysctl_oid *
 168 .Fo SYSCTL_ADD_PROC
 169 .Fa "struct sysctl_ctx_list *ctx"
 170 .Fa "struct sysctl_oid_list *parent"
 171 .Fa "int number"
 172 .Fa "NAME"
 173 .Fa "int access"
 174 .Fa "0"
 175 .Fa "0"
 176 .Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
 177 .Fa "char *format"
 178 .Fa "char *descr"
 179 .Fc
 180 .Sh DESCRIPTION
 181 These functions and macros provide an interface
 182 for creating and deleting sysctl oids at runtime
 183 (e.g. during lifetime of a module).
 184 The alternative method,
 185 based on linker sets (see
 186 .Aq sys/linker_set.h
 187 and
 188 .\" XXX Manual pages should avoid referencing source files
 189 .Pa src/sys/kern/kern_sysctl.c
 190 for details), only allows creation and deletion
 191 on module load and unload respectively.
 192 .Pp
 193 Dynamic oids of type
 194 .Dv CTLTYPE_NODE
 195 are reusable
 196 so that several code sections can create and delete them,
 197 but in reality they are allocated and freed
 198 based on their reference count.
 199 As a consequence,
 200 it is possible for two or more code sections
 201 to create partially overlapping trees that they both can use.
 202 It is not possible to create overlapping leaves,
 203 nor to create different child types with the same name and parent.
 204 .Pp
 205 Newly created oids are connected to their parent nodes.
 206 In all these functions and macros
 207 (with the exception of
 208 .Fn sysctl_remove_oid ) ,
 209 one of the required parameters is
 210 .Fa parent ,
 211 which points to the head of the parent's list of children.
 212 .Pp
 213 Most top level categories are created statically.
 214 When connecting to existing static oids,
 215 this pointer can be obtained with the
 216 .Fn SYSCTL_STATIC_CHILDREN
 217 macro, where the
 218 .Fa OID_NAME
 219 argumwent is name of the parent oid of type
 220 .Dv CTLTYPE_NODE
 221 (i.e. the name displayed by
 222 .Xr sysctl 8 ,
 223 preceded by underscore, and with all dots replaced with underscores).
 224 .Pp
 225 When connecting to an existing dynamic oid, this pointer
 226 can be obtained with the
 227 .Fn SYSCTL_CHILDREN
 228 macro, where the
 229 .Fa oidp
 230 argument points to the parent oid of type
 231 .Dv CTLTYPE_NODE .
 232 .Pp
 233 The
 234 .Fn sysctl_add_oid
 235 function creates raw oids of any type.
 236 If the oid is successfuly created,
 237 the function returns a pointer to it;
 238 otherwise it returns
 239 .Dv NULL .
 240 Many of the arguments for
 241 .Fn sysctl_add_oid
 242 are common to the macros.
 243 The arguments are as follows:
 244 .Bl -tag -width handler
 245 .It Fa ctx
 246 A pointer to an optional sysctl context, or
 247 .Dv NULL .
 248 See
 249 .Xr sysctl_ctx_init 9
 250 for details.
 251 Programmers are strongly advised to use contexts
 252 to organize the dynamic oids which they create,
 253 unless special creation and deletion sequences are required.
 254 If
 255 .Fa ctx
 256 is not
 257 .Dv NULL ,
 258 the newly created oid will be added to this context
 259 as its first entry.
 260 .It Fa parent
 261 A pointer to a
 262 .Li struct sysctl_oid_list ,
 263 which is the head of the parent's list of children.
 264 .It Fa number
 265 The oid number that will be assigned to this oid.
 266 In almost all cases this should be set to
 267 .Dv OID_AUTO ,
 268 which will result in the assignment of the next available oid number.
 269 .It Fa name
 270 The name of the oid.
 271 The newly created oid will contain a copy of the name.
 272 .It Fa kind
 273 The kind of oid,
 274 specified as a bitmask of the type and access values defined in the
 275 .Aq sys/sysctl.h
 276 header file.
 277 Oids created dynamically always have the
 278 .Dv CTLTYPE_DYN
 279 flag set.
 280 Access flags specify whether this oid is read-only or read-write,
 281 and whether it may be modified by all users
 282 or by the supseruser only.
 283 .It Fa arg1
 284 A pointer to any data that the oid should reference, or
 285 .Dv NULL .
 286 .It Fa arg2
 287 The size of
 288 .Fa arg1 ,
 289 or 0 if
 290 .Fa arg1
 291 is
 292 .Dv NULL .
 293 .It Fa handler
 294 A pointer to the function
 295 that is responsible for handling read and write requests
 296 to this oid.
 297 There are several standard handlers
 298 that support operations on nodes,
 299 integers, strings and opaque objects.
 300 It is possible also to define new handlers using the
 301 .Fn SYSCTL_ADD_PROC
 302 macro.
 303 .It Fa format
 304 A pointer to a string
 305 which specifies the format of the oid symbolically.
 306 This format is used as a hint by
 307 .Xr sysctl 8
 308 to apply proper data formatting for display purposes.
 309 Currently used format names are:
 310 .Dq N
 311 for node,
 312 .Dq A
 313 for
 314 .Li "char *" ,
 315 .Dq I
 316 for
 317 .Li "int" ,
 318 .Dq IU
 319 for
 320 .Li "unsigned int" ,
 321 .Dq L
 322 for
 323 .Li "long" ,
 324 .Dq LU
 325 for
 326 .Li "unsigned long"
 327 and
 328 .Dq S,TYPE
 329 for
 330 .Li "struct TYPE"
 331 structures.
 332 .It Fa descr
 333 A pointer to a textual description of the oid.
 334 .El
 335 .Pp
 336 The
 337 .Fn sysctl_remove_oid
 338 function removes a dynamically created oid from the tree,
 339 optionally freeing its resources.
 340 It takes the following arguments:
 341 .Bl -tag -width recurse
 342 .It Fa oidp
 343 A pointer to the dynamic oid to be removed.
 344 If the oid is not dynamic, or the pointer is
 345 .Dv NULL ,
 346 the function returns
 347 .Er EINVAL .
 348 .It Fa del
 349 If non-zero,
 350 .Fn sysctl_remove_oid
 351 will try to free the oid's resources
 352 when the reference count of the oid becomes zero.
 353 However, if
 354 .Fa del
 355 is set to 0,
 356 the routine will only deregister the oid from the tree,
 357 without freeing its resources.
 358 This behaviour is useful when the caller expects to rollback
 359 (possibly partially failed)
 360 deletion of many oids later.
 361 .It Fa recurse
 362 If non-zero, attempt to remove the node and all its children.
 363 If
 364 .Pa recurse
 365 is set to 0,
 366 any attempt to remove a node that contains any children
 367 will result in a
 368 .Er ENOTEMPTY
 369 error.
 370 .Em WARNING : "use recursive deletion with extreme caution" !
 371 Normally it should not be needed if contexts are used.
 372 Contexts take care of tracking inter-dependencies
 373 between users of the tree.
 374 However, in some extreme cases it might be necessary
 375 to remove part of the subtree no matter how it was created,
 376 in order to free some other resources.
 377 Be aware, though, that this may result in a system
 378 .Xr panic 9
 379 if other code sections continue to use removed subtrees.
 380 .El
 381 .Pp
 382 .\" XXX sheldonh finished up to here
 383 Again, in most cases the programmer should use contexts,
 384 as described in
 385 .Xr sysctl_ctx_init 9 ,
 386 to keep track of created oids,
 387 and to delete them later in orderly fashion.
 388 .Pp
 389 There is a set of macros defined
 390 that helps to create oids of given type.
 391 .Bl -tag -width SYSCTL_ADD_STRINGXX
 392 They are as follows:
 393 .It Fn SYSCTL_ADD_OID
 394 creates a raw oid.
 395 This macro is functionally equivalent to the
 396 .Fn sysctl_add_oid
 397 function.
 398 .It Fn SYSCTL_ADD_NODE
 399 creates an oid of type
 400 .Dv CTLTYPE_NODE ,
 401 to which child oids may be added.
 402 .It Fn SYSCTL_ADD_STRING
 403 creates an oid that handles a zero-terminated character string.
 404 .It Fn SYSCTL_ADD_INT
 405 creates an oid that handles an
 406 .Li int
 407 variable.
 408 .It Fn SYSCTL_ADD_UINT
 409 creates an oid that handles an
 410 .Li unsigned int
 411 variable.
 412 .It Fn SYSCTL_ADD_LONG
 413 creates an oid that handles a
 414 .Li long
 415 variable.
 416 .It Fn SYSCTL_ADD_ULONG
 417 creates an oid that handles an
 418 .Li unsigned long
 419 variable.
 420 .It Fn SYSCTL_ADD_OPAQUE
 421 creates an oid that handles any chunk of opaque data
 422 of the size specified by the
 423 .Fa len
 424 argument,
 425 which is a pointer to a
 426 .Li "size_t *" .
 427 .It Fn SYSCTL_ADD_STRUCT
 428 creates an oid that handles a
 429 .Li "struct TYPE"
 430 structure.
 431 The
 432 .Fa format
 433 parameter will be set to
 434 .Dq S,TYPE
 435 to provide proper hints to the
 436 .Xr sysctl 8
 437 utility.
 438 .It Fn SYSCTL_ADD_PROC
 439 creates an oid with the specified
 440 .Pa handler
 441 function.
 442 The handler is responsible for handling read and write requests
 443 to the oid.
 444 This oid type is especially useful
 445 if the kernel data is not easily accessible,
 446 or needs to be processed before exporting.
 447 .El
 448 .Sh EXAMPLES
 449 The following is an example of
 450 how to create a new top-level category
 451 and how to hook up another subtree to an existing static node.
 452 This example does not use contexts,
 453 which results in tedious management of all intermediate oids,
 454 as they need to be freed later on:
 455 .Bd -literal
 456 #include <sys/sysctl.h>
 457  ...
 458 /* Need to preserve pointers to newly created subtrees, to be able
 459  * to free them later.
 460  */
 461 struct sysctl_oid *root1, *root2, *oidp;
 462 int a_int;
 463 char *string = "dynamic sysctl";
 464  ...
 465
 466 root1 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(/* tree top */),
 467         OID_AUTO, newtree, CTFLAG_RW, 0, "new top level tree");
 468 oidp = SYSCTL_ADD_INT( NULL, SYSCTL_CHILDREN(root1),
 469         OID_AUTO, newint, CTLFLAG_RW, &a_int, 0, "new int leaf");
 470  ...
 471 root2 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(_debug),
 472         OID_AUTO, newtree, CTFLAG_RW, 0, "new tree under debug");
 473 oidp = SYSCTL_ADD_STRING( NULL, SYSCTL_CHILDREN(root2),
 474         OID_AUTO, newstring, CTLFLAG_R, string, 0, "new string leaf");
 475 .Ed
 476 .Pp
 477 This example creates the following subtrees:
 478 .Bd -literal -offset indent
 479 debug.newtree.newstring
 480 newtree.newint
 481 .Ed
 482 .Pp
 483 .Em "Care should be taken to free all oids once they are no longer needed!"
 484 .Sh SEE ALSO
 485 .Xr sysctl 8 ,
 486 .Xr sysctl_ctx_free 9 ,
 487 .Xr sysctl_ctx_init 9
 488 .Sh HISTORY
 489 These functions first appeared in
 490 .Fx 4.2 .
 491 .Sh AUTHORS
 492 .An Andrzej Bialecki Aq abial@FreeBSD.org
 493 .Sh BUGS
 494 Sharing nodes between many code sections
 495 causes interdependencies that sometimes may lock the resources.
 496 For example,
 497 if module A hooks up a subtree to an oid created by module B,
 498 module B will be unable to delete that oid.
 499 These issues are handled properly by sysctl contexts.
 500 .Pp
 501 Many operations on the tree involve traversing linked lists.
 502 For this reason, oid creation and removal is relatively costly.