gtpc1m3wTransmission Control Protocol/Internet Protocol

getsockopt -- Return Socket Options

The getsockopt function gets options associated with a socket.

Format

#include  <socket.h>
int       getsockopt(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
Returns the value of the 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_DONTROUTE
Returns the value of the 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_ERROR
Returns any pending error on the socket and clears the error status. You can use it to check for asynchronous errors on connected datagram sockets or for other asynchronous errors (errors that are not returned explicitly by one of the socket calls).

SO_KEEPALIVE
Sends probes on idle sockets to verify that the socket is still active. This option has meaning only for stream sockets.

SO_LINGER
Waits to complete the close function if data is present. When you enable this option and there is unsent data present when close 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 and recv 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 and recv only by specifying the MSG_OOB flag in these functions. This option has meaning only for stream sockets.

SO_RCVBUF
Returns the size of the receive buffer. This option has meaning only for sockets that are using TCP/IP native stack support.

SO_RCVLOWAT
Returns 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, activate_on_receipt_with_length, or activate_on_receipt_with_length function is completed successfully. This option has meaning only for TCP sockets that are using TCP/IP native stack support.

SO_RCVTIMEO
Returns 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 successfully before timing out the operation. A returned value of 0 indicates the system will not time out. This option has meaning only for sockets that are using TCP/IP native stack support.

SO_REUSEADDR
Toggles local address reuse. Enabling this option allows 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_SNDBUF
Allows you to set the size of the send buffer to a value to suit your application needs.

SO_SNDLOWAT
Returns 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
Returns 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. This option has meaning only for sockets that are using TCP/IP native stack support.

SO_TYPE
Returns the type of the socket. On return, the integer pointed to by optval is set to one of the following values:
  • SOCK_STREAM
  • SOCK_DGRAM
  • SOCK_RAW.

optval
Pointer to option data. The optval and optlen parameters return data used by the particular get command. The optval parameter points to a buffer that is to receive the data requested by the get command.

optlen
Pointer to the length of the option data. The optlen parameter points to the size of the buffer pointed to by the optval parameter. It must be initially set to the size of the buffer before calling getsockopt. On return, it is set to the actual size of the data returned.

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

SOCFAULT
Using optval and optlen parameters would result in an attempt to copy the address into 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 SOL_SOCKET.

SOCNOTSOCK
The s parameter is not a valid socket descriptor.

SOCNOBUFS
There is not enough buffer space available to process the message. This error code is returned only for TCP/IP offload support.

EIBMIUCVERR
An error occurred while the function call 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 a specified time period. This error code is returned only for TCP/IP offload support.

SOCINVAL
The socket type is incorrect for the option passed. This error code is returned only for TCP/IP native stack support.

Programming Considerations

Examples

The following example obtains out-of-band information.

#include <socket.h>

·
·
·
int optval; int optlen; int rc; int server_sock;
·
·
·
/* Is out of band data in the normal input queue? */ optlen = sizeof(optval); rc = getsockopt(server_sock, SOL_SOCKET, SO_OOBINLINE, (char *)&optval, &optlen); if (rc == 0) if (optlen == sizeof(int)) { if (optval) /* yes it is in the normal queue */ else /* no it is not */ }

Related Information