getsockopt(2) getsockopt(2)
NAME [Toc] [Back]
getsockopt(), setsockopt() - get and set options on sockets
SYNOPSIS [Toc] [Back]
#include <sys/socket.h>
int getsockopt(
int s,
int level,
int optname,
void *optval,
int *optlen
);
int setsockopt(
int s,
int level,
int optname,
const void *optval,
int optlen
);
_XOPEN_SOURCE_EXTENDED Only (UNIX 98)
int getsockopt(
int s,
int level,
int optname,
void *optval,
socklen_t *optlen
);
int setsockopt(
int s,
int level,
int optname,
const void *optval,
socklen_t optlen
);
Obsolescent _XOPEN_SOURCE_EXTENDED Only (UNIX 95) [Toc] [Back]
int getsockopt(
int s,
int level,
int optname,
void *optval,
size_t *optlen
);
int setsockopt(
int s,
int level,
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
getsockopt(2) getsockopt(2)
int optname,
const void *optval,
size_t optlen
);
DESCRIPTION [Toc] [Back]
The getsockopt() and setsockopt() 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 SOL_SOCKET. To specify options at another level, level
should be the protocol number specified in <netinet/in.h> (for
example, IPPROTO_TCP).
The parameters optval and optlen specify the value of the option.
optval 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
non-zero (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 tc
.
For setsockopt(), optval and optlen are used to pass information from
the application to the system. optval is the address of a location in
memory that contains 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 getsockopt(), 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 getsockopt(), 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 getsockopt() returns without
error.
The following ``socket'' level option names (optname) are defined in
<sys/socket.h>. The type of the variable pointed to by optval is
indicated in parentheses. Options for other protocol levels are
described in the individual protocol manual pages, such as tcp(7P) and
ip(7P).
SO_ACCEPTCONN (int; boolean ) Returns a non-zero value
if socket listening is enabled,
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
getsockopt(2) getsockopt(2)
otherwise returns a zero value.
SO_BROADCAST (int; boolean; SOCK_DGRAM sockets only)
Allows the application to send messages
to a broadcast address. Default:
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,
broadcasts are not supported. For
validity in other domains, see
individual product manual.
SO_DEBUG (int; boolean; AF_INET SOCK_STREAM
sockets only) Enables or disables the
recording of internal debug information.
Default: disabled.
SO_DONTROUTE (int; boolean; AF_INET sockets only)
Causes outbound messages to bypass
normal routing facilities. Instead,
messages are sent through the
appropriate network interface based on
the network portion of the destination
address. Default: disabled.
SO_ERROR (int) Returns any pending error on the
socket, and clears the error status.
The value returned by SO_ERROR would be
the value of errno after the next socket
data transfer system call.
SO_KEEPALIVE (int; boolean; AF_INET SOCK_STREAM
sockets only) If enabled, keeps an
otherwise idle TCP connection active.
Default: disabled.
SO_LINGER (struct linger; AF_INET SOCK_STREAM
sockets only) Controls whether or not an
application "lingers" (waits) if there
are untransmitted data in the send
socket buffer when the socket is closed.
The data type struct linger is defined
in <sys/socket.h>. Default: disabled,
as if l_onoff had been set to zero.
(See details below.)
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
getsockopt(2) getsockopt(2)
SO_OOBINLINE (int; 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 MSG_OOB in the flags
parameter when the application reads the
data (see recv(2)). Default: disabled.
SO_RCVBUF (int) Specifies the maximum size, in
bytes, of the receive socket buffer.
For SOCK_DGRAM sockets, the receive
buffer size may limit the maximum size
of messages that the socket can receive.
Default and maximum values are
protocol-dependent; see individual
protocol manual entries, such as tcp(7P)
(default buffer size: 32768 bytes;
maximum buffer size: 1073725440 bytes;
maximum buffer size can be lowered using
the ndd variable tcp_recv_hiwater_max)
and udp(7P) (default buffer size:
2147483647 bytes; maximum buffer size:
2147483647 bytes; udp maximum receive
buffer size can be lowered using the ndd
parameter udp_recv_hiwater_max).
SO_REUSEADDR (int; boolean; AF_INET sockets only) If
enabled, allows a local address to be
reused in subsequent calls to bind().
Default: disallowed.
SO_REUSEPORT (int; boolean; AF_INET sockets only) If
enabled, allows a local address and port
to be reused in subsequent calls to
bind(). Default: disallowed.
SO_SNDBUF (int) 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 messages that the application
can send through the socket. Default
and maximum values are protocoldependent;
see individual protocol
manual entries, such as tcp(7P) (default
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
getsockopt(2) getsockopt(2)
send buffer size: 32768 bytes; maximum
send buffer size: 2147483647 bytes;
maximum buffer size can be lowered using
the ndd variable tcp_xmit_hiwater_max)
and udp(7P) (default send buffer size:
65535 bytes; maximum send buffer size:
2147483647 bytes).
SO_TYPE (int) Returns the socket type.
SO_USELOOPBACK (int; boolean) Not used internally;
provided only for compatibility.
Setting the SO_BROADCAST option allows the application to send
messages through the SOCK_DGRAM socket to a broadcast destination
address.
If SO_DONTROUTE 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 network address matches the network portion of the destination
address. If SO_DONTROUTE is not set (default), the system uses the
network routing tables.
If SO_KEEPALIVE is disabled (default), a TCP connection may remain
idle until the connection is released at the protocol layer. If
SO_KEEPALIVE 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 connection 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 system call (for example,
recv()) returns an error, and errno is set to ETIMEDOUT.
SO_LINGER 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 close() or because the
application terminates normally or abnormally. The action is
determined by the values of members of the struct linger data
structure pointed to by optval in a call to setsockopt(). The data
type struct linger is defined in <sys/socket.h>. If l_onoff is zero
(the default action), close() returns immediately, but the system
tries to transmit any unsent data and release the protocol connection
gracefully. If l_onoff is non-zero and l_linger is zero, close()
returns immediately, any unsent data is discarded, and the protocol
connection is aborted. If both l_onoff and l_linger are non-zero,
close() does not return until the system has tried to transmit all
unsent data and release the connection gracefully. In that case,
close() can return an error, and errno may be set to ETIMEDOUT, if the
system is unable to transmit the data after a protocol-defined time
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
getsockopt(2) getsockopt(2)
limit. Note that the value of l_linger is treated simply as a
boolean; a non-zero value is not interpreted as a time limit( see
_XOPEN_SOURCE_EXTENDED Only below). SO_LINGER does not affect the
actions taken when the function shutdown() is called.
If SO_OOBINLINE is set, out-of-band data (TCP "urgent data") is left
"in-line" among the normal data stream. In that case, the SIOCATMARK
ioctl() 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 SO_OOBINLINE 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 MSG_OOB 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 SO_REUSEADDR option allows the local socket address to be
reused in subsequent calls to bind(). 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 bind() is called for a new socket. For SOCK_DGRAM
sockets, SO_REUSEADDR 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, SO_REUSEADDR must be set
before calling bind().
Setting the SO_REUSEPORT 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 bind().
SO_RCVBUF and SO_SNDBUF specify the maximum number of bytes that the
system may allocate, as needed, for the receive and send buffers,
respectively. These limits are merely approximate because of the way
in which memory is allocated. 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 information, 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 connect() or listen(). An application can increase or
decrease the send buffer at any time.
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
getsockopt(2) getsockopt(2)
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,
respectively. These limits include socket buffer space that is also
used to save the sender's socket address (struct sockaddr) which is
associated with each datagram transmission. The sender's socket
address can be returned in the from parameter when recvfrom() is
called (see recv(2)).
AF_CCITT [Toc] [Back]
SO_SNDBUF and SO_RCVBUF are the only options supported for sockets of
the AF_CCITT address family.
_XOPEN_SOURCE_EXTENDED Only
The value of l_linger in the linger structure is interpreted as a time
limit in seconds.
RETURN VALUE [Toc] [Back]
getsockopt() and setsockopt() return the following values:
0 Successful completion.
-1 Failure. errno is set to indicate the error.
ERRORS [Toc] [Back]
If getsockopt() or setsockopt() fails, errno is set to one of the
following values:
[EBADF] The argument s is not a valid descriptor.
[EFAULT] The optval or optlen address is not valid.
[EINVAL] The level or optlen value is not valid; or optval
is the NULL address; or the protocol connection
has been released.
[ENOBUFS] Insufficient memory is available for internal
system data structures.
[ENOPROTOOPT] The option is not recognized at the specified
option level.
[ENOTSOCK] The argument s is not a socket descriptor.
[EOPNOTSUPP] The option is not supported by the socket family
or socket type.
OBSOLESCENCE [Toc] [Back]
Currently, the socklen_t and size_t types are the same size. This is
compatible with both the UNIX 95 and UNIX 98 profiles. However, in a
future release, socklen_t might be a different size. In that case,
passing a size_t pointer will evoke compile-time warnings, which must
be corrected in order for the application to behave correctly.
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
getsockopt(2) getsockopt(2)
Applications that use socklen_t now, where appropriate, will avoid
such migration problems. On the other hand, applications that need to
be portable to the UNIX 95 profile should follow the X/Open
specification (see xopen_networking(7)).
FUTURE DIRECTION [Toc] [Back]
Currently, the default behavior is the HP-UX BSD Sockets; however, it
might be changed to X/Open Sockets in a future release. At that time,
any HP-UX BSD Sockets behavior that is incompatible with X/Open
Sockets might be obsoleted. Applications that conform to the X/Open
specification now will avoid migration problems (see
xopen_networking(7)).
AUTHOR [Toc] [Back]
getsockopt() and setsockopt() were developed by HP and the University
of California, Berkeley.
SEE ALSO [Toc] [Back]
socket(2), getprotoent(3N), thread_safety(5), tcp(7P), udp(7P),
unix(7P), xopen_networking(7).
STANDARDS CONFORMANCE [Toc] [Back]
getsockopt(): XPG4
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003 [ Back ] |