getsockopt: Return socket options

The getsockopt socket function gets options associated with a socket.

Last updated

Changed for PUT04.
Added for PUT00.

Format

#include  <sys/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_INPUT_PRIORITY

Returns the input message priority for this socket. If the application has issued setsockopt to set the priority to a value that is not 0, that value is returned. If setsockopt has not been issued or has been issued with a priority value of 0, the priority value in the network services database is returned. If setsockopt has not been issued or has been issued with a priority value of 0 and the application is not defined in the network services database, the default priority is returned. This option is valid only for TCP and UDP sockets and is unique to the z/TPF system. Input message priority has meaning only for sockets using OSA-Express.

See z/TPF Transmission Control Protocol/Internet Protocol for information about input message priority.

SO_RCVBUF

Returns the size of the receive buffer.

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, or activate_on_receipt_with_length function is completed successfully.

SO_RCVTIMEO

Returns the receive timeout value, which is how long the system will wait for a read, recv, recvfrom, tpf_read_TCP_message, activate_on_receipt, activate_on_receipt_with_length, activate_on_receipt_of_TCP_message, 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.

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.

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.

SO_TCPDELAY

Returns the TCP delayed acknowledgment timer value, which is the amount of time that the z/TPF system waits before sending a stand-alone acknowledgment (ACK) to acknowledge data on this TCP socket. Values are specified in tens of milliseconds, ranging from 1 (10 ms) to 50 (500 ms). If you did not issue the setsockopt function to define this value for this socket, the system default value (the value of the TCPDELAY parameter in CTK2) is returned. This option is valid only for TCP sockets that are using TCP/IP native stack support.

Note: The SO_TCPDELAY socket option is unique to the z/TPF system.

SO_TCPDUACK

Returns the duplicate acknowledgment (ACK) for fast retransmit value, which is the number of duplicate standalone ACKs that the z/TPF system receives for a given socket before generating a fast retransmit. A value of 0 means that fast retransmits will not happen for the socket. If you did not issue the setsockopt function to define this value for this socket, the system default value (the value of the TCPDUACK parameter in CTK2) is returned. This option is valid only for TCP sockets that are using TCP/IP native stack support.

Note: The SO_TCPDUACK socket option is unique to the z/TPF system.

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.

SO_UDPMPSIZ

Returns the maximum packet size of the socket. This option is valid only for UDP sockets.

Note:

For a UDP socket bound to one local IP address, the maximum packet size returned is the smaller value of the SO_UDPMPSIZ value defined for the socket by the setsockopt function (or the system default value (UDPMPSIZ) in CTK2 if you did not use setsockopt to define the value) and the maximum transmission unit (MTU) of the link associated with the local IP address.
For a UDP socket bound to all local IP addresses or not bound to any specific local IP address, the MTU of the link over which the packets will be sent is not known yet, so the value returned is the SO_UDPMPSIZ value defined for the socket by the setsockopt function (or the system default value (UDPMPSIZ) in CTK2 if you did not use setsockopt to define the value). Different links may have different MTU values, so the maximum packet size may be different for each link. Therefore, the actual maximum size of a given packet may be smaller than the value returned by this function.
The SO_UDPMPSIZ socket option is unique to the z/TPF system.

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 z/TPF Transmission Control Protocol/Internet Protocol for more information about socket errors.

E1052STATE: The socket was closed because the system was in or cycling down to 1052 state.
SOCFAULT: The pointer to the optval or optlen parameter is NULL.
SOCINVAL: The socket type is incorrect for the option passed.
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.

Programming considerations

The getsockopt function gets options associated with a socket.
When manipulating socket options, you must specify the name of the option and the level at which the option resides.
The length passed by the optlen parameter must be a minimum of 4 bytes.
All of the socket-level options except SO_LINGER expect optval to point to an integer and optlen to be set to the size of an integer. When the integer is nonzero, the option is enabled. When it is 0, the option is disabled. The SO_LINGER option expects optval to point to a linger structure. The linger structure is defined in the following example:
```
struct linger
      int     l_onoff;              /* option on/off */
      int     l_linger;             /* linger time   */
⋮
```
The l_onoff is set to 0 if the SO_LINGER option is being disabled. A nonzero value enables the option. The l_linger field specifies the amount of time to wait before completing a close when there is still data to be sent.
The getsockopt function is rejected if the socket and the bind function has not been issued.

Examples

The following example obtains out-of-band information.

#include <sys/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

See z/TPF Transmission Control Protocol/Internet Protocol for information about z/TPF TCP/IP support.