The sysctl() call performs special operations on the TCP/IP stack. Unlike getsockopt() or setsockopt(), sysctl() accesses and modifies systemwide parameter values for the entire TCP/IP stack.
Syntax
#include <types.h> #include <netinet\in.h> #include <netinet\ip_var.h> #include <sys\socket.h> #include <sys\sysctl.h> int sysctl(mib, namelen, oldp, oldenp, newp, newlen) int *mib; u_int namelen; void *oldp; size_t newlen; size_t *oldlenp; void *newp;
Parameters
mib
Description
The sysctl() call is functionally similar to the ioctl() call but does not need a socket to carry the options to and from the stack.
The sysctl() function retrieves stack parameters and allows them to be set. The information available from sysctl() consists of integers, strings, and tables. Unless explicitly noted below, sysctl() returns a consistent snapshot of the data requested. Consistency is achieved by locking the destination buffer into memory so that the data may be copied without blocking.
Calls to sysctl() are serialized to avoid deadlock. The state is described using a Management Information Base (MIB) style name, listed below, which is a namelen length array of integers. 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. 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 SOCENOMEM.
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 oldenp. 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.
An Inetcfg sysctl needs a fifth mib argument, mib[4], to specify the actual inet configuration command.
All route sysctl() calls use another additional argument to be carried in mib[5] for rt_flags. The old newp may be pointing to a single integer or char buffer. Also, there are two special control structures (inetver_ctl and intecfg_ctl) used as oldp/newp structures. Similarly, for statistics the xxxstat structures should be used.
An application uses the OS2_MEMMAPIO sysctl() call to request the TCP/IP stack to provide kernel memory for performing High Performance Send (HPS). One such call can return up to 60K (as 15 4K buffers) of memory. The calling application provides an array named oldp of up to 15 pointers (to char). On return from this call, these pointers point to the 4K buffers. The memory acquired in this way is now owned by the application, and it resides in the address space of this application. As a result, the application is now responsible for the management of this memory from a reusability point of view. Applications can use either semaphores or the OS2_QUERY_MEMMAPIO sysctl() call for this purpose. Typically, before calling the next high performance send (which may use one of these buffers), the application needs to verify that the buffers are free to be reused. Sysctl() supports a maximum of 64 such calls. Thus, the kernel can provide up to 64 times 60K of high speed send memory to an application. An ENOMEM error code is returned to any sysctl() call beyond this limit. A sample of usage of this call for supporting HPS is contained in High Performance Send.
An application uses the OS2_QUERY_MEMMAPIO sysctl() call to verify the reusability of the buffers provided by the kernel through the OS2_MEMMAPIO sysctl() call. This call sends the oldp array of pointers which were filled in by the kernel during the OS2_MEMMAPIO sysctl() call. oldenp is used to pass the number of 4K buffers referred to in the oldp array. If a particular pointer in the oldp array is left unchanged on return from this call, that buffer has been freed for reuse. Conversely, if a particular pointer in this array is returned as NULL, this buffer is not yet freed and may not be reused. It is the responsibility of the application to make these checks. Alternatively, an application may use semaphores to manage the reusability of these buffers. The oldp array can be passed with any number of HPS buffers in a single call and this number of buffers (oldenp) need not be an integer multiple of 15. The HPS buffers in oldp need not be arranged in the same order in which they were obtained. Applications should save a copy of the obtained HPS buffer pointers before calling OS2_QUERY_MEMMAPIO, so that the pointers are not lost if the buffers are not available.
Values
The values that are supported for different categories of mib values are listed in the following tables.
The generic mib array has the following structure
┌──────────────────────────────────────────────────────────────────┐│mib Index Description │ ├──────────────────────────────────────────────────────────────────┤ │0 Top Level identifier │ ├──────────────────────────────────────────────────────────────────┤ │1 Protocol Family │ ├──────────────────────────────────────────────────────────────────┤ │2 Protocol │ ├──────────────────────────────────────────────────────────────────┤ │3 Address Family or Control Command │ ├──────────────────────────────────────────────────────────────────┤ │4 Control Command │ ├──────────────────────────────────────────────────────────────────┤ │5 Flags, etc. │ └──────────────────────────────────────────────────────────────────┘
The mib[0] Top Level values are:
┌─────────────────────────────────────────────────────────────────┐ │Value Description │ ├─────────────────────────────────────────────────────────────────┤ │CTL_KERN Sockets (kernel) domain. │ ├─────────────────────────────────────────────────────────────────┤ │CTL_NET Routing domain. │ ├─────────────────────────────────────────────────────────────────┤ │CTL_OS2 Local Interprocess Communication│ │ (afos2) domain. │ └─────────────────────────────────────────────────────────────────┘
The mib[1] Protocol Family values are:
┌─────────────────────────────────────────────────────────────────┐ │Value Description │ ├─────────────────────────────────────────────────────────────────┤ │PF_INET Internet protocol family. │ ├─────────────────────────────────────────────────────────────────┤ │PF_OS2 LIPC (afos2) protocol family. │ ├─────────────────────────────────────────────────────────────────┤ │PF_ROUTE Route protocol family. │ ├─────────────────────────────────────────────────────────────────┤ │KERN_HOSTID │ └─────────────────────────────────────────────────────────────────┘
The mib[2] Protocols values are:
┌─────────────────────────────────────────────────────────────────┐ │Value Description │ ├─────────────────────────────────────────────────────────────────┤ │IPPROTO_IP Internet Protocol. │ ├─────────────────────────────────────────────────────────────────┤ │IPPROTO_TCP Transmission Control Protocol. │ ├─────────────────────────────────────────────────────────────────┤ │IPPROTO_UDP User Datagram Protocol. │ └─────────────────────────────────────────────────────────────────┘
The mib[3] Control Command values for inetcfg are:
┌─────────────────────────────────────────────────────────────────┐ │Value Description │ ├─────────────────────────────────────────────────────────────────┤ │IPCTL_INETCFG IP inet configuration. │ ├─────────────────────────────────────────────────────────────────┤ │TCPCTL_INETCFG TCP inet configuration. │ ├─────────────────────────────────────────────────────────────────┤ │UDPCTL_INETCFG UDP inet configuration. │ ├─────────────────────────────────────────────────────────────────┤ │LIPCCTL_INETCFG LIPC inet configuration. │ └─────────────────────────────────────────────────────────────────┘
The following table is an overview of the sysctl() calls structure, with links to the descriptions of the mib values. The table is the calling tree to get to individual leaves, which are the supported mib values. You read the table by looking on the right-hand side for the leaf for the value you are seeking, then taking the link to the table that defines that value and describes the function of the value. For example, the first leaf, KERNCTL_INETVER, will get you to the table for mib[0]=CTL_KERN, mib[1]=KERN_HOSTID, and mib[2]=IPPROTO_IP.
mib numbers
[0] [1] [2] [3] [4] [5]
CTL_KERN
....KERN_HOSTID
........IPPROTO_IP
............KERNCTL_INETVER on page mibs for INET Version (sockets.sys).
CTL_OS2
....PF_OS2
........IPPROTO_IP
............LIPCCTL_INETVER on page mibs for INET Version (afos2.sys).
............LIPCCTL_INETCFG
................LIPCCTL_DG_RECVSPACE on page mibs for afos2 inetconfig.
................LIPCCTL_DG_SENDSPACE on page mibs for afos2 inetconfig.
................LIPCCTL_ST_RECVSPACE on page mibs for afos2 inetconfig.
................LIPCCTL_ST_SENDSPACE on page mibs for afos2 inetconfig.
....PF_INET
........IPPROTO_IP
............OS2_MEMMAPIO on page mibs for High Performance Memory.
............OS2_QUERY_MEMMAPIO on page mibs for High Performance Memory.
CTL_NET
....PF_INET
........IPPROTO_TCP
............TCPCTL_INETCFG
................TCPCTL_CC on page mibs for TCPCTL inetconfig.
................TCPCTL_KEEPCNT on page mibs for TCPCTL inetconfig.
................TCPCTL_LINGERTIME on page mibs for TCPCTL inetconfig.
................TCPCTL_MSL on page mibs for TCPCTL inetconfig.
................TCPCTL_MTU on page mibs for TCPCTL inetconfig.
................TCPCTL_REALSLOW on page mibs for TCPCTL inetconfig.
................TCPCTL_TCPRWIN on page mibs for TCPCTL inetconfig.
................TCPCTL_TCPSWIN on page mibs for TCPCTL inetconfig.
................TCPCTL_TIMESTMP on page mibs for TCPCTL inetconfig.
................TCPCTL_TTL on page mibs for TCPCTL inetconfig.
................TCPCTL_WINSCALE on page mibs for TCPCTL inetconfig.
............TCPCTL_MSSDFLT on page mibs for TCPCTL.
............TCPCTL_RTTDFLT on page mibs for TCPCTL.
............TCPCTL_STATS on page mibs for TCPCTL.
........IPPROTO_UDP
............UDPCTL_INETCFG
................UDPCTL_TTL on page mibs for UDPCTL inetconfig.
................UDPCTL_UDPRWIN on page mibs for UDPCTL inetconfig.
................UDPCTL_UDPSWIN on page mibs for UDPCTL inetconfig.
............UDPCTL_CHECKSUM on page mibs for UDPCTL.
............UDPCTL_STATS on page mibs for UDPCTL.
........IPPROTO_IP
............IPCTL_INETVER on page mibs for IPCTL.
............IPCTL_FORWARDING on page mibs for IPCTL.
............IPCTL_SENDREDIRECTS on page mibs for IPCTL.
............IPCTL_INETCFG
................FRAGCTL_TTL on page mibs for IPCTL inetconfig.
................ICMPCTL_TTL on page mibs for IPCTL inetconfig.
................IPCTL_ARPTKILLC on page mibs for IPCTL inetconfig.
................IPCTL_ARPTKILLI on page mibs for IPCTL inetconfig.
................IPCTL_FIREWALL on page mibs for IPCTL inetconfig.
................IPCTL_FORWARD on page mibs for IPCTL inetconfig.
................IPCTL_MULTIDEFROUTES on page mibs for IPCTL inetconfig.
................IPCTL_SYNATTACK on page mibs for IPCTL inetconfig.
........IPPROTO_ICMP
............ICMPCTL_ECHOREPL on page mibs for ICMPCTL.
............ICMPCTL_MASKREPL on page mibs for ICMPCTL.
............ICMPCTL_STATS on page mibs for ICMPCTL.
....PF_ROUTE
........0 (wildcard)
............0 (wildcard)
................NET_RT_DUMP on page mibs for ROUTE.
....................NET_RT_LLINFO on page mibs for ROUTE with Flags.
................NET_RT_FLAGS on page mibs for ROUTE.
................NET_RT_IFLIST on page mibs for ROUTE.
[0] [1] [2] [3] [4] [5]
mib numbers
Return Values
The requested values are returned in the newp parameter. The sysctl() call itself returns the number of bytes copied, if the call is successful. Otherwise, -1 is returned and the errno value is set appropriately.
Error Code
Related Calls