2 .\" Copyright (c) 2006 Robert N. M. Watson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .Nm SYSCTL_ADD_OPAQUE ,
39 .Nm SYSCTL_ADD_ROOT_NODE ,
40 .Nm SYSCTL_ADD_STRING ,
41 .Nm SYSCTL_ADD_STRUCT ,
42 .Nm SYSCTL_ADD_UAUTO ,
44 .Nm SYSCTL_ADD_ULONG ,
45 .Nm SYSCTL_ADD_UQUAD ,
47 .Nm SYSCTL_STATIC_CHILDREN ,
48 .Nm SYSCTL_NODE_CHILDREN ,
56 .Nm SYSCTL_ROOT_NODE ,
62 .Nd Dynamic and static sysctl MIB creation functions
67 .Ft struct sysctl_oid *
69 .Fa "struct sysctl_ctx_list *ctx"
70 .Fa "struct sysctl_oid_list *parent"
72 .Fa "const char *name"
76 .Fa "const char *descr"
78 .Ft struct sysctl_oid *
80 .Fa "struct sysctl_ctx_list *ctx"
81 .Fa "struct sysctl_oid_list *parent"
83 .Fa "const char *name"
86 .Fa "const char *descr"
88 .Ft struct sysctl_oid *
90 .Fa "struct sysctl_ctx_list *ctx"
91 .Fa "struct sysctl_oid_list *parent"
93 .Fa "const char *name"
95 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
96 .Fa "const char *descr"
98 .Ft struct sysctl_oid *
100 .Fa "struct sysctl_ctx_list *ctx"
101 .Fa "struct sysctl_oid_list *parent"
103 .Fa "const char *name"
107 .Fa "const char *format"
108 .Fa "const char *descr"
110 .Ft struct sysctl_oid *
112 .Fa "struct sysctl_ctx_list *ctx"
113 .Fa "struct sysctl_oid_list *parent"
115 .Fa "const char *name"
119 .Fa "int (*handler) (SYSCTL_HANDLERARGS)"
120 .Fa "const char *format"
121 .Fa "const char *descr"
123 .Ft struct sysctl_oid *
125 .Fa "struct sysctl_ctx_list *ctx"
126 .Fa "struct sysctl_oid_list *parent"
128 .Fa "const char *name"
131 .Fa "const char *descr"
133 .Ft struct sysctl_oid *
134 .Fo SYSCTL_ADD_ROOT_NODE
135 .Fa "struct sysctl_ctx_list *ctx"
137 .Fa "const char *name"
139 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
140 .Fa "const char *descr"
142 .Ft struct sysctl_oid *
143 .Fo SYSCTL_ADD_STRING
144 .Fa "struct sysctl_ctx_list *ctx"
145 .Fa "struct sysctl_oid_list *parent"
147 .Fa "const char *name"
151 .Fa "const char *descr"
153 .Ft struct sysctl_oid *
154 .Fo SYSCTL_ADD_STRUCT
155 .Fa "struct sysctl_ctx_list *ctx"
156 .Fa "struct sysctl_oid_list *parent"
158 .Fa "const char *name"
162 .Fa "const char *descr"
164 .Ft struct sysctl_oid *
166 .Fa "struct sysctl_ctx_list *ctx"
167 .Fa "struct sysctl_oid_list *parent"
169 .Fa "const char *name"
171 .Fa "unsigned int *ptr"
173 .Fa "const char *descr"
175 .Ft struct sysctl_oid *
177 .Fa "struct sysctl_ctx_list *ctx"
178 .Fa "struct sysctl_oid_list *parent"
180 .Fa "const char *name"
182 .Fa "unsigned long *ptr"
183 .Fa "const char *descr"
185 .Ft struct sysctl_oid *
187 .Fa "struct sysctl_ctx_list *ctx"
188 .Fa "struct sysctl_oid_list *parent"
190 .Fa "const char *name"
193 .Fa "const char *descr"
195 .Ft struct sysctl_oid *
197 .Fa "struct sysctl_ctx_list *ctx"
198 .Fa "struct sysctl_oid_list *parent"
200 .Fa "const char *name"
203 .Fa "const char *descr"
205 .Ft struct sysctl_oid_list *
207 .Fa "struct sysctl_oid *oidp"
209 .Ft struct sysctl_oid_list *
210 .Fo SYSCTL_STATIC_CHILDREN
211 .Fa "struct sysctl_oid_list OID_NAME"
213 .Ft struct sysctl_oid_list *
214 .Fo SYSCTL_NODE_CHILDREN
218 .Ft struct sysctl_oid *
220 .Fa "struct sysctl_oid *oid"
222 .Fn SYSCTL_INT parent number name ctlflags ptr val descr
223 .Fn SYSCTL_LONG parent number name ctlflags ptr val descr
224 .Fn SYSCTL_NODE parent number name ctlflags handler descr
225 .Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr
226 .Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr
227 .Fn SYSCTL_QUAD parent number name ctlflags ptr val descr
228 .Fn SYSCTL_STRING parent number name ctlflags arg len descr
229 .Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr
230 .Fn SYSCTL_ROOT_NODE number name ctlflags handler descr
231 .Fn SYSCTL_UINT parent number name ctlflags ptr val descr
232 .Fn SYSCTL_ULONG parent number name ctlflags ptr val descr
233 .Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr
237 kernel interface allows dynamic or static creation of
240 All static sysctls are automatically destroyed when the module which
241 they are part of is unloaded.
242 Most top level categories are created statically and are available to
243 all kernel code and its modules.
244 .Sh DESCRIPTION OF ARGUMENTS
245 .Bl -tag -width ctlflags
247 Pointer to sysctl context or NULL, if no context.
249 .Xr sysctl_ctx_init 9
250 for how to create a new sysctl context.
251 Programmers are strongly advised to use contexts to organize the
252 dynamic OIDs which they create because when a context is destroyed all
253 belonging sysctls are destroyed as well.
254 This makes the sysctl cleanup code much simpler.
255 Else deletion of all created OIDs is required at module unload.
258 .Li struct sysctl_oid_list ,
259 which is the head of the parent's list of children.
260 This pointer is retrieved using the
261 .Fn SYSCTL_STATIC_CHILDREN
262 macro for static sysctls and the
264 macro for dynamic sysctls.
267 macro can be used to get the parent of an OID.
268 The macro returns NULL if there is no parent.
270 The OID number that will be assigned to this OID.
271 In almost all cases this should be set to
273 which will result in the assignment of the next available OID number.
276 The newly created OID will contain a copy of the name.
278 A bit mask of sysctl control flags.
279 See the section below describing all the control flags.
281 First callback argument for procedure sysctls.
283 Second callback argument for procedure sysctls.
285 The length of the data pointed to by the
288 For string type OIDs a length of zero means that
290 will be used to get the length of the string at each access to the OID.
292 Pointer to sysctl variable or string data.
293 For sysctl values the pointer can be SYSCTL_NULL_XXX_PTR which means the OID is read-only and the returned value should be taken from the
299 argument is SYSCTL_NULL_XXX_PTR, gives the constant value returned by this OID.
300 Else this argument is not used.
302 Name of structure type.
304 A pointer to the function
305 that is responsible for handling read and write requests
307 There are several standard handlers
308 that support operations on nodes,
309 integers, strings and opaque objects.
310 It is possible to define custom handlers using the
316 A pointer to a string
317 which specifies the format of the OID in a symbolic way.
318 This format is used as a hint by
320 to apply proper data formatting for display purposes.
321 Currently used format names are:
338 .Li "unsigned long" ,
351 A pointer to a textual description of the OID.
353 .Sh CREATING ROOT NODES
354 Sysctl MIBs or OIDs are created in a hierarchical tree.
355 The nodes at the bottom of the tree are called root nodes, and have no
357 To create bottom tree nodes the
360 .Fn SYSCTL_ADD_ROOT_NODE
361 function needs to be used.
362 By default all static sysctl node OIDs are global and need a
364 statement prior to their
366 definition statement, typically in a so-called header file.
367 .Sh CREATING SYSCTL STRINGS
368 Zero terminated character strings sysctls are created either using the
371 .Fn SYSCTL_ADD_STRING
375 argument in zero, the string length is computed at every access to the OID using
377 .Sh CREATING OPAQUE SYSCTLS
383 .Fn SYSCTL_ADD_OPAQUE
385 .Fn SYSCTL_ADD_STRUCT
386 functions create an OID that handle any chunk of data
387 of the size specified by the
389 argument and data pointed to by the
392 When using the structure version the type is encoded as part of the
394 .Sh CREATING CUSTOM SYSCTLS
400 create OIDs with the specified
403 The handler is responsible for handling all read and write requests to
405 This OID type is especially useful if the kernel data is not easily
406 accessible, or needs to be processed before exporting.
407 .Sh CREATING A STATIC SYSCTL
408 Static sysctls are declared using one of the
415 .Fn SYSCTL_ROOT_NODE ,
423 .Sh CREATING A DYNAMIC SYSCTL
424 Dynamic nodes are created using one of the
426 .Fn SYSCTL_ADD_LONG ,
427 .Fn SYSCTL_ADD_NODE ,
428 .Fn SYSCTL_ADD_OPAQUE ,
429 .Fn SYSCTL_ADD_PROC ,
430 .Fn SYSCTL_ADD_QUAD ,
431 .Fn SYSCTL_ADD_ROOT_NODE ,
432 .Fn SYSCTL_ADD_STRING ,
433 .Fn SYSCTL_ADD_STRUCT ,
434 .Fn SYSCTL_ADD_UAUTO ,
435 .Fn SYSCTL_ADD_UINT ,
436 .Fn SYSCTL_ADD_ULONG ,
441 .Xr sysctl_remove_oid 9
443 .Xr sysctl_ctx_free 9
444 for more information on how to destroy a dynamically created OID.
446 For most of the above functions and macros, declaring a type as part
447 of the access flags is not necessary \[em] however, when declaring a
448 sysctl implemented by a function, including a type in the access mask
450 .Bl -tag -width ".Dv CTLTYPE_NOFETCH"
452 This is a node intended to be a parent for other nodes.
454 This is a signed integer.
455 .It Dv CTLTYPE_STRING
456 This is a nul-terminated string stored in a character array.
458 This is a 64-bit signed integer.
459 .It Dv CTLTYPE_OPAQUE
460 This is an opaque data structure.
461 .It Dv CTLTYPE_STRUCT
465 This is an unsigned integer.
467 This is a signed long.
469 This is an unsigned long.
471 This is a 64-bit unsigned integer.
474 All sysctl types except for new node declarations require one of the following
475 flags to be set indicating the read and write disposition of the sysctl:
476 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
478 This is a read-only sysctl.
480 This is a read-only sysctl and tunable which is tried fetched once
481 from the system enviroment early during module load or system boot.
483 This is a writable sysctl.
485 This sysctl is readable and writable.
487 This is a readable and writeable sysctl and tunable which is tried
488 fetched once from the system enviroment early during module load or
490 .It Dv CTLFLAG_NOFETCH
491 In case the node is marked as a tunable using the CTLFLAG_[XX]TUN,
492 this flag will prevent fetching the initial value from the system
493 environment. Typically this flag should only be used for very early
494 low level system setup code, and not by common drivers and modules.
497 Additionally, any of the following optional flags may also be specified:
498 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
499 .It Dv CTLFLAG_ANYBODY
500 Any user or process can write to this sysctl.
501 .It Dv CTLFLAG_SECURE
502 This sysctl can be written to only if the effective securelevel of the
504 .It Dv CTLFLAG_PRISON
505 This sysctl can be written to by processes in
508 When iterating the sysctl name space, do not list this sysctl.
510 Advisory flag that a system tunable also exists for this variable.
511 The initial sysctl value is tried fetched once from the system
512 enviroment early during module load or system boot.
514 Dynamically created OIDs automatically get this flag set.
516 OID references a VIMAGE-enabled variable.
523 sysctl tree for use by new nodes:
524 .Bd -literal -offset indent
525 SYSCTL_DECL(_security);
528 Examples of integer, opaque, string, and procedure sysctls follow:
529 .Bd -literal -offset indent
531 * Example of a constant integer value. Notice that the control
532 * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR,
533 * and the value is declared.
535 SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR,
536 sizeof(struct bio), "sizeof(struct bio)");
539 * Example of a variable integer value. Notice that the control
540 * flags are CTLFLAG_RW, the variable pointer is set, and the
543 static int doingcache = 1; /* 1 => enable the cache */
544 SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0,
545 "Enable name cache");
548 * Example of a variable string value. Notice that the control
549 * flags are CTLFLAG_RW, that the variable pointer and string
550 * size are set. Unlike newer sysctls, this older sysctl uses a
553 char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */
554 SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW,
555 kernelname, sizeof(kernelname), "Name of kernel file booted");
558 * Example of an opaque data type exported by sysctl. Notice that
559 * the variable pointer and size are provided, as well as a format
560 * string for sysctl(8).
562 static l_fp pps_freq; /* scaled frequence offset (ns/s) */
563 SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD,
564 &pps_freq, sizeof(pps_freq), "I", "");
567 * Example of a procedure based sysctl exporting string
568 * information. Notice that the data type is declared, the NULL
569 * variable pointer and 0 size, the function pointer, and the
570 * format string for sysctl(8).
572 SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING |
573 CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A",
577 The following is an example of
578 how to create a new top-level category
579 and how to hook up another subtree to an existing static node.
580 This example does not use contexts,
581 which results in tedious management of all intermediate oids,
582 as they need to be freed later on:
583 .Bd -literal -offset indent
584 #include <sys/sysctl.h>
587 * Need to preserve pointers to newly created subtrees,
588 * to be able to free them later:
590 static struct sysctl_oid *root1;
591 static struct sysctl_oid *root2;
592 static struct sysctl_oid *oidp;
594 static char *string = "dynamic sysctl";
597 root1 = SYSCTL_ADD_ROOT_NODE(NULL,
598 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree");
599 oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1),
600 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf");
602 root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug),
603 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug");
604 oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2),
605 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf");
608 This example creates the following subtrees:
609 .Bd -literal -offset indent
610 debug.newtree.newstring
614 .Em "Care should be taken to free all OIDs once they are no longer needed!"
616 When adding, modifying, or removing sysctl names, it is important to be
617 aware that these interfaces may be used by users, libraries, applications,
618 or documentation (such as published books), and are implicitly published application interfaces.
619 As with other application interfaces, caution must be taken not to break
620 existing applications, and to think about future use of new name spaces so as
621 to avoid the need to rename or remove interfaces that might be depended on in
624 The semantics chosen for a new sysctl should be as clear as possible,
625 and the name of the sysctl must closely reflect its semantics.
626 Therefore the sysctl name deserves a fair amount of consideration.
627 It should be short but yet representative of the sysctl meaning.
628 If the name consists of several words, they should be separated by
629 underscore characters, as in
630 .Va compute_summary_at_mount .
631 Underscore characters may be omitted only if the name consists of not more
632 than two words, each being not longer than four characters, as in
634 For boolean sysctls, negative logic should be totally avoided.
635 That is, do not use names like
639 They are confusing and lead to configuration errors.
640 Use positive logic instead:
644 A temporary sysctl node OID that should not be relied upon must be designated
645 as such by a leading underscore character in its name. For example:
650 .Xr sysctl_add_oid 9 ,
651 .Xr sysctl_ctx_free 9 ,
652 .Xr sysctl_ctx_init 9 ,
653 .Xr sysctl_remove_oid 9
657 utility first appeared in
663 implementation originally found in
665 has been extensively rewritten by
666 .An Poul-Henning Kamp
667 in order to add support for name lookups, name space iteration, and dynamic
668 addition of MIB nodes.
670 This man page was written by
671 .An Robert N. M. Watson .
672 .Sh SECURITY CONSIDERATIONS
673 When creating new sysctls, careful attention should be paid to the security
674 implications of the monitoring or management interface being created.
675 Most sysctls present in the kernel are read-only or writable only by the
677 Sysctls exporting extensive information on system data structures and
678 operation, especially those implemented using procedures, will wish to
679 implement access control to limit the undesired exposure of information about
680 other processes, network connections, etc.
682 The following top level sysctl name spaces are commonly used:
683 .Bl -tag -width ".Va regression"
685 Compatibility layer information.
687 Debugging information.
688 Various name spaces exist under
691 Hardware and device driver information.
693 Kernel behavior tuning; generally deprecated in favor of more specific
696 Machine-dependent configuration parameters.
699 Various protocols have name spaces under
702 Regression test configuration and information.
704 Security and security-policy configuration and information.
706 Reserved name space for the implementation of sysctl.
708 Configuration settings relating to user application behavior.
709 Generally, configuring applications using kernel sysctls is discouraged.
711 Virtual file system configuration and information.
713 Virtual memory subsystem configuration and information.