1.\" Copyright (c) 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)sysctl.3 8.3 (Berkeley) 05/03/95 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. 26Information may be retrieved and set from the command interface 27using the 28.Xr sysctl 1 29utility. 30.Pp 31Unless explicitly noted below, 32.Nm sysctl 33returns a consistent snapshot of the data requested. 34Consistency is obtained by locking the destination 35buffer into memory so that the data may be copied out without blocking. 36Calls to 37.Nm sysctl 38are serialized to avoid deadlock. 39.Pp 40The state is described using a ``Management Information Base'' (MIB) 41style name, listed in 42.Fa name , 43which is a 44.Fa namelen 45length array of integers. 46.Pp 47The information is copied into the buffer specified by 48.Fa oldp . 49The size of the buffer is given by the location specified by 50.Fa oldlenp 51before the call, 52and that location gives the amount of data copied after a successful call. 53If the amount of data available is greater 54than the size of the buffer supplied, 55the call supplies as much data as fits in the buffer provided 56and returns with the error code ENOMEM. 57If the old value is not desired, 58.Fa oldp 59and 60.Fa oldlenp 61should be set to NULL. 62.Pp 63The size of the available data can be determined by calling 64.Nm sysctl 65with a NULL parameter for 66.Fa oldp . 67The size of the available data will be returned in the location pointed to by 68.Fa oldlenp . 69For some operations, the amount of space may change often. 70For these operations, 71the system attempts to round up so that the returned size is 72large enough for a call to return the data shortly thereafter. 73.Pp 74To set a new value, 75.Fa newp 76is set to point to a buffer of length 77.Fa newlen 78from which the requested value is to be taken. 79If a new value is not to be set, 80.Fa newp 81should be set to NULL and 82.Fa newlen 83set to 0. 84.Pp 85The top level names are defined with a CTL_ prefix in 86.Pa <sys/sysctl.h> , 87and are as follows. 88The next and subsequent levels down are found in the include files 89listed here, and described in separate sections below. 90.Pp 91.Bl -column CTLXMACHDEPXXX "Next level namesXXXXXX" -offset indent 92.It Sy Pa Name Next level names Description 93.It CTL\_DEBUG sys/sysctl.h Debugging 94.It CTL\_FS sys/sysctl.h File system 95.It CTL\_HW sys/sysctl.h Generic CPU, I/O 96.It CTL\_KERN sys/sysctl.h High kernel limits 97.It CTL\_MACHDEP sys/sysctl.h Machine dependent 98.It CTL\_NET sys/socket.h Networking 99.It CTL\_USER sys/sysctl.h User-level 100.It CTL\_VM vm/vm_param.h Virtual memory 101.El 102.Pp 103For example, the following retrieves the maximum number of processes allowed 104in the system: 105.Bd -literal -offset indent -compact 106int mib[2], maxproc; 107size_t len; 108.sp 109mib[0] = CTL_KERN; 110mib[1] = KERN_MAXPROC; 111len = sizeof(maxproc); 112sysctl(mib, 2, &maxproc, &len, NULL, 0); 113.Ed 114.sp 115To retrieve the standard search path for the system utilities: 116.Bd -literal -offset indent -compact 117int mib[2]; 118size_t len; 119char *p; 120.sp 121mib[0] = CTL_USER; 122mib[1] = USER_CS_PATH; 123sysctl(mib, 2, NULL, &len, NULL, 0); 124p = malloc(len); 125sysctl(mib, 2, p, &len, NULL, 0); 126.Ed 127.Sh CTL_DEBUG 128The debugging variables vary from system to system. 129A debugging variable may be added or deleted without need to recompile 130.Nm sysctl 131to know about it. 132Each time it runs, 133.Nm sysctl 134gets the list of debugging variables from the kernel and 135displays their current values. 136The system defines twenty 137.Ns ( Va struct ctldebug ) 138variables named 139.Nm debug0 140through 141.Nm debug19 . 142They are declared as separate variables so that they can be 143individually initialized at the location of their associated variable. 144The loader prevents multiple use of the same variable by issuing errors 145if a variable is initialized in more than one place. 146For example, to export the variable 147.Nm dospecialcheck 148as a debugging variable, the following declaration would be used: 149.Bd -literal -offset indent -compact 150int dospecialcheck = 1; 151struct ctldebug debug5 = { "dospecialcheck", &dospecialcheck }; 152.Ed 153.Sh CTL_FS 154There are currently no second level names for the file system. 155.Sh CTL_HW 156The string and integer information available for the CTL_HW level 157is detailed below. 158The changeable column shows whether a process with appropriate 159privilege may change the value. 160.Bl -column "Second level nameXXXXXX" integerXXX -offset indent 161.It Sy Pa Second level name Type Changeable 162.It HW\_MACHINE string no 163.It HW\_MODEL string no 164.It HW\_NCPU integer no 165.It HW\_BYTEORDER integer no 166.It HW\_PHYSMEM integer no 167.It HW\_USERMEM integer no 168.It HW\_PAGESIZE integer no 169.\".It HW\_DISKNAMES integer no 170.\".It HW\_DISKSTATS integer no 171.El 172.Pp 173.Bl -tag -width "123456" 174.It Li HW_MACHINE 175The machine class. 176.It Li HW_MODEL 177The machine model 178.It Li HW_NCPU 179The number of cpus. 180.ne 1i 181.It Li HW_BYTEORDER 182The byteorder (4,321, or 1,234). 183.It Li HW_PHYSMEM 184The bytes of physical memory. 185.It Li HW_USERMEM 186The bytes of non-kernel memory. 187.It Li HW_PAGESIZE 188The software page size. 189.\".It Fa HW_DISKNAMES 190.\".It Fa HW_DISKSTATS 191.El 192.Sh CTL_KERN 193The string and integer information available for the CTL_KERN level 194is detailed below. 195The changeable column shows whether a process with appropriate 196privilege may change the value. 197The types of data currently available are process information, 198system vnodes, the open file entries, routing table entries, 199virtual memory statistics, load average history, and clock rate 200information. 201.Bl -column "KERNXCHOWNXRESTRICTEDXXX" "struct clockrateXXX" -offset indent 202.It Sy Pa Second level name Type Changeable 203.It KERN\_ARGMAX integer no 204.It KERN\_BOOTTIME struct timeval no 205.It KERN\_CHOWN\_RESTRICTED integer no 206.It KERN\_CLOCKRATE struct clockinfo no 207.It KERN\_FILE struct file no 208.It KERN\_HOSTID integer yes 209.It KERN\_HOSTNAME string yes 210.It KERN\_JOB\_CONTROL integer no 211.It KERN\_LINK\_MAX integer no 212.It KERN\_MAXFILES integer yes 213.It KERN\_MAXPROC integer yes 214.It KERN\_MAXVNODES integer yes 215.It KERN\_MAX\_CANON integer no 216.It KERN\_MAX\_INPUT integer no 217.It KERN\_NAME\_MAX integer no 218.It KERN\_NGROUPS integer no 219.It KERN\_NO\_TRUNC integer no 220.It KERN\_OSRELEASE string no 221.It KERN\_OSREV integer no 222.It KERN\_OSTYPE string no 223.It KERN\_PATH\_MAX integer no 224.It KERN\_PIPE\_BUF integer no 225.It KERN\_POSIX1 integer no 226.It KERN\_PROC struct proc no 227.It KERN\_PROF node not applicable 228.It KERN\_SAVED\_IDS integer no 229.It KERN\_SECURELVL integer raise only 230.It KERN\_VDISABLE integer no 231.It KERN\_VERSION string no 232.It KERN\_VNODE struct vnode no 233.El 234.ne 1i 235.Pp 236.Bl -tag -width "123456" 237.It Li KERN_ARGMAX 238The maximum bytes of argument to 239.Xr exec 2 . 240.It Li KERN_BOOTTIME 241A 242.Va struct timeval 243structure is returned. 244This structure contains the time that the system was booted. 245.It Li KERN_CHOWN_RESTRICTED 246Return 1 if appropriate privileges are required for the 247.Xr chown 2 248system call, otherwise 0. 249.It Li KERN_CLOCKRATE 250A 251.Va struct clockinfo 252structure is returned. 253This structure contains the clock, statistics clock and profiling clock 254frequencies, and the number of micro-seconds per hz tick. 255.It Li KERN_FILE 256Return the entire file table. 257The returned data consists of a single 258.Va struct filehead 259followed by an array of 260.Va struct file , 261whose size depends on the current number of such objects in the system. 262.It Li KERN_HOSTID 263Get or set the host id. 264.It Li KERN_HOSTNAME 265Get or set the hostname. 266.It Li KERN_JOB_CONTROL 267Return 1 if job control is available on this system, otherwise 0. 268.It Li KERN_LINK_MAX 269The maximum file link count. 270.It Li KERN_MAXFILES 271The maximum number of open files that may be open in the system. 272.It Li KERN_MAXPROC 273The maximum number of simultaneous processes the system will allow. 274.It Li KERN_MAXVNODES 275The maximum number of vnodes available on the system. 276.It Li KERN_MAX_CANON 277The maximum number of bytes in terminal canonical input line. 278.It Li KERN_MAX_INPUT 279The minimum maximum number of bytes for which space is available in 280a terminal input queue. 281.It Li KERN_NAME_MAX 282The maximum number of bytes in a file name. 283.It Li KERN_NGROUPS 284The maximum number of supplemental groups. 285.It Li KERN_NO_TRUNC 286Return 1 if file names longer than KERN_NAME_MAX are truncated. 287.It Li KERN_OSRELEASE 288The system release string. 289.It Li KERN_OSREV 290The system revision string. 291.It Li KERN_OSTYPE 292The system type string. 293.It Li KERN_PATH_MAX 294The maximum number of bytes in a pathname. 295.It Li KERN_PIPE_BUF 296The maximum number of bytes which will be written atomically to a pipe. 297.It Li KERN_POSIX1 298The version of ISO/IEC 9945 (POSIX 1003.1) with which the system 299attempts to comply. 300.It Li KERN_PROC 301Return the entire process table, or a subset of it. 302An array of 303.Va struct kinfo_proc 304structures is returned, 305whose size depends on the current number of such objects in the system. 306The third and fourth level names are as follows: 307.Bl -column "Third level nameXXXXXX" "Fourth level is:XXXXXX" -offset indent 308.It Pa Third level name Fourth level is: 309.It KERN\_PROC\_ALL None 310.It KERN\_PROC\_PID A process ID 311.It KERN\_PROC\_PGRP A process group 312.It KERN\_PROC\_TTY A tty device 313.It KERN\_PROC\_UID A user ID 314.It KERN\_PROC\_RUID A real user ID 315.El 316.It Li KERN_PROF 317Return profiling information about the kernel. 318If the kernel is not compiled for profiling, 319attempts to retrieve any of the KERN_PROF values will 320fail with EOPNOTSUPP. 321The third level names for the string and integer profiling information 322is detailed below. 323The changeable column shows whether a process with appropriate 324privilege may change the value. 325.Bl -column "GPROFXGMONPARAMXXX" "struct gmonparamXXX" -offset indent 326.It Sy Pa Third level name Type Changeable 327.It GPROF\_STATE integer yes 328.It GPROF\_COUNT u_short[\|] yes 329.It GPROF\_FROMS u_short[\|] yes 330.It GPROF\_TOS struct tostruct yes 331.It GPROF\_GMONPARAM struct gmonparam no 332.El 333.Pp 334The variables are as follows: 335.Bl -tag -width "123456" 336.It Li GPROF_STATE 337Returns GMON_PROF_ON or GMON_PROF_OFF to show that profiling 338is running or stopped. 339.It Li GPROF_COUNT 340Array of statistical program counter counts. 341.It Li GPROF_FROMS 342Array indexed by program counter of call-from points. 343.It Li GPROF_TOS 344Array of 345.Va struct tostruct 346describing destination of calls and their counts. 347.It Li GPROF_GMONPARAM 348Structure giving the sizes of the above arrays. 349.El 350.ne 1i 351.It Li KERN_SAVED_IDS 352Returns 1 if saved set-group and saved set-user ID is available. 353.It Li KERN_SECURELVL 354The system security level. 355This level may be raised by processes with appropriate privilege. 356It may only be lowered by process 1. 357.It Li KERN_VDISABLE 358Returns the terminal character disabling value. 359.It Li KERN_VERSION 360The system version string. 361.It Li KERN_VNODE 362Return the entire vnode table. 363Note, the vnode table is not necessarily a consistent snapshot of 364the system. 365The returned data consists of an array whose size depends on the 366current number of such objects in the system. 367Each element of the array contains the kernel address of a vnode 368.Va struct vnode * 369followed by the vnode itself 370.Va struct vnode . 371.El 372.Sh CTL_MACHDEP 373The set of variables defined is architecture dependent. 374Most architectures define at least the following variables. 375.Bl -column "CONSOLE_DEVICEXXX" "integerXXX" -offset indent 376.It Sy Pa Second level name Type Changeable 377.It Li CPU_CONSDEV dev_t no 378.El 379.Sh CTL_NET 380The string and integer information available for the CTL_NET level 381is detailed below. 382The changeable column shows whether a process with appropriate 383privilege may change the value. 384.Bl -column "Second level nameXXXXXX" "routing messagesXXX" -offset indent 385.It Sy Pa Second level name Type Changeable 386.It PF\_ROUTE routing messages no 387.It PF\_INET internet values yes 388.El 389.Pp 390.Bl -tag -width "123456" 391.It Li PF_ROUTE 392Return the entire routing table or a subset of it. 393The data is returned as a sequence of routing messages (see 394.Xr route 4 395for the header file, format and meaning). 396The length of each message is contained in the message header. 397.Pp 398The third level name is a protocol number, which is currently always 0. 399The fourth level name is an address family, which may be set to 0 to 400select all address families. 401The fifth and sixth level names are as follows: 402.Bl -column "Fifth level nameXXXXXX" "Sixth level is:XXX" -offset indent 403.It Pa Fifth level name Sixth level is: 404.It NET\_RT\_FLAGS rtflags 405.It NET\_RT\_DUMP None 406.It NET\_RT\_IFLIST None 407.El 408.It Li PF_INET 409Get or set various global information about the internet protocols. 410The third level name is the protocol. 411The fourth level name is the variable name. 412The currently defined protocols and names are: 413.ne 1i 414.Bl -column "Protocol nameXXXXXX" "Variable nameXXX" "integerXXX" -offset indent 415.It Pa Protocol name Variable name Type Changeable 416.It ip forwarding integer yes 417.It ip redirect integer yes 418.It ip ttl integer yes 419.It icmp maskrepl integer yes 420.It udp checksum integer yes 421.El 422.Pp 423The variables are as follows: 424.Bl -tag -width "123456" 425.It Li ip.forwarding 426Returns 1 when IP forwarding is enabled for the host, 427meaning that the host is acting as a router. 428.It Li ip.redirect 429Returns 1 when ICMP redirects may be sent by the host. 430This option is ignored unless the host is routing IP packets, 431and should normally be enabled on all systems. 432.It Li ip.ttl 433The maximum time-to-live (hop count) value for an IP packet sourced by 434the system. 435This value applies to normal transport protocols, not to ICMP. 436.It Li icmp.maskrepl 437Returns 1 if ICMP network mask requests are to be answered. 438.It Li udp.checksum 439Returns 1 when UDP checksums are being computed and checked. 440Disabling UDP checksums is strongly discouraged. 441.El 442.Sh CTL_USER 443The string and integer information available for the CTL_USER level 444is detailed below. 445The changeable column shows whether a process with appropriate 446privilege may change the value. 447.Bl -column "USER_COLL_WEIGHTS_MAXXXX" "integerXXX" -offset indent 448.It Sy Pa Second level name Type Changeable 449.It USER\_BC\_BASE\_MAX integer no 450.It USER\_BC\_DIM\_MAX integer no 451.It USER\_BC\_SCALE\_MAX integer no 452.It USER\_BC\_STRING\_MAX integer no 453.It USER\_COLL\_WEIGHTS\_MAX integer no 454.It USER\_CS\_PATH string no 455.It USER\_EXPR\_NEST\_MAX integer no 456.It USER\_LINE\_MAX integer no 457.It USER\_POSIX2\_CHAR\_TERM integer no 458.It USER\_POSIX2\_C\_BIND integer no 459.It USER\_POSIX2\_C\_DEV integer no 460.It USER\_POSIX2\_FORT\_DEV integer no 461.It USER\_POSIX2\_FORT\_RUN integer no 462.It USER\_POSIX2\_LOCALEDEF integer no 463.It USER\_POSIX2\_SW\_DEV integer no 464.It USER\_POSIX2\_UPE integer no 465.It USER\_POSIX2\_VERSION integer no 466.It USER\_RE\_DUP\_MAX integer no 467.It USER\_STREAM\_MAX integer no 468.It USER\_TZNAME\_MAX integer no 469.El 470.Bl -tag -width "123456" 471.Pp 472.It Li USER_BC_BASE_MAX 473The maximum ibase/obase values in the 474.Xr bc 1 475utility. 476.It Li USER_BC_DIM_MAX 477The maximum array size in the 478.Xr bc 1 479utility. 480.It Li USER_BC_SCALE_MAX 481The maximum scale value in the 482.Xr bc 1 483utility. 484.It Li USER_BC_STRING_MAX 485The maximum string length in the 486.Xr bc 1 487utility. 488.It Li USER_COLL_WEIGHTS_MAX 489The maximum number of weights that can be assigned to any entry of 490the LC_COLLATE order keyword in the locale definition file. 491.It Li USER_CS_PATH 492Return a value for the 493.Ev PATH 494environment variable that finds all the standard utilities. 495.It Li USER_EXPR_NEST_MAX 496The maximum number of expressions that can be nested within 497parenthesis by the 498.Xr expr 1 499utility. 500.It Li USER_LINE_MAX 501The maximum length in bytes of a text-processing utility's input 502line. 503.It Li USER_POSIX2_CHAR_TERM 504Return 1 if the system supports at least one terminal type capable of 505all operations described in POSIX 1003.2, otherwise 0. 506.It Li USER_POSIX2_C_BIND 507Return 1 if the system's C-language development facilities support the 508C-Language Bindings Option, otherwise 0. 509.It Li USER_POSIX2_C_DEV 510Return 1 if the system supports the C-Language Development Utilities Option, 511otherwise 0. 512.It Li USER_POSIX2_FORT_DEV 513Return 1 if the system supports the FORTRAN Development Utilities Option, 514otherwise 0. 515.It Li USER_POSIX2_FORT_RUN 516Return 1 if the system supports the FORTRAN Runtime Utilities Option, 517otherwise 0. 518.It Li USER_POSIX2_LOCALEDEF 519Return 1 if the system supports the creation of locales, otherwise 0. 520.It Li USER_POSIX2_SW_DEV 521Return 1 if the system supports the Software Development Utilities Option, 522otherwise 0. 523.It Li USER_POSIX2_UPE 524Return 1 if the system supports the User Portability Utilities Option, 525otherwise 0. 526.It Li USER_POSIX2_VERSION 527The version of POSIX 1003.2 with which the system attempts to comply. 528.It Li USER_RE_DUP_MAX 529The maximum number of repeated occurrences of a regular expression 530permitted when using interval notation. 531.ne 1i 532.It Li USER_STREAM_MAX 533The minimum maximum number of streams that a process may have open 534at any one time. 535.It Li USER_TZNAME_MAX 536The minimum maximum number of types supported for the name of a 537timezone. 538.El 539.Sh CTL_VM 540The string and integer information available for the CTL_VM level 541is detailed below. 542The changeable column shows whether a process with appropriate 543privilege may change the value. 544.Bl -column "Second level nameXXXXXX" "struct loadavgXXX" -offset indent 545.It Sy Pa Second level name Type Changeable 546.It VM\_LOADAVG struct loadavg no 547.It VM\_METER struct vmtotal no 548.El 549.Pp 550.Bl -tag -width "123456" 551.It Li VM_LOADAVG 552Return the load average history. 553The returned data consists of a 554.Va struct loadavg . 555.It Li VM_METER 556Return the system wide virtual memory statistics. 557The returned data consists of a 558.Va struct vmtotal . 559.El 560.Sh RETURN VALUES 561If the call to 562.Nm sysctl 563is successful, the number of bytes copied out is returned. 564Otherwise \-1 is returned and 565.Va errno 566is set appropriately. 567.Sh ERRORS 568The following errors may be reported: 569.Bl -tag -width Er 570.It Bq Er EFAULT 571The buffer 572.Fa name , 573.Fa oldp , 574.Fa newp , 575or length pointer 576.Fa oldlenp 577contains an invalid address. 578.It Bq Er EINVAL 579The 580.Fa name 581array is less than two or greater than CTL_MAXNAME. 582.It Bq Er EINVAL 583A non-null 584.Fa newp 585is given and its specified length in 586.Fa newlen 587is too large or too small. 588.It Bq Er ENOMEM 589The length pointed to by 590.Fa oldlenp 591is too short to hold the requested value. 592.It Bq Er ENOTDIR 593The 594.Fa name 595array specifies an intermediate rather than terminal name. 596.It Bq Er EOPNOTSUPP 597The 598.Fa name 599array specifies a value that is unknown. 600.It Bq Er EPERM 601An attempt is made to set a read-only value. 602.It Bq Er EPERM 603A process without appropriate privilege attempts to set a value. 604.El 605.Sh FILES 606.Bl -tag -width <netinet/icmpXvar.h> -compact 607.It Pa <sys/sysctl.h> 608definitions for top level identifiers, second level kernel and hardware 609identifiers, and user level identifiers 610.It Pa <sys/socket.h> 611definitions for second level network identifiers 612.It Pa <sys/gmon.h> 613definitions for third level profiling identifiers 614.It Pa <vm/vm_param.h> 615definitions for second level virtual memory identifiers 616.It Pa <netinet/in.h> 617definitions for third level Internet identifiers and 618fourth level IP identifiers 619.It Pa <netinet/icmp_var.h> 620definitions for fourth level ICMP identifiers 621.It Pa <netinet/udp_var.h> 622definitions for fourth level UDP identifiers 623.El 624.Sh SEE ALSO 625.Xr sysctl 8 626.Sh HISTORY 627The 628.Nm sysctl 629function first appeared in 4.4BSD. 630