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$ 29.\" 30.Dd July 15, 2000 31.Dt SYSCTL_ADD_OID 9 32.Os 33.Sh NAME 34.Nm sysctl_add_oid , 35.Nm sysctl_move_oid , 36.Nm sysctl_remove_oid 37.Nd runtime sysctl tree manipulation 38.Sh SYNOPSIS 39.In sys/types.h 40.In sys/sysctl.h 41.Ft struct sysctl_oid * 42.Fo sysctl_add_oid 43.Fa "struct sysctl_ctx_list *ctx" 44.Fa "struct sysctl_oid_list *parent" 45.Fa "int number" 46.Fa "const char *name" 47.Fa "int kind" 48.Fa "void *arg1" 49.Fa "int arg2" 50.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" 51.Fa "const char *format" 52.Fa "const char *descr" 53.Fc 54.Ft int 55.Fo sysctl_move_oid 56.Fa "struct sysctl_oid *oidp" 57.Fa "struct sysctl_oid_list *parent" 58.Fc 59.Ft int 60.Fo sysctl_remove_oid 61.Fa "struct sysctl_oid *oidp" 62.Fa "int del" 63.Fa "int recurse" 64.Fc 65.Ft struct sysctl_oid_list * 66.Fo SYSCTL_CHILDREN 67.Fa "struct sysctl_oid *oidp" 68.Fc 69.Ft struct sysctl_oid_list * 70.Fo SYSCTL_STATIC_CHILDREN 71.Fa "struct sysctl_oid_list OID_NAME" 72.Fc 73.Ft struct sysctl_oid * 74.Fo SYSCTL_ADD_OID 75.Fa "struct sysctl_ctx_list *ctx" 76.Fa "struct sysctl_oid_list *parent" 77.Fa "int number" 78.Fa "const char *name" 79.Fa "int kind" 80.Fa "void *arg1" 81.Fa "int arg2" 82.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" 83.Fa "const char *format" 84.Fa "const char *descr" 85.Fc 86.Ft struct sysctl_oid * 87.Fo SYSCTL_ADD_NODE 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 access" 93.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" 94.Fa "const char *descr" 95.Fc 96.Ft struct sysctl_oid * 97.Fo SYSCTL_ADD_STRING 98.Fa "struct sysctl_ctx_list *ctx" 99.Fa "struct sysctl_oid_list *parent" 100.Fa "int number" 101.Fa "const char *name" 102.Fa "int access" 103.Fa "char *arg" 104.Fa "int len" 105.Fa "const char *descr" 106.Fc 107.Ft struct sysctl_oid * 108.Fo SYSCTL_ADD_INT 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 access" 114.Fa "int *arg" 115.Fa "int len" 116.Fa "const char *descr" 117.Fc 118.Ft struct sysctl_oid * 119.Fo SYSCTL_ADD_UINT 120.Fa "struct sysctl_ctx_list *ctx" 121.Fa "struct sysctl_oid_list *parent" 122.Fa "int number" 123.Fa "const char *name" 124.Fa "int access" 125.Fa "unsigned int *arg" 126.Fa "int len" 127.Fa "const char *descr" 128.Fc 129.Ft struct sysctl_oid * 130.Fo SYSCTL_ADD_LONG 131.Fa "struct sysctl_ctx_list *ctx" 132.Fa "struct sysctl_oid_list *parent" 133.Fa "int number" 134.Fa "const char *name" 135.Fa "int access" 136.Fa "long *arg" 137.Fa "const char *descr" 138.Fc 139.Ft struct sysctl_oid * 140.Fo SYSCTL_ADD_ULONG 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 access" 146.Fa "unsigned long *arg" 147.Fa "const char *descr" 148.Fc 149.Ft struct sysctl_oid * 150.Fo SYSCTL_ADD_QUAD 151.Fa "struct sysctl_ctx_list *ctx" 152.Fa "struct sysctl_oid_list *parent" 153.Fa "int number" 154.Fa "const char *name" 155.Fa "int access" 156.Fa "int64_t *arg" 157.Fa "const char *descr" 158.Fc 159.Ft struct sysctl_oid * 160.Fo SYSCTL_ADD_OPAQUE 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 "void *arg" 167.Fa "int len" 168.Fa "const char *format" 169.Fa "const char *descr" 170.Fc 171.Ft struct sysctl_oid * 172.Fo SYSCTL_ADD_STRUCT 173.Fa "struct sysctl_ctx_list *ctx" 174.Fa "struct sysctl_oid_list *parent" 175.Fa "int number" 176.Fa "const char *name" 177.Fa "int access" 178.Fa "void *arg" 179.Fa STRUCT_NAME 180.Fa "const char *descr" 181.Fc 182.Ft struct sysctl_oid * 183.Fo SYSCTL_ADD_PROC 184.Fa "struct sysctl_ctx_list *ctx" 185.Fa "struct sysctl_oid_list *parent" 186.Fa "int number" 187.Fa "const char *name" 188.Fa "int access" 189.Fa "void *arg1" 190.Fa "int arg2" 191.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" 192.Fa "const char *format" 193.Fa "const char *descr" 194.Fc 195.Sh DESCRIPTION 196These functions and macros provide an interface 197for creating and deleting sysctl oids at runtime 198(e.g.\& during lifetime of a module). 199The alternative method, 200based on linker sets (see 201.In sys/linker_set.h 202and 203.\" XXX Manual pages should avoid referencing source files 204.Pa src/sys/kern/kern_sysctl.c 205for details), only allows creation and deletion 206on module load and unload respectively. 207.Pp 208Dynamic oids of type 209.Dv CTLTYPE_NODE 210are reusable 211so that several code sections can create and delete them, 212but in reality they are allocated and freed 213based on their reference count. 214As a consequence, 215it is possible for two or more code sections 216to create partially overlapping trees that they both can use. 217It is not possible to create overlapping leaves, 218nor to create different child types with the same name and parent. 219.Pp 220Newly created oids are connected to their parent nodes. 221In all these functions and macros 222(with the exception of 223.Fn sysctl_remove_oid ) , 224one of the required parameters is 225.Fa parent , 226which points to the head of the parent's list of children. 227.Pp 228Most top level categories are created statically. 229When connecting to existing static oids, 230this pointer can be obtained with the 231.Fn SYSCTL_STATIC_CHILDREN 232macro, where the 233.Fa OID_NAME 234argument is name of the parent oid of type 235.Dv CTLTYPE_NODE 236(i.e., the name displayed by 237.Xr sysctl 8 , 238preceded by underscore, and with all dots replaced with underscores). 239.Pp 240When connecting to an existing dynamic oid, this pointer 241can be obtained with the 242.Fn SYSCTL_CHILDREN 243macro, where the 244.Fa oidp 245argument points to the parent oid of type 246.Dv CTLTYPE_NODE . 247.Pp 248The 249.Fn sysctl_add_oid 250function creates raw oids of any type. 251If the oid is successfully created, 252the function returns a pointer to it; 253otherwise it returns 254.Dv NULL . 255Many of the arguments for 256.Fn sysctl_add_oid 257are common to the macros. 258The arguments are as follows: 259.Bl -tag -width handler 260.It Fa ctx 261A pointer to an optional sysctl context, or 262.Dv NULL . 263See 264.Xr sysctl_ctx_init 9 265for details. 266Programmers are strongly advised to use contexts 267to organize the dynamic oids which they create, 268unless special creation and deletion sequences are required. 269If 270.Fa ctx 271is not 272.Dv NULL , 273the newly created oid will be added to this context 274as its first entry. 275.It Fa parent 276A pointer to a 277.Li struct sysctl_oid_list , 278which is the head of the parent's list of children. 279.It Fa number 280The oid number that will be assigned to this oid. 281In almost all cases this should be set to 282.Dv OID_AUTO , 283which will result in the assignment of the next available oid number. 284.It Fa name 285The name of the oid. 286The newly created oid will contain a copy of the name. 287.It Fa kind 288The kind of oid, 289specified as a bit mask of the type and access values defined in the 290.In sys/sysctl.h 291header file. 292Oids created dynamically always have the 293.Dv CTLFLAG_DYN 294flag set. 295Access flags specify whether this oid is read-only or read-write, 296and whether it may be modified by all users 297or by the superuser only. 298.It Fa arg1 299A pointer to any data that the oid should reference, or 300.Dv NULL . 301.It Fa arg2 302The size of 303.Fa arg1 , 304or 0 if 305.Fa arg1 306is 307.Dv NULL . 308.It Fa handler 309A pointer to the function 310that is responsible for handling read and write requests 311to this oid. 312There are several standard handlers 313that support operations on nodes, 314integers, strings and opaque objects. 315It is possible also to define new handlers using the 316.Fn SYSCTL_ADD_PROC 317macro. 318.It Fa format 319A pointer to a string 320which specifies the format of the oid symbolically. 321This format is used as a hint by 322.Xr sysctl 8 323to apply proper data formatting for display purposes. 324Currently used format names are: 325.Dq N 326for node, 327.Dq A 328for 329.Li "char *" , 330.Dq I 331for 332.Li "int" , 333.Dq IU 334for 335.Li "unsigned int" , 336.Dq L 337for 338.Li "long" , 339.Dq LU 340for 341.Li "unsigned long" 342and 343.Dq S,TYPE 344for 345.Li "struct TYPE" 346structures. 347.It Fa descr 348A pointer to a textual description of the oid. 349.El 350.Pp 351The 352.Fn sysctl_move_oid 353function reparents an existing oid. 354The oid is assigned a new number as if it had been created with 355.Fa number 356set to 357.Dv OID_AUTO . 358.Pp 359The 360.Fn sysctl_remove_oid 361function removes a dynamically created oid from the tree, 362optionally freeing its resources. 363It takes the following arguments: 364.Bl -tag -width recurse 365.It Fa oidp 366A pointer to the dynamic oid to be removed. 367If the oid is not dynamic, or the pointer is 368.Dv NULL , 369the function returns 370.Er EINVAL . 371.It Fa del 372If non-zero, 373.Fn sysctl_remove_oid 374will try to free the oid's resources 375when the reference count of the oid becomes zero. 376However, if 377.Fa del 378is set to 0, 379the routine will only deregister the oid from the tree, 380without freeing its resources. 381This behaviour is useful when the caller expects to rollback 382(possibly partially failed) 383deletion of many oids later. 384.It Fa recurse 385If non-zero, attempt to remove the node and all its children. 386If 387.Pa recurse 388is set to 0, 389any attempt to remove a node that contains any children 390will result in a 391.Er ENOTEMPTY 392error. 393.Em WARNING : "use recursive deletion with extreme caution" ! 394Normally it should not be needed if contexts are used. 395Contexts take care of tracking inter-dependencies 396between users of the tree. 397However, in some extreme cases it might be necessary 398to remove part of the subtree no matter how it was created, 399in order to free some other resources. 400Be aware, though, that this may result in a system 401.Xr panic 9 402if other code sections continue to use removed subtrees. 403.El 404.Pp 405.\" XXX sheldonh finished up to here 406Again, in most cases the programmer should use contexts, 407as described in 408.Xr sysctl_ctx_init 9 , 409to keep track of created oids, 410and to delete them later in orderly fashion. 411.Pp 412There is a set of macros defined 413that helps to create oids of given type. 414They are as follows: 415.Bl -tag -width SYSCTL_ADD_STRINGXX 416.It Fn SYSCTL_ADD_OID 417creates a raw oid. 418This macro is functionally equivalent to the 419.Fn sysctl_add_oid 420function. 421.It Fn SYSCTL_ADD_NODE 422creates an oid of type 423.Dv CTLTYPE_NODE , 424to which child oids may be added. 425.It Fn SYSCTL_ADD_STRING 426creates an oid that handles a zero-terminated character string. 427.It Fn SYSCTL_ADD_INT 428creates an oid that handles an 429.Li int 430variable. 431.It Fn SYSCTL_ADD_UINT 432creates an oid that handles an 433.Li unsigned int 434variable. 435.It Fn SYSCTL_ADD_LONG 436creates an oid that handles a 437.Li long 438variable. 439.It Fn SYSCTL_ADD_ULONG 440creates an oid that handles an 441.Li unsigned long 442variable. 443.It Fn SYSCTL_ADD_QUAD 444creates an oid that handles an 445.Li int64_t 446variable. 447.It Fn SYSCTL_ADD_OPAQUE 448creates an oid that handles any chunk of opaque data 449of the size specified by the 450.Fa len 451argument, 452which is a pointer to a 453.Li "size_t *" . 454.It Fn SYSCTL_ADD_STRUCT 455creates an oid that handles a 456.Li "struct TYPE" 457structure. 458The 459.Fa format 460parameter will be set to 461.Dq S,TYPE 462to provide proper hints to the 463.Xr sysctl 8 464utility. 465.It Fn SYSCTL_ADD_PROC 466creates an oid with the specified 467.Pa handler 468function. 469The handler is responsible for handling read and write requests 470to the oid. 471This oid type is especially useful 472if the kernel data is not easily accessible, 473or needs to be processed before exporting. 474.El 475.Sh EXAMPLES 476The following is an example of 477how to create a new top-level category 478and how to hook up another subtree to an existing static node. 479This example does not use contexts, 480which results in tedious management of all intermediate oids, 481as they need to be freed later on: 482.Bd -literal 483#include <sys/sysctl.h> 484 ... 485/* Need to preserve pointers to newly created subtrees, to be able 486 * to free them later. 487 */ 488struct sysctl_oid *root1, *root2, *oidp; 489int a_int; 490char *string = "dynamic sysctl"; 491 ... 492 493root1 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(/* tree top */), 494 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); 495oidp = SYSCTL_ADD_INT( NULL, SYSCTL_CHILDREN(root1), 496 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); 497 ... 498root2 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(_debug), 499 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); 500oidp = SYSCTL_ADD_STRING( NULL, SYSCTL_CHILDREN(root2), 501 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); 502.Ed 503.Pp 504This example creates the following subtrees: 505.Bd -literal -offset indent 506debug.newtree.newstring 507newtree.newint 508.Ed 509.Pp 510.Em "Care should be taken to free all oids once they are no longer needed!" 511.Sh SEE ALSO 512.Xr sysctl 8 , 513.Xr sysctl 9 , 514.Xr sysctl_ctx_free 9 , 515.Xr sysctl_ctx_init 9 516.Sh HISTORY 517These functions first appeared in 518.Fx 4.2 . 519.Sh AUTHORS 520.An Andrzej Bialecki Aq abial@FreeBSD.org 521.Sh BUGS 522Sharing nodes between many code sections 523causes interdependencies that sometimes may lock the resources. 524For example, 525if module A hooks up a subtree to an oid created by module B, 526module B will be unable to delete that oid. 527These issues are handled properly by sysctl contexts. 528.Pp 529Many operations on the tree involve traversing linked lists. 530For this reason, oid creation and removal is relatively costly. 531