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