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 10, 2017 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_CAPRD 672A process in capability mode can read from this sysctl. 673.It Dv CTLFLAG_CAPWR 674A process in capability mode can write to this sysctl. 675.It Dv CTLFLAG_SECURE 676This sysctl can be written to only if the effective securelevel of the 677process is \[<=] 0. 678.It Dv CTLFLAG_PRISON 679This sysctl can be written to by processes in 680.Xr jail 2 . 681.It Dv CTLFLAG_SKIP 682When iterating the sysctl name space, do not list this sysctl. 683.It Dv CTLFLAG_TUN 684Advisory flag that a system tunable also exists for this variable. 685The initial sysctl value is tried fetched once from the system 686environment early during module load or system boot. 687.It Dv CTLFLAG_DYN 688Dynamically created OIDs automatically get this flag set. 689.It Dv CTLFLAG_VNET 690OID references a VIMAGE-enabled variable. 691.El 692.Sh EXAMPLES 693Sample use of 694.Fn SYSCTL_DECL 695to declare the 696.Va security 697sysctl tree for use by new nodes: 698.Bd -literal -offset indent 699SYSCTL_DECL(_security); 700.Ed 701.Pp 702Examples of integer, opaque, string, and procedure sysctls follow: 703.Bd -literal -offset indent 704/* 705 * Example of a constant integer value. Notice that the control 706 * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR, 707 * and the value is declared. 708 */ 709SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR, 710 sizeof(struct bio), "sizeof(struct bio)"); 711 712/* 713 * Example of a variable integer value. Notice that the control 714 * flags are CTLFLAG_RW, the variable pointer is set, and the 715 * value is 0. 716 */ 717static int doingcache = 1; /* 1 => enable the cache */ 718SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0, 719 "Enable name cache"); 720 721/* 722 * Example of a variable string value. Notice that the control 723 * flags are CTLFLAG_RW, that the variable pointer and string 724 * size are set. Unlike newer sysctls, this older sysctl uses a 725 * static oid number. 726 */ 727char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */ 728SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW, 729 kernelname, sizeof(kernelname), "Name of kernel file booted"); 730 731/* 732 * Example of an opaque data type exported by sysctl. Notice that 733 * the variable pointer and size are provided, as well as a format 734 * string for sysctl(8). 735 */ 736static l_fp pps_freq; /* scaled frequency offset (ns/s) */ 737SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD, 738 &pps_freq, sizeof(pps_freq), "I", ""); 739 740/* 741 * Example of a procedure based sysctl exporting string 742 * information. Notice that the data type is declared, the NULL 743 * variable pointer and 0 size, the function pointer, and the 744 * format string for sysctl(8). 745 */ 746SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING | 747 CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A", 748 ""); 749.Ed 750.Pp 751The following is an example of 752how to create a new top-level category 753and how to hook up another subtree to an existing static node. 754This example does not use contexts, 755which results in tedious management of all intermediate oids, 756as they need to be freed later on: 757.Bd -literal -offset indent 758#include <sys/sysctl.h> 759 ... 760/* 761 * Need to preserve pointers to newly created subtrees, 762 * to be able to free them later: 763 */ 764static struct sysctl_oid *root1; 765static struct sysctl_oid *root2; 766static struct sysctl_oid *oidp; 767static int a_int; 768static char *string = "dynamic sysctl"; 769 ... 770 771root1 = SYSCTL_ADD_ROOT_NODE(NULL, 772 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); 773oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1), 774 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); 775 ... 776root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug), 777 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); 778oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2), 779 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); 780.Ed 781.Pp 782This example creates the following subtrees: 783.Bd -literal -offset indent 784debug.newtree.newstring 785newtree.newint 786.Ed 787.Pp 788.Em "Care should be taken to free all OIDs once they are no longer needed!" 789.Sh SYSCTL NAMING 790When adding, modifying, or removing sysctl names, it is important to be 791aware that these interfaces may be used by users, libraries, applications, 792or documentation (such as published books), and are implicitly published application interfaces. 793As with other application interfaces, caution must be taken not to break 794existing applications, and to think about future use of new name spaces so as 795to avoid the need to rename or remove interfaces that might be depended on in 796the future. 797.Pp 798The semantics chosen for a new sysctl should be as clear as possible, 799and the name of the sysctl must closely reflect its semantics. 800Therefore the sysctl name deserves a fair amount of consideration. 801It should be short but yet representative of the sysctl meaning. 802If the name consists of several words, they should be separated by 803underscore characters, as in 804.Va compute_summary_at_mount . 805Underscore characters may be omitted only if the name consists of not more 806than two words, each being not longer than four characters, as in 807.Va bootfile . 808For boolean sysctls, negative logic should be totally avoided. 809That is, do not use names like 810.Va no_foobar 811or 812.Va foobar_disable . 813They are confusing and lead to configuration errors. 814Use positive logic instead: 815.Va foobar , 816.Va foobar_enable . 817.Pp 818A temporary sysctl node OID that should not be relied upon must be designated 819as such by a leading underscore character in its name. 820For example: 821.Va _dirty_hack . 822.Sh SEE ALSO 823.Xr sysctl 3 , 824.Xr sysctl 8 , 825.Xr sysctl_add_oid 9 , 826.Xr sysctl_ctx_free 9 , 827.Xr sysctl_ctx_init 9 , 828.Xr sysctl_remove_oid 9 829.Sh HISTORY 830The 831.Xr sysctl 8 832utility first appeared in 833.Bx 4.4 . 834.Sh AUTHORS 835.An -nosplit 836The 837.Nm sysctl 838implementation originally found in 839.Bx 840has been extensively rewritten by 841.An Poul-Henning Kamp 842in order to add support for name lookups, name space iteration, and dynamic 843addition of MIB nodes. 844.Pp 845This man page was written by 846.An Robert N. M. Watson . 847.Sh SECURITY CONSIDERATIONS 848When creating new sysctls, careful attention should be paid to the security 849implications of the monitoring or management interface being created. 850Most sysctls present in the kernel are read-only or writable only by the 851superuser. 852Sysctls exporting extensive information on system data structures and 853operation, especially those implemented using procedures, will wish to 854implement access control to limit the undesired exposure of information about 855other processes, network connections, etc. 856.Pp 857The following top level sysctl name spaces are commonly used: 858.Bl -tag -width ".Va regression" 859.It Va compat 860Compatibility layer information. 861.It Va debug 862Debugging information. 863Various name spaces exist under 864.Va debug . 865.It Va hw 866Hardware and device driver information. 867.It Va kern 868Kernel behavior tuning; generally deprecated in favor of more specific 869name spaces. 870.It Va machdep 871Machine-dependent configuration parameters. 872.It Va net 873Network subsystem. 874Various protocols have name spaces under 875.Va net . 876.It Va regression 877Regression test configuration and information. 878.It Va security 879Security and security-policy configuration and information. 880.It Va sysctl 881Reserved name space for the implementation of sysctl. 882.It Va user 883Configuration settings relating to user application behavior. 884Generally, configuring applications using kernel sysctls is discouraged. 885.It Va vfs 886Virtual file system configuration and information. 887.It Va vm 888Virtual memory subsystem configuration and information. 889.El 890