Technical Reference: Communications, Volume 2

setsockopt Subroutine

Purpose

Sets socket options.

Library

Standard C Library (libc.a)

Syntax

#include <sys/types.h>
#include <sys/socket.h>
#include <sys/socketvar.h>
#include <sys/atmsock.h> /*Needed for SOCK_CONN_DGRAM socket type 
only*/

int setsockopt (Socket, Level, OptionName, OptionValue, OptionLength) int Socket, Level, OptionName; const void * OptionValue; size_t OptionLength;

Description

The setsockopt subroutine sets options associated with a socket. Options can exist at multiple protocol levels. The options are always present at the uppermost socket level.

The setsockopt subroutine provides an application program with the means to control a socket communication. An application program can use the setsockopt subroutine to enable debugging at the protocol level, allocate buffer space, control time outs, or permit socket data broadcasts. The /usr/include/sys/socket.h file defines all the options available to the setsockopt subroutine.

When setting socket options, specify the protocol level at which the option resides and the name of the option.

Use the parameters OptionValue and OptionLength to access option values for the setsockopt subroutine. These parameters identify a buffer in which the value for the requested option or options is returned.

All applications containing the setsockopt subroutine must be compiled with _BSD set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.

Parameters

Socket	Specifies the unique socket name.
Level	Specifies the protocol level at which the option resides. To set options at: Socket level Specifies the Level parameter as SOL_SOCKET. Other levels Supplies the appropriate protocol number for the protocol controlling the option. For example, to indicate that an option will be interpreted by the TCP protocol, set the Level parameter to the protocol number of TCP, as defined in the netinet/in.h file. Similarly, to indicate that an option will be interpreted by ATM protocol, set the Level parameter to NDDPROTO_ATM, as defined in sys/atmsock.h.
OptionName	Specifies the option to set. The OptionName parameter and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The sys/socket.h file defines the socket protocol level options. The netinet/tcp.h file defines the TCP protocol level options. The socket level options can be enabled or disabled; they operate in a toggle fashion. The following list defines socket protocol level options found in the sys/socket.h file: SO_DEBUG Turns on recording of debugging information. This option enables or disables debugging in the underlying protocol modules. SO_REUSEADDR Specifies that the rules used in validating addresses supplied by a bind subroutine should allow reuse of a local port. SO_REUSEADDR allows an application to explicitly deny subsequent bind subroutine to the port/address of the socket with SO_REUSEADDR set. This allows an application to block other applications from binding with the bind subroutine. SO_REUSEPORT Specifies that the rules used in validating addresses supplied by a bind subroutine should allow reuse of a local port/address combination. Each binding of the port/address combination must specify the SO_REUSEPORT socket option SO_CKSUMREV Enables performance enhancements in the protocol layers. If the protocol supports this option, enabling causes the protocol to defer checksum verification until the user's data is moved into the user's buffer (on recv, recvfrom, read, or recvmsg thread). This can cause applications to be awakened when no data is available, in the case of a checksum error. In this case, EAGAIN is returned. Applications that set this option must handle the EAGAIN error code returned from a receive call. SO_KEEPALIVE Monitors the activity of a connection by enabling or disabling the periodic transmission of ACK messages on a connected socket. The idle interval time can be designated using the TCP/IP no command. Broken connections are discussed in "Understanding Socket Types and Protocols" in AIX 5L Version 5.2 Communications Programming Concepts. SO_DONTROUTE Does not apply routing on outgoing messages. Indicates that outgoing messages should bypass the standard routing facilities. Instead, they are directed to the appropriate network interface according to the network portion of the destination address.
	SO_BROADCAST Permits sending of broadcast messages. SO_LINGER Lingers on a close subroutine if data is present. This option controls the action taken when an unsent messages queue exists for a socket, and a process performs a close subroutine on the socket. If SO_LINGER is set, the system blocks the process during the close subroutine until it can transmit the data or until the time expires. If SO_LINGER is not specified and a close subroutine is issued, the system handles the call in a way that allows the process to continue as quickly as possible. The sys/socket.h file defines the linger structure that contains the l_linger value for specifying linger time interval. If linger time is set to anything but 0, the system tries to send any messages queued on the socket. The maximum value that l_linger can be set to is 65535. SO_OOBINLINE Leaves received out-of-band data (data marked urgent) in line. SO_SNDBUF Sets send buffer size. SO_RCVBUF Sets receive buffer size. SO_SNDLOWAT Sets send low-water mark. SO_RCVLOWAT Sets receive low-water mark. SO_SNDTIMEO Sets send time out. This option is setable, but currently not used. SO_RCVTIMEO Sets receive time out. This option is setable, but currently not used. SO_ERROR Sets the retrieval of error status and clear. SO_TYPE Sets the retrieval of a socket type.
	The following list defines TCP protocol level options found in the netinet/tcp.h file: TCP_KEEPCNT Specifies the maximum number of keepalive packets to be sent to validate a connection. This socket option value is inherited from the parent socket. The default is 8. TCP_KEEPIDLE Specifies the number of seconds of idle time on a connection after which TCP sends a keepalive packet. This socket option value is inherited from the parent socket from the accept system call. The default value is 7200 seconds (14400 half seconds). TCP_KEEPINTVL Specifies the interval of time between keepalive packets. It is measured in seconds. This socket option value is inherited from the parent socket from the accept system call. The default value is 75 seconds (150 half seconds). TCP_NODELAY Specifies whether TCP should follow the Nagle algorithm for deciding when to send data. By default, TCP will follow the Nagle algorithm. To disable this behavior, applications can enable TCP_NODELAY to force TCP to always send data immediately. For example, TCP_NODELAY should be used when there is an application using TCP for a request/response. TCP_RFC1323 Enables or disables RFC 1323 enhancements on the specified TCP socket. An application might contain the following lines to enable RFC 1323: int on=1; setsockopt(s,IPPROTO_TCP,TCP_RFC1323,&on,sizeof(on)); TCP_STDURG Enables or disables RFC 1122 compliant urgent point handling. By default, TCP implements urgent pointer behavior compliant with the 4.2 BSD operating system, i.e., this option defaults to 0.
	Beginning at AIX 4.3.2, TCP protocol level socket options are inherited from listening sockets to new sockets. Prior to 4.3.2, only the TCP_RFC1323 option was inherited. The following list defines ATM protocol level options found in the sys/atmsock.h file: SO_ATM_PARAM Sets all ATM parameters. This socket option can be used instead of using individual sockets options described below. It uses the connect_ie structure defined in sys/call_ie.h file. SO_ATM_AAL_PARM Sets ATM AAL(Adaptation Layer) parameters. It uses the aal_parm structure defined in sys/call_ie.h file. SO_ATM_TRAFFIC_DES Sets ATM Traffic Descriptor values. It uses the traffic structure defined in sys/call_ie.h file. SO_ATM_BEARER Sets ATM Bearer capability. It uses the bearer structure defined in sys/call_ie.h file. SO_ATM_BHLI Sets ATM Broadband High Layer Information. It uses the bhli structure defined in sys/call_ie.h file. SO_ATM_BLLI Sets ATM Broadband Low Layer Information. It uses the blli structure defined in sys/call_ie.h file. SO_ATM_QOS Sets ATM Quality Of Service values. It uses the qos_parm structure defined in sys/call_ie.h file. SO_ATM_TRANSIT_SEL Sets ATM Transit Selector Carrier. It uses the transit_sel structure defined in sys/call_ie.h file. SO_ATM_ACCEPT Indicates acceptance of an incoming ATM call, which was indicated to the application via ACCEPT system call. This must be issues for the incoming connection to be fully established. This allows negotiation of ATM parameters. SO_ATM_MAX_PEND Sets the number of outstanding transmit buffers that are permitted before an error indication is returned to applications as a result of a transmit operation. This option is only valid for non best effort types of virtual circuits. OptionValue/OptionLength point to a byte which contains the value that this parameter will be set to.
