'\"macro stdmacro
.if n .pH g3n.getsockopt @(#)getsockopt	40.8 of 1/29/90
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} getsockopt 3N "" "\&"
.if \nX=1 .ds x} getsockopt 3N ""
.if \nX=2 .ds x} getsockopt 3N "" "\&"
.if \nX=3 .ds x} getsockopt "" "" "\&"
.TH \*(x}
.SH NAME
\f4getsockopt\fP, \f4setsockopt\fP \- get and set options on sockets
.SH SYNOPSIS
.nf
.ft 4
#include <sys/types.h>
#include <sys/socket.h>
.LP
.ft 4
int getsockopt(s, level, optname, optval, optlen)
int s, level, optname;
char \(**optval;
int \(**optlen;
.sp
int setsockopt(s, level, optname, optval, optlen)
int s, level, optname;
char \(**optval;
int optlen;
.fi
.SH DESCRIPTION
.LP
\f4getsockopt\fP(\|)
and
\f4setsockopt\fP(\|)
manipulate
.I options
associated with a socket.
Options may exist at multiple protocol levels; they
are always present at the uppermost \(lqsocket\(rq level.
.LP
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 \(lqsocket\(rq level,
.I level
is specified as
.SM
\f4SOL_SOCKET\fP.
To manipulate options at any
other level, \f2level\fP is the protocol number of the protocol that
controls the option.
For example,
to indicate that an option is to be interpreted by the
.SM TCP
protocol,
.I level
is set to the
.SM TCP
protocol number
[see
\f4getprotoent\fP(3N)].
.LP
The parameters
.I optval
and
.I optlen
are used to access option values for
\f4setsockopt\fP(\|).
For
\f4getsockopt\fP(\|),
they identify a buffer in which the value(s) for the
requested option(s) are to be returned.
For
\f4getsockopt\fP(\|) ,
.I optlen
is a value-result parameter, initially containing the
size of the buffer pointed to by
.IR optval ,
and modified on return to indicate the actual size of
the value returned.
If no option value is to be supplied or returned,
a 0
.I optval
may be supplied.
.LP
.I optname
and any specified options are passed uninterpreted to the appropriate
protocol module for interpretation.
The include file
\f4/usr/include/sys/socket.h\fP
contains definitions for the socket-level
options described below.
Options at other protocol levels vary in format and
name.
.LP
Most socket-level options take an
.I int
for
.IR optval .
For
\f4setsockopt\fP(\|),
the
.I optval
parameter should be non-zero to enable a boolean option,
or zero if the option is to be disabled.
\f4SO_LINGER\fP
uses a
\f4struct linger\fP
parameter
that specifies the desired state of the option and the
linger interval (see below).
\f4struct linger\fP is defined in
\f4/usr/include/sys/socket.h\fP.
.LP
The following options are recognized at the socket level.
Except as noted, each may be examined with
\f4getsockopt\fP(\|)
and set with
\f4setsockopt\fP(\|).
.LP
.RS
.PD 0
.TP 20
\f4SO_DEBUG\fP
toggle recording of debugging information
.TP
\f4SO_REUSEADDR\fP
toggle local address reuse
.TP
\f4SO_KEEPALIVE\fP
toggle keep connections alive
.TP
\f4SO_DONTROUTE\fP
toggle routing bypass for outgoing messages
.TP
\f4SO_LINGER\fP
linger on close if data is present
.TP
\f4SO_BROADCAST\fP
toggle permission to transmit broadcast messages
.TP
\f4SO_OOBINLINE\fP
toggle reception of out-of-band data in band
.TP
\f4SO_SNDBUF\fP
set buffer size for output
.TP
\f4SO_RCVBUF\fP
set buffer size for input
.TP
\f4SO_TYPE\fP
get the type of the socket\fP(get only)
.TP
\f4SO_ERROR\fP
get and clear error on the socket\fP(get only)
.PD
.RE
.LP
\f4SO_DEBUG\fP
enables debugging in the underlying protocol modules.
\f4SO_REUSEADDR\fP
indicates that the rules used in validating addresses supplied
in a
\f4bind\fP(3N)
call should allow reuse of local addresses.
\f4SO_KEEPALIVE\fP
enables the
periodic transmission of messages on a connected socket.
If the
connected party fails to respond to these messages, the connection is
considered broken and processes using the socket are notified using a
\f4SIGPIPE\fP
signal.
\f4SO_DONTROUTE\fP
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.
.LP
\f4SO_LINGER\fP
controls the action taken when unsent messages are queued on a socket and a
\f4close\fP(2)
is performed.
If the socket promises reliable delivery of data and
\f4SO_LINGER\fP
is set, the system will block the process on the
\f4close\fP(\|)
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
\f4setsockopt\fP(\|)
call when
\f4SO_LINGER\fP
is requested).
If
\f4SO_LINGER\fP
is disabled and a
\f4close(\|)\fP
is issued, the system will process the \f4close(\|)\fP in a manner that allows
the process to continue as quickly as possible.
.LP
The option
\f4SO_BROADCAST\fP
requests permission to send broadcast datagrams on the socket.
With protocols that support out-of-band data, the
\f4SO_OOBINLINE\fP
option requests that out-of-band data be placed in the normal data input queue
as received; it will then be accessible with
\f4recv\fP(\|)
or
\f4read\fP(\|)
calls without the
\f4MSG_OOB\fP
flag.
\f4SO_SNDBUF\fP
and
\f4SO_RCVBUF\fP
are options that 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,
\f4SO_TYPE\fP
and
\f4SO_ERROR\fP
are options used only with
\f4getsockopt\fP(\|).
\f4SO_TYPE\fP
returns the type of the socket (for example,
\f4SOCK_STREAM)\fP.
It is useful for servers that inherit sockets on startup.
\f4SO_ERROR\fP
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.
.SH RETURN VALUE
.LP
A \f40\fP is returned if the call succeeds, \f4-1\fP if it fails.
.SH ERRORS
.LP
The call succeeds unless:
.TP 20
\f4EBADF\f1
The argument
.I s
is not a valid descriptor.
.TP
\f4ENOTSOCK\f1
The argument
.I s
is a file, not a socket.
.TP
\f4ENOPROTOOPT\f1
The option is unknown at the level indicated.
.TP
\f4ENOMEM\f1
There was insufficient user memory available for the operation
to complete.
.TP
\f4ENOSR\f1
There were insufficient
.SM STREAMS
resources available for the operation
to complete.
.SH "SEE ALSO"
\f4ioctl\fP(2),
\f4socket\fP(3N),
\f4getprotoent\fP(3N).
