setsockopt Subroutine

Edit online

Purpose

Sets the 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;
socklen_t OptionLength;

Description

The setsockopt subroutine sets the options that are associated with a socket. The options can exist at a multiple protocol levels. The options are 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 timeouts, or to allow socket data broadcasts. The /usr/include/sys/socket.h file defines the options that are available to the setsockopt subroutine.

Specify the protocol level at which the option is located and the name of the option when you set socket options.

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

The applications that contain the setsockopt subroutine must be compiled with the _BSD macro set to a specific value. The acceptable values are 43 and 44. In addition, all socket applications must include the Berkeley Software Distribution (BSD) libbsd.a library.

Parameters

Table 1. Parameters
Item Description
Socket Specifies the unique name of the socket.
Level Specifies the protocol level at which the option is located. You can set the socket options at the following levels:
Socket level
Specifies the Level parameter as the SOL_SOCKET option.
Other levels
Supplies the appropriate protocol number for the protocol that controls the option. For example, to indicate that the TCP protocol interprets the option, set the Level parameter to the protocol number of TCP as defined in the netinet/in.h file. Similarly, to indicate that the ATM protocol interprets the option, set the Level parameter to the NDDPROTO_ATM option as defined in sys/atmsock.h file.
OptionName Specifies the option to set. The OptionName parameter and the 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. You can enable or disable the socket level options and they operate in a toggle fashion.

The following list defines the socket protocol level options that are available in the sys/socket.h file:

SO_DEBUG
Enables or disables the debugging in the underlying protocol modules. The SO_DEBUG turns on the recording of the debugging information. Set this option in one of the following ways at the command level:
  • To turn on or turn OFF this option for the existing sockets by using the sodebug command.
  • To turn on this option for the specific service, you must specify the |DEBUG[=level] in the wait/nowait field of a service in the inetd.conf file.
  • To turn on or turn OFF this option for all the subsequent sockets that are created by the process, you must set the sodebug_env parameter to no. Specify the SODEBUG=level in the process environment.
The value for the level parameter can be either min, normal, or detail.
SO_REUSEADDR
Specifies that the rules used in validating addresses that are supplied by a bind subroutine must allow reuse of a local port.

SO_REUSEADDR option allows an application to explicitly deny subsequent bind subroutine to the port or address of the socket with the SO_REUSEADDR socket option. This allows an application to block other applications from binding with the bind subroutine.

