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