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