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