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