1.\" Copyright (c) 1993 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)sysctl.3 6.4 (Berkeley) 05/10/93 7.\" 8.Dd "" 9.Dt SYSCTL 3 10.Os 11.Sh NAME 12.Nm sysctl 13.Nd get or set system information 14.Sh SYNOPSIS 15.Fd #include <sys/sysctl.h> 16.Ft int 17.Fn sysctl "int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" 18.Sh DESCRIPTION 19The 20.Nm sysctl 21function retrieves system information and allows processes with 22appropriate privileges to set system information. 23The information available from 24.Nm sysctl 25consists of integers, strings, and tables. 26Unless explicitly noted below, 27.Nm sysctl 28returns a consistent snapshot of the data requested 29Information may be retrieved and set from the command interface 30using the 31.Xr sysctl 1 32utility. 33.Pp 34The state is described using a ``Management Information Base'' (MIB) 35style name, listed in 36.Fa name , 37which is a 38.Fa namelen 39length array of integers. 40.Pp 41The information is copied into the buffer specified by 42.Fa oldp . 43The size of the buffer is given by the location specified by 44.Fa oldlenp 45before the call, 46and that location gives the amount of data copied after a successful call. 47If the amount of data available is greater 48than the size of the buffer supplied, 49the call supplies as much data as fits in the buffer provided 50and returns with the error code EINVAL. 51If the old value is not desired, 52.Fa oldp 53and 54.Fa oldlenp 55should be set to NULL. 56.Pp 57The size of the available data can be determined by calling 58.Nm sysctl 59with a NULL parameter for 60.Fa oldp . 61The size of the available data be returned in the location pointed to by 62.Fa oldlenp . 63For some operations, the amount of space may change often; 64the system attempts to round up so that the returned size is 65large enough for a call to return the data shortly thereafter. 66.Pp 67To set a new value, 68.Fa newp 69is set to point to a buffer of length 70.Fa newlen 71from which the requested value is to be taken. 72If a new value is not to be set, 73.Fa newp 74should be set to NULL and 75.Fa newlen 76set to 0. 77.Pp 78The top level names are defined with a CTL_ prefix in 79.Pa <sys/sysctl.h> , 80and are as follows. 81The next and subsequent levels down are found in the include files 82listed here, and described in separate sections below. 83.Pp 84.Bl -column CTLXMACHDEPXXX "Next level namesXXX" -offset indent 85.It Sy Pa Name Next level names Description 86.It CTL\_DEBUG sys/sysctl.h Debugging 87.It CTL\_FS sys/sysctl.h File system 88.It CTL\_HW sys/sysctl.h Generic CPU, I/O 89.It CTL\_KERN sys/sysctl.h High kernel: processes, limits 90.It CTL\_MACHDEP sys/sysctl.h Machine dependent 91.It CTL\_NET sys/socket.h Networking 92.It CTL\_USER sys/sysctl.h User-level 93.It CTL\_VM vm/vm_param.h Virtual memory 94.El 95.Pp 96For example, the following retrieves the maximum number of processes allowed 97in the system: 98.Bd -literal -offset indent -compact 99int mib[2], maxproc; 100size_t len; 101.sp 102mib[0] = CTL_KERN; 103mib[1] = KERN_MAXPROC; 104len = sizeof(maxproc); 105sysctl(mib, 2, &maxproc, &len, NULL, 0); 106.Ed 107.sp 108To retrieve the standard search path for the system utilities: 109.Bd -literal -offset indent -compact 110int mib[2]; 111size_t len; 112char *p; 113.sp 114mib[0] = CTL_USER; 115mib[1] = USER_CS_PATH; 116sysctl(mib, 2, NULL, &len, NULL, 0); 117p = malloc(len); 118sysctl(mib, 2, p, &len, NULL, 0); 119.Ed 120.Sh RETURN VALUES 121If the call to 122.Nm sysctl 123is successful, 0 is returned. 124Otherwise \-1 is returned and 125.Va errno 126is set appropriately. 127.Sh CTL_DEBUG 128There are currently no second level names for the debugging interface. 129.Sh CTL_FS 130There are currently no second level names for the file system. 131.Sh CTL_HW 132The string and integer information available for the CTL_KERN level 133is detailed below. 134The changeable column shows whether a process with appropriate 135privilege may change the value. 136.Bl -column "Second level nameXXX" integerXXX -offset indent 137.It Sy Pa Second level name Type Changeable 138.It HW\_MACHINE string no 139.It HW\_MODEL string no 140.It HW\_NCPU integer no 141.It HW\_BYTEORDER integer no 142.It HW\_PHYSMEM integer no 143.It HW\_USERMEM integer no 144.It HW\_PAGESIZE integer no 145.\".It HW\_DISKNAMES integer no 146.\".It HW\_DISKSTATS integer no 147.El 148.Pp 149.Bl -tag -width "123456" 150.It Li HW_MACHINE 151Return the machine class. 152.It Li HW_MODEL 153Return the machine model 154.It Li HW_NCPU 155Return the number of cpus. 156.It Li HW_BYTEORDER 157Return the byteorder (4,321, or 1,234). 158.It Li HW_PHYSMEM 159Return the bytes of physical memory. 160.It Li HW_USERMEM 161Return the bytes of non-kernel memory. 162.It Li HW_PAGESIZE 163Return the software page size. 164.\".It Fa HW_DISKNAMES 165.\".It Fa HW_DISKSTATS 166.El 167.Sh CTL_KERN 168The string and integer information available for the CTL_KERN level 169is detailed below. 170The changeable column shows whether a process with appropriate 171privilege may change the value. 172The types of data currently available are process information, 173system vnodes, the open file entries, routing table entries, 174virtual memory statistics, load average history, and clock rate 175information. 176Consistency in the kernel tables is obtained by locking the destination 177buffer into memory so that the data may be copied out without blocking. 178Calls are serialized to avoid deadlock. 179.Bl -column "KERNXCHOWNXRESTRICTEDXXX" "struct clockrateXXX" -offset indent 180.It Sy Pa Second level name Type Changeable 181.It KERN\_ARGMAX integer no 182.It KERN\_CHOWN\_RESTRICTED integer no 183.It KERN\_CLOCKRATE struct clockinfo yes 184.It KERN\_FILE struct file yes 185.It KERN\_HOSTID integer yes 186.It KERN\_HOSTNAME string yes 187.It KERN\_JOB\_CONTROL integer no 188.It KERN\_LINK\_MAX integer no 189.It KERN\_MAXFILES integer yes 190.It KERN\_MAXPROC integer yes 191.It KERN\_MAXVNODES integer no 192.It KERN\_MAX\_CANON integer no 193.It KERN\_MAX\_INPUT integer no 194.It KERN\_NAME\_MAX integer no 195.It KERN\_NGROUPS integer no 196.It KERN\_NO\_TRUNC integer no 197.It KERN\_OSRELEASE string no 198.It KERN\_OSREV integer no 199.It KERN\_OSTYPE string no 200.It KERN\_PATH\_MAX integer no 201.It KERN\_PIPE\_BUF integer no 202.It KERN\_POSIX1 integer no 203.It KERN\_PROC struct proc yes 204.It KERN\_PROF node yes 205.It KERN\_SAVED\_IDS integer no 206.It KERN\_SECURELVL integer raise only 207.It KERN\_VDISABLE integer no 208.It KERN\_VERSION string no 209.It KERN\_VNODE struct vnode yes 210.El 211.Pp 212.Bl -tag -width "123456" 213.It Li KERN_ARGMAX 214Maximum bytes of argument to exec. 215.It Li KERN_CHOWN_RESTRICTED 216Return 1 if appropriate privileges are required for the 217.Xr chown 2 218system call, otherwise 0. 219.It Li KERN_CLOCKRATE 220A 221.Ns ( Li struct clockinfo Ns ) 222structure is returned. 223This structure contains the clock, statistics clock and profiling clock 224frequencies, and the number of micro-seconds per hz tick. 225.It Li KERN_FILE 226Return the entire file table. 227The returned data consists of a single 228.Ns ( Li struct filehead Ns ) 229followed by an array of 230.Ns ( Li struct file Ns ) , 231whose size depends on the current number of such objects in the system. 232.It Li KERN_HOSTID 233Return the host id. 234.It Li KERN_HOSTNAME 235Return the hostname. 236.It Li KERN_JOB_CONTROL 237Return 1 if job control is available on this system, otherwise 0. 238.It Li KERN_LINK_MAX 239Return the maximum file link count. 240.It Li KERN_MAXFILES 241Return the maximum number of open files a process may have. 242.It Li KERN_MAXPROC 243Return the maximum number of simultaneous processes a user may have. 244.It Li KERN_MAXVNODES 245Return the maximum number of vnodes available on the system. 246.It Li KERN_MAX_CANON 247Return the maximum number of bytes in terminal canonical input line. 248.It Li KERN_MAX_INPUT 249Return the minimum number of bytes for which space is available in 250a terminal input queue. 251.It Li KERN_NAME_MAX 252Maximum number of bytes in a file name. 253.It Li KERN_NGROUPS 254Maximum number of supplemental groups. 255.It Li KERN_NO_TRUNC 256Return 1 if too long pathnames are truncated. 257.It Li KERN_OSRELEASE 258Return the system release string. 259.It Li KERN_OSREV 260Return the system revision string. 261.It Li KERN_OSTYPE 262Return the system type string. 263.It Li KERN_PATH_MAX 264Maximum number of bytes in a pathname. 265.It Li KERN_PIPE_BUF 266Maximum number of bytes which will be written atomically to a pipe. 267.It Li KERN_POSIX1 268Return the POSIX 1003.1 version with which the system attempts to comply. 269.It Li KERN_PROC 270Return the entire process table, or a subset of it. 271An array of 272.Ns ( Li struct kinfo_proc Ns ) 273structures is returned, 274whose size depends on the current number of such objects in the system. 275The third and fourth level names are as follows: 276.Bl -column "Third level nameXXX" "Fourth level is:XXX" -offset indent 277.It Pa Third level name Fourth level is: 278.It KERN\_PROC\_ALL None 279.It KERN\_PROC\_PID A process ID 280.It KERN\_PROC\_PGRP A process group 281.It KERN\_PROC\_TTY A tty device 282.It KERN\_PROC\_UID A user ID 283.It KERN\_PROC\_RUID A real user ID 284.El 285.It Li KERN_PROF 286Return kernel profiling information. 287The only currently available third level name is GPROF_STATE, which 288returns 1 if the kernel was compiled for profiling, and 0 if it was 289not. 290.It Li KERN_SAVED_IDS 291Returns 1 if saved set-group and saved set-user ID is available. 292.It Li KERN_SECURELVL 293Returns the system security level. 294This level may be raised by processes with appropriate privilege. 295.It Li KERN_VDISABLE 296Returns the terminal character disabling value. 297.It Li KERN_VERSION 298Return the system version string. 299.It Li KERN_VNODE 300Return the entire vnode table. 301(Note, the vnode table is not necessarily a consistent snapshot of 302the system.) 303The returned data consists of an array whose size depends on the 304current number of such objects in the system. 305Each element of the array contains the kernel address of a vnode 306.Ns ( Li struct vnode * Ns ) 307followed by the vnode itself 308.Ns ( Li struct vnode Ns ) . 309.El 310.Sh CTL_MACHDEP 311There are currently no second level names for the machine dependent 312interface. 313.Sh CTL_NET 314The string and integer information available for the CTL_NET level 315is detailed below. 316The changeable column shows whether a process with appropriate 317privilege may change the value. 318.Bl -column "Second level nameXXX" "routine messagesXXX" -offset indent 319.It Sy Pa Second level name Type Changeable 320.It PF\_ROUTE routine messages no 321.El 322.Pp 323.Bl -tag -width "123456" 324.It Li PF_ROUTE 325Return the entire routing table or a subset of it. 326The data is returned as a sequence of routing messages (see 327.Xr route 4 328for the header file, format and meaning). 329The length of each message is contained in the message header. 330.Pp 331The third level name is a protocol number, which is currently always 0. 332The fourth level name is an address family, which may be set to 0 to 333select all address families. 334The fifth and sixth level names are as follows: 335.Bl -column "Fifth level nameXXX" "Sixth level is:XXX" -offset indent 336.It Pa Fifth level name Sixth level is: 337.It NET\_RT\_FLAGS rtflags 338.It NET\_RT\_DUMP None 339.It NET\_RT\_IFLIST None 340.El 341.Sh CTL_USER 342The string and integer information available for the CTL_USER level 343is detailed below. 344The changeable column shows whether a process with appropriate 345privilege may change the value. 346.Bl -column "Second level nameXXX" "integerXXX" -offset indent 347.It Sy Pa Second level name Type Changeable 348.It USER\_BC\_BASE\_MAX integer no 349.It USER\_BC\_DIM\_MAX integer no 350.It USER\_BC\_SCALE\_MAX integer no 351.It USER\_BC\_STRING\_MAX integer no 352.It USER\_COLL\_WEIGHTS\_MAX integer no 353.It USER\_CS\_PATH string no 354.It USER\_EXPR\_NEST\_MAX integer no 355.It USER\_LINE\_MAX integer no 356.It USER\_POSIX2\_CHAR\_TERM integer no 357.It USER\_POSIX2\_C\_BIND integer no 358.It USER\_POSIX2\_C\_DEV integer no 359.It USER\_POSIX2\_FORT\_DEV integer no 360.It USER\_POSIX2\_FORT\_RUN integer no 361.It USER\_POSIX2\_LOCALEDEF integer no 362.It USER\_POSIX2\_SW\_DEV integer no 363.It USER\_POSIX2\_UPE integer no 364.It USER\_POSIX2\_VERSION integer no 365.It USER\_RE\_DUP\_MAX integer no 366.El 367.Bl -tag -width "123456" 368.Pp 369.It Li USER_BC_BASE_MAX 370Return the maximum ibase/obase values in the 371.Xr bc 1 372utility 373.It Li USER_BC_DIM_MAX 374Return the maximum array size in the 375.Xr bc 1 376utility. 377.It Li USER_BC_SCALE_MAX 378Return the maximum scale value in the 379.Xr bc 1 380utility. 381.It Li USER_BC_STRING_MAX 382Return the maximum string length in the 383.Xr bc 1 384utility. 385.It Li USER_COLL_WEIGHTS_MAX 386Return the maximum number of weights that can be assigned to any entry of 387the LC_COLLATE order keyword in the locale definition file. 388.It Li USER_CS_PATH 389Return a value for the 390.Ev PATH 391environment variable that finds all of the standard utilities. 392.It Li USER_EXPR_NEST_MAX 393Return the maximum number of expressions that can be nested within 394parenthesis by the 395.Xr expr 1 396utility. 397.It Li USER_LINE_MAX 398Return the maximum length in bytes of a text-processing utility's input 399line. 400.It Li USER_POSIX2_CHAR_TERM 401Return 1 if the system supports at least one terminal type capable of 402all operations described in POSIX 1003.2, otherwise 0. 403.It Li USER_POSIX2_C_BIND 404Return 1 if the system's C-language development facilities support the 405C-Language Bindings Option, otherwise 0. 406.It Li USER_POSIX2_C_DEV 407Return 1 if the system supports the C-Language Development Utilities Option, 408otherwise 0. 409.It Li USER_POSIX2_FORT_DEV 410Return 1 if the system supports the FORTRAN Development Utilities Option, 411otherwise 0. 412.It Li USER_POSIX2_FORT_RUN 413Return 1 if the system supports the FORTRAN Runtime Utilities Option, 414otherwise 0. 415.It Li USER_POSIX2_LOCALEDEF 416Return 1 if the system supports the creation of locales, otherwise 0. 417.It Li USER_POSIX2_SW_DEV 418Return 1 if the system supports the Software Development Utilities Option, 419otherwise 0. 420.It Li USER_POSIX2_UPE 421Return 1 if the system supports the User Portability Utilities Option, 422otherwise 0. 423.It Li USER_POSIX2_VERSION 424Return the POSIX 1003.2 version with which the system attempts to comply. 425.It Li USER_RE_DUP_MAX 426Return the maximum number of repeated occurrences of a regular expression 427permitted when using interval notation. 428.El 429.Sh CTL_VM 430The string and integer information available for the CTL_VM level 431is detailed below. 432The changeable column shows whether a process with appropriate 433privilege may change the value. 434.Bl -column "Second level nameXXX" "struct loadavgXXX" -offset indent 435.It Sy Pa Second level name Type Changeable 436.It VM\_LOADAVG struct loadavg no 437.It VM\_METER struct vmtotal no 438.El 439.Pp 440.Bl -tag -width "123456" 441.It Li VM_LOADAVG 442Return the load average history. 443The returned data consists of a 444.Ns ( Li struct loadavg Ns ) . 445.It Li VM_METER 446Return the system wide virtual memory statistics. 447The returned data consists of a 448.Ns ( Li struct vmtotal Ns ) . 449.El 450.Sh ERRORS 451The following errors may be reported: 452.Bl -tag -width Er 453.It Bq Er EFAULT 454The buffer 455.Fa name , 456.Fa oldp , 457.Fa newp , 458or length pointer 459.Fa oldlenp 460contains an invalid address. 461.It Bq Er EINVAL 462The 463.Fa name 464array is less than two or greater than CTL_MAXNAME. 465.It Bq Er EINVAL 466A non-null 467.Fa newp 468is given and its specified length in 469.Fa newlen 470is too large or too small. 471.It Bq Er ENOMEM 472The length pointed to by 473.Fa oldlenp 474is too short to hold the requested value. 475.It Bq Er ENOTDIR 476The 477.Fa name 478array specifies an intermediate rather than terminal name. 479.It Bq Er EOPNOTSUPP 480The 481.Fa name 482array specifies a value that is unknown. 483.It Bq Er EPERM 484An attempt is made to set a read-only value. 485.It Bq Er EPERM 486A process without appropriate privilege attempts to set a value. 487.El 488.Sh FILES 489.Bl -tag -width <vm/vmXparam.h> -compact 490.It Pa <sys/sysctl.h> 491definitions for top level identifiers, second level kernel and hardware 492identifiers, user level identifiers 493.It Pa <sys/socket.h> 494definitions for second level network identifiers 495.It Pa <vm/vm_param.h> 496definitions for second level virtual memory identifiers 497.El 498.Sh SEE ALSO 499.Xr sysctl 8 500.Sh HISTORY 501The 502.Nm sysctl 503function first appeared in 4.4BSD. 504