share/man/man9/sysctl.9

   1 .\"
   2 .\" Copyright (c) 2006 Robert N. M. Watson
   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 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd October 23, 2015
  29 .Dt SYSCTL 9
  30 .Os
  31 .Sh NAME
  32 .Nm SYSCTL_DECL ,
  33 .Nm SYSCTL_ADD_INT ,
  34 .Nm SYSCTL_ADD_LONG ,
  35 .Nm SYSCTL_ADD_NODE ,
  36 .Nm SYSCTL_ADD_OPAQUE ,
  37 .Nm SYSCTL_ADD_PROC ,
  38 .Nm SYSCTL_ADD_QUAD ,
  39 .Nm SYSCTL_ADD_ROOT_NODE ,
  40 .Nm SYSCTL_ADD_STRING ,
  41 .Nm SYSCTL_ADD_STRUCT ,
  42 .Nm SYSCTL_ADD_U8 ,
  43 .Nm SYSCTL_ADD_U16 ,
  44 .Nm SYSCTL_ADD_UAUTO ,
  45 .Nm SYSCTL_ADD_UINT ,
  46 .Nm SYSCTL_ADD_ULONG ,
  47 .Nm SYSCTL_ADD_UQUAD ,
  48 .Nm SYSCTL_CHILDREN ,
  49 .Nm SYSCTL_STATIC_CHILDREN ,
  50 .Nm SYSCTL_NODE_CHILDREN ,
  51 .Nm SYSCTL_PARENT ,
  52 .Nm SYSCTL_INT ,
  53 .Nm SYSCTL_LONG ,
  54 .Nm SYSCTL_NODE ,
  55 .Nm SYSCTL_OPAQUE ,
  56 .Nm SYSCTL_PROC ,
  57 .Nm SYSCTL_QUAD ,
  58 .Nm SYSCTL_ROOT_NODE ,
  59 .Nm SYSCTL_STRING ,
  60 .Nm SYSCTL_STRUCT ,
  61 .Nm SYSCTL_U8 ,
  62 .Nm SYSCTL_U16 ,
  63 .Nm SYSCTL_UINT ,
  64 .Nm SYSCTL_ULONG ,
  65 .Nm SYSCTL_UQUAD
  66 .Nd Dynamic and static sysctl MIB creation functions
  67 .Sh SYNOPSIS
  68 .In sys/types.h
  69 .In sys/sysctl.h
  70 .Fn SYSCTL_DECL name
  71 .Ft struct sysctl_oid *
  72 .Fo SYSCTL_ADD_INT
  73 .Fa "struct sysctl_ctx_list *ctx"
  74 .Fa "struct sysctl_oid_list *parent"
  75 .Fa "int number"
  76 .Fa "const char *name"
  77 .Fa "int ctlflags"
  78 .Fa "int *ptr"
  79 .Fa "intptr_t val"
  80 .Fa "const char *descr"
  81 .Fc
  82 .Ft struct sysctl_oid *
  83 .Fo SYSCTL_ADD_LONG
  84 .Fa "struct sysctl_ctx_list *ctx"
  85 .Fa "struct sysctl_oid_list *parent"
  86 .Fa "int number"
  87 .Fa "const char *name"
  88 .Fa "int ctlflags"
  89 .Fa "long *ptr"
  90 .Fa "const char *descr"
  91 .Fc
  92 .Ft struct sysctl_oid *
  93 .Fo SYSCTL_ADD_NODE
  94 .Fa "struct sysctl_ctx_list *ctx"
  95 .Fa "struct sysctl_oid_list *parent"
  96 .Fa "int number"
  97 .Fa "const char *name"
  98 .Fa "int ctlflags"
  99 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
 100 .Fa "const char *descr"
 101 .Fc
 102 .Ft struct sysctl_oid *
 103 .Fo SYSCTL_ADD_OPAQUE
 104 .Fa "struct sysctl_ctx_list *ctx"
 105 .Fa "struct sysctl_oid_list *parent"
 106 .Fa "int number"
 107 .Fa "const char *name"
 108 .Fa "int ctlflags"
 109 .Fa "void *ptr"
 110 .Fa "intptr_t len"
 111 .Fa "const char *format"
 112 .Fa "const char *descr"
 113 .Fc
 114 .Ft struct sysctl_oid *
 115 .Fo SYSCTL_ADD_PROC
 116 .Fa "struct sysctl_ctx_list *ctx"
 117 .Fa "struct sysctl_oid_list *parent"
 118 .Fa "int number"
 119 .Fa "const char *name"
 120 .Fa "int ctlflags"
 121 .Fa "void *arg1"
 122 .Fa "intptr_t arg2"
 123 .Fa "int (*handler) (SYSCTL_HANDLERARGS)"
 124 .Fa "const char *format"
 125 .Fa "const char *descr"
 126 .Fc
 127 .Ft struct sysctl_oid *
 128 .Fo SYSCTL_ADD_QUAD
 129 .Fa "struct sysctl_ctx_list *ctx"
 130 .Fa "struct sysctl_oid_list *parent"
 131 .Fa "int number"
 132 .Fa "const char *name"
 133 .Fa "int ctlflags"
 134 .Fa "quad_t *ptr"
 135 .Fa "const char *descr"
 136 .Fc
 137 .Ft struct sysctl_oid *
 138 .Fo SYSCTL_ADD_ROOT_NODE
 139 .Fa "struct sysctl_ctx_list *ctx"
 140 .Fa "int number"
 141 .Fa "const char *name"
 142 .Fa "int ctlflags"
 143 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
 144 .Fa "const char *descr"
 145 .Fc
 146 .Ft struct sysctl_oid *
 147 .Fo SYSCTL_ADD_STRING
 148 .Fa "struct sysctl_ctx_list *ctx"
 149 .Fa "struct sysctl_oid_list *parent"
 150 .Fa "int number"
 151 .Fa "const char *name"
 152 .Fa "int ctlflags"
 153 .Fa "char *ptr"
 154 .Fa "intptr_t len"
 155 .Fa "const char *descr"
 156 .Fc
 157 .Ft struct sysctl_oid *
 158 .Fo SYSCTL_ADD_STRUCT
 159 .Fa "struct sysctl_ctx_list *ctx"
 160 .Fa "struct sysctl_oid_list *parent"
 161 .Fa "int number"
 162 .Fa "const char *name"
 163 .Fa "int ctlflags"
 164 .Fa "void *ptr"
 165 .Fa struct_type
 166 .Fa "const char *descr"
 167 .Fc
 168 .Ft struct sysctl_oid *
 169 .Fo SYSCTL_ADD_U8
 170 .Fa "struct sysctl_ctx_list *ctx"
 171 .Fa "struct sysctl_oid_list *parent"
 172 .Fa "int number"
 173 .Fa "const char *name"
 174 .Fa "int ctlflags"
 175 .Fa "unsigned int *ptr"
 176 .Fa "intptr_t val"
 177 .Fa "const char *descr"
 178 .Fc
 179 .Ft struct sysctl_oid *
 180 .Fo SYSCTL_ADD_U16
 181 .Fa "struct sysctl_ctx_list *ctx"
 182 .Fa "struct sysctl_oid_list *parent"
 183 .Fa "int number"
 184 .Fa "const char *name"
 185 .Fa "int ctlflags"
 186 .Fa "unsigned int *ptr"
 187 .Fa "intptr_t val"
 188 .Fa "const char *descr"
 189 .Fc
 190 .Ft struct sysctl_oid *
 191 .Fo SYSCTL_ADD_UINT
 192 .Fa "struct sysctl_ctx_list *ctx"
 193 .Fa "struct sysctl_oid_list *parent"
 194 .Fa "int number"
 195 .Fa "const char *name"
 196 .Fa "int ctlflags"
 197 .Fa "unsigned int *ptr"
 198 .Fa "intptr_t val"
 199 .Fa "const char *descr"
 200 .Fc
 201 .Ft struct sysctl_oid *
 202 .Fo SYSCTL_ADD_ULONG
 203 .Fa "struct sysctl_ctx_list *ctx"
 204 .Fa "struct sysctl_oid_list *parent"
 205 .Fa "int number"
 206 .Fa "const char *name"
 207 .Fa "int ctlflags"
 208 .Fa "unsigned long *ptr"
 209 .Fa "const char *descr"
 210 .Fc
 211 .Ft struct sysctl_oid *
 212 .Fo SYSCTL_ADD_UQUAD
 213 .Fa "struct sysctl_ctx_list *ctx"
 214 .Fa "struct sysctl_oid_list *parent"
 215 .Fa "int number"
 216 .Fa "const char *name"
 217 .Fa "int ctlflags"
 218 .Fa "u_quad_t *ptr"
 219 .Fa "const char *descr"
 220 .Fc
 221 .Ft struct sysctl_oid *
 222 .Fo SYSCTL_ADD_UAUTO
 223 .Fa "struct sysctl_ctx_list *ctx"
 224 .Fa "struct sysctl_oid_list *parent"
 225 .Fa "int number"
 226 .Fa "const char *name"
 227 .Fa "int ctlflags"
 228 .Fa "void *ptr"
 229 .Fa "const char *descr"
 230 .Fc
 231 .Ft struct sysctl_oid_list *
 232 .Fo SYSCTL_CHILDREN
 233 .Fa "struct sysctl_oid *oidp"
 234 .Fc
 235 .Ft struct sysctl_oid_list *
 236 .Fo SYSCTL_STATIC_CHILDREN
 237 .Fa "struct sysctl_oid_list OID_NAME"
 238 .Fc
 239 .Ft struct sysctl_oid_list *
 240 .Fo SYSCTL_NODE_CHILDREN
 241 .Fa "parent"
 242 .Fa "name"
 243 .Fc
 244 .Ft struct sysctl_oid *
 245 .Fo SYSCTL_PARENT
 246 .Fa "struct sysctl_oid *oid"
 247 .Fc
 248 .Fn SYSCTL_INT parent number name ctlflags ptr val descr
 249 .Fn SYSCTL_LONG parent number name ctlflags ptr val descr
 250 .Fn SYSCTL_NODE parent number name ctlflags handler descr
 251 .Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr
 252 .Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr
 253 .Fn SYSCTL_QUAD parent number name ctlflags ptr val descr
 254 .Fn SYSCTL_STRING parent number name ctlflags arg len descr
 255 .Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr
 256 .Fn SYSCTL_ROOT_NODE number name ctlflags handler descr
 257 .Fn SYSCTL_U8 parent number name ctlflags ptr val descr
 258 .Fn SYSCTL_U16 parent number name ctlflags ptr val descr
 259 .Fn SYSCTL_UINT parent number name ctlflags ptr val descr
 260 .Fn SYSCTL_ULONG parent number name ctlflags ptr val descr
 261 .Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr
 262 .Sh DESCRIPTION
 263 The
 264 .Nm SYSCTL
 265 kernel interface allows dynamic or static creation of
 266 .Xr sysctl 8
 267 MIB entries.
 268 All static sysctls are automatically destroyed when the module which
 269 they are part of is unloaded.
 270 Most top level categories are created statically and are available to
 271 all kernel code and its modules.
 272 .Sh DESCRIPTION OF ARGUMENTS
 273 .Bl -tag -width ctlflags
 274 .It Fa ctx
 275 Pointer to sysctl context or NULL, if no context.
 276 See
 277 .Xr sysctl_ctx_init 9
 278 for how to create a new sysctl context.
 279 Programmers are strongly advised to use contexts to organize the
 280 dynamic OIDs which they create because when a context is destroyed all
 281 belonging sysctls are destroyed as well.
 282 This makes the sysctl cleanup code much simpler.
 283 Else deletion of all created OIDs is required at module unload.
 284 .It Fa parent
 285 A pointer to a
 286 .Li struct sysctl_oid_list ,
 287 which is the head of the parent's list of children.
 288 This pointer is retrieved using the
 289 .Fn SYSCTL_STATIC_CHILDREN
 290 macro for static sysctls and the
 291 .Fn SYSCTL_CHILDREN
 292 macro for dynamic sysctls.
 293 The
 294 .Fn SYSCTL_PARENT
 295 macro can be used to get the parent of an OID.
 296 The macro returns NULL if there is no parent.
 297 .It Fa number
 298 The OID number that will be assigned to this OID.
 299 In almost all cases this should be set to
 300 .Dv OID_AUTO ,
 301 which will result in the assignment of the next available OID number.
 302 .It Fa name
 303 The name of the OID.
 304 The newly created OID will contain a copy of the name.
 305 .It Fa ctlflags
 306 A bit mask of sysctl control flags.
 307 See the section below describing all the control flags.
 308 .It Fa arg1
 309 First callback argument for procedure sysctls.
 310 .It Fa arg2
 311 Second callback argument for procedure sysctls.
 312 .It Fa len
 313 The length of the data pointed to by the
 314 .Fa ptr
 315 argument.
 316 For string type OIDs a length of zero means that
 317 .Xr strlen 3
 318 will be used to get the length of the string at each access to the OID.
 319 .It Fa ptr
 320 Pointer to sysctl variable or string data.
 321 For sysctl values the pointer can be SYSCTL_NULL_XXX_PTR which means the OID is read-only and the returned value should be taken from the
 322 .Fa val
 323 argument.
 324 .It Fa val
 325 If the
 326 .Fa ptr
 327 argument is SYSCTL_NULL_XXX_PTR, gives the constant value returned by this OID.
 328 Else this argument is not used.
 329 .It Fa struct_type
 330 Name of structure type.
 331 .It Fa handler
 332 A pointer to the function
 333 that is responsible for handling read and write requests
 334 to this OID.
 335 There are several standard handlers
 336 that support operations on nodes,
 337 integers, strings and opaque objects.
 338 It is possible to define custom handlers using the
 339 .Fn SYSCTL_PROC
 340 macro or the
 341 .Fn SYSCTL_ADD_PROC
 342 function.
 343 .It Fa format
 344 A pointer to a string
 345 which specifies the format of the OID in a symbolic way.
 346 This format is used as a hint by
 347 .Xr sysctl 8
 348 to apply proper data formatting for display purposes.
 349 .Pp
 350 Current formats:
 351 .Bl -tag -width "S,TYPE" -compact -offset indent
 352 .It Cm N
 353 node
 354 .It Cm A
 355 .Li "char *"
 356 .It Cm I
 357 .Li "int"
 358 .It Cm IK Ns Op Ar n
 359 temperature in Kelvin, multiplied by an optional single digit
 360 power of ten scaling factor: 1 (default) gives deciKelvin, 0 gives Kelvin, 3
 361 gives milliKelvin
 362 .It Cm IU
 363 .Li "unsigned int"
 364 .It Cm L
 365 .Li "long"
 366 .It Cm LU
 367 .Li "unsigned long"
 368 .It Cm Q
 369 .Li "quad_t"
 370 .It Cm QU
 371 .Li "u_quad_t"
 372 .It Cm "S,TYPE"
 373 .Li "struct TYPE"
 374 structures
 375 .El
 376 .It Fa descr
 377 A pointer to a textual description of the OID.
 378 .El
 379 .Sh CREATING ROOT NODES
 380 Sysctl MIBs or OIDs are created in a hierarchical tree.
 381 The nodes at the bottom of the tree are called root nodes, and have no
 382 parent OID.
 383 To create bottom tree nodes the
 384 .Fn SYSCTL_ROOT_NODE
 385 macro or the
 386 .Fn SYSCTL_ADD_ROOT_NODE
 387 function needs to be used.
 388 By default all static sysctl node OIDs are global and need a
 389 .Fn SYSCTL_DECL
 390 statement prior to their
 391 .Fn SYSCTL_NODE
 392 definition statement, typically in a so-called header file.
 393 .Sh CREATING SYSCTL STRINGS
 394 Zero terminated character strings sysctls are created either using the
 395 .Fn SYSCTL_STRING
 396 macro or the
 397 .Fn SYSCTL_ADD_STRING
 398 function.
 399 If the
 400 .Fa len
 401 argument in zero, the string length is computed at every access to the OID using
 402 .Xr strlen 3 .
 403 .Sh CREATING OPAQUE SYSCTLS
 404 The
 405 .Fn SYSCTL_OPAQUE
 406 or
 407 .Fn SYSCTL_STRUCT
 408 macros or the
 409 .Fn SYSCTL_ADD_OPAQUE
 410 or
 411 .Fn SYSCTL_ADD_STRUCT
 412 functions create an OID that handle any chunk of data
 413 of the size specified by the
 414 .Fa len
 415 argument and data pointed to by the
 416 .Fa ptr
 417 argument.
 418 When using the structure version the type is encoded as part of the
 419 created sysctl.
 420 .Sh CREATING CUSTOM SYSCTLS
 421 The
 422 .Fn SYSCTL_PROC
 423 macro and the
 424 .Fn SYSCTL_ADD_PROC
 425 function
 426 create OIDs with the specified
 427 .Pa handler
 428 function.
 429 The handler is responsible for handling all read and write requests to
 430 the OID.
 431 This OID type is especially useful if the kernel data is not easily
 432 accessible, or needs to be processed before exporting.
 433 .Sh CREATING A STATIC SYSCTL
 434 Static sysctls are declared using one of the
 435 .Fn SYSCTL_INT ,
 436 .Fn SYSCTL_LONG ,
 437 .Fn SYSCTL_NODE ,
 438 .Fn SYSCTL_OPAQUE ,
 439 .Fn SYSCTL_PROC ,
 440 .Fn SYSCTL_QUAD ,
 441 .Fn SYSCTL_ROOT_NODE ,
 442 .Fn SYSCTL_STRING ,
 443 .Fn SYSCTL_STRUCT ,
 444 .Fn SYSCTL_U8 ,
 445 .Fn SYSCTL_U16 ,
 446 .Fn SYSCTL_UINT ,
 447 .Fn SYSCTL_ULONG
 448 or
 449 .Fn SYSCTL_UQUAD
 450 macros.
 451 .Sh CREATING A DYNAMIC SYSCTL
 452 Dynamic nodes are created using one of the
 453 .Fn SYSCTL_ADD_INT ,
 454 .Fn SYSCTL_ADD_LONG ,
 455 .Fn SYSCTL_ADD_NODE ,
 456 .Fn SYSCTL_ADD_OPAQUE ,
 457 .Fn SYSCTL_ADD_PROC ,
 458 .Fn SYSCTL_ADD_QUAD ,
 459 .Fn SYSCTL_ADD_ROOT_NODE ,
 460 .Fn SYSCTL_ADD_STRING ,
 461 .Fn SYSCTL_ADD_STRUCT ,
 462 .Fn SYSCTL_ADD_U8 ,
 463 .Fn SYSCTL_ADD_U16 ,
 464 .Fn SYSCTL_ADD_UAUTO ,
 465 .Fn SYSCTL_ADD_UINT ,
 466 .Fn SYSCTL_ADD_ULONG ,
 467 or
 468 .Fn SYSCTL_UQUAD
 469 functions.
 470 See
 471 .Xr sysctl_remove_oid 9
 472 or
 473 .Xr sysctl_ctx_free 9
 474 for more information on how to destroy a dynamically created OID.
 475 .Sh CONTROL FLAGS
 476 For most of the above functions and macros, declaring a type as part
 477 of the access flags is not necessary \[em] however, when declaring a
 478 sysctl implemented by a function, including a type in the access mask
 479 is required:
 480 .Bl -tag -width ".Dv CTLTYPE_NOFETCH"
 481 .It Dv CTLTYPE_NODE
 482 This is a node intended to be a parent for other nodes.
 483 .It Dv CTLTYPE_INT
 484 This is a signed integer.
 485 .It Dv CTLTYPE_STRING
 486 This is a nul-terminated string stored in a character array.
 487 .It Dv CTLTYPE_S64
 488 This is a 64-bit signed integer.
 489 .It Dv CTLTYPE_OPAQUE
 490 This is an opaque data structure.
 491 .It Dv CTLTYPE_STRUCT
 492 Alias for
 493 .Dv CTLTYPE_OPAQUE .
 494 .It Dv CTLTYPE_U8
 495 This is an 8-bit unsigned integer.
 496 .It Dv CTLTYPE_U16
 497 This is a 16-bit unsigned integer.
 498 .It Dv CTLTYPE_UINT
 499 This is an unsigned integer.
 500 .It Dv CTLTYPE_LONG
 501 This is a signed long.
 502 .It Dv CTLTYPE_ULONG
 503 This is an unsigned long.
 504 .It Dv CTLTYPE_U64
 505 This is a 64-bit unsigned integer.
 506 .El
 507 .Pp
 508 All sysctl types except for new node declarations require one of the following
 509 flags to be set indicating the read and write disposition of the sysctl:
 510 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
 511 .It Dv CTLFLAG_RD
 512 This is a read-only sysctl.
 513 .It Dv CTLFLAG_RDTUN
 514 This is a read-only sysctl and tunable which is tried fetched once
 515 from the system enviroment early during module load or system boot.
 516 .It Dv CTLFLAG_WR
 517 This is a writable sysctl.
 518 .It Dv CTLFLAG_RW
 519 This sysctl is readable and writable.
 520 .It Dv CTLFLAG_RWTUN
 521 This is a readable and writeable sysctl and tunable which is tried
 522 fetched once from the system enviroment early during module load or
 523 system boot.
 524 .It Dv CTLFLAG_NOFETCH
 525 In case the node is marked as a tunable using the CTLFLAG_[XX]TUN,
 526 this flag will prevent fetching the initial value from the system
 527 environment. Typically this flag should only be used for very early
 528 low level system setup code, and not by common drivers and modules.
 529 .El
 530 .Pp
 531 Additionally, any of the following optional flags may also be specified:
 532 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
 533 .It Dv CTLFLAG_ANYBODY
 534 Any user or process can write to this sysctl.
 535 .It Dv CTLFLAG_SECURE
 536 This sysctl can be written to only if the effective securelevel of the
 537 process is \[<=] 0.
 538 .It Dv CTLFLAG_PRISON
 539 This sysctl can be written to by processes in
 540 .Xr jail 2 .
 541 .It Dv CTLFLAG_SKIP
 542 When iterating the sysctl name space, do not list this sysctl.
 543 .It Dv CTLFLAG_TUN
 544 Advisory flag that a system tunable also exists for this variable.
 545 The initial sysctl value is tried fetched once from the system
 546 enviroment early during module load or system boot.
 547 .It Dv CTLFLAG_DYN
 548 Dynamically created OIDs automatically get this flag set.
 549 .It Dv CTLFLAG_VNET
 550 OID references a VIMAGE-enabled variable.
 551 .El
 552 .Sh EXAMPLES
 553 Sample use of
 554 .Fn SYSCTL_DECL
 555 to declare the
 556 .Va security
 557 sysctl tree for use by new nodes:
 558 .Bd -literal -offset indent
 559 SYSCTL_DECL(_security);
 560 .Ed
 561 .Pp
 562 Examples of integer, opaque, string, and procedure sysctls follow:
 563 .Bd -literal -offset indent
 564 /*
 565  * Example of a constant integer value.  Notice that the control
 566  * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR,
 567  * and the value is declared.
 568  */
 569 SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR,
 570     sizeof(struct bio), "sizeof(struct bio)");
 571
 572 /*
 573  * Example of a variable integer value.  Notice that the control
 574  * flags are CTLFLAG_RW, the variable pointer is set, and the
 575  * value is 0.
 576  */
 577 static int      doingcache = 1;         /* 1 => enable the cache */
 578 SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0,
 579     "Enable name cache");
 580
 581 /*
 582  * Example of a variable string value.  Notice that the control
 583  * flags are CTLFLAG_RW, that the variable pointer and string
 584  * size are set.  Unlike newer sysctls, this older sysctl uses a
 585  * static oid number.
 586  */
 587 char kernelname[MAXPATHLEN] = "/kernel";        /* XXX bloat */
 588 SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW,
 589     kernelname, sizeof(kernelname), "Name of kernel file booted");
 590
 591 /*
 592  * Example of an opaque data type exported by sysctl.  Notice that
 593  * the variable pointer and size are provided, as well as a format
 594  * string for sysctl(8).
 595  */
 596 static l_fp pps_freq;   /* scaled frequence offset (ns/s) */
 597 SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD,
 598     &pps_freq, sizeof(pps_freq), "I", "");
 599
 600 /*
 601  * Example of a procedure based sysctl exporting string
 602  * information.  Notice that the data type is declared, the NULL
 603  * variable pointer and 0 size, the function pointer, and the
 604  * format string for sysctl(8).
 605  */
 606 SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING |
 607     CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A",
 608     "");
 609 .Ed
 610 .Pp
 611 The following is an example of
 612 how to create a new top-level category
 613 and how to hook up another subtree to an existing static node.
 614 This example does not use contexts,
 615 which results in tedious management of all intermediate oids,
 616 as they need to be freed later on:
 617 .Bd -literal -offset indent
 618 #include <sys/sysctl.h>
 619  ...
 620 /*
 621  * Need to preserve pointers to newly created subtrees,
 622  * to be able to free them later:
 623  */
 624 static struct sysctl_oid *root1;
 625 static struct sysctl_oid *root2;
 626 static struct sysctl_oid *oidp;
 627 static int a_int;
 628 static char *string = "dynamic sysctl";
 629  ...
 630
 631 root1 = SYSCTL_ADD_ROOT_NODE(NULL,
 632         OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree");
 633 oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1),
 634         OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf");
 635  ...
 636 root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug),
 637         OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug");
 638 oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2),
 639         OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf");
 640 .Ed
 641 .Pp
 642 This example creates the following subtrees:
 643 .Bd -literal -offset indent
 644 debug.newtree.newstring
 645 newtree.newint
 646 .Ed
 647 .Pp
 648 .Em "Care should be taken to free all OIDs once they are no longer needed!"
 649 .Sh SYSCTL NAMING
 650 When adding, modifying, or removing sysctl names, it is important to be
 651 aware that these interfaces may be used by users, libraries, applications,
 652 or documentation (such as published books), and are implicitly published application interfaces.
 653 As with other application interfaces, caution must be taken not to break
 654 existing applications, and to think about future use of new name spaces so as
 655 to avoid the need to rename or remove interfaces that might be depended on in
 656 the future.
 657 .Pp
 658 The semantics chosen for a new sysctl should be as clear as possible,
 659 and the name of the sysctl must closely reflect its semantics.
 660 Therefore the sysctl name deserves a fair amount of consideration.
 661 It should be short but yet representative of the sysctl meaning.
 662 If the name consists of several words, they should be separated by
 663 underscore characters, as in
 664 .Va compute_summary_at_mount .
 665 Underscore characters may be omitted only if the name consists of not more
 666 than two words, each being not longer than four characters, as in
 667 .Va bootfile .
 668 For boolean sysctls, negative logic should be totally avoided.
 669 That is, do not use names like
 670 .Va no_foobar
 671 or
 672 .Va foobar_disable .
 673 They are confusing and lead to configuration errors.
 674 Use positive logic instead:
 675 .Va foobar ,
 676 .Va foobar_enable .
 677 .Pp
 678 A temporary sysctl node OID that should not be relied upon must be designated
 679 as such by a leading underscore character in its name. For example:
 680 .Va _dirty_hack .
 681 .Sh SEE ALSO
 682 .Xr sysctl 3 ,
 683 .Xr sysctl 8 ,
 684 .Xr sysctl_add_oid 9 ,
 685 .Xr sysctl_ctx_free 9 ,
 686 .Xr sysctl_ctx_init 9 ,
 687 .Xr sysctl_remove_oid 9
 688 .Sh HISTORY
 689 The
 690 .Xr sysctl 8
 691 utility first appeared in
 692 .Bx 4.4 .
 693 .Sh AUTHORS
 694 .An -nosplit
 695 The
 696 .Nm sysctl
 697 implementation originally found in
 698 .Bx
 699 has been extensively rewritten by
 700 .An Poul-Henning Kamp
 701 in order to add support for name lookups, name space iteration, and dynamic
 702 addition of MIB nodes.
 703 .Pp
 704 This man page was written by
 705 .An Robert N. M. Watson .
 706 .Sh SECURITY CONSIDERATIONS
 707 When creating new sysctls, careful attention should be paid to the security
 708 implications of the monitoring or management interface being created.
 709 Most sysctls present in the kernel are read-only or writable only by the
 710 superuser.
 711 Sysctls exporting extensive information on system data structures and
 712 operation, especially those implemented using procedures, will wish to
 713 implement access control to limit the undesired exposure of information about
 714 other processes, network connections, etc.
 715 .Pp
 716 The following top level sysctl name spaces are commonly used:
 717 .Bl -tag -width ".Va regression"
 718 .It Va compat
 719 Compatibility layer information.
 720 .It Va debug
 721 Debugging information.
 722 Various name spaces exist under
 723 .Va debug .
 724 .It Va hw
 725 Hardware and device driver information.
 726 .It Va kern
 727 Kernel behavior tuning; generally deprecated in favor of more specific
 728 name spaces.
 729 .It Va machdep
 730 Machine-dependent configuration parameters.
 731 .It Va net
 732 Network subsystem.
 733 Various protocols have name spaces under
 734 .Va net .
 735 .It Va regression
 736 Regression test configuration and information.
 737 .It Va security
 738 Security and security-policy configuration and information.
 739 .It Va sysctl
 740 Reserved name space for the implementation of sysctl.
 741 .It Va user
 742 Configuration settings relating to user application behavior.
 743 Generally, configuring applications using kernel sysctls is discouraged.
 744 .It Va vfs
 745 Virtual file system configuration and information.
 746 .It Va vm
 747 Virtual memory subsystem configuration and information.
 748 .El