gtpc1m4dTransmission Control Protocol/Internet Protocol

setsockopt -- Set Options Associated with a Socket

The setsockopt function sets options associated with a socket.

Format

#include  <socket.h>
int       setsockopt(int s,
                     int level,
                     int optname,
                     char *optval,
                     int optlen);

s
The socket descriptor.

level
Level for which the option is set. Use the value SOL_SOCKET.

optname
Name of a specified socket option. Use one of the following values:

SO_BROADCAST
Toggles the ability to broadcast messages. Enabling this option lets the application send broadcast messages over s if the interface specified in the destination supports broadcasting of packets. This option has no meaning for stream sockets.

SO_KEEPALIVE
Toggles the ability to send probes on idle sockets to verify that the socket is still active. This option has meaning only for stream sockets. The KEEPALIVE option is valid only for TCP/IP native stack support when the socket sweeper is active.

SO_LINGER
Waits to complete the close function if data is present. When this option is enabled and there is unsent data present when the close function is called, the calling application is blocked during the close function until the data is transmitted or the connection has timed out. The close function returns without blocking the caller. This option has meaning only for stream sockets.

SO_OOBINLINE
Toggles reception of out-of-band data. Enabling this option causes out-of-band data to be placed in the normal data input queue as it is received, making it available to recvfrom without having to specify the MSG_OOB flag in those calls. Disabling this option causes out-of-band data to be placed in the priority data input queue as it is received, making it available to recvfrom only by specifying the MSG_OOB flag in these calls. This option has meaning only for stream sockets.

SO_RCVBUF
Allows you to set the size of the receive buffer to a value to suit your application needs. The minimum size is 512 bytes. The maximum size is 1 048 576 bytes. This option has meaning only for sockets that are using TCP/IP native stack support.

SO_RCVLOWAT
Allows you to set the receive buffer low-water mark, which is the minimum amount of data that must be received before a read, recv, recvfrom, activate_on_receipt, or activate_on_receipt_with_length function will be completed. This option has meaning only for TCP sockets that are using TCP/IP native stack support.

SO_RCVTIMEO
Defines the receive timeout value, which is how long the system will wait for a read, recv, recvfrom, activate_on_receipt, activate_on_receipt_with_length, accept, activate_on_accept, or connect function to be completed before timing out the operation. A returned value of 0 indicates the system will not time out. The maximum value is 32 767 seconds. This option has meaning only for sockets that are using TCP/IP native stack support.

SO_REUSEADDR
Toggles local address reuse. Enabling this option lets local addresses that are already in use to be bound. This changes the normal algorithm used in the bind function. At connect time, the system checks that no local address and port have the same remote address and port and returns error code SOCADDRINUSE if the association already exists.

SO_DONTROUTE
Toggles the routine bypass for outgoing messages. When you enable this option, outgoing messages bypass the standard routing algorithm and are directed to the appropriate network interface according to the network portion of the destination address. When enabled, this option lets you send packets only to directly connected networks (networks for which the host has an interface). This option has no meaning for stream sockets.

SO_SNDBUF
Allows you to set the size of the send buffer to a value to suit your application needs. For sockets using TCP/IP native stack support, the minimum size is 512 bytes and the maximum size is 1 048 576 bytes.

SO_SNDLOWAT
Allows you to set the send buffer low-water mark, which is the minimum amount of space that must be available in the send buffer to allow a select for write function to be processed. This option has meaning only for sockets that are using TCP/IP native stack support.

SO_SNDTIMEO
Defines the send timeout value, which is how long the system will wait for a send, sendto, write, or writev function to be completed before timing out the operation. A returned value of 0 indicates the system will not time out. The maximum value is 32 767 seconds. This option has meaning only for sockets that are using TCP/IP native stack support.

optval
Pointer to option data. The optval and optlen parameters are used to pass data used by a particular command. The optval parameter points to a buffer containing the data needed by the command. The optval parameter is optional and can be set to the NULL pointer if data is not needed by the command.

optlen
Length of the option data. The optlen parameter must be set to the size of the data pointed to by optval.

Normal Return

Return code 0 indicates that the function was successful.

Error Return

A return code equal to -1 indicates an error. You can get the specific error code by calling sock_errno. See Appendix C, Socket Error Return Codes for more information about socket errors.

Note:
Unless otherwise stated in the description, the following error codes can be returned for either TCP/IP offload support or TCP/IP native stack support.

Value
Description

SOCADDRINUSE
The address is already in use. This error code is returned only for TCP/IP offload support.

SOCFAULT
Using the optval and optlen parameters results in an attempt to access a protected address space. This error code is returned only for TCP/IP offload support.

SOCNOPROTOOPT
The optname parameter is not recognized, or the level parameter is not valid.

SOCNOTSOCK
The s parameter is not a valid socket descriptor.

SOCINVAL
The value of the optlen parameter is not a valid size.

SOCNOBUFS
There is not enough buffer space to satisfy the setsockopt function. This error code is returned only for TCP/IP offload support.

SOCIPNOTFOUND
The TPF system could not locate the header for the IP table (IPT). This error code is returned only for TCP/IP offload support.

EIBMIUCVERR
An error occurred while the message was sent to the offload device. This error code is returned only for TCP/IP offload support.

E1052STATE
The socket was closed because the system was in or cycling down to 1052 state.

EINACT
All offload devices associated with the socket descriptor have been disconnected. The socket is closed. This error code is returned only for TCP/IP offload support.

EINACTWS
An offload device associated with the socket descriptor has been disconnected. The socket is still available. This error code is returned only for TCP/IP offload support.

ESYSTEMERROR
A system error has occurred and closed the socket. This error code is returned only for TCP/IP offload support.

OFFLOADTIMEOUT
The offload device did not respond to the function call in the requested time. This error code is returned only for TCP/IP offload support.

Programming Considerations

Examples

In the following example, out-of-band data is set in the normal input queue.

#include <socket.h>

·
·
·
int rc; int server_sock; int optval;
·
·
·
optval = 1; rc = setsockopt(server_sock, SOL_SOCKET, SO_OOBINLINE, (char *)&optval, sizeof(int));
·
·
·

Related Information