mirror of https://github.com/mkerrisk/man-pages
226 lines
8.4 KiB
Plaintext
226 lines
8.4 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "SETSOCKOPT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" setsockopt
|
||
|
.SH NAME
|
||
|
setsockopt \- set the socket options
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <sys/socket.h>
|
||
|
.br
|
||
|
.sp
|
||
|
int setsockopt(int\fP \fIsocket\fP\fB, int\fP \fIlevel\fP\fB, int\fP
|
||
|
\fIoption_name\fP\fB,
|
||
|
.br
|
||
|
\ \ \ \ \ \ const void *\fP\fIoption_value\fP\fB, socklen_t\fP \fIoption_len\fP\fB);
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIsetsockopt\fP() function shall set the option specified by
|
||
|
the \fIoption_name\fP argument, at the protocol level
|
||
|
specified by the \fIlevel\fP argument, to the value pointed to by
|
||
|
the \fIoption_value\fP argument for the socket associated with
|
||
|
the file descriptor specified by the \fIsocket\fP argument.
|
||
|
.LP
|
||
|
The \fIlevel\fP argument specifies the protocol level at which the
|
||
|
option resides. To set options at the socket level, specify
|
||
|
the \fIlevel\fP argument as SOL_SOCKET. To set options at other levels,
|
||
|
supply the appropriate \fIlevel\fP identifier for the
|
||
|
protocol controlling the option. For example, to indicate that an
|
||
|
option is interpreted by the TCP (Transport Control Protocol),
|
||
|
set \fIlevel\fP to IPPROTO_TCP as defined in the \fI<netinet/in.h>\fP
|
||
|
header.
|
||
|
.LP
|
||
|
The \fIoption_name\fP argument specifies a single option to set. The
|
||
|
\fIoption_name\fP argument and any specified options are
|
||
|
passed uninterpreted to the appropriate protocol module for interpretations.
|
||
|
The \fI<sys/socket.h>\fP header defines the socket-level options.
|
||
|
The options are as
|
||
|
follows:
|
||
|
.TP 7
|
||
|
SO_DEBUG
|
||
|
Turns on recording of debugging information. This option enables or
|
||
|
disables debugging in the underlying protocol modules. This
|
||
|
option takes an \fBint\fP value. This is a Boolean option.
|
||
|
.TP 7
|
||
|
SO_BROADCAST
|
||
|
Permits sending of broadcast messages, if this is supported by the
|
||
|
protocol. This option takes an \fBint\fP value. This is a
|
||
|
Boolean option.
|
||
|
.TP 7
|
||
|
SO_REUSEADDR
|
||
|
Specifies that the rules used in validating addresses supplied to
|
||
|
\fIbind\fP() should
|
||
|
allow reuse of local addresses, if this is supported by the protocol.
|
||
|
This option takes an \fBint\fP value. This is a Boolean
|
||
|
option.
|
||
|
.TP 7
|
||
|
SO_KEEPALIVE
|
||
|
Keeps connections active by enabling the periodic transmission of
|
||
|
messages, if this is supported by the protocol. This option
|
||
|
takes an \fBint\fP value.
|
||
|
.LP
|
||
|
If the connected socket fails to respond to these messages, the connection
|
||
|
is broken and threads writing to that socket are
|
||
|
notified with a SIGPIPE signal. This is a Boolean option.
|
||
|
.TP 7
|
||
|
SO_LINGER
|
||
|
Lingers on a \fIclose\fP() if data is present. This option controls
|
||
|
the action taken
|
||
|
when unsent messages queue on a socket and \fIclose\fP() is performed.
|
||
|
If SO_LINGER is set,
|
||
|
the system shall block the process during \fIclose\fP() until it can
|
||
|
transmit the data or
|
||
|
until the time expires. If SO_LINGER is not specified, and \fIclose\fP()
|
||
|
is issued, the
|
||
|
system handles the call in a way that allows the process to continue
|
||
|
as quickly as possible. This option takes a \fBlinger\fP
|
||
|
structure, as defined in the \fI<sys/socket.h>\fP header, to specify
|
||
|
the state
|
||
|
of the option and linger interval.
|
||
|
.TP 7
|
||
|
SO_OOBINLINE
|
||
|
Leaves received out-of-band data (data marked urgent) inline. This
|
||
|
option takes an \fBint\fP value. This is a Boolean
|
||
|
option.
|
||
|
.TP 7
|
||
|
SO_SNDBUF
|
||
|
Sets send buffer size. This option takes an \fBint\fP value.
|
||
|
.TP 7
|
||
|
SO_RCVBUF
|
||
|
Sets receive buffer size. This option takes an \fBint\fP value.
|
||
|
.TP 7
|
||
|
SO_DONTROUTE
|
||
|
Requests that outgoing messages bypass the standard routing facilities.
|
||
|
The destination shall be on a directly-connected
|
||
|
network, and messages are directed to the appropriate network interface
|
||
|
according to the destination address. The effect, if any,
|
||
|
of this option depends on what protocol is in use. This option takes
|
||
|
an \fBint\fP value. This is a Boolean option.
|
||
|
.TP 7
|
||
|
SO_RCVLOWAT
|
||
|
Sets the minimum number of bytes to process for socket input operations.
|
||
|
The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT
|
||
|
is set to a larger value, blocking receive calls normally wait until
|
||
|
they have received the smaller of the low water mark value or
|
||
|
the requested amount. (They may return less than the low water mark
|
||
|
if an error occurs, a signal is caught, or the type of data
|
||
|
next in the receive queue is different from that returned; for example,
|
||
|
out-of-band data.) This option takes an \fBint\fP value.
|
||
|
Note that not all implementations allow this option to be set.
|
||
|
.TP 7
|
||
|
SO_RCVTIMEO
|
||
|
Sets the timeout value that specifies the maximum amount of time an
|
||
|
input function waits until it completes. It accepts a
|
||
|
\fBtimeval\fP structure with the number of seconds and microseconds
|
||
|
specifying the limit on how long to wait for an input
|
||
|
operation to complete. If a receive operation has blocked for this
|
||
|
much time without receiving additional data, it shall return
|
||
|
with a partial count or \fIerrno\fP set to [EAGAIN] or [EWOULDBLOCK]
|
||
|
if no data is received. The default for this option is zero,
|
||
|
which indicates that a receive operation shall not time out. This
|
||
|
option takes a \fBtimeval\fP structure. Note that not all
|
||
|
implementations allow this option to be set.
|
||
|
.TP 7
|
||
|
SO_SNDLOWAT
|
||
|
Sets the minimum number of bytes to process for socket output operations.
|
||
|
Non-blocking output operations shall process no data
|
||
|
if flow control does not allow the smaller of the send low water mark
|
||
|
value or the entire request to be processed. This option
|
||
|
takes an \fBint\fP value. Note that not all implementations allow
|
||
|
this option to be set.
|
||
|
.TP 7
|
||
|
SO_SNDTIMEO
|
||
|
Sets the timeout value specifying the amount of time that an output
|
||
|
function blocks because flow control prevents data from
|
||
|
being sent. If a send operation has blocked for this time, it shall
|
||
|
return with a partial count or with \fIerrno\fP set to
|
||
|
[EAGAIN] or [EWOULDBLOCK] if no data is sent. The default for this
|
||
|
option is zero, which indicates that a send operation shall not
|
||
|
time out. This option stores a \fBtimeval\fP structure. Note that
|
||
|
not all implementations allow this option to be set.
|
||
|
.sp
|
||
|
.LP
|
||
|
For Boolean options, 0 indicates that the option is disabled and 1
|
||
|
indicates that the option is enabled.
|
||
|
.LP
|
||
|
Options at other protocol levels vary in format and name.
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
Upon successful completion, \fIsetsockopt\fP() shall return 0. Otherwise,
|
||
|
-1 shall be returned and \fIerrno\fP set to indicate
|
||
|
the error.
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
The \fIsetsockopt\fP() function shall fail if:
|
||
|
.TP 7
|
||
|
.B EBADF
|
||
|
The \fIsocket\fP argument is not a valid file descriptor.
|
||
|
.TP 7
|
||
|
.B EDOM
|
||
|
The send and receive timeout values are too big to fit into the timeout
|
||
|
fields in the socket structure.
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The specified option is invalid at the specified socket level or the
|
||
|
socket has been shut down.
|
||
|
.TP 7
|
||
|
.B EISCONN
|
||
|
The socket is already connected, and a specified option cannot be
|
||
|
set while the socket is connected.
|
||
|
.TP 7
|
||
|
.B ENOPROTOOPT
|
||
|
.sp
|
||
|
The option is not supported by the protocol.
|
||
|
.TP 7
|
||
|
.B ENOTSOCK
|
||
|
The \fIsocket\fP argument does not refer to a socket.
|
||
|
.sp
|
||
|
.LP
|
||
|
The \fIsetsockopt\fP() function may fail if:
|
||
|
.TP 7
|
||
|
.B ENOMEM
|
||
|
There was insufficient memory available for the operation to complete.
|
||
|
.TP 7
|
||
|
.B ENOBUFS
|
||
|
Insufficient resources are available in the system to complete the
|
||
|
call.
|
||
|
.sp
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
The \fIsetsockopt\fP() function provides an application program with
|
||
|
the means to control socket behavior. An application
|
||
|
program can use \fIsetsockopt\fP() to allocate buffer space, control
|
||
|
timeouts, or permit socket data broadcasts. The \fI<sys/socket.h>\fP
|
||
|
header defines the socket-level options available to
|
||
|
\fIsetsockopt\fP().
|
||
|
.LP
|
||
|
Options may exist at multiple protocol levels. The SO_ options are
|
||
|
always present at the uppermost socket level.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fISockets\fP , \fIbind\fP() , \fIendprotoent\fP() , \fIgetsockopt\fP()
|
||
|
, \fIsocket\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
||
|
\fI<netinet/in.h>\fP, \fI<sys/socket.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|