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