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