OptionValue	The OptionValue parameter takes an Int parameter. To enable a Boolean option, set the OptionValue parameter to a nonzero value. To disable an option, set the OptionValue parameter to 0. The following options enable and disable in the same manner: SO_DEBUG SO_REUSEADDR SO_KEEPALIVE SO_DONTROUTE SO_BROADCAST SO_OOBINLINE SO_LINGER TCP_RFC1323
OptionLength	The OptionLength parameter contains the size of the buffer pointed to by the OptionValue parameter.

Options at other protocol levels vary in format and name.

IP level (IPPROTO_IP level) options are defined as follows:

IP_DONTFRAG	Sets DF bit from now on for every packet in the IP header.
IP_FINDPMTU	Sets enable/disable PMTU discovery for this path. Protocol level path MTU discovery should be enabled for the discovery to happen.
IP_PMTUAGE	Sets the age of PMTU. Specifies the frequency of PMT reductions discovery for the session. Setting it to 0 (zero) implies infinite age and PMTU reduction discovery will not be attempted. This will replace the previously set PMTU age. The new PMTU age will become effective after the currently set timer expires.
IP_TTL	Sets the time-to-live field in the IP header for every packet. However, for raw sockets, the default MAXTTL value will be used while sending the messages irrespective of the value set using the setsockopt subroutine.
IP_HDRINCL	This option allows users to build their own IP header. It indicates that the complete IP header is included with the data and can be used only for raw sockets.

