1SYSCTL(3) Library Functions Manual SYSCTL(3)
2
3
4
6 sysctl - get or set system information
7
9 #include <sys/sysctl.h>
10
11 int
12 sysctl(name, namelen, oldp, *oldlenp, *newp, newlen)
13 int *name;
14 u_int namelen;
15 void *oldp;
16 size_t *oldlenp;
17 void *newp;
18 size_t newlen
19
21 The sysctl function retrieves system information and allows processes
22 with appropriate privileges to set system information. The information
23 available from sysctl consists of integers, strings, and tables.
24 Information may be retrieved and set from the command interface using
25 the sysctl(1) utility.
26
27 Unless explicitly noted below, sysctl returns a consistent snapshot of
28 the data requested. Calls to sysctl are serialized to avoid deadlock.
29
30 The state is described using a ``Management Information Base'' (MIB)
31 style name, listed in name , which is a namelen length array of inte‐
32 gers.
33
34 The information is copied into the buffer specified by oldp . The size
35 of the buffer is given by the location specified by oldlenp before the
36 call, and that location gives the amount of data copied after a suc‐
37 cessful call. If the amount of data available is greater than the size
38 of the buffer supplied, the call supplies as much data as fits in the
39 buffer provided and returns with the error code ENOMEM. If the old
40 value is not desired, oldp and oldlenp should be set to NULL.
41
42 The size of the available data can be determined by calling sysctl with
43 a NULL parameter for oldp. The size of the available data will be
44 returned in the location pointed to by oldlenp. For some operations,
45 the amount of space may change often. For these operations, the system
46 attempts to round up so that the returned size is large enough for a
47 call to return the data shortly thereafter.
48
49 To set a new value, newp is set to point to a buffer of length newlen
50 from which the requested value is to be taken. If a new value is not
51 to be set, newp should be set to NULL and newlen set to 0.
52
53 The top level names are defined with a CTL_ prefix in <sys/sysctl.h>,
54 and are as follows. The next and subsequent levels down are found in
55 the include files listed here, and described in separate sections
56 below.
57
58 Name Next level names Description
59 CTL_DEBUG sys/sysctl.h Debugging
60 CTL_FS sys/sysctl.h File system
61 CTL_HW sys/sysctl.h Generic CPU, I/O
62 CTL_KERN sys/sysctl.h High kernel limits
63 CTL_MACHDEP sys/sysctl.h Machine dependent
64 CTL_NET sys/socket.h Networking
65 CTL_USER sys/sysctl.h User-level
66 CTL_VM vm/vm_param.h Virtual memory
67
68 For example, the following retrieves the maximum number of processes
69 allowed in the system:
70
71 int mib[2], maxproc;
72 size_t len;
73
74 mib[0] = CTL_KERN;
75 mib[1] = KERN_MAXPROC;
76 len = sizeof(maxproc);
77 sysctl(mib, 2, &maxproc, &len, NULL, 0);
78
79 To retrieve the standard search path for the system utilities:
80
81 int mib[2];
82 size_t len;
83 char *p;
84
85 mib[0] = CTL_USER;
86 mib[1] = USER_CS_PATH;
87 sysctl(mib, 2, NULL, &len, NULL, 0);
88 p = malloc(len);
89 sysctl(mib, 2, p, &len, NULL, 0);
90
92 The debugging variables vary from system to system. A debugging vari‐
93 able may be added or deleted without need to recompile sysctl to know
94 about it. Each time it runs, sysctl gets the list of debugging vari‐
95 ables from the kernel and displays their current values. The system
96 defines twenty struct ctldebug variables named debug0 through debug19.
97 They are declared as separate variables so that they can be individu‐
98 ally initialized at the location of their associated variable. The
99 loader prevents multiple use of the same variable by issuing errors if
100 a variable is initialized in more than one place. For example, to
101 export the variable dospecialcheck as a debugging variable, the follow‐
102 ing declaration would be used:
103
104 int dospecialcheck = 1;
105 struct ctldebug debug5 = { "dospecialcheck", &dospecialcheck };
106
108 There are currently no second level names for the file system.
109
111 The string and integer information available for the CTL_HW level is
112 detailed below. The changeable column shows whether a process with
113 appropriate privilege may change the value.
114
115 Second level name Type Changeable
116 HW_MACHINE string no
117 HW_MODEL string no
118 HW_NCPU integer no
119 HW_BYTEORDER integer no
120 HW_PHYSMEM integer no
121 HW_USERMEM integer no
122 HW_PAGESIZE integer no
123
124 HW_MACHINE
125 The machine class.
126
127 HW_MODEL
128 The machine model
129
130 HW_NCPU
131 The number of cpus.
132
133 HW_BYTEORDER
134 The byteorder (3412, 4321, or 1234).
135
136 HW_PHYSMEM
137 The bytes of physical memory.
138
139 HW_USERMEM
140 The bytes of non-kernel memory.
141
142 HW_PAGESIZE
143 The software page size.
144
145
147 The string and integer information available for the CTL_KERN level is
148 detailed below. The changeable column shows whether a process with
149 appropriate privilege may change the value. The types of data cur‐
150 rently available are process information, system inodes, the open file
151 entries, routing table entries, virtual memory statistics, load average
152 history, and clock rate information.
153
154
155 Second level name Type Changeable
156 KERN_ARGMAX integer no
157 KERN_BOOTTIME struct timeval no
158 KERN_CHOWN_RESTRICTED integer no
159 KERN_CLOCKRATE struct clockinfo no
160 KERN_FILE struct file no
161 KERN_HOSTID long yes
162 KERN_HOSTNAME string yes
163 KERN_JOB_CONTROL integer no
164 KERN_MAXFILES integer no
165 KERN_MAXPROC integer no
166 KERN_MAXINODES integer no
167 KERN_MAXTEXTS integer no
168 KERN_NGROUPS integer no
169 KERN_OSRELEASE string no
170 KERN_OSREV integer no
171 KERN_OSTYPE string no
172 KERN_POSIX1 integer no
173 KERN_PROC struct proc no
174 KERN_PROF node not applicable
175 KERN_SAVED_IDS integer no
176 KERN_SECURELVL integer raise only
177 KERN_TEXT struct text no
178 KERN_VERSION string no
179 KERN_INODE struct inode no
180
181 KERN_ARGMAX
182 The maximum bytes of argument to exec(2).
183
184 KERN_BOOTTIME
185 A struct timeval structure is returned. This structure contains
186 the time that the system was booted.
187
188 KERN_CLOCKRATE
189 A struct clockinfo structure is returned. This structure contains
190 the clock, statistics clock and profiling clock frequencies, and
191 the number of micro-seconds per hz tick.
192
193 KERN_FILE
194 Return the entire file table as an array of extended file struc‐
195 tures. Each element of the array contains the kernel address of a
196 file struct inode * followed by the file itself struct file.
197 There can never be more than KERN_MAXFILES inodes returned.
198
199 KERN_HOSTID
200 Get or set the host id.
201
202 KERN_HOSTNAME
203 Get or set the hostname.
204
205 KERN_JOB_CONTROL
206 Return 1 if job control is available on this system, otherwise 0.
207
208 KERN_MAXFILES
209 The maximum number of open files that may be open in the system.
210
211 KERN_MAXPROC
212 The maximum number of simultaneous processes the system will
213 allow.
214
215 KERN_MAXINODES
216 The maximum number of inodes available on the system.
217
218 KERN_MAXTEXTS
219 The maximum number of text structures available on the system.
220
221 KERN_NGROUPS
222 The maximum number of supplemental groups.
223
224 KERN_OSRELEASE
225 The system release string.
226
227 KERN_OSREV
228 The system revision string.
229
230 KERN_OSTYPE
231 The system type string.
232
233 KERN_POSIX1
234 The version of ISO/IEC 9945 (POSIX 1003.1) with which the system
235 attempts to comply.
236
237 KERN_PROC
238 Return the entire process table, or a subset of it. An array of
239 struct kinfo_proc structures is returned, whose size depends on
240 the current number of such objects in the system.
241
242 The third and fourth level names are as follows:
243
244 Third level name Fourth level is:
245 KERN_PROC_ALL None
246 KERN_PROC_PID A process ID
247 KERN_PROC_PGRP A process group
248 KERN_PROC_TTY A tty device
249 KERN_PROC_UID A user ID
250 KERN_PROC_RUID A real user ID
251 KERN_PROF Return kernel profiling information.
252
253 If the kernel is not compiled for profiling, attempts to retrieve
254 any of the KERN_PROF values will fail with EOPNOTSUPP.
255
256 The third level names for the string and integer profiling information
257 is detailed below. The changeable column shows whether a process with
258 appropriate privilege may change the value.
259
260 Third level name Type Changeable
261 GPROF_STATE integer yes
262 GPROF_COUNT u_short[] yes
263 GPROF_FROMS u_short[] yes
264 GPROF_TOS struct tostruct yes
265 GPROF_GMONPARAM struct gmonparam no
266
267 The variables are as follows:
268
269 GPROF_STATE
270 Returns GMON_PROF_ON or GMON_PROF_OFF to show that profiling is
271 running or stopped.
272
273 GPROF_COUNT
274 Array of statistical program counter counts.
275
276 GPROF_FROMS
277 Array indexed by program counter of call-from points.
278
279 GPROF_TOS
280 Array of struct tostruct describing destination of calls and their
281 counts.
282
283 GPROF_GMONPARAM
284 Structure giving the sizes of the above arrays.
285
286 KERN_SAVED_IDS
287 Returns 1 if saved set-group and saved set-user ID is available.
288
289 KERN_SECURELVL
290 The system security level. This level may be raised by processes with
291 appropriate privilege. It may only be lowered by process 1.
292
293 KERN_VERSION
294 The system version string.
295
296 KERN_INODE
297 Return the entire inode table. Note, the inode table is not necessar‐
298 ily a consistent snapshot of the system. The returned data consists of
299 an array whose size depends on the current number of such objects in
300 the system. Each element of the array contains the kernel address of a
301 inode struct inode * followed by the inode itself struct inode. There
302 can never be more than KERN_MAXINODES inodes returned.
303
304 KERN_TEXT
305 Return the entire text table. The returned data consists of an array
306 whose size depends on the current number of such objects active in the
307 system. Each element of the array contains the kernel address of a
308 text struct text * followed by the text structure itself struct text.
309 There can never be more structures than returned by KERN_MAXTEXTS.
310
312 The set of variables defined is architecture dependent. Most architec‐
313 tures define at least the following variables.
314
315 Second level name Type Changeable
316 CPU_CONSDEV dev_t no
317
319 The string and integer information available for the CTL_NET level is
320 detailed below. The changeable column shows whether a process with
321 appropriate privilege may change the value.
322
323 Second level name Type Changeable
324 PF_ROUTE routing messages no
325 PF_INET internet values yes
326
327 PF_ROUTE
328 Return the entire routing table or a subset of it. The data is
329 returned as a sequence of routing messages (see route(4) for the
330 header file, format and meaning). The length of each message is
331 contained in the message header.
332
333 The third level name is a protocol number, which is currently always 0.
334 The fourth level name is an address family, which may be set to 0 to
335 select all address families. The fifth and sixth level names are as
336 follows:
337
338 Fifth level name Sixth level is:
339 NET_RT_FLAGS rtflags
340 NET_RT_DUMP None
341 NET_RT_IFLIST None
342
343 PF_INET
344 Get or set various global information about the internet proto‐
345 cols. The third level name is the protocol. The fourth level
346 name is the variable name. The currently defined protocols and
347 names are:
348
349 Protocol name Variable name Type Changeable
350 ip forwarding integer yes
351 ip redirect integer yes
352 ip ttl integer yes
353 icmp maskrepl integer yes
354 udp checksum integer yes
355
356 The variables are as follows:
357
358 ip.forwarding
359 Returns 1 when IP forwarding is enabled for the host, meaning that
360 the host is acting as a router.
361
362 ip.redirect
363 Returns 1 when ICMP redirects may be sent by the host. This
364 option is ignored unless the host is routing IP packets, and
365 should normally be enabled on all systems.
366
367 ip.ttl
368 The maximum time-to-live (hop count) value for an IP packet
369 sourced by the system. This value applies to normal transport
370 protocols, not to ICMP.
371
372 icmp.maskrepl
373 Returns 1 if ICMP network mask requests are to be answered.
374
375 udp.checksum
376 Returns 1 when UDP checksums are being computed and checked. Dis‐
377 abling UDP checksums is strongly discouraged.
378
379
381 The string and integer information available for the CTL_USER level is
382 detailed below. The changeable column shows whether a process with
383 appropriate privilege may change the value.
384
385 Second level name Type Changeable
386 USER_BC_BASE_MAX integer no
387 USER_BC_DIM_MAX integer no
388 USER_BC_SCALE_MAX integer no
389 USER_BC_STRING_MAX integer no
390 USER_COLL_WEIGHTS_MAX integer no
391 USER_CS_PATH string no
392 USER_EXPR_NEST_MAX integer no
393 USER_LINE_MAX integer no
394 USER_POSIX2_CHAR_TERM integer no
395 USER_POSIX2_C_BIND integer no
396 USER_POSIX2_C_DEV integer no
397 USER_POSIX2_FORT_DEV integer no
398 USER_POSIX2_FORT_RUN integer no
399 USER_POSIX2_LOCALEDEF integer no
400 USER_POSIX2_SW_DEV integer no
401 USER_POSIX2_UPE integer no
402 USER_POSIX2_VERSION integer no
403 USER_RE_DUP_MAX integer no
404 USER_STREAM_MAX integer no
405 USER_TZNAME_MAX integer no
406
407 USER_BC_BASE_MAX
408 The maximum ibase/obase values in the bc(1) utility.
409
410 USER_BC_DIM_MAX
411 The maximum array size in the bc(1) utility.
412
413 USER_BC_SCALE_MAX
414 The maximum scale value in the bc(1) utility.
415
416 USER_BC_STRING_MAX
417 The maximum string length in the bc(1) utility.
418
419 USER_COLL_WEIGHTS_MAX
420 The maximum number of weights that can be assigned to any entry of
421 the LC_COLLATE order keyword in the locale definition file.
422
423 USER_CS_PATH
424 Return a value for the PATH environment variable that finds all
425 the standard utilities.
426
427 USER_EXPR_NEST_MAX
428 The maximum number of expressions that can be nested within paren‐
429 thesis by the expr(1) utility.
430
431 USER_LINE_MAX
432 The maximum length in bytes of a text-processing utility's input
433 line.
434
435 USER_POSIX2_CHAR_TERM
436 Return 1 if the system supports at least one terminal type capable
437 of all operations described in POSIX 1003.2, otherwise 0.
438
439 USER_POSIX2_C_BIND
440 Return 1 if the system's C-language development facilities support
441 the C-Language Bindings Option, otherwise 0.
442
443 USER_POSIX2_C_DEV
444 Return 1 if the system supports the C-Language Development Utili‐
445 ties Option, otherwise 0.
446
447 USER_POSIX2_FORT_DEV
448 Return 1 if the system supports the FORTRAN Development Utilities
449 Option, otherwise 0.
450
451 USER_POSIX2_FORT_RUN
452 Return 1 if the system supports the FORTRAN Runtime Utilities
453 Option, otherwise 0.
454
455 USER_POSIX2_LOCALEDEF
456 Return 1 if the system supports the creation of locales, otherwise
457 0.
458
459 USER_POSIX2_SW_DEV
460 Return 1 if the system supports the Software Development Utilities
461 Option, otherwise 0.
462
463 USER_POSIX2_UPE
464 Return 1 if the system supports the User Portability Utilities
465 Option, otherwise 0.
466
467 USER_POSIX2_VERSION
468 The version of POSIX 1003.2 with which the system attempts to com‐
469 ply.
470
471 USER_RE_DUP_MAX
472 The maximum number of repeated occurrences of a regular expression
473 permitted when using interval notation.
474
475 USER_STREAM_MAX
476 The minimum maximum number of streams that a process may have open
477 at any one time.
478
479 USER_TZNAME_MAX
480 The minimum maximum number of types supported for the name of a
481 timezone.
482
484 The string and integer information available for the CTL_VM level is
485 detailed below. The changeable column shows whether a process with
486 appropriate privilege may change the value.
487
488 Second level name Type Changeable
489 VM_LOADAVG struct loadavg no
490 VM_METER struct vmtotal no
491 VM_SWAPMAP struct map no
492 VM_COREMAP struct map no
493
494 VM_LOADAVG
495 Return the load average history. The returned data consists of a
496 struct loadavg.
497
498 VM_METER
499 Return the system wide virtual memory statistics. The returned
500 data consists of a struct vmtotal.
501
502 VM_SWAPMAP
503 Return the swapmap. The size of this structure is fixed and may
504 be determined by specifying a oldlenp initialized to zero, the
505 kernel will fill in the size of the swapmap.
506
507 VM_COREMAP
508 Same as for swapmap above except that the core allocation map is
509 returned.
510
512 If the call to sysctl is successful, 0 is returned. Otherwise -1 is
513 returned and errno is set appropriately.
514
516 The following errors may be reported:
517
518 EFAULT The buffer name, oldp , newp , or length pointer oldlenp
519 contains an invalid address.
520
521 EINVAL The name array is less than two or greater than CTL_MAX‐
522 NAME.
523
524 EINVAL A non-null newp is given and its specified length in
525 newlen is too large or too small.
526
527 ENOMEM The length pointed to by oldlenp is too short to hold
528 the requested value.
529
530 ENOTDIR The name array specifies an intermediate rather than
531 terminal name.
532
533 EOPNOTSUPP The name array specifies a value that is unknown.
534
535 EPERM An attempt is made to set a read-only value.
536
537 EPERM A process without appropriate privilege attempts to set
538 a value.
539
541 <sys/sysctl.h> definitions for top level identifiers, second level ker‐
542 nel and hardware identifiers, and user level identifiers
543
544 <sys/socket.h> definitions for second level network identifiers
545
546 <sys/gmon.h> definitions for third level profiling identifiers
547
548 <sys/vmparam.h>
549 definitions for second level virtual memory identifiers
550
551 <netinet/in.h> definitions for third level Internet identifiers and
552 fourth level IP identifiers
553
554 <netinet/icmp_var.h>
555 definitions for fourth level ICMP identifiers
556
557 <netinet/udp_var.h>
558 definitions for fourth level UDP identifiers
559
561 sysctl(8)
562
564 The sysctl function first appeared in 4.4BSD.
565
566 The KERN_TEXT, KERN_MAXTEXTS, VM_SWAPMAP, VM_COREMAP options are
567 2.11BSD specific extensions to the 4.4BSD sysctl implmentation.
568
569 Having KERN_FILE return the address of the file structure before the
570 actual struct file is a 2.11BSD enhancement. The inode (vnode under
571 4.4) table was handled this way.
572
573
574
5754th Berkeley Distribution January 13, 1995 SYSCTL(3)