sysctl()

Get or set information about the socket manager

Synopsis:

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

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

Arguments:

name

An array of integers that specifies the Management Information Base (MIB) style name of the item that you want to set or get; see below. The minimum number of entries in this array is two; the maximum is CTL_MAXNAME.

namelen

The length of the name.

oldp

NULL, or a pointer to a buffer where the function can store the old value.

oldlenp

NULL, or a pointer to a location that initially specifies the size of the oldp buffer. The function changes the value in this location to be the size of the old information stored in the oldp buffer.

newp

NULL, or a pointer to a buffer that holds the new value.

newlen

The size of the new value.

Library:

libsocket

Use the -l socket option to qcc to link against this library.

Description:

The sysctl() function retrieves information about the socket manager and allows processes with appropriate privileges to set this information. The data available from sysctl() consists of integers and tables. You can also get or set data using the sysctl utility at the command line.

The state is described using a Management Information Base (MIB) style name, specified in name, which is a namelen length array of integers.

---

For descriptions of the most commonly used variables, see the entry for sysctl in the Utilities Reference.

---

The sysctl() function copies the information for the specified variable 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. If the amount of data available is greater than the size of the buffer supplied, the call delivers as much data as fits in the buffer provided and returns with the error code ENOMEM. If you don't need the old value, you can set oldp and oldlenp to NULL.

You can determine the size of the available data by calling sysctl() with a NULL parameter for oldp. The function stores the size of the available data 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 specify a new value, set newp to point to a buffer of length newlen from which the requested value is to be taken. If you're not setting a new value, set newp to NULL and newlen to 0.

The top-level names are defined with a CTL_ prefix in <sys/sysctl.h>. The next and subsequent levels down are found in the following header files:

The <sys/sysctl.h> file defines the top-level identifiers like this:

#define	CTL_UNSPEC	0		/* unused */
#define	CTL_KERN	1		/* "high kernel": proc, limits */
#define	CTL_VM		2		/* virtual memory */
#define	CTL_VFS		3		/* file system, mount type is next */
#define	CTL_NET		4		/* network, see socket.h */
#define	CTL_DEBUG	5		/* debugging parameters */
#define	CTL_HW		6		/* generic cpu/io */
#define	CTL_MACHDEP	7		/* machine dependent */
#define	CTL_USER	8		/* user-level */
#define	CTL_DDB		9		/* in-kernel debugger */
#define	CTL_PROC	10		/* per-proc attr */
#define	CTL_VENDOR	11		/* vendor-specific data */
#define	CTL_EMUL	12		/* emulation-specific data */
#define	CTL_MAXID	13		/* number of valid top-level ids */

#define	CTL_NAMES { \
	{ 0, 0 }, \
	{ "kern", CTLTYPE_NODE }, \
	{ "vm", CTLTYPE_NODE }, \
	{ "vfs", CTLTYPE_NODE }, \
	{ "net", CTLTYPE_NODE }, \
	{ "debug", CTLTYPE_NODE }, \
	{ "hw", CTLTYPE_NODE }, \
	{ "machdep", CTLTYPE_NODE }, \
	{ "user", CTLTYPE_NODE }, \
	{ "ddb", CTLTYPE_NODE }, \
	{ "proc", CTLTYPE_NODE }, \
	{ "vendor", CTLTYPE_NODE }, \
	{ "emul", CTLTYPE_NODE }, \
}

Note how the CTL_* definitions correspond to the strings defined below. Let's look at how you'd build the array of integers from a few strings:

kern.clockrate

The top-level name (kern) corresponds to CTL_KERN, as shown above. The second-level name (clockrate) is also defined in <sys/sysctl.h>. The entries in the name array that you'd pass to sysctl() would be as follows:

Entry	Value	See:
0	CTL_KERN	<sys/sysctl.h>
1	KERN_CLOCKRATE	<sys/sysctl.h>

kern.mbuf.mblowat

Once again, the top-level name corresponds to CTL_KERN. The second-level name is defined in <sys/sysctl.h>, but you need to look in <sys/mbuf.h> for the third-level name. The entries in the name array would be as follows:

Entry	Value	See:
0	CTL_KERN	<sys/sysctl.h>
1	KERN_MBUF	<sys/sysctl.h>
2	MBUF_MBLOWAT	<sys/mbuf.h>

net.inet.tcp.mssdflt

The first-level name (net) corresponds to CTL_NET, as shown above. The second-level name (inet) is for information about Internet protocols, and is defined as one of the address families in <sys/socket>. The third-level name (tcp) is defined as one of the protocols in <netinet/in.h>, and the fourth-level name (mssdflt) is defined in <netinet/in_offload.h>.

The entries in the name array would be as follows:

Entry	Value	See:
0	CTL_NET	<sys/sysctl.h>
1	AF_INET	<sys/socket.h>
2	IPPROTO_TCP	<netinet/in.h>
3	TCPCTL_MSSDFLT	<netinet/in_offload.h>

For full details, see the source for the sysctl utility in Foundry 27 (http://community.qnx.com/sf/sfmain/do/home).

Returns:

0

Success.

-1

An error occurred (errno is set).

Errors:

EFAULT

One of the buffers name, oldp, newp, or the length pointer oldlenp contains an invalid address.

EINVAL

The name array is less than two or greater than CTL_MAXNAME entries long, or a non-NULL newp was 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 an unknown value.

EPERM

An attempt was made to set a read-only value, or a process without the appropriate privilege attempted to set or change a value protected by the current system security level.

Examples:

The following code fragment checks whether the UDP packets checksum is enabled:

int mib[5], val;
size_t len;

mib[0] = CTL_NET;
mib[1] = AF_INET;
mib[2] = IPPROTO_UDP;
mib[3] = UDPCTL_CHECKSUM;
len = sizeof(val);
sysctl(mib, 4, &val, &len, NULL, 0);

Classification:

Unix

See also:

ICMP6, ICMP, INET6, IPv6, IP, IPsec, ROUTE, TCP, UDP, UNIX protocols

sysctl in the Utilities Reference