Get or set system information.

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

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

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

Description

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("kern.proc.pid", 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)
                perror("sysctl");
        else if (len > 0)
                printkproc(&kp);
}

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.

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.

Files

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:

Requirements

See Also

sysctl