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