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