SO_REUSEPORT
Specifies that the rules used in validating addresses that are supplied by a bind subroutine must allow reuse of a local port or address combination. Each binding of the port or address combination must specify the SO_REUSEPORT socket option
SO_CKSUMREV
Enables the performance enhancements in the protocol layers. If the protocol supports the SO_CKSUMREV option, enabling causes the protocol to defer checksum verification until the data of the user is moved into the buffer of the user (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 and the EAGAIN is returned. The applications that set this option must handle the EAGAIN error code rturned from a receive call.
SO_KEEPALIVE
Enables or disables the periodic transmission of ACK messages on a connected socket to monitor the activity of a connection. The idle interval time can be designated by using the Transmission Control Protocol/Internet Protocol (TCP/IP) no command. For more information on broken connections, see Understanding Socket Types and Protocols in Communications Programming Concepts.
OptionName
SO_DONTROUTE
Does not apply routing on outgoing messages. Indicates that outgoing messages must 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 the broadcast messages.
SO_LINGER
Controls the action that is taken when an unsent messages queue exists for a socket, and a process performs a close subroutine on the socket. Lingers on a close subroutine if data is present. If SO_LINGER option is set, the system blocks the process during the close subroutine until it can transmit the data or until the time expires. If you do not specify the SO_LINGER option 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 member to specify the linger time interval. If the linger time is set to anything but 0, the system tries to send any messages that are queued on the socket. The maximum value that the l_linger member can be set to is 65535. If the application has requested the SPEC1170 compliant behavior by exporting the XPG_SUS_ENV environment variable, the linger time is n seconds. Otherwise, the linger time is n per 100 seconds (ticks), where n is the value of the l_linger member.

SO_OOBINLINE
Leaves the received out-of-band data (data marked urgent) in line.
SO_SNDBUF
Sets the send buffer size.
SO_RCVBUF
Sets the receive buffer size.
SO_SNDLOWAT
Sets the send low-water mark.
SO_RCVLOWAT
Sets the receive a low-water mark.
SO_SNDTIMEO
Sets the maximum length of time that a send-type function that is called with socket, for example send or write subroutines, can remain blocked before it completes. The SO_SNDTIMEO option requires a TIMEVAL structure. The TIMEVAL structure contains the number of seconds and microseconds. You can specify the TIMEVAL value in microseconds. However, the internal TCP/IP timers that are used to implement this function have a granularity of 10 milliseconds. If the timeout value is set to a value less than 10 milliseconds, it results in the same behavior as if the timeout value is not set.
SO_RCVTIMEO
Sets the maximum length of time that a receive-type function that is called with socket, for example recv or read subroutines, can wait before it completes. The SO_RCVTIMEO option requires a TIMEVAL structure. The TIMEVAL structure contains the number of seconds and microseconds. You can specify the TIMEVAL value in microseconds. However, the internal TCP/IP timers that are used to implement this function have a granularity of 10 milliseconds. If the timeout value is set to a value less than 10 milliseconds, it results in the same behavior as if the timeout value is not set.
SO_ERROR
Sets the retrieval of error status and clear.
SO_TYPE
Sets the retrieval of a socket type.
OptionName

The following list defines the TCP protocol level options that are available in the netinet/tcp.h file:

TCP_CWND_IF
Increases the factor of the TCP congestion window (cwnd) during the congestion avoidance. The value must be in the range 0 to 100 (0 is disable). Enable the tcp_cwnd_modified network tunable option.
TCP_CWND_DF
Decreases the factor of the TCP cwnd during the congestion avoidance. The value must be in the range 0 to 100 (0 is disable). Enable the tcp_cwnd_modified network tunable option.
TCP_NOTENTER_SSTART
Avoids reentering the slow start after the retransmit timeout that might reset the cwnd to the initial window size, instead of the size of the current slow-start threshold (ss_threshold) value or half of the maximum cwnd (max cwnd/2). The values are 1 for enable and 0 for disable. Enable the tcp_cwnd_modified network tunable option.
TCP_ NOREDUCE_CWND_IN_FRXMT
Does not decrease the cwnd size in the fast retransmit phrase. The values are 1 for enable and 0 for disable. Enable the tcp_cwnd_modified network tunable option.
TCP_ NOREDUCE_CWND_EXIT_FRXMT
Does not decrease the cwnd size when exits the fast retransmit phrase. The values are 1 for enable and 0 for disable. Enable the tcp_cwnd_modified network tunable option.
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 value is 8.
TCP_KEEPIDLE
Specifies the number of seconds of idle time on a connection after which the 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 each keepalive packets. The interval of time 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 the TCP must follow the Nagle algorithm for deciding when to send the data. By default, TCP follows the Nagle algorithm. To disable this behavior, applications can enable the TCP_NODELAY option to force to TCP to send the data immediately. For example, TCP_NODELAY option must be used when there is an application by using the TCP for a request or response.
OptionName
TCP_RFC1323
Enables or disables the RFC 1323 enhancements on the specified TCP socket. An application might contain the following lines to enable the RFC 1323: 
int on=1;
setsockopt(s,IPPROTO_TCP,TCP_RFC1323,&on,
           sizeof(on));
TCP_STDURG
Enables or disables the RFC 1122 compliant urgent point handling. By default, the TCP implements urgent pointer behavior compliant with the 4.2 BSD operating system, that is, this option defaults to 0.
TCP_NODELAYACK
Specifies whether the TCP needs to send immediate acknowledgment packets to the sender. If this option is not set, TCP delays sending the acknowledgment packets by up to 200 ms. This allows the acknowledgements to be sent along with the data on a response and minimizes the system overhead. If this TCP option is set, it might cause a slight increase in the system overhead, but can result in a higher performance for the network transfers if the sender is waiting on the acknowledgements of the receiver.

The TCP protocol level socket options are inherited from listening sockets to new sockets.

The following list defines the ATM protocol-level options that are available in the sys/atmsock.h file:

SO_ATM_PARAM
Sets the ATM parameters. You can use the SO_ATM_PARAM socket option instead of using the individual sockets options described below. It uses the connect_ie structure that is defined in the sys/call_ie.h file.
SO_ATM_AAL_PARM
Sets ATM AAL (Adaptation Layer) parameters. It uses the aal_parm structure that is defined in the sys/call_ie.h file.
SO_ATM_TRAFFIC_DES
Sets the ATM Traffic Descriptor values. It uses the traffic structure that is defined in the sys/call_ie.h file.
SO_ATM_BEARER
Sets the ATM bearer capability. It uses the bearer structure that is defined in the sys/call_ie.h file.
SO_ATM_BHLI
Sets the ATM broadband high layer information. It uses the bhli structure that is defined in the sys/call_ie.h file.
SO_ATM_BLLI
Sets the ATM broadband low layer information. It uses the blli structure that is defined in the sys/call_ie.h file.
SO_ATM_QOS
Sets the ATM quality of service values. It uses the qos_parm structure that is defined in the sys/call_ie.h file.
SO_ATM_TRANSIT_SEL
Sets the ATM Transit Selector Carrier. It uses the transit_sel structure that is defined in the sys/call_ie.h file.
OptionName
SO_ATM_ACCEPT
Indicates the acceptance of an incoming ATM call that is indicated to the application through the ACCEPT system call. This must be issues for the incoming connection to be fully established. This allows negotiation of the 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. The OptionValue or OptionLength parameters points to a byte that contains the value that this parameter is set to.

The following list defines the IPPROTO_TCP protocol-level options that are available in the netinet/sctp.h file:

SCTP_PEER_ADDR_PARAMS
Enables or disables heartbeats for an association and modifies the heartbeat interval of the association. This option uses the sctp_paddrparams structure that is defined in the netinet/sctp.h file. For spp_address field, the AIX® supports only wildcard address now. The SPP_HB_ENABLE, SPP_HB_DISABLE, and SPP_HB_TIME_ISZERO flags are supported for the spp_flags field. You can set the spp_hbinterval field to a minimum value of 50 milliseconds.
SCTP_MAXSEG
Sets the maximum size of any outgoing SCTP DATA chunk. If the message is larger than the specified size, the SCTP fragments the message into the specified size. It uses the sctp_assoc_value structure that is defined in the netinet/sctp.h file.
OptionValue The OptionValue parameter takes an Int parameter. To enable a Boolean option, you must set the OptionValue parameter to a nonzero value. To disable a Boolean option, set the OptionValue parameter to 0.

The following options are enabled and disabled 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.

Table 2. IP level options
Item Description
IP_DONTFRAG Sets DF bit from now on for every packet in the IP header. Use the IP_DONTFRAG option to detect decreases in Path MTU (PMTU), UDP applications.
IP_FINDPMTU Sets enable or disable PMTU discovery for this path. Enable the protocol-level path to MTU discovery for the discovery to happen.
IP_PMTUAGE Sets the age of the PMTU. Specifies the frequency of the PMT reductions discovery for the session. Setting the PMTU age to 0 implies an infinite age and PMTU reduction discovery is not attempted and replaces the previously set PMTU age. The new PMTU age is effective after the currently set timer expires. This option is unused because UDP applications must set the IP_DONTFRAG socket to detect decreases in PMTU immediately.
IP_TTL Sets the time-to-live (TTL) field in the IP header for every packet. However, for raw sockets, the default MAXTTL value is used while sending the messages irrespective of the value set by using the setsockopt subroutine.
IP_HDRINCL Allows you to build your own IP header. It indicates that the complete IP header is included with the data and can be used only for raw sockets.
IP_ADD_MEMBERSHIP Joins a multicast group as specified in the OptionValue parameter of the ip_mreq structure type.
IP_DROP_MEMBERSHIP Leaves a multicast group as specified in the OptionValue parameter of the ip_mreq structure type.
IP_MULTICAST_IF Permits sending of multicast messages on an interface as specified in the OptionValue parameter of the ip_addr structure type. An address of INADDR_ANY (0x000000000) removes the previous selection of an interface in the multicast options. If you do not specify the interface, the interface leading to the default route is used.
IP_MULTICAST_LOOP Sets a multicast loopback, determining whether the transmitted messages are delivered to the sending host. An OptionValue parameter of the char type controls the loopback to be ON or OFF.
IP_MULTICAST_TTL Sets the TTL for multicast packets. An OptionValue parameter of the char type sets the value of TTL that ranges from 0 to 255.
IP_BLOCK_SOURCE Blocks the data from a given source to a given group.
IP_UNBLOCK_SOURCE Unblocks a blocked source to undo the IP_BLOCK_SOURCE operation.
IP_ADD_SOURCE_MEMBERSHIP Joins a source-specific multicast group. If the host is a member of the group, accept data from the source. Otherwise, join the group and accept data from the given source.
IP_DROP_SOURCE_MEMBERSHIP Leaves a source-specific multicast group. Drops the source from the given multicast group list. To drop all sources of a given group, you must use the IP_DROP_MEMBERSHIP socket option.
Table 3. IPv6 level options
Item Description Value
IPPROTO_IPV6 Restricts the AF_INET6 sockets to IPv6 communications only.
Option Type
int (Boolean interpretation)
  Allows you 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
  Allows you to set the outgoing hop limit for multicast IPv6 packets.
Option Type
int (x)
Option Value
The interpretation is the same as IPV6_UNICAST_HOPS (listed before).
  Allows you to specify the interface that is used for outgoing multicast packets. If specified as 0, the system selects the outgoing interface.
Option Type
Unsigned int (index of interface to use)
  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
  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.
  Leaves a multicast group on a specified interface.
Option Type
struct ipv6_mreq as defined in the netinet/in.h file.
  Specifies that the kernel computes a checksum over the data and the pseudo-IPv6 header for a raw socket. The kernel computes the checksum for outgoing packets and verifies the checksum for incoming packets on that socket. Incoming packets with incorrect checksum are 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. If the value is set to -1 disables the option.
  Causes the destination IPv6 address and arriving interface index of incoming IPv6 packets to be received as ancillary data on UDP and raw sockets.
Option Type
int (Boolean interpretation)
  Causes the hop limit of incoming IPv6 packets to be received as ancillary data on UDP and raw sockets.
Option Type
int (Boolean interpretation)
  Causes the traffic class of incoming IPv6 packets to be received as ancillary data on UDP and raw sockets.
Option Type
int (Boolean interpretation)
  Causes the routing header of incoming IPv6 packets to be received as ancillary data on UDP and raw sockets.
Option Type
int (Boolean interpretation)
  Causes the hop-by-hop options header of incoming IPv6 packets to be received as ancillary data on UDP and raw sockets.
Option Type
int (Boolean interpretation)
  Causes the destination options header of incoming IPv6 packets to be received as ancillary data on UDP and raw sockets.
Option Type
int (Boolean interpretation)
  Sets the source IPv6 address and outgoing interface index for all IPv6 packets that are sent on this socket. You can clear this option by doing a regular setsockopt with ipi6_addr being in6addr_any and ipi6_ifindex being 0.
Option Type
struct in6_pktinfo defined in the netinet/in.h file.
  Sets the next hop for outgoing IPv6 datagrams on this socket. You can clear this option by doing a regular setsockopt with a 0 length. A memory pointer must be supplied for the option value.
Option Type
struct sockaddr_in6 defined in the netinet/in.h file.
  Sets the traffic class for outgoing IPv6 datagrams on this socket. To clear this option, the application can specify the value as -1.
Option Type
int (x)
Option Value
x < -1 Error EINVAL
x == -1 Use kernel default
0 <= x <= 255 Use
x x >= 256 Error EINVAL
  Sets the routing header to be used for outgoing IPv6 datagrams on this socket. This option can be cleared by doing a regular setsockopt with a 0 length. A memory pointer must still be supplied for the option value in this case.
Option Type
struct ip6_rthdr defined in the netinet/ip6.h file.
  Sets the hop-by-hop options header to be used for outgoing IPv6 datagrams on this socket. This option can be cleared by doing a regular setsockopt with a 0 length. A memory pointer must still be supplied for the option value in this case.
Option Type
struct ip6_hbh defined in the netinet/ip6.h file.
  Sets the destination options header to be used for outgoing IPv6 datagrams on this socket. This header follows a routing header and is used when the routing header is not specified. This option can be cleared by doing a regular setsockopt with a 0 length. A memory pointer must still be supplied for the option value in this case.
Option Type
struct ip6_dest defined in the netinet/ip6.h file.
  Sets the destination options header to be used for outgoing IPv6 datagrams on this socket. This header precedes a routing header. If no routing header is specified, this option is silently ignored. This option can be cleared by doing a regular setsockopt with a 0 length. A memory pointer must still be supplied for the option value in this case.
Option Type
struct ip6_dest defined in the netinet/ip6.h file.
  Sets this option to control IPv6 path MTU discovery.
Option Type
int
Option Type
-1 Performs path MTU discovery for unicast destinations, but does not perform it for multicast destinations. 0 performs path MTU discovery. 1 disables path MTU discovery and sends packets at the minimum MTU.
  Set this option to prevent fragmentation of outgoing IPv6 packets on this socket. If a packet is being sent that is larger than the outgoing interface MTU, the packet is discarded.
Option Type
int (Boolean interpretation)
  Enables the receipt of the IPV6_PATHMTU ancillary data items by setting this option.
Option Type
int (Boolean interpretation)
  Sets the address selection preferences for this socket.
Option Type
int
Option Value
Combination of the IPV6_PREFER_SRC_* flags defined in the netinet/in.h file.
  Joins the multicast group as specified in the OptionValue parameter of the group_req structure. If the specified interface index is 0, the kernel chooses the default interface.
Option Type
struct group_req as defined in the netinet/in.h file.
  Leaves the multicast group as specified in the OptionValue parameter of the group_req structure.
Option Type
struct group_req as defined in the netinet/in.h file.
  Blocks data from the specified source to the specified multicast group.
Option Type
struct group_source_req as defined in the netinet/in.h file.
  Unblocks data from the specified source to the specified multicast group. The option is used to undo the MCAST_BLOCK_SOURCE operation.
Option Type
struct group_source_req as defined in the netinet/in.h file.
  Joins a source-specific multicast group. If the host is already a member of the group, accept data from the specified source. Otherwise, join the group and accept data from the specified source.
Option Type
struct group_source_req as defined in the netinet/in.h file.
  Leaves a source-specific multicast group. Leaves the specified source from the specified multicast group. To leave all sources of the multicast group, you must use the IPV6_LEAVE_GROUP or MCAST_LEAVE_GROUP socket option.
Option Type
struct group_source_req as defined in the netinet/in.h file.
Table 4. ICMPV6 level options
Item Description Value
IPPROTO_ICMPV6 Filters the ICMPV6 messages by the ICMPV6 type field. Issue a setsockopt call with zero length to clear an existing filter.
Option Type
The icmp6_filter structure defined in the netinet/icmp6.h file.
The following values that are defined in the /usr/include/netint/tcp.h file are used by the setsockopt subroutine to configure the dacinet functions. 
tcp.h:#define TCP_ACLFLUSH    0x21    /* clear all DACinet ACLs */
tcp.h:#define TCP_ACLCLEAR    0x22    /* clear DACinet ACL */
tcp.h:#define TCP_ACLADD      0x23    /* Add to DACinet ACL */
tcp.h:#define TCP_ACLDEL      0x24    /* Delete from DACinet ACL */
tcp.h:#define TCP_ACLLS       0x25    /* List DACinet ACL */
tcp.h:#define TCP_ACLBIND     0x26    /* Set port number for TCP_ACLLS */
tcp.h:#define TCP_ACLGID      0x01    /* ID being added to ACL is a GID */
tcp.h:#define TCP_ACLUID      0x02    /* ID being added to ACL is a GID */
tcp.h:#define TCP_ACLSUBNET   0x04    /* address being added to ACL is a subnet */
tcp.h:#define TCP_ACLDENY     0x08    /* this ACL entry is for denying access */
Note: The DACinet facility is available only in a CAPP/EAL4+ configured AIX system.

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.

Error Codes

Table 5. Error codes
Item Description
EBADF The Socket parameter is not valid.
EFAULT The Address parameter is not in a writable part of the user address space.
EINVAL The OptionValue parameter or the OptionLength parameter is invalid or the socket is shutdown.
ENOBUFS Insufficient memory for an internal data structure.
ENOTSOCK The Socket parameter refers to a file, not to a socket.
ENOPROTOOPT The option is unknown.
EOPNOTSUPP The socket family or the socket type does not support the EOPNOTSUPP option.
EPERM The user application does not have the permission to get or to set this socket option. Check the network tunable option.

Examples

  • To mark a socket for broadcasting, enter the following command: 
    int on=1;
setsockopt(s, SOL_SOCKET, SO_BROADCAST, &on, sizeof(on));
  • To turn on the TCP_NODELAYACK option, enter the following command: 
    int on=1;
setsockopt(s, IPPROTO_TCP, TCP_NODELAYACK, &on, sizeof(on));