NAME | SYNOPSIS | DESCRIPTION | EXTENDED DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | FILES | ATTRIBUTES | SEE ALSO
#include <sys/types.h> #include <sys/sysctl.h>int sysctl(int * name, u_int namelen, void * oldp, size_t * oldlenp, void * newp, size_t newlen);
sysctl() retrieves system information and allows processes with appropriate privileges to set system information. The information available from sysctl() consists of integers, strings, and tables. Information may be retrieved and set from the command interface using sysctl(1M) .
The state is described using a Management Information Base ( MIB )-style name, listed in name, which is a namelen length array of integers.
The sysctlbyname() function accepts an ASCII representation of the name and internally looks up the integer name vector. Apart from that, it behaves in the same way as the standard sysctl() function.
Unless explicitly noted below, 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 sysctl() are serialized to avoid deadlock.
The information is copied into the buffer specified by
oldp
. The size of the buffer is given by the location specified by
oldlenp
before the call, and that location gives the amount of data copied after a successful call and after a call that returns with the error code
ENOMEM
. If the amount of data available is greater than the size of the buffer supplied, the call supplies as much data as fits into the buffer provided and returns with the error code
ENOMEM
. If the old value is not desired,
oldp
and
oldlenp
should be set to
NULL
.
The size of the available data can be determined by calling
sysctl()
with a
NULL
parameter for
oldp
. The size of the available data will be returned in the location pointed to by
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.
To set a new value,
newp
is set to point to a buffer of length
newlen
from which the requested value is to be taken. If a new value is not to be set,
newp
should be set to
NULL
and
newlen
set to
0
.
The top level names are defined with a CTL_ prefix in <sys/sysctl.h> , and are as follows. The next and subsequent levels down are found in the header files listed here, and described below.
Name | Next level names | Description |
---|---|---|
CTL_HW | <sys/sysctl.h> | Generic CPU, I/O |
CTL_KERN | <sys/sysctl.h> | High kernel limits |
CTL_MQ | <posix/unistd.h> | Message queue |
CTL_NET | <sys/socket.h> | Networking |
CTL_SHM | <posix/unistd.h> | Shared memory |
CTL_VFS | <sys/sysctl.h> | File system |
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.
Second level name | Type | Changeable |
---|---|---|
HW_MACHINE | string | no |
HW_MACHINE
The machine class.
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.
Second level name | Type | Changeable |
---|---|---|
KERN_BOOTTIME | struct timeval | no |
KERN_FILE | struct file | no |
KERN_HOSTID | integer | yes |
KERN_HOSTNAME | string | yes |
KERN_MAXFILES | integer | yes |
KERN_MAXFILESPERPROC | integer | yes |
KERN_MAXSOCKBUF | integer | yes |
KERN_MAXVNODES | integer | yes |
KERN_NGROUPS | integer | no |
KERN_NISDOMAINNAME | string | yes |
KERN_OSRELDATE | integer | no |
KERN_OSRELEASE | string | no |
KERN_OSREV | integer | no |
KERN_OSTYPE | string | no |
KERN_SOMAXCONN | integer | yes |
KERN_UPDATEINTERVAL | integer | no |
KERN_VERSION | string | no |
KERN_BOOTTIME
A
struct timeval
structure is returned. This structure contains the time that the system was booted.
KERN_FILE
Returns the entire file table. The returned data consists of a single
struct filehead
followed by an array of
struct file
, whose size depends on the current number of these types of objects in the system.
KERN_HOSTID
Get or set the host ID .
KERN_HOSTNAME
Get or set the hostname.
KERN_MAXFILES
The maximum number of files that may be open in the system.
KERN_MAXFILESPERPROC
The maximum number of files that may be open for a single process. This limit only applies to processes with an effective
uid
of nonzero at the time of the open request. Files that have already been opened are not affected if the limit or the effective
uid
is changed.
KERN_MAXSOCKBUF
The maximum size of a socket buffer.
KERN_MAXVNODES
The maximum number of vnodes available on the system.
KERN_NGROUPS
The maximum number of supplementary groups.
KERN_NISDOMAINNAME
The name of the current YP/NIS domain.
KERN_OSRELDATE
The system release date in YYYYMM format (January 1996 is encoded as 199601).
KERN_OSRELEASE
The system release string.
KERN_OSREV
The system revision string.
KERN_OSTYPE
The system type string.
KERN_SOMAXCONN
The maximum number of connections when listening for events.
KERN_UPDATEINTERVAL
The system version string.
KERN_VERSION
Returns the entire vnode table. Note that 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 these objects in the system. Each element of the array contains the kernel address of a vnode
struct vnode *
followed by the vnode itself
struct vnode
.
CTL_SHM
The integer information available for the
CTL_SHM
level is detailed below. The
Changeable
column shows whether a process with appropriate privilege may change the value.
Second level name | Type | Changeable |
---|---|---|
_SC_SHARED_MEMORY_OBJECTS | int | no |
_SC_SHM_PATHMAX | int | yes |
_SC_SHARED_MEMORY_OBJECTS
Toggles the POSIX_SHM(5FEA) feature.
_SC_SHM_PATHMAX
Maximum path length for a shared memory object.
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.
Second level name | Type | Changeable |
---|---|---|
PF_ROUTE | routing messages | no |
PF_INET | internet values | yes |
PF_ROUTE
Returns the entire routing table or a subset of it. The data is returned as a sequence of routing messages. See route(4CC) for the header file format and meaning. The length of each message is contained in the message header.
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:
Fifth level name | Sixth level is: |
---|---|
NET_RT_DUMP | None |
NET_RT_FLAGS | rtflags |
NET_RT_IFLIST | None |
The fifth level names are defined as follows:
NET_RT_DUMP
Dump internal routing protocol.
NET_RT_FLAGS
Resolve internal routing protocol.
NET_RT_IFLIST
Survey interface list.
PF_INET
Get or set various global information about the internet protocols. The information available for the five subtypes of the
PF_INET
level are detailed below. The
Changeable
column in each table shows whether a process with appropriate privilege may change the value.
The variables related to the
IPPROTO_ICMP
subtype are as follows:
Fourth level name | Type | Changeable |
---|---|---|
ICMPCTL_MASKREPL | int | yes |
ICMPCTL_STATS | struct | no |
ICMPCTL_MASKREPL
Netmask requests
ICMPCTL_STATS
Statistics
The variable related to the
IPPROTO_IGMP
subtype is as follows:
Fourth level name | Type | Changeable |
---|---|---|
IGMPCTL_STATS | struct | no |
IGMPCTL_STATS
Statistics
The variables related to the
IPPROTO_IP
subtype are as follows:
Fourth level name | Type | Changeable |
---|---|---|
IPCTL_ACCEPTSOURCEROUTE | int | yes |
IPCTL_FORWARDING | int | yes |
IPCTL_INTRQDROPS | int | no |
IPCTL_INTRQMAXLEN | int | no |
IPCTL_SENDREDIRECTS | int | yes |
IPCTL_RTEXPIRE | int | yes |
IPCTL_RTMAXCACHE | int | yes |
IPCTL_RTMINEXPIRE | int | yes |
IPCTL_SOURCEROUTE | int | yes |
IPCTL_DEFTTL | int | yes |
IPCTL_ACCEPTSOURCEROUTE
Accept source routed packets
IPCTL_FORWARDING
Act as router
IPCTL_INTRQDROPS
Number of netisr queue drops
IPCTL_INTRQMAXLEN
Maximum length of netisr queue
IPCTL_SENDREDIRECTS
Send redirects when forwarding
IPCTL_RTEXPIRE
Cloned route expiration time
IPCTL_RTMAXCACHE
Trigger level for dynamic expire
IPCTL_RTMINEXPIRE
Minimum value for expiration time
IPCTL_SOURCEROUTE
Perform source routes
IPCTL_DEFTTL
Default TTL
The variables related to the
IPPROTO_TCP
subtype are as follows:
Fourth level name | Type | Changeable |
---|---|---|
TCPCTL_KEEPIDLE | int | yes |
TCPCTL_KEEPINIT | int | yes |
TCPCTL_KEEPINTVL | int | yes |
TCPCTL_MSSDFLT | int | yes |
TCPCTL_RECVSPACE | int | yes |
TCPCTL_DO_RFC1323 | int | yes |
TCPCTL_DO_RFC1644 | int | yes |
TCPCTL_RTTDFLT | int | yes |
TCPCTL_SENDSPACE | int | yes |
TCPCTL_STATS | struct | no |
TCPCTL_KEEPIDLE
Maximum before probing
TCPCTL_KEEPINIT
Maximum idle time during connect
TCPCTL_KEEPINTVL
Default probe interval
TCPCTL_MSSDFLT
MSS default
TCPCTL_RECVSPACE
Receive buffer space
TCPCTL_DO_RFC1323
RFC1323 extensions
TCPCTL_DO_RFC1644
RFC1644 extensions
TCPCTL_RTTDFLT
Default RTT estimate
TCPCTL_SENDSPACE
Send buffer space
TCPCTL_STATS
Statistics
The variables related to the
IPPROTO_UDP
subtype are as follows:
Fourth level name | Type | Changeable |
---|---|---|
UDPCTL_CHECKSUM | int | yes |
UDPCTL_MAXDGRAM | int | yes |
UDPCTL_RECVSPACE | int | yes |
UDPCTL_STATS | int | no |
UDPCTL_CHECKSUM
Checksum UDP packets
UDPCTL_MAXDGRAM
Maximum datagram size
UDPCTL_RECVSPACE
Default receive buffer space
UDPCTL_STATS
Statistics
CTL_MQ
The information available for the
CTL_MQ
level is detailed below. The
Changeable
column shows whether a process with appropriate privilege may change the value.
Second level name | Type | Changeable |
---|---|---|
_SC_MQ_OPEN_MAX | long | no |
_SC_MQ_PRIO_MAX | long | no |
_SC_MQ_DFL_MSGSIZE | long | no |
_SC_MQ_MAXMSGNB | long | no |
_SC_MQ_PATHMAX | long | no |
_SC_MQ_OPEN_MAX
Maximum number of open message queues.
_SC_MQ_PRIO_MAX
Maximum number of message priorities.
_SC_MQ_MSGSIZE
Default message size of a message queue.
_SC_MQ_DFL_MAXMSGNB
Default maximum message number of a message queue.
_SC_MQ_PATHMAX
Maximum message queue object name size.
CTL_VFS
The information available for the
CTL_VFS
level is detailed below. The
Changeable
column shows whether a process with appropriate privilege may change the value.
Second level name | Type | Changeable |
---|---|---|
VFS_VFSCONF | struct | no |
NFS_NFSSTATS | struct | no |
NFS_NFSPRIVPORT | int | yes |
VFS_VFSCONF
Get configured file systems.
NFS_NFSSTATS
Get NFS statistics.
NFS_NFSPRIVPORT
Prohibit NFS to resvports.
If the call to sysctl() is successful, 0 is returned. Otherwise -1 is returned and errno is set appropriately.
The following errors may be reported:
The buffer name, oldp , newp , or length pointer oldlenp contains an invalid address.
The name array is less than two or greater than
CTL_MAX_NAME
.
A non-null newp is given and its specified length in newlen is too large or too small.
The length pointed to by oldlenp is too short to hold the requested value.
The name array specifies an intermediate rather than terminal name.
The name array specifies a value that is unknown.
An attempt was made to set a read-only value.
A process without appropriate privilege attempted to set a value.
int mib[2], maxproc; size_t len; mib[0] = CTL_KERN; mib[1] = KERN_MAXPROC; len = sizeof(maxproc); sysctl(mib, 2, &maxproc, &len, NULL, 0);
The following example retrieves the standard search path for the system utilities:
int mib[2]; size_t len; char *p; 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);
For more information see the following files:
Definitions for fourth level ICMP identifiers.
Definitions for third level Internet identifiers and fourth level IP identifiers.
Definitions for fourth level UDP identifiers.
Definitions for third level profiling identifiers.
Definitions for second level network identifiers.
Definitions for top level identifiers, second level kernel and hardware identifiers, and user level identifiers.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | DESCRIPTION | EXTENDED DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | FILES | ATTRIBUTES | SEE ALSO