Commit | Line | Data |
---|---|---|
5e4ec111 KM |
1 | .\" Copyright (c) 1993 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" %sccs.include.redist.roff% | |
5 | .\" | |
e75c1b6b | 6 | .\" @(#)sysctl.3 6.3 (Berkeley) %G% |
5e4ec111 KM |
7 | .\" |
8 | .Dd "" | |
9 | .Dt SYSCTL 2 | |
10 | .Os | |
11 | .Sh NAME | |
12 | .Nm sysctl | |
13 | .Nd get or set kernel state | |
14 | .Sh SYNOPSIS | |
15 | .Fd #include <sys/sysctl.h> | |
16 | .Ft int | |
efc8bbc6 | 17 | .Fn sysctl "int *name" "u_int namelen" "void *old" "size_t *oldlenp" "void *new" "size_t newlen" |
5e4ec111 KM |
18 | .Sh DESCRIPTION |
19 | The | |
20 | .Fn sysctl | |
21 | function retrieves kernel state and allows processes with | |
22 | appropriate privilege to set kernel state. | |
e75c1b6b KM |
23 | The state to be set is described using a |
24 | ``Management Information Base'' (MIB) style name, | |
5e4ec111 KM |
25 | described in a |
26 | .Fa namelen | |
27 | length array of integers pointed to by | |
28 | .Fa name . | |
29 | The top level names are defined with a CTL_ prefix in | |
30 | .Pa <sys/sysctl.h> . | |
31 | The next levels down are found in the files given in the ``FILES'' | |
32 | section of this manual page. | |
33 | .Pp | |
e75c1b6b KM |
34 | The information is copied into the buffer specified by |
35 | .Fa old . | |
36 | The size of the buffer is given by the location specified by | |
37 | .Fa oldlenp | |
38 | before the call, | |
39 | and that location gives the amount of data copied after a successful call. | |
40 | If the amount of data available is greater | |
41 | than the size of the buffer supplied, | |
42 | the call supplies as much data as fits in the buffer provided | |
43 | and returns with the error code EINVAL. | |
5e4ec111 KM |
44 | If the old value is not desired, |
45 | .Fa old | |
46 | and | |
47 | .Fa oldlenp | |
48 | can be set to NULL. | |
49 | .Pp | |
e75c1b6b KM |
50 | The size of the available data can be determined by calling |
51 | .Fn sysctl | |
52 | with a NULL parameter for | |
53 | .Fa old . | |
54 | The size of the available data be returned in the location pointed to by | |
55 | .Fa oldlenp . | |
56 | For some operations, the amount of space may change often; | |
57 | the system attempts to round up so that the returned size is | |
58 | large enough for a call to return the data shortly thereafter. | |
59 | .Pp | |
5e4ec111 KM |
60 | To set a new value, |
61 | .Fa new | |
62 | is set to point to a buffer of length | |
63 | .Fa newlen | |
64 | from which the requested value is to be taken. | |
e75c1b6b | 65 | If a new value is not to be set, |
5e4ec111 KM |
66 | .Fa new |
67 | should be set to NULL and | |
68 | .Fa newlen | |
69 | set to 0. | |
70 | .Pp | |
e75c1b6b KM |
71 | The information available from |
72 | .Fn sysctl | |
73 | consists of integers, strings, and tables. | |
74 | The string and integer information is detailed below. | |
75 | The changeable column shows whether a process with appropriate | |
76 | privilege can change the value. | |
77 | Changeable values may be retrieved and set using the | |
78 | .Xr sysctl 1 | |
79 | utility. | |
80 | .Bl -column CTL_KERN/KERN_OSRELEASEXX "integerxx" -offset indent | |
81 | .It Sy "Name " " Type " " Changeable" | |
82 | .It Pa CTL_KERN/KERN_OSTYPE No " string" No " no" | |
83 | .It Pa CTL_KERN/KERN_OSRELEASE No " string" No " no" | |
84 | .It Pa CTL_KERN/KERN_VERSION No " string" No " no" | |
85 | .It Pa CTL_KERN/KERN_OSREV No " integer" No " no" | |
86 | .It Pa CTL_KERN/KERN_POSIX1 No " integer" No " no" | |
87 | .It Pa CTL_KERN/KERN_MAXPROC No " integer" No " yes" | |
88 | .It Pa CTL_KERN/KERN_MAXFILES No " integer" No " yes" | |
89 | .It Pa CTL_KERN/KERN_ARGMAX No " integer" No " no" | |
90 | .It Pa CTL_KERN/KERN_SECURELVL No " integer" No " raise only" | |
91 | .It Pa CTL_KERN/KERN_HOSTNAME No " string" No " yes" | |
92 | .It Pa CTL_KERN/KERN_HOSTID No " integer" No " yes" | |
93 | .It Pa CTL_HW/HW_MACHINE No " string" No " no" | |
94 | .It Pa CTL_HW/HW_MODEL No " string" No " no" | |
95 | .It Pa CTL_HW/HW_NCPU No " integer" No " no" | |
96 | .It Pa CTL_HW/HW_CPUSPEED No " integer" No " no" | |
97 | .It Pa CTL_HW/HW_PHYSMEM No " integer" No " no" | |
98 | .It Pa CTL_HW/HW_USERMEM No " integer" No " no" | |
99 | .It Pa CTL_HW/HW_PAGESIZE No " integer" No " no" | |
100 | .El | |
101 | .Pp | |
102 | For example, the following retrieves the maximum number of processes allowed | |
103 | in the system: | |
5e4ec111 | 104 | .Bd -literal -offset indent -compact |
efc8bbc6 KB |
105 | int name[2], maxproc; |
106 | size_t len; | |
e75c1b6b | 107 | .sp |
5e4ec111 KM |
108 | name[0] = CTL_KERN; |
109 | name[1] = KERN_MAXPROC; | |
efc8bbc6 | 110 | len = sizeof(maxproc); |
5e4ec111 KM |
111 | sysctl(name, 2, &maxproc, &len, NULL, 0); |
112 | .Ed | |
e75c1b6b KM |
113 | .Pp |
114 | The tables that can be retrieved from the kernel by | |
115 | .Fn sysctl | |
116 | are detailed below. | |
117 | For most operations, the | |
118 | .Fn sysctl | |
119 | function returns a consistent snapshot of the data requested. | |
120 | (This is not currently true for | |
121 | .Dv KERN_VNODE ) . | |
122 | The consistency is done by locking the destination buffer into memory | |
123 | so that the data may be copied out without blocking. | |
124 | Calls are serialized to avoid deadlock. | |
125 | The types of data currently available are process information, | |
126 | system vnodes, the open file entries, routing table entries, | |
127 | virtual memory statistics, load average history, | |
128 | and clock rate information. | |
129 | The following paragraphs detail how each of these is obtained. | |
130 | .Pp | |
131 | The entire process table, or a subset of it, may be obtained with | |
132 | .Pa CTL_KERN/KERN_PROC/<op>/<arg> . | |
133 | An array of | |
134 | .Ns ( Fa struct kinfo_proc Ns ) | |
135 | structures is returned, | |
136 | whose size depends on the current number of such objects in the system. | |
137 | The values for <op> and <arg> are: | |
138 | .Bl -column KERN_PROC_PGRPX "ARG Meaningxx" -offset indent | |
139 | .It Sy "OP " " ARG Meaning " | |
140 | .It Dv KERN_PROC_ALL No " none" | |
141 | .It Dv KERN_PROC_PID No " process ID" | |
142 | .It Dv KERN_PROC_PGRP No " process group" | |
143 | .It Dv KERN_PROC_TTY No " tty device" | |
144 | .It Dv KERN_PROC_UID No " user ID" | |
145 | .It Dv KERN_PROC_RUID No " real user ID" | |
146 | .El | |
147 | .Pp | |
148 | The entire vnode table may be obtained with | |
149 | .Pa CTL_KERN/KERN_VNODE . | |
150 | The returned data consists of an array | |
151 | whose size depends on the current number of such objects in the system. | |
152 | Each element of the array contains the kernel address of a vnode | |
153 | .Ns ( Fa struct vnode * Ns ) | |
154 | followed by the vnode itself | |
155 | .Ns ( Fa struct vnode Ns ) . | |
156 | .Pp | |
157 | The entire file table may be obtained with | |
158 | .Pa CTL_KERN/KERN_FILE . | |
159 | The returned data consists of a single | |
160 | .Ns ( Fa struct filehead Ns ) | |
161 | followed by an array of | |
162 | .Ns ( Fa struct file Ns ) , | |
163 | whose size depends on the current number of such objects in the system. | |
164 | .Pp | |
165 | Information about the system clock rate may be obtained with | |
166 | .Pa CTL_KERN/KERN_CLOCKRATE . | |
167 | The returned data consists of a | |
168 | .Ns ( Fa struct clockinfo Ns ) . | |
169 | .Pp | |
170 | Information about the load average history may be obtained with | |
171 | .Pa CTL_VM/VM_LOADAVG . | |
172 | The returned data consists of a | |
173 | .Ns ( Fa struct loadavg Ns ) . | |
174 | .Pp | |
175 | Information about the system wide virtual memory statistics | |
176 | may be obtained with | |
177 | .Pa CTL_VM/VM_METER . | |
178 | The returned data consists of a | |
179 | .Ns ( Fa struct vmtotal Ns ) . | |
180 | .Pp | |
181 | The entire routing table or a subset of it may be obtained with | |
182 | .Pa CTL_NET/PF_ROUTE/<protocol number>/<address family>/<op>/<arg> . | |
183 | The protocol number is currently always zero. | |
184 | The address family may be set to zero to select all address families. | |
185 | The values for <op> and <arg> are: | |
186 | .Bl -column NET_RT_IFLISTX "ARG Meaningxx" -offset indent | |
187 | .It Sy "OP " " ARG Meaning " | |
188 | .It Dv NET_RT_FLAGS No " rtflags" | |
189 | .It Dv NET_RT_DUMP No " none" | |
190 | .It Dv NET_RT_IFLIST No " none" | |
191 | .El | |
192 | The data is returned as a sequence of routing messages (see | |
193 | .Xr route 4 | |
194 | for the header file, format and meaning). | |
195 | The length of each message is contained in the message header. | |
5e4ec111 KM |
196 | .Sh RETURN VALUES |
197 | If the call to | |
198 | .Fn sysctl | |
e75c1b6b | 199 | is successful, 0 is returned. |
5e4ec111 KM |
200 | Otherwise \-1 is returned and |
201 | .Va errno | |
202 | is set appropriately. | |
203 | .Sh ERRORS | |
204 | The following error may be reported: | |
205 | .Bl -tag -width Er | |
206 | .It Bq Er EFAULT | |
207 | The buffer | |
208 | .Fa name , | |
209 | .Fa old , | |
210 | .Fa new , | |
211 | or length pointer | |
212 | .Fa oldlenp | |
213 | contains an invalid address. | |
214 | .It Bq Er EINVAL | |
215 | The | |
216 | .Fa name | |
217 | array is less than two or greater than CTL_MAXNAME. | |
218 | .It Bq Er EINVAL | |
219 | A non-null | |
220 | .Fa new | |
221 | is given and its specified length in | |
222 | .Fa newlen | |
223 | is too large or too small. | |
224 | .It Bq Er ENOMEM | |
225 | The length pointed to by | |
226 | .Fa oldlenp | |
227 | is too short to hold the requested value. | |
228 | .It Bq Er ENOTDIR | |
229 | The | |
230 | .Fa name | |
231 | array specifies an intermediate rather than terminal name. | |
232 | .It Bq Er EOPNOTSUPP | |
233 | The | |
234 | .Fa name | |
235 | array specifies a value that is unknown. | |
236 | .It Bq Er EPERM | |
237 | An attempt is made to set a read-only value. | |
238 | .It Bq Er EPERM | |
239 | A process without appropriate privilege attempts to set a value. | |
240 | .El | |
241 | .Sh FILES | |
242 | .Bl -tag -width <vm/vm_param.h> -compact | |
243 | .It Pa <sys/sysctl.h> | |
244 | definitions for top level identifiers and second level kernel | |
245 | and hardware identifiers | |
246 | .It Pa <sys/socket.h> | |
247 | definitions for second level network identifiers | |
248 | .It Pa <vm/vm_param.h> | |
249 | definitions for second level virtual memory identifiers | |
250 | .El | |
251 | .Sh SEE ALSO | |
252 | .Xr sysctl 8 | |
253 | .Sh HISTORY | |
e75c1b6b | 254 | The |
5e4ec111 | 255 | .Fn sysctl |
e75c1b6b | 256 | function first appeared in 4.4BSD. |