1.\" 2.\" Copyright (c) 2000, Andrzej Bialecki <abial@FreeBSD.org> 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.\" 3. The name of the author may not be used to endorse or promote products 14.\" derived from this software without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD: src/share/man/man9/sysctl_add_oid.9,v 1.21 2006/04/28 10:45:27 rwatson Exp $ 29.\" 30.Dd October 6, 2018 31.Dt SYSCTL_ADD_OID 9 32.Os 33.Sh NAME 34.Nm sysctl_add_oid , 35.Nm sysctl_remove_oid , 36.Nm SYSCTL_CHILDREN , 37.Nm SYSCTL_STATIC_CHILDREN , 38.Nm SYSCTL_ADD_OID , 39.Nm SYSCTL_ADD_NODE , 40.Nm SYSCTL_ADD_STRING , 41.Nm SYSCTL_ADD_INT , 42.Nm SYSCTL_ADD_U32 , 43.Nm SYSCTL_ADD_UINT , 44.Nm SYSCTL_ADD_LONG , 45.Nm SYSCTL_ADD_ULONG , 46.Nm SYSCTL_ADD_QUAD , 47.Nm SYSCTL_ADD_UQUAD , 48.Nm SYSCTL_ADD_OPAQUE , 49.Nm SYSCTL_ADD_STRUCT , 50.Nm SYSCTL_ADD_PROC 51.Nd runtime sysctl tree manipulation 52.Sh SYNOPSIS 53.In sys/sysctl.h 54.Ft struct sysctl_oid * 55.Fo sysctl_add_oid 56.Fa "struct sysctl_ctx_list *ctx" 57.Fa "struct sysctl_oid_list *parent" 58.Fa "int number" 59.Fa "const char *name" 60.Fa "int kind" 61.Fa "void *arg1" 62.Fa "int arg2" 63.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" 64.Fa "const char *format" 65.Fa "const char *descr" 66.Fc 67.Ft int 68.Fo sysctl_remove_oid 69.Fa "struct sysctl_oid *oidp" 70.Fa "int del" 71.Fa "int recurse" 72.Fc 73.Ft struct sysctl_oid_list * 74.Fo SYSCTL_CHILDREN 75.Fa "struct sysctl_oid *oidp" 76.Fc 77.Ft struct sysctl_oid_list * 78.Fo SYSCTL_STATIC_CHILDREN 79.Fa "struct sysctl_oid_list oid_name" 80.Fc 81.Ft struct sysctl_oid * 82.Fo SYSCTL_ADD_OID 83.Fa "struct sysctl_ctx_list *ctx" 84.Fa "struct sysctl_oid_list *parent" 85.Fa "int number" 86.Fa "const char *name" 87.Fa "int kind" 88.Fa "void *arg1" 89.Fa "int arg2" 90.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" 91.Fa "const char *format" 92.Fa "const char *descr" 93.Fc 94.Ft struct sysctl_oid * 95.Fo SYSCTL_ADD_NODE 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 access" 101.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" 102.Fa "const char *descr" 103.Fc 104.Ft struct sysctl_oid * 105.Fo SYSCTL_ADD_S8 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 access" 111.Fa "int8_t *arg" 112.Fa "int len" 113.Fa "const char *descr" 114.Fc 115.Ft struct sysctl_oid * 116.Fo SYSCTL_ADD_S16 117.Fa "struct sysctl_ctx_list *ctx" 118.Fa "struct sysctl_oid_list *parent" 119.Fa "int number" 120.Fa "const char *name" 121.Fa "int access" 122.Fa "int16_t *arg" 123.Fa "int len" 124.Fa "const char *descr" 125.Fc 126.Ft struct sysctl_oid * 127.Fo SYSCTL_ADD_S32 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 access" 133.Fa "int32_t *arg" 134.Fa "int len" 135.Fa "const char *descr" 136.Fc 137.Ft struct sysctl_oid * 138.Fo SYSCTL_ADD_S64 139.Fa "struct sysctl_ctx_list *ctx" 140.Fa "struct sysctl_oid_list *parent" 141.Fa "int number" 142.Fa "const char *name" 143.Fa "int access" 144.Fa "int64_t *arg" 145.Fa "int len" 146.Fa "const char *descr" 147.Fc 148.Ft struct sysctl_oid * 149.Fo SYSCTL_ADD_STRING 150.Fa "struct sysctl_ctx_list *ctx" 151.Fa "struct sysctl_oid_list *parent" 152.Fa "int number" 153.Fa "const char *name" 154.Fa "int access" 155.Fa "char *arg" 156.Fa "int len" 157.Fa "const char *descr" 158.Fc 159.Ft struct sysctl_oid * 160.Fo SYSCTL_ADD_INT 161.Fa "struct sysctl_ctx_list *ctx" 162.Fa "struct sysctl_oid_list *parent" 163.Fa "int number" 164.Fa "const char *name" 165.Fa "int access" 166.Fa "int *arg" 167.Fa "int len" 168.Fa "const char *descr" 169.Fc 170.Ft struct sysctl_oid * 171.Fo SYSCTL_ADD_U8 172.Fa "struct sysctl_ctx_list *ctx" 173.Fa "struct sysctl_oid_list *parent" 174.Fa "int number" 175.Fa "const char *name" 176.Fa "int access" 177.Fa "uint8_t *arg" 178.Fa "int len" 179.Fa "const char *descr" 180.Fc 181.Ft struct sysctl_oid * 182.Fo SYSCTL_ADD_U16 183.Fa "struct sysctl_ctx_list *ctx" 184.Fa "struct sysctl_oid_list *parent" 185.Fa "int number" 186.Fa "const char *name" 187.Fa "int access" 188.Fa "uint16_t *arg" 189.Fa "int len" 190.Fa "const char *descr" 191.Fc 192.Ft struct sysctl_oid * 193.Fo SYSCTL_ADD_U32 194.Fa "struct sysctl_ctx_list *ctx" 195.Fa "struct sysctl_oid_list *parent" 196.Fa "int number" 197.Fa "const char *name" 198.Fa "int access" 199.Fa "uint32_t *arg" 200.Fa "const char *descr" 201.Fc 202.Ft struct sysctl_oid * 203.Fo SYSCTL_ADD_U64 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 access" 209.Fa "uint64_t *arg" 210.Fa "int len" 211.Fa "const char *descr" 212.Fc 213.Ft struct sysctl_oid * 214.Fo SYSCTL_ADD_UINT 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 access" 220.Fa "unsigned int *arg" 221.Fa "int val" 222.Fa "const char *descr" 223.Fc 224.Ft struct sysctl_oid * 225.Fo SYSCTL_ADD_LONG 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 access" 231.Fa "long *arg" 232.Fa "const char *descr" 233.Fc 234.Ft struct sysctl_oid * 235.Fo SYSCTL_ADD_ULONG 236.Fa "struct sysctl_ctx_list *ctx" 237.Fa "struct sysctl_oid_list *parent" 238.Fa "int number" 239.Fa "const char *name" 240.Fa "int access" 241.Fa "unsigned long *arg" 242.Fa "const char *descr" 243.Fc 244.Ft struct sysctl_oid * 245.Fo SYSCTL_ADD_QUAD 246.Fa "struct sysctl_ctx_list *ctx" 247.Fa "struct sysctl_oid_list *parent" 248.Fa "int number" 249.Fa "const char *name" 250.Fa "int access" 251.Fa "quad_t *arg" 252.Fa "int val" 253.Fa "const char *descr" 254.Fc 255.Ft struct sysctl_oid * 256.Fo SYSCTL_ADD_UQUAD 257.Fa "struct sysctl_ctx_list *ctx" 258.Fa "struct sysctl_oid_list *parent" 259.Fa "int number" 260.Fa "const char *name" 261.Fa "int access" 262.Fa "u_quad_t *arg" 263.Fa "int val" 264.Fa "const char *descr" 265.Fc 266.Ft struct sysctl_oid * 267.Fo SYSCTL_ADD_OPAQUE 268.Fa "struct sysctl_ctx_list *ctx" 269.Fa "struct sysctl_oid_list *parent" 270.Fa "int number" 271.Fa "const char *name" 272.Fa "int access" 273.Fa "void *arg" 274.Fa "int len" 275.Fa "const char *format" 276.Fa "const char *descr" 277.Fc 278.Ft struct sysctl_oid * 279.Fo SYSCTL_ADD_STRUCT 280.Fa "struct sysctl_ctx_list *ctx" 281.Fa "struct sysctl_oid_list *parent" 282.Fa "int number" 283.Fa "const char *name" 284.Fa "int access" 285.Fa "void *arg" 286.Fa STRUCT_NAME 287.Fa "const char *descr" 288.Fc 289.Ft struct sysctl_oid * 290.Fo SYSCTL_ADD_PROC 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 access" 296.Fa "void *arg1" 297.Fa "int arg2" 298.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" 299.Fa "const char *format" 300.Fa "const char *descr" 301.Fc 302.Sh DESCRIPTION 303These functions and macros provide an interface 304for creating and deleting sysctl oids at runtime 305(e.g.\& during lifetime of a module). 306The alternative method, 307based on linker sets (see 308.In sys/linker_set.h 309and 310.\" XXX Manual pages should avoid referencing source files 311.Pa /sys/kern/kern_sysctl.c 312for details), only allows creation and deletion 313on module load and unload respectively. 314.Pp 315Dynamic oids of type 316.Dv CTLTYPE_NODE 317are reusable 318so that several code sections can create and delete them, 319but in reality they are allocated and freed 320based on their reference count. 321As a consequence, 322it is possible for two or more code sections 323to create partially overlapping trees that they both can use. 324It is not possible to create overlapping leaves, 325nor to create different child types with the same name and parent. 326.Pp 327Newly created oids are connected to their parent nodes. 328In all these functions and macros 329(with the exception of 330.Fn sysctl_remove_oid ) , 331one of the required parameters is 332.Fa parent , 333which points to the head of the parent's list of children. 334.Pp 335Most top level categories are created statically. 336When connecting to existing static oids, 337this pointer can be obtained with the 338.Fn SYSCTL_STATIC_CHILDREN 339macro, where the 340.Fa OID_NAME 341argument is name of the parent oid of type 342.Dv CTLTYPE_NODE 343(i.e., the name displayed by 344.Xr sysctl 8 , 345preceded by underscore, and with all dots replaced with underscores). 346.Pp 347When connecting to an existing dynamic oid, this pointer 348can be obtained with the 349.Fn SYSCTL_CHILDREN 350macro, where the 351.Fa oidp 352argument points to the parent oid of type 353.Dv CTLTYPE_NODE . 354.Pp 355The 356.Fn sysctl_add_oid 357function creates raw oids of any type. 358If the oid is successfully created, 359the function returns a pointer to it; 360otherwise it returns 361.Dv NULL . 362Many of the arguments for 363.Fn sysctl_add_oid 364are common to the macros. 365The arguments are as follows: 366.Bl -tag -width handler 367.It Fa ctx 368A pointer to an optional sysctl context, or 369.Dv NULL . 370See 371.Xr sysctl_ctx_init 9 372for details. 373Programmers are strongly advised to use contexts 374to organize the dynamic oids which they create, 375unless special creation and deletion sequences are required. 376If 377.Fa ctx 378is not 379.Dv NULL , 380the newly created oid will be added to this context 381as its first entry. 382.It Fa parent 383A pointer to a 384.Li struct sysctl_oid_list , 385which is the head of the parent's list of children. 386.It Fa number 387The oid number that will be assigned to this oid. 388In almost all cases this should be set to 389.Dv OID_AUTO , 390which will result in the assignment of the next available oid number. 391.It Fa name 392The name of the oid. 393The newly created oid will contain a copy of the name. 394.It Fa kind 395The kind of oid, 396specified as a bit mask of the type and access values defined in the 397.In sys/sysctl.h 398header file. 399Oids created dynamically always have the 400.Dv CTLFLAG_DYN 401flag set. 402Access flags specify whether this oid is read-only or read-write, 403and whether it may be modified by all users 404or by the superuser only. 405.It Fa arg1 406A pointer to any data that the oid should reference, or 407.Dv NULL . 408.It Fa arg2 409The size of 410.Fa arg1 , 411or 0 if 412.Fa arg1 413is 414.Dv NULL . 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 also to define new handlers using the 423.Fn SYSCTL_ADD_PROC 424macro. 425.It Fa format 426A pointer to a string 427which specifies the format of the oid symbolically. 428This format is used as a hint by 429.Xr sysctl 8 430to apply proper data formatting for display purposes. 431Currently used format names are: 432.Dq N 433for node, 434.Dq A 435for 436.Li "char *" , 437.Dq I 438for 439.Li "int" , 440.Dq IU 441for 442.Li "unsigned int" , 443.Dq IK 444for temperature in tenths of kelvins, 445.Dq L 446for 447.Li "long" , 448.Dq LU 449for 450.Li "unsigned long" 451and 452.Dq S,TYPE 453for 454.Li "struct TYPE" 455structures. 456.It Fa descr 457A pointer to a textual description of the oid. 458.El 459.Pp 460The 461.Fn sysctl_remove_oid 462function removes a dynamically created oid from the tree, 463optionally freeing its resources. 464It takes the following arguments: 465.Bl -tag -width recurse 466.It Fa oidp 467A pointer to the dynamic oid to be removed. 468If the oid is not dynamic, or the pointer is 469.Dv NULL , 470the function returns 471.Er EINVAL . 472.It Fa del 473If non-zero, 474.Fn sysctl_remove_oid 475will try to free the oid's resources 476when the reference count of the oid becomes zero. 477However, if 478.Fa del 479is set to 0, 480the routine will only deregister the oid from the tree, 481without freeing its resources. 482This behaviour is useful when the caller expects to rollback 483(possibly partially failed) 484deletion of many oids later. 485.It Fa recurse 486If non-zero, attempt to remove the node and all its children. 487If 488.Fa recurse 489is set to 0, 490any attempt to remove a node that contains any children 491will result in a 492.Er ENOTEMPTY 493error. 494.Em WARNING : "use recursive deletion with extreme caution" ! 495Normally it should not be needed if contexts are used. 496Contexts take care of tracking inter-dependencies 497between users of the tree. 498However, in some extreme cases it might be necessary 499to remove part of the subtree no matter how it was created, 500in order to free some other resources. 501Be aware, though, that this may result in a system 502.Xr panic 9 503if other code sections continue to use removed subtrees. 504.El 505.Pp 506.\" XXX sheldonh finished up to here 507Again, in most cases the programmer should use contexts, 508as described in 509.Xr sysctl_ctx_init 9 , 510to keep track of created oids, 511and to delete them later in orderly fashion. 512.Pp 513There is a set of macros defined 514that helps to create oids of given type. 515.Pp 516They are as follows: 517.Bl -tag -width SYSCTL_ADD_STRINGXX 518.It Fn SYSCTL_ADD_OID 519creates a raw oid. 520This macro is functionally equivalent to the 521.Fn sysctl_add_oid 522function. 523.It Fn SYSCTL_ADD_NODE 524creates an oid of type 525.Dv CTLTYPE_NODE , 526to which child oids may be added. 527.It Fn SYSCTL_ADD_S8 528creates an oid that handles an 529.Li int8_t 530variable. 531.It Fn SYSCTL_ADD_S16 532creates an oid that handles an 533.Li int16_t 534variable. 535.It Fn SYSCTL_ADD_S32 536creates an oid that handles an 537.Li int16_t 538variable. 539.It Fn SYSCTL_ADD_S64 540creates an oid that handles an 541.Li int64_t 542variable. 543.It Fn SYSCTL_ADD_STRING 544creates an oid that handles a zero-terminated character string. 545.It Fn SYSCTL_ADD_INT 546creates an oid that handles an 547.Li int 548variable. 549.It Fn SYSCTL_ADD_U8 550creates an oid that handles a 551.Li uint8_t 552variable. 553.It Fn SYSCTL_ADD_U16 554creates an oid that handles a 555.Li uint16_t 556variable. 557.It Fn SYSCTL_ADD_U32 558creates an oid that handles a 559.Li uint32_t 560variable. 561.It Fn SYSCTL_ADD_U64 562creates an oid that handles a 563.Li uint64_t 564variable. 565.It Fn SYSCTL_ADD_UINT 566creates an oid that handles an 567.Li unsigned int 568variable. 569.It Fn SYSCTL_ADD_LONG 570creates an oid that handles a 571.Li long 572variable. 573.It Fn SYSCTL_ADD_ULONG 574creates an oid that handles an 575.Li unsigned long 576variable. 577.It Fn SYSCTL_ADD_QUAD 578creates an oid that handles a 64-bit 579.Li int 580variable. 581.It Fn SYSCTL_ADD_UQUAD 582creates an oid that handles a 64-bit 583.Li unsigned int 584variable. 585.It Fn SYSCTL_ADD_OPAQUE 586creates an oid that handles any chunk of opaque data 587of the size specified by the 588.Fa len 589argument, 590which is a pointer to a 591.Li "size_t *" . 592.It Fn SYSCTL_ADD_STRUCT 593creates an oid that handles a 594.Li "struct TYPE" 595structure. 596The 597.Fa format 598parameter will be set to 599.Dq S,TYPE 600to provide proper hints to the 601.Xr sysctl 8 602utility. 603.It Fn SYSCTL_ADD_PROC 604creates an oid with the specified 605.Fa handler 606function. 607The handler is responsible for handling read and write requests 608to the oid. 609This oid type is especially useful 610if the kernel data is not easily accessible, 611or needs to be processed before exporting. 612.El 613.Sh EXAMPLES 614The following is an example of 615how to create a new top-level category 616and how to hook up another subtree to an existing static node. 617This example does not use contexts, 618which results in tedious management of all intermediate oids, 619as they need to be freed later on: 620.Bd -literal 621#include <sys/sysctl.h> 622 ... 623/* Need to preserve pointers to newly created subtrees, to be able 624 * to free them later. 625 */ 626struct sysctl_oid *root1, *root2, *oidp; 627int a_int; 628char *string = "dynamic sysctl"; 629 ... 630 631root1 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(/* tree top */), 632 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); 633oidp = SYSCTL_ADD_INT( NULL, SYSCTL_CHILDREN(root1), 634 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); 635 ... 636root2 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(_debug), 637 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); 638oidp = SYSCTL_ADD_STRING( NULL, SYSCTL_CHILDREN(root2), 639 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); 640.Ed 641.Pp 642This example creates the following subtrees: 643.Bd -literal -offset indent 644debug.newtree.newstring 645newtree.newint 646.Ed 647.Pp 648.Em "Care should be taken to free all oids once they are no longer needed!" 649.Sh SEE ALSO 650.Xr sysctl 8 , 651.Xr sysctl 9 , 652.Xr sysctl_ctx_free 9 , 653.Xr sysctl_ctx_init 9 654.Sh HISTORY 655These functions first appeared in 656.Fx 4.2 . 657.Sh AUTHORS 658.An Andrzej Bialecki Aq Mt abial@FreeBSD.org 659.Sh BUGS 660Sharing nodes between many code sections 661causes interdependencies that sometimes may lock the resources. 662For example, 663if module A hooks up a subtree to an oid created by module B, 664module B will be unable to delete that oid. 665These issues are handled properly by sysctl contexts. 666.Pp 667Many operations on the tree involve traversing linked lists. 668For this reason, oid creation and removal is relatively costly. 669