| sysctl.9 (161256) | sysctl.9 (162877) |
|---|---|
| 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 unchanged lines hidden (view full) --- 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.\" | 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 unchanged lines hidden (view full) --- 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: head/share/man/man9/sysctl.9 161256 2006-08-12 23:33:10Z obrien $ | 26.\" $FreeBSD: head/share/man/man9/sysctl.9 162877 2006-09-30 17:09:59Z ru $ |
| 27.\" 28.Dd April 28, 2006 29.Dt SYSCTL 9 30.Os 31.Sh NAME 32.Nm SYSCTL_DECL , 33.Nm SYSCTL_INT , 34.Nm SYSCTL_LONG , --- 5 unchanged lines hidden (view full) --- 40.Nm SYSCTL_UINT , 41.Nm SYSCTL_ULONG , 42.Nm SYSCTL_XINT , 43.Nm SYSCTL_XLONG 44.Nd Static sysctl declaration functions 45.Sh SYNOPSIS 46.In sys/types.h 47.In sys/sysctl.h | 27.\" 28.Dd April 28, 2006 29.Dt SYSCTL 9 30.Os 31.Sh NAME 32.Nm SYSCTL_DECL , 33.Nm SYSCTL_INT , 34.Nm SYSCTL_LONG , --- 5 unchanged lines hidden (view full) --- 40.Nm SYSCTL_UINT , 41.Nm SYSCTL_ULONG , 42.Nm SYSCTL_XINT , 43.Nm SYSCTL_XLONG 44.Nd Static sysctl declaration functions 45.Sh SYNOPSIS 46.In sys/types.h 47.In sys/sysctl.h |
| 48.Fo SYSCTL_DECL 49.Fa "name" 50.Fc 51.Fo SYSCTL_INT 52.Fa "parent" 53.Fa "nbr" 54.Fa "name" 55.Fa "access" 56.Fa "ptr" 57.Fa "val" 58.Fa "descr" 59.Fc 60.Fo SYSCTL_LONG 61.Fa "parent" 62.Fa "nbr" 63.Fa "name" 64.Fa "access" 65.Fa "ptr" 66.Fa "val" 67.Fa "descr" 68.Fc 69.Fo SYSCTL_NODE 70.Fa "parent" 71.Fa "nbr" 72.Fa "name" 73.Fa "access" 74.Fa "handler" 75.Fa "descr" 76.Fc 77.Fo SYSCTL_OPAQUE 78.Fa "parent" 79.Fa "nbr" 80.Fa "name" 81.Fa "access" 82.Fa "ptr" 83.Fa "len" 84.Fa "fmt" 85.Fa "descr" 86.Fc 87.Fo SYSCTL_PROC 88.Fa "parent" 89.Fa "nbr" 90.Fa "name" 91.Fa "access" 92.Fa "ptr" 93.Fa "arg" 94.Fa "handler" 95.Fa "fmt" 96.Fa "descr" 97.Fc 98.Fo SYSCTL_STRING 99.Fa "parent" 100.Fa "nbr" 101.Fa "name" 102.Fa "access" 103.Fa "arg" 104.Fa "len" 105.Fa "descr" 106.Fc 107.Fo SYSCTL_STRUCT 108.Fa "parent" 109.Fa "nbr" 110.Fa "name" 111.Fa "access" 112.Fa "ptr" 113.Fa "type" 114.Fa "descr" 115.Fc 116.Fo SYSCTL_UINT 117.Fa "parent" 118.Fa "nbr" 119.Fa "name" 120.Fa "access" 121.Fa "ptr" 122.Fa "val" 123.Fa "descr" 124.Fc 125.Fo SYSCTL_ULONG 126.Fa "parent" 127.Fa "nbr" 128.Fa "name" 129.Fa "access" 130.Fa "ptr" 131.Fa "val" 132.Fa "descr" 133.Fc 134.Fo SYSCTL_XINT 135.Fa "parent" 136.Fa "nbr" 137.Fa "name" 138.Fa "access" 139.Fa "ptr" 140.Fa "val" 141.Fa "descr" 142.Fc 143.Fo SYSCTL_XLONG 144.Fa "parent" 145.Fa "nbr" 146.Fa "name" 147.Fa "access" 148.Fa "ptr" 149.Fa "val" 150.Fa "descr" 151.Fc | 48.Fn SYSCTL_DECL name 49.Fn SYSCTL_INT parent nbr name access ptr val descr 50.Fn SYSCTL_LONG parent nbr name access ptr val descr 51.Fn SYSCTL_NODE parent nbr name access handler descr 52.Fn SYSCTL_OPAQUE parent nbr name access ptr len fmt descr 53.Fn SYSCTL_PROC parent nbr name access ptr arg handler fmt descr 54.Fn SYSCTL_STRING parent nbr name access arg len descr 55.Fn SYSCTL_STRUCT parent nbr name access ptr type descr 56.Fn SYSCTL_UINT parent nbr name access ptr val descr 57.Fn SYSCTL_ULONG parent nbr name access ptr val descr 58.Fn SYSCTL_XINT parent nbr name access ptr val descr 59.Fn SYSCTL_XLONG parent nbr name access ptr val descr |
| 152.Sh DESCRIPTION 153The | 60.Sh DESCRIPTION 61The |
| 154.Nm | 62.Nm SYSCTL |
| 155kernel interfaces allow code to statically declare 156.Xr sysctl 8 157MIB entries, which will be initialized when the kernel module containing the 158declaration is initialized. 159When the module is unloaded, the sysctl will be automatically destroyed. 160.Pp 161Sysctl nodes are created in a hierarchical tree, with all static nodes being 162represented by named C data structures; in order to create a new node under 163an existing node in the tree, the structure representing the desired parent 164node must be declared in the current context using 165.Fn SYSCTL_DECL . 166.Pp 167New nodes are declared using one of | 63kernel interfaces allow code to statically declare 64.Xr sysctl 8 65MIB entries, which will be initialized when the kernel module containing the 66declaration is initialized. 67When the module is unloaded, the sysctl will be automatically destroyed. 68.Pp 69Sysctl nodes are created in a hierarchical tree, with all static nodes being 70represented by named C data structures; in order to create a new node under 71an existing node in the tree, the structure representing the desired parent 72node must be declared in the current context using 73.Fn SYSCTL_DECL . 74.Pp 75New nodes are declared using one of |
| 168.Nm SYSCTL_INT , 169.Nm SYSCTL_LONG , 170.Nm SYSCTL_NODE , 171.Nm SYSCTL_OPAQUE , 172.Nm SYSCTL_PROC , 173.Nm SYSCTL_STRING , 174.Nm SYSCTL_STRUCT , 175.Nm SYSCTL_UINT , 176.Nm SYSCTL_ULONG , 177.Nm SYSCTL_XINT , | 76.Fn SYSCTL_INT , 77.Fn SYSCTL_LONG , 78.Fn SYSCTL_NODE , 79.Fn SYSCTL_OPAQUE , 80.Fn SYSCTL_PROC , 81.Fn SYSCTL_STRING , 82.Fn SYSCTL_STRUCT , 83.Fn SYSCTL_UINT , 84.Fn SYSCTL_ULONG , 85.Fn SYSCTL_XINT , |
| 178and | 86and |
| 179.Nm SYSCTL_XLONG . | 87.Fn SYSCTL_XLONG . |
| 180Each macro accepts a parent name, as declared using | 88Each macro accepts a parent name, as declared using |
| 181.Nm SYSCTL_DECL , | 89.Fn SYSCTL_DECL , |
| 182an OID number, typically 183.Dv OID_AUTO , 184a node name, a set of control and access flags, and a description. 185Depending on the macro, a pointer to a variable supporting the MIB entry, a 186size, a value, and a function pointer implementing the MIB entry may also be 187present. 188.Pp 189For most of the above macros, declaring a type as part of the access flags is | 90an OID number, typically 91.Dv OID_AUTO , 92a node name, a set of control and access flags, and a description. 93Depending on the macro, a pointer to a variable supporting the MIB entry, a 94size, a value, and a function pointer implementing the MIB entry may also be 95present. 96.Pp 97For most of the above macros, declaring a type as part of the access flags is |
| 190not necessary -- however, when declaring a sysctl implemented by a function, | 98not necessary \[em] however, when declaring a sysctl implemented by a function, |
| 191including a type in the access mask is required: | 99including a type in the access mask is required: |
| 192.Bl -tag -width CTLTYPE_STRING | 100.Bl -tag -width ".Dv CTLTYPE_STRING" |
| 193.It Dv CTLTYPE_NODE 194This is a node intended to be a parent for other nodes. 195.It Dv CTLTYPE_INT 196This is a signed integer. 197.It Dv CTLTYPE_STRING 198This is a nul-terminated string stored in a character array. 199.It Dv CTLTYPE_QUAD 200This is a 64-bit signed integer. --- 7 unchanged lines hidden (view full) --- 208.It Dv CTLTYPE_LONG 209This is a signed long. 210.It Dv CTLTYPE_ULONG 211This is an unsigned long. 212.El 213.Pp 214All sysctl types except for new node declarations require one or more flags 215to be set indicating the read and write disposition of the sysctl: | 101.It Dv CTLTYPE_NODE 102This is a node intended to be a parent for other nodes. 103.It Dv CTLTYPE_INT 104This is a signed integer. 105.It Dv CTLTYPE_STRING 106This is a nul-terminated string stored in a character array. 107.It Dv CTLTYPE_QUAD 108This is a 64-bit signed integer. --- 7 unchanged lines hidden (view full) --- 116.It Dv CTLTYPE_LONG 117This is a signed long. 118.It Dv CTLTYPE_ULONG 119This is an unsigned long. 120.El 121.Pp 122All sysctl types except for new node declarations require one or more flags 123to be set indicating the read and write disposition of the sysctl: |
| 216.Bl -tag -width CTLFLAG_ANYBODY | 124.Bl -tag -width ".Dv CTLFLAG_ANYBODY" |
| 217.It Dv CTLFLAG_RD 218This is a read-only sysctl. 219.It Dv CTLFLAG_WR 220This is a writable sysctl. 221.It Dv CTLFLAG_RW 222This sysctl is readable and writable. 223.It Dv CTLFLAG_ANYBODY 224Any user or process can write to this sysctl. 225.It Dv CTLFLAG_SECURE 226This sysctl can be written to only if the effective securelevel of the | 125.It Dv CTLFLAG_RD 126This is a read-only sysctl. 127.It Dv CTLFLAG_WR 128This is a writable sysctl. 129.It Dv CTLFLAG_RW 130This sysctl is readable and writable. 131.It Dv CTLFLAG_ANYBODY 132Any user or process can write to this sysctl. 133.It Dv CTLFLAG_SECURE 134This sysctl can be written to only if the effective securelevel of the |
| 227process is <= 0. | 135process is \[<=] 0. |
| 228.It Dv CTLFLAG_PRISON 229This sysctl can be written to by processes in 230.Xr jail 2 . 231.It Dv CTLFLAG_SKIP 232When iterating the sysctl name space, do not list this sysctl. 233.It Dv CTLFLAG_TUN 234Also declare a system tunable with the same name to initialize this variable. 235.It Dv CTLFLAG_RDTUN --- 6 unchanged lines hidden (view full) --- 242Most sysctls present in the kernel are read-only or writable only by the 243superuser. 244Sysctls exporting extensive information on system data structures and 245operation, especially those implemented using procedures, will wish to 246implement access control to limit the undesired exposure of information about 247other processes, network connections, etc. 248.Pp 249The following top level sysctl name spaces are commonly used: | 136.It Dv CTLFLAG_PRISON 137This sysctl can be written to by processes in 138.Xr jail 2 . 139.It Dv CTLFLAG_SKIP 140When iterating the sysctl name space, do not list this sysctl. 141.It Dv CTLFLAG_TUN 142Also declare a system tunable with the same name to initialize this variable. 143.It Dv CTLFLAG_RDTUN --- 6 unchanged lines hidden (view full) --- 150Most sysctls present in the kernel are read-only or writable only by the 151superuser. 152Sysctls exporting extensive information on system data structures and 153operation, especially those implemented using procedures, will wish to 154implement access control to limit the undesired exposure of information about 155other processes, network connections, etc. 156.Pp 157The following top level sysctl name spaces are commonly used: |
| 250.Bl -tag -width regression 251.It Dv compat | 158.Bl -tag -width ".Va regression" 159.It Va compat |
| 252Compatibility layer information. | 160Compatibility layer information. |
| 253.It Dv debug | 161.It Va debug |
| 254Debugging information. 255Various name spaces exist under | 162Debugging information. 163Various name spaces exist under |
| 256.Dv debug . 257.It Dv hw | 164.Va debug . 165.It Va hw |
| 258Hardware and device driver information. | 166Hardware and device driver information. |
| 259.It Dv kern | 167.It Va kern |
| 260Kernel behavior tuning; generally deprecated in favor of more specific 261name spaces. | 168Kernel behavior tuning; generally deprecated in favor of more specific 169name spaces. |
| 262.It Dv machdep | 170.It Va machdep |
| 263Machine-dependent configuration parameters. | 171Machine-dependent configuration parameters. |
| 264.It Dv net | 172.It Va net |
| 265Network subsystem. 266Various protocols have name spaces under | 173Network subsystem. 174Various protocols have name spaces under |
| 267.Dv net . 268.It Dv regression | 175.Va net . 176.It Va regression |
| 269Regression test configuration and information. | 177Regression test configuration and information. |
| 270.It Dv security | 178.It Va security |
| 271Security and security-policy configuration and information. | 179Security and security-policy configuration and information. |
| 272.It Dv sysctl | 180.It Va sysctl |
| 273Reserved name space for the implementation of sysctl. | 181Reserved name space for the implementation of sysctl. |
| 274.It Dv user | 182.It Va user |
| 275Configuration settings relating to user application behavior. 276Generally, configuring applications using kernel sysctls is discouraged. | 183Configuration settings relating to user application behavior. 184Generally, configuring applications using kernel sysctls is discouraged. |
| 277.It Dv vfs | 185.It Va vfs |
| 278Virtual file system configuration and information. | 186Virtual file system configuration and information. |
| 279.It Dv vm | 187.It Va vm |
| 280Virtual memory subsystem configuration and information. 281.El 282.Sh EXAMPLES 283Sample use of | 188Virtual memory subsystem configuration and information. 189.El 190.Sh EXAMPLES 191Sample use of |
| 284.Nm SYSCTL_DECL 285to declare the "security" sysctl tree for use by new nodes: | 192.Fn SYSCTL_DECL 193to declare the 194.Va security 195sysctl tree for use by new nodes: |
| 286.Bd -literal -offset indent 287SYSCTL_DECL(_security); 288.Ed 289.Pp 290Examples of integer, opaque, string, and procedure sysctls follow: 291.Bd -literal -offset indent 292/* 293 * Example of a constant integer value. Notice that the control --- 52 unchanged lines hidden (view full) --- 346the future. 347.Sh SEE ALSO 348.Xr sysctl 8 , 349.Xr sysctl_add_oid 9 , 350.Xr sysctl_ctx_free 9 , 351.Xr sysctl_ctx_init 9 , 352.Xr sysctl_remove_oid 9 353.Sh HISTORY | 196.Bd -literal -offset indent 197SYSCTL_DECL(_security); 198.Ed 199.Pp 200Examples of integer, opaque, string, and procedure sysctls follow: 201.Bd -literal -offset indent 202/* 203 * Example of a constant integer value. Notice that the control --- 52 unchanged lines hidden (view full) --- 256the future. 257.Sh SEE ALSO 258.Xr sysctl 8 , 259.Xr sysctl_add_oid 9 , 260.Xr sysctl_ctx_free 9 , 261.Xr sysctl_ctx_init 9 , 262.Xr sysctl_remove_oid 9 263.Sh HISTORY |
| 264The |
|
| 354.Xr sysctl 8 | 265.Xr sysctl 8 |
| 355first appeared in | 266utility first appeared in |
| 356.Bx 4.4 . 357.Sh AUTHORS | 267.Bx 4.4 . 268.Sh AUTHORS |
| 358The sysctl implementation originally found in | 269.An -nosplit 270The 271.Nm sysctl 272implementation originally found in |
| 359.Bx 360has been extensively rewritten by 361.An Poul-Henning Kamp 362in order to add support for name lookups, name space iteration, and dynamic 363addition of MIB nodes. 364.Pp 365This man page was written by 366.An Robert N. M. Watson . | 273.Bx 274has been extensively rewritten by 275.An Poul-Henning Kamp 276in order to add support for name lookups, name space iteration, and dynamic 277addition of MIB nodes. 278.Pp 279This man page was written by 280.An Robert N. M. Watson . |