/share/man/man9/sysctl_add_oid.9

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