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