setsockopt()--Set Socket Options

  #include <sys/types.h>
  #include <sys/socket.h>

 int setsockopt(int socket_descriptor,
                int level,
                int option_name,
                char *option_value,
                int option_length)

  #define _XOPEN_SOURCE 520
  #include <sys/socket.h>

 int setsockopt(int socket_descriptor,
                int level,
                int option_name,
                const void *option_value,
                socklen_t option_length)

The setsockopt() function is used to set socket options.

There are two versions of the API, as shown above. The base i5/OS API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.

Parameters

socket_descriptor

(Input) The descriptor of the socket for which options are to be set.

level

(Input) Whether the request applies to the socket itself or the underlying protocol being used. Supported values are:

IPPROTO_IP	Request applies to IP protocol layer.
IPPROTO_TCP	Request applies to TCP protocol layer.
SOL_SOCKET	Request applies to socket layer.
IPPROTO_IPV6	Request applies to IPv6 protocol layer.
IPPROTO_ICMPV6	Request applies to ICMPv6 protocol layer.

option_name

(Input) The name of the option to be set. The following tables list the options supported for each level. Assume that the option is supported for all address families unless the option is described otherwise.

Note: Options directed to a specific protocol level are only supported by that protocol. An option that is directed to the SOL_SOCKET level always completes successfully. This provides compatibility with Berkeley Software Distributions implementations that also shield the application from protocols that do not support an option.

Socket Options That Apply to the IP Layer (IPPROTO_IP)

Option	Description
IP_OPTIONS	Set IP header options. This is only supported for sockets with an address family of AF_INET.
IP_TOS	Set Type Of Service (TOS) and Precedence in the IP header. This option is only supported for sockets with an address family of AF_INET.
IP_TTL	Set Time To Live (TTL) in the IP header. This option is only supported for sockets with an address family AF_INET.
IP_MULTICAST_IF	Set interface over which outgoing multicast datagrams should be sent. An option_value parameter of type in_addr is used to specify the local IP address that is associated with the interface over which outgoing multicast datagrams should be sent. An address of INADDR_ANY removes the previous selection. This option is only supported for sockets with an address family of AF_INET and type of SOCK_DGRAM or SOCK_RAW.
IP_MULTICAST_TTL	Set Time To Live (TTL) in the IP header for outgoing multicast datagrams. An option_value parameter of type char is used to set this value between 0 and 255. This option is only supported for sockets with an address family of AF_INET and type of SOCK_DGRAM or SOCK_RAW.
IP_MULTICAST_LOOP	Specify that a copy of an outgoing multicast datagram should be delivered to the sending host as long as it is a member of the multicast group. If this option is not set, a copy of the datagram will not be delivered to the sending host. An option_value parameter of type char is used to control loopback being on or off. This option is only supported for sockets with an address family of AF_INET and type of SOCK_DGRAM or SOCK_RAW.
IP_ADD_MEMBERSHIP	Joins a multicast group as specified in the option_value parameter of type struct ip_mreq. A maximum of IP_MAX_MEMBERSHIPS groups may be joined per socket. This option is only supported for sockets with an address family of AF_INET and type of SOCK_DGRAM or SOCK_RAW.
IP_DROP_MEMBERSHIP	Leaves a multicast group as specified in the option_value parameter of type struct ip_mreq. This option is only supported for sockets with an address family of AF_INET and type of SOCK_DGRAM or SOCK_RAW.
IP_RECVLCLIFADDR	Indicates if the local interface that a datagram to be received should be returned. A value of 1 indicates the first 4 bytes of the reserved field of the sockaddr structure will contain the local interface. This option is only supported for sockets with an address family of AF_INET and type of SOCK_DGRAM.
IP_DONTFRAG	Set or reset the don't fragment flag in the IP header. This option is supported for sockets with an address family of AF_INET and type of SOCK_DGRAM or SOCK_RAW only.

Socket Options That Apply to the TCP Layer (IPPROTO_TCP)

Option

Description

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. This option is only supported for sockets with an address family of AF_INET or AF_INET6 and type of SOCK_STREAM.

Socket Options That Apply to the Socket Layer (SOL_SOCKET )

