setsockopt(2)setsockopt(2)NAMEsetsockopt - Set socket options
SYNOPSIS
#include <sys/socket.h>
int setsockopt(
int socket,
int level,
int option_name,
const void *option_value,
socklen_t option_len );
[XNS4.0] The definition of the setsockopt() function in XNS4.0uses a
size_t data type instead of a socklen_t data type as specified in
XNS5.0 (the previous definition).
[Tru64 UNIX] The following definition of the setsockopt() function
does not conform to current standards and is supported only for back‐
ward compatibility (see standards(5)): #include <sys/socket.h>
int setsockopt
int socket,
int level,
int option_name,
char *option_value,
int option_len );
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
setsockopt(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the file descriptor for the socket. Specifies the protocol
level at which the option resides. To set options at the socket level,
specify the level parameter as SOL_SOCKET. To set options at other lev‐
els, supply the appropriate protocol number for the protocol control‐
ling the option. For example, to indicate that an option will be inter‐
preted by the TCP protocol, set level to the protocol number of TCP, as
defined in the netinet/in.h file or as determined by using the getpro‐
tobyname() function. Specifies the option to set. The option_name
parameter and any specified options are passed uninterpreted to the
appropriate protocol module for interpretation. The sys/socket.h
header file defines the socket level options. The socket level options
can be enabled or disabled. The options are: Permits sending of broad‐
cast messages. This option takes an int value. [Tru64 UNIX] In a
cluster, specifies that if the local address has not already been set
through a call to bind(), the socket will use the default cluster alias
as its source address. [Tru64 UNIX] In a cluster, specifies that the
socket can only receive packets addressed to this cluster member.
Attempts to bind the socket to a cluster alias address will fail. A
bind to an dynamic port (greater than or equal to IPPORT_RESERVED and
less than IPPORT_USERRESERVED) will not result in that port being dedi‐
cated (or "locked") for use by a single node in the cluster. A bind to
a privileged reserved port with a wildcard address (INADDR_ANY or
in6addr_any) will not result in that port being locked. The source
address for outgoing UDP sends or TCP connection requests will be a
local host address (never a cluster alias address). The
SO_CLUA_IN_NOLOCAL and SO_CLUA_IN_NOALIAS options are mutually exclu‐
sive. [Tru64 UNIX] In a cluster, specifies that the socket must
receive packets addressed to a cluster alias and will drop any packets
that are not addressed to a cluster alias. The SO_CLUA_IN_NOLOCAL and
SO_CLUA_IN_NOALIAS options are mutually exclusive. Turns on recording
of debugging information. This option enables or disables debugging in
the underlying protocol modules. This option takes an int value.
Indicates that outgoing messages should bypass the standard routing
facilities. Instead, they are directed to the appropriate network
interface according to the network portion of the destination address.
Keeps connections active. 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. Lingers on a close() func‐
tion if data is present. This option controls the action taken when
unsent messages queue on a socket and a close() function is performed.
If SO_LINGER is set, the system blocks the process during the close()
function until it can transmit the data or until the time expires. If
SO_LINGER is not specified and a close() function is issued, the system
handles the call in a way that allows the process to continue as
quickly as possible. This option takes a struct linger value, defined
in the sys/socket.h header file, to specify the state of the option and
linger interval. Leaves received out-of-band data (data marked urgent)
in line. This option takes an int value. Sets receive buffer size.
This option takes an int value. Reports the minimum number of bytes
(low-water mark) for socket receive operations. The default is 1. If
the value is set to a larger value, blocking receive calls wait until
they receive either the low water mark value or the requested value
(whichever is smaller). The calls might return less than the water
mark if an error occurs, a signal is received, or type of data in the
receive queue is different than that returned. This option takes an
int value. Sets receive time out. This option takes a struct timeval
value, defined in the sys/time.h header file, to specify the amount of
time towait for a receive operation to complete. If a receive operation
has blocke for the specified amount of time without receiving addi‐
tional data, it returns with a partial error count or errno set to
[EAGAIN] or [EWOULDBLOCK]. The default is 0 (zero), which indicates
that a receive operation will not time out. [Tru64 UNIX] In a clus‐
ter, an attempt to bind the socket to a port in the reserved range
(512-1024) will fail if the port is marked static, either by a static
entry for the port in /etc/clua_services or through a call to clua_reg‐
isterservice() with the CLUASRV_STATIC option. The call to bind() will
return EADDRINUSE. Specifies that the rules used in validating
addresses supplied by a bind() function should allow reuse of local
addresses. This option takes an int value. [Tru64 UNIX] In a cluster,
specifies that the socket can reuse a locked cluster alias port. When
this option is set, a bind() is distributed clusterwide. A distributed
application can use this side-effect to determine whether or not a port
is in use. [Tru64 UNIX] Allows more than one process to receive UDP
datagrams destined for the same port. The bind system call binding a
process to that port must be preceded by a setsockopt system call spec‐
ifying this option. Sets send buffer size. This option takes an int
value. Sets the minimum number of bytes (low-water mark) for socket
transmit operations. Non-blocking transmit operations process no data
if flow control does not allow either the send low water mark value or
the entire request (whichever is smaller) to be processed. This option
takes an int value. Sets send time out. This option takes a struct
timeval value, defined in the sys/time.h header file, to specify the
amount of time a transmit function blocks when flow control prevents
the transmission of data. If a transmit operation blocks for this
amount of time without transmitting data, it returns with a partial
error count or errno set to [EAGAIN] or [EWOULDBLOCK]. The default is
0 (zero), which indicates that a transmit operation will not time out.
[Tru64 UNIX] Valid only for routing sockets. Determines if a sending
socket receives a copy of its own message.
[Tru64 UNIX] Options at other protocol levels vary in format
and name. See the tcp(7) and ip(7) reference pages for more
information on option names relevant for TCP and IP options
respectively.
Note
[Tru64 UNIX] The maximum values for socket level options like
SO_SENDBUF, SO_RCVBUF, SO_SNDLOWAT, and SO_RCVLOWAT are governed
by the protocol limits, as well as its implementation. Use the
getsockopt(2) routine to verify the values for these options
after the socket connection has been established. To enable a
Boolean option or integer value, set the option_value parameter
to a nonzero value. To disable an option, set the option_value
parameter to 0 (zero). The option_len parameter contains the
size of the buffer pointed to by the option_value parameter.
DESCRIPTION
The setsockopt() function sets options associated with a socket.
Options may exist at multiple protocol levels. The SO_ options are
always present at the uppermost socket level.
The setsockopt() function provides an application program with the
means to control a socket communication. An application program can use
the setsockopt() function to enable debugging at the protocol level,
allocate buffer space, control timeouts, or permit socket data broad‐
casts. The sys/socket.h file defines all the options available to the
setsockopt() function.
When setting socket options, specify the protocol level at which the
option resides and the name of the option.
Use the option_value and option_len parameters to access option values
for the setsockopt() function. These parameters identify a buffer in
which the value for the requested option or options is returned.
RETURN VALUES
Upon successful completion, a value of 0 (zero) is returned. Otherwise,
a value of -1 is returned and errno is set to indicate the error.
ERRORS
If the setsockopt() function fails, errno may be set to one of the fol‐
lowing values: [POSIX] The calling process does not have appropriate
permissions. The socket parameter is not valid. The send and receive
timeout values are too large to fit in the timeout fields of the socket
structure. The option_len parameter is not valid. The socket is
already connected; the specified option cannot be set when the socket
is in the connected state. The option_value parameter is not in a
readable part of the user address space. Insufficient resources are
available in the system to complete the call. The system did not have
sufficient memory to fulfill the request. The option is unknown. The
available STREAMS resources were insufficient for the operation to com‐
plete. The socket parameter refers to a file, not a socket.
SEE ALSO
Functions: bind(2), endprotoent(3), getsockopt(2), getprotobynumber(3),
getprotoent(3), setprotoent(3), socket(2).
Network Information: ip(7), tcp(7).
Standards: standards(5).
Network Programmer's Guide
setsockopt(2)