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