|
The getsockopt() call gets options associated with a socket.
It can be called only for sockets in the AF_INET domain. This call
is not supported in the AF_IUCV domain. While options can exist at
multiple protocol levels, they are always present at the highest socket
level.
When manipulating socket options, you must specify the
level at which the option resides and the name of that option. To
manipulate options at the socket level, the level parameter must be set to SOL_SOCKET as defined in SOCKET.H. To manipulate options
at the TCP level, the level parameter must be set to IPPROTO_TCP
as defined in SOCKET.H. To manipulate options at any other level,
such as the IP level, supply the appropriate protocol number for the
protocol controlling the option. Currently, the SOL_SOCKET, IPPROTO_TCP,
and IPPROTO_IP levels are supported. The getprotobyname() call can
be used to return the protocol number for a named protocol.
#include <manifest.h>
#include <bsdtypes.h>
#include <socket.h>
int getsockopt(int s, int level, int optname, char *optval, int *optlen
- Parameter
- Description
- s
- The socket descriptor.
- level
- The level to which the option is set.
- optname
- The name of a specified socket option. See GETSOCKOPT/SETSOCKOPT command values for the numeric
values of optname.
- optval
- Points to option data.
- optlen
- Points to the length of the option data.
The optval and optlen parameters are used to 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. The optlen parameter
points to the size of the buffer pointed to by the optval parameter. Initially, this size must be set to the size
of that buffer before calling getsockopt(). On return it is set to
the size of the data actually returned.
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 as defined in SOCKET.H. This structure
is defined in the following example: #include <manifest.h>
struct linger
{
int l_onoff; /* option on/off */
int l_linger; /* linger time */
};
The l_onoff field
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 linger on close.
The following option
is recognized at the TCP level (IPPROTO_TCP): - Option
- Description
- TCP_NODELAY
- Returns the status of Nagle algorithm (RFC 896). This
option is not supported for AF_IUCV sockets.
When optval is 0, Nagle algorithm is enabled and TCP will wait to send
small packets of data until the acknowledgment for the previous data
is received.
When optval is nonzero,
Nagle algorithm is disabled and TCP will send small packets of data
even before the acknowledgment for previous data sent is received.
The following options are recognized at the
socket level (SOL_SOCKET): - Option
- Description
- SO_ACCEPTCONN
- Indicates whether listen() was called for a stream
socket.
- SO_BROADCAST
- Toggles the ability to broadcast messages. The default is disabled. When this option is enabled, it allows
the application to send broadcast messages over s when the interface specified in the destination supports
the broadcasting of packets. This option has no meaning for stream
sockets.
- SO_CLUSTERCONNTYPE
- Returns a bit mapped 32–bit value. One or more than one of the
following values will be returned:
- No Conn means that the socket is not connected.
- None means that the socket is active, but the partner is not in
the same cluster. If this indicator is set, the other 3 indicators
are 0.
- Same cluster means that the connection partners are in the same
cluster.
- Same image means that the connection partners are in the same MVS™ image. SO_CLUSTERCONNTYPE_SAME_CLUSTER
will also be set. If the connection partner is a distributed DVIPA,
the same image bit will not be on since the exact hosting stack is
not known.
- Internal means that communication from this node to the stack
hosting the partner application is not sent on links/interfaces exposed
outside the cluster (sysplex). To determine if both ends of the connection
flow over internal links/interfaces, the partner application must
also issue this getsockopt() and both ends exchange their results
from this socket call (through an application-dependent method).
Note: If the destination IP address for a connection (partner's IP address)
is a dynamic VIPA or distributed dynamic VIPA residing in the cluster,
the internal indicator will not be on because traffic for these connections
can be forwarded to the target TCP/IP stacks over links or interfaces
that are external to the cluster.
An internal indicator
means that for this side of the connection, the link/interface type
is one of the following types: - CTC
- HiperSockets™ (iQDIO)
- MPCPTP (including XCF and IUTSAMEH connections)
- OSA-Express QDIO with CHPID type OSX or OSM
- Loopback
- Or both partners are owned by the same multi-homed stack
On return, one or more of the following bits are set:
00000000 00000000 00000000 00000001'-SO_CLUSTERCONNTYPE_NONE
00000000 00000000 00000000 00000010'-SO_CLUSTERCONNTYPE_SAME_CLUSTER
00000000 00000000 00000000 00000100'-SO_CLUSTERCONNTYPE_SAME_IMAGE
00000000 00000000 00000000 00001000'-SO_CLUSTERCONNTYPE_INTERNAL
00000000 00000000 00000000 00000000'-SO_CLUSTERCONNTYPE_NOCONN
Note: A value of all zeros means that there is no active connection
on the socket. This is usually the case for a listening socket. This
is also true for a client socket before the client issues connect().
The caller should first check for a returned value of SO_CLUSTERCONNTYPE_NOCONN
before checking for any of the other returned indicators.
If getsockopt() (SO_CLUSTERCONNTYPE) is issued before the connection
has been established, it results in a return value of 0.
If
the application issues getsockopt() (SO_CLUSTERCONNTYPE) on a connected
socket, and has received an indication of SO_CLUSTERCONNTYPE_INTERNAL,
any subsequent rerouting decisions because of current route failure
will either select an alternate route, which is also SO_CLUSTERCONNTYPE_INTERNAL,
or fail the connection with no route available indications. This means
that when an application has received an indication of SO_CLUSTERCONNTYPE_INTERNAL
on a connection, any subsequent rerouting preserves that indication
on the new route, or will fail the connection. This ensures that a
connection that an application relies on as being internal does not
transparently become non-internal because of a routing change.
If the application never issues the new getsockopt() or if the
connection was previously reported as not SO_CLUSTERCONNTYPE_INTERNAL,
rerouting decisions are made as at present, and the rerouting is transparent
to the application as long as any alternate route exists.
- SO_DEBUG
- The sock_debug() call provides the socket library tracing facility.
The onoff parameter can have a value of
0 or nonzero. When onoff=0 (the default),
no socket library tracing is done; when onoff=nonzero, the system traces for socket library calls and interrupts.
- SO_ERROR
- Returns any error pending on the socket and clears the error status.
It can be used to check for asynchronous errors on connected datagram
sockets and for other asynchronous errors (errors returned explicitly
by one of the socket calls).
- SO_KEEPALIVE
- Toggles the TCP keep alive mechanism for a stream socket. The
default is disabled. When activated, the
keep alive mechanism periodically sends a packet along an otherwise
idle connection. If the remote TCP does not respond to the packet
or to retransmissions of the packet, the connection is terminated
with the error ETIMEDOUT.
- SO_LINGER
- Lingers on close if data is present. The default is disabled. When this option is enabled and there is
unsent data present when close() is called, the calling application
is blocked during the close() call until the data is transmitted,
or the connection has timed out. If this option is disabled, the close()
call returns without blocking the caller and the TCP/IP address space
still waits before trying to send the data. Although the data transfer
is usually successful, it cannot be guaranteed, because the TCP/IP
address space waits only a finite amount of time while trying to send
the data. This option has meaning only for stream sockets.
- SO_OOBINLINE
- Toggles reception of out-of-band data. The default is disabled. When this option is enabled, it causes out-of-band
data to be placed in the normal data input queue as it is received,
making it available to recv(), recvfrom(), and recvmsg() without specifying
the MSG_OOB flag in those calls. When this option is disabled, it
causes out-of-band data to be placed in the priority data input queue
as it is received, making it available to recv(), recvfrom(), and
recvmsg() only by specifying the MSG_OOB flag in those calls. This
option has meaning only for stream sockets.
- SO_RCVBUF
- Returns the size of the data portion of the TCP⁄IP send
buffer in optval. The size of the data portion
of the receive buffer is protocol-specific.
- SO_REUSEADDR
- Toggles local address reuse. The default is disabled. This alters
the normal algorithm used in the bind() call.
The normal bind()
call algorithm allows each internet address and port combination to
be bound only once. If the address and port have been bound already,
a subsequent bind() will fail and return error EADDRINUSE.
After the SO_REUSEADDR option is active, the following situations
are supported: - A server can bind() the same port multiple times as long as every
invocation uses a different local IP address, and the wildcard address
INADDR_ANY is used only one time per port.
- A server with active client connections can be restarted and can
bind to its port without having to close all of the client connections.
- For datagram sockets, multicasting is supported so multiple bind()
calls can be made to the same class D address and port number.
- SO_SNDBUF
- Returns the size of the data portion of the TCP⁄IP send
buffer in optval. The size of the data portion
of the send buffer is protocol-specific.
- SO_TYPE
- Returns the type of the socket. On return, the integer pointed
to by optval is set to SOCK_STREAM, SOCK_DGRAM,
or SOCK_RAW.
The following options are recognized at the
IP level (IPPROTO_IP): - Option
- Description
- IP_MULTICAST_TTL
- Gets the IP time to live of outgoing multicast datagrams.
The default value is 1 (multicast is available only to the local subnet).
- IP_MULTICAST_LOOP
- Used to determine whether outgoing multicast datagrams are looped
back.
- IP_MULTICAST_IF
- Gets the interface for sending outbound multicast datagrams from
the socket application.
Note: Multicast datagrams can be transmitted
only on one interface at a time.
Return values The value 0 indicates success;
the value -1 indicates an error. Errno identifies the specific error. - Errno
- Description
- EBADF
- The s parameter is not a valid socket
descriptor.
- EFAULT
- Using optval and optlen parameters would result in an attempt to access storage
outside the caller address space.
- EINVAL
- The optname parameter is unrecognized,
or the level parameter is not SOL_SOCKET.
Example The following examples show the getsockopt() call. See setsockopt() to see how the setsockopt() call
options are set.
Example 1 #include <manifest.h>
int rc;
int s;
int optval;
int optlen;
struct linger l;
int getsockopt(int s, int level, int optname, char *optval, int *optlen);
⋮
/* Is out of band data in the normal input queue? */
optlen = sizeof(int);
rc = getsockopt(
s, SOL_SOCKET, SO_OOBINLINE, (char *) &optval, &optlen);
if (rc == 0)
{
if (optlen == sizeof(int))
{
if (optval)
/* yes it is in the normalqueue */
else
/* no it is not */
}
}
⋮
Example 2 /* Do I linger on close? */
optlen = sizeof(l);
rc = getsockopt(
s, SOL_SOCKET, SO_LINGER, (char *) &l, &optlen);
if (rc == 0)
{
if (optlen == sizeof(l))
{
if (l.l_onoff)
/* yes I linger */
else
/* no I do not */
}
}
Related calls bind(), close(), getprotobyname(),
setsockopt(), socket()
|