path: root/usr/src/man/man3socket/getsockopt.3socket

'\" te
.\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH GETSOCKOPT 3SOCKET "Jan 27, 2009"
.SH NAME
getsockopt, setsockopt \- get and set options on sockets
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
#include <sys/types.h>
#include <sys/socket.h>

\fBint\fR \fBgetsockopt\fR(\fBint\fR \fIs\fR, \fBint\fR \fIlevel\fR, \fBint\fR \fIoptname\fR, \fBvoid *\fR\fIoptval\fR,
     \fBint *\fR\fIoptlen\fR);
.fi

.LP
.nf
\fBint\fR \fBsetsockopt\fR(\fBint\fR \fIs\fR, \fBint\fR \fIlevel\fR, \fBint\fR \fIoptname\fR, \fBconst void *\fR\fIoptval\fR,
     \fBint\fR \fIoptlen\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgetsockopt()\fR and \fBsetsockopt()\fR functions manipulate options
associated with a socket. Options may exist at multiple protocol levels; they
are always present at the uppermost "socket" level.
.sp
.LP
The \fIlevel\fR argument specifies the protocol level at which the option
resides. To manipulate options at the socket level, specify the \fIlevel\fR
argument as \fBSOL_SOCKET\fR. To manipulate options at the protocol level,
supply the appropriate protocol number for the protocol controlling the option.
For example, to indicate that an option will be interpreted by the \fBTCP\fR,
set \fIlevel\fR to the protocol number of \fBTCP\fR, as defined in the
\fB<netinet/in.h>\fR header, or as determined by using
\fBgetprotobyname\fR(3SOCKET). Some socket protocol families may also define
additional levels, such as \fBSOL_ROUTE\fR. Only socket-level options are
described here.
.sp
.LP
The parameters \fIoptval\fR and \fIoptlen\fR are used to access option values
for \fBsetsockopt()\fR. For \fBgetsockopt()\fR, they identify a buffer in which
the value(s) for the requested option(s) are to be returned. For
\fBgetsockopt()\fR, \fIoptlen\fR is a value-result parameter, initially
containing the size of the buffer pointed to by \fIoptval\fR, and modified on
return to indicate the actual size of the value returned. Use a 0 \fIoptval\fR
if no option value is to be supplied or returned.
.sp
.LP
The \fIoptname\fR and any specified options are passed uninterpreted to the
appropriate protocol module for interpretation. The include file
<\fBsys/socket.h\fR> contains definitions for the socket-level options
described below. Options at other protocol levels vary in format and name.
.sp
.LP
Most socket-level options take an \fBint\fR for \fIoptval\fR. For
\fBsetsockopt()\fR, the \fIoptval\fR parameter should be non-zero to enable a
boolean option, or zero if the option is to be disabled. \fBSO_LINGER\fR uses a
\fBstruct linger\fR parameter that specifies the desired state of the option
and the linger interval. \fBstruct linger\fR is defined in
<\fBsys/socket.h\fR>. \fBstruct\fR \fBlinger\fR contains the following members:
.sp
.ne 2
.na
\fB\fBl_onoff\fR\fR
.ad
.RS 12n
on = 1/off = 0
.RE

.sp
.ne 2
.na
\fB\fBl_linger\fR\fR
.ad
.RS 12n
linger time, in seconds
.RE

.sp
.LP
The following options are recognized at the socket level. Except as noted, each
may be examined with \fBgetsockopt()\fR and set with \fBsetsockopt()\fR.
.sp
.ne 2
.na
\fB\fBSO_DEBUG\fR\fR
.ad
.RS 19n
enable/disable recording of debugging information
.RE

.sp
.ne 2
.na
\fB\fBSO_REUSEADDR\fR\fR
.ad
.RS 19n
enable/disable local address reuse
.RE

.sp
.ne 2
.na
\fB\fBSO_KEEPALIVE\fR\fR
.ad
.RS 19n
enable/disable keep connections alive
.RE

.sp
.ne 2
.na
\fB\fBSO_DONTROUTE\fR\fR
.ad
.RS 19n
enable/disable routing bypass for outgoing messages
.RE

.sp
.ne 2
.na
\fB\fBSO_LINGER\fR\fR
.ad
.RS 19n
linger on close if data is present
.RE

.sp
.ne 2
.na
\fB\fBSO_BROADCAST\fR\fR
.ad
.RS 19n
enable/disable permission to transmit broadcast messages
.RE

.sp
.ne 2
.na
\fB\fBSO_OOBINLINE\fR\fR
.ad
.RS 19n
enable/disable reception of out-of-band data in band
.RE

.sp
.ne 2
.na
\fB\fBSO_SNDBUF\fR\fR
.ad
.RS 19n
set buffer size for output
.RE

.sp
.ne 2
.na
\fB\fBSO_RCVBUF\fR\fR
.ad
.RS 19n
set buffer size for input
.RE

.sp
.ne 2
.na
\fB\fBSO_DGRAM_ERRIND\fR\fR
.ad
.RS 19n
application wants delayed error
.RE

.sp
.ne 2
.na
\fB\fBSO_TIMESTAMP\fR\fR
.ad
.RS 19n
enable/disable reception of timestamp with datagrams
.RE

.sp
.ne 2
.na
\fB\fBSO_EXCLBIND\fR\fR
.ad
.RS 19n
enable/disable exclusive binding of the socket
.RE

.sp
.ne 2
.na
\fB\fBSO_TYPE\fR\fR
.ad
.RS 19n
get the type of the socket (get only)
.RE

.sp
.ne 2
.na
\fB\fBSO_ERROR\fR\fR
.ad
.RS 19n
get and clear error on the socket (get only)
.RE

.sp
.ne 2
.na
\fB\fBSO_MAC_EXEMPT\fR\fR
.ad
.RS 19n
get or set mandatory access control on the socket. This option is available
only when the system is configured with Trusted Extensions.
.RE

.sp
.ne 2
.na
\fB\fBSO_ALLZONES\fR\fR
.ad
.RS 19n
bypass zone boundaries (privileged).
.RE

.sp
.ne 2
.na
\fB\fBSO_DOMAIN\fR\fR
.ad
.RS 19n
get the domain used in the socket (get only)
.RE

.sp
.ne 2
.na
\fB\fBSO_PROTOTYPE\fR\fR
.ad
.RS 19n
for socket in domains \fBPF_INET\fR and \fBPF_INET6\fR, get the underlying
protocol number used in the socket. For socket in domain \fBPF_ROUTE\fR, get
the address family used in the socket.
.RE

.sp
.LP
The \fBSO_DEBUG\fR option enables debugging in the underlying protocol modules.
The \fBSO_REUSEADDR\fR option indicates that the rules used in validating
addresses supplied in a \fBbind\fR(3SOCKET) call should allow reuse of local
addresses. The \fBSO_KEEPALIVE\fR option 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 threads using the
socket are notified using a \fBSIGPIPE\fR signal. The \fBSO_DONTROUTE\fR option
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.
.sp
.LP
The \fBSO_LINGER\fR option controls the action taken when unsent messages are
queued on a socket and a \fBclose\fR(2) is performed. If the socket promises
reliable delivery of data and \fBSO_LINGER\fR is set, the system will block the
thread on the \fBclose()\fR 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 \fBsetsockopt()\fR call when
\fBSO_LINGER\fR is requested). If \fBSO_LINGER\fR is disabled and a
\fBclose()\fR is issued, the system will process the \fBclose()\fR in a manner
that allows the thread to continue as quickly as possible.
.sp
.LP
The option \fBSO_BROADCAST\fR requests permission to send broadcast datagrams
on the socket. With protocols that support out-of-band data, the
\fBSO_OOBINLINE\fR option requests that out-of-band data be placed in the
normal data input queue as received; it will then be accessible with
\fBrecv()\fR or \fBread()\fR calls without the \fBMSG_OOB\fR flag.
.sp
.LP
The \fBSO_SNDBUF\fR and \fBSO_RCVBUF\fR options 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 maximum buffer size for \fBUDP\fR is determined
by the value of the \fBndd\fR variable \fBudp_max_buf\fR. The maximum buffer
size for \fBTCP\fR is determined the value of the \fBndd\fR variable
\fBtcp_max_buf\fR. Use the \fBndd\fR(1M) utility to determine the current
default values. See the \fISolaris Tunable Parameters Reference Manual\fR for
information on setting the values of \fBudp_max_buf\fR and \fBtcp_max_buf\fR.
At present, lowering \fBSO_RCVBUF\fR on a TCP connection after it has been
established has no effect.
.sp
.LP
By default, delayed errors (such as \fBICMP\fR port unreachable packets) are
returned only for connected datagram sockets. The \fBSO_DGRAM_ERRIND\fR option
makes it possible to receive errors for datagram sockets that are not
connected. When this option is set, certain delayed errors received after
completion of a \fBsendto()\fR or \fBsendmsg()\fR operation will cause a
subsequent \fBsendto()\fR or \fBsendmsg()\fR operation using the same
destination address (\fIto\fR parameter) to fail with the appropriate error.
See \fBsend\fR(3SOCKET).
.sp
.LP
If the \fBSO_TIMESTAMP\fR option is enabled on a \fBSO_DGRAM\fR or a
\fBSO_RAW\fR socket, the \fBrecvmsg\fR(3XNET) call will return a timestamp in
the native data format, corresponding to when the datagram was received.
.sp
.LP
The \fBSO_EXCLBIND\fR option is used to enable or disable the exclusive binding
of a socket. It overrides the use of the \fBSO_REUSEADDR\fR option to reuse an
address on \fBbind\fR(3SOCKET). The actual semantics of the \fBSO_EXCLBIND\fR
option depend on the underlying protocol. See \fBtcp\fR(7P) or \fBudp\fR(7P)
for more information.
.sp
.LP
The \fBSO_TYPE\fR and \fBSO_ERROR\fR options are used only with
\fBgetsockopt()\fR. The \fBSO_TYPE\fR option returns the type of the socket,
for example, \fBSOCK_STREAM\fR. It is useful for servers that inherit sockets
on startup. The \fBSO_ERROR\fR option 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.
.sp
.LP
The \fBSO_MAC_EXEMPT\fR option is used to toggle socket behavior with unlabeled
peers. A socket that has this option enabled can communicate with an unlabeled
peer if it is in the global zone or has a label that dominates the default
label of the peer. Otherwise, the socket must have a label that is equal to the
default label of the unlabeled peer. Calling \fBsetsockopt()\fR with this
option returns an \fBEACCES\fR error if the process lacks the
\fBNET_MAC_AWARE\fR privilege or if the socket is bound. The
\fBSO_MAC_EXEMPT\fR option is available only when the system is configured with
Trusted Extensions.
.sp
.LP
The \fBSO_ALLZONES\fR option can be used to bypass zone boundaries between
shared-IP zones. Normally, the system prevents a socket from being bound to an
address that is not assigned to the current zone. It also prevents a socket
that is bound to a wildcard address from receiving traffic for other zones.
However, some daemons which run in the global zone might need to send and
receive traffic using addresses that belong to other shared-IP zones. If set
before a socket is bound, \fBSO_ALLZONES\fR causes the socket to ignore zone
boundaries between shared-IP zones and permits the socket to be bound to any
address assigned to the shared-IP zones. If the socket is bound to a wildcard
address, it receives traffic intended for all shared-IP zones and behaves as if
an equivalent socket were bound in each active shared-IP zone. Applications
that use the \fBSO_ALLZONES\fR option to initiate connections or send datagram
traffic should specify the source address for outbound traffic by binding to a
specific address. There is no effect from setting this option in an
exclusive-IP zone. Setting this option requires the \fBsys_net_config\fR
privilege. See \fBzones\fR(5).
.SH RETURN VALUES
.sp
.LP
If successful, \fBgetsockopt()\fR and \fBsetsockopt()\fR return \fB0\fR.
Otherwise, the functions return \fB\(mi1\fR and set \fBerrno\fR to indicate the
error.
.SH ERRORS
.sp
.LP
The \fBgetsockopt()\fR and \fBsetsockopt()\fR calls succeed unless:
.sp
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 17n
The argument \fIs\fR is not a valid file descriptor.
.RE

.sp
.ne 2
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 17n
There was insufficient memory available for the operation to complete.
.RE

.sp
.ne 2
.na
\fB\fBENOPROTOOPT\fR\fR
.ad
.RS 17n
The option is unknown at the level indicated.
.RE

.sp
.ne 2
.na
\fB\fBENOSR\fR\fR
.ad
.RS 17n
There were insufficient STREAMS resources available for the operation to
complete.
.RE

.sp
.ne 2
.na
\fB\fBENOTSOCK\fR\fR
.ad
.RS 17n
The argument \fIs\fR is not a socket.
.RE

.sp
.ne 2
.na
\fB\fBENOBUFS\fR\fR
.ad
.RS 17n
\fBSO_SNDBUF\fR or \fBSO_RCVBUF\fR exceeds a system limit.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 17n
Invalid length for a given socket option.
.RE

.sp
.ne 2
.na
\fB\fBEHOSTUNREACH\fR\fR
.ad
.RS 17n
Invalid address for \fBIP_MULTICAST_IF\fR.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 17n
Not a multicast address for \fBIP_ADD_MEMBERSHIP\fR and
\fBIP_DROP_MEMBERSHIP\fR.
.RE

.sp
.ne 2
.na
\fB\fBEADDRNOTAVAIL\fR\fR
.ad
.RS 17n
Bad interface address for \fBIP_ADD_MEMBERSHIP\fR and \fBIP_DROP_MEMBERSHIP\fR.
.RE

.sp
.ne 2
.na
\fB\fBEADDRINUSE\fR\fR
.ad
.RS 17n
Address already joined for \fBIP_ADD_MEMBERSHIP\fR.
.RE

.sp
.ne 2
.na
\fB\fBENOENT\fR\fR
.ad
.RS 17n
Address not joined for \fBIP_DROP_MEMBERSHIP\fR.
.RE

.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 17n
No permissions.
.RE

.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 17n
Permission denied.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 17n
The specified option is invalid at the specified socket level, or the socket
has been shut down.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBndd\fR(1M), \fBclose\fR(2), \fBioctl\fR(2), \fBread\fR(2),
\fBbind\fR(3SOCKET), \fBgetprotobyname\fR(3SOCKET), \fBrecv\fR(3SOCKET),
\fBrecvmsg\fR(3XNET), \fBsend\fR(3SOCKET), \fBsocket\fR(3SOCKET),
\fBsocket.h\fR(3HEAD), \fBattributes\fR(5), \fBzones\fR(5), \fBtcp\fR(7P),
\fBudp\fR(7P)
.sp
.LP
\fISolaris Tunable Parameters Reference Manual\fR