Option	Description
SO_ACCEPTECONNABORTED	Enable the listening socket such that a blocking accept() will return ECONNABORTED when a connection on the listening backlog is reset prior to the accept(). A backlog entry is created when a new connection is established to the listener socket. The accept() call will consume all leading invalid entries in the backlog, until a valid entry is located or the backlog is exhausted. If the backlog contains no entries or a valid entry is located, the option has no effect. If the backlog contains at least one invalid entry and there are no valid entries, the accept() will return -1 with errno set to ECONNABORTED. The option is only valid on a socket that has successfully issued the listen() call. The option has no effect on non-blocking sockets. This option is only used by sockets with an address family of AF_INET or AF_INET6.
SO_BROADCAST	Enable the socket for issuing messages to a broadcast address. This option is only supported for sockets with an address family of AF_INET and type SOCK_DGRAM or SOCK_RAW. The broadcast address to be used may be determined by issuing an ioctl() with the SIOCGIFBRDADDR request.
SO_DEBUG	Indicates if low level-debugging is active.
SO_DONTROUTE	Bypass normal routing mechanisms. This option is only supported by sockets with an address family of AF_INET or AF_INET6.
SO_KEEPALIVE	Keep the connection up by sending periodic transmissions. This option is only supported for sockets of an address family of AF_INET or AF_INET6 and type SOCK_STREAM.
SO_LINGER	Indicates if the system attempts delivery of any buffered data or if the system discards it when a close() is issued. For sockets that are using a connection-oriented transport service with an address family of AF_INET or AF_INET6, the default is off (which means that the system attempts to send any queued data, with an infinite wait-time).
SO_OOBINLINE	Indicates whether out-of-band data is received inline with normal data. This option is only supported for sockets with an address family of AF_INET or AF_INET6.
SO_RCVBUF	Set the size of the receive buffer.
SO_RCVLOWAT	Set the size of the receive low-water mark. The default size is 1. This option is only supported for sockets with a type of SOCK_STREAM.
SO_RCVTIMEO	Set the receive timeout value. This option is not supported unless _XOPEN_SOURCE is defined to be 520 or greater.
SO_REUSEADDR	Indicates if the local socket address can be reused. This option is supported by sockets with an address family of AF_INET or AF_INET6 and a type of SOCK_STREAM or SOCK_DGRAM.
SO_SNDBUF	Set the size of the send buffer.
SO_SNDLOWAT	Set the size of the send low-water mark. This option is not supported.
SO_SNDTIMEO	Set the send timeout value. This option is not supported unless _XOPEN_SOURCE is defined to be 520 or greater.
SO_USELOOPBACK	Indicates if the loopback feature is being used. This option is not supported.

Socket Options That Apply to the IPv6 Layer (IPPROTO_IPV6)

Option	Description
IPV6_UNICAST_HOPS	Set the hop limit value that will be used for subsequent unicast packets sent by this socket. An option_value parameter of type int is used to set this value between 0 and 255. This option is supported for sockets with an address family of AF_INET6 only.
IPV6_MULTICAST_IF	Set the interface over which outgoing multicast datagrams will be sent. An option_value parameter of type unsigned int is used to set the interface index that is associated with the interface over which outgoing multicast datagrams will be sent. This option is only supported for sockets with an address family of AF_INET6 and type of SOCK_DGRAM or SOCK_RAW.
IPV6_MULTICAST_HOPS	Set the hop limit value that will be used for subsequent multicast packets sent by this socket. An option_value parameter of type int is used to set this value between 0 and 255. If IPV6_MULTICAST_HOPS is not set, the default is 1. This option is only supported for sockets with an address family of AF_INET6 and type of SOCK_DGRAM or SOCK_RAW.
IPV6_MULTICAST_LOOP	Set the multicast looping mode. A value of 1 (default), indicates that multicast datagrams sent by this system should also be delivered to this system as long as it is a member of the multicast group. If this option is 0, a copy of the datagram will not be delivered to the sending host. An option_value parameter of type unsigned int is used to set this value. This option is only supported for sockets with an address family of AF_INET6 and type of SOCK_DGRAM or SOCK_RAW.
IPV6_JOIN_GROUP	Joins a multicast group as specified in the option_value parameter of type struct ipv6_mreq. A maximum of IP_MAX_MEMBERSHIPS groups may be joined per socket. This option is only supported for sockets with an address family of AF_INET6 and type of SOCK_DGRAM or SOCK_RAW.
IPV6_LEAVE_GROUP	Leaves a multicast group as specified in the option_value parameter of type struct ipv6_mreq. This option is only supported for sockets with an address family of AF_INET6 and type of SOCK_DGRAM or SOCK_RAW.
IPV6_V6ONLY	Set the AF_INET6 communication restrictions. A non-zero value indicates that this AF_INET6 socket is restricted to IPv6 communications only. This option stores an int value. This is a boolean option. By default this option is turned off. This option is supported for sockets with an address family of AF_INET6 only.
IPV6_CHECKSUM	Set if the kernel will calculate and insert a checksum for output and verify the received checksum on input, discarding the packet if the checksum is in error for this socket. An option_value parameter of type int is used to set this value. If this option is -1 (the default), this socket option is disabled. A value of 0 or greater specifies an integer offset into the user data of where the checksum is located. This must be an even integer value. This option is only supported for sockets with an address family of AF_INET6 and type of SOCK_RAW with a protocol other than IPPROTO_ICMPV6. The checksum is automatically computed for protocol IPPROTO_ICMPV6.
IPV6_DONTFRAG	Set if the kernel will not implement the automatic insertion of a fragment header in the packet if the packet is too big for the path MTU. By default this socket option is disabled. Setting the value to 0 also disables the option. If this option is set to a non-zero value the kernel will discard the packet instead of inserting the fragment header. This option is supported for sockets with an address family of AF_INET6 and type of SOCK_DGRAM or SOCK_RAW only.

