setsockopt()--Set Socket Options


  BSD 4.3 Syntax
  #include <sys/types.h>
  #include <sys/socket.h>

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

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes



  UNIX® 98 Compatible Syntax
  #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)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes


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

There are two versions of the API, as shown above. The base IBM i® 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:
option_name
(Input) The name of the option to be set. The following tables under option_value 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.

option_value
(Input) A pointer to the option value. The following tables list the options with details on the structure type passed for the option_value pointer.

Socket Options That Apply to the IP Layer (IPPROTO_IP)



Socket Options That Apply to the TCP Layer (IPPROTO_TCP)



Socket Options That Apply to the Socket Layer (SOL_SOCKET )



Socket Options That Apply to the IPv6 Layer (IPPROTO_IPV6)



Socket Options That Apply to the ICMPv6 Layer (IPPROTO_ICMPV6)



option_length
(Input) The length of the option_value.

Authorities

The user profile for the thread must have *IOSYSCFG special authority to set options when:

Return Value

setsockopt() returns an integer. Possible values are:


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.
  • An invalid flag combination was supplied for IPV6_ADDR_PREFERENCES.

[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.

[EOPNOTSUPP]

Operation not supported.

[EPERM]

Operation not permitted.

The executing user profile must have *IOSYSCFG special authority to get options when:

  • the level parameter specifies IPPROTO_IP and the option_value parameter is IP_OPTIONS
  • the level parameter specifies IPPROTO_IPV6 and the option_value parameter is IPV6_NEXTHOP
  • the level parameter specifies IPPROTO_IPV6 and the option_value parameter is IPV6_RTHDR
[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. 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().
  8. The following comments apply to the IPV6_RTHDR option value:
    • The following functions can be used to build a routing header:

  9. The following comment applies to the IPV6_HOPOPTS, IPV6_DSTOPTS, and IPV6_RTHDRDSTOPTS option values:
  10. Data options set using setsockopt() referred to as sticky options. Sticky options apply to all packets flowing on the socket, until the option is reset, or the option is overridden by an ancillary data option, referred to as a non-sticky option.


Related Information


API introduced: V3R1