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