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.Dd September 1, 2020 27.Dt SYSCTL 9 28.Os 29.Sh NAME 30.Nm SYSCTL_DECL , 31.Nm SYSCTL_ADD_BOOL , 32.Nm SYSCTL_ADD_COUNTER_U64 , 33.Nm SYSCTL_ADD_COUNTER_U64_ARRAY , 34.Nm SYSCTL_ADD_INT , 35.Nm SYSCTL_ADD_LONG , 36.Nm SYSCTL_ADD_NODE , 37.Nm SYSCTL_ADD_NODE_WITH_LABEL , 38.Nm SYSCTL_ADD_OPAQUE , 39.Nm SYSCTL_ADD_PROC , 40.Nm SYSCTL_ADD_QUAD , 41.Nm SYSCTL_ADD_ROOT_NODE , 42.Nm SYSCTL_ADD_S8 , 43.Nm SYSCTL_ADD_S16 , 44.Nm SYSCTL_ADD_S32 , 45.Nm SYSCTL_ADD_S64 , 46.Nm SYSCTL_ADD_SBINTIME_MSEC , 47.Nm SYSCTL_ADD_SBINTIME_USEC , 48.Nm SYSCTL_ADD_STRING , 49.Nm SYSCTL_ADD_CONST_STRING , 50.Nm SYSCTL_ADD_STRUCT , 51.Nm SYSCTL_ADD_TIMEVAL_SEC , 52.Nm SYSCTL_ADD_U8 , 53.Nm SYSCTL_ADD_U16 , 54.Nm SYSCTL_ADD_U32 , 55.Nm SYSCTL_ADD_U64 , 56.Nm SYSCTL_ADD_UAUTO , 57.Nm SYSCTL_ADD_UINT , 58.Nm SYSCTL_ADD_ULONG , 59.Nm SYSCTL_ADD_UMA_CUR , 60.Nm SYSCTL_ADD_UMA_MAX , 61.Nm SYSCTL_ADD_UQUAD , 62.Nm SYSCTL_CHILDREN , 63.Nm SYSCTL_STATIC_CHILDREN , 64.Nm SYSCTL_NODE_CHILDREN , 65.Nm SYSCTL_PARENT , 66.Nm SYSCTL_BOOL , 67.Nm SYSCTL_COUNTER_U64 , 68.Nm SYSCTL_COUNTER_U64_ARRAY , 69.Nm SYSCTL_INT , 70.Nm SYSCTL_INT_WITH_LABEL , 71.Nm SYSCTL_LONG , 72.Nm sysctl_msec_to_ticks , 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_TIMEVAL_SEC , 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_UMA_CUR , 96.Nm SYSCTL_UMA_MAX , 97.Nm SYSCTL_UQUAD 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_TIMEVAL_SEC 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 "struct timeval *ptr" 325.Fa "const char *descr" 326.Fc 327.Ft struct sysctl_oid * 328.Fo SYSCTL_ADD_U8 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 "uint8_t *ptr" 335.Fa "uint8_t val" 336.Fa "const char *descr" 337.Fc 338.Ft struct sysctl_oid * 339.Fo SYSCTL_ADD_U16 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 "uint16_t *ptr" 346.Fa "uint16_t val" 347.Fa "const char *descr" 348.Fc 349.Ft struct sysctl_oid * 350.Fo SYSCTL_ADD_U32 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 "uint32_t *ptr" 357.Fa "uint32_t val" 358.Fa "const char *descr" 359.Fc 360.Ft struct sysctl_oid * 361.Fo SYSCTL_ADD_U64 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 "uint64_t *ptr" 368.Fa "uint64_t val" 369.Fa "const char *descr" 370.Fc 371.Ft struct sysctl_oid * 372.Fo SYSCTL_ADD_UINT 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 int *ptr" 379.Fa "unsigned int val" 380.Fa "const char *descr" 381.Fc 382.Ft struct sysctl_oid * 383.Fo SYSCTL_ADD_ULONG 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 "unsigned long *ptr" 390.Fa "const char *descr" 391.Fc 392.Ft struct sysctl_oid * 393.Fo SYSCTL_ADD_UQUAD 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 "uint64_t *ptr" 400.Fa "const char *descr" 401.Fc 402.Ft struct sysctl_oid * 403.Fo SYSCTL_ADD_UMA_CUR 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.Ft struct sysctl_oid * 413.Fo SYSCTL_ADD_UMA_MAX 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 "uma_zone_t ptr" 420.Fa "const char *descr" 421.Fc 422.Fa "const char *descr" 423.Ft struct sysctl_oid * 424.Fo SYSCTL_ADD_UAUTO 425.Fa "struct sysctl_ctx_list *ctx" 426.Fa "struct sysctl_oid_list *parent" 427.Fa "int number" 428.Fa "const char *name" 429.Fa "int ctlflags" 430.Fa "void *ptr" 431.Fa "const char *descr" 432.Fc 433.Ft struct sysctl_oid_list * 434.Fo SYSCTL_CHILDREN 435.Fa "struct sysctl_oid *oidp" 436.Fc 437.Ft struct sysctl_oid_list * 438.Fo SYSCTL_STATIC_CHILDREN 439.Fa "struct sysctl_oid_list OID_NAME" 440.Fc 441.Ft struct sysctl_oid_list * 442.Fo SYSCTL_NODE_CHILDREN 443.Fa "parent" 444.Fa "name" 445.Fc 446.Ft struct sysctl_oid * 447.Fo SYSCTL_PARENT 448.Fa "struct sysctl_oid *oid" 449.Fc 450.Fn SYSCTL_BOOL parent number name ctlflags ptr val descr 451.Fn SYSCTL_COUNTER_U64 parent number name ctlflags ptr descr 452.Fn SYSCTL_COUNTER_U64_ARRAY parent number name ctlflags ptr len descr 453.Fn SYSCTL_INT parent number name ctlflags ptr val descr 454.Fn SYSCTL_INT_WITH_LABEL parent number name ctlflags ptr val descr label 455.Fn SYSCTL_LONG parent number name ctlflags ptr val descr 456.Ft int 457.Fn sysctl_msec_to_ticks SYSCTL_HANDLER_ARGS 458.Fn SYSCTL_NODE parent number name ctlflags handler descr 459.Fn SYSCTL_NODE_WITH_LABEL parent number name ctlflags handler descr label 460.Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr 461.Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr 462.Fn SYSCTL_QUAD parent number name ctlflags ptr val descr 463.Fn SYSCTL_ROOT_NODE number name ctlflags handler descr 464.Fn SYSCTL_S8 parent number name ctlflags ptr val descr 465.Fn SYSCTL_S16 parent number name ctlflags ptr val descr 466.Fn SYSCTL_S32 parent number name ctlflags ptr val descr 467.Fn SYSCTL_S64 parent number name ctlflags ptr val descr 468.Fn SYSCTL_SBINTIME_MSEC parent number name ctlflags ptr descr 469.Fn SYSCTL_SBINTIME_USEC parent number name ctlflags ptr descr 470.Fn SYSCTL_STRING parent number name ctlflags arg len descr 471.Fn SYSCTL_CONST_STRING parent number name ctlflags arg descr 472.Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr 473.Fn SYSCTL_TIMEVAL_SEC parent number name ctlflags ptr descr 474.Fn SYSCTL_U8 parent number name ctlflags ptr val descr 475.Fn SYSCTL_U16 parent number name ctlflags ptr val descr 476.Fn SYSCTL_U32 parent number name ctlflags ptr val descr 477.Fn SYSCTL_U64 parent number name ctlflags ptr val descr 478.Fn SYSCTL_UINT parent number name ctlflags ptr val descr 479.Fn SYSCTL_ULONG parent number name ctlflags ptr val descr 480.Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr 481.Fn SYSCTL_UMA_MAX parent number name ctlflags ptr descr 482.Fn SYSCTL_UMA_CUR parent number name ctlflags ptr descr 483.Sh DESCRIPTION 484The 485.Nm SYSCTL 486kernel interface allows dynamic or static creation of 487.Xr sysctl 8 488MIB entries. 489All static sysctls are automatically destroyed when the module which 490they are part of is unloaded. 491Most top level categories are created statically and are available to 492all kernel code and its modules. 493.Sh DESCRIPTION OF ARGUMENTS 494.Bl -tag -width ctlflags 495.It Fa ctx 496Pointer to sysctl context or NULL, if no context. 497See 498.Xr sysctl_ctx_init 9 499for how to create a new sysctl context. 500Programmers are strongly advised to use contexts to organize the 501dynamic OIDs which they create because when a context is destroyed all 502belonging sysctls are destroyed as well. 503This makes the sysctl cleanup code much simpler. 504Else deletion of all created OIDs is required at module unload. 505.It Fa parent 506A pointer to a 507.Li struct sysctl_oid_list , 508which is the head of the parent's list of children. 509This pointer is retrieved using the 510.Fn SYSCTL_STATIC_CHILDREN 511macro for static sysctls and the 512.Fn SYSCTL_CHILDREN 513macro for dynamic sysctls. 514The 515.Fn SYSCTL_PARENT 516macro can be used to get the parent of an OID. 517The macro returns NULL if there is no parent. 518.It Fa number 519The OID number that will be assigned to this OID. 520In almost all cases this should be set to 521.Dv OID_AUTO , 522which will result in the assignment of the next available OID number. 523.It Fa name 524The name of the OID. 525The newly created OID will contain a copy of the name. 526.It Fa ctlflags 527A bit mask of sysctl control flags. 528See the section below describing all the control flags. 529.It Fa arg1 530First callback argument for procedure sysctls. 531.It Fa arg2 532Second callback argument for procedure sysctls. 533.It Fa len 534The length of the data pointed to by the 535.Fa ptr 536argument. 537For string type OIDs a length of zero means that 538.Xr strlen 3 539will be used to get the length of the string at each access to the OID. 540For array type OIDs the length must be greater than zero. 541.It Fa ptr 542Pointer to sysctl variable or string data. 543For 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 544.Fa val 545argument. 546.It Fa val 547If the 548.Fa ptr 549argument is SYSCTL_NULL_XXX_PTR, gives the constant value returned by this OID. 550Else this argument is not used. 551.It Fa struct_type 552Name of structure type. 553.It Fa handler 554A pointer to the function 555that is responsible for handling read and write requests 556to this OID. 557There are several standard handlers 558that support operations on nodes, 559integers, strings and opaque objects. 560It is possible to define custom handlers using the 561.Fn SYSCTL_PROC 562macro or the 563.Fn SYSCTL_ADD_PROC 564function. 565.It Fa format 566A pointer to a string 567which specifies the format of the OID in a symbolic way. 568This format is used as a hint by 569.Xr sysctl 8 570to apply proper data formatting for display purposes. 571.Pp 572Current formats: 573.Bl -tag -width "S,TYPE" -compact -offset indent 574.It Cm N 575node 576.It Cm A 577.Li "char *" 578.It Cm C 579.Li "int8_t" 580.It Cm CU 581.Li "uint8_t" 582.It Cm I 583.Li "int" 584.It Cm IK Ns Op Ar n 585temperature in Kelvin, multiplied by an optional single digit 586power of ten scaling factor: 1 (default) gives deciKelvin, 0 gives Kelvin, 3 587gives milliKelvin 588.It Cm IU 589.Li "unsigned int" 590.It Cm L 591.Li "long" 592.It Cm LU 593.Li "unsigned long" 594.It Cm Q 595.Li "quad_t" 596.It Cm QU 597.Li "u_quad_t" 598.It Cm S 599.Li "int16_t" 600.It Cm SU 601.Li "uint16_t" 602.It Cm "S,TYPE" 603.Li "struct TYPE" 604structures 605.El 606.It Fa descr 607A pointer to a textual description of the OID. 608.It Fa label 609A pointer to an aggregation label for this component of the OID. 610To make it easier to export sysctl data to monitoring systems that 611support aggregations through labels (e.g., Prometheus), 612this argument can be used to attach a label name to an OID. 613The label acts as a hint that this component's name should not be part 614of the metric's name, 615but attached to the metric as a label instead. 616.Pp 617Labels should only be applied to siblings that are structurally similar 618and encode the same type of value, 619as aggregation is of no use otherwise. 620.El 621.Sh NODE VALUE TYPES 622Most of the macros and functions used to create sysctl nodes export a 623read-only constant or in-kernel variable whose type matches the type 624of the node's value. 625For example, 626.Fn SYSCTL_INT 627reports the raw value of an associated variable of type 628.Vt int . 629However, nodes may also export a value that is a translation of an internal 630representation. 631.Pp 632The 633.Fn sysctl_msec_to_ticks 634handler can be used with 635.Fn SYSCTL_PROC 636or 637.Fn SYSCTL_ADD_PROC 638to export a millisecond time interval. 639When using this handler, 640the 641.Fa arg2 642parameter points to an in-kernel variable of type 643.Vt int 644which stores a tick count suitable for use with functions like 645.Xr tsleep 9 . 646The 647.Fn sysctl_msec_to_ticks 648function converts this value to milliseconds when reporting the node's value. 649Similarly, 650.Fn sysctl_msec_to_ticks 651accepts new values in milliseconds and stores an equivalent value in ticks to 652.Fa *arg2 . 653Note that new code should use kernel variables of type 654.Vt sbintime_t 655instead of tick counts. 656.Pp 657The 658.Fn SYSCTL_ADD_SBINTIME_MSEC 659and 660.Fn SYSCTL_ADD_SBINTIME_USEC 661functions and 662.Fn SYSCTL_SBINTIME_MSEC 663and 664.Fn SYSCTL_SBINTIME_USEC 665macros all create nodes which export an in-kernel variable of type 666.Vt sbintime_t . 667These nodes do not export the raw value of the associated variable. 668Instead, they export a 64-bit integer containing a count of either 669milliseconds (the MSEC variants) or microseconds (the USEC variants). 670.Pp 671The 672.Fn SYSCTL_ADD_TIMEVAL_SEC 673function and 674.Fn SYSCTL_TIMEVAL_SEC 675macro create nodes which export an in-kernel variable of type 676.Vt struct timeval . 677These nodes do not export full value of the associated structure. 678Instead, they export a count in seconds as a simple integer which is 679stored in the 680.Fa tv_sec 681field of the associated variable. 682This function and macro are intended to be used with variables which 683store a non-negative interval rather than an absolute time. 684As a result, they reject attempts to store negative values. 685.Sh CREATING ROOT NODES 686Sysctl MIBs or OIDs are created in a hierarchical tree. 687The nodes at the bottom of the tree are called root nodes, and have no 688parent OID. 689To create bottom tree nodes the 690.Fn SYSCTL_ROOT_NODE 691macro or the 692.Fn SYSCTL_ADD_ROOT_NODE 693function needs to be used. 694By default all static sysctl node OIDs are global and need a 695.Fn SYSCTL_DECL 696statement prior to their 697.Fn SYSCTL_NODE 698definition statement, typically in a so-called header file. 699.Sh CREATING SYSCTL STRINGS 700Zero terminated character strings sysctls are created either using the 701.Fn SYSCTL_STRING 702macro or the 703.Fn SYSCTL_ADD_STRING 704function. 705If the 706.Fa len 707argument in zero, the string length is computed at every access to the OID using 708.Xr strlen 3 . 709Use the 710.Fn SYSCTL_CONST_STRING 711macro or the 712.Fn SYSCTL_ADD_CONST_STRING 713function to add a sysctl for a constant string. 714.Sh CREATING OPAQUE SYSCTLS 715The 716.Fn SYSCTL_OPAQUE 717or 718.Fn SYSCTL_STRUCT 719macros or the 720.Fn SYSCTL_ADD_OPAQUE 721or 722.Fn SYSCTL_ADD_STRUCT 723functions create an OID that handle any chunk of data 724of the size specified by the 725.Fa len 726argument and data pointed to by the 727.Fa ptr 728argument. 729When using the structure version the type is encoded as part of the 730created sysctl. 731.Sh CREATING CUSTOM SYSCTLS 732The 733.Fn SYSCTL_PROC 734macro and the 735.Fn SYSCTL_ADD_PROC 736function 737create OIDs with the specified 738.Pa handler 739function. 740The handler is responsible for handling all read and write requests to 741the OID. 742This OID type is especially useful if the kernel data is not easily 743accessible, or needs to be processed before exporting. 744.Sh CREATING A STATIC SYSCTL 745Static sysctls are declared using one of the 746.Fn SYSCTL_BOOL , 747.Fn SYSCTL_COUNTER_U64 , 748.Fn SYSCTL_COUNTER_U64_ARRAY , 749.Fn SYSCTL_INT , 750.Fn SYSCTL_INT_WITH_LABEL , 751.Fn SYSCTL_LONG , 752.Fn SYSCTL_NODE , 753.Fn SYSCTL_NODE_WITH_LABEL , 754.Fn SYSCTL_OPAQUE , 755.Fn SYSCTL_PROC , 756.Fn SYSCTL_QUAD , 757.Fn SYSCTL_ROOT_NODE , 758.Fn SYSCTL_S8 , 759.Fn SYSCTL_S16 , 760.Fn SYSCTL_S32 , 761.Fn SYSCTL_S64 , 762.Fn SYSCTL_SBINTIME_MSEC , 763.Fn SYSCTL_SBINTIME_USEC , 764.Fn SYSCTL_STRING , 765.Fn SYSCTL_CONST_STRING , 766.Fn SYSCTL_STRUCT , 767.Fn SYSCTL_TIMEVAL_SEC , 768.Fn SYSCTL_U8 , 769.Fn SYSCTL_U16 , 770.Fn SYSCTL_U32 , 771.Fn SYSCTL_U64 , 772.Fn SYSCTL_UINT , 773.Fn SYSCTL_ULONG , 774.Fn SYSCTL_UQUAD , 775.Fn SYSCTL_UMA_CUR 776or 777.Fn SYSCTL_UMA_MAX 778macros. 779.Sh CREATING A DYNAMIC SYSCTL 780Dynamic nodes are created using one of the 781.Fn SYSCTL_ADD_BOOL , 782.Fn SYSCTL_ADD_COUNTER_U64 , 783.Fn SYSCTL_ADD_COUNTER_U64_ARRAY , 784.Fn SYSCTL_ADD_INT , 785.Fn SYSCTL_ADD_LONG , 786.Fn SYSCTL_ADD_NODE , 787.Fn SYSCTL_ADD_NODE_WITH_LABEL , 788.Fn SYSCTL_ADD_OPAQUE , 789.Fn SYSCTL_ADD_PROC , 790.Fn SYSCTL_ADD_QUAD , 791.Fn SYSCTL_ADD_ROOT_NODE , 792.Fn SYSCTL_ADD_S8 , 793.Fn SYSCTL_ADD_S16 , 794.Fn SYSCTL_ADD_S32 , 795.Fn SYSCTL_ADD_S64 , 796.Fn SYSCTL_ADD_SBINTIME_MSEC , 797.Fn SYSCTL_ADD_SBINTIME_USEC , 798.Fn SYSCTL_ADD_STRING , 799.Fn SYSCTL_ADD_CONST_STRING , 800.Fn SYSCTL_ADD_STRUCT , 801.Fn SYSCTL_ADD_TIMEVAL_SEC , 802.Fn SYSCTL_ADD_U8 , 803.Fn SYSCTL_ADD_U16 , 804.Fn SYSCTL_ADD_U32 , 805.Fn SYSCTL_ADD_U64 , 806.Fn SYSCTL_ADD_UAUTO , 807.Fn SYSCTL_ADD_UINT , 808.Fn SYSCTL_ADD_ULONG , 809.Fn SYSCTL_ADD_UQUAD , 810.Fn SYSCTL_ADD_UMA_CUR 811or 812.Fn SYSCTL_ADD_UMA_MAX 813functions. 814See 815.Xr sysctl_remove_oid 9 816or 817.Xr sysctl_ctx_free 9 818for more information on how to destroy a dynamically created OID. 819.Sh CONTROL FLAGS 820For most of the above functions and macros, declaring a type as part 821of the access flags is not necessary \[em] however, when declaring a 822sysctl implemented by a function, including a type in the access mask 823is required: 824.Bl -tag -width ".Dv CTLTYPE_NOFETCH" 825.It Dv CTLTYPE_NODE 826This is a node intended to be a parent for other nodes. 827.It Dv CTLTYPE_INT 828This is a signed integer. 829.It Dv CTLTYPE_STRING 830This is a nul-terminated string stored in a character array. 831.It Dv CTLTYPE_S8 832This is an 8-bit signed integer. 833.It Dv CTLTYPE_S16 834This is a 16-bit signed integer. 835.It Dv CTLTYPE_S32 836This is a 32-bit signed integer. 837.It Dv CTLTYPE_S64 838This is a 64-bit signed integer. 839.It Dv CTLTYPE_OPAQUE 840This is an opaque data structure. 841.It Dv CTLTYPE_STRUCT 842Alias for 843.Dv CTLTYPE_OPAQUE . 844.It Dv CTLTYPE_U8 845This is an 8-bit unsigned integer. 846.It Dv CTLTYPE_U16 847This is a 16-bit unsigned integer. 848.It Dv CTLTYPE_U32 849This is a 32-bit unsigned integer. 850.It Dv CTLTYPE_U64 851This is a 64-bit unsigned integer. 852.It Dv CTLTYPE_UINT 853This is an unsigned integer. 854.It Dv CTLTYPE_LONG 855This is a signed long. 856.It Dv CTLTYPE_ULONG 857This is an unsigned long. 858.El 859.Pp 860All sysctl types except for new node declarations require one of the following 861flags to be set indicating the read and write disposition of the sysctl: 862.Bl -tag -width ".Dv CTLFLAG_ANYBODY" 863.It Dv CTLFLAG_RD 864This is a read-only sysctl. 865.It Dv CTLFLAG_RDTUN 866This is a read-only sysctl and tunable which is tried fetched once 867from the system environment early during module load or system boot. 868.It Dv CTLFLAG_WR 869This is a writable sysctl. 870.It Dv CTLFLAG_RW 871This sysctl is readable and writable. 872.It Dv CTLFLAG_RWTUN 873This is a readable and writeable sysctl and tunable which is tried 874fetched once from the system environment early during module load or 875system boot. 876.It Dv CTLFLAG_NOFETCH 877In case the node is marked as a tunable using the CTLFLAG_[XX]TUN, 878this flag will prevent fetching the initial value from the system 879environment. 880Typically this flag should only be used for very early 881low level system setup code, and not by common drivers and modules. 882.It Dv CTLFLAG_MPSAFE 883This 884.Xr sysctl 9 885handler is MP safe. 886Do not grab Giant around calls to this handler. 887This should only be used for 888.Fn SYSCTL_PROC 889entries. 890.El 891.Pp 892Additionally, any of the following optional flags may also be specified: 893.Bl -tag -width ".Dv CTLFLAG_ANYBODY" 894.It Dv CTLFLAG_ANYBODY 895Any user or process can write to this sysctl. 896.It Dv CTLFLAG_CAPRD 897A process in capability mode can read from this sysctl. 898.It Dv CTLFLAG_CAPWR 899A process in capability mode can write to this sysctl. 900.It Dv CTLFLAG_SECURE 901This sysctl can be written to only if the effective securelevel of the 902process is \[<=] 0. 903.It Dv CTLFLAG_PRISON 904This sysctl can be written to by processes in 905.Xr jail 2 . 906.It Dv CTLFLAG_SKIP 907When iterating the sysctl name space, do not list this sysctl. 908.It Dv CTLFLAG_TUN 909Advisory flag that a system tunable also exists for this variable. 910The initial sysctl value is tried fetched once from the system 911environment early during module load or system boot. 912.It Dv CTLFLAG_DYN 913Dynamically created OIDs automatically get this flag set. 914.It Dv CTLFLAG_VNET 915OID references a VIMAGE-enabled variable. 916.El 917.Sh EXAMPLES 918Sample use of 919.Fn SYSCTL_DECL 920to declare the 921.Va security 922sysctl tree for use by new nodes: 923.Bd -literal -offset indent 924SYSCTL_DECL(_security); 925.Ed 926.Pp 927Examples of integer, opaque, string, and procedure sysctls follow: 928.Bd -literal -offset indent 929/* 930 * Example of a constant integer value. Notice that the control 931 * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR, 932 * and the value is declared. 933 */ 934SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR, 935 sizeof(struct bio), "sizeof(struct bio)"); 936 937/* 938 * Example of a variable integer value. Notice that the control 939 * flags are CTLFLAG_RW, the variable pointer is set, and the 940 * value is 0. 941 */ 942static int doingcache = 1; /* 1 => enable the cache */ 943SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0, 944 "Enable name cache"); 945 946/* 947 * Example of a variable string value. Notice that the control 948 * flags are CTLFLAG_RW, that the variable pointer and string 949 * size are set. Unlike newer sysctls, this older sysctl uses a 950 * static oid number. 951 */ 952char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */ 953SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW, 954 kernelname, sizeof(kernelname), "Name of kernel file booted"); 955 956/* 957 * Example of an opaque data type exported by sysctl. Notice that 958 * the variable pointer and size are provided, as well as a format 959 * string for sysctl(8). 960 */ 961static l_fp pps_freq; /* scaled frequency offset (ns/s) */ 962SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD, 963 &pps_freq, sizeof(pps_freq), "I", ""); 964 965/* 966 * Example of a procedure based sysctl exporting string 967 * information. Notice that the data type is declared, the NULL 968 * variable pointer and 0 size, the function pointer, and the 969 * format string for sysctl(8). 970 */ 971SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING | 972 CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A", 973 ""); 974.Ed 975.Pp 976The following is an example of 977how to create a new top-level category 978and how to hook up another subtree to an existing static node. 979This example does not use contexts, 980which results in tedious management of all intermediate oids, 981as they need to be freed later on: 982.Bd -literal -offset indent 983#include <sys/sysctl.h> 984 ... 985/* 986 * Need to preserve pointers to newly created subtrees, 987 * to be able to free them later: 988 */ 989static struct sysctl_oid *root1; 990static struct sysctl_oid *root2; 991static struct sysctl_oid *oidp; 992static int a_int; 993static char *string = "dynamic sysctl"; 994 ... 995 996root1 = SYSCTL_ADD_ROOT_NODE(NULL, 997 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); 998oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1), 999 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); 1000 ... 1001root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug), 1002 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); 1003oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2), 1004 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); 1005.Ed 1006.Pp 1007This example creates the following subtrees: 1008.Bd -literal -offset indent 1009debug.newtree.newstring 1010newtree.newint 1011.Ed 1012.Pp 1013.Em "Care should be taken to free all OIDs once they are no longer needed!" 1014.Sh SYSCTL NAMING 1015When adding, modifying, or removing sysctl names, it is important to be 1016aware that these interfaces may be used by users, libraries, applications, 1017or documentation (such as published books), and are implicitly published application interfaces. 1018As with other application interfaces, caution must be taken not to break 1019existing applications, and to think about future use of new name spaces so as 1020to avoid the need to rename or remove interfaces that might be depended on in 1021the future. 1022.Pp 1023The semantics chosen for a new sysctl should be as clear as possible, 1024and the name of the sysctl must closely reflect its semantics. 1025Therefore the sysctl name deserves a fair amount of consideration. 1026It should be short but yet representative of the sysctl meaning. 1027If the name consists of several words, they should be separated by 1028underscore characters, as in 1029.Va compute_summary_at_mount . 1030Underscore characters may be omitted only if the name consists of not more 1031than two words, each being not longer than four characters, as in 1032.Va bootfile . 1033.Pp 1034For boolean sysctls, negative logic should be totally avoided. 1035That is, do not use names like 1036.Va no_foobar 1037or 1038.Va foobar_disable . 1039They are confusing and lead to configuration errors. 1040Use positive logic instead: 1041.Va foobar , 1042.Va foobar_enable . 1043.Pp 1044A temporary sysctl node OID that should not be relied upon must be designated 1045as such by a leading underscore character in its name. 1046For example: 1047.Va _dirty_hack . 1048.Sh SEE ALSO 1049.Xr sysctl 3 , 1050.Xr sysctl 8 , 1051.Xr device_get_sysctl 9 , 1052.Xr sysctl_add_oid 9 , 1053.Xr sysctl_ctx_free 9 , 1054.Xr sysctl_ctx_init 9 , 1055.Xr sysctl_remove_oid 9 1056.Sh HISTORY 1057The 1058.Xr sysctl 8 1059utility first appeared in 1060.Bx 4.4 . 1061.Sh AUTHORS 1062.An -nosplit 1063The 1064.Nm sysctl 1065implementation originally found in 1066.Bx 1067has been extensively rewritten by 1068.An Poul-Henning Kamp 1069in order to add support for name lookups, name space iteration, and dynamic 1070addition of MIB nodes. 1071.Pp 1072This man page was written by 1073.An Robert N. M. Watson . 1074.Sh SECURITY CONSIDERATIONS 1075When creating new sysctls, careful attention should be paid to the security 1076implications of the monitoring or management interface being created. 1077Most sysctls present in the kernel are read-only or writable only by the 1078superuser. 1079Sysctls exporting extensive information on system data structures and 1080operation, especially those implemented using procedures, will wish to 1081implement access control to limit the undesired exposure of information about 1082other processes, network connections, etc. 1083.Pp 1084The following top level sysctl name spaces are commonly used: 1085.Bl -tag -width ".Va regression" 1086.It Va compat 1087Compatibility layer information. 1088.It Va debug 1089Debugging information. 1090Various name spaces exist under 1091.Va debug . 1092.It Va hw 1093Hardware and device driver information. 1094.It Va kern 1095Kernel behavior tuning; generally deprecated in favor of more specific 1096name spaces. 1097.It Va machdep 1098Machine-dependent configuration parameters. 1099.It Va net 1100Network subsystem. 1101Various protocols have name spaces under 1102.Va net . 1103.It Va regression 1104Regression test configuration and information. 1105.It Va security 1106Security and security-policy configuration and information. 1107.It Va sysctl 1108Reserved name space for the implementation of sysctl. 1109.It Va user 1110Configuration settings relating to user application behavior. 1111Generally, configuring applications using kernel sysctls is discouraged. 1112.It Va vfs 1113Virtual file system configuration and information. 1114.It Va vm 1115Virtual memory subsystem configuration and information. 1116.El 1117