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