Socket Options That Apply to the ICMPv6 Layer (IPPROTO_ICMPV6)

Option

Description

ICMP6_FILTER

Set the ICMPv6 Type Filtering. An option_value parameter of type struct icmp6_filter, defined in <netinet/icmp6.h> is used to set this value. The following macros, defined in <netinet/icmp6.h> can be used to update the type filtering structure to specify whether or not specific ICMPv6 message types will be passed to the application or be blocked: ICMP6_FILTER_SETPASS, ICMP6_FILTER_SETBLOCK, ICMP6_FILTER_SETPASSALL, and ICMP6_FILTER_SETBLOCKALL. The default is to pass all ICMPv6 message types to the application. This option is only supported for sockets with an address family of AF_INET6 and type of SOCK_RAW with a protocol of IPPROTO_ICMPV6.

option_value

(Input) A pointer to the option value. Integer flags/values are required by setsockopt() for all the socket options except SO_LINGER, IP_OPTIONS, IP_MULTICAST_IF, IP_MULTICAST_TTL, IP_MULTICAST_LOOP, IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP, IPV6_JOIN_GROUP, IPV6_LEAVE_GROUP, ICMP6_FILTER.

Note: For the IP_TOS and IP_TTL options, only the rightmost octet (least significant octet) of the integer value is used.

The following options can be set by specifying a nonzero value for the option_value parameter:

• SO_ACCEPTECONNABORTED
• SO_BROADCAST
• SO_DEBUG
• SO_DONTROUTE
• SO_KEEPALIVE
• SO_OOBINLINE
• SO_REUSEADDR
• TCP_NODELAY
• IP_MULTICAST_LOOP
• IP_DONTFRAG
• IPV6_V6ONLY
• IPV6_MULTICAST_LOOP
• IPV6_DONTFRAG

For the SO_LINGER option, option_value is a pointer to the structure struct linger, defined in <sys/socket.h>.

      struct linger [
        int        l_onoff;
        int        l_linger;
      ];

The l_onoff field determines if the linger option is set. A nonzero value indicates the linger option is set and is using the l_linger value. A zero value indicates that the option is not set. The l_linger field is the time to wait before any buffered data to be sent is discarded. The following occur on a close():

• For AF_INET and AF_INET6 sockets:
  
  
  • If the l_onoff value is zero, the system attempts to send any buffered data with an infinite wait-time.
    
    
  • If the l_onoff value is nonzero and the l_linger value is nonzero, the system attempts to send any buffered data for l_linger time. If l_linger time has elapsed and the data is still not successfully sent, it is discarded. When data is discarded, the remote program may receive a [ECONNRESET].
    
    
• For AF_INET sockets over SNA:
  
  
  • If the l_onoff value is nonzero and the l_linger value is zero, the system waits indefinitely (no timer is implemented). Otherwise, if the l_onoff value is nonzero and the l_linger value is zero, the system discards any buffered data. When data is discarded, the remote program may receive a [ECONNRESET].
    
    

Note: An application must implement an application level confirmation. Guaranteed receipt of data by the partner program is required. Setting SO_LINGER does not guarantee delivery.

