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 ,
44 .Nm SYSCTL_ADD_STRING ,
45 .Nm SYSCTL_ADD_STRUCT ,
50 .Nm SYSCTL_ADD_UAUTO ,
52 .Nm SYSCTL_ADD_ULONG ,
53 .Nm SYSCTL_ADD_UQUAD ,
55 .Nm SYSCTL_STATIC_CHILDREN ,
56 .Nm SYSCTL_NODE_CHILDREN ,
64 .Nm SYSCTL_ROOT_NODE ,
78 .Nd Dynamic and static sysctl MIB creation functions
83 .Ft struct sysctl_oid *
85 .Fa "struct sysctl_ctx_list *ctx"
86 .Fa "struct sysctl_oid_list *parent"
88 .Fa "const char *name"
92 .Fa "const char *descr"
94 .Ft struct sysctl_oid *
96 .Fa "struct sysctl_ctx_list *ctx"
97 .Fa "struct sysctl_oid_list *parent"
99 .Fa "const char *name"
102 .Fa "const char *descr"
104 .Ft struct sysctl_oid *
106 .Fa "struct sysctl_ctx_list *ctx"
107 .Fa "struct sysctl_oid_list *parent"
109 .Fa "const char *name"
111 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
112 .Fa "const char *descr"
114 .Ft struct sysctl_oid *
115 .Fo SYSCTL_ADD_OPAQUE
116 .Fa "struct sysctl_ctx_list *ctx"
117 .Fa "struct sysctl_oid_list *parent"
119 .Fa "const char *name"
123 .Fa "const char *format"
124 .Fa "const char *descr"
126 .Ft struct sysctl_oid *
128 .Fa "struct sysctl_ctx_list *ctx"
129 .Fa "struct sysctl_oid_list *parent"
131 .Fa "const char *name"
135 .Fa "int (*handler) (SYSCTL_HANDLERARGS)"
136 .Fa "const char *format"
137 .Fa "const char *descr"
139 .Ft struct sysctl_oid *
141 .Fa "struct sysctl_ctx_list *ctx"
142 .Fa "struct sysctl_oid_list *parent"
144 .Fa "const char *name"
147 .Fa "const char *descr"
149 .Ft struct sysctl_oid *
150 .Fo SYSCTL_ADD_ROOT_NODE
151 .Fa "struct sysctl_ctx_list *ctx"
153 .Fa "const char *name"
155 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
156 .Fa "const char *descr"
158 .Ft struct sysctl_oid *
160 .Fa "struct sysctl_ctx_list *ctx"
161 .Fa "struct sysctl_oid_list *parent"
163 .Fa "const char *name"
167 .Fa "const char *descr"
169 .Ft struct sysctl_oid *
171 .Fa "struct sysctl_ctx_list *ctx"
172 .Fa "struct sysctl_oid_list *parent"
174 .Fa "const char *name"
178 .Fa "const char *descr"
180 .Ft struct sysctl_oid *
182 .Fa "struct sysctl_ctx_list *ctx"
183 .Fa "struct sysctl_oid_list *parent"
185 .Fa "const char *name"
189 .Fa "const char *descr"
191 .Ft struct sysctl_oid *
193 .Fa "struct sysctl_ctx_list *ctx"
194 .Fa "struct sysctl_oid_list *parent"
196 .Fa "const char *name"
200 .Fa "const char *descr"
202 .Ft struct sysctl_oid *
203 .Fo SYSCTL_ADD_STRING
204 .Fa "struct sysctl_ctx_list *ctx"
205 .Fa "struct sysctl_oid_list *parent"
207 .Fa "const char *name"
211 .Fa "const char *descr"
213 .Ft struct sysctl_oid *
214 .Fo SYSCTL_ADD_STRUCT
215 .Fa "struct sysctl_ctx_list *ctx"
216 .Fa "struct sysctl_oid_list *parent"
218 .Fa "const char *name"
222 .Fa "const char *descr"
224 .Ft struct sysctl_oid *
226 .Fa "struct sysctl_ctx_list *ctx"
227 .Fa "struct sysctl_oid_list *parent"
229 .Fa "const char *name"
233 .Fa "const char *descr"
235 .Ft struct sysctl_oid *
237 .Fa "struct sysctl_ctx_list *ctx"
238 .Fa "struct sysctl_oid_list *parent"
240 .Fa "const char *name"
244 .Fa "const char *descr"
246 .Ft struct sysctl_oid *
248 .Fa "struct sysctl_ctx_list *ctx"
249 .Fa "struct sysctl_oid_list *parent"
251 .Fa "const char *name"
255 .Fa "const char *descr"
257 .Ft struct sysctl_oid *
259 .Fa "struct sysctl_ctx_list *ctx"
260 .Fa "struct sysctl_oid_list *parent"
262 .Fa "const char *name"
266 .Fa "const char *descr"
268 .Ft struct sysctl_oid *
270 .Fa "struct sysctl_ctx_list *ctx"
271 .Fa "struct sysctl_oid_list *parent"
273 .Fa "const char *name"
275 .Fa "unsigned int *ptr"
276 .Fa "unsigned int val"
277 .Fa "const char *descr"
279 .Ft struct sysctl_oid *
281 .Fa "struct sysctl_ctx_list *ctx"
282 .Fa "struct sysctl_oid_list *parent"
284 .Fa "const char *name"
286 .Fa "unsigned long *ptr"
287 .Fa "const char *descr"
289 .Ft struct sysctl_oid *
291 .Fa "struct sysctl_ctx_list *ctx"
292 .Fa "struct sysctl_oid_list *parent"
294 .Fa "const char *name"
297 .Fa "const char *descr"
299 .Ft struct sysctl_oid *
301 .Fa "struct sysctl_ctx_list *ctx"
302 .Fa "struct sysctl_oid_list *parent"
304 .Fa "const char *name"
307 .Fa "const char *descr"
309 .Ft struct sysctl_oid_list *
311 .Fa "struct sysctl_oid *oidp"
313 .Ft struct sysctl_oid_list *
314 .Fo SYSCTL_STATIC_CHILDREN
315 .Fa "struct sysctl_oid_list OID_NAME"
317 .Ft struct sysctl_oid_list *
318 .Fo SYSCTL_NODE_CHILDREN
322 .Ft struct sysctl_oid *
324 .Fa "struct sysctl_oid *oid"
326 .Fn SYSCTL_INT parent number name ctlflags ptr val descr
327 .Fn SYSCTL_LONG parent number name ctlflags ptr val descr
328 .Fn SYSCTL_NODE parent number name ctlflags handler descr
329 .Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr
330 .Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr
331 .Fn SYSCTL_QUAD parent number name ctlflags ptr val descr
332 .Fn SYSCTL_ROOT_NODE number name ctlflags handler descr
333 .Fn SYSCTL_S8 parent number name ctlflags ptr val descr
334 .Fn SYSCTL_S16 parent number name ctlflags ptr val descr
335 .Fn SYSCTL_S32 parent number name ctlflags ptr val descr
336 .Fn SYSCTL_S64 parent number name ctlflags ptr val descr
337 .Fn SYSCTL_STRING parent number name ctlflags arg len descr
338 .Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr
339 .Fn SYSCTL_U8 parent number name ctlflags ptr val descr
340 .Fn SYSCTL_U16 parent number name ctlflags ptr val descr
341 .Fn SYSCTL_U32 parent number name ctlflags ptr val descr
342 .Fn SYSCTL_U64 parent number name ctlflags ptr val descr
343 .Fn SYSCTL_UINT parent number name ctlflags ptr val descr
344 .Fn SYSCTL_ULONG parent number name ctlflags ptr val descr
345 .Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr
349 kernel interface allows dynamic or static creation of
352 All static sysctls are automatically destroyed when the module which
353 they are part of is unloaded.
354 Most top level categories are created statically and are available to
355 all kernel code and its modules.
356 .Sh DESCRIPTION OF ARGUMENTS
357 .Bl -tag -width ctlflags
359 Pointer to sysctl context or NULL, if no context.
361 .Xr sysctl_ctx_init 9
362 for how to create a new sysctl context.
363 Programmers are strongly advised to use contexts to organize the
364 dynamic OIDs which they create because when a context is destroyed all
365 belonging sysctls are destroyed as well.
366 This makes the sysctl cleanup code much simpler.
367 Else deletion of all created OIDs is required at module unload.
370 .Li struct sysctl_oid_list ,
371 which is the head of the parent's list of children.
372 This pointer is retrieved using the
373 .Fn SYSCTL_STATIC_CHILDREN
374 macro for static sysctls and the
376 macro for dynamic sysctls.
379 macro can be used to get the parent of an OID.
380 The macro returns NULL if there is no parent.
382 The OID number that will be assigned to this OID.
383 In almost all cases this should be set to
385 which will result in the assignment of the next available OID number.
388 The newly created OID will contain a copy of the name.
390 A bit mask of sysctl control flags.
391 See the section below describing all the control flags.
393 First callback argument for procedure sysctls.
395 Second callback argument for procedure sysctls.
397 The length of the data pointed to by the
400 For string type OIDs a length of zero means that
402 will be used to get the length of the string at each access to the OID.
404 Pointer to sysctl variable or string data.
405 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
411 argument is SYSCTL_NULL_XXX_PTR, gives the constant value returned by this OID.
412 Else this argument is not used.
414 Name of structure type.
416 A pointer to the function
417 that is responsible for handling read and write requests
419 There are several standard handlers
420 that support operations on nodes,
421 integers, strings and opaque objects.
422 It is possible to define custom handlers using the
428 A pointer to a string
429 which specifies the format of the OID in a symbolic way.
430 This format is used as a hint by
432 to apply proper data formatting for display purposes.
435 .Bl -tag -width "S,TYPE" -compact -offset indent
443 temperature in Kelvin, multiplied by an optional single digit
444 power of ten scaling factor: 1 (default) gives deciKelvin, 0 gives Kelvin, 3
461 A pointer to a textual description of the OID.
463 .Sh CREATING ROOT NODES
464 Sysctl MIBs or OIDs are created in a hierarchical tree.
465 The nodes at the bottom of the tree are called root nodes, and have no
467 To create bottom tree nodes the
470 .Fn SYSCTL_ADD_ROOT_NODE
471 function needs to be used.
472 By default all static sysctl node OIDs are global and need a
474 statement prior to their
476 definition statement, typically in a so-called header file.
477 .Sh CREATING SYSCTL STRINGS
478 Zero terminated character strings sysctls are created either using the
481 .Fn SYSCTL_ADD_STRING
485 argument in zero, the string length is computed at every access to the OID using
487 .Sh CREATING OPAQUE SYSCTLS
493 .Fn SYSCTL_ADD_OPAQUE
495 .Fn SYSCTL_ADD_STRUCT
496 functions create an OID that handle any chunk of data
497 of the size specified by the
499 argument and data pointed to by the
502 When using the structure version the type is encoded as part of the
504 .Sh CREATING CUSTOM SYSCTLS
510 create OIDs with the specified
513 The handler is responsible for handling all read and write requests to
515 This OID type is especially useful if the kernel data is not easily
516 accessible, or needs to be processed before exporting.
517 .Sh CREATING A STATIC SYSCTL
518 Static sysctls are declared using one of the
525 .Fn SYSCTL_ROOT_NODE ,
541 .Sh CREATING A DYNAMIC SYSCTL
542 Dynamic nodes are created using one of the
544 .Fn SYSCTL_ADD_LONG ,
545 .Fn SYSCTL_ADD_NODE ,
546 .Fn SYSCTL_ADD_OPAQUE ,
547 .Fn SYSCTL_ADD_PROC ,
548 .Fn SYSCTL_ADD_QUAD ,
549 .Fn SYSCTL_ADD_ROOT_NODE ,
554 .Fn SYSCTL_ADD_STRING ,
555 .Fn SYSCTL_ADD_STRUCT ,
560 .Fn SYSCTL_ADD_UAUTO ,
561 .Fn SYSCTL_ADD_UINT ,
562 .Fn SYSCTL_ADD_ULONG ,
567 .Xr sysctl_remove_oid 9
569 .Xr sysctl_ctx_free 9
570 for more information on how to destroy a dynamically created OID.
572 For most of the above functions and macros, declaring a type as part
573 of the access flags is not necessary \[em] however, when declaring a
574 sysctl implemented by a function, including a type in the access mask
576 .Bl -tag -width ".Dv CTLTYPE_NOFETCH"
578 This is a node intended to be a parent for other nodes.
580 This is a signed integer.
581 .It Dv CTLTYPE_STRING
582 This is a nul-terminated string stored in a character array.
584 This is an 8-bit signed integer.
586 This is a 16-bit signed integer.
588 This is a 32-bit signed integer.
590 This is a 64-bit signed integer.
591 .It Dv CTLTYPE_OPAQUE
592 This is an opaque data structure.
593 .It Dv CTLTYPE_STRUCT
597 This is an 8-bit unsigned integer.
599 This is a 16-bit unsigned integer.
601 This is a 32-bit unsigned integer.
603 This is a 64-bit unsigned integer.
605 This is an unsigned integer.
607 This is a signed long.
609 This is an unsigned long.
612 All sysctl types except for new node declarations require one of the following
613 flags to be set indicating the read and write disposition of the sysctl:
614 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
616 This is a read-only sysctl.
618 This is a read-only sysctl and tunable which is tried fetched once
619 from the system enviroment early during module load or system boot.
621 This is a writable sysctl.
623 This sysctl is readable and writable.
625 This is a readable and writeable sysctl and tunable which is tried
626 fetched once from the system enviroment early during module load or
628 .It Dv CTLFLAG_NOFETCH
629 In case the node is marked as a tunable using the CTLFLAG_[XX]TUN,
630 this flag will prevent fetching the initial value from the system
631 environment. Typically this flag should only be used for very early
632 low level system setup code, and not by common drivers and modules.
635 Additionally, any of the following optional flags may also be specified:
636 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
637 .It Dv CTLFLAG_ANYBODY
638 Any user or process can write to this sysctl.
639 .It Dv CTLFLAG_SECURE
640 This sysctl can be written to only if the effective securelevel of the
642 .It Dv CTLFLAG_PRISON
643 This sysctl can be written to by processes in
646 When iterating the sysctl name space, do not list this sysctl.
648 Advisory flag that a system tunable also exists for this variable.
649 The initial sysctl value is tried fetched once from the system
650 enviroment early during module load or system boot.
652 Dynamically created OIDs automatically get this flag set.
654 OID references a VIMAGE-enabled variable.
661 sysctl tree for use by new nodes:
662 .Bd -literal -offset indent
663 SYSCTL_DECL(_security);
666 Examples of integer, opaque, string, and procedure sysctls follow:
667 .Bd -literal -offset indent
669 * Example of a constant integer value. Notice that the control
670 * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR,
671 * and the value is declared.
673 SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR,
674 sizeof(struct bio), "sizeof(struct bio)");
677 * Example of a variable integer value. Notice that the control
678 * flags are CTLFLAG_RW, the variable pointer is set, and the
681 static int doingcache = 1; /* 1 => enable the cache */
682 SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0,
683 "Enable name cache");
686 * Example of a variable string value. Notice that the control
687 * flags are CTLFLAG_RW, that the variable pointer and string
688 * size are set. Unlike newer sysctls, this older sysctl uses a
691 char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */
692 SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW,
693 kernelname, sizeof(kernelname), "Name of kernel file booted");
696 * Example of an opaque data type exported by sysctl. Notice that
697 * the variable pointer and size are provided, as well as a format
698 * string for sysctl(8).
700 static l_fp pps_freq; /* scaled frequence offset (ns/s) */
701 SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD,
702 &pps_freq, sizeof(pps_freq), "I", "");
705 * Example of a procedure based sysctl exporting string
706 * information. Notice that the data type is declared, the NULL
707 * variable pointer and 0 size, the function pointer, and the
708 * format string for sysctl(8).
710 SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING |
711 CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A",
715 The following is an example of
716 how to create a new top-level category
717 and how to hook up another subtree to an existing static node.
718 This example does not use contexts,
719 which results in tedious management of all intermediate oids,
720 as they need to be freed later on:
721 .Bd -literal -offset indent
722 #include <sys/sysctl.h>
725 * Need to preserve pointers to newly created subtrees,
726 * to be able to free them later:
728 static struct sysctl_oid *root1;
729 static struct sysctl_oid *root2;
730 static struct sysctl_oid *oidp;
732 static char *string = "dynamic sysctl";
735 root1 = SYSCTL_ADD_ROOT_NODE(NULL,
736 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree");
737 oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1),
738 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf");
740 root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug),
741 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug");
742 oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2),
743 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf");
746 This example creates the following subtrees:
747 .Bd -literal -offset indent
748 debug.newtree.newstring
752 .Em "Care should be taken to free all OIDs once they are no longer needed!"
754 When adding, modifying, or removing sysctl names, it is important to be
755 aware that these interfaces may be used by users, libraries, applications,
756 or documentation (such as published books), and are implicitly published application interfaces.
757 As with other application interfaces, caution must be taken not to break
758 existing applications, and to think about future use of new name spaces so as
759 to avoid the need to rename or remove interfaces that might be depended on in
762 The semantics chosen for a new sysctl should be as clear as possible,
763 and the name of the sysctl must closely reflect its semantics.
764 Therefore the sysctl name deserves a fair amount of consideration.
765 It should be short but yet representative of the sysctl meaning.
766 If the name consists of several words, they should be separated by
767 underscore characters, as in
768 .Va compute_summary_at_mount .
769 Underscore characters may be omitted only if the name consists of not more
770 than two words, each being not longer than four characters, as in
772 For boolean sysctls, negative logic should be totally avoided.
773 That is, do not use names like
777 They are confusing and lead to configuration errors.
778 Use positive logic instead:
782 A temporary sysctl node OID that should not be relied upon must be designated
783 as such by a leading underscore character in its name. For example:
788 .Xr sysctl_add_oid 9 ,
789 .Xr sysctl_ctx_free 9 ,
790 .Xr sysctl_ctx_init 9 ,
791 .Xr sysctl_remove_oid 9
795 utility first appeared in
801 implementation originally found in
803 has been extensively rewritten by
804 .An Poul-Henning Kamp
805 in order to add support for name lookups, name space iteration, and dynamic
806 addition of MIB nodes.
808 This man page was written by
809 .An Robert N. M. Watson .
810 .Sh SECURITY CONSIDERATIONS
811 When creating new sysctls, careful attention should be paid to the security
812 implications of the monitoring or management interface being created.
813 Most sysctls present in the kernel are read-only or writable only by the
815 Sysctls exporting extensive information on system data structures and
816 operation, especially those implemented using procedures, will wish to
817 implement access control to limit the undesired exposure of information about
818 other processes, network connections, etc.
820 The following top level sysctl name spaces are commonly used:
821 .Bl -tag -width ".Va regression"
823 Compatibility layer information.
825 Debugging information.
826 Various name spaces exist under
829 Hardware and device driver information.
831 Kernel behavior tuning; generally deprecated in favor of more specific
834 Machine-dependent configuration parameters.
837 Various protocols have name spaces under
840 Regression test configuration and information.
842 Security and security-policy configuration and information.
844 Reserved name space for the implementation of sysctl.
846 Configuration settings relating to user application behavior.
847 Generally, configuring applications using kernel sysctls is discouraged.
849 Virtual file system configuration and information.
851 Virtual memory subsystem configuration and information.