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_UQUAD ,
62 .Nm SYSCTL_ADD_UMA_CUR ,
63 .Nm SYSCTL_ADD_UMA_MAX ,
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
489 kernel interface allows dynamic or static creation of
492 All static sysctls are automatically destroyed when the module which
493 they are part of is unloaded.
494 Most top level categories are created statically and are available to
495 all kernel code and its modules.
496 .Sh DESCRIPTION OF ARGUMENTS
497 .Bl -tag -width ctlflags
499 Pointer to sysctl context or NULL, if no context.
501 .Xr sysctl_ctx_init 9
502 for how to create a new sysctl context.
503 Programmers are strongly advised to use contexts to organize the
504 dynamic OIDs which they create because when a context is destroyed all
505 belonging sysctls are destroyed as well.
506 This makes the sysctl cleanup code much simpler.
507 Else deletion of all created OIDs is required at module unload.
510 .Li struct sysctl_oid_list ,
511 which is the head of the parent's list of children.
512 This pointer is retrieved using the
513 .Fn SYSCTL_STATIC_CHILDREN
514 macro for static sysctls and the
516 macro for dynamic sysctls.
519 macro can be used to get the parent of an OID.
520 The macro returns NULL if there is no parent.
522 The OID number that will be assigned to this OID.
523 In almost all cases this should be set to
525 which will result in the assignment of the next available OID number.
528 The newly created OID will contain a copy of the name.
530 A bit mask of sysctl control flags.
531 See the section below describing all the control flags.
533 First callback argument for procedure sysctls.
535 Second callback argument for procedure sysctls.
537 The length of the data pointed to by the
540 For string type OIDs a length of zero means that
542 will be used to get the length of the string at each access to the OID.
543 For array type OIDs the length must be greater than zero.
545 Pointer to sysctl variable or string data.
546 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
552 argument is SYSCTL_NULL_XXX_PTR, gives the constant value returned by this OID.
553 Else this argument is not used.
555 Name of structure type.
557 A pointer to the function
558 that is responsible for handling read and write requests
560 There are several standard handlers
561 that support operations on nodes,
562 integers, strings and opaque objects.
563 It is possible to define custom handlers using the
569 A pointer to a string
570 which specifies the format of the OID in a symbolic way.
571 This format is used as a hint by
573 to apply proper data formatting for display purposes.
576 .Bl -tag -width "S,TYPE" -compact -offset indent
584 temperature in Kelvin, multiplied by an optional single digit
585 power of ten scaling factor: 1 (default) gives deciKelvin, 0 gives Kelvin, 3
602 A pointer to a textual description of the OID.
604 A pointer to an aggregation label for this component of the OID.
605 To make it easier to export sysctl data to monitoring systems that
606 support aggregations through labels (e.g., Prometheus),
607 this argument can be used to attach a label name to an OID.
608 The label acts as a hint that this component's name should not be part
609 of the metric's name,
610 but attached to the metric as a label instead.
612 Labels should only be applied to siblings that are structurally similar
613 and encode the same type of value,
614 as aggregation is of no use otherwise.
617 Most of the macros and functions used to create sysctl nodes export a
618 read-only constant or in-kernel variable whose type matches the type
622 reports the raw value of an associated variable of type
624 However, nodes may also export a value that is a translatation of an internal
628 .Fn sysctl_msec_to_ticks
629 handler can be used with
633 to export a millisecond time interval.
634 When using this handler,
637 parameter points to an in-kernel variable of type
639 which stores a tick count suitable for use with functions like
642 .Fn sysctl_msec_to_ticks
643 function converts this value to milliseconds when reporting the node's value.
645 .Fn sysctl_msec_to_ticks
646 accepts new values in milliseconds and stores an equivalent value in ticks to
648 Note that new code should use kernel variables of type
650 instead of tick counts.
653 .Fn SYSCTL_ADD_SBINTIME_MSEC
655 .Fn SYSCTL_ADD_SBINTIME_USEC
657 .Fn SYSCTL_SBINTIME_MSEC
659 .Fn SYSCTL_SBINTIME_USEC
660 macros all create nodes which export an in-kernel variable of type
662 These nodes do not export the raw value of the associated variable.
663 Instead, they export a 64-bit integer containing a count of either
664 milliseconds (the MSEC variants) or microseconds (the USEC variants).
667 .Fn SYSCTL_ADD_TIMEVAL_SEC
669 .Fn SYSCTL_TIMEVAL_SEC
670 macro create nodes which export an in-kernel variable of type
672 These nodes do not export full value of the associated structure.
673 Instead, they export a count in seconds as a simple integer which is
676 field of the associated variable.
677 This function and macro are intended to be used with variables which
678 store a non-negative interval rather than an absolute time.
679 As a result, they reject attempts to store negative values.
680 .Sh CREATING ROOT NODES
681 Sysctl MIBs or OIDs are created in a hierarchical tree.
682 The nodes at the bottom of the tree are called root nodes, and have no
684 To create bottom tree nodes the
687 .Fn SYSCTL_ADD_ROOT_NODE
688 function needs to be used.
689 By default all static sysctl node OIDs are global and need a
691 statement prior to their
693 definition statement, typically in a so-called header file.
694 .Sh CREATING SYSCTL STRINGS
695 Zero terminated character strings sysctls are created either using the
698 .Fn SYSCTL_ADD_STRING
702 argument in zero, the string length is computed at every access to the OID using
705 .Fn SYSCTL_CONST_STRING
707 .Fn SYSCTL_ADD_CONST_STRING
708 function to add a sysctl for a constant string.
709 .Sh CREATING OPAQUE SYSCTLS
715 .Fn SYSCTL_ADD_OPAQUE
717 .Fn SYSCTL_ADD_STRUCT
718 functions create an OID that handle any chunk of data
719 of the size specified by the
721 argument and data pointed to by the
724 When using the structure version the type is encoded as part of the
726 .Sh CREATING CUSTOM SYSCTLS
732 create OIDs with the specified
735 The handler is responsible for handling all read and write requests to
737 This OID type is especially useful if the kernel data is not easily
738 accessible, or needs to be processed before exporting.
739 .Sh CREATING A STATIC SYSCTL
740 Static sysctls are declared using one of the
742 .Fn SYSCTL_COUNTER_U64 ,
743 .Fn SYSCTL_COUNTER_U64_ARRAY ,
745 .Fn SYSCTL_INT_WITH_LABEL ,
748 .Fn SYSCTL_NODE_WITH_LABEL ,
752 .Fn SYSCTL_ROOT_NODE ,
757 .Fn SYSCTL_SBINTIME_MSEC ,
758 .Fn SYSCTL_SBINTIME_USEC ,
760 .Fn SYSCTL_CONST_STRING ,
762 .Fn SYSCTL_TIMEVAL_SEC ,
774 .Sh CREATING A DYNAMIC SYSCTL
775 Dynamic nodes are created using one of the
776 .Fn SYSCTL_ADD_BOOL ,
777 .Fn SYSCTL_ADD_COUNTER_U64 ,
778 .Fn SYSCTL_ADD_COUNTER_U64_ARRAY ,
780 .Fn SYSCTL_ADD_LONG ,
781 .Fn SYSCTL_ADD_NODE ,
782 .Fn SYSCTL_ADD_NODE_WITH_LABEL ,
783 .Fn SYSCTL_ADD_OPAQUE ,
784 .Fn SYSCTL_ADD_PROC ,
785 .Fn SYSCTL_ADD_QUAD ,
786 .Fn SYSCTL_ADD_ROOT_NODE ,
791 .Fn SYSCTL_ADD_SBINTIME_MSEC ,
792 .Fn SYSCTL_ADD_SBINTIME_USEC ,
793 .Fn SYSCTL_ADD_STRING ,
794 .Fn SYSCTL_ADD_CONST_STRING ,
795 .Fn SYSCTL_ADD_STRUCT ,
796 .Fn SYSCTL_ADD_TIMEVAL_SEC ,
801 .Fn SYSCTL_ADD_UAUTO ,
802 .Fn SYSCTL_ADD_UINT ,
803 .Fn SYSCTL_ADD_ULONG ,
804 .Fn SYSCTL_ADD_UQUAD ,
805 .Fn SYSCTL_ADD_UMA_CUR
807 .Fn SYSCTL_ADD_UMA_MAX
810 .Xr sysctl_remove_oid 9
812 .Xr sysctl_ctx_free 9
813 for more information on how to destroy a dynamically created OID.
815 For most of the above functions and macros, declaring a type as part
816 of the access flags is not necessary \[em] however, when declaring a
817 sysctl implemented by a function, including a type in the access mask
819 .Bl -tag -width ".Dv CTLTYPE_NOFETCH"
821 This is a node intended to be a parent for other nodes.
823 This is a signed integer.
824 .It Dv CTLTYPE_STRING
825 This is a nul-terminated string stored in a character array.
827 This is an 8-bit signed integer.
829 This is a 16-bit signed integer.
831 This is a 32-bit signed integer.
833 This is a 64-bit signed integer.
834 .It Dv CTLTYPE_OPAQUE
835 This is an opaque data structure.
836 .It Dv CTLTYPE_STRUCT
840 This is an 8-bit unsigned integer.
842 This is a 16-bit unsigned integer.
844 This is a 32-bit unsigned integer.
846 This is a 64-bit unsigned integer.
848 This is an unsigned integer.
850 This is a signed long.
852 This is an unsigned long.
855 All sysctl types except for new node declarations require one of the following
856 flags to be set indicating the read and write disposition of the sysctl:
857 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
859 This is a read-only sysctl.
861 This is a read-only sysctl and tunable which is tried fetched once
862 from the system environment early during module load or system boot.
864 This is a writable sysctl.
866 This sysctl is readable and writable.
868 This is a readable and writeable sysctl and tunable which is tried
869 fetched once from the system environment early during module load or
871 .It Dv CTLFLAG_NOFETCH
872 In case the node is marked as a tunable using the CTLFLAG_[XX]TUN,
873 this flag will prevent fetching the initial value from the system
875 Typically this flag should only be used for very early
876 low level system setup code, and not by common drivers and modules.
877 .It Dv CTLFLAG_MPSAFE
881 Do not grab Giant around calls to this handler.
882 This should only be used for
887 Additionally, any of the following optional flags may also be specified:
888 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
889 .It Dv CTLFLAG_ANYBODY
890 Any user or process can write to this sysctl.
892 A process in capability mode can read from this sysctl.
894 A process in capability mode can write to this sysctl.
895 .It Dv CTLFLAG_SECURE
896 This sysctl can be written to only if the effective securelevel of the
898 .It Dv CTLFLAG_PRISON
899 This sysctl can be written to by processes in
902 When iterating the sysctl name space, do not list this sysctl.
904 Advisory flag that a system tunable also exists for this variable.
905 The initial sysctl value is tried fetched once from the system
906 environment early during module load or system boot.
908 Dynamically created OIDs automatically get this flag set.
910 OID references a VIMAGE-enabled variable.
917 sysctl tree for use by new nodes:
918 .Bd -literal -offset indent
919 SYSCTL_DECL(_security);
922 Examples of integer, opaque, string, and procedure sysctls follow:
923 .Bd -literal -offset indent
925 * Example of a constant integer value. Notice that the control
926 * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR,
927 * and the value is declared.
929 SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR,
930 sizeof(struct bio), "sizeof(struct bio)");
933 * Example of a variable integer value. Notice that the control
934 * flags are CTLFLAG_RW, the variable pointer is set, and the
937 static int doingcache = 1; /* 1 => enable the cache */
938 SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0,
939 "Enable name cache");
942 * Example of a variable string value. Notice that the control
943 * flags are CTLFLAG_RW, that the variable pointer and string
944 * size are set. Unlike newer sysctls, this older sysctl uses a
947 char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */
948 SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW,
949 kernelname, sizeof(kernelname), "Name of kernel file booted");
952 * Example of an opaque data type exported by sysctl. Notice that
953 * the variable pointer and size are provided, as well as a format
954 * string for sysctl(8).
956 static l_fp pps_freq; /* scaled frequency offset (ns/s) */
957 SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD,
958 &pps_freq, sizeof(pps_freq), "I", "");
961 * Example of a procedure based sysctl exporting string
962 * information. Notice that the data type is declared, the NULL
963 * variable pointer and 0 size, the function pointer, and the
964 * format string for sysctl(8).
966 SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING |
967 CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A",
971 The following is an example of
972 how to create a new top-level category
973 and how to hook up another subtree to an existing static node.
974 This example does not use contexts,
975 which results in tedious management of all intermediate oids,
976 as they need to be freed later on:
977 .Bd -literal -offset indent
978 #include <sys/sysctl.h>
981 * Need to preserve pointers to newly created subtrees,
982 * to be able to free them later:
984 static struct sysctl_oid *root1;
985 static struct sysctl_oid *root2;
986 static struct sysctl_oid *oidp;
988 static char *string = "dynamic sysctl";
991 root1 = SYSCTL_ADD_ROOT_NODE(NULL,
992 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree");
993 oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1),
994 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf");
996 root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug),
997 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug");
998 oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2),
999 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf");
1002 This example creates the following subtrees:
1003 .Bd -literal -offset indent
1004 debug.newtree.newstring
1008 .Em "Care should be taken to free all OIDs once they are no longer needed!"
1010 When adding, modifying, or removing sysctl names, it is important to be
1011 aware that these interfaces may be used by users, libraries, applications,
1012 or documentation (such as published books), and are implicitly published application interfaces.
1013 As with other application interfaces, caution must be taken not to break
1014 existing applications, and to think about future use of new name spaces so as
1015 to avoid the need to rename or remove interfaces that might be depended on in
1018 The semantics chosen for a new sysctl should be as clear as possible,
1019 and the name of the sysctl must closely reflect its semantics.
1020 Therefore the sysctl name deserves a fair amount of consideration.
1021 It should be short but yet representative of the sysctl meaning.
1022 If the name consists of several words, they should be separated by
1023 underscore characters, as in
1024 .Va compute_summary_at_mount .
1025 Underscore characters may be omitted only if the name consists of not more
1026 than two words, each being not longer than four characters, as in
1028 For boolean sysctls, negative logic should be totally avoided.
1029 That is, do not use names like
1032 .Va foobar_disable .
1033 They are confusing and lead to configuration errors.
1034 Use positive logic instead:
1038 A temporary sysctl node OID that should not be relied upon must be designated
1039 as such by a leading underscore character in its name.
1045 .Xr sysctl_add_oid 9 ,
1046 .Xr sysctl_ctx_free 9 ,
1047 .Xr sysctl_ctx_init 9 ,
1048 .Xr sysctl_remove_oid 9
1052 utility first appeared in
1058 implementation originally found in
1060 has been extensively rewritten by
1061 .An Poul-Henning Kamp
1062 in order to add support for name lookups, name space iteration, and dynamic
1063 addition of MIB nodes.
1065 This man page was written by
1066 .An Robert N. M. Watson .
1067 .Sh SECURITY CONSIDERATIONS
1068 When creating new sysctls, careful attention should be paid to the security
1069 implications of the monitoring or management interface being created.
1070 Most sysctls present in the kernel are read-only or writable only by the
1072 Sysctls exporting extensive information on system data structures and
1073 operation, especially those implemented using procedures, will wish to
1074 implement access control to limit the undesired exposure of information about
1075 other processes, network connections, etc.
1077 The following top level sysctl name spaces are commonly used:
1078 .Bl -tag -width ".Va regression"
1080 Compatibility layer information.
1082 Debugging information.
1083 Various name spaces exist under
1086 Hardware and device driver information.
1088 Kernel behavior tuning; generally deprecated in favor of more specific
1091 Machine-dependent configuration parameters.
1094 Various protocols have name spaces under
1097 Regression test configuration and information.
1099 Security and security-policy configuration and information.
1101 Reserved name space for the implementation of sysctl.
1103 Configuration settings relating to user application behavior.
1104 Generally, configuring applications using kernel sysctls is discouraged.
1106 Virtual file system configuration and information.
1108 Virtual memory subsystem configuration and information.