- Uniformly use .In for header file references.
[dragonfly.git] / share / man / man9 / sysctl_add_oid.9
CommitLineData
984263bc
MD
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.3.2.10 2001/12/17 11:30:19 ru Exp $
44cb301e 29.\" $DragonFly: src/share/man/man9/sysctl_add_oid.9,v 1.3 2006/05/26 19:39:40 swildner Exp $
984263bc
MD
30.\"
31.Dd July 15, 2000
32.Dt SYSCTL_ADD_OID 9
33.Os
34.Sh NAME
35.Nm sysctl_add_oid ,
36.Nm sysctl_remove_oid
37.Nd runtime sysctl tree manipulation
38.Sh SYNOPSIS
39.In sys/sysctl.h
40.Ft struct sysctl_oid *
41.Fo sysctl_add_oid
42.Fa "struct sysctl_ctx_list *ctx"
43.Fa "struct sysctl_oid_list *parent"
44.Fa "int number"
45.Fa "char *name"
46.Fa "int kind"
47.Fa "void *arg1"
48.Fa "int arg2"
49.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
50.Fa "char *format"
51.Fa "char *descr"
52.Fc
53.Ft int
54.Fo sysctl_remove_oid
55.Fa "struct sysctl_oid *oidp"
56.Fa "int del"
57.Fa "int recurse"
58.Fc
59.Ft struct sysctl_oid_list *
60.Fo SYSCTL_CHILDREN
61.Fa "struct sysctl_oid *oidp"
62.Fc
63.Ft struct sysctl_oid_list *
64.Fo SYSCTL_STATIC_CHILDREN
65.Fa "OID_NAME"
66.Fc
67.Ft struct sysctl_oid *
68.Fo SYSCTL_ADD_OID
69.Fa "struct sysctl_ctx_list *ctx"
70.Fa "struct sysctl_oid_list *parent"
71.Fa "int number"
72.Fa "NAME"
73.Fa "int kind"
74.Fa "void *arg1"
75.Fa "int arg2"
76.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
77.Fa "char *format"
78.Fa "char *descr"
79.Fc
80.Ft struct sysctl_oid *
81.Fo SYSCTL_ADD_NODE
82.Fa "struct sysctl_ctx_list *ctx"
83.Fa "struct sysctl_oid_list *parent"
84.Fa "int number"
85.Fa "NAME"
86.Fa "int access"
87.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
88.Fa "char *descr"
89.Fc
90.Ft struct sysctl_oid *
91.Fo SYSCTL_ADD_STRING
92.Fa "struct sysctl_ctx_list *ctx"
93.Fa "struct sysctl_oid_list *parent"
94.Fa "int number"
95.Fa "NAME"
96.Fa "int access"
97.Fa "char *arg"
98.Fa "0"
99.Fa "char *descr"
100.Fc
101.Ft struct sysctl_oid *
102.Fo SYSCTL_ADD_INT
103.Fa "struct sysctl_ctx_list *ctx"
104.Fa "struct sysctl_oid_list *parent"
105.Fa "int number"
106.Fa "NAME"
107.Fa "int access"
108.Fa "int *arg"
109.Fa "0"
110.Fa "char *descr"
111.Fc
112.Ft struct sysctl_oid *
113.Fo SYSCTL_ADD_UINT
114.Fa "struct sysctl_ctx_list *ctx"
115.Fa "struct sysctl_oid_list *parent"
116.Fa "int number"
117.Fa "NAME"
118.Fa "int access"
119.Fa "unsigned int *arg"
120.Fa "0"
121.Fa "char *descr"
122.Fc
123.Ft struct sysctl_oid *
124.Fo SYSCTL_ADD_LONG
125.Fa "struct sysctl_ctx_list *ctx"
126.Fa "struct sysctl_oid_list *parent"
127.Fa "int number"
128.Fa "NAME"
129.Fa "int access"
130.Fa "long *arg"
131.Fa "0"
132.Fa "char *descr"
133.Fc
134.Ft struct sysctl_oid *
135.Fo SYSCTL_ADD_ULONG
136.Fa "struct sysctl_ctx_list *ctx"
137.Fa "struct sysctl_oid_list *parent"
138.Fa "int number"
139.Fa "NAME"
140.Fa "int access"
141.Fa "unsigned long *arg"
142.Fa "0"
143.Fa "char *descr"
144.Fc
145.Ft struct sysctl_oid *
146.Fo SYSCTL_ADD_OPAQUE
147.Fa "struct sysctl_ctx_list *ctx"
148.Fa "struct sysctl_oid_list *parent"
149.Fa "int number"
150.Fa "NAME"
151.Fa "int access"
152.Fa "void *arg"
153.Fa "size_t *len"
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
44cb301e 186.In sys/linker_set.h
984263bc
MD
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
44cb301e 275.In sys/sysctl.h
984263bc
MD
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, CTFLAG_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, CTFLAG_RW, 0, "new tree under debug");
473oidp = SYSCTL_ADD_STRING( NULL, SYSCTL_CHILDREN(root2),
474 OID_AUTO, newstring, CTLFLAG_R, 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.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 4.2 .
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.