xref: /freebsd/share/man/man9/sysctl.9 (revision a2aef24aa3c8458e4036735dd6928b4ef77294e5)
1.\"
2.\" Copyright (c) 2006 Robert N. M. Watson
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
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
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd October 10, 2017
29.Dt SYSCTL 9
30.Os
31.Sh NAME
32.Nm SYSCTL_DECL ,
33.Nm SYSCTL_ADD_INT ,
34.Nm SYSCTL_ADD_LONG ,
35.Nm SYSCTL_ADD_NODE ,
36.Nm SYSCTL_ADD_NODE_WITH_LABEL ,
37.Nm SYSCTL_ADD_OPAQUE ,
38.Nm SYSCTL_ADD_PROC ,
39.Nm SYSCTL_ADD_QUAD ,
40.Nm SYSCTL_ADD_ROOT_NODE ,
41.Nm SYSCTL_ADD_S8 ,
42.Nm SYSCTL_ADD_S16 ,
43.Nm SYSCTL_ADD_S32 ,
44.Nm SYSCTL_ADD_S64 ,
45.Nm SYSCTL_ADD_STRING ,
46.Nm SYSCTL_ADD_STRUCT ,
47.Nm SYSCTL_ADD_U8 ,
48.Nm SYSCTL_ADD_U16 ,
49.Nm SYSCTL_ADD_U32 ,
50.Nm SYSCTL_ADD_U64 ,
51.Nm SYSCTL_ADD_UAUTO ,
52.Nm SYSCTL_ADD_UINT ,
53.Nm SYSCTL_ADD_ULONG ,
54.Nm SYSCTL_ADD_UQUAD ,
55.Nm SYSCTL_CHILDREN ,
56.Nm SYSCTL_STATIC_CHILDREN ,
57.Nm SYSCTL_NODE_CHILDREN ,
58.Nm SYSCTL_PARENT ,
59.Nm SYSCTL_INT ,
60.Nm SYSCTL_INT_WITH_LABEL ,
61.Nm SYSCTL_LONG ,
62.Nm SYSCTL_NODE ,
63.Nm SYSCTL_NODE_WITH_LABEL ,
64.Nm SYSCTL_OPAQUE ,
65.Nm SYSCTL_PROC ,
66.Nm SYSCTL_QUAD ,
67.Nm SYSCTL_ROOT_NODE ,
68.Nm SYSCTL_S8 ,
69.Nm SYSCTL_S16 ,
70.Nm SYSCTL_S32 ,
71.Nm SYSCTL_S64 ,
72.Nm SYSCTL_STRING ,
73.Nm SYSCTL_STRUCT ,
74.Nm SYSCTL_U8 ,
75.Nm SYSCTL_U16 ,
76.Nm SYSCTL_U32 ,
77.Nm SYSCTL_U64 ,
78.Nm SYSCTL_UINT ,
79.Nm SYSCTL_ULONG ,
80.Nm SYSCTL_UQUAD
81.Nd Dynamic and static sysctl MIB creation functions
82.Sh SYNOPSIS
83.In sys/types.h
84.In sys/sysctl.h
85.Fn SYSCTL_DECL name
86.Ft struct sysctl_oid *
87.Fo SYSCTL_ADD_INT
88.Fa "struct sysctl_ctx_list *ctx"
89.Fa "struct sysctl_oid_list *parent"
90.Fa "int number"
91.Fa "const char *name"
92.Fa "int ctlflags"
93.Fa "int *ptr"
94.Fa "int val"
95.Fa "const char *descr"
96.Fc
97.Ft struct sysctl_oid *
98.Fo SYSCTL_ADD_LONG
99.Fa "struct sysctl_ctx_list *ctx"
100.Fa "struct sysctl_oid_list *parent"
101.Fa "int number"
102.Fa "const char *name"
103.Fa "int ctlflags"
104.Fa "long *ptr"
105.Fa "const char *descr"
106.Fc
107.Ft struct sysctl_oid *
108.Fo SYSCTL_ADD_NODE
109.Fa "struct sysctl_ctx_list *ctx"
110.Fa "struct sysctl_oid_list *parent"
111.Fa "int number"
112.Fa "const char *name"
113.Fa "int ctlflags"
114.Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
115.Fa "const char *descr"
116.Fc
117.Ft struct sysctl_oid *
118.Fo SYSCTL_ADD_NODE_WITH_LABEL
119.Fa "struct sysctl_ctx_list *ctx"
120.Fa "struct sysctl_oid_list *parent"
121.Fa "int number"
122.Fa "const char *name"
123.Fa "int ctlflags"
124.Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
125.Fa "const char *descr"
126.Fa "const char *label"
127.Fc
128.Ft struct sysctl_oid *
129.Fo SYSCTL_ADD_OPAQUE
130.Fa "struct sysctl_ctx_list *ctx"
131.Fa "struct sysctl_oid_list *parent"
132.Fa "int number"
133.Fa "const char *name"
134.Fa "int ctlflags"
135.Fa "void *ptr"
136.Fa "intptr_t len"
137.Fa "const char *format"
138.Fa "const char *descr"
139.Fc
140.Ft struct sysctl_oid *
141.Fo SYSCTL_ADD_PROC
142.Fa "struct sysctl_ctx_list *ctx"
143.Fa "struct sysctl_oid_list *parent"
144.Fa "int number"
145.Fa "const char *name"
146.Fa "int ctlflags"
147.Fa "void *arg1"
148.Fa "intptr_t arg2"
149.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
150.Fa "const char *format"
151.Fa "const char *descr"
152.Fc
153.Ft struct sysctl_oid *
154.Fo SYSCTL_ADD_QUAD
155.Fa "struct sysctl_ctx_list *ctx"
156.Fa "struct sysctl_oid_list *parent"
157.Fa "int number"
158.Fa "const char *name"
159.Fa "int ctlflags"
160.Fa "int64_t *ptr"
161.Fa "const char *descr"
162.Fc
163.Ft struct sysctl_oid *
164.Fo SYSCTL_ADD_ROOT_NODE
165.Fa "struct sysctl_ctx_list *ctx"
166.Fa "int number"
167.Fa "const char *name"
168.Fa "int ctlflags"
169.Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
170.Fa "const char *descr"
171.Fc
172.Ft struct sysctl_oid *
173.Fo SYSCTL_ADD_S8
174.Fa "struct sysctl_ctx_list *ctx"
175.Fa "struct sysctl_oid_list *parent"
176.Fa "int number"
177.Fa "const char *name"
178.Fa "int ctlflags"
179.Fa "int8_t *ptr"
180.Fa "int8_t val"
181.Fa "const char *descr"
182.Fc
183.Ft struct sysctl_oid *
184.Fo SYSCTL_ADD_S16
185.Fa "struct sysctl_ctx_list *ctx"
186.Fa "struct sysctl_oid_list *parent"
187.Fa "int number"
188.Fa "const char *name"
189.Fa "int ctlflags"
190.Fa "int16_t *ptr"
191.Fa "int16_t val"
192.Fa "const char *descr"
193.Fc
194.Ft struct sysctl_oid *
195.Fo SYSCTL_ADD_S32
196.Fa "struct sysctl_ctx_list *ctx"
197.Fa "struct sysctl_oid_list *parent"
198.Fa "int number"
199.Fa "const char *name"
200.Fa "int ctlflags"
201.Fa "int32_t *ptr"
202.Fa "int32_t val"
203.Fa "const char *descr"
204.Fc
205.Ft struct sysctl_oid *
206.Fo SYSCTL_ADD_S64
207.Fa "struct sysctl_ctx_list *ctx"
208.Fa "struct sysctl_oid_list *parent"
209.Fa "int number"
210.Fa "const char *name"
211.Fa "int ctlflags"
212.Fa "int64_t *ptr"
213.Fa "int64_t val"
214.Fa "const char *descr"
215.Fc
216.Ft struct sysctl_oid *
217.Fo SYSCTL_ADD_STRING
218.Fa "struct sysctl_ctx_list *ctx"
219.Fa "struct sysctl_oid_list *parent"
220.Fa "int number"
221.Fa "const char *name"
222.Fa "int ctlflags"
223.Fa "char *ptr"
224.Fa "intptr_t len"
225.Fa "const char *descr"
226.Fc
227.Ft struct sysctl_oid *
228.Fo SYSCTL_ADD_STRUCT
229.Fa "struct sysctl_ctx_list *ctx"
230.Fa "struct sysctl_oid_list *parent"
231.Fa "int number"
232.Fa "const char *name"
233.Fa "int ctlflags"
234.Fa "void *ptr"
235.Fa struct_type
236.Fa "const char *descr"
237.Fc
238.Ft struct sysctl_oid *
239.Fo SYSCTL_ADD_U8
240.Fa "struct sysctl_ctx_list *ctx"
241.Fa "struct sysctl_oid_list *parent"
242.Fa "int number"
243.Fa "const char *name"
244.Fa "int ctlflags"
245.Fa "uint8_t *ptr"
246.Fa "uint8_t val"
247.Fa "const char *descr"
248.Fc
249.Ft struct sysctl_oid *
250.Fo SYSCTL_ADD_U16
251.Fa "struct sysctl_ctx_list *ctx"
252.Fa "struct sysctl_oid_list *parent"
253.Fa "int number"
254.Fa "const char *name"
255.Fa "int ctlflags"
256.Fa "uint16_t *ptr"
257.Fa "uint16_t val"
258.Fa "const char *descr"
259.Fc
260.Ft struct sysctl_oid *
261.Fo SYSCTL_ADD_U32
262.Fa "struct sysctl_ctx_list *ctx"
263.Fa "struct sysctl_oid_list *parent"
264.Fa "int number"
265.Fa "const char *name"
266.Fa "int ctlflags"
267.Fa "uint32_t *ptr"
268.Fa "uint32_t val"
269.Fa "const char *descr"
270.Fc
271.Ft struct sysctl_oid *
272.Fo SYSCTL_ADD_U64
273.Fa "struct sysctl_ctx_list *ctx"
274.Fa "struct sysctl_oid_list *parent"
275.Fa "int number"
276.Fa "const char *name"
277.Fa "int ctlflags"
278.Fa "uint64_t *ptr"
279.Fa "uint64_t val"
280.Fa "const char *descr"
281.Fc
282.Ft struct sysctl_oid *
283.Fo SYSCTL_ADD_UINT
284.Fa "struct sysctl_ctx_list *ctx"
285.Fa "struct sysctl_oid_list *parent"
286.Fa "int number"
287.Fa "const char *name"
288.Fa "int ctlflags"
289.Fa "unsigned int *ptr"
290.Fa "unsigned int val"
291.Fa "const char *descr"
292.Fc
293.Ft struct sysctl_oid *
294.Fo SYSCTL_ADD_ULONG
295.Fa "struct sysctl_ctx_list *ctx"
296.Fa "struct sysctl_oid_list *parent"
297.Fa "int number"
298.Fa "const char *name"
299.Fa "int ctlflags"
300.Fa "unsigned long *ptr"
301.Fa "const char *descr"
302.Fc
303.Ft struct sysctl_oid *
304.Fo SYSCTL_ADD_UQUAD
305.Fa "struct sysctl_ctx_list *ctx"
306.Fa "struct sysctl_oid_list *parent"
307.Fa "int number"
308.Fa "const char *name"
309.Fa "int ctlflags"
310.Fa "uint64_t *ptr"
311.Fa "const char *descr"
312.Fc
313.Ft struct sysctl_oid *
314.Fo SYSCTL_ADD_UAUTO
315.Fa "struct sysctl_ctx_list *ctx"
316.Fa "struct sysctl_oid_list *parent"
317.Fa "int number"
318.Fa "const char *name"
319.Fa "int ctlflags"
320.Fa "void *ptr"
321.Fa "const char *descr"
322.Fc
323.Ft struct sysctl_oid_list *
324.Fo SYSCTL_CHILDREN
325.Fa "struct sysctl_oid *oidp"
326.Fc
327.Ft struct sysctl_oid_list *
328.Fo SYSCTL_STATIC_CHILDREN
329.Fa "struct sysctl_oid_list OID_NAME"
330.Fc
331.Ft struct sysctl_oid_list *
332.Fo SYSCTL_NODE_CHILDREN
333.Fa "parent"
334.Fa "name"
335.Fc
336.Ft struct sysctl_oid *
337.Fo SYSCTL_PARENT
338.Fa "struct sysctl_oid *oid"
339.Fc
340.Fn SYSCTL_INT parent number name ctlflags ptr val descr
341.Fn SYSCTL_INT_WITH_LABEL parent number name ctlflags ptr val descr label
342.Fn SYSCTL_LONG parent number name ctlflags ptr val descr
343.Fn SYSCTL_NODE parent number name ctlflags handler descr
344.Fn SYSCTL_NODE_WITH_LABEL parent number name ctlflags handler descr label
345.Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr
346.Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr
347.Fn SYSCTL_QUAD parent number name ctlflags ptr val descr
348.Fn SYSCTL_ROOT_NODE number name ctlflags handler descr
349.Fn SYSCTL_S8 parent number name ctlflags ptr val descr
350.Fn SYSCTL_S16 parent number name ctlflags ptr val descr
351.Fn SYSCTL_S32 parent number name ctlflags ptr val descr
352.Fn SYSCTL_S64 parent number name ctlflags ptr val descr
353.Fn SYSCTL_STRING parent number name ctlflags arg len descr
354.Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr
355.Fn SYSCTL_U8 parent number name ctlflags ptr val descr
356.Fn SYSCTL_U16 parent number name ctlflags ptr val descr
357.Fn SYSCTL_U32 parent number name ctlflags ptr val descr
358.Fn SYSCTL_U64 parent number name ctlflags ptr val descr
359.Fn SYSCTL_UINT parent number name ctlflags ptr val descr
360.Fn SYSCTL_ULONG parent number name ctlflags ptr val descr
361.Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr
362.Sh DESCRIPTION
363The
364.Nm SYSCTL
365kernel interface allows dynamic or static creation of
366.Xr sysctl 8
367MIB entries.
368All static sysctls are automatically destroyed when the module which
369they are part of is unloaded.
370Most top level categories are created statically and are available to
371all kernel code and its modules.
372.Sh DESCRIPTION OF ARGUMENTS
373.Bl -tag -width ctlflags
374.It Fa ctx
375Pointer to sysctl context or NULL, if no context.
376See
377.Xr sysctl_ctx_init 9
378for how to create a new sysctl context.
379Programmers are strongly advised to use contexts to organize the
380dynamic OIDs which they create because when a context is destroyed all
381belonging sysctls are destroyed as well.
382This makes the sysctl cleanup code much simpler.
383Else deletion of all created OIDs is required at module unload.
384.It Fa parent
385A pointer to a
386.Li struct sysctl_oid_list ,
387which is the head of the parent's list of children.
388This pointer is retrieved using the
389.Fn SYSCTL_STATIC_CHILDREN
390macro for static sysctls and the
391.Fn SYSCTL_CHILDREN
392macro for dynamic sysctls.
393The
394.Fn SYSCTL_PARENT
395macro can be used to get the parent of an OID.
396The macro returns NULL if there is no parent.
397.It Fa number
398The OID number that will be assigned to this OID.
399In almost all cases this should be set to
400.Dv OID_AUTO ,
401which will result in the assignment of the next available OID number.
402.It Fa name
403The name of the OID.
404The newly created OID will contain a copy of the name.
405.It Fa ctlflags
406A bit mask of sysctl control flags.
407See the section below describing all the control flags.
408.It Fa arg1
409First callback argument for procedure sysctls.
410.It Fa arg2
411Second callback argument for procedure sysctls.
412.It Fa len
413The length of the data pointed to by the
414.Fa ptr
415argument.
416For string type OIDs a length of zero means that
417.Xr strlen 3
418will be used to get the length of the string at each access to the OID.
419.It Fa ptr
420Pointer to sysctl variable or string data.
421For 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
422.Fa val
423argument.
424.It Fa val
425If the
426.Fa ptr
427argument is SYSCTL_NULL_XXX_PTR, gives the constant value returned by this OID.
428Else this argument is not used.
429.It Fa struct_type
430Name of structure type.
431.It Fa handler
432A pointer to the function
433that is responsible for handling read and write requests
434to this OID.
435There are several standard handlers
436that support operations on nodes,
437integers, strings and opaque objects.
438It is possible to define custom handlers using the
439.Fn SYSCTL_PROC
440macro or the
441.Fn SYSCTL_ADD_PROC
442function.
443.It Fa format
444A pointer to a string
445which specifies the format of the OID in a symbolic way.
446This format is used as a hint by
447.Xr sysctl 8
448to apply proper data formatting for display purposes.
449.Pp
450Current formats:
451.Bl -tag -width "S,TYPE" -compact -offset indent
452.It Cm N
453node
454.It Cm A
455.Li "char *"
456.It Cm I
457.Li "int"
458.It Cm IK Ns Op Ar n
459temperature in Kelvin, multiplied by an optional single digit
460power of ten scaling factor: 1 (default) gives deciKelvin, 0 gives Kelvin, 3
461gives milliKelvin
462.It Cm IU
463.Li "unsigned int"
464.It Cm L
465.Li "long"
466.It Cm LU
467.Li "unsigned long"
468.It Cm Q
469.Li "quad_t"
470.It Cm QU
471.Li "u_quad_t"
472.It Cm "S,TYPE"
473.Li "struct TYPE"
474structures
475.El
476.It Fa descr
477A pointer to a textual description of the OID.
478.It Fa label
479A pointer to an aggregation label for this component of the OID.
480To make it easier to export sysctl data to monitoring systems that
481support aggregations through labels (e.g., Prometheus),
482this argument can be used to attach a label name to an OID.
483The label acts as a hint that this component's name should not be part
484of the metric's name,
485but attached to the metric as a label instead.
486.Pp
487Labels should only be applied to siblings that are structurally similar
488and encode the same type of value,
489as aggregation is of no use otherwise.
490.El
491.Sh CREATING ROOT NODES
492Sysctl MIBs or OIDs are created in a hierarchical tree.
493The nodes at the bottom of the tree are called root nodes, and have no
494parent OID.
495To create bottom tree nodes the
496.Fn SYSCTL_ROOT_NODE
497macro or the
498.Fn SYSCTL_ADD_ROOT_NODE
499function needs to be used.
500By default all static sysctl node OIDs are global and need a
501.Fn SYSCTL_DECL
502statement prior to their
503.Fn SYSCTL_NODE
504definition statement, typically in a so-called header file.
505.Sh CREATING SYSCTL STRINGS
506Zero terminated character strings sysctls are created either using the
507.Fn SYSCTL_STRING
508macro or the
509.Fn SYSCTL_ADD_STRING
510function.
511If the
512.Fa len
513argument in zero, the string length is computed at every access to the OID using
514.Xr strlen 3 .
515.Sh CREATING OPAQUE SYSCTLS
516The
517.Fn SYSCTL_OPAQUE
518or
519.Fn SYSCTL_STRUCT
520macros or the
521.Fn SYSCTL_ADD_OPAQUE
522or
523.Fn SYSCTL_ADD_STRUCT
524functions create an OID that handle any chunk of data
525of the size specified by the
526.Fa len
527argument and data pointed to by the
528.Fa ptr
529argument.
530When using the structure version the type is encoded as part of the
531created sysctl.
532.Sh CREATING CUSTOM SYSCTLS
533The
534.Fn SYSCTL_PROC
535macro and the
536.Fn SYSCTL_ADD_PROC
537function
538create OIDs with the specified
539.Pa handler
540function.
541The handler is responsible for handling all read and write requests to
542the OID.
543This OID type is especially useful if the kernel data is not easily
544accessible, or needs to be processed before exporting.
545.Sh CREATING A STATIC SYSCTL
546Static sysctls are declared using one of the
547.Fn SYSCTL_INT ,
548.Fn SYSCTL_INT_WITH_LABEL ,
549.Fn SYSCTL_LONG ,
550.Fn SYSCTL_NODE ,
551.Fn SYSCTL_NODE_WITH_LABEL ,
552.Fn SYSCTL_OPAQUE ,
553.Fn SYSCTL_PROC ,
554.Fn SYSCTL_QUAD ,
555.Fn SYSCTL_ROOT_NODE ,
556.Fn SYSCTL_S8 ,
557.Fn SYSCTL_S16 ,
558.Fn SYSCTL_S32 ,
559.Fn SYSCTL_S64 ,
560.Fn SYSCTL_STRING ,
561.Fn SYSCTL_STRUCT ,
562.Fn SYSCTL_U8 ,
563.Fn SYSCTL_U16 ,
564.Fn SYSCTL_U32 ,
565.Fn SYSCTL_U64 ,
566.Fn SYSCTL_UINT ,
567.Fn SYSCTL_ULONG
568or
569.Fn SYSCTL_UQUAD
570macros.
571.Sh CREATING A DYNAMIC SYSCTL
572Dynamic nodes are created using one of the
573.Fn SYSCTL_ADD_INT ,
574.Fn SYSCTL_ADD_LONG ,
575.Fn SYSCTL_ADD_NODE ,
576.Fn SYSCTL_ADD_NODE_WITH_LABEL ,
577.Fn SYSCTL_ADD_OPAQUE ,
578.Fn SYSCTL_ADD_PROC ,
579.Fn SYSCTL_ADD_QUAD ,
580.Fn SYSCTL_ADD_ROOT_NODE ,
581.Fn SYSCTL_ADD_S8 ,
582.Fn SYSCTL_ADD_S16 ,
583.Fn SYSCTL_ADD_S32 ,
584.Fn SYSCTL_ADD_S64 ,
585.Fn SYSCTL_ADD_STRING ,
586.Fn SYSCTL_ADD_STRUCT ,
587.Fn SYSCTL_ADD_U8 ,
588.Fn SYSCTL_ADD_U16 ,
589.Fn SYSCTL_ADD_U32 ,
590.Fn SYSCTL_ADD_U64 ,
591.Fn SYSCTL_ADD_UAUTO ,
592.Fn SYSCTL_ADD_UINT ,
593.Fn SYSCTL_ADD_ULONG ,
594or
595.Fn SYSCTL_UQUAD
596functions.
597See
598.Xr sysctl_remove_oid 9
599or
600.Xr sysctl_ctx_free 9
601for more information on how to destroy a dynamically created OID.
602.Sh CONTROL FLAGS
603For most of the above functions and macros, declaring a type as part
604of the access flags is not necessary \[em] however, when declaring a
605sysctl implemented by a function, including a type in the access mask
606is required:
607.Bl -tag -width ".Dv CTLTYPE_NOFETCH"
608.It Dv CTLTYPE_NODE
609This is a node intended to be a parent for other nodes.
610.It Dv CTLTYPE_INT
611This is a signed integer.
612.It Dv CTLTYPE_STRING
613This is a nul-terminated string stored in a character array.
614.It Dv CTLTYPE_S8
615This is an 8-bit signed integer.
616.It Dv CTLTYPE_S16
617This is a 16-bit signed integer.
618.It Dv CTLTYPE_S32
619This is a 32-bit signed integer.
620.It Dv CTLTYPE_S64
621This is a 64-bit signed integer.
622.It Dv CTLTYPE_OPAQUE
623This is an opaque data structure.
624.It Dv CTLTYPE_STRUCT
625Alias for
626.Dv CTLTYPE_OPAQUE .
627.It Dv CTLTYPE_U8
628This is an 8-bit unsigned integer.
629.It Dv CTLTYPE_U16
630This is a 16-bit unsigned integer.
631.It Dv CTLTYPE_U32
632This is a 32-bit unsigned integer.
633.It Dv CTLTYPE_U64
634This is a 64-bit unsigned integer.
635.It Dv CTLTYPE_UINT
636This is an unsigned integer.
637.It Dv CTLTYPE_LONG
638This is a signed long.
639.It Dv CTLTYPE_ULONG
640This is an unsigned long.
641.El
642.Pp
643All sysctl types except for new node declarations require one of the following
644flags to be set indicating the read and write disposition of the sysctl:
645.Bl -tag -width ".Dv CTLFLAG_ANYBODY"
646.It Dv CTLFLAG_RD
647This is a read-only sysctl.
648.It Dv CTLFLAG_RDTUN
649This is a read-only sysctl and tunable which is tried fetched once
650from the system environment early during module load or system boot.
651.It Dv CTLFLAG_WR
652This is a writable sysctl.
653.It Dv CTLFLAG_RW
654This sysctl is readable and writable.
655.It Dv CTLFLAG_RWTUN
656This is a readable and writeable sysctl and tunable which is tried
657fetched once from the system environment early during module load or
658system boot.
659.It Dv CTLFLAG_NOFETCH
660In case the node is marked as a tunable using the CTLFLAG_[XX]TUN,
661this flag will prevent fetching the initial value from the system
662environment.
663Typically this flag should only be used for very early
664low level system setup code, and not by common drivers and modules.
665.El
666.Pp
667Additionally, any of the following optional flags may also be specified:
668.Bl -tag -width ".Dv CTLFLAG_ANYBODY"
669.It Dv CTLFLAG_ANYBODY
670Any user or process can write to this sysctl.
671.It Dv CTLFLAG_CAPRD
672A process in capability mode can read from this sysctl.
673.It Dv CTLFLAG_CAPWR
674A process in capability mode can write to this sysctl.
675.It Dv CTLFLAG_SECURE
676This sysctl can be written to only if the effective securelevel of the
677process is \[<=] 0.
678.It Dv CTLFLAG_PRISON
679This sysctl can be written to by processes in
680.Xr jail 2 .
681.It Dv CTLFLAG_SKIP
682When iterating the sysctl name space, do not list this sysctl.
683.It Dv CTLFLAG_TUN
684Advisory flag that a system tunable also exists for this variable.
685The initial sysctl value is tried fetched once from the system
686environment early during module load or system boot.
687.It Dv CTLFLAG_DYN
688Dynamically created OIDs automatically get this flag set.
689.It Dv CTLFLAG_VNET
690OID references a VIMAGE-enabled variable.
691.El
692.Sh EXAMPLES
693Sample use of
694.Fn SYSCTL_DECL
695to declare the
696.Va security
697sysctl tree for use by new nodes:
698.Bd -literal -offset indent
699SYSCTL_DECL(_security);
700.Ed
701.Pp
702Examples of integer, opaque, string, and procedure sysctls follow:
703.Bd -literal -offset indent
704/*
705 * Example of a constant integer value.  Notice that the control
706 * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR,
707 * and the value is declared.
708 */
709SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR,
710    sizeof(struct bio), "sizeof(struct bio)");
711
712/*
713 * Example of a variable integer value.  Notice that the control
714 * flags are CTLFLAG_RW, the variable pointer is set, and the
715 * value is 0.
716 */
717static int	doingcache = 1;		/* 1 => enable the cache */
718SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0,
719    "Enable name cache");
720
721/*
722 * Example of a variable string value.  Notice that the control
723 * flags are CTLFLAG_RW, that the variable pointer and string
724 * size are set.  Unlike newer sysctls, this older sysctl uses a
725 * static oid number.
726 */
727char kernelname[MAXPATHLEN] = "/kernel";	/* XXX bloat */
728SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW,
729    kernelname, sizeof(kernelname), "Name of kernel file booted");
730
731/*
732 * Example of an opaque data type exported by sysctl.  Notice that
733 * the variable pointer and size are provided, as well as a format
734 * string for sysctl(8).
735 */
736static l_fp pps_freq;	/* scaled frequency offset (ns/s) */
737SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD,
738    &pps_freq, sizeof(pps_freq), "I", "");
739
740/*
741 * Example of a procedure based sysctl exporting string
742 * information.  Notice that the data type is declared, the NULL
743 * variable pointer and 0 size, the function pointer, and the
744 * format string for sysctl(8).
745 */
746SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING |
747    CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A",
748    "");
749.Ed
750.Pp
751The following is an example of
752how to create a new top-level category
753and how to hook up another subtree to an existing static node.
754This example does not use contexts,
755which results in tedious management of all intermediate oids,
756as they need to be freed later on:
757.Bd -literal -offset indent
758#include <sys/sysctl.h>
759 ...
760/*
761 * Need to preserve pointers to newly created subtrees,
762 * to be able to free them later:
763 */
764static struct sysctl_oid *root1;
765static struct sysctl_oid *root2;
766static struct sysctl_oid *oidp;
767static int a_int;
768static char *string = "dynamic sysctl";
769 ...
770
771root1 = SYSCTL_ADD_ROOT_NODE(NULL,
772	OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree");
773oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1),
774	OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf");
775 ...
776root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug),
777	OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug");
778oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2),
779	OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf");
780.Ed
781.Pp
782This example creates the following subtrees:
783.Bd -literal -offset indent
784debug.newtree.newstring
785newtree.newint
786.Ed
787.Pp
788.Em "Care should be taken to free all OIDs once they are no longer needed!"
789.Sh SYSCTL NAMING
790When adding, modifying, or removing sysctl names, it is important to be
791aware that these interfaces may be used by users, libraries, applications,
792or documentation (such as published books), and are implicitly published application interfaces.
793As with other application interfaces, caution must be taken not to break
794existing applications, and to think about future use of new name spaces so as
795to avoid the need to rename or remove interfaces that might be depended on in
796the future.
797.Pp
798The semantics chosen for a new sysctl should be as clear as possible,
799and the name of the sysctl must closely reflect its semantics.
800Therefore the sysctl name deserves a fair amount of consideration.
801It should be short but yet representative of the sysctl meaning.
802If the name consists of several words, they should be separated by
803underscore characters, as in
804.Va compute_summary_at_mount .
805Underscore characters may be omitted only if the name consists of not more
806than two words, each being not longer than four characters, as in
807.Va bootfile .
808For boolean sysctls, negative logic should be totally avoided.
809That is, do not use names like
810.Va no_foobar
811or
812.Va foobar_disable .
813They are confusing and lead to configuration errors.
814Use positive logic instead:
815.Va foobar ,
816.Va foobar_enable .
817.Pp
818A temporary sysctl node OID that should not be relied upon must be designated
819as such by a leading underscore character in its name.
820For example:
821.Va _dirty_hack .
822.Sh SEE ALSO
823.Xr sysctl 3 ,
824.Xr sysctl 8 ,
825.Xr sysctl_add_oid 9 ,
826.Xr sysctl_ctx_free 9 ,
827.Xr sysctl_ctx_init 9 ,
828.Xr sysctl_remove_oid 9
829.Sh HISTORY
830The
831.Xr sysctl 8
832utility first appeared in
833.Bx 4.4 .
834.Sh AUTHORS
835.An -nosplit
836The
837.Nm sysctl
838implementation originally found in
839.Bx
840has been extensively rewritten by
841.An Poul-Henning Kamp
842in order to add support for name lookups, name space iteration, and dynamic
843addition of MIB nodes.
844.Pp
845This man page was written by
846.An Robert N. M. Watson .
847.Sh SECURITY CONSIDERATIONS
848When creating new sysctls, careful attention should be paid to the security
849implications of the monitoring or management interface being created.
850Most sysctls present in the kernel are read-only or writable only by the
851superuser.
852Sysctls exporting extensive information on system data structures and
853operation, especially those implemented using procedures, will wish to
854implement access control to limit the undesired exposure of information about
855other processes, network connections, etc.
856.Pp
857The following top level sysctl name spaces are commonly used:
858.Bl -tag -width ".Va regression"
859.It Va compat
860Compatibility layer information.
861.It Va debug
862Debugging information.
863Various name spaces exist under
864.Va debug .
865.It Va hw
866Hardware and device driver information.
867.It Va kern
868Kernel behavior tuning; generally deprecated in favor of more specific
869name spaces.
870.It Va machdep
871Machine-dependent configuration parameters.
872.It Va net
873Network subsystem.
874Various protocols have name spaces under
875.Va net .
876.It Va regression
877Regression test configuration and information.
878.It Va security
879Security and security-policy configuration and information.
880.It Va sysctl
881Reserved name space for the implementation of sysctl.
882.It Va user
883Configuration settings relating to user application behavior.
884Generally, configuring applications using kernel sysctls is discouraged.
885.It Va vfs
886Virtual file system configuration and information.
887.It Va vm
888Virtual memory subsystem configuration and information.
889.El
890