sysctl(3POSIX)

NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | EXTENDED DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | FILES | ATTRIBUTES | SEE ALSO

NAME

sysctl, sysctlbyname- get or set system information

SYNOPSIS

$(OS_DIR)/lib/libc.a
#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);

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

DESCRIPTION

The sysctl() function retrieves system information and allows processes with the appropriate privileges to set system information. The information available from sysctl() includes integers, strings, and tables. Information may be retrieved and set from the command interface using sysctl(1M) .

The system 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 behaves in largely the same way as the standard sysctl() function. However, sysctlbyname() accepts an ASCII representation of name and looks up the integer name vector internally.

EXTENDED DESCRIPTION

Unless explicitly stated 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 system information obtained is copied into the buffer specified by oldp . The size of the buffer is given by the location specified by oldlenp before the call. This location provides the amount of data copied after a successful call or 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 required, set oldp and oldlenp to NULL .

To determine the size of the available data, call sysctl() with oldp set to NULL . The size is returned in the location pointed to by oldlenp . For certain operations, the amount of space may change frequently. For these operations, the system attempts to round up so that the returned size is large enough for a call to return the data within a short time interval.

To set a new value, set newp to point to a buffer of length newlen , from which the requested value is taken. If a new value is not to be set, set newp to NULL and newlen to 0 .

The top level names are defined with a CTL_ prefix in <sys/sysctl.h> , and are as follows:

Name	Next level names	Description
CTL_HW	<sys/sysctl.h>	Generic CPU, I/O
CTL_KERN	<sys/sysctl.h>	High microkernel 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

The next and subsequent levels down are found in the header files, described below.

CTL_HW

The table below lists the string and integer information available for the CTL_HW level. The "Changeable" column indicates whether a process with the appropriate privileges can 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 the appropriate privileges can change the value. The types of data currently available are process information, system vnodes, open file entries, routing table entries, virtual memory statistics, load average history, and clock rate information.

Second level name	Type	Changeable
KERN_FILE	struct file	no
KERN_HOSTID	integer	yes
KERN_HOSTNAME	string	yes
KERN_MAXFILES	integer	yes
KERN_MAXFILESPERPROC	integer	yes
KERN_MAXVNODES	integer	yes
KERN_NGROUPS	integer	no
KERN_OSRELDATE	integer	no
KERN_OSRELEASE	string	no
KERN_OSREVISION	integer	no
KERN_OSTYPE	string	no
KERN_VERSION	string	no

KERN_FILE

Returns the entire file table. The returned data consists of a single struct filehead followed by an array of struct files , 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 applies only 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_MAXVNODES

The maximum number of vnodes available on the system.

KERN_NGROUPS

The maximum number of supplementary groups.

KERN_OSRELDATE

The system release date in YYYYMM format (January 1996 is encoded as 199601).

KERN_OSRELEASE

The system release string.

KERN_OSREVISION

The system revision string.

KERN_OSTYPE

The system type 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 microkernel 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 the appropriate privileges can change the value.

Second level name	Type	Changeable
_SC_SHM_PATHMAX	int	no

_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 the appropriate privileges can 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(1M) 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 can 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 the appropriate privileges can 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	yes
IPCTL_REDIRECT	int	yes
IPCTL_RTEXPIRE	int	yes
IPCTL_RTMAXCACHE	int	yes
IPCTL_RTMINEXPIRE	int	yes
IPCTL_SOURCEROUTE	int	yes
IPCTL_TTL	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_REDIRECT

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_TTL

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_RFC1323	int	yes
TCPCTL_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_RFC1323

RFC1323 extensions

TCPCTL_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 the appropriate privileges can 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 the appropriate privileges can change the value.

Second level name	Type	Changeable
VFS_VFSCONF	struct	no
VFS_BUFMALLOCSPACE	int	no
NFS_NFSSTATS	struct	no
NFS_NFSPRIVPORT	int	yes

VFS_VFSCONF

Get configured file systems.

VFS_BUFMALLOCSPACE

This gauge indicates the current value of the mbuf space.

NFS_NFSSTATS

Get NFS statistics.

NFS_NFSPRIVPORT

Prohibit NFS to resvports .

RETURN VALUES

If the call to sysctl() is successful, 0 is returned. Otherwise -1 is returned and errno is set appropriately.

ERRORS

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_MAX_NAME .

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.

ENOTDIR

The name array specifies an intermediate rather than terminal name.

EOPNOTSUPP

The name array specifies a value that is unknown.

EPERM

An attempt was made to set a read-only value.

EPERM

A process without the appropriate privileges attempted to set a value.

EXAMPLES

---

The following example shows the retrieval of 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);

---

---

The following example shows the retrieval of 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);

---

FILES

For more information see the following files:

<netinet/icmp_var.h>

Definitions for fourth level ICMP identifiers.

<netinet/in.h>

Definitions for third level Internet identifiers and fourth level IP identifiers.

<netinet/udp_var.h>

Definitions for fourth level UDP identifiers.

<sys/gmon.h>

Definitions for third level profiling identifiers.

<sys/socket.h>

Definitions for second level network identifiers.

<sys/sysctl.h>

Definitions for top level identifiers, second level microkernel and hardware identifiers, and user level identifiers.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

SEE ALSO

sysctl(1M)

ChorusOS 5.0  Last Revised December 2001

NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | EXTENDED DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | FILES | ATTRIBUTES | SEE ALSO