For the SO_RCVTIME and SO_SNDTIME options, option_value is a pointer to where the structure timeval is stored. The structure timeval is defined in <sys/time.h>.

struct timeval {
   long  tv_sec;
   long  tv_usec;
};

For the IP_OPTIONS option, option_value is a pointer to a character string representing the IP options as specified in RFC 791. The character string varies depending on which options are selected. Each option is made up of a single byte representing the option code, and may be followed by a length field (1 byte) and data for the option. The IP options that can be set are:

• End of option list. Used if options do not end at end of header.
• No operation (used to align octets in a list of options).
• Security and handling restrictions.
• Loose source routing. Used to route a datagram along a path of specified IP addresses. Multiple network hops are allowed between any two IP addresses on the path.
• Record route. Used to trace a route.
• Stream identifier. Used to carry a SATNET stream identifier. This option has been deprecated by RFC 1122 and will result in an error of [EINVAL] if used.
• Strict source routing. Used to route datagram along a path of specified IP addresses. No additional network hops are allowed between any two IP addresses in the path.
• Internet timestamp. Used to record timestamps along the route.

For the IP_MULTICAST_IF option, option_value is a pointer to the structure in_addr, defined in <netinet/in.h> as:

   struct in_addr [
      u_long  s_addr;
          /* IP address                  */
    ];

The s_addr field specifies the local IP address that is associated with the interface over which outgoing multicast datagrams should be sent.

For the IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP options, option_value is a pointer to the structure ip_mreq, defined in <netinet/in.h> as:

   struct ip_mreq [
      struct in_addr imr_multiaddr;          /* IP multicast address of group */
      struct in_addr imr_interface;          /* local IP address of interface */
   ];

The imr_multiaddr field is used to specify the multicast group to join or leave. The imr_interface field is used to specify the local IP address that is associated with the interface to which this request applies. If INADDR_ANY is specified for the local interface, the default multicast interface will be selected.

For the IPV6_JOIN_GROUP and IPV6_LEAVE_GROUP options, option_value is a pointer to the structure ipv6_mreq, defined in <netinet/in.h> as:

   struct ipv6_mreq [
      struct in6_addr ipv6mr_multiaddr;      /* IPv6 multicast address        */
      unsigned int    ipv6mr_interface;      /* interface index               */
   ];

The ipv6mr_multiaddr field is used to specify the multicast group to join or leave. The ipv6mr_interface field is used to specify the interface to which this request applies. If 0 is specified for the interface, the system will choose the local interface.

Note: Reception of IP multicast datagrams may require configuration changes to the line description to enable the adapter to receive packets with a multicast destination address. On Ethernet, for example, the Ethernet group address that is associated with the IP group address must be specified by the GRPADR parameter on the line description. To determine the Ethernet group address for a particular IP group address, the low-order 23 bits of the IP address are placed into the low-order 23 bits of the Ethernet group address 01.00.5E.xx.xx.xx.

Notes:

1. For sockets that use a connection-oriented transport service, IP options that are set using setsockopt() are only used if they are set prior to a connect() being issued. After the connection is established, any IP options that the user sets are ignored.
   
   
2. If the IP options portion contains a source routing option, then the address in the source routing option overrides the destination address. The destination address may have been specified on an output operation (for example, on a sendto()) or on a connect().
   
   
3. If a socket has a type of SOCK_RAW and a protocol of IPPROTO_RAW, any IP options set using setsockopt() are ignored (since the user must supply the IP header data on an output operation as part of the data that is being transmitted).

option_length

(Input) The length of the option_value.

Authorities

Return Value

setsockopt() returns an integer. Possible values are:

• -1 (unsuccessful)
  
  
• 0 (successful)

Error Conditions

When setsockopt() fails, errno can be set to one of the following:

[EADDRINUSE]

Address already in use. This error code indicates that the socket_descriptor parameter specified for the IP_ADD_MEMBERSHIP operation is already a member of the specified multicast group.

[EADDRNOTAVAIL]

Address not available. For the IP_ADD_MEMBERSHIP or IP_DROP_MEMBERSHIP operations, this error code indicates that an incorrect address was specified for either the imr_multiaddr or imr_interface parameter value.

[EBADF]

Descriptor not valid.

[ECONNABORTED]

Connection ended abnormally.

This error code indicates that the transport provider ended the connection abnormally because of one of the following:

