INtime SDK Help
sysctl, sysctlbyname, sysctlnametomib
INtime Help

Get or set system information.

#include <sys/types.h>
#include <sys/sysctl.h>

sysctl(int *name, u_int namelen, void *oldp, 
       size_t *oldlenp, void *newp, size_t newlen);

sysctlbyname(const char *name, void *oldp, 
             size_t *oldlenp, void *newp, size_t newlen);

sysctlnametomib(const char *name, int *mibp, size_t *sizep);


The sysctl() function 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 the sysctl utility.

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 state is described using a ``Management Information Base'' (MIB) style name, listed in name , which is anamelen 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 the same as the standard sysctl() function.

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 in 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 the NULL argument 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 sysctlnametomib() function accepts an ASCII representation of the name, looks up the integer name vector, and returns the numeric representation in the mib array pointed to by mibp . The number of elements in the mib array is given by the location specified by sizep before the call, and that location gives the number of entries copied after a successful call. The resulting mib and size may be used in subsequent sysctl() calls to get the data associated with the requested ASCII name. This interface is intended for use by applications that want to repeatedly request the same variable (the sysctl() function runs in about a third the time as the same request made via the sysctlbyname() function). The sysctlnametomib() function is also useful for fetching mib prefixes and then adding a final component. For example, to fetch process information for processes with pid's less than 100:

int i, mib[4];
size_t len;
struct kinfo_proc kp;

/* Fill out the first three components of the mib */
len = 4;
sysctlnametomib("", mib, &len);

/* Fetch and print entries for pid's < 100 */
for (i = 0; i < 100; i++) {
        mib[3] = i;
        len = sizeof(kp);
        if (sysctl(mib, 4, &kp, &len, NULL, 0) == -1)
        else if (len > 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 include files listed here, and described in separate sections below.

Name Next level names Description
CTL_NET sys/socket.h Networking

For example, the following retrieves the maximum number of processes allowed in the system:

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);

To retrieve 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);

The debugging variables vary from system to system. A debugging variable may be added or deleted without need to recompile sysctl() to know about it. Each time it runs, sysctl() gets the list of debugging variables from the kernel and displays their current values. The system defines twenty variables named debug0 through 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 dospecialcheck as a debugging variable, the following declaration would be used:

int dospecialcheck = 1;
struct ctldebug debug5 = { "dospecialcheck", &dospecialcheck };

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 IPv4 values yes
PF_INET6 IPv6 values yes
PF_ROUTE Return the entire routing table or a subset of it. The data is returned as a sequence of routing messages (see route 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_FLAGS rtflags
NET_RT_IFLIST 0 or if_index
NET_RT_IFMALIST 0 or if_index

The NET_RT_IFMALIST name returns information about multicast group memberships on all interfaces if 0 is specified, or for the interface specified by if_index.

PF_INET Get or set various global information about the IPv4 (Internet Protocol version 4). The third level name is the protocol. The fourth level name is the variable name. The currently defined protocols and names are:
Protocol Variable Type Changeable Description
icmp bmcastecho integer yes Returns 1 if an ICMP echo request to broacast or multicast address is to be answered
icmp maskrepl integer yes Returns 1 if ICMP network mask requests are to be answered
ip forwarding integer yes Returns 1 when IP forwarding is enabled for the host, meaning that the host is acting as a router.
ip redirect integer yes Returns 1 when ICMP redirects may be sent by the host. The option is ignored unless the the host is routing IP packets, and should normally be enabled on all systems.
ip ttl integer yes The maximum time-to-live (hop count) value for an IP packet sourced by the system. The value applies to normal transport protocols, not to ICMP.
udp checksum integer yes Returns 1 when UDP checksums are being computed and checked. Disabled UDP checksum is strongly discouraged.
PF_INET6 Get or set various global information about the IPv6 (Internet Protocol version 6). The third level name is the protocol.

The fourth level name is the variable name. For variables net.inet6.* please refer to inet64.


<sys/sysctl.h> definitions for top level identifiers, second level kernel and hardware identifiers, and user level identifiers
<sys/socket.h> definitions for second level network identifiers
<netinet/in.h> definitions for third level IPv4/IPv6 identifiers and fourth level IPv4/v6 identifiers
<netinet/icmp_var.h> definitions for fourth level ICMP identifiers
<netinet/icmp6.h> definitions for fourth level ICMPv6 identifiers
<netinet/udp_var.h> definitions for fourth level UDP identifiers

Return Values

The function returns the value 0 if successful; otherwisethe value -1 is returned and the global variable errno is set to indicate the error.

The following errors may be reported:

EFAULT The buffer name, oldp, newp, or length pointer oldlenp contains an invalid address.
EINVAL The name array is less than two or greater than CTL_MAXNAME.
EINVAL A non-null newp is given and its specified length in newlen is too large or too small.
ENOMEM The length pointed to by oldlenp is too short to hold the requested value.
ENOMEM The smaller of either the length pointed to by oldlenp or the estimated size of the returned data exceeds the system limit on locked memory.
ENOMEM Locking the buffer oldp, or a portion of the buffer if the estimated size of the data to be returned is smaller, would cause the process to exceed its per-process locked memory limit.
ENOTDIR The name array specifies an intermediate rather than terminal name.
EISDIR The name array specifies a terminal name, but the actual name is not terminal.
ENOENT The name array specifies a value that is unknown.
EPERM An attempt is made to set a read-only value.


Versions Link to
INtime 4.0 netlib.lib

See Also