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.3 (Berkeley) 03/05/93 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 17.Fn sysctl "int *name" "u_int namelen" "void *old" "size_t *oldlenp" "void *new" "size_t newlen" 18.Sh DESCRIPTION 19The 20.Fn sysctl 21function retrieves kernel state and allows processes with 22appropriate privilege to set kernel state. 23The state to be set is described using a 24``Management Information Base'' (MIB) style name, 25described in a 26.Fa namelen 27length array of integers pointed to by 28.Fa name . 29The top level names are defined with a CTL_ prefix in 30.Pa <sys/sysctl.h> . 31The next levels down are found in the files given in the ``FILES'' 32section of this manual page. 33.Pp 34The information is copied into the buffer specified by 35.Fa old . 36The size of the buffer is given by the location specified by 37.Fa oldlenp 38before the call, 39and that location gives the amount of data copied after a successful call. 40If the amount of data available is greater 41than the size of the buffer supplied, 42the call supplies as much data as fits in the buffer provided 43and returns with the error code EINVAL. 44If the old value is not desired, 45.Fa old 46and 47.Fa oldlenp 48can be set to NULL. 49.Pp 50The size of the available data can be determined by calling 51.Fn sysctl 52with a NULL parameter for 53.Fa old . 54The size of the available data be returned in the location pointed to by 55.Fa oldlenp . 56For some operations, the amount of space may change often; 57the system attempts to round up so that the returned size is 58large enough for a call to return the data shortly thereafter. 59.Pp 60To set a new value, 61.Fa new 62is set to point to a buffer of length 63.Fa newlen 64from which the requested value is to be taken. 65If a new value is not to be set, 66.Fa new 67should be set to NULL and 68.Fa newlen 69set to 0. 70.Pp 71The information available from 72.Fn sysctl 73consists of integers, strings, and tables. 74The string and integer information is detailed below. 75The changeable column shows whether a process with appropriate 76privilege can change the value. 77Changeable values may be retrieved and set using the 78.Xr sysctl 1 79utility. 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 102For example, the following retrieves the maximum number of processes allowed 103in the system: 104.Bd -literal -offset indent -compact 105int name[2], maxproc; 106size_t len; 107.sp 108name[0] = CTL_KERN; 109name[1] = KERN_MAXPROC; 110len = sizeof(maxproc); 111sysctl(name, 2, &maxproc, &len, NULL, 0); 112.Ed 113.Pp 114The tables that can be retrieved from the kernel by 115.Fn sysctl 116are detailed below. 117For most operations, the 118.Fn sysctl 119function returns a consistent snapshot of the data requested. 120(This is not currently true for 121.Dv KERN_VNODE ) . 122The consistency is done by locking the destination buffer into memory 123so that the data may be copied out without blocking. 124Calls are serialized to avoid deadlock. 125The types of data currently available are process information, 126system vnodes, the open file entries, routing table entries, 127virtual memory statistics, load average history, 128and clock rate information. 129The following paragraphs detail how each of these is obtained. 130.Pp 131The entire process table, or a subset of it, may be obtained with 132.Pa CTL_KERN/KERN_PROC/<op>/<arg> . 133An array of 134.Ns ( Fa struct kinfo_proc Ns ) 135structures is returned, 136whose size depends on the current number of such objects in the system. 137The 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 148The entire vnode table may be obtained with 149.Pa CTL_KERN/KERN_VNODE . 150The returned data consists of an array 151whose size depends on the current number of such objects in the system. 152Each element of the array contains the kernel address of a vnode 153.Ns ( Fa struct vnode * Ns ) 154followed by the vnode itself 155.Ns ( Fa struct vnode Ns ) . 156.Pp 157The entire file table may be obtained with 158.Pa CTL_KERN/KERN_FILE . 159The returned data consists of a single 160.Ns ( Fa struct filehead Ns ) 161followed by an array of 162.Ns ( Fa struct file Ns ) , 163whose size depends on the current number of such objects in the system. 164.Pp 165Information about the system clock rate may be obtained with 166.Pa CTL_KERN/KERN_CLOCKRATE . 167The returned data consists of a 168.Ns ( Fa struct clockinfo Ns ) . 169.Pp 170Information about the load average history may be obtained with 171.Pa CTL_VM/VM_LOADAVG . 172The returned data consists of a 173.Ns ( Fa struct loadavg Ns ) . 174.Pp 175Information about the system wide virtual memory statistics 176may be obtained with 177.Pa CTL_VM/VM_METER . 178The returned data consists of a 179.Ns ( Fa struct vmtotal Ns ) . 180.Pp 181The entire routing table or a subset of it may be obtained with 182.Pa CTL_NET/PF_ROUTE/<protocol number>/<address family>/<op>/<arg> . 183The protocol number is currently always zero. 184The address family may be set to zero to select all address families. 185The 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 192The data is returned as a sequence of routing messages (see 193.Xr route 4 194for the header file, format and meaning). 195The length of each message is contained in the message header. 196.Sh RETURN VALUES 197If the call to 198.Fn sysctl 199is successful, 0 is returned. 200Otherwise \-1 is returned and 201.Va errno 202is set appropriately. 203.Sh ERRORS 204The following error may be reported: 205.Bl -tag -width Er 206.It Bq Er EFAULT 207The buffer 208.Fa name , 209.Fa old , 210.Fa new , 211or length pointer 212.Fa oldlenp 213contains an invalid address. 214.It Bq Er EINVAL 215The 216.Fa name 217array is less than two or greater than CTL_MAXNAME. 218.It Bq Er EINVAL 219A non-null 220.Fa new 221is given and its specified length in 222.Fa newlen 223is too large or too small. 224.It Bq Er ENOMEM 225The length pointed to by 226.Fa oldlenp 227is too short to hold the requested value. 228.It Bq Er ENOTDIR 229The 230.Fa name 231array specifies an intermediate rather than terminal name. 232.It Bq Er EOPNOTSUPP 233The 234.Fa name 235array specifies a value that is unknown. 236.It Bq Er EPERM 237An attempt is made to set a read-only value. 238.It Bq Er EPERM 239A 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> 244definitions for top level identifiers and second level kernel 245and hardware identifiers 246.It Pa <sys/socket.h> 247definitions for second level network identifiers 248.It Pa <vm/vm_param.h> 249definitions for second level virtual memory identifiers 250.El 251.Sh SEE ALSO 252.Xr sysctl 8 253.Sh HISTORY 254The 255.Fn sysctl 256function first appeared in 4.4BSD. 257