• The retransmission limit has been reached for data that was being sent on the socket.
• A protocol error was detected.

[EFAULT]

Bad address.

The system detected an address which was not valid while attempting to access the option_value parameter.

[EINVAL]

Parameter not valid.

This error code indicates one of the following:

• The level parameter specifies a level that is not supported.
• The option_name parameter specifies a value that is not valid (except for when the level is SOL_SOCKET , in which case [ENOPROTOOPT] is returned).
• The option_value parameter specifies a value that is not valid.
• The option_length parameter specifies a negative or zero value.
• An attempt was made to set a socket option that was read-only.

[EIO]

Input/output error.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOPROTOOPT]

The protocol does not support the specified option.

This error code indicates one of the following:

• The socket has an address family of AF_UNIX and the level parameter specified is not SOL_SOCKET .
• The level parameter specifies a level of SOL_SOCKET and the option_name parameter specifies a value that is not valid.

[ENOTCONN]

Requested operation requires a connection.

This error code is only returned if the level parameter specifies a level other than SOL_SOCKET and the socket_descriptor parameter points to a socket that is using a connection-oriented transport service that has had its connection broken.

[ENOTSOCK]

The specified descriptor does not reference a socket.

[EPERM]

Operation not permitted.

The executing user profile must have *IOSYSCFG special authority to set options when the level parameter specifies IPPROTO_IP and the option_value parameter is IP_OPTIONS.

[ETOOMANYREFS]

The operation would have exceeded the maximum number of references allowed for this socket.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

[EUNKNOWN]

Unknown system state.

Error Messages

Usage Notes

1. Socket options are defined in <sys/socket.h>, IP options are defined in <netinet/ip.h> and <netinet/in.h>, TCP options are defined in <netinet/tcp.h>, IPv6 and ICMPv6 options are defined in <netinet/in.h>.
   
   
2. The following comments applies to the SO_SNDBUF option value:
   • For AF_INET and AF_INET6 sockets over TCP of type SOCK_STREAM, the maximum value the SO_SNDBUF option can be set to is 8 megabytes. Anything greater results in an error of [ENOBUFS]. If the SO_SNDBUF option value is set to a positive value that is less than 512 bytes, the system automatically uses 512 bytes as the SO_SNDBUF size.
     
     
   • For AF_INET and AF_INET6 sockets over UDP of type SOCK_DGRAM, the maximum value the SO_SNDBUF option can be set to is 65535 bytes less the IP and UDP header sizes. Anything greater results in an error of [EINVAL].
   
   
3. For AF_INET sockets over SNA of type SOCK_STREAM, SO_RCVBUF should be set before connection is established. After connection is established, any changes are ignored. Also, only the client can affect the receive buffer size. The server cannot affect it.
   
   
4. For AF_INET sockets over SNA of type SOCK_DGRAM, both SO_SNDBUF and SO_RCVBUF are ignored and have no effect on processing.
   
   
5. When a TCP connection is closed for a socket using the AF_INET or AF_INET6 address family, the port associated with that connection is not made available until twice the Maximum Segment Life (MSL) time in seconds has passed. The MSL time is approximately 2 minutes. The SO_REUSEADDR option allows a bind() to succeed when requesting a port that is being held during this time frame. This can be especially useful if a server is abruptly ended and restarted.

   Notes:

   • For AF_INET and AF_INET6, SOCK_STREAM sockets, this option does not allow two servers to successfully issue a bind() requesting the same port number and local address combination. For AF_INET and AF_INET6, SOCK_DGRAM sockets, the SO_REUSEADDR option does allow multiple servers to successfully bind to the same port. When broadcast or multicast datagrams are received for a given port, each server that is bound to that port receives a copy of the datagram provided each server has enabled the SO_REUSEADDR option.
     
     
   • This option does not affect unicast datagram delivery.
   
   
6. The following SOL_SOCKET options are not supported by AF_INET sockets over SNA. setsockopt() appears to succeed, but has no effect on the function of AF_INET sockets over SNA.
   • SO_BROADCAST
   • SO_DONTROUTE
   • SO_KEEPALIVE
   • SO_LINGER
   
   
7. The option IP_DONTFRAG and IPV6_DONTFRAG are not valid for multicast group destinations.
   
   
8. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the setsockopt() API is mapped to qso_setsockopt98().

Related Information

• _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
  
  
• getsockopt()--Retrieve Information about Socket Options