|
|
|
C Interface
#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. Options are described below
under the appropriate option.
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 or not a boolean option 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 ENOPROTOOPT.
For setsockopt, the parameters optval and
optlen are used to pass option information from the calling
process to the system. 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 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.
Options at other protocol levels vary in format and name.
The "socket" level options defined in the include file
<sys/socket.h> are explained below.
SOL_SOCKETS
When the socket level is SOL_SOCKETS, the following options are
available:
- SO_DEBUG
- (Boolean option) No functionality; included only for compatibility.
- SO_KEEPALIVE
- (Boolean option; AF_INET SOCK_STREAM sockets only) Keeps
otherwise idle connected sockets active by forcing transmissions every
600 seconds for up to four retransmissions without a response. The
length of time and number of retransmissions are configurable in NMMGR.
Default: Off
- SO_LINGER
- (Boolean option; AF_INET SOCK_STREAM sockets only) Lingers on
close if data is present. For SO_LINGER, optval
points to a struct linger, defined in <sys/socket.h>. The
linger structure contains an integer boolean flag to toggle behavior
on/off and an integer linger value.
Default: Off
- SO_BROADCAST
- (Boolean option; AF_INET SOCK_DGRAM sockets only) Toggles
permission to transmit broadcast messages.
Default: Off
- SO_ERROR
- Returns to the caller the last error stored in the socket record. This
error variable is then cleared in the socket record.
- SO_TYPE
- Returns the socket type. This option is typically used by a process that
inherits a socket when it is started.
SO_LINGER controls the actions taken when unsent messages are queued
on a SOCK_STREAM socket and a close 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_LINGERis 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.
The ip level option defined in the include file <netinet/in.h>
is explained below.
IPPROTO_IP
When the socket level is IPPROTO_IP, the following option is
available:
- IP_OPTIONS
- (AF_INET SOCK_DGRAM) Allows you to set and retrieve direct IP
header information.
IPPROTO_UDP
No options are defined for this level.
The tcp level option defined in the include file <netinet/tcp.h>
is described below.
IPPROTO_TCP
When the socket level is IPPROTO_TCP, the following option is
available:
- TCP_MAXSEG
- (AF_INET SOCK_STREAM) Returns the maximum segment size in use
for the socket. It defaults the size to 536 until the socket is
connected. The size is negotiated during connection establishment.
Return Value
If the call is successful, 0 is returned. If it fails, -1 is returned and an
error code is stored in errno.
Errors
The call to getsockopt or setsockopt fails if:
| Error Code |
Description |
| [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. |
| [ESOCKTNOSUPPORT] |
The socket is a NetIPC socket. |
Author
UCB (University of California at Berkeley)
See Also
close,
socket,
getprotoent
|
