Sockets Library Functions getsockopt(3SOCKET)
NAME
getsockopt, setsockopt - get and set options on sockets
SYNOPSIS
cc [ flag ... ] file ... -lsocket -lnsl [ library ... ]
#include
#include
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
The getsockopt() and setsockopt() functions manipulate
options associated with a socket. Options may exist at mul-
tiple protocol levels; they are always present at the upper-
most "socket" level.
The level argument specifies the protocol level at which the
option resides. To manipulate options at the socket level,
specify the level argument as SOLSOCKET. To manipulate
options at the protocol level, supply the appropriate proto-
col number for the protocol controlling the option. For
example, to indicate that an option will be interpreted by
the TCP, set level to the protocol number of TCP, as defined
in the header, or as determined by using
getprotobyname(3SOCKET). Some socket protocol families may
also define additional levels, such as SOLROUTE. Only
socket-level options are described here.
The parameters optval and optlen are used to access option
values for setsockopt(). For getsockopt(), they identify a
buffer in which the value(s) for the requested option(s) are
to 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. Use a 0 optval if no
option value is to be supplied or returned.
The optname and any specified options are passed uninter-
preted to the appropriate protocol module for interpreta-
tion. The include file contains definitions
for the socket-level options described below. Options at
other protocol levels vary in format and name.
SunOS 5.11 Last change: 27 Jan 2009 1
Sockets Library Functions getsockopt(3SOCKET)
Most socket-level options take an int for optval. For set-
sockopt(), the optval parameter should be non-zero to enable
a boolean option, or zero if the option is to be disabled.
SOLINGER uses a struct linger parameter that specifies the
desired state of the option and the linger interval. struct
linger is defined in . struct linger contains
the following members:
lonoff on = 1/off = 0
llinger linger time, in seconds
The following options are recognized at the socket level.
Except as noted, each may be examined with getsockopt() and
set with setsockopt().
SODEBUG enable/disable recording of debugging
information
SOREUSEADR enable/disable local address reuse
SOKEPALIVE enable/disable keep connections alive
SODONTROUTE enable/disable routing bypass for outgo-
ing messages
SOLINGER linger on close if data is present
SOBROADCAST enable/disable permission to transmit
broadcast messages
SOBINLINE enable/disable reception of out-of-band
data in band
SOSNDBUF set buffer size for output
SORCVBUF set buffer size for input
SODGRAMERIND application wants delayed error
SunOS 5.11 Last change: 27 Jan 2009 2
Sockets Library Functions getsockopt(3SOCKET)
SOTIMESTAMP enable/disable reception of timestamp
with datagrams
SOEXCLBIND enable/disable exclusive binding of the
socket
SOTYPE get the type of the socket (get only)
SOEROR get and clear error on the socket (get
only)
SOMACEXEMPT get or set mandatory access control on
the socket. This option is available only
when the system is configured with
Trusted Extensions.
SOALZONES bypass zone boundaries (privileged).
SODOMAIN get the domain used in the socket (get
only)
SOPROTOTYPE for socket in domains PFINET and
PFINET6, get the underlying protocol
number used in the socket. For socket in
domain PFROUTE, get the address family
used in the socket.
The SODEBUG option enables debugging in the underlying pro-
tocol modules. The SOREUSEADR option indicates that the
rules used in validating addresses supplied in a
bind(3SOCKET) call should allow reuse of local addresses.
The SOKEPALIVE 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
SIGPIPE signal. The SODONTROUTE option indicates that out-
going messages should bypass the standard routing facili-
ties. Instead, messages are directed to the appropriate net-
work interface according to the network portion of the des-
tination address.
SunOS 5.11 Last change: 27 Jan 2009 3
Sockets Library Functions getsockopt(3SOCKET)
The SOLINGER option controls the action taken when unsent
messages are queued on a socket and a close(2) is performed.
If the socket promises reliable delivery of data and
SOLINGER is set, the system will block the thread 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() call when SOLINGER is requested). If
SOLINGER is disabled and a close() is issued, the system
will process the close() in a manner that allows the thread
to continue as quickly as possible.
The option SOBROADCAST requests permission to send broad-
cast datagrams on the socket. With protocols that support
out-of-band data, the SOBINLINE 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()
calls without the MSGOB flag.
The SOSNDBUF and SORCVBUF 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 incom-
ing data. The maximum buffer size for UDP is determined by
the value of the ndd variable udpmaxbuf. The maximum
buffer size for TCP is determined the value of the ndd vari-
able tcpmaxbuf. Use the ndd(1M) utility to determine the
current default values. See the Solaris Tunable Parameters
Reference Manual for information on setting the values of
udpmaxbuf and tcpmaxbuf. At present, lowering SORCVBUF
on a TCP connection after it has been established has no
effect.
By default, delayed errors (such as ICMP port unreachable
packets) are returned only for connected datagram sockets.
The SODGRAMERIND 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 sendto() or sendmsg() operation will cause a
subsequent sendto() or sendmsg() operation using the same
destination address (to parameter) to fail with the
appropriate error. See send(3SOCKET).
If the SOTIMESTAMP option is enabled on a SODGRAM or a
SORAW socket, the recvmsg(3XNET) call will return a times-
tamp in the native data format, corresponding to when the
datagram was received.
SunOS 5.11 Last change: 27 Jan 2009 4
Sockets Library Functions getsockopt(3SOCKET)
The SOEXCLBIND option is used to enable or disable the
exclusive binding of a socket. It overrides the use of the
SOREUSEADR option to reuse an address on bind(3SOCKET).
The actual semantics of the SOEXCLBIND option depend on the
underlying protocol. See tcp(7P) or udp(7P) for more infor-
mation.
The SOTYPE and SOEROR options are used only with get-
sockopt(). The SOTYPE option returns the type of the
socket, for example, SOCKSTREAM. It is useful for servers
that inherit sockets on startup. The SOEROR 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.
The SOMACEXEMPT 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 glo-
bal 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
setsockopt() with this option returns an EACES error if the
process lacks the NETMACAWARE privilege or if the socket
is bound. The SOMACEXEMPT option is available only when
the system is configured with Trusted Extensions.
The SOALZONES 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, SOALZONES causes the socket to ignore zone boun-
daries 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 SOALZONES 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
sysnetconfig privilege. See zones(5).
RETURN VALUES
SunOS 5.11 Last change: 27 Jan 2009 5
Sockets Library Functions getsockopt(3SOCKET)
If successful, getsockopt() and setsockopt() return 0. Oth-
erwise, the functions return -1 and set errno to indicate
the error.
ERORS
The getsockopt() and setsockopt() calls succeed unless:
EBADF The argument s is not a valid file descrip-
tor.
ENOMEM There was insufficient memory available for
the operation to complete.
ENOPROTOPT The option is unknown at the level indi-
cated.
ENOSR There were insufficient STREAMS resources
available for the operation to complete.
ENOTSOCK The argument s is not a socket.
ENOBUFS SOSNDBUF or SORCVBUF exceeds a system
limit.
EINVAL Invalid length for IPOPTIONS.
EHOSTUNREACH Invalid address for IPMULTICASTIF.
EINVAL Not a multicast address for
IPADMEMBERSHIP and IPDROPMEMBERSHIP.
EADRNOTAVAIL Bad interface address for IPADMEMBERSHIP
and IPDROPMEMBERSHIP.
EADRINUSE Address already joined for
IPADMEMBERSHIP.
ENOENT Address not joined for IPDROPMEMBERSHIP.
SunOS 5.11 Last change: 27 Jan 2009 6
Sockets Library Functions getsockopt(3SOCKET)
EPERM No permissions.
EACES Permission denied.
EINVAL The specified option is invalid at the
specified socket level, or the socket has
been shut down.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level Safe
SEE ALSO
ndd(1M), close(2), ioctl(2), read(2), bind(3SOCKET),
getprotobyname(3SOCKET), recv(3SOCKET), recvmsg(3XNET),
send(3SOCKET), socket(3SOCKET), socket.h(3HEAD), attri-
butes(5), zones(5), tcp(7P), udp(7P)
Solaris Tunable Parameters Reference Manual
SunOS 5.11 Last change: 27 Jan 2009 7
|
