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