GETSOCKOPT(2,L) AIX Technical Reference GETSOCKOPT(2,L)
-------------------------------------------------------------------------------
getsockopt, setsockopt
PURPOSE
Gets and sets options on sockets.
LIBRARY
Internet Library (libc.a)
SYNTAX
#include <sys/types.h>
#include <sys/socket.h>
int getsockopt (s, level, optname, optval, optlen)
int s, level, optname;
char *optval;
int *optlen;
int setsockopt (s, level, optname, optval, optlen)
int s, level, optname;
char *optval;
int optlen;
DESCRIPTION
The getsockopt and setsockopt system calls 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, you must specify the level at which the
option resides and the name of the option. To manipulate options at the socket
level, specify level as SOL_SOCKET. To manipulate options at any other level,
supply the appropriate protocol number for the protocol controlling the option.
For example, to indicate that an option will be interpreted by the TCP
protocol, set level to the protocol number of TCP. For more information, see
page getprotoent-1.
Use the parameters optval and optlen to access option values for setsockopt.
For getsockopt, these parameters identify a buffer in which the value for the
requested option or options are returned. For getsockopt, the optlen parameter
initially contains the size of the buffer pointed to by the optval parameter.
On return, the optlen parameter is modified to indicate the actual size of the
value returned. If no option value is supplied or returned, the optval
parameter can be 0.
Most socket-level options take an int parameter for optval. For setsockopt,
the parameter should be nonzero to enable a boolean option, or 0 if the option
Processed November 7, 1990 GETSOCKOPT(2,L) 1
GETSOCKOPT(2,L) AIX Technical Reference GETSOCKOPT(2,L)
is to be disabled. SO_LINGER uses a struct linger parameter, defined in
sys/socket.h, which specifies the desired state of the option and the linger
interval.
The optname parameter and any specified options are passed uninterpreted to the
appropriate protocol module for interpretation. The sys/socket.h header file
contains definitions for socket level options. These options are:
SO_DEBUG Turns on recording of debugging information.
SO_REUSEADDR Allows local address reuse.
SO_KEEPALIVE Keeps connections active.
SO_DONTROUTE Does not apply routing on outgoing messages.
SO_LINGER Lingers on a close system call if data is present.
SO_OOBINLINE Leaves received out-of-band data (data marked urgent) in line.
SO_SNDBUF Sends buffer size.
SO_RCVBUF Receives buffer size.
SO_ERROR Gets error status.
SO_TYPE Gets socket type.
SO_BROADCAST Request permission to transmit broadcast messages.
SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR
indicates that the rules used in validating addresses supplied by a bind system
call should allow reuse of local addresses. SO_KEEPALIVE enables the periodic
transmission of messages on a connected socket. If the connected socket fails
to respond to these messages, the connection is broken and processes using that
socket are notified with a SIGPIPE signal. SO_DONTROUTE indicates that
outgoing messages should bypass the standard routing facilities and 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 a socket and a close system call is performed. If
SO_LINGER is set, the system blocks the process during the close system call
until it can transmit the data or until the time expires. Specify the amount
of time for the linger interval by using the setsockopt system call when
requesting SO_LINGER. If SO_LINGER is not specified and a close system call is
issued, the system handles the call in a way 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 will then be accessible with recv or read system calls without the
MSG_OOB flag. SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer
sizes allocated for output and input buffers, respectively. The buffer size
may be increased for high-volume connections, or may be decreased to limit the
possible backlog of incoming data. The system places an absolute limit on
these values. Finally, SO_TYPE and SO_ERROR are options used only with
setsockopt. SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is
useful for servers that inherit sockets on startup. SO_ERROR returns any
pending error on the socket and clears the error status. It may be used to
check for asynchronous errors on connected datagram sockets or for other
asynchronous errors.
Processed November 7, 1990 GETSOCKOPT(2,L) 2
GETSOCKOPT(2,L) AIX Technical Reference GETSOCKOPT(2,L)
Options at other protocol levels vary in format and name.
RETURN VALUE
Upon successful completion, a value of 0 is returned. If the getsockopt or
setsockopt system call fails, a value of -1 is returned, and errno is set to
indicate the error.
ERROR CONDITIONS
The system calls fail if one or more of the following are true:
EBADF The s parameter is not valid.
ENOTSOCK The s parameter refers to a file, not a socket.
ENOPROTOOPT The option is unknown.
EFAULT The optval parameter is not in a writable part of the user
address space.
RELATED INFORMATION
In this book: "getprotoent, getprotobynumber, getprotobyname, setprotoent,
endprotoent," and "socket."
Processed November 7, 1990 GETSOCKOPT(2,L) 3