getsockopt(2)getsockopt(2)NAMEgetsockopt - Get socket options
SYNOPSIS
#include <sys/socket.h>
int getsockopt(
int socket,
int level,
int option_nam,
void *option_value,
socklen_t *option_len );
[XNS4.0] The definition of the getsockopt() function in XNS4.0 uses a
size_t data type instead of a socklen_t data type as specified in
XNS5.0 (the previous definition).
[Tru64 UNIX] The following definition of the getsockopt() function
does not conform to current standards and is supported only for back‐
ward compatibility (see standards(5)): int getsockopt(
int socket,
int level,
int option_nam,
char *option_value,
int *option_len );
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
getsockopt(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the file descriptor for the socket. Specifies the protocol
level at which the option resides. To retrieve options at the socket
level, specify the level parameter as SOL_SOCKET. To retrieve options
at other levels, supply the appropriate protocol number for the proto‐
col controlling the option. For example, to indicate that an option
will be interpreted by the TCP protocol, set level to the protocol num‐
ber of TCP, as defined in the netinet/in.h header file, or as deter‐
mined by using the getprotobyname() function. Specifies a single
option to be retrieved. The socket level options can be enabled or dis‐
abled by the setsockopt() function. The getsockopt() function retrieves
information about the following options: Reports whether socket listen‐
ing is enabled. This option returns an int value. Reports whether
transmission of broadcast messages is supported. This option returns an
int value. [Tru64 UNIX] In a cluster, reports whether the socket will
use the default cluster alias as its source address. [Tru64 UNIX] In
a cluster, reports whether the socket can only receive packets
addressed to this cluster member. [Tru64 UNIX] In a cluster, reports
whether the socket must receive packets addressed to a cluster alias
and will drop any packets that are not addressed to a cluster alias.
Reports whether debugging information is being recorded. This option
returns an int value. Reports whether outgoing messages should bypass
the standard routing facilities. The destination must be on a directly-
connected network; messages are directed to the appropriate network
interface. The protocol in use determines the effect of this option.
(Not recommended, for debugging purposes only.) This option returns an
int value. Reports information about error status and clears it. This
option returns an int value. Reports whether connections are kept
active with periodic transmission of messages. If the connected socket
fails to respond to these messages, the connection is broken and pro‐
cesses using that socket are notified with a SIGPIPE signal. This
option returns an int value. Reports whether the socket lingers on a
close() function if data is present. If SO_LINGER is set, the system
blocks the process during the close() function until it can transmit
the data or until the time expires. If SO_LINGER is not specified, and
a close() function is issued, the system handles the call in a way that
allows the process to continue as quickly as possible. This option
returns an struct linger value. Reports whether the socket leaves
received out-of-band data (data marked urgent) in line. This option
returns an int value. Reports receive buffer size information. This
option returns an int value. Reports the minimum number of bytes (low-
water mark) for socket receive operations. The default value is 1. If
the value is set to a larger value, blocking receive calls wait until
they receive either the low water mark value or the requested value
(whichever is smaller). The calls might return less than the water mark
if an error occurs, a signal is received, or type of data in the
receive queue is different than that returned. This option returns an
int value. Reports receive time-out information. This option returns
a struct timeval value that specifies the amount of time to wait for a
receive operation to complete. If a receive operation has blocked for
the specified amount of time without receiving additional data, it
returns with a partial error count or errno set to [EAGAIN] or [EWOULD‐
BLOCK]. The default is 0 (zero), which indicates that a receive opera‐
tion will not time out. [Tru64 UNIX] In a cluster, reports whether
an attempt to bind the socket to a port in the reserved range
(512-1024) will fail if the port is marked static. Reports whether the
rules used in validating addresses supplied by a bind() function should
allow reuse of local addresses. This option returns an int value.
[Tru64 UNIX] In a cluster, reports whether the socket can reuse a
locked cluster alias port. Reports send buffer size information. This
option returns an int value. Reports the minimum number of bytes (low-
water mark) for socket transmit operations. Non-blocking transmit oper‐
ations process no data if flow control does not allow either the send
low water mark value or the entire request (whichever is smaller) to be
processed. This option returns an int value. Reports send time-out
information. This option returns a struct timeval value that specifies
the amount of time a transmit function blocks when flow control pre‐
vents the transmission of data. If a transmit operation blocks for this
amount of time without transmitting data, it returns with a partial
error count or errno set to [EAGAIN] or [EWOULDBLOCK]. The default is 0
(zero), which indicates that a transmit operation will not time out.
Reports the socket type. This option returns an int value. Only valid
for routing sockets. Reports whether the sender receives a copy of
each message. This option returns an int value.
[Tru64 UNIX] Options at other protocol levels vary in format
and name. See the tcp(7) and ip(7) reference pages for more
information on option names relevant for TCP and IP options
respectively.
Note
[Tru64 UNIX] The default values for socket level options
like SO_SENDBUF, SO_RCVBUF, SO_SNDLOWAT, and SO_RCVLOWAT are not
constant across different protocols and implementations. Use the
getsockopt(2) routine to obtain the default values programmati‐
cally. The address of a buffer. Specifies the length of buffer
pointed to by option_value. The option_len parameter initially
contains the size of the buffer pointed to by the option_value
parameter. On return, the option_len parameter is modified to
indicate the actual size of the value returned. If no option
value is supplied or returned, the option_value parameter can be
0 (zero). Options at other protocol levels vary in format and
name.
DESCRIPTION
The getsockopt() function allows an application program to query socket
options. The calling program specifies the name of the socket, the name
of the option, and a place to store the requested information. The
operating system gets the socket option information from its internal
data structures and passes the requested information back to the call‐
ing program.
Options may exist at multiple protocol levels. They are always present
at the uppermost socket level. When retrieving socket options, specify
the level at which the option resides and the name of the option.
RETURN VALUES
Upon successful completion, the getsockopt() function returns a value
of 0 (zero). Otherwise, a value of -1 is returned, and errno is set to
indicate the error.
ERRORS
If the getsockopt() function fails, errno may be set to one of the fol‐
lowing values: The calling process does not have appropriate permis‐
sions. The socket parameter is not valid. [POSIX] The send and
receive timeout values are too large to fit in the timeout fields of
the socket structure. The address pointed to by the option_value
parameter is not in a valid (writable) part of the process space, or
the option_len parameter is not in a valid part of the process address
space. The option_value or option_len parameter is invalid; or the
socket is shut down. Insufficient resources are available in the sys‐
tem to complete the call. The option is unknown. The available
STREAMS resources were insufficient for the operation to complete. The
socket parameter refers to a file, not a socket. [XNS4.0] The opera‐
tion is not supported by the socket protocol.
SEE ALSO
Functions: bind(2), close(2), endprotoent(3), getprotobynumber(3), get‐
protoent(3), setprotoent(3), setsockopt(2), socket(2).
NetworkInformation: ip(7), tcp(7).
Standards: standards(5).
Network Programmer's Guide
getsockopt(2)