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