getsockopt(2) CLIX getsockopt(2)
NAME
getsockopt, setsockopt - Gets and sets options on sockets
LIBRARY
Berkeley Software Distribution Library (libbsd.a)
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int getsockopt(
int s ,
int level ,
int optname ,
char *optval ,
int *optlen );
int setsockopt(
int s ,
int level ,
int optname ,
char *optval ,
int *optlen );
PARAMETERS
s Represents a socket descriptor.
level Represents the protocol level at which the specified action is
to be set.
optname Specifies the option that is to be set.
optval Points to the value that the option should have.
optlen Specifies the amount of space pointed to by optval.
DESCRIPTION
The getsockopt() and setsockopt() functions manipulate options associated
with a socket. Options may exist at multiple protocol levels; they are
always present at the uppermost socket level.
When manipulating socket options, the level at which the option resides
and the name of the option must be specified. To manipulate options at
the socket level, level is specified as SOL_SOCKET. To manipulate options
at any other level, the protocol number of the appropriate protocol
2/94 - Intergraph Corporation 1
getsockopt(2) CLIX getsockopt(2)
controlling the option is supplied.
The optval and optlen parameters are used to access option values for
setsockopt(). For getsockopt(), they identify a buffer in which the value
for the requested options will be returned. For getsockopt(), optlen is a
value-result parameter, initially containing the size of the buffer
pointed to by optval, and modified on return to indicate the actual size
of the value returned. If no option value will be supplied or returned,
optval may be supplied as 0.
The 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, described
below. Options at other protocol levels vary in format and name. Consult
the appropriate entries in section 7.
Most socket-level options take an int parameter for optval. For
setsockopt(), the parameter should be nonzero to enable a boolean option,
or 0 to disable the option.
The following options are recognized at the socket level. Except as
noted, each may be examined with getsockopt() and set with setsockopt().
SO_DEBUG
Toggle recording of debugging information.
SO_REUSEADDR
Toggle local address reuse.
SO_KEEPALIVE
Toggle keeping connections alive.
SO_DONTROUTE
Toggle routing bypass for outgoing messages.
SO_LINGER
Linger on close if data is present.
SO_BROADCAST
Toggle permission to transmit broadcast messages.
SO_OOBINLINE
Toggle reception of out-of-band data in band.
SO_TYPE
Get the type of the socket (get only).
SO_DEBUG enables debugging in the underlying protocol modules.
SO_REUSEADDR indicates that the rules used in validating addresses
supplied in a bind() call should allow local addresses to be reused.
SO_KEEPALIVE enables the periodic transmission of messages on a connected
2 Intergraph Corporation - 2/94
getsockopt(2) CLIX getsockopt(2)
socket. If the connected party fails to respond to these messages, the
connection is considered broken and processes using the socket are
notified with a SIGPIPE signal. SO_DONTROUTE indicates that outgoing
messages should bypass the standard routing facilities. Instead, messages
are directed to the appropriate network interface according to the network
portion of the destination address.
SO_LINGER controls the action taken when unsent messages are queued on the
socket and a close() attempt is performed. If the socket promises
reliable delivery of data and SO_LINGER is set, the system will block 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. (A timeout
period, termed the linger interval, is specified in the setsockopt()
function when SO_LINGER is requested.) If SO_LINGER is disabled and a
close() call is issued, the system will process the close in a manner that
allows the process to continue as quickly as possible.
The option SO_BROADCAST requests permission to send broadcast datagrams on
the socket. With protocols that support out-of-band data, the
SO_OOBINLINE option requests that out-of-band data be placed in the normal
data input queue as received; it can then be accessed with recv() or
read() functions without the MSG_OOB flag. Finally, SO_TYPE is an option
used only with getsockopt(). SO_TYPE returns the type of the socket, such
as SOCK_STREAM; it is useful for servers that inherit sockets on startup.
EXAMPLES
To mark the socket so that the address can be reused:
int val = 1;
if (setsockopt(sd, SOL_SOCKET, SO_REUSEADDR, &val, sizeof(val)) == -1)
perror("Setsockopt failed");
NOTES
SO_SNDBUF, SO_RCVBUF and SO_ERROR are not supported in this
implementation. An attempt to set or get one of these options will result
in errno being set to ENOPROTOOPT.
SO_DEBUG and SO_DONTROUTE are always off in this implementation.
Attempting to turn them on will result in errno being set to ENOPROTOOPT.
Attempting to turn them off will succeed.
SO_BROADCAST are always on in this implementation. Attempting to turn it
off will result in errno being set to ENOPROTOOPT. Attempting to turn it
on will succeed.
SO_LINGER is always on in this implementation. Attempting to turn linger
off will result in errno being set to ENOPROTOOPT. The linger interval is
2/94 - Intergraph Corporation 3
getsockopt(2) CLIX getsockopt(2)
always set to -1 meaning block indefinitely until all data is transmitted.
RETURN VALUES
Upon successful completion, a value of 0 is returned. Otherwise, a value
of -1 is returned and errno is set to indicate the error.
ERRORS
The getsockopt() and setsockopt() functions fail if one or more of the
following is true:
[EBADF]
The descriptor is invalid.
[ENOTSOCK]
The descriptor references a file, not a socket.
[EFAULT]
One of the option parameters is not in a valid part of the user
address space.
[EINVAL]
The optlen parameter is larger than the maximum option length
(setsockopt()) or the specified option does not exist for the given
protocol.
[ENOPROTOOPT]
The specified option is unknown at the level indicated.
RELATED INFORMATION
Functions: read(2), socket(2), getprotoent(3), bind(2), recv(2)
4 Intergraph Corporation - 2/94