getsockopt(2)getsockopt(2)NAMEgetsockopt(), setsockopt() - get and set options on sockets
SYNOPSIS
UNIX 03 Only (X/Open Sockets)
Obsolescent UNIX 95 Only (X/Open Sockets)
DESCRIPTION
The and system calls manipulate options associated with a socket. The
socket is identified by the socket descriptor s. Options can exist at
multiple protocol levels, and they are always present at the uppermost
"socket" level (see socket(2)).
When manipulating socket options, the level at which the option resides
(level) and the name of the option (optname) must be specified. To
manipulate options at the "socket" level, level is specified as To
specify options at another level, level should be the protocol number
specified in (for example,
The parameters optval and optlen specify the value of the option. opt‐
val is the address of the data structure that contains the option
value, and optlen is the length of the data structure. The type and
value of the data structure that optval points to depends on the
option. For "boolean" options, the value may be zero (not set) or
nonzero (set). The value of other options depends on the purpose of
the option. Usually, neither optval nor optlen may be the NULL address
or zero; see individual protocol manual entries for any exceptions,
such as TCP(7P) and IP(7P).
For optval and optlen are used to pass information from the application
to the system. optval is the address of a location in memory that con‐
tains the option information to be passed to the system. The parameter
optlen is an integer value that specifies the size, in bytes, of the
data structure pointed to by optval.
For optval and optlen are used to pass information from the system to
the application. The parameter optlen is the address of a variable.
Before calling the application should set the value of the variable to
the maximum size, in bytes, of the data structure pointed to by optval.
Normally, upon return, the variable pointed to by optlen is set to the
actual size the data returned in the structure pointed to by optval, if
returns without error.
The following "socket" level option names (optname) are defined in The
type of the variable pointed to by optval is indicated in parentheses.
Options for other protocol levels are described in the individual pro‐
tocol manual pages, such as TCP(7P) and IP(7P).
boolean ) Returns a non-zero value if socket lis‐
tening is enabled, otherwise returns a
zero value.
boolean; SOCK_DGRAM sockets only)
Allows the application to send messages
to a broadcast address. disallowed.
Note, the actual effect of this option
is communication domain dependent. In
AF_INET domain, broadcasts are always
allowed regardless of the value set for
this option. In AF_UNIX domain, broad‐
casts are not supported. For validity
in other domains, see individual prod‐
uct manual.
boolean; AF_INET SOCK_STREAM sockets only)
Enables or disables the recording of
internal debug information. disabled.
boolean; AF_INET sockets only)
Causes outbound messages to bypass nor‐
mal routing facilities. Instead, mes‐
sages are sent through the appropriate
network interface based on the network
portion of the destination address.
disabled.
Returns any pending error on the socket, and
clears the error status. The value
returned by would be the value of after
the next socket data transfer system
call.
boolean; AF_INET SOCK_STREAM sockets only)
If enabled, keeps an otherwise idle TCP
connection active. disabled.
AF_INET SOCK_STREAM sockets only)
Controls whether or not an application
"lingers" (waits) if there are untrans‐
mitted data in the send socket buffer
when the socket is closed. The data
type is defined in disabled, as if had
been set to zero. (See details below.)
boolean; AF_INET SOCK_STREAM sockets only)
If enabled, specifies that out-of-band
data (TCP "urgent data") should be left
"in-line" among the normal data stream.
Otherwise, one byte of out-of-band data
is pulled out of the data stream, and
it is accessible only by setting in the
flags parameter when the application
reads the data (see recv(2)). dis‐
abled.
Specifies the maximum size, in bytes, of the receive socket
buffer. For SOCK_DGRAM sockets, the
receive buffer size may limit the maxi‐
mum size of messages that the socket
can receive.
protocol-dependent; see individual pro‐
tocol manual entries, such as TCP(7P)
(default buffer size: 32768 bytes; max‐
imum buffer size: 1073725440 bytes;
maximum buffer size can be lowered
using the variable tcp_recv_hiwa‐
ter_max) and UDP(7P) (default buffer
size: 2147483647 bytes; maximum buffer
size: 2147483647 bytes; udp maximum
receive buffer size can be lowered
using the parameter udp_recv_hiwa‐
ter_max).
boolean; AF_INET sockets only)
If enabled, allows a local address to
be reused in subsequent calls to disal‐
lowed.
boolean; AF_INET sockets only)
If enabled, allows a local address and
port to be reused in subsequent calls
to disallowed.
Specifies the maximum size, in bytes, of the send socket
buffer. For SOCK_STREAM sockets, the
send buffer size limits how much data
can be queued for transmission before
the application is blocked. For
SOCK_DGRAM sockets, the send buffer
size may limit the maximum size of mes‐
sages that the application can send
through the socket.
protocol-dependent; see individual pro‐
tocol manual entries, such as TCP(7P)
(default send buffer size: 32768 bytes;
maximum send buffer size: 2147483647
bytes; maximum buffer size can be low‐
ered using the variable tcp_xmit_hiwa‐
ter_max) and UDP(7P) (default send buf‐
fer size: 65535 bytes; maximum send
buffer size: 2147483647 bytes).
Returns the socket type.
boolean) Not used internally; provided only for compatibility.
Setting the option allows the application to send messages through the
SOCK_DGRAM socket to a broadcast destination address.
If is set, the system does not use the network routing tables when
determining which interface to use to send an outbound message.
Instead, the system sends the message through the interface whose net‐
work address matches the network portion of the destination address.
If is not set (default), the system uses the network routing tables.
If is disabled (default), a TCP connection may remain idle until the
connection is released at the protocol layer. If is enabled and the
connection has been idle for two hours, TCP sends a packet to the
remote socket, expecting the remote TCP to acknowledge that the connec‐
tion is still active. If the remote TCP does not respond in a timely
manner, TCP continues to send keepalive packets according to the normal
retransmission algorithm. If the remote TCP does not respond within a
particular time limit, TCP drops the connection. The next socket sys‐
tem call (for example, returns an error, and is set to
controls the actions to be taken when there are untransmitted data in a
SOCK_STREAM send socket buffer when the socket is closed, either due to
an explicit call to or because the application terminates normally or
abnormally. The action is determined by the values of members of the
data structure pointed to by optval in a call to The data type is
defined in If is zero (the default action), returns immediately, but
the system tries to transmit any unsent data and release the protocol
connection gracefully. If is non-zero and is zero, returns immedi‐
ately, any unsent data is discarded, and the protocol connection is
aborted. If both and are non-zero, does not return until the system
has tried to transmit all unsent data and release the connection grace‐
fully or until a protocol-defined time limit. Note that the value of
is treated simply as a boolean; a non-zero value is interpreted as a
time limit (see below). does not affect the actions taken when the
function is called.
If is set, out-of-band data (TCP "urgent data") is left "in-line" among
the normal data stream. In that case, the SIOCATMARK request must be
used to determine if the inbound data stream has been read up to the
point where the out-of-band data begins. If multiple transmissions of
out-of-band data are received before the application reads them, all of
the data is left in-line; however, SIOCATMARK indicates the location of
only the last transmission of out-of-band data. If is not set
(default), only one byte of out-of-band is saved. This byte is pulled
out of the normal data stream, and it is accessible only by setting in
the flags parameter when the application reads the data (see recv(2)).
In that case, if multiple transmissions of out-of-band data are
received before the application reads them, previous bytes of out-of-
band data are lost.
Setting the option allows the local socket address to be reused in sub‐
sequent calls to This permits multiple SOCK_STREAM sockets to be bound
to the same local address, as long as all existing sockets with the
desired local address are in a connected state before is called for a
new socket. For SOCK_DGRAM sockets, allows multiple sockets to receive
UDP multicast datagrams addressed to the bound port number. For all
SOCK_DGRAM sockets bound to the same local address, must be set before
calling
Setting the option allows multiple SOCK_DGRAM sockets to share the same
address and port. Each one of those sockets, including the first one
to use that port, must specify this option before calling
and specify the maximum number of bytes that the system may allocate,
as needed, for the receive and send buffers, respectively. These lim‐
its are merely approximate because of the way in which memory is allo‐
cated. For example, a large number of small transmissions may require
more memory than the sum of the number of data bytes sent. The default
receive and send buffer sizes are protocol-specific. For more informa‐
tion, see the appropriate manual entries, such as TCP(7P) and UDP(7P).
For SOCK_STREAM sockets, larger buffer sizes can improve performance.
An application can increase the size of the receive buffer at any time;
however, it can decrease the receive buffer size only prior to calling
or An application can increase or decrease the send buffer at any time.
For SOCK_DGRAM sockets, the size of the receive and send buffers limits
the size of the maximum datagram that can be received and sent, respec‐
tively. These limits include socket buffer space that is also used to
save the sender's socket address which is associated with each datagram
transmission. The sender's socket address can be returned in the from
parameter when is called (see recv(2)).
AF_CCITT Only
and are the only options supported for sockets of the AF_CCITT address
family.
X/Open Sockets Only
The value of in the linger structure is interpreted as a time limit in
seconds.
X/Open Sockets Compilation Environment
See xopen_networking(7).
RETURN VALUE
and return the following values:
Successful completion.
Failure.
is set to indicate the error.
ERRORS
If or fails, is set to one of the following values:
The argument s is not a valid descriptor.
The optval or optlen address is not valid.
The level or optlen value is not valid; or opt‐
val is the NULL address; or the protocol
connection has been released.
Insufficient memory is available for internal system data struc‐
tures.
The option is not recognized at the specified option level.
The argument s is not a socket descriptor.
The option is not supported by the socket family or socket type.
The operation was interrupted by a signal.
Application needs to retry if it wants to
get the value of an option or retry to set
an option.
OBSOLESCENCE
Currently, the and types are the same size. This is compatible with
the UNIX 95 and UNIX 03 profiles. However, in a future release, might
be a different size. In that case, passing a pointer will evoke com‐
pile-time warnings, which must be corrected in order for the applica‐
tion to behave correctly. Applications that use now, where appropri‐
ate, will avoid such migration problems. On the other hand, applica‐
tions that need to be portable to the UNIX 95 profile should follow the
X/Open specification (see xopen_networking(7)).
WARNINGS
Linking binary objects compiled to specification and binary objects
compiled to specification to the same executable may result in unex‐
pected behavior, including application abnormal termination and unex‐
pected socket errors. See xopen_networking(7) for details and remedy.
FUTURE DIRECTION
Currently, the default behavior is the however, it might be changed to
in a future release. At that time, any behavior that is incompatible
with might be obsoleted. Applications that conform to the X/Open spec‐
ification now will avoid migration problems (see xopen_networking(7)).
AUTHOR
and were developed by HP and the University of California, Berkeley.
SEE ALSOsocket(2), getprotoent(3N), thread_safety(5), IP(7P), sctp(7), TCP(7P),
UDP(7P), UNIX(7P), xopen_networking(7).
STANDARDS CONFORMANCEgetsockopt(2)