IPV6 level (IPPROTO_IPV6 level) options are defined as follows:

IPV6_V6ONLY	Restricts AF_INET6 sockets to IPV6 communications only.
	Option Type:	int (boolean interpretation)
IPV6_UNICAST_HOPS	Allows the user to set the outgoing hop limit for unicast IPV6 packets.
	Option Type:	int (x)
	Option Value:	x < -1	Error EINVAL
		x == -1	Use kernel default
		0 <= x <= 255	Use x
		x >= 256	Error EINVAL
IPV6_MULTICAST_HOPS	Allows the user to set the outgoing hop limit for multicast IPV6 packets.
	Option Type:	int (x)
	Option Value:	Interpretation is the same as IPV6_UNICAST_HOPS (listed above).
IPV6_MULTICAST_IF	Allows the user to specify the interface being used for outgoing multicast packets. If specified as 0, the system selects the outgoing interface.
	Option Type:	unsigned int (index of interface to use)
IPV6_MULTICAST_LOOP	If a multicast datagram is sent to a group that the sending host belongs to, a copy of the datagram is looped back by the IP layer for local delivery (if the option is set to 1). If the option is set to 0, a copy is not looped back.
	Option Type:	unsigned int
IPV6_JOIN_GROUP	Joins a multicast group on a specified local interface. If the interface index is specified as 0, the kernel chooses the local interface.
	Option Type:	struct ipv6_mreq as defined in the netinet/in.h file
IPV6_LEAVE_GROUP	Leaves a multicast group on a specified interface.
	Option Type:	struct ipv6_mreq as defined in the netinet/in.h file
IPV6_CHECKSUM	Specifies that the kernel computes checksums over the data and the pseudo-IPv6 header for a raw socket. The kernel will compute the checksums for outgoing packets as well as verify checksums for incoming packets on that socket. Incoming packets with incorrect checksums will be discarded. This option is disabled by default.
	Option Type:	int
	Option Value:	Offsets into the user data where the checksum result must be stored. This must be a positive even value. Setting the value to -1 will disable the option.

ICMPV6 level (IPPROTO_ICMPV6 level) options are defined as follows:

ICMP6_FILTER	Allows the user to filter ICMPV6 messages by the ICMPV6 type field. In order to clear an existing filter, issue a setsockopt call with zero length.
	Option Type:	The icmp6_filter structure defined in the netinet/icmp6.h file.

Return Values

Upon successful completion, a value of 0 is returned.

If the setsockopt subroutine is unsuccessful, the subroutine handler performs the following functions:

Returns a value of -1 to the calling program.

Moves an error code, indicating the specific error, into the errno global variable. For further explanation of the errno variable see Error Notification Object Class in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

Error Codes

The setsockopt subroutine is unsuccessful if any of the following errors occurs:

EBADF	The Socket parameter is not valid.
ENOTSOCK	The Socket parameter refers to a file, not a socket.
ENOPROTOOPT	The option is unknown.
EFAULT	The Address parameter is not in a writable part of the user address space.

Examples

To mark a socket for broadcasting:

int on=1;
setsockopt(s, SOL_SOCKET, SO_BROADCAST, &on, sizeof(on));

Related Information

The no command.

The bind subroutine, endprotoent subroutine, getprotobynumber subroutine, getprotoent subroutine, getsockopt subroutine, setprotoent subroutine, socket subroutine.

Sockets Overview, Understanding Socket Options, Understanding Socket Types and Protocols in AIX 5L Version 5.2 Communications Programming Concepts.