HPUX getsockopt[2]
getsockopt(2) getsockopt(2)
NAME
getsockopt, setsockopt - get and set options on sockets
SYNOPSIS
#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);
DESCRIPTION
getsockopt() and setsockopt() 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.
There are two kinds of options: boolean and non-boolean. Boolean
options are either set or not set and also can use optval and optlen
(see below) to pass information. Non-boolean options always use
optval and optlen to pass information.
To determine whether boolean option optname is set, the return value
of getsockopt() must be examined. If the option is set, getsockopt()
returns without error. If the boolean option is not set, getsockopt()
returns -1 and errno is set to indicate the error.
For setsockopt(), the parameters optval and optlen are used to pass
option information from the system to the calling process. optval is
the address of a location in memory that contains the option
information to be passed to the system. optlen is an integer that
specifies the size in bytes of the option information.
For getsockopt(), optval and optlen are used to pass option
information from the system to the calling process. optval is the
address of a location in memory that contains the option information
to be passed to the calling process, or (char *) NULL if the option
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
getsockopt(2) getsockopt(2)
information is not of interest and not to be passed to the calling
process. optlen is an address of an integer initially used to specify
the maximum number of bytes of option information to be passed. If
optval is not (char *) NULL, optlen is set on return to the actual
number of bytes of option information passed. If the getsockopt()
call fails, no option information is passed.
optname and any specified options are passed uninterpreted to the
appropriate protocol module for interpretation. The include file
<sys/socket.h> contains definitions for ``socket'' level options (see
socket(2)). Options at other protocol levels vary in format and name.
Consult the appropriate entries in Section 7P, such as tcp(7P).
The ``socket'' level options defined in the include file
<sys/socket.h> are explained below:
SO_DEBUG (boolean option) no functionality;
included only for compatibility.
SO_DONTROUTE (boolean option; SOCK_STREAM sockets
only) causes outgoing messages to bypass
standard routing facilities and to be
routed by the network portion of the
Internet address.
SO_ERROR returns the current contents of the
variable so_error for this socket and
then clears the variable (so_error is
defined in <sys/socketvar.h>. The
contents match those found in errno.
SO_REUSEADDR (boolean option; AF_INET sockets only)
allows local address reuse.
SO_KEEPALIVE (boolean option; SOCK_STREAM and AF_INET
<<<<<<< getsockopt.2 sockets only) keeps
otherwise idle connections active. If a
connection has been idle for two hours,
transmissions are forced every 75
seconds until a response is received or
10 minutes expires, whichever occurs
first. If 10 minutes expires with no
response, the connection is dropped.
SO_LINGER (boolean option; SOCK_STREAM and AF_INET
sockets only) lingers on close if data
is present. For SO_LINGER, optval
points to a struct linger , defined in
/usr/include/sys/socket.h. The linger
structure contains an integer boolean
flag to toggle behavior on/off and an
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
getsockopt(2) getsockopt(2)
integer linger value.
SO_BROADCAST (boolean option; SOCK_DGRAM and AF_INET
sockets only) toggles permission to
transmit broadcast messages.
SO_RCVBUF (non-boolean option) For stream sockets
it changes the buffer size of a socket's
receive socket buffer. For datagram
sockets it changes the maximum size
message a socket can receive. A stream
socket's buffer size can be increased at
any time but decreased only prior to
establishing a connection. For datagram
sockets, the inbound maximum message
size can be increased or decreased at
any time. The default and maximum
values for SO_RCVBUF are protocol-
specific. Refer to the appropriate
entries in Sections 7F and 7P.
SO_SNDBUF (non-boolean option) For stream sockets,
it changes the buffer size of a socket's
send socket buffer. For datagram
sockets it changes the maximum size
message that can be sent. A stream
socket's buffer size can be increased at
any time but decreased only prior to
establishing a connection. For datagram
sockets, the maximum outbound message
size can be increased or decreased at
any time. The default and maximum
values for SO_SNDBUF are protocol-
specific. Refer to the appropriate
entries in Sections 7F and 7P.
SO_USELOOPBACK (boolean option) no functionality;
included only for compatibility.
None of the boolean options are supported for SOCK_DGRAM sockets.
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 out through the
interface that has a configured address matching the address to which
the message is intended to be sent. If SO_DONTROUTE is not set, the
system uses the network routing tables.
SO_REUSEADDR indicates the rules used in validating addresses supplied
in a bind() call should allow reuse of local addresses. This allows
multiple SOCK_STREAM sockets to be bound to the same local address, as
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
getsockopt(2) getsockopt(2)
long as all existing sockets at the desired address are in a connected
state before the bind() is done on the new socket. The SO_REUSEADDR
option has no effect on SOCK_DGRAM sockets.
The SO_KEEPALIVE option defaults to off. If SO_KEEPALIVE is set on
and the connection has been idle for two hours, TCP sends a packet to
the remote socket to acknowledge that it is still alive. If the
remote socket does not respond within 75 seconds, TCP sends another
packet. If TCP sends a total of 8 packets without response from the
remote socket (i.e., 10 minutes have passed), TCP drops the
connection. The next socket call (e.g., recv()) returns an error, and
errno is set to ETIMEDOUT.
SO_LINGER controls the actions taken when unsent messages are queued
on a SOCK_STREAM socket and a close(2) is performed. If SO_LINGER is
toggled on with a non-zero linger interval, the system blocks the
process on the close() attempt until it is able to transmit the data
or until it decides it is unable to deliver the information. If
SO_LINGER is toggled on with a linger interval of zero, the connection
is immediately terminated on the close() of the socket, and any unsent
data queued on the connection is lost. If SO_LINGER is toggled off
(default upon socket creation) and a close() is issued, the call
returns immediately. The system still gracefully brings down the
connection by transmitting any queued data, if possible. SO_LINGER
can be toggled on/off at any time during the life of an established
connection. Toggling SO_LINGER does not affect the action of
shutdown().
The SO_BROADCAST option requests permission to send Internet broadcast
datagrams on the socket.
For stream sockets, SO_RCVBUF and SO_SNDBUF can be used with
getsockopt() to find the current sizes (in number of bytes) of the
socket's receive and send buffers, respectively. If supported by the
protocol, SO_RCVBUF and SO_SNDBUF can also be used with setsockopt()
to set the sizes (in number of bytes) of the socket's receive and send
buffers, respectively. The sizes are passed as integer values using
optval and optlen. You can increase a socket's buffer size at any
time, but you can decrease it only prior to establishing a connection.
The default and maximum buffer sizes are protocol-specific. See the
appropriate entries in Sections 7F and 7P for more information.
For datagram sockets, SO_RCVBUF and SO_SNDBUF can be used with
getsockopt() to find the current maximum datagram size (in number of
bytes) in the inbound and outbound direction, respectively. SO_RCVBUF
and SO_SNDBUF can also be used with setsockopt() to set the maximum
datagram size. The default and maximum datagram sizes are protocol-
specific. See the appropriate entries in Sections 7F and 7P for more
information.
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
getsockopt(2) getsockopt(2)
AF_CCITT
SO_SNDBUF and SO_RCVBUF are the only options supported for sockets of
the AF_CCITT address family.
RETURN VALUE
Upon successful completion, getsockopt() and setsockopt() return 0;
otherwise, they return -1 and set errno to indicate the error.
DIAGNOSTICS
getsockopt() and setsockopt() fail if any of the following conditions
are encountered:
[EBADF] The argument s is not a valid descriptor.
[EOPNOTSUPP] The option is not supported by the protocol in use
by the socket.
[ENOBUFS] No buffer space is available.
[ENOTSOCK] The argument s is a file, not a socket.
[ENOPROTOOPT] In getsockopt(), the requested option is currently
not set.
[EINVAL] The option is unknown at the socket level or the
socket has been shut down.
[EFAULT] The optval or, in the case of getsockopt(), optlen
parameters are not valid pointers.
AUTHOR
getsockopt() was developed by the University of California, Berkeley.
SEE ALSO
socket(2), getprotoent(3N), af_ccitt(7F), tcp(7P), udp(7P), unix(7P).
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992