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