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 I 581.Li "int" 582.It Cm IK Ns Op Ar n 583temperature in Kelvin, multiplied by an optional single digit 584power of ten scaling factor: 1 (default) gives deciKelvin, 0 gives Kelvin, 3 585gives milliKelvin 586.It Cm IU 587.Li "unsigned int" 588.It Cm L 589.Li "long" 590.It Cm LU 591.Li "unsigned long" 592.It Cm Q 593.Li "quad_t" 594.It Cm QU 595.Li "u_quad_t" 596.It Cm "S,TYPE" 597.Li "struct TYPE" 598structures 599.El 600.It Fa descr 601A pointer to a textual description of the OID. 602.It Fa label 603A pointer to an aggregation label for this component of the OID. 604To make it easier to export sysctl data to monitoring systems that 605support aggregations through labels (e.g., Prometheus), 606this argument can be used to attach a label name to an OID. 607The label acts as a hint that this component's name should not be part 608of the metric's name, 609but attached to the metric as a label instead. 610.Pp 611Labels should only be applied to siblings that are structurally similar 612and encode the same type of value, 613as aggregation is of no use otherwise. 614.El 615.Sh NODE VALUE TYPES 616Most of the macros and functions used to create sysctl nodes export a 617read-only constant or in-kernel variable whose type matches the type 618of the node's value. 619For example, 620.Fn SYSCTL_INT 621reports the raw value of an associated variable of type 622.Vt int . 623However, nodes may also export a value that is a translatation of an internal 624representation. 625.Pp 626The 627.Fn sysctl_msec_to_ticks 628handler can be used with 629.Fn SYSCTL_PROC 630or 631.Fn SYSCTL_ADD_PROC 632to export a millisecond time interval. 633When using this handler, 634the 635.Fa arg2 636parameter points to an in-kernel variable of type 637.Vt int 638which stores a tick count suitable for use with functions like 639.Xr tsleep 9 . 640The 641.Fn sysctl_msec_to_ticks 642function converts this value to milliseconds when reporting the node's value. 643Similarly, 644.Fn sysctl_msec_to_ticks 645accepts new values in milliseconds and stores an equivalent value in ticks to 646.Fa *arg2 . 647Note that new code should use kernel variables of type 648.Vt sbintime_t 649instead of tick counts. 650.Pp 651The 652.Fn SYSCTL_ADD_SBINTIME_MSEC 653and 654.Fn SYSCTL_ADD_SBINTIME_USEC 655functions and 656.Fn SYSCTL_SBINTIME_MSEC 657and 658.Fn SYSCTL_SBINTIME_USEC 659macros all create nodes which export an in-kernel variable of type 660.Vt sbintime_t . 661These nodes do not export the raw value of the associated variable. 662Instead, they export a 64-bit integer containing a count of either 663milliseconds (the MSEC variants) or microseconds (the USEC variants). 664.Pp 665The 666.Fn SYSCTL_ADD_TIMEVAL_SEC 667function and 668.Fn SYSCTL_TIMEVAL_SEC 669macro create nodes which export an in-kernel variable of type 670.Vt struct timeval . 671These nodes do not export full value of the associated structure. 672Instead, they export a count in seconds as a simple integer which is 673stored in the 674.Fa tv_sec 675field of the associated variable. 676This function and macro are intended to be used with variables which 677store a non-negative interval rather than an absolute time. 678As a result, they reject attempts to store negative values. 679.Sh CREATING ROOT NODES 680Sysctl MIBs or OIDs are created in a hierarchical tree. 681The nodes at the bottom of the tree are called root nodes, and have no 682parent OID. 683To create bottom tree nodes the 684.Fn SYSCTL_ROOT_NODE 685macro or the 686.Fn SYSCTL_ADD_ROOT_NODE 687function needs to be used. 688By default all static sysctl node OIDs are global and need a 689.Fn SYSCTL_DECL 690statement prior to their 691.Fn SYSCTL_NODE 692definition statement, typically in a so-called header file. 693.Sh CREATING SYSCTL STRINGS 694Zero terminated character strings sysctls are created either using the 695.Fn SYSCTL_STRING 696macro or the 697.Fn SYSCTL_ADD_STRING 698function. 699If the 700.Fa len 701argument in zero, the string length is computed at every access to the OID using 702.Xr strlen 3 . 703Use the 704.Fn SYSCTL_CONST_STRING 705macro or the 706.Fn SYSCTL_ADD_CONST_STRING 707function to add a sysctl for a constant string. 708.Sh CREATING OPAQUE SYSCTLS 709The 710.Fn SYSCTL_OPAQUE 711or 712.Fn SYSCTL_STRUCT 713macros or the 714.Fn SYSCTL_ADD_OPAQUE 715or 716.Fn SYSCTL_ADD_STRUCT 717functions create an OID that handle any chunk of data 718of the size specified by the 719.Fa len 720argument and data pointed to by the 721.Fa ptr 722argument. 723When using the structure version the type is encoded as part of the 724created sysctl. 725.Sh CREATING CUSTOM SYSCTLS 726The 727.Fn SYSCTL_PROC 728macro and the 729.Fn SYSCTL_ADD_PROC 730function 731create OIDs with the specified 732.Pa handler 733function. 734The handler is responsible for handling all read and write requests to 735the OID. 736This OID type is especially useful if the kernel data is not easily 737accessible, or needs to be processed before exporting. 738.Sh CREATING A STATIC SYSCTL 739Static sysctls are declared using one of the 740.Fn SYSCTL_BOOL , 741.Fn SYSCTL_COUNTER_U64 , 742.Fn SYSCTL_COUNTER_U64_ARRAY , 743.Fn SYSCTL_INT , 744.Fn SYSCTL_INT_WITH_LABEL , 745.Fn SYSCTL_LONG , 746.Fn SYSCTL_NODE , 747.Fn SYSCTL_NODE_WITH_LABEL , 748.Fn SYSCTL_OPAQUE , 749.Fn SYSCTL_PROC , 750.Fn SYSCTL_QUAD , 751.Fn SYSCTL_ROOT_NODE , 752.Fn SYSCTL_S8 , 753.Fn SYSCTL_S16 , 754.Fn SYSCTL_S32 , 755.Fn SYSCTL_S64 , 756.Fn SYSCTL_SBINTIME_MSEC , 757.Fn SYSCTL_SBINTIME_USEC , 758.Fn SYSCTL_STRING , 759.Fn SYSCTL_CONST_STRING , 760.Fn SYSCTL_STRUCT , 761.Fn SYSCTL_TIMEVAL_SEC , 762.Fn SYSCTL_U8 , 763.Fn SYSCTL_U16 , 764.Fn SYSCTL_U32 , 765.Fn SYSCTL_U64 , 766.Fn SYSCTL_UINT , 767.Fn SYSCTL_ULONG , 768.Fn SYSCTL_UQUAD , 769.Fn SYSCTL_UMA_CUR 770or 771.Fn SYSCTL_UMA_MAX 772macros. 773.Sh CREATING A DYNAMIC SYSCTL 774Dynamic nodes are created using one of the 775.Fn SYSCTL_ADD_BOOL , 776.Fn SYSCTL_ADD_COUNTER_U64 , 777.Fn SYSCTL_ADD_COUNTER_U64_ARRAY , 778.Fn SYSCTL_ADD_INT , 779.Fn SYSCTL_ADD_LONG , 780.Fn SYSCTL_ADD_NODE , 781.Fn SYSCTL_ADD_NODE_WITH_LABEL , 782.Fn SYSCTL_ADD_OPAQUE , 783.Fn SYSCTL_ADD_PROC , 784.Fn SYSCTL_ADD_QUAD , 785.Fn SYSCTL_ADD_ROOT_NODE , 786.Fn SYSCTL_ADD_S8 , 787.Fn SYSCTL_ADD_S16 , 788.Fn SYSCTL_ADD_S32 , 789.Fn SYSCTL_ADD_S64 , 790.Fn SYSCTL_ADD_SBINTIME_MSEC , 791.Fn SYSCTL_ADD_SBINTIME_USEC , 792.Fn SYSCTL_ADD_STRING , 793.Fn SYSCTL_ADD_CONST_STRING , 794.Fn SYSCTL_ADD_STRUCT , 795.Fn SYSCTL_ADD_TIMEVAL_SEC , 796.Fn SYSCTL_ADD_U8 , 797.Fn SYSCTL_ADD_U16 , 798.Fn SYSCTL_ADD_U32 , 799.Fn SYSCTL_ADD_U64 , 800.Fn SYSCTL_ADD_UAUTO , 801.Fn SYSCTL_ADD_UINT , 802.Fn SYSCTL_ADD_ULONG , 803.Fn SYSCTL_ADD_UQUAD , 804.Fn SYSCTL_ADD_UMA_CUR 805or 806.Fn SYSCTL_ADD_UMA_MAX 807functions. 808See 809.Xr sysctl_remove_oid 9 810or 811.Xr sysctl_ctx_free 9 812for more information on how to destroy a dynamically created OID. 813.Sh CONTROL FLAGS 814For most of the above functions and macros, declaring a type as part 815of the access flags is not necessary \[em] however, when declaring a 816sysctl implemented by a function, including a type in the access mask 817is required: 818.Bl -tag -width ".Dv CTLTYPE_NOFETCH" 819.It Dv CTLTYPE_NODE 820This is a node intended to be a parent for other nodes. 821.It Dv CTLTYPE_INT 822This is a signed integer. 823.It Dv CTLTYPE_STRING 824This is a nul-terminated string stored in a character array. 825.It Dv CTLTYPE_S8 826This is an 8-bit signed integer. 827.It Dv CTLTYPE_S16 828This is a 16-bit signed integer. 829.It Dv CTLTYPE_S32 830This is a 32-bit signed integer. 831.It Dv CTLTYPE_S64 832This is a 64-bit signed integer. 833.It Dv CTLTYPE_OPAQUE 834This is an opaque data structure. 835.It Dv CTLTYPE_STRUCT 836Alias for 837.Dv CTLTYPE_OPAQUE . 838.It Dv CTLTYPE_U8 839This is an 8-bit unsigned integer. 840.It Dv CTLTYPE_U16 841This is a 16-bit unsigned integer. 842.It Dv CTLTYPE_U32 843This is a 32-bit unsigned integer. 844.It Dv CTLTYPE_U64 845This is a 64-bit unsigned integer. 846.It Dv CTLTYPE_UINT 847This is an unsigned integer. 848.It Dv CTLTYPE_LONG 849This is a signed long. 850.It Dv CTLTYPE_ULONG 851This is an unsigned long. 852.El 853.Pp 854All sysctl types except for new node declarations require one of the following 855flags to be set indicating the read and write disposition of the sysctl: 856.Bl -tag -width ".Dv CTLFLAG_ANYBODY" 857.It Dv CTLFLAG_RD 858This is a read-only sysctl. 859.It Dv CTLFLAG_RDTUN 860This is a read-only sysctl and tunable which is tried fetched once 861from the system environment early during module load or system boot. 862.It Dv CTLFLAG_WR 863This is a writable sysctl. 864.It Dv CTLFLAG_RW 865This sysctl is readable and writable. 866.It Dv CTLFLAG_RWTUN 867This is a readable and writeable sysctl and tunable which is tried 868fetched once from the system environment early during module load or 869system boot. 870.It Dv CTLFLAG_NOFETCH 871In case the node is marked as a tunable using the CTLFLAG_[XX]TUN, 872this flag will prevent fetching the initial value from the system 873environment. 874Typically this flag should only be used for very early 875low level system setup code, and not by common drivers and modules. 876.It Dv CTLFLAG_MPSAFE 877This 878.Xr sysctl 9 879handler is MP safe. 880Do not grab Giant around calls to this handler. 881This should only be used for 882.Fn SYSCTL_PROC 883entries. 884.El 885.Pp 886Additionally, any of the following optional flags may also be specified: 887.Bl -tag -width ".Dv CTLFLAG_ANYBODY" 888.It Dv CTLFLAG_ANYBODY 889Any user or process can write to this sysctl. 890.It Dv CTLFLAG_CAPRD 891A process in capability mode can read from this sysctl. 892.It Dv CTLFLAG_CAPWR 893A process in capability mode can write to this sysctl. 894.It Dv CTLFLAG_SECURE 895This sysctl can be written to only if the effective securelevel of the 896process is \[<=] 0. 897.It Dv CTLFLAG_PRISON 898This sysctl can be written to by processes in 899.Xr jail 2 . 900.It Dv CTLFLAG_SKIP 901When iterating the sysctl name space, do not list this sysctl. 902.It Dv CTLFLAG_TUN 903Advisory flag that a system tunable also exists for this variable. 904The initial sysctl value is tried fetched once from the system 905environment early during module load or system boot. 906.It Dv CTLFLAG_DYN 907Dynamically created OIDs automatically get this flag set. 908.It Dv CTLFLAG_VNET 909OID references a VIMAGE-enabled variable. 910.El 911.Sh EXAMPLES 912Sample use of 913.Fn SYSCTL_DECL 914to declare the 915.Va security 916sysctl tree for use by new nodes: 917.Bd -literal -offset indent 918SYSCTL_DECL(_security); 919.Ed 920.Pp 921Examples of integer, opaque, string, and procedure sysctls follow: 922.Bd -literal -offset indent 923/* 924 * Example of a constant integer value. Notice that the control 925 * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR, 926 * and the value is declared. 927 */ 928SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR, 929 sizeof(struct bio), "sizeof(struct bio)"); 930 931/* 932 * Example of a variable integer value. Notice that the control 933 * flags are CTLFLAG_RW, the variable pointer is set, and the 934 * value is 0. 935 */ 936static int doingcache = 1; /* 1 => enable the cache */ 937SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0, 938 "Enable name cache"); 939 940/* 941 * Example of a variable string value. Notice that the control 942 * flags are CTLFLAG_RW, that the variable pointer and string 943 * size are set. Unlike newer sysctls, this older sysctl uses a 944 * static oid number. 945 */ 946char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */ 947SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW, 948 kernelname, sizeof(kernelname), "Name of kernel file booted"); 949 950/* 951 * Example of an opaque data type exported by sysctl. Notice that 952 * the variable pointer and size are provided, as well as a format 953 * string for sysctl(8). 954 */ 955static l_fp pps_freq; /* scaled frequency offset (ns/s) */ 956SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD, 957 &pps_freq, sizeof(pps_freq), "I", ""); 958 959/* 960 * Example of a procedure based sysctl exporting string 961 * information. Notice that the data type is declared, the NULL 962 * variable pointer and 0 size, the function pointer, and the 963 * format string for sysctl(8). 964 */ 965SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING | 966 CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A", 967 ""); 968.Ed 969.Pp 970The following is an example of 971how to create a new top-level category 972and how to hook up another subtree to an existing static node. 973This example does not use contexts, 974which results in tedious management of all intermediate oids, 975as they need to be freed later on: 976.Bd -literal -offset indent 977#include <sys/sysctl.h> 978 ... 979/* 980 * Need to preserve pointers to newly created subtrees, 981 * to be able to free them later: 982 */ 983static struct sysctl_oid *root1; 984static struct sysctl_oid *root2; 985static struct sysctl_oid *oidp; 986static int a_int; 987static char *string = "dynamic sysctl"; 988 ... 989 990root1 = SYSCTL_ADD_ROOT_NODE(NULL, 991 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); 992oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1), 993 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); 994 ... 995root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug), 996 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); 997oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2), 998 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); 999.Ed 1000.Pp 1001This example creates the following subtrees: 1002.Bd -literal -offset indent 1003debug.newtree.newstring 1004newtree.newint 1005.Ed 1006.Pp 1007.Em "Care should be taken to free all OIDs once they are no longer needed!" 1008.Sh SYSCTL NAMING 1009When adding, modifying, or removing sysctl names, it is important to be 1010aware that these interfaces may be used by users, libraries, applications, 1011or documentation (such as published books), and are implicitly published application interfaces. 1012As with other application interfaces, caution must be taken not to break 1013existing applications, and to think about future use of new name spaces so as 1014to avoid the need to rename or remove interfaces that might be depended on in 1015the future. 1016.Pp 1017The semantics chosen for a new sysctl should be as clear as possible, 1018and the name of the sysctl must closely reflect its semantics. 1019Therefore the sysctl name deserves a fair amount of consideration. 1020It should be short but yet representative of the sysctl meaning. 1021If the name consists of several words, they should be separated by 1022underscore characters, as in 1023.Va compute_summary_at_mount . 1024Underscore characters may be omitted only if the name consists of not more 1025than two words, each being not longer than four characters, as in 1026.Va bootfile . 1027For boolean sysctls, negative logic should be totally avoided. 1028That is, do not use names like 1029.Va no_foobar 1030or 1031.Va foobar_disable . 1032They are confusing and lead to configuration errors. 1033Use positive logic instead: 1034.Va foobar , 1035.Va foobar_enable . 1036.Pp 1037A temporary sysctl node OID that should not be relied upon must be designated 1038as such by a leading underscore character in its name. 1039For example: 1040.Va _dirty_hack . 1041.Sh SEE ALSO 1042.Xr sysctl 3 , 1043.Xr sysctl 8 , 1044.Xr device_get_sysctl 9 , 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