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