[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Communications Technical Reference, 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.

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 Version 4.3 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. Although a linger interval can be specified in seconds, the system ignores the specified time and makes repeated attempts to send unsent messages.

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_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_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_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 the 4.3.2 level of AIX, 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.

Return Values

Upon successful completion, a value of 0 is returned.

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

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

Implementation Specifics

The setsockopt subroutine is part of Base Operating System (BOS) Runtime.

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.

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 Version 4.3 Communications Programming Concepts.

[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]