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