diff options
Diffstat (limited to 'lib/libc/gen/sysctl.3')
| -rw-r--r-- | lib/libc/gen/sysctl.3 | 650 |
1 files changed, 650 insertions, 0 deletions
diff --git a/lib/libc/gen/sysctl.3 b/lib/libc/gen/sysctl.3 new file mode 100644 index 0000000..602b559 --- /dev/null +++ b/lib/libc/gen/sysctl.3 @@ -0,0 +1,650 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sysctl.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd "June 4, 1993" +.Dt SYSCTL 3 +.Os +.Sh NAME +.Nm sysctl +.Nd get or set system information +.Sh SYNOPSIS +.Fd #include <sys/sysctl.h> +.Ft int +.Fn sysctl "int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" +.Sh DESCRIPTION +The +.Nm sysctl +function retrieves system information and allows processes with +appropriate privileges to set system information. +The information available from +.Nm sysctl +consists of integers, strings, and tables. +Information may be retrieved and set from the command interface +using the +.Xr sysctl 1 +utility. +.Pp +Unless explicitly noted below, +.Nm sysctl +returns a consistent snapshot of the data requested. +Consistency is obtained by locking the destination +buffer into memory so that the data may be copied out without blocking. +Calls to +.Nm sysctl +are serialized to avoid deadlock. +.Pp +The state is described using a ``Management Information Base'' (MIB) +style name, listed in +.Fa name , +which is a +.Fa namelen +length array of integers. +.Pp +The information is copied into the buffer specified by +.Fa oldp . +The size of the buffer is given by the location specified by +.Fa oldlenp +before the call, +and that location gives the amount of data copied after a successful call. +If the amount of data available is greater +than the size of the buffer supplied, +the call supplies as much data as fits in the buffer provided +and returns with the error code ENOMEM. +If the old value is not desired, +.Fa oldp +and +.Fa oldlenp +should be set to NULL. +.Pp +The size of the available data can be determined by calling +.Nm sysctl +with a NULL parameter for +.Fa oldp . +The size of the available data will be returned in the location pointed to by +.Fa oldlenp . +For some operations, the amount of space may change often. +For these operations, +the system attempts to round up so that the returned size is +large enough for a call to return the data shortly thereafter. +.Pp +To set a new value, +.Fa newp +is set to point to a buffer of length +.Fa newlen +from which the requested value is to be taken. +If a new value is not to be set, +.Fa newp +should be set to NULL and +.Fa newlen +set to 0. +.Pp +The top level names are defined with a CTL_ prefix in +.Pa <sys/sysctl.h> , +and are as follows. +The next and subsequent levels down are found in the include files +listed here, and described in separate sections below. +.Pp +.Bl -column CTLXMACHDEPXXX "Next level namesXXXXXX" -offset indent +.It Sy Pa Name Next level names Description +.It CTL\_DEBUG sys/sysctl.h Debugging +.It CTL\_FS sys/sysctl.h File system +.It CTL\_HW sys/sysctl.h Generic CPU, I/O +.It CTL\_KERN sys/sysctl.h High kernel limits +.It CTL\_MACHDEP sys/sysctl.h Machine dependent +.It CTL\_NET sys/socket.h Networking +.It CTL\_USER sys/sysctl.h User-level +.It CTL\_VM vm/vm_param.h Virtual memory +.El +.Pp +For example, the following retrieves the maximum number of processes allowed +in the system: +.Bd -literal -offset indent -compact +int mib[2], maxproc; +size_t len; +.sp +mib[0] = CTL_KERN; +mib[1] = KERN_MAXPROC; +len = sizeof(maxproc); +sysctl(mib, 2, &maxproc, &len, NULL, 0); +.Ed +.sp +To retrieve the standard search path for the system utilities: +.Bd -literal -offset indent -compact +int mib[2]; +size_t len; +char *p; +.sp +mib[0] = CTL_USER; +mib[1] = USER_CS_PATH; +sysctl(mib, 2, NULL, &len, NULL, 0); +p = malloc(len); +sysctl(mib, 2, p, &len, NULL, 0); +.Ed +.Sh CTL_DEBUG +The debugging variables vary from system to system. +A debugging variable may be added or deleted without need to recompile +.Nm sysctl +to know about it. +Each time it runs, +.Nm sysctl +gets the list of debugging variables from the kernel and +displays their current values. +The system defines twenty +.Ns ( Va struct ctldebug ) +variables named +.Nm debug0 +through +.Nm debug19 . +They are declared as separate variables so that they can be +individually initialized at the location of their associated variable. +The loader prevents multiple use of the same variable by issuing errors +if a variable is initialized in more than one place. +For example, to export the variable +.Nm dospecialcheck +as a debugging variable, the following declaration would be used: +.Bd -literal -offset indent -compact +int dospecialcheck = 1; +struct ctldebug debug5 = { "dospecialcheck", &dospecialcheck }; +.Ed +.Sh CTL_FS +There are currently no second level names for the file system. +.Sh CTL_HW +The string and integer information available for the CTL_HW level +is detailed below. +The changeable column shows whether a process with appropriate +privilege may change the value. +.Bl -column "Second level nameXXXXXX" integerXXX -offset indent +.It Sy Pa Second level name Type Changeable +.It HW\_MACHINE string no +.It HW\_MODEL string no +.It HW\_NCPU integer no +.It HW\_BYTEORDER integer no +.It HW\_PHYSMEM integer no +.It HW\_USERMEM integer no +.It HW\_PAGESIZE integer no +.\".It HW\_DISKNAMES integer no +.\".It HW\_DISKSTATS integer no +.El +.Pp +.Bl -tag -width "123456" +.It Li HW_MACHINE +The machine class. +.It Li HW_MODEL +The machine model +.It Li HW_NCPU +The number of cpus. +.It Li HW_BYTEORDER +The byteorder (4,321, or 1,234). +.It Li HW_PHYSMEM +The bytes of physical memory. +.It Li HW_USERMEM +The bytes of non-kernel memory. +.It Li HW_PAGESIZE +The software page size. +.\".It Fa HW_DISKNAMES +.\".It Fa HW_DISKSTATS +.El +.Sh CTL_KERN +The string and integer information available for the CTL_KERN level +is detailed below. +The changeable column shows whether a process with appropriate +privilege may change the value. +The types of data currently available are process information, +system vnodes, the open file entries, routing table entries, +virtual memory statistics, load average history, and clock rate +information. +.Bl -column "KERNXCHOWNXRESTRICTEDXXX" "struct clockrateXXX" -offset indent +.It Sy Pa Second level name Type Changeable +.It KERN\_ARGMAX integer no +.It KERN\_BOOTTIME struct timeval no +.It KERN\_CHOWN\_RESTRICTED integer no +.It KERN\_CLOCKRATE struct clockinfo no +.It KERN\_FILE struct file no +.It KERN\_HOSTID integer yes +.It KERN\_HOSTNAME string yes +.It KERN\_JOB\_CONTROL integer no +.It KERN\_LINK\_MAX integer no +.It KERN\_MAXFILES integer yes +.It KERN\_MAXPROC integer yes +.It KERN\_MAXVNODES integer yes +.It KERN\_MAX\_CANON integer no +.It KERN\_MAX\_INPUT integer no +.It KERN\_NAME\_MAX integer no +.It KERN\_NGROUPS integer no +.It KERN\_NO\_TRUNC integer no +.It KERN\_OSRELEASE string no +.It KERN\_OSREV integer no +.It KERN\_OSTYPE string no +.It KERN\_PATH\_MAX integer no +.It KERN\_PIPE\_BUF integer no +.It KERN\_POSIX1 integer no +.It KERN\_PROC struct proc no +.It KERN\_PROF node not applicable +.It KERN\_SAVED\_IDS integer no +.It KERN\_SECURELVL integer raise only +.It KERN\_VDISABLE integer no +.It KERN\_VERSION string no +.It KERN\_VNODE struct vnode no +.El +.Pp +.Bl -tag -width "123456" +.It Li KERN_ARGMAX +The maximum bytes of argument to +.Xr exec 2 . +.It Li KERN_BOOTTIME +A +.Va struct timeval +structure is returned. +This structure contains the time that the system was booted. +.It Li KERN_CHOWN_RESTRICTED +Return 1 if appropriate privileges are required for the +.Xr chown 2 +system call, otherwise 0. +.It Li KERN_CLOCKRATE +A +.Va struct clockinfo +structure is returned. +This structure contains the clock, statistics clock and profiling clock +frequencies, and the number of micro-seconds per hz tick. +.It Li KERN_FILE +Return the entire file table. +The returned data consists of a single +.Va struct filehead +followed by an array of +.Va struct file , +whose size depends on the current number of such objects in the system. +.It Li KERN_HOSTID +Get or set the host id. +.It Li KERN_HOSTNAME +Get or set the hostname. +.It Li KERN_JOB_CONTROL +Return 1 if job control is available on this system, otherwise 0. +.It Li KERN_LINK_MAX +The maximum file link count. +.It Li KERN_MAXFILES +The maximum number of open files that may be open in the system. +.It Li KERN_MAXPROC +The maximum number of simultaneous processes the system will allow. +.It Li KERN_MAXVNODES +The maximum number of vnodes available on the system. +.It Li KERN_MAX_CANON +The maximum number of bytes in terminal canonical input line. +.It Li KERN_MAX_INPUT +The minimum maximum number of bytes for which space is available in +a terminal input queue. +.It Li KERN_NAME_MAX +The maximum number of bytes in a file name. +.It Li KERN_NGROUPS +The maximum number of supplemental groups. +.It Li KERN_NO_TRUNC +Return 1 if file names longer than KERN_NAME_MAX are truncated. +.It Li KERN_OSRELEASE +The system release string. +.It Li KERN_OSREV +The system revision string. +.It Li KERN_OSTYPE +The system type string. +.It Li KERN_PATH_MAX +The maximum number of bytes in a pathname. +.It Li KERN_PIPE_BUF +The maximum number of bytes which will be written atomically to a pipe. +.It Li KERN_POSIX1 +The version of ISO/IEC 9945 (POSIX 1003.1) with which the system +attempts to comply. +.It Li KERN_PROC +Return the entire process table, or a subset of it. +An array of +.Va struct kinfo_proc +structures is returned, +whose size depends on the current number of such objects in the system. +The third and fourth level names are as follows: +.Bl -column "Third level nameXXXXXX" "Fourth level is:XXXXXX" -offset indent +.It Pa Third level name Fourth level is: +.It KERN\_PROC\_ALL None +.It KERN\_PROC\_PID A process ID +.It KERN\_PROC\_PGRP A process group +.It KERN\_PROC\_TTY A tty device +.It KERN\_PROC\_UID A user ID +.It KERN\_PROC\_RUID A real user ID +.El +.It Li KERN_PROF +Return profiling information about the kernel. +If the kernel is not compiled for profiling, +attempts to retrieve any of the KERN_PROF values will +fail with EOPNOTSUPP. +The third level names for the string and integer profiling information +is detailed below. +The changeable column shows whether a process with appropriate +privilege may change the value. +.Bl -column "GPROFXGMONPARAMXXX" "struct gmonparamXXX" -offset indent +.It Sy Pa Third level name Type Changeable +.It GPROF\_STATE integer yes +.It GPROF\_COUNT u_short[\|] yes +.It GPROF\_FROMS u_short[\|] yes +.It GPROF\_TOS struct tostruct yes +.It GPROF\_GMONPARAM struct gmonparam no +.El +.Pp +The variables are as follows: +.Bl -tag -width "123456" +.It Li GPROF_STATE +Returns GMON_PROF_ON or GMON_PROF_OFF to show that profiling +is running or stopped. +.It Li GPROF_COUNT +Array of statistical program counter counts. +.It Li GPROF_FROMS +Array indexed by program counter of call-from points. +.It Li GPROF_TOS +Array of +.Va struct tostruct +describing destination of calls and their counts. +.It Li GPROF_GMONPARAM +Structure giving the sizes of the above arrays. +.El +.It Li KERN_SAVED_IDS +Returns 1 if saved set-group and saved set-user ID is available. +.It Li KERN_SECURELVL +The system security level. +This level may be raised by processes with appropriate privilege. +It may only be lowered by process 1. +.It Li KERN_VDISABLE +Returns the terminal character disabling value. +.It Li KERN_VERSION +The system version string. +.It Li KERN_VNODE +Return the entire vnode table. +Note, the vnode table is not necessarily a consistent snapshot of +the system. +The returned data consists of an array whose size depends on the +current number of such objects in the system. +Each element of the array contains the kernel address of a vnode +.Va struct vnode * +followed by the vnode itself +.Va struct vnode . +.El +.Sh CTL_MACHDEP +The set of variables defined is architecture dependent. +Most architectures define at least the following variables. +.Bl -column "CONSOLE_DEVICEXXX" "integerXXX" -offset indent +.It Sy Pa Second level name Type Changeable +.It Li CPU_CONSDEV dev_t no +.El +.Sh CTL_NET +The string and integer information available for the CTL_NET level +is detailed below. +The changeable column shows whether a process with appropriate +privilege may change the value. +.Bl -column "Second level nameXXXXXX" "routing messagesXXX" -offset indent +.It Sy Pa Second level name Type Changeable +.It PF\_ROUTE routing messages no +.It PF\_INET internet values yes +.El +.Pp +.Bl -tag -width "123456" +.It Li PF_ROUTE +Return the entire routing table or a subset of it. +The data is returned as a sequence of routing messages (see +.Xr route 4 +for the header file, format and meaning). +The length of each message is contained in the message header. +.Pp +The third level name is a protocol number, which is currently always 0. +The fourth level name is an address family, which may be set to 0 to +select all address families. +The fifth and sixth level names are as follows: +.Bl -column "Fifth level nameXXXXXX" "Sixth level is:XXX" -offset indent +.It Pa Fifth level name Sixth level is: +.It NET\_RT\_FLAGS rtflags +.It NET\_RT\_DUMP None +.It NET\_RT\_IFLIST None +.El +.It Li PF_INET +Get or set various global information about the internet protocols. +The third level name is the protocol. +The fourth level name is the variable name. +The currently defined protocols and names are: +.Bl -column "Protocol nameXXXXXX" "Variable nameXXX" "integerXXX" -offset indent +.It Pa Protocol name Variable name Type Changeable +.It ip forwarding integer yes +.It ip redirect integer yes +.It ip ttl integer yes +.It icmp maskrepl integer yes +.It udp checksum integer yes +.El +.Pp +The variables are as follows: +.Bl -tag -width "123456" +.It Li ip.forwarding +Returns 1 when IP forwarding is enabled for the host, +meaning that the host is acting as a router. +.It Li ip.redirect +Returns 1 when ICMP redirects may be sent by the host. +This option is ignored unless the host is routing IP packets, +and should normally be enabled on all systems. +.It Li ip.ttl +The maximum time-to-live (hop count) value for an IP packet sourced by +the system. +This value applies to normal transport protocols, not to ICMP. +.It Li icmp.maskrepl +Returns 1 if ICMP network mask requests are to be answered. +.It Li udp.checksum +Returns 1 when UDP checksums are being computed and checked. +Disabling UDP checksums is strongly discouraged. +.El +.Sh CTL_USER +The string and integer information available for the CTL_USER level +is detailed below. +The changeable column shows whether a process with appropriate +privilege may change the value. +.Bl -column "USER_COLL_WEIGHTS_MAXXXX" "integerXXX" -offset indent +.It Sy Pa Second level name Type Changeable +.It USER\_BC\_BASE\_MAX integer no +.It USER\_BC\_DIM\_MAX integer no +.It USER\_BC\_SCALE\_MAX integer no +.It USER\_BC\_STRING\_MAX integer no +.It USER\_COLL\_WEIGHTS\_MAX integer no +.It USER\_CS\_PATH string no +.It USER\_EXPR\_NEST\_MAX integer no +.It USER\_LINE\_MAX integer no +.It USER\_POSIX2\_CHAR\_TERM integer no +.It USER\_POSIX2\_C\_BIND integer no +.It USER\_POSIX2\_C\_DEV integer no +.It USER\_POSIX2\_FORT\_DEV integer no +.It USER\_POSIX2\_FORT\_RUN integer no +.It USER\_POSIX2\_LOCALEDEF integer no +.It USER\_POSIX2\_SW\_DEV integer no +.It USER\_POSIX2\_UPE integer no +.It USER\_POSIX2\_VERSION integer no +.It USER\_RE\_DUP\_MAX integer no +.It USER\_STREAM\_MAX integer no +.It USER\_TZNAME\_MAX integer no +.El +.Bl -tag -width "123456" +.Pp +.It Li USER_BC_BASE_MAX +The maximum ibase/obase values in the +.Xr bc 1 +utility. +.It Li USER_BC_DIM_MAX +The maximum array size in the +.Xr bc 1 +utility. +.It Li USER_BC_SCALE_MAX +The maximum scale value in the +.Xr bc 1 +utility. +.It Li USER_BC_STRING_MAX +The maximum string length in the +.Xr bc 1 +utility. +.It Li USER_COLL_WEIGHTS_MAX +The maximum number of weights that can be assigned to any entry of +the LC_COLLATE order keyword in the locale definition file. +.It Li USER_CS_PATH +Return a value for the +.Ev PATH +environment variable that finds all the standard utilities. +.It Li USER_EXPR_NEST_MAX +The maximum number of expressions that can be nested within +parenthesis by the +.Xr expr 1 +utility. +.It Li USER_LINE_MAX +The maximum length in bytes of a text-processing utility's input +line. +.It Li USER_POSIX2_CHAR_TERM +Return 1 if the system supports at least one terminal type capable of +all operations described in POSIX 1003.2, otherwise 0. +.It Li USER_POSIX2_C_BIND +Return 1 if the system's C-language development facilities support the +C-Language Bindings Option, otherwise 0. +.It Li USER_POSIX2_C_DEV +Return 1 if the system supports the C-Language Development Utilities Option, +otherwise 0. +.It Li USER_POSIX2_FORT_DEV +Return 1 if the system supports the FORTRAN Development Utilities Option, +otherwise 0. +.It Li USER_POSIX2_FORT_RUN +Return 1 if the system supports the FORTRAN Runtime Utilities Option, +otherwise 0. +.It Li USER_POSIX2_LOCALEDEF +Return 1 if the system supports the creation of locales, otherwise 0. +.It Li USER_POSIX2_SW_DEV +Return 1 if the system supports the Software Development Utilities Option, +otherwise 0. +.It Li USER_POSIX2_UPE +Return 1 if the system supports the User Portability Utilities Option, +otherwise 0. +.It Li USER_POSIX2_VERSION +The version of POSIX 1003.2 with which the system attempts to comply. +.It Li USER_RE_DUP_MAX +The maximum number of repeated occurrences of a regular expression +permitted when using interval notation. +.It Li USER_STREAM_MAX +The minimum maximum number of streams that a process may have open +at any one time. +.It Li USER_TZNAME_MAX +The minimum maximum number of types supported for the name of a +timezone. +.El +.Sh CTL_VM +The string and integer information available for the CTL_VM level +is detailed below. +The changeable column shows whether a process with appropriate +privilege may change the value. +.Bl -column "Second level nameXXXXXX" "struct loadavgXXX" -offset indent +.It Sy Pa Second level name Type Changeable +.It VM\_LOADAVG struct loadavg no +.It VM\_METER struct vmtotal no +.El +.Pp +.Bl -tag -width "123456" +.It Li VM_LOADAVG +Return the load average history. +The returned data consists of a +.Va struct loadavg . +.It Li VM_METER +Return the system wide virtual memory statistics. +The returned data consists of a +.Va struct vmtotal . +.El +.Sh RETURN VALUES +If the call to +.Nm sysctl +is successful, 0 is returned. +Otherwise \-1 is returned and +.Va errno +is set appropriately. +.Sh ERRORS +The following errors may be reported: +.Bl -tag -width Er +.It Bq Er EFAULT +The buffer +.Fa name , +.Fa oldp , +.Fa newp , +or length pointer +.Fa oldlenp +contains an invalid address. +.It Bq Er EINVAL +The +.Fa name +array is less than two or greater than CTL_MAXNAME. +.It Bq Er EINVAL +A non-null +.Fa newp +is given and its specified length in +.Fa newlen +is too large or too small. +.It Bq Er ENOMEM +The length pointed to by +.Fa oldlenp +is too short to hold the requested value. +.It Bq Er ENOTDIR +The +.Fa name +array specifies an intermediate rather than terminal name. +.It Bq Er EOPNOTSUPP +The +.Fa name +array specifies a value that is unknown. +.It Bq Er EPERM +An attempt is made to set a read-only value. +.It Bq Er EPERM +A process without appropriate privilege attempts to set a value. +.El +.Sh FILES +.Bl -tag -width <netinet/icmpXvar.h> -compact +.It Pa <sys/sysctl.h> +definitions for top level identifiers, second level kernel and hardware +identifiers, and user level identifiers +.It Pa <sys/socket.h> +definitions for second level network identifiers +.It Pa <sys/gmon.h> +definitions for third level profiling identifiers +.It Pa <vm/vm_param.h> +definitions for second level virtual memory identifiers +.It Pa <netinet/in.h> +definitions for third level Internet identifiers and +fourth level IP identifiers +.It Pa <netinet/icmp_var.h> +definitions for fourth level ICMP identifiers +.It Pa <netinet/udp_var.h> +definitions for fourth level UDP identifiers +.El +.Sh SEE ALSO +.Xr sysctl 8 +.Sh HISTORY +The +.Nm sysctl +function first appeared in 4.4BSD. |
