kernel: Add further support for fixed-width integer type sysctls.
[dragonfly.git] / share / man / man9 / sysctl.9
CommitLineData
59308cc9
SW
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: src/share/man/man9/sysctl.9,v 1.3 2006/04/28 23:21:36 keramida Exp $
59308cc9 27.\"
347aefc6 28.Dd October 6, 2018
59308cc9
SW
29.Dt SYSCTL 9
30.Os
31.Sh NAME
32.Nm SYSCTL_DECL ,
33.Nm SYSCTL_INT ,
34.Nm SYSCTL_LONG ,
35.Nm SYSCTL_QUAD ,
36.Nm SYSCTL_NODE ,
37.Nm SYSCTL_OPAQUE ,
38.Nm SYSCTL_PROC ,
347aefc6
SW
39.Nm SYSCTL_S8 ,
40.Nm SYSCTL_S16 ,
41.Nm SYSCTL_S32 ,
42.Nm SYSCTL_S64 ,
59308cc9
SW
43.Nm SYSCTL_STRING ,
44.Nm SYSCTL_STRUCT ,
347aefc6
SW
45.Nm SYSCTL_U8 ,
46.Nm SYSCTL_U16 ,
c48b2bac 47.Nm SYSCTL_U32 ,
347aefc6 48.Nm SYSCTL_U64 ,
59308cc9
SW
49.Nm SYSCTL_UINT ,
50.Nm SYSCTL_ULONG ,
51.Nm SYSCTL_UQUAD
52.Nd Static sysctl declaration functions
53.Sh SYNOPSIS
54.In sys/types.h
55.In sys/sysctl.h
56.Fo SYSCTL_DECL
57.Fa "name"
58.Fc
59.Fo SYSCTL_INT
60.Fa "parent"
61.Fa "nbr"
62.Fa "name"
63.Fa "access"
64.Fa "ptr"
65.Fa "val"
66.Fa "descr"
67.Fc
68.Fo SYSCTL_LONG
69.Fa "parent"
70.Fa "nbr"
71.Fa "name"
72.Fa "access"
73.Fa "ptr"
74.Fa "val"
75.Fa "descr"
76.Fc
59308cc9
SW
77.Fo SYSCTL_NODE
78.Fa "parent"
79.Fa "nbr"
80.Fa "name"
81.Fa "access"
82.Fa "handler"
83.Fa "descr"
84.Fc
85.Fo SYSCTL_OPAQUE
86.Fa "parent"
87.Fa "nbr"
88.Fa "name"
89.Fa "access"
90.Fa "ptr"
91.Fa "len"
92.Fa "fmt"
93.Fa "descr"
94.Fc
95.Fo SYSCTL_PROC
96.Fa "parent"
97.Fa "nbr"
98.Fa "name"
99.Fa "access"
100.Fa "ptr"
101.Fa "arg"
102.Fa "handler"
103.Fa "fmt"
104.Fa "descr"
105.Fc
347aefc6
SW
106.Fo SYSCTL_QUAD
107.Fa "parent"
108.Fa "nbr"
109.Fa "name"
110.Fa "access"
111.Fa "ptr"
112.Fa "val"
113.Fa "descr"
114.Fc
115.Fo SYSCTL_S8
116.Fa "parent"
117.Fa "number"
118.Fa "name"
119.Fa "access"
120.Fa "ptr"
121.Fa "val"
122.Fa "descr"
123.Fc
124.Fo SYSCTL_S16
125.Fa "parent"
126.Fa "number"
127.Fa "name"
128.Fa "access"
129.Fa "ptr"
130.Fa "val"
131.Fa "descr"
132.Fc
133.Fo SYSCTL_S32
134.Fa "parent"
135.Fa "number"
136.Fa "name"
137.Fa "access"
138.Fa "ptr"
139.Fa "val"
140.Fa "descr"
141.Fc
142.Fo SYSCTL_S64
143.Fa "parent"
144.Fa "number"
145.Fa "name"
146.Fa "access"
147.Fa "ptr"
148.Fa "val"
149.Fa "descr"
150.Fc
59308cc9
SW
151.Fo SYSCTL_STRING
152.Fa "parent"
153.Fa "nbr"
154.Fa "name"
155.Fa "access"
156.Fa "arg"
157.Fa "len"
158.Fa "descr"
159.Fc
160.Fo SYSCTL_STRUCT
161.Fa "parent"
162.Fa "nbr"
163.Fa "name"
164.Fa "access"
165.Fa "ptr"
166.Fa "type"
167.Fa "descr"
168.Fc
347aefc6
SW
169.Fo SYSCTL_U8
170.Fa "parent"
171.Fa "number"
172.Fa "name"
173.Fa "access"
174.Fa "ptr"
175.Fa "val"
176.Fa "descr"
177.Fc
178.Fo SYSCTL_U16
179.Fa "parent"
180.Fa "number"
181.Fa "name"
182.Fa "access"
183.Fa "ptr"
184.Fa "val"
185.Fa "descr"
186.Fc
c48b2bac
SW
187.Fo SYSCTL_U32
188.Fa "parent"
189.Fa "number"
190.Fa "name"
191.Fa "access"
192.Fa "ptr"
193.Fa "val"
194.Fa "descr"
195.Fc
347aefc6
SW
196.Fo SYSCTL_U64
197.Fa "parent"
198.Fa "number"
199.Fa "name"
200.Fa "access"
201.Fa "ptr"
202.Fa "val"
203.Fa "descr"
204.Fc
59308cc9
SW
205.Fo SYSCTL_UINT
206.Fa "parent"
207.Fa "nbr"
208.Fa "name"
209.Fa "access"
210.Fa "ptr"
211.Fa "val"
212.Fa "descr"
213.Fc
214.Fo SYSCTL_ULONG
215.Fa "parent"
216.Fa "nbr"
217.Fa "name"
218.Fa "access"
219.Fa "ptr"
220.Fa "val"
221.Fa "descr"
222.Fc
223.Fo SYSCTL_UQUAD
224.Fa "parent"
225.Fa "nbr"
226.Fa "name"
227.Fa "access"
228.Fa "ptr"
229.Fa "val"
230.Fa "descr"
231.Fc
232.Sh DESCRIPTION
233The
234.Nm
235kernel interfaces allow code to statically declare
236.Xr sysctl 8
237MIB entries, which will be initialized when the kernel module containing the
238declaration is initialized.
239When the module is unloaded, the sysctl will be automatically destroyed.
240.Pp
241Sysctl nodes are created in a hierarchical tree, with all static nodes being
242represented by named C data structures; in order to create a new node under
243an existing node in the tree, the structure representing the desired parent
244node must be declared in the current context using
245.Fn SYSCTL_DECL .
246.Pp
247New nodes are declared using one of
248.Nm SYSCTL_INT ,
249.Nm SYSCTL_LONG ,
250.Nm SYSCTL_QUAD ,
251.Nm SYSCTL_NODE ,
252.Nm SYSCTL_OPAQUE ,
253.Nm SYSCTL_PROC ,
347aefc6
SW
254.Nm SYSCTL_S8 ,
255.Nm SYSCTL_S16 ,
256.Nm SYSCTL_S32 ,
257.Nm SYSCTL_S64 ,
59308cc9
SW
258.Nm SYSCTL_STRING ,
259.Nm SYSCTL_STRUCT ,
347aefc6
SW
260.Nm SYSCTL_U8 ,
261.Nm SYSCTL_U16 ,
c48b2bac 262.Nm SYSCTL_U32 ,
347aefc6 263.Nm SYSCTL_U64 ,
59308cc9
SW
264.Nm SYSCTL_UINT ,
265.Nm SYSCTL_ULONG ,
266and
267.Nm SYSCTL_UQUAD .
268Each macro accepts a parent name, as declared using
269.Nm SYSCTL_DECL ,
270an OID number, typically
271.Dv OID_AUTO ,
272a node name, a set of control and access flags, and a description.
273Depending on the macro, a pointer to a variable supporting the MIB entry, a
274size, a value, and a function pointer implementing the MIB entry may also be
275present.
276.Pp
277For most of the above macros, declaring a type as part of the access flags is
278not necessary -- however, when declaring a sysctl implemented by a function,
279including a type in the access mask is required:
f54c32e1 280.Bl -tag -width ".Dv CTLTYPE_STRING"
59308cc9
SW
281.It Dv CTLTYPE_NODE
282This is a node intended to be a parent for other nodes.
283.It Dv CTLTYPE_INT
284This is a signed integer.
347aefc6
SW
285.It Dv CTLTYPE_S8
286This is an 8-bit signed integer.
287.It Dv CTLTYPE_S16
288This is a 16-bit signed integer.
289.It Dv CTLTYPE_S32
290This is a 32-bit signed integer.
291.It Dv CTLTYPE_S64
292This is a 64-bit signed integer.
59308cc9
SW
293.It Dv CTLTYPE_STRING
294This is a nul-terminated string stored in a character array.
295.It Dv CTLTYPE_QUAD
296This is a 64-bit signed integer.
297.It Dv CTLTYPE_OPAQUE
298This is an opaque data structure.
299.It Dv CTLTYPE_STRUCT
300Alias for
f60c028d 301.Dv CTLTYPE_OPAQUE .
347aefc6
SW
302.It Dv CTLTYPE_U8
303This is an 8-bit unsigned integer.
304.It Dv CTLTYPE_U16
305This is a 16-bit unsigned integer.
c48b2bac
SW
306.It Dv CTLTYPE_U32
307This is a 32-bit unsigned integer.
347aefc6
SW
308.It Dv CTLTYPE_U64
309This is a 64-bit unsigned integer.
59308cc9
SW
310.It Dv CTLTYPE_UINT
311This is an unsigned integer.
312.It Dv CTLTYPE_LONG
313This is a signed long.
314.It Dv CTLTYPE_ULONG
315This is an unsigned long.
316.It Dv CTLTYPE_UQUAD
317This is a 64-bit unsigned integer.
318.El
319.Pp
320All sysctl types except for new node declarations require one or more flags
321to be set indicating the read and write disposition of the sysctl:
f54c32e1 322.Bl -tag -width ".Dv CTLFLAG_ANYBODY"
59308cc9
SW
323.It Dv CTLFLAG_RD
324This is a read-only sysctl.
6d600fe3 325.It Dv CTLFLAG_WR
59308cc9
SW
326This is a writable sysctl.
327.It Dv CTLFLAG_RW
328This sysctl is readable and writable.
329.It Dv CTLFLAG_ANYBODY
330Any user or process can write to this sysctl.
59308cc9
SW
331.It Dv CTLFLAG_SECURE
332This sysctl can be written to only if the effective securelevel of the
333process is <= 0.
334.It Dv CTLFLAG_PRISON
335This sysctl can be written to by processes in
336.Xr jail 2 .
afc5c1ad
SW
337.\".It Dv CTLFLAG_SKIP
338.\"When iterating the sysctl name space, do not list this sysctl.
59308cc9
SW
339.El
340.Pp
341When creating new sysctls, careful attention should be paid to the security
342implications of the monitoring or management interface being created.
343Most sysctls present in the kernel are read-only or writable only by the
344superuser.
345Sysctls exporting extensive information on system data structures and
346operation, especially those implemented using procedures, will wish to
347implement access control to limit the undesired exposure of information about
348other processes, network connections, etc.
349.Pp
350The following top level sysctl name spaces are commonly used:
afc5c1ad
SW
351.Bl -tag -width ".Va machdep"
352.It Va compat
59308cc9 353Compatibility layer information.
afc5c1ad 354.It Va debug
59308cc9
SW
355Debugging information.
356Various name spaces exist under
afc5c1ad
SW
357.Va debug .
358.It Va hw
59308cc9 359Hardware and device driver information.
afc5c1ad 360.It Va lwkt
59308cc9
SW
361Information about the
362.Xr lwkt 9
363subsystem.
afc5c1ad 364.It Va kern
59308cc9
SW
365Kernel behavior tuning; generally deprecated in favor of more specific
366name spaces.
afc5c1ad 367.It Va machdep
59308cc9 368Machine-dependent configuration parameters.
afc5c1ad 369.It Va net
59308cc9
SW
370Network subsystem.
371Various protocols have name spaces under
afc5c1ad
SW
372.Va net .
373.It Va sysctl
59308cc9 374Reserved name space for the implementation of sysctl.
afc5c1ad 375.It Va user
59308cc9
SW
376Configuration settings relating to user application behavior.
377Generally, configuring applications using kernel sysctls is discouraged.
afc5c1ad 378.It Va vfs
59308cc9 379Virtual file system configuration and information.
afc5c1ad 380.It Va vm
59308cc9
SW
381Virtual memory subsystem configuration and information.
382.El
383.Sh EXAMPLES
384Sample use of
385.Nm SYSCTL_DECL
386to declare the "machdep" sysctl tree for use by new nodes:
387.Bd -literal -offset indent
388SYSCTL_DECL(_machdep);
389.Ed
390.Pp
391Examples of integer, opaque, string, and procedure sysctls follow:
392.Bd -literal -offset indent
393/*
394 * Example of a constant integer value. Notice that the control
395 * flags are CTLFLAG_RD, the variable pointer is NULL, and the
396 * value is declared.
397 */
398SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, NULL,
399 sizeof(struct bio), "sizeof(struct bio)");
400
401/*
402 * Example of a variable integer value. Notice that the control
403 * flags are CTLFLAG_RW, the variable pointer is set, and the
404 * value is 0.
405 */
406static int doingcache = 1; /* 1 => enable the cache */
407SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0,
408 "Enable name cache");
409
410/*
411 * Example of a variable string value. Notice that the control
412 * flags are CTLFLAG_RW, that the variable pointer and string
413 * size are set. Unlike newer sysctls, this older sysctl uses a
414 * static oid number.
415 */
8e1c6f81 416char kernelname[MAXPATHLEN] = "/boot/kernel"; /* XXX bloat */
59308cc9
SW
417SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW,
418 kernelname, sizeof(kernelname), "Name of kernel file booted");
419
420/*
421 * Example of an opaque data type exported by sysctl. Notice that
422 * the variable pointer and size are provided, as well as a format
423 * string for sysctl(8).
424 */
2a1faf81 425static l_fp pps_freq; /* scaled frequency offset (ns/s) */
59308cc9
SW
426SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD,
427 &pps_freq, sizeof(pps_freq), "I", "");
428
429/*
430 * Example of a procedure based sysctl exporting string
431 * information. Notice that the data type is declared, the NULL
432 * variable pointer and 0 size, the function pointer, and the
433 * format string for sysctl(8).
434 */
435SYSCTL_PROC(_kern, OID_AUTO, msgbuf, CTLTYPE_STRING | CTLFLAG_RD,
436 0, 0, sysctl_kern_msgbuf, "A", "Contents of kernel message buffer");
437.Ed
438.Pp
439When adding, modifying, or removing sysctl names, it is important to be
440aware that these interfaces may be used by users, libraries, applications,
441or documentation (such as published books), and are implicitly published
442application interfaces.
443As with other application interfaces, caution must be taken not to break
444existing applications, and to think about future use of new name spaces so as
445to avoid the need to rename or remove interfaces that might be depended on in
446the future.
447.Sh SEE ALSO
448.Xr sysctl 8 ,
449.Xr sysctl_add_oid 9 ,
450.Xr sysctl_ctx_free 9 ,
451.Xr sysctl_ctx_init 9 ,
452.Xr sysctl_remove_oid 9
453.Sh HISTORY
454.Xr sysctl 8
455first appeared in
456.Bx 4.4 .
457.Sh AUTHORS
18dfd54e 458.An -nosplit
59308cc9
SW
459The sysctl implementation originally found in
460.Bx
461has been extensively rewritten by
462.An Poul-Henning Kamp
463in order to add support for name lookups, name space iteration, and dynamic
464addition of MIB nodes.
465.Pp
466This man page was written by
467.An Robert N. M. Watson .