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
34 .Nm SYSCTL_ADD_COUNTER_U64 ,
35 .Nm SYSCTL_ADD_COUNTER_U64_ARRAY ,
39 .Nm SYSCTL_ADD_NODE_WITH_LABEL ,
40 .Nm SYSCTL_ADD_OPAQUE ,
43 .Nm SYSCTL_ADD_ROOT_NODE ,
48 .Nm SYSCTL_ADD_SBINTIME_MSEC ,
49 .Nm SYSCTL_ADD_SBINTIME_USEC ,
50 .Nm SYSCTL_ADD_STRING ,
51 .Nm SYSCTL_ADD_CONST_STRING ,
52 .Nm SYSCTL_ADD_STRUCT ,
53 .Nm SYSCTL_ADD_TIMEVAL_SEC ,
58 .Nm SYSCTL_ADD_UAUTO ,
60 .Nm SYSCTL_ADD_ULONG ,
61 .Nm SYSCTL_ADD_UMA_CUR ,
62 .Nm SYSCTL_ADD_UMA_MAX ,
63 .Nm SYSCTL_ADD_UQUAD ,
65 .Nm SYSCTL_STATIC_CHILDREN ,
66 .Nm SYSCTL_NODE_CHILDREN ,
69 .Nm SYSCTL_COUNTER_U64 ,
70 .Nm SYSCTL_COUNTER_U64_ARRAY ,
72 .Nm SYSCTL_INT_WITH_LABEL ,
74 .Nm sysctl_msec_to_ticks ,
76 .Nm SYSCTL_NODE_WITH_LABEL ,
80 .Nm SYSCTL_ROOT_NODE ,
85 .Nm SYSCTL_SBINTIME_MSEC ,
86 .Nm SYSCTL_SBINTIME_USEC ,
88 .Nm SYSCTL_CONST_STRING ,
90 .Nm SYSCTL_TIMEVAL_SEC ,
100 .Nd Dynamic and static sysctl MIB creation functions
105 .Ft struct sysctl_oid *
107 .Fa "struct sysctl_ctx_list *ctx"
108 .Fa "struct sysctl_oid_list *parent"
110 .Fa "const char *name"
114 .Fa "const char *descr"
116 .Ft struct sysctl_oid *
117 .Fo SYSCTL_ADD_COUNTER_U64
118 .Fa "struct sysctl_ctx_list *ctx"
119 .Fa "struct sysctl_oid_list *parent"
121 .Fa "const char *name"
123 .Fa "counter_u64_t *ptr"
124 .Fa "const char *descr"
126 .Ft struct sysctl_oid *
127 .Fo SYSCTL_ADD_COUNTER_U64_ARRAY
128 .Fa "struct sysctl_ctx_list *ctx"
129 .Fa "struct sysctl_oid_list *parent"
131 .Fa "const char *name"
133 .Fa "counter_u64_t *ptr"
135 .Fa "const char *descr"
137 .Ft struct sysctl_oid *
139 .Fa "struct sysctl_ctx_list *ctx"
140 .Fa "struct sysctl_oid_list *parent"
142 .Fa "const char *name"
146 .Fa "const char *descr"
148 .Ft struct sysctl_oid *
150 .Fa "struct sysctl_ctx_list *ctx"
151 .Fa "struct sysctl_oid_list *parent"
153 .Fa "const char *name"
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"
165 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
166 .Fa "const char *descr"
168 .Ft struct sysctl_oid *
169 .Fo SYSCTL_ADD_NODE_WITH_LABEL
170 .Fa "struct sysctl_ctx_list *ctx"
171 .Fa "struct sysctl_oid_list *parent"
173 .Fa "const char *name"
175 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
176 .Fa "const char *descr"
177 .Fa "const char *label"
179 .Ft struct sysctl_oid *
180 .Fo SYSCTL_ADD_OPAQUE
181 .Fa "struct sysctl_ctx_list *ctx"
182 .Fa "struct sysctl_oid_list *parent"
184 .Fa "const char *name"
188 .Fa "const char *format"
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 "int (*handler) (SYSCTL_HANDLER_ARGS)"
201 .Fa "const char *format"
202 .Fa "const char *descr"
204 .Ft struct sysctl_oid *
206 .Fa "struct sysctl_ctx_list *ctx"
207 .Fa "struct sysctl_oid_list *parent"
209 .Fa "const char *name"
212 .Fa "const char *descr"
214 .Ft struct sysctl_oid *
215 .Fo SYSCTL_ADD_ROOT_NODE
216 .Fa "struct sysctl_ctx_list *ctx"
218 .Fa "const char *name"
220 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
221 .Fa "const char *descr"
223 .Ft struct sysctl_oid *
225 .Fa "struct sysctl_ctx_list *ctx"
226 .Fa "struct sysctl_oid_list *parent"
228 .Fa "const char *name"
232 .Fa "const char *descr"
234 .Ft struct sysctl_oid *
236 .Fa "struct sysctl_ctx_list *ctx"
237 .Fa "struct sysctl_oid_list *parent"
239 .Fa "const char *name"
243 .Fa "const char *descr"
245 .Ft struct sysctl_oid *
247 .Fa "struct sysctl_ctx_list *ctx"
248 .Fa "struct sysctl_oid_list *parent"
250 .Fa "const char *name"
254 .Fa "const char *descr"
256 .Ft struct sysctl_oid *
258 .Fa "struct sysctl_ctx_list *ctx"
259 .Fa "struct sysctl_oid_list *parent"
261 .Fa "const char *name"
265 .Fa "const char *descr"
267 .Ft struct sysctl_oid *
268 .Fo SYSCTL_ADD_SBINTIME_MSEC
269 .Fa "struct sysctl_ctx_list *ctx"
270 .Fa "struct sysctl_oid_list *parent"
272 .Fa "const char *name"
274 .Fa "sbintime_t *ptr"
275 .Fa "const char *descr"
277 .Ft struct sysctl_oid *
278 .Fo SYSCTL_ADD_SBINTIME_USEC
279 .Fa "struct sysctl_ctx_list *ctx"
280 .Fa "struct sysctl_oid_list *parent"
282 .Fa "const char *name"
284 .Fa "sbintime_t *ptr"
285 .Fa "const char *descr"
287 .Ft struct sysctl_oid *
288 .Fo SYSCTL_ADD_STRING
289 .Fa "struct sysctl_ctx_list *ctx"
290 .Fa "struct sysctl_oid_list *parent"
292 .Fa "const char *name"
296 .Fa "const char *descr"
298 .Ft struct sysctl_oid *
299 .Fo SYSCTL_ADD_CONST_STRING
300 .Fa "struct sysctl_ctx_list *ctx"
301 .Fa "struct sysctl_oid_list *parent"
303 .Fa "const char *name"
305 .Fa "const char *ptr"
306 .Fa "const char *descr"
308 .Ft struct sysctl_oid *
309 .Fo SYSCTL_ADD_STRUCT
310 .Fa "struct sysctl_ctx_list *ctx"
311 .Fa "struct sysctl_oid_list *parent"
313 .Fa "const char *name"
317 .Fa "const char *descr"
319 .Ft struct sysctl_oid *
320 .Fo SYSCTL_ADD_TIMEVAL_SEC
321 .Fa "struct sysctl_ctx_list *ctx"
322 .Fa "struct sysctl_oid_list *parent"
324 .Fa "const char *name"
326 .Fa "struct timeval *ptr"
327 .Fa "const char *descr"
329 .Ft struct sysctl_oid *
331 .Fa "struct sysctl_ctx_list *ctx"
332 .Fa "struct sysctl_oid_list *parent"
334 .Fa "const char *name"
338 .Fa "const char *descr"
340 .Ft struct sysctl_oid *
342 .Fa "struct sysctl_ctx_list *ctx"
343 .Fa "struct sysctl_oid_list *parent"
345 .Fa "const char *name"
349 .Fa "const char *descr"
351 .Ft struct sysctl_oid *
353 .Fa "struct sysctl_ctx_list *ctx"
354 .Fa "struct sysctl_oid_list *parent"
356 .Fa "const char *name"
360 .Fa "const char *descr"
362 .Ft struct sysctl_oid *
364 .Fa "struct sysctl_ctx_list *ctx"
365 .Fa "struct sysctl_oid_list *parent"
367 .Fa "const char *name"
371 .Fa "const char *descr"
373 .Ft struct sysctl_oid *
375 .Fa "struct sysctl_ctx_list *ctx"
376 .Fa "struct sysctl_oid_list *parent"
378 .Fa "const char *name"
380 .Fa "unsigned int *ptr"
381 .Fa "unsigned int val"
382 .Fa "const char *descr"
384 .Ft struct sysctl_oid *
386 .Fa "struct sysctl_ctx_list *ctx"
387 .Fa "struct sysctl_oid_list *parent"
389 .Fa "const char *name"
391 .Fa "unsigned long *ptr"
392 .Fa "const char *descr"
394 .Ft struct sysctl_oid *
396 .Fa "struct sysctl_ctx_list *ctx"
397 .Fa "struct sysctl_oid_list *parent"
399 .Fa "const char *name"
402 .Fa "const char *descr"
404 .Ft struct sysctl_oid *
405 .Fo SYSCTL_ADD_UMA_CUR
406 .Fa "struct sysctl_ctx_list *ctx"
407 .Fa "struct sysctl_oid_list *parent"
409 .Fa "const char *name"
412 .Fa "const char *descr"
414 .Ft struct sysctl_oid *
415 .Fo SYSCTL_ADD_UMA_MAX
416 .Fa "struct sysctl_ctx_list *ctx"
417 .Fa "struct sysctl_oid_list *parent"
419 .Fa "const char *name"
422 .Fa "const char *descr"
424 .Fa "const char *descr"
425 .Ft struct sysctl_oid *
427 .Fa "struct sysctl_ctx_list *ctx"
428 .Fa "struct sysctl_oid_list *parent"
430 .Fa "const char *name"
433 .Fa "const char *descr"
435 .Ft struct sysctl_oid_list *
437 .Fa "struct sysctl_oid *oidp"
439 .Ft struct sysctl_oid_list *
440 .Fo SYSCTL_STATIC_CHILDREN
441 .Fa "struct sysctl_oid_list OID_NAME"
443 .Ft struct sysctl_oid_list *
444 .Fo SYSCTL_NODE_CHILDREN
448 .Ft struct sysctl_oid *
450 .Fa "struct sysctl_oid *oid"
452 .Fn SYSCTL_BOOL parent number name ctlflags ptr val descr
453 .Fn SYSCTL_COUNTER_U64 parent number name ctlflags ptr descr
454 .Fn SYSCTL_COUNTER_U64_ARRAY parent number name ctlflags ptr len descr
455 .Fn SYSCTL_INT parent number name ctlflags ptr val descr
456 .Fn SYSCTL_INT_WITH_LABEL parent number name ctlflags ptr val descr label
457 .Fn SYSCTL_LONG parent number name ctlflags ptr val descr
459 .Fn sysctl_msec_to_ticks SYSCTL_HANDLER_ARGS
460 .Fn SYSCTL_NODE parent number name ctlflags handler descr
461 .Fn SYSCTL_NODE_WITH_LABEL parent number name ctlflags handler descr label
462 .Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr
463 .Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr
464 .Fn SYSCTL_QUAD parent number name ctlflags ptr val descr
465 .Fn SYSCTL_ROOT_NODE number name ctlflags handler descr
466 .Fn SYSCTL_S8 parent number name ctlflags ptr val descr
467 .Fn SYSCTL_S16 parent number name ctlflags ptr val descr
468 .Fn SYSCTL_S32 parent number name ctlflags ptr val descr
469 .Fn SYSCTL_S64 parent number name ctlflags ptr val descr
470 .Fn SYSCTL_SBINTIME_MSEC parent number name ctlflags ptr descr
471 .Fn SYSCTL_SBINTIME_USEC parent number name ctlflags ptr descr
472 .Fn SYSCTL_STRING parent number name ctlflags arg len descr
473 .Fn SYSCTL_CONST_STRING parent number name ctlflags arg descr
474 .Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr
475 .Fn SYSCTL_TIMEVAL_SEC parent number name ctlflags ptr descr
476 .Fn SYSCTL_U8 parent number name ctlflags ptr val descr
477 .Fn SYSCTL_U16 parent number name ctlflags ptr val descr
478 .Fn SYSCTL_U32 parent number name ctlflags ptr val descr
479 .Fn SYSCTL_U64 parent number name ctlflags ptr val descr
480 .Fn SYSCTL_UINT parent number name ctlflags ptr val descr
481 .Fn SYSCTL_ULONG parent number name ctlflags ptr val descr
482 .Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr
483 .Fn SYSCTL_UMA_MAX parent number name ctlflags ptr descr
484 .Fn SYSCTL_UMA_CUR parent number name ctlflags ptr descr
488 kernel interface allows dynamic or static creation of
491 All static sysctls are automatically destroyed when the module which
492 they are part of is unloaded.
493 Most top level categories are created statically and are available to
494 all kernel code and its modules.
495 .Sh DESCRIPTION OF ARGUMENTS
496 .Bl -tag -width ctlflags
498 Pointer to sysctl context or NULL, if no context.
500 .Xr sysctl_ctx_init 9
501 for how to create a new sysctl context.
502 Programmers are strongly advised to use contexts to organize the
503 dynamic OIDs which they create because when a context is destroyed all
504 belonging sysctls are destroyed as well.
505 This makes the sysctl cleanup code much simpler.
506 Else deletion of all created OIDs is required at module unload.
509 .Li struct sysctl_oid_list ,
510 which is the head of the parent's list of children.
511 This pointer is retrieved using the
512 .Fn SYSCTL_STATIC_CHILDREN
513 macro for static sysctls and the
515 macro for dynamic sysctls.
518 macro can be used to get the parent of an OID.
519 The macro returns NULL if there is no parent.
521 The OID number that will be assigned to this OID.
522 In almost all cases this should be set to
524 which will result in the assignment of the next available OID number.
527 The newly created OID will contain a copy of the name.
529 A bit mask of sysctl control flags.
530 See the section below describing all the control flags.
532 First callback argument for procedure sysctls.
534 Second callback argument for procedure sysctls.
536 The length of the data pointed to by the
539 For string type OIDs a length of zero means that
541 will be used to get the length of the string at each access to the OID.
542 For array type OIDs the length must be greater than zero.
544 Pointer to sysctl variable or string data.
545 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
551 argument is SYSCTL_NULL_XXX_PTR, gives the constant value returned by this OID.
552 Else this argument is not used.
554 Name of structure type.
556 A pointer to the function
557 that is responsible for handling read and write requests
559 There are several standard handlers
560 that support operations on nodes,
561 integers, strings and opaque objects.
562 It is possible to define custom handlers using the
568 A pointer to a string
569 which specifies the format of the OID in a symbolic way.
570 This format is used as a hint by
572 to apply proper data formatting for display purposes.
575 .Bl -tag -width "S,TYPE" -compact -offset indent
583 temperature in Kelvin, multiplied by an optional single digit
584 power of ten scaling factor: 1 (default) gives deciKelvin, 0 gives Kelvin, 3
601 A pointer to a textual description of the OID.
603 A pointer to an aggregation label for this component of the OID.
604 To make it easier to export sysctl data to monitoring systems that
605 support aggregations through labels (e.g., Prometheus),
606 this argument can be used to attach a label name to an OID.
607 The label acts as a hint that this component's name should not be part
608 of the metric's name,
609 but attached to the metric as a label instead.
611 Labels should only be applied to siblings that are structurally similar
612 and encode the same type of value,
613 as aggregation is of no use otherwise.
616 Most of the macros and functions used to create sysctl nodes export a
617 read-only constant or in-kernel variable whose type matches the type
621 reports the raw value of an associated variable of type
623 However, nodes may also export a value that is a translatation of an internal
627 .Fn sysctl_msec_to_ticks
628 handler can be used with
632 to export a millisecond time interval.
633 When using this handler,
636 parameter points to an in-kernel variable of type
638 which stores a tick count suitable for use with functions like
641 .Fn sysctl_msec_to_ticks
642 function converts this value to milliseconds when reporting the node's value.
644 .Fn sysctl_msec_to_ticks
645 accepts new values in milliseconds and stores an equivalent value in ticks to
647 Note that new code should use kernel variables of type
649 instead of tick counts.
652 .Fn SYSCTL_ADD_SBINTIME_MSEC
654 .Fn SYSCTL_ADD_SBINTIME_USEC
656 .Fn SYSCTL_SBINTIME_MSEC
658 .Fn SYSCTL_SBINTIME_USEC
659 macros all create nodes which export an in-kernel variable of type
661 These nodes do not export the raw value of the associated variable.
662 Instead, they export a 64-bit integer containing a count of either
663 milliseconds (the MSEC variants) or microseconds (the USEC variants).
666 .Fn SYSCTL_ADD_TIMEVAL_SEC
668 .Fn SYSCTL_TIMEVAL_SEC
669 macro create nodes which export an in-kernel variable of type
671 These nodes do not export full value of the associated structure.
672 Instead, they export a count in seconds as a simple integer which is
675 field of the associated variable.
676 This function and macro are intended to be used with variables which
677 store a non-negative interval rather than an absolute time.
678 As a result, they reject attempts to store negative values.
679 .Sh CREATING ROOT NODES
680 Sysctl MIBs or OIDs are created in a hierarchical tree.
681 The nodes at the bottom of the tree are called root nodes, and have no
683 To create bottom tree nodes the
686 .Fn SYSCTL_ADD_ROOT_NODE
687 function needs to be used.
688 By default all static sysctl node OIDs are global and need a
690 statement prior to their
692 definition statement, typically in a so-called header file.
693 .Sh CREATING SYSCTL STRINGS
694 Zero terminated character strings sysctls are created either using the
697 .Fn SYSCTL_ADD_STRING
701 argument in zero, the string length is computed at every access to the OID using
704 .Fn SYSCTL_CONST_STRING
706 .Fn SYSCTL_ADD_CONST_STRING
707 function to add a sysctl for a constant string.
708 .Sh CREATING OPAQUE SYSCTLS
714 .Fn SYSCTL_ADD_OPAQUE
716 .Fn SYSCTL_ADD_STRUCT
717 functions create an OID that handle any chunk of data
718 of the size specified by the
720 argument and data pointed to by the
723 When using the structure version the type is encoded as part of the
725 .Sh CREATING CUSTOM SYSCTLS
731 create OIDs with the specified
734 The handler is responsible for handling all read and write requests to
736 This OID type is especially useful if the kernel data is not easily
737 accessible, or needs to be processed before exporting.
738 .Sh CREATING A STATIC SYSCTL
739 Static sysctls are declared using one of the
741 .Fn SYSCTL_COUNTER_U64 ,
742 .Fn SYSCTL_COUNTER_U64_ARRAY ,
744 .Fn SYSCTL_INT_WITH_LABEL ,
747 .Fn SYSCTL_NODE_WITH_LABEL ,
751 .Fn SYSCTL_ROOT_NODE ,
756 .Fn SYSCTL_SBINTIME_MSEC ,
757 .Fn SYSCTL_SBINTIME_USEC ,
759 .Fn SYSCTL_CONST_STRING ,
761 .Fn SYSCTL_TIMEVAL_SEC ,
773 .Sh CREATING A DYNAMIC SYSCTL
774 Dynamic nodes are created using one of the
775 .Fn SYSCTL_ADD_BOOL ,
776 .Fn SYSCTL_ADD_COUNTER_U64 ,
777 .Fn SYSCTL_ADD_COUNTER_U64_ARRAY ,
779 .Fn SYSCTL_ADD_LONG ,
780 .Fn SYSCTL_ADD_NODE ,
781 .Fn SYSCTL_ADD_NODE_WITH_LABEL ,
782 .Fn SYSCTL_ADD_OPAQUE ,
783 .Fn SYSCTL_ADD_PROC ,
784 .Fn SYSCTL_ADD_QUAD ,
785 .Fn SYSCTL_ADD_ROOT_NODE ,
790 .Fn SYSCTL_ADD_SBINTIME_MSEC ,
791 .Fn SYSCTL_ADD_SBINTIME_USEC ,
792 .Fn SYSCTL_ADD_STRING ,
793 .Fn SYSCTL_ADD_CONST_STRING ,
794 .Fn SYSCTL_ADD_STRUCT ,
795 .Fn SYSCTL_ADD_TIMEVAL_SEC ,
800 .Fn SYSCTL_ADD_UAUTO ,
801 .Fn SYSCTL_ADD_UINT ,
802 .Fn SYSCTL_ADD_ULONG ,
803 .Fn SYSCTL_ADD_UQUAD ,
804 .Fn SYSCTL_ADD_UMA_CUR
806 .Fn SYSCTL_ADD_UMA_MAX
809 .Xr sysctl_remove_oid 9
811 .Xr sysctl_ctx_free 9
812 for more information on how to destroy a dynamically created OID.
814 For most of the above functions and macros, declaring a type as part
815 of the access flags is not necessary \[em] however, when declaring a
816 sysctl implemented by a function, including a type in the access mask
818 .Bl -tag -width ".Dv CTLTYPE_NOFETCH"
820 This is a node intended to be a parent for other nodes.
822 This is a signed integer.
823 .It Dv CTLTYPE_STRING
824 This is a nul-terminated string stored in a character array.
826 This is an 8-bit signed integer.
828 This is a 16-bit signed integer.
830 This is a 32-bit signed integer.
832 This is a 64-bit signed integer.
833 .It Dv CTLTYPE_OPAQUE
834 This is an opaque data structure.
835 .It Dv CTLTYPE_STRUCT
839 This is an 8-bit unsigned integer.
841 This is a 16-bit unsigned integer.
843 This is a 32-bit unsigned integer.
845 This is a 64-bit unsigned integer.
847 This is an unsigned integer.
849 This is a signed long.
851 This is an unsigned long.
854 All sysctl types except for new node declarations require one of the following
855 flags to be set indicating the read and write disposition of the sysctl:
856 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
858 This is a read-only sysctl.
860 This is a read-only sysctl and tunable which is tried fetched once
861 from the system environment early during module load or system boot.
863 This is a writable sysctl.
865 This sysctl is readable and writable.
867 This is a readable and writeable sysctl and tunable which is tried
868 fetched once from the system environment early during module load or
870 .It Dv CTLFLAG_NOFETCH
871 In case the node is marked as a tunable using the CTLFLAG_[XX]TUN,
872 this flag will prevent fetching the initial value from the system
874 Typically this flag should only be used for very early
875 low level system setup code, and not by common drivers and modules.
876 .It Dv CTLFLAG_MPSAFE
880 Do not grab Giant around calls to this handler.
881 This should only be used for
886 Additionally, any of the following optional flags may also be specified:
887 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
888 .It Dv CTLFLAG_ANYBODY
889 Any user or process can write to this sysctl.
891 A process in capability mode can read from this sysctl.
893 A process in capability mode can write to this sysctl.
894 .It Dv CTLFLAG_SECURE
895 This sysctl can be written to only if the effective securelevel of the
897 .It Dv CTLFLAG_PRISON
898 This sysctl can be written to by processes in
901 When iterating the sysctl name space, do not list this sysctl.
903 Advisory flag that a system tunable also exists for this variable.
904 The initial sysctl value is tried fetched once from the system
905 environment early during module load or system boot.
907 Dynamically created OIDs automatically get this flag set.
909 OID references a VIMAGE-enabled variable.
916 sysctl tree for use by new nodes:
917 .Bd -literal -offset indent
918 SYSCTL_DECL(_security);
921 Examples of integer, opaque, string, and procedure sysctls follow:
922 .Bd -literal -offset indent
924 * Example of a constant integer value. Notice that the control
925 * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR,
926 * and the value is declared.
928 SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR,
929 sizeof(struct bio), "sizeof(struct bio)");
932 * Example of a variable integer value. Notice that the control
933 * flags are CTLFLAG_RW, the variable pointer is set, and the
936 static int doingcache = 1; /* 1 => enable the cache */
937 SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0,
938 "Enable name cache");
941 * Example of a variable string value. Notice that the control
942 * flags are CTLFLAG_RW, that the variable pointer and string
943 * size are set. Unlike newer sysctls, this older sysctl uses a
946 char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */
947 SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW,
948 kernelname, sizeof(kernelname), "Name of kernel file booted");
951 * Example of an opaque data type exported by sysctl. Notice that
952 * the variable pointer and size are provided, as well as a format
953 * string for sysctl(8).
955 static l_fp pps_freq; /* scaled frequency offset (ns/s) */
956 SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD,
957 &pps_freq, sizeof(pps_freq), "I", "");
960 * Example of a procedure based sysctl exporting string
961 * information. Notice that the data type is declared, the NULL
962 * variable pointer and 0 size, the function pointer, and the
963 * format string for sysctl(8).
965 SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING |
966 CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A",
970 The following is an example of
971 how to create a new top-level category
972 and how to hook up another subtree to an existing static node.
973 This example does not use contexts,
974 which results in tedious management of all intermediate oids,
975 as they need to be freed later on:
976 .Bd -literal -offset indent
977 #include <sys/sysctl.h>
980 * Need to preserve pointers to newly created subtrees,
981 * to be able to free them later:
983 static struct sysctl_oid *root1;
984 static struct sysctl_oid *root2;
985 static struct sysctl_oid *oidp;
987 static char *string = "dynamic sysctl";
990 root1 = SYSCTL_ADD_ROOT_NODE(NULL,
991 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree");
992 oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1),
993 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf");
995 root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug),
996 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug");
997 oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2),
998 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf");
1001 This example creates the following subtrees:
1002 .Bd -literal -offset indent
1003 debug.newtree.newstring
1007 .Em "Care should be taken to free all OIDs once they are no longer needed!"
1009 When adding, modifying, or removing sysctl names, it is important to be
1010 aware that these interfaces may be used by users, libraries, applications,
1011 or documentation (such as published books), and are implicitly published application interfaces.
1012 As with other application interfaces, caution must be taken not to break
1013 existing applications, and to think about future use of new name spaces so as
1014 to avoid the need to rename or remove interfaces that might be depended on in
1017 The semantics chosen for a new sysctl should be as clear as possible,
1018 and the name of the sysctl must closely reflect its semantics.
1019 Therefore the sysctl name deserves a fair amount of consideration.
1020 It should be short but yet representative of the sysctl meaning.
1021 If the name consists of several words, they should be separated by
1022 underscore characters, as in
1023 .Va compute_summary_at_mount .
1024 Underscore characters may be omitted only if the name consists of not more
1025 than two words, each being not longer than four characters, as in
1027 For boolean sysctls, negative logic should be totally avoided.
1028 That is, do not use names like
1031 .Va foobar_disable .
1032 They are confusing and lead to configuration errors.
1033 Use positive logic instead:
1037 A temporary sysctl node OID that should not be relied upon must be designated
1038 as such by a leading underscore character in its name.
1044 .Xr sysctl_add_oid 9 ,
1045 .Xr sysctl_ctx_free 9 ,
1046 .Xr sysctl_ctx_init 9 ,
1047 .Xr sysctl_remove_oid 9
1051 utility first appeared in
1057 implementation originally found in
1059 has been extensively rewritten by
1060 .An Poul-Henning Kamp
1061 in order to add support for name lookups, name space iteration, and dynamic
1062 addition of MIB nodes.
1064 This man page was written by
1065 .An Robert N. M. Watson .
1066 .Sh SECURITY CONSIDERATIONS
1067 When creating new sysctls, careful attention should be paid to the security
1068 implications of the monitoring or management interface being created.
1069 Most sysctls present in the kernel are read-only or writable only by the
1071 Sysctls exporting extensive information on system data structures and
1072 operation, especially those implemented using procedures, will wish to
1073 implement access control to limit the undesired exposure of information about
1074 other processes, network connections, etc.
1076 The following top level sysctl name spaces are commonly used:
1077 .Bl -tag -width ".Va regression"
1079 Compatibility layer information.
1081 Debugging information.
1082 Various name spaces exist under
1085 Hardware and device driver information.
1087 Kernel behavior tuning; generally deprecated in favor of more specific
1090 Machine-dependent configuration parameters.
1093 Various protocols have name spaces under
1096 Regression test configuration and information.
1098 Security and security-policy configuration and information.
1100 Reserved name space for the implementation of sysctl.
1102 Configuration settings relating to user application behavior.
1103 Generally, configuring applications using kernel sysctls is discouraged.
1105 Virtual file system configuration and information.
1107 Virtual memory subsystem configuration and information.