259 lines
11 KiB
HTML
259 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>setsockopt</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
|
|
<basefont size="3"> <a name="setsockopt"></a> <a name="tag_03_668"></a><!-- setsockopt -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_668_01"></a>NAME</h4>
|
|
|
|
<blockquote>setsockopt - set the socket options</blockquote>
|
|
|
|
<h4><a name="tag_03_668_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/sys/socket.h.html">sys/socket.h</a>><br>
|
|
<br>
|
|
int setsockopt(int</tt> <i>socket</i><tt>, int</tt> <i>level</i><tt>, int</tt> <i>option_name</i><tt>,<br>
|
|
const void *</tt><i>option_value</i><tt>, socklen_t</tt> <i>option_len</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_668_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>setsockopt</i>() function shall set the option specified by the <i>option_name</i> argument, at the protocol level
|
|
specified by the <i>level</i> argument, to the value pointed to by the <i>option_value</i> argument for the socket associated with
|
|
the file descriptor specified by the <i>socket</i> argument.</p>
|
|
|
|
<p>The <i>level</i> argument specifies the protocol level at which the option resides. To set options at the socket level, specify
|
|
the <i>level</i> argument as SOL_SOCKET. To set options at other levels, supply the appropriate <i>level</i> identifier for the
|
|
protocol controlling the option. For example, to indicate that an option is interpreted by the TCP (Transport Control Protocol),
|
|
set <i>level</i> to IPPROTO_TCP as defined in the <a href="../basedefs/netinet/in.h.html"><i><netinet/in.h></i></a>
|
|
header.</p>
|
|
|
|
<p>The <i>option_name</i> argument specifies a single option to set. The <i>option_name</i> argument and any specified options are
|
|
passed uninterpreted to the appropriate protocol module for interpretations. The <a href=
|
|
"../basedefs/sys/socket.h.html"><i><sys/socket.h></i></a> header defines the socket-level options. The options are as
|
|
follows:</p>
|
|
|
|
<dl compact>
|
|
<dt>SO_DEBUG</dt>
|
|
|
|
<dd>Turns on recording of debugging information. This option enables or disables debugging in the underlying protocol modules. This
|
|
option takes an <b>int</b> value. This is a Boolean option.</dd>
|
|
|
|
<dt>SO_BROADCAST</dt>
|
|
|
|
<dd>Permits sending of broadcast messages, if this is supported by the protocol. This option takes an <b>int</b> value. This is a
|
|
Boolean option.</dd>
|
|
|
|
<dt>SO_REUSEADDR</dt>
|
|
|
|
<dd>Specifies that the rules used in validating addresses supplied to <a href="../functions/bind.html"><i>bind</i>()</a> should
|
|
allow reuse of local addresses, if this is supported by the protocol. This option takes an <b>int</b> value. This is a Boolean
|
|
option.</dd>
|
|
|
|
<dt>SO_KEEPALIVE</dt>
|
|
|
|
<dd>Keeps connections active by enabling the periodic transmission of messages, if this is supported by the protocol. This option
|
|
takes an <b>int</b> value.
|
|
|
|
<p>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.</p>
|
|
</dd>
|
|
|
|
<dt>SO_LINGER</dt>
|
|
|
|
<dd>Lingers on a <a href="../functions/close.html"><i>close</i>()</a> if data is present. This option controls the action taken
|
|
when unsent messages queue on a socket and <a href="../functions/close.html"><i>close</i>()</a> is performed. If SO_LINGER is set,
|
|
the system shall block the process during <a href="../functions/close.html"><i>close</i>()</a> until it can transmit the data or
|
|
until the time expires. If SO_LINGER is not specified, and <a href="../functions/close.html"><i>close</i>()</a> is issued, the
|
|
system handles the call in a way that allows the process to continue as quickly as possible. This option takes a <b>linger</b>
|
|
structure, as defined in the <a href="../basedefs/sys/socket.h.html"><i><sys/socket.h></i></a> header, to specify the state
|
|
of the option and linger interval.</dd>
|
|
|
|
<dt>SO_OOBINLINE</dt>
|
|
|
|
<dd>Leaves received out-of-band data (data marked urgent) inline. This option takes an <b>int</b> value. This is a Boolean
|
|
option.</dd>
|
|
|
|
<dt>SO_SNDBUF</dt>
|
|
|
|
<dd>Sets send buffer size. This option takes an <b>int</b> value.</dd>
|
|
|
|
<dt>SO_RCVBUF</dt>
|
|
|
|
<dd>Sets receive buffer size. This option takes an <b>int</b> value.</dd>
|
|
|
|
<dt>SO_DONTROUTE</dt>
|
|
|
|
<dd>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 <b>int</b> value. This is a Boolean option.</dd>
|
|
|
|
<dt>SO_RCVLOWAT</dt>
|
|
|
|
<dd>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 <b>int</b> value.
|
|
Note that not all implementations allow this option to be set.</dd>
|
|
|
|
<dt>SO_RCVTIMEO</dt>
|
|
|
|
<dd>Sets the timeout value that specifies the maximum amount of time an input function waits until it completes. It accepts a
|
|
<b>timeval</b> 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 <i>errno</i> 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 <b>timeval</b> structure. Note that not all
|
|
implementations allow this option to be set.</dd>
|
|
|
|
<dt>SO_SNDLOWAT</dt>
|
|
|
|
<dd>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 <b>int</b> value. Note that not all implementations allow this option to be set.</dd>
|
|
|
|
<dt>SO_SNDTIMEO</dt>
|
|
|
|
<dd>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 <i>errno</i> 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 <b>timeval</b> structure. Note that not all implementations allow this option to be set.</dd>
|
|
</dl>
|
|
|
|
<p>For Boolean options, 0 indicates that the option is disabled and 1 indicates that the option is enabled.</p>
|
|
|
|
<p>Options at other protocol levels vary in format and name.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_668_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, <i>setsockopt</i>() shall return 0. Otherwise, -1 shall be returned and <i>errno</i> set to indicate
|
|
the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_668_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>setsockopt</i>() function shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EBADF]</dt>
|
|
|
|
<dd>The <i>socket</i> argument is not a valid file descriptor.</dd>
|
|
|
|
<dt>[EDOM]</dt>
|
|
|
|
<dd>The send and receive timeout values are too big to fit into the timeout fields in the socket structure.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The specified option is invalid at the specified socket level or the socket has been shut down.</dd>
|
|
|
|
<dt>[EISCONN]</dt>
|
|
|
|
<dd>The socket is already connected, and a specified option cannot be set while the socket is connected.</dd>
|
|
|
|
<dt>[ENOPROTOOPT]</dt>
|
|
|
|
<dd><br>
|
|
The option is not supported by the protocol.</dd>
|
|
|
|
<dt>[ENOTSOCK]</dt>
|
|
|
|
<dd>The <i>socket</i> argument does not refer to a socket.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>setsockopt</i>() function may fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[ENOMEM]</dt>
|
|
|
|
<dd>There was insufficient memory available for the operation to complete.</dd>
|
|
|
|
<dt>[ENOBUFS]</dt>
|
|
|
|
<dd>Insufficient resources are available in the system to complete the call.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_668_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_668_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>setsockopt</i>() function provides an application program with the means to control socket behavior. An application
|
|
program can use <i>setsockopt</i>() to allocate buffer space, control timeouts, or permit socket data broadcasts. The <a href=
|
|
"../basedefs/sys/socket.h.html"><i><sys/socket.h></i></a> header defines the socket-level options available to
|
|
<i>setsockopt</i>().</p>
|
|
|
|
<p>Options may exist at multiple protocol levels. The SO_ options are always present at the uppermost socket level.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_668_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_668_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_668_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="xsh_chap02_10.html#tag_02_10"><i>Sockets</i></a> , <a href="bind.html"><i>bind</i>()</a> , <a href=
|
|
"endprotoent.html"><i>endprotoent</i>()</a> , <a href="getsockopt.html"><i>getsockopt</i>()</a> , <a href=
|
|
"socket.html"><i>socket</i>()</a> , the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/netinet/in.h.html"><i><netinet/in.h></i></a>, <a href=
|
|
"../basedefs/sys/socket.h.html"><i><sys/socket.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_668_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 6. Derived from the XNS, Issue 5.2 specification.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|