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 May 16, 2015 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 IK 342for temperature in tenths of kelvins, 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_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 a 64-bit 445.Li int 446variable. 447.It Fn SYSCTL_ADD_UQUAD 448creates an oid that handles a 64-bit 449.Li unsigned int 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 Mt 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