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