 |
Index for
Section 2 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
setsockopt(2)
NAME
setsockopt - 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 backward
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 standards
as follows:
setsockopt(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
socket
Specifies the file descriptor for the socket.
level
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 levels, 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, as defined in the netinet/in.h file or as
determined by using the getprotobyname() function.
option_name
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:
SO_BROADCAST
Permits sending of broadcast messages. This option takes an int
value.
SO_CLUA_DEFAULT_SRC
[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.
SO_CLUA_IN_NOALIAS
[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
dedicated (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 exclusive.
SO_CLUA_IN_NOLOCAL
[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.
SO_DEBUG
Turns on recording of debugging information. This option enables
or disables debugging in the underlying protocol modules. This
option takes an int value.
SO_DONTROUTE
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.
SO_KEEPALIVE
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.
SO_LINGER
Lingers on a close() function 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.
SO_OOBINLINE
Leaves received out-of-band data (data marked urgent) in line. This
option takes an int value.
SO_RCVBUF
Sets receive buffer size. This option takes an int value.
SO_RCVLOWAT
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.
SO_RCVTIMEO
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 additional 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.
SO_RESVPORT
[Tru64 UNIX] In a cluster, 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_registerservice() with
the CLUASRV_STATIC option. The call to bind() will return
EADDRINUSE.
SO_REUSEADDR
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.
SO_REUSEALIASPORT
[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.
SO_REUSEPORT
[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
specifying this option.
SO_SNDBUF
Sets send buffer size. This option takes an int value.
SO_SNDLOWAT
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.
SO_SNDTIMEO
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.
SO_USELOOPBACK
[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.
option_value
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).
option_len
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 broadcasts. 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
following values:
[EACCES]
[POSIX] The calling process does not have appropriate permissions.
[EBADF]
The socket parameter is not valid.
[EDOM]
The send and receive timeout values are too large to fit in the timeout
fields of the socket structure.
[EINVAL]
The option_len parameter is not valid.
[EISCONN]
The socket is already connected; the specified option cannot be set
when the socket is in the connected state.
[EFAULT]
The option_value parameter is not in a readable part of the user
address space.
[ENOBUFS]
Insufficient resources are available in the system to complete the
call.
[ENOMEM]
The system did not have sufficient memory to fulfill the request.
[ENOPROTOOPT]
The option is unknown.
[ENOSR]
The available STREAMS resources were insufficient for the operation to
complete.
[ENOTSOCK]
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
|
Index for
Section 2 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|