friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
0332907f0f
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/ssocko.htm

1146 lines
38 KiB
HTML
Raw Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>setsockopt()--Set Socket Options</title>
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Begin Header Records ========================================== -->
<!-- Unix8 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Edited by Kersten Feb 02 -->
<!-- 040405 MULLENBA Added IPV6_DONTFRAG and misc otherchanges -->
<!-- 041207 MULLENBA Added SO_ACCEPTECONNABORTED -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>setsockopt()--Set Socket Options</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;BSD 4.3 Syntax<br>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;sys/socket.h&gt;
int setsockopt(int <em>socket_descriptor</em>,
int <em>level</em>,
int <em>option_name</em>,
char *<em>option_value</em>,
int <em>option_length</em>)
</pre>
<br>
&nbsp;&nbsp;Service Program Name: QSOSRV1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<br>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;<a href="_xopen_source.htm">UNIX 98 Compatible Syntax</a><br>
<pre>
#define _XOPEN_SOURCE 520
#include &lt;sys/socket.h&gt;
int setsockopt(int <em>socket_descriptor</em>,
int <em>level</em>,
int <em>option_name</em>,
const void *<em>option_value</em>,
socklen_t <em>option_length</em>)
</pre>
<br>
&nbsp;&nbsp;Service Program Name: QSOSRV1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<br>
<p>The <em>setsockopt()</em> function is used to set socket options.</p>
<p>There are two versions of
the API, as shown above. The base i5/OS API uses BSD 4.3 structures and
syntax. The other uses syntax and structures compatible with the UNIX 98
programming interface specifications. You can select the UNIX 98 compatible
interface with the <a href="_xopen_source.htm">_XOPEN_SOURCE</a> macro.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>socket_descriptor</strong></dt>
<dd>(Input) The descriptor of the socket for which options are to be set.<br>
<br>
</dd>
<dt><strong>level</strong></dt>
<dd>(Input) Whether the request applies to the socket itself or the underlying
protocol being used. Supported values are:
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em><samp>IPPROTO_IP</samp></em></td>
<td align="left" valign="top">Request applies to IP protocol layer.</td>
</tr>
<tr>
<td align="left" valign="top"><em><samp>IPPROTO_TCP</samp></em></td>
<td align="left" valign="top">Request applies to TCP protocol layer.</td>
</tr>
<tr>
<td align="left" valign="top"><em><samp>SOL_SOCKET</samp></em></td>
<td align="left" valign="top">Request applies to socket layer.</td>
</tr>
<tr>
<td align="left" valign="top"><em><samp>IPPROTO_IPV6</samp></em></td>
<td align="left" valign="top">Request applies to IPv6 protocol layer.</td>
</tr>
<tr>
<td align="left" valign="top"><em><samp>IPPROTO_ICMPV6</samp></em></td>
<td align="left" valign="top">Request applies to ICMPv6 protocol layer.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>option_name</strong></dt>
<dd>(Input) The name of the option to be set. The following tables list the
options supported for each <em>level</em>. Assume that the option is supported
for all address families unless the option is described otherwise.
<p><strong>Note:</strong> Options directed to a specific protocol level are
only supported by that protocol. An option that is directed to the
<samp>SOL_SOCKET</samp> level always completes successfully. This provides
compatibility with <strong>Berkeley Software Distributions</strong>
implementations that also shield the application from protocols that do not
support an option.</p>
<p><strong><a name="Table_1-13">Socket Options That Apply to the IP Layer
(<samp>IPPROTO_IP</samp>)</a></strong></p>
<table border cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="top">Option</th>
<th align="left" valign="top">Description</th>
</tr>
<tr>
<td align="left" valign="top"><samp>IP_OPTIONS</samp> </td>
<td align="left" valign="top">Set IP header options. This is only supported for
sockets with an address family of <samp>AF_INET</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IP_TOS</samp> </td>
<td align="left" valign="top">Set Type Of Service (TOS) and Precedence in the
IP header. This option is only supported for sockets with an address family of
<samp>AF_INET</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IP_TTL</samp> </td>
<td align="left" valign="top">Set Time To Live (TTL) in the IP header. This
option is only supported for sockets with an address family
<samp>AF_INET</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IP_MULTICAST_IF</samp> </td>
<td align="left" valign="top">Set interface over which outgoing multicast
datagrams should be sent. An <em>option_value</em> parameter of type in_addr is
used to specify the local IP address that is associated with the interface over
which outgoing multicast datagrams should be sent. An address of INADDR_ANY
removes the previous selection. This option is only supported for sockets with
an address family of <samp>AF_INET</samp> and type of <samp>SOCK_DGRAM</samp>
or <samp>SOCK_RAW</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IP_MULTICAST_TTL</samp> </td>
<td align="left" valign="top">Set Time To Live (TTL) in the IP header for
outgoing multicast datagrams. An <em>option_value</em> parameter of type char
is used to set this value between 0 and 255. This option is only supported for
sockets with an address family of <samp>AF_INET</samp> and type of
<samp>SOCK_DGRAM</samp> or <samp>SOCK_RAW</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IP_MULTICAST_LOOP</samp> </td>
<td align="left" valign="top">Specify that a copy of an outgoing multicast
datagram should be delivered to the sending host as long as it is a member of
the multicast group. If this option is not set, a copy of the datagram will not
be delivered to the sending host. An <em>option_value</em> parameter of type
char is used to control loopback being on or off. This option is only supported
for sockets with an address family of <samp>AF_INET</samp> and type of
<samp>SOCK_DGRAM</samp> or <samp>SOCK_RAW</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IP_ADD_MEMBERSHIP</samp> </td>
<td align="left" valign="top">Joins a multicast group as specified in the
<em>option_value</em> parameter of type struct ip_mreq. A maximum of
IP_MAX_MEMBERSHIPS groups may be joined per socket. This option is only
supported for sockets with an address family of <samp>AF_INET</samp> and type
of <samp>SOCK_DGRAM</samp> or <samp>SOCK_RAW</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IP_DROP_MEMBERSHIP</samp> </td>
<td align="left" valign="top">Leaves a multicast group as specified in the
<em>option_value</em> parameter of type struct ip_mreq. This option is only
supported for sockets with an address family of <samp>AF_INET</samp> and type
of <samp>SOCK_DGRAM</samp> or <samp>SOCK_RAW</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IP_RECVLCLIFADDR</samp> </td>
<td align="left" valign="top">Indicates if the local interface that a datagram
to be received should be returned. A value of 1 indicates the first 4 bytes of
the reserved field of the sockaddr structure will contain the local interface.
This option is only supported for sockets with an address family of AF_INET and
type of SOCK_DGRAM.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IP_DONTFRAG</samp> </td>
<td align="left" valign="top">Set or reset the don't fragment flag in the IP
header. This option is supported for sockets with an address family of
<samp>AF_INET</samp> and type of <samp>SOCK_DGRAM</samp> or
<samp>SOCK_RAW</samp> only.</td>
</tr>
</table>
<br>
<br>
<p><strong><a name="Table_1-14">Socket Options That Apply to the TCP Layer
(<samp>IPPROTO_TCP</samp>)</a></strong></p>
<table border cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Option</th>
<th align="left" valign="top">Description</th>
</tr>
<tr>
<td align="left" valign="top"><samp>TCP_NODELAY</samp> </td>
<td align="left" valign="top"><img src="delta.gif" alt="Start of change">
Specifies whether TCP should follow the Nagle
algorithm for deciding when to send data. By default, TCP will follow the
Nagle algorithm. To disable this behavior, applications can enable TCP_NODELAY
to force TCP to always send data immediately. For example, TCP_NODELAY should
be used when there is an application using TCP for a request/response.
<img src="deltaend.gif" alt="End of change">
This option is only supported for sockets with an address family of
<samp>AF_INET</samp> or <samp>AF_INET6</samp> and type
of <samp>SOCK_STREAM</samp>.</td>
</tr>
</table>
<br>
<br>
<p><strong><a name="Table_1-17">Socket Options That Apply to the Socket Layer
(<samp>SOL_SOCKET</samp> )</a></strong></p>
<table border cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="top">Option</th>
<th align="left" valign="top">Description</th>
</tr>
<tr>
<td align="left" valign="top">
<img src="delta.gif" alt="Start of change">
<samp>SO_ACCEPTECONNABORTED</samp> </td>
<td align="left" valign="top">
Enable the listening socket such that a blocking <em>accept()</em> will return
ECONNABORTED when a connection
on the listening backlog is reset prior to the <em>accept()</em>.
A backlog entry is created when a new connection is established to the listener socket.
The <em>accept()</em> call will consume all leading invalid entries in the backlog,
until a valid entry is located or the backlog is exhausted. If the backlog
contains no entries or a valid entry is located, the option has no effect. If
the backlog contains at least one invalid entry and there are no valid entries,
the <em>accept()</em> will return -1 with errno set to ECONNABORTED.
The option is only valid on a socket that has successfully issued
the <em>listen()</em> call. The option has no effect on non-blocking sockets.
This option is only used by sockets with an address family of <samp>AF_INET</samp>
or <samp>AF_INET6</samp>.
<br>
<img src="deltaend.gif" alt="End of change">
</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_BROADCAST</samp> </td>
<td align="left" valign="top">Enable the socket for issuing messages to a
broadcast address. This option is only supported for sockets with an address
family of <samp>AF_INET</samp> and type <samp>SOCK_DGRAM</samp> or
<samp>SOCK_RAW</samp>. The broadcast address to be used may be determined by
issuing an <em>ioctl()</em> with the <samp>SIOCGIFBRDADDR</samp> request.<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_DEBUG</samp> </td>
<td align="left" valign="top">Indicates if low level-debugging is active.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_DONTROUTE</samp> </td>
<td align="left" valign="top">Bypass normal routing mechanisms. This option is
only supported by sockets with an address family of <samp>AF_INET</samp> or <samp>AF_INET6</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_KEEPALIVE</samp> </td>
<td align="left" valign="top">Keep the connection up by sending periodic
transmissions. This option is only supported for sockets of an address family
of <samp>AF_INET</samp> or <samp>AF_INET6</samp> and type
<samp>SOCK_STREAM</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_LINGER</samp> </td>
<td align="left" valign="top">Indicates if the system attempts delivery of any
buffered data or if the system discards it when a <em>close()</em> is issued.
<p>For sockets that are using a connection-oriented transport service with an
address family of <samp>AF_INET</samp> or <samp>AF_INET6</samp>, the
default is off (which means that the system attempts to
send any queued data, with an infinite wait-time).</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_OOBINLINE</samp> </td>
<td align="left" valign="top">Indicates whether out-of-band data is received
inline with normal data. This option is only supported for sockets with an
address family of <samp>AF_INET</samp> or <samp>AF_INET6</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_RCVBUF</samp> </td>
<td align="left" valign="top">Set the size of the receive buffer.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_RCVLOWAT</samp> </td>
<td align="left" valign="top">Set the size of the receive low-water mark. The
default size is 1. This option is only supported for sockets with a type of
SOCK_STREAM.<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_RCVTIMEO</samp> </td>
<td align="left" valign="top">Set the receive timeout value. This option is not
supported unless _XOPEN_SOURCE is defined to be 520 or greater.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_REUSEADDR</samp> </td>
<td align="left" valign="top">Indicates if the local socket address can be
reused. This option is supported by sockets with an address family of
<samp>AF_INET</samp> or
<samp>AF_INET6</samp> and a
type of <samp>SOCK_STREAM</samp> or <samp>SOCK_DGRAM</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_SNDBUF</samp> </td>
<td align="left" valign="top">Set the size of the send buffer.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_SNDLOWAT</samp> </td>
<td align="left" valign="top">Set the size of the send low-water mark. This
option is not supported.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_SNDTIMEO</samp> </td>
<td align="left" valign="top">Set the send timeout value. This option is not
supported unless _XOPEN_SOURCE is defined to be 520 or greater.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_USELOOPBACK</samp> </td>
<td align="left" valign="top">Indicates if the loopback feature is being used.
This option is not supported.</td>
</tr>
</table><br><br>
<p><strong><a name="Table_1-18">
Socket Options That Apply to the IPv6 Layer
(<samp>IPPROTO_IPV6</samp>)</a></strong></p>
<table border cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="top">Option</th>
<th align="left" valign="top">Description</th>
</tr>
<tr>
<td align="left" valign="top"><samp>IPV6_UNICAST_HOPS</samp> </td>
<td align="left" valign="top">Set the hop limit value that will be used for
subsequent unicast packets sent by this socket. An <em>option_value</em>
parameter of type int is used to set this value between 0 and 255. This option
is supported for sockets with an address family of <samp>AF_INET6</samp> only.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IPV6_MULTICAST_IF</samp> </td>
<td align="left" valign="top">Set the interface over which outgoing multicast
datagrams will be sent. An <em>option_value</em> parameter of type unsigned int
is used to set the interface index that is associated with the interface over
which outgoing multicast datagrams will be sent.
<img src="delta.gif" alt="Start of change">
This option is only supported for sockets with an address family of
<samp>AF_INET6</samp> and type of <samp>SOCK_DGRAM</samp> or <samp>SOCK_RAW</samp>.
<img src="deltaend.gif" alt="End of change">
</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IPV6_MULTICAST_HOPS</samp> </td>
<td align="left" valign="top">Set the hop limit value that will be used for
subsequent multicast packets sent by this socket. An <em>option_value</em>
parameter of type int is used to set this value between 0 and 255. If
IPV6_MULTICAST_HOPS is not set, the default is 1.
<img src="delta.gif" alt="Start of change">
This option is only supported for sockets with an address family of
<samp>AF_INET6</samp> and type of <samp>SOCK_DGRAM</samp> or <samp>SOCK_RAW</samp>.
<img src="deltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top"><samp>IPV6_MULTICAST_LOOP</samp> </td>
<td align="left" valign="top">Set the multicast looping mode. A value of 1
(default), indicates that multicast datagrams sent by this system should also
be delivered to this system as long as it is a member of the multicast group.
If this option is 0, a copy of the datagram will not be delivered to the
sending host. An <em>option_value</em> parameter of type unsigned int is used
to set this value. <img src="delta.gif" alt="Start of change">
This option is only supported for sockets with an address family of
<samp>AF_INET6</samp> and type of <samp>SOCK_DGRAM</samp> or <samp>SOCK_RAW</samp>.
<img src="deltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top"><samp>IPV6_JOIN_GROUP</samp> </td>
<td align="left" valign="top">Joins a multicast group as specified in the
<em>option_value</em> parameter of type struct ipv6_mreq. A maximum of
IP_MAX_MEMBERSHIPS groups may be joined per socket.
<img src="delta.gif" alt="Start of change">
This option is only supported for sockets with an address family of
<samp>AF_INET6</samp> and type of <samp>SOCK_DGRAM</samp> or <samp>SOCK_RAW</samp>.
<img src="deltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top"><samp>IPV6_LEAVE_GROUP</samp> </td>
<td align="left" valign="top">Leaves a multicast group as specified in the
<em>option_value</em> parameter of type struct ipv6_mreq.
<img src="delta.gif" alt="Start of change">
This option is only supported for sockets with an address family of
<samp>AF_INET6</samp> and type of <samp>SOCK_DGRAM</samp> or <samp>SOCK_RAW</samp>.
<img src="deltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top"><samp>IPV6_V6ONLY</samp> </td>
<td align="left" valign="top">Set the <samp>AF_INET6</samp> communication
restrictions. A non-zero value indicates that this <samp>AF_INET6</samp> socket
is restricted to IPv6 communications only. This option stores an int value.
This is a boolean option. By default this option is turned off. This option is
supported for sockets with an address family of
<samp>AF_INET6</samp> only.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IPV6_CHECKSUM</samp></td>
<td align="left" valign="top">Set if the kernel will calculate and insert a
checksum for output and verify the received checksum on input, discarding the
packet if the checksum is in error for this socket. An <em>option_value</em>
parameter of type int is used to set this value. If this option is -1 (the
default), this socket option is disabled. A value of 0 or greater specifies an
integer offset into the user data of where the checksum is located. This must be
an even integer value. This option
is only supported for sockets with an address family of <samp>AF_INET6</samp>
and type of <samp>SOCK_RAW</samp> with a protocol other than
<samp>IPPROTO_ICMPV6</samp>. The checksum is automatically computed for
protocol <samp>IPPROTO_ICMPV6</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><img src="delta.gif" alt="Start of change"><samp>IPV6_DONTFRAG</samp></td>
<td align="left" valign="top">Set if the kernel will not implement the
automatic insertion of a fragment header in the packet if the packet is too big
for the path MTU. By default this socket option is disabled. Setting the
value to 0 also disables the option. If this option is set to a non-zero value
the kernel will discard the packet instead of inserting the fragment
header. This option is supported for sockets with an address family of
<samp>AF_INET6</samp> and type of <samp>SOCK_DGRAM</samp> or
<samp>SOCK_RAW</samp> only.<img src="deltaend.gif" alt="End of change"></td>
</tr>
</table>
<br><br>
<p><strong><a name="Table_1-19">Socket Options That Apply to the ICMPv6 Layer
(<samp>IPPROTO_ICMPV6</samp>)</a></strong></p>
<table border cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Option</th>
<th align="left" valign="top">Description</th>
</tr>
<tr>
<td align="left" valign="top"><samp>ICMP6_FILTER</samp> </td>
<td align="left" valign="top">Set the ICMPv6 Type Filtering. An
<em>option_value</em> parameter of type <strong>struct icmp6_filter</strong>,
defined in <strong>&lt;netinet/icmp6.h&gt;</strong> is used to set this value.
The following macros, defined in <strong>&lt;netinet/icmp6.h&gt;</strong> can
be used to update the type filtering structure to specify whether or not
specific ICMPv6 message types will be passed to the application or be blocked:
ICMP6_FILTER_SETPASS, ICMP6_FILTER_SETBLOCK, ICMP6_FILTER_SETPASSALL, and
ICMP6_FILTER_SETBLOCKALL. The default is to pass all ICMPv6 message types to
the application. This option is only supported for sockets with an address
family of <samp>AF_INET6</samp> and type of <samp>SOCK_RAW</samp> with a
protocol of <samp>IPPROTO_ICMPV6</samp>.</td>
</tr>
</table>
<br><br>
</dd>
<dt><strong>option_value</strong></dt>
<dd>(Input) A pointer to the option value. Integer flags/values are required by
<em>setsockopt()</em> for all the socket options except <samp>SO_LINGER</samp>,
<samp>IP_OPTIONS</samp>, <samp>IP_MULTICAST_IF</samp>,
<samp>IP_MULTICAST_TTL</samp>, <samp>IP_MULTICAST_LOOP</samp>,
<samp>IP_ADD_MEMBERSHIP</samp>, <samp>IP_DROP_MEMBERSHIP</samp>, <samp>IPV6_JOIN_GROUP</samp>,
<samp>IPV6_LEAVE_GROUP</samp>, <samp>ICMP6_FILTER</samp>.
<p><strong>Note:</strong> For the <samp>IP_TOS</samp> and <samp>IP_TTL</samp>
options, only the rightmost octet (least significant octet) of the integer
value is used.</p>
<p>The following options can be set by specifying a nonzero value for the
<em>option_value</em> parameter:</p>
<ul>
<li><samp><img src="delta.gif" alt="Start of change">
SO_ACCEPTECONNABORTED<img src="deltaend.gif" alt="End of change"></samp></li>
<li><samp>SO_BROADCAST</samp></li>
<li><samp>SO_DEBUG</samp></li>
<li><samp>SO_DONTROUTE</samp></li>
<li><samp>SO_KEEPALIVE</samp></li>
<li><samp>SO_OOBINLINE</samp></li>
<li><samp>SO_REUSEADDR</samp></li>
<li><samp>TCP_NODELAY</samp></li>
<li><samp>IP_MULTICAST_LOOP</samp></li>
<li><samp>IP_DONTFRAG</samp></li>
<li><samp>IPV6_V6ONLY</samp></li>
<li><samp>IPV6_MULTICAST_LOOP</samp></li>
<li><img src="delta.gif" alt="Start of change">
<samp>IPV6_DONTFRAG</samp><img src="deltaend.gif" alt="End of change"></li>
</ul>
<p>For the <samp>SO_LINGER</samp> option, <em>option_value</em> is a pointer to
the structure <strong>struct linger</strong>, defined in
<strong>&lt;sys/socket.h&gt;</strong>.</p>
<pre>
struct linger [
int l_onoff;
int l_linger;
];
</pre>
<p>The <em>l_onoff</em> field determines if the linger option is set. A nonzero
value indicates the linger option is set and is using the <em>l_linger</em>
value. A zero value indicates that the option is not set. The <em>l_linger</em>
field is the time to wait before any buffered data to be sent is discarded. The
following occur on a <em>close()</em>:</p>
<ul>
<li>For <samp>AF_INET</samp> and
<samp>AF_INET6</samp>
sockets:<br>
<br>
<ul>
<li>If the <em>l_onoff</em> value is zero, the system attempts to send any
buffered data with an infinite wait-time.<br>
<br>
</li>
<li>If the <em>l_onoff</em> value is nonzero and the <em>l_linger</em> value is
nonzero, the system attempts to send any buffered data for <em>l_linger</em>
time. If <em>l_linger</em> time has elapsed and the data is still not
successfully sent, it is discarded. When data is discarded, the remote program
may receive a <samp>[ECONNRESET]</samp>.<br>
<br>
</li>
</ul>
</li>
<li>For <samp>AF_INET</samp> sockets over SNA:<br>
<br>
<ul>
<li>If the <em>l_onoff</em> value is nonzero and the <em>l_linger</em> value is
zero, the system waits indefinitely (no timer is implemented). Otherwise, if
the <em>l_onoff</em> value is nonzero and the <em>l_linger</em> value is zero,
the system discards any buffered data. When data is discarded, the remote
program may receive a <samp>[ECONNRESET]</samp>.<br>
<br>
</li>
</ul>
</li>
</ul>
<p><strong>Note:</strong> An application must implement an application level
confirmation. Guaranteed receipt of data by the partner program is required.
Setting <samp>SO_LINGER</samp> does not guarantee delivery.</p>
<p> For the
<samp>SO_RCVTIME</samp> and <samp>SO_SNDTIME</samp> options,
<em>option_value</em> is a pointer to where the structure
<strong>timeval</strong> is stored. The structure <strong>timeval</strong> is
defined in <strong>&lt;sys/time.h&gt;</strong>.</p>
<pre>
struct timeval {
long tv_sec;
long tv_usec;
};
</pre>
<p>For the <samp>IP_OPTIONS</samp> option, <em>option_value</em> is a pointer
to a character string representing the IP options as specified in RFC 791. The
character string varies depending on which options are selected. Each option is
made up of a single byte representing the option code, and may be followed by a
length field (1 byte) and data for the option. The IP options that can be set
are:</p>
<ul>
<li>End of option list. Used if options do not end at end of header.</li>
<li>No operation (used to align octets in a list of options).</li>
<li>Security and handling restrictions.</li>
<li>Loose source routing. Used to route a datagram along a path of specified IP
addresses. Multiple network hops are allowed between any two IP addresses on
the path.</li>
<li>Record route. Used to trace a route.</li>
<li>Stream identifier. Used to carry a SATNET stream identifier. This option
has been deprecated by RFC 1122 and will result in an error of
<samp>[EINVAL]</samp> if used.</li>
<li>Strict source routing. Used to route datagram along a path of specified IP
addresses. No additional network hops are allowed between any two IP addresses
in the path.</li>
<li>Internet timestamp. Used to record timestamps along the route.</li>
</ul>
<p>For the <samp>IP_MULTICAST_IF</samp> option, <em>option_value</em> is a
pointer to the structure <strong>in_addr</strong>, defined in
<strong>&lt;netinet/in.h&gt;</strong> as:</p>
<pre>
struct in_addr [
u_long s_addr;
/* IP address */
];
</pre>
<p>The <strong>s_addr</strong> field specifies the local IP address that is
associated with the interface over which outgoing multicast datagrams should be
sent.</p>
<p>For the <samp>IP_ADD_MEMBERSHIP</samp> and <samp>IP_DROP_MEMBERSHIP</samp>
options, <em>option_value</em> is a pointer to the structure
<strong>ip_mreq</strong>, defined in <strong>&lt;netinet/in.h&gt;</strong>
as:</p>
<pre>
struct ip_mreq [
struct in_addr imr_multiaddr; /* IP multicast address of group */
struct in_addr imr_interface; /* local IP address of interface */
];
</pre>
<p>The <em>imr_multiaddr</em> field is used to specify the multicast group to
join or leave. The <em>imr_interface</em> field is used to specify the local IP
address that is associated with the interface to which this request applies. If
INADDR_ANY is specified for the local interface, the default multicast
interface will be selected.</p>
<p><img src="delta.gif" alt="Start of change">
For the <samp>IPV6_JOIN_GROUP</samp> and <samp>IPV6_LEAVE_GROUP</samp>
options, <em>option_value</em> is a pointer to the structure
<strong>ipv6_mreq</strong>, defined in <strong>&lt;netinet/in.h&gt;</strong>
as:</p>
<pre>
struct ipv6_mreq [
struct in6_addr ipv6mr_multiaddr; /* IPv6 multicast address */
unsigned int ipv6mr_interface; /* interface index */
];
</pre>
<p>The <em>ipv6mr_multiaddr</em> field is used to specify the multicast group to join
or leave. The <em>ipv6mr_interface</em> field is used to specify the interface to
which this request applies. If 0 is specified for the interface, the system will
choose the local interface.<img src="deltaend.gif" alt="End of change"></p>
<p><strong>Note:</strong> Reception of IP multicast datagrams may require
configuration changes to the line description to enable the adapter to receive
packets with a multicast destination address. On Ethernet, for example, the
Ethernet group address that is associated with the IP group address must be
specified by the GRPADR parameter on the line description. To determine the
Ethernet group address for a particular IP group address, the low-order 23 bits
of the IP address are placed into the low-order 23 bits of the Ethernet group
address 01.00.5E.xx.xx.xx.</p>
<p><strong>Notes:</strong></p>
<ol>
<li>For sockets that use a connection-oriented transport service, IP options
that are set using <em>setsockopt()</em> are only used if they are set prior to
a <em>connect()</em> being issued. After the connection is established, any IP
options that the user sets are ignored.<br>
<br>
</li>
<li>If the IP options portion contains a source routing option, then the
address in the source routing option overrides the destination address. The
destination address may have been specified on an output operation (for
example, on a <em>sendto()</em>) or on a <em>connect()</em>.<br>
<br>
</li>
<li>If a socket has a type of SOCK_RAW and a protocol of IPPROTO_RAW, any IP
options set using <em>setsockopt()</em> are ignored (since the user must supply
the IP header data on an output operation as part of the data that is being
transmitted).</li>
</ol>
<br>
</dd>
<dt><strong>option_length</strong></dt>
<dd>(Input) The length of the <em>option_value</em>.</dd>
</dl>
<br>
<h3>Authorities</h3>
The user profile for the thread must have
<samp>*IOSYSCFG</samp> special authority to set options when the <em>level</em>
parameter specifies <samp>IPPROTO_IP</samp> and the <em>option_value</em>
parameter is <samp>IP_OPTIONS</samp>.<br>
<br>
<h3>Return Value</h3>
<p><em>setsockopt()</em> returns an integer. Possible values are:</p>
<ul>
<li>-1 (unsuccessful)<br>
<br>
</li>
<li>0 (successful)</li>
</ul>
<br>
<h3>Error Conditions</h3>
<p>When <em>setsockopt()</em> fails, <em>errno</em> can be set to one of the
following:</p>
<dl>
<dt><em>[EADDRINUSE]</em></dt>
<dd>
<p>Address already in use. This error code indicates that the
<em>socket_descriptor</em> parameter specified for the
<samp>IP_ADD_MEMBERSHIP</samp> operation is already a member of the specified
multicast group.</p>
</dd>
<dt><em>[EADDRNOTAVAIL]</em></dt>
<dd>
<p>Address not available. For the <samp>IP_ADD_MEMBERSHIP</samp> or
<samp>IP_DROP_MEMBERSHIP</samp> operations, this error code indicates that an
incorrect address was specified for either the <em>imr_multiaddr</em> or
<em>imr_interface</em> parameter value.</p>
</dd>
<dt><em>[EBADF]</em></dt>
<dd>
<p>Descriptor not valid.</p>
</dd>
<dt><em>[ECONNABORTED]</em></dt>
<dd>
<p>Connection ended abnormally.</p>
<p>This error code indicates that the transport provider ended the connection
abnormally because of one of the following:</p>
<ul>
<li>The retransmission limit has been reached for data that was being sent on
the socket.</li>
<li>A protocol error was detected.</li>
</ul><br>
</dd>
<dt><em>[EFAULT]</em></dt>
<dd>
<p>Bad address.</p>
<p>The system detected an address which was not valid while attempting to
access the <em>option_value</em> parameter.</p>
</dd>
<dt><em>[EINVAL]</em></dt>
<dd>
<p>Parameter not valid.</p>
<p>This error code indicates one of the following:</p>
<ul>
<li>The <em>level</em> parameter specifies a level that is not supported.</li>
<li>The <em>option_name</em> parameter specifies a value that is not valid
(except for when the level is <samp>SOL_SOCKET</samp> , in which case
<samp>[ENOPROTOOPT]</samp> is returned).</li>
<li>The <em>option_value</em> parameter specifies a value that is not
valid.</li>
<li>The <em>option_length</em> parameter specifies a negative or zero
value.</li>
<li>An attempt was made to set a socket option that was read-only.</li>
</ul><br>
</dd>
<dt><em>[EIO]</em></dt>
<dd>
<p>Input/output error.</p>
</dd>
<dt><em>[ENOBUFS]</em></dt>
<dd>
<p>There is not enough buffer space for the requested operation.</p>
</dd>
<dt><em>[ENOPROTOOPT]</em></dt>
<dd>
<p>The protocol does not support the specified option.</p>
<p>This error code indicates one of the following:</p>
<ul>
<li>The socket has an address family of <samp>AF_UNIX</samp> and the
<em>level</em> parameter specified is not <samp>SOL_SOCKET</samp> .</li>
<li>The <em>level</em> parameter specifies a level of <samp>SOL_SOCKET</samp>
and the <em>option_name</em> parameter specifies a value that is not
valid.</li>
</ul><br>
</dd>
<dt><em>[ENOTCONN]</em></dt>
<dd>
<p>Requested operation requires a connection.</p>
<p>This error code is only returned if the <em>level</em> parameter specifies a
level other than <samp>SOL_SOCKET</samp> and the <em>socket_descriptor</em>
parameter points to a socket that is using a connection-oriented transport
service that has had its connection broken.</p>
</dd>
<dt><em>[ENOTSOCK]</em></dt>
<dd>
<p>The specified descriptor does not reference a socket.</p>
</dd>
<dt><em>[EPERM]</em></dt>
<dd>
<p>Operation not permitted.</p>
<p>The executing user profile must have <samp>*IOSYSCFG</samp> special
authority to set options when the <em>level</em> parameter specifies
<samp>IPPROTO_IP</samp> and the <em>option_value</em> parameter is
<samp>IP_OPTIONS</samp>.</p>
</dd>
<dt><em>[ETOOMANYREFS]</em></dt>
<dd>
<p>The operation would have exceeded the maximum number of references allowed
for this socket.</p>
</dd>
<dt><em>[EUNATCH]</em></dt>
<dd>
<p>The protocol required to support the specified address family is not
available at this time.</p>
</dd>
<dt><em>[EUNKNOWN]</em></dt>
<dd>
<p>Unknown system state.</p>
</dd>
</dl>
<br>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPE3418 E</td>
<td align="left" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA081 E</td>
<td align="left" valign="top">Unable to set return value or error code.</td>
</tr>
</table>
<br>
<br>
<h3>Usage Notes</h3>
<ol>
<li>Socket options are defined in <strong>&lt;sys/socket.h&gt;</strong>, IP
options are defined in <strong>&lt;netinet/ip.h&gt;</strong> and
<strong>&lt;netinet/in.h&gt;</strong>, TCP options are defined in
<strong>&lt;netinet/tcp.h&gt;</strong>, IPv6 and ICMPv6 options are defined in
<strong>&lt;netinet/in.h&gt;</strong>.<br>
<br>
</li>
<li>The following comments applies to the <samp>SO_SNDBUF</samp> option value:
<ul>
<li>For <samp>AF_INET</samp> and
<samp>AF_INET6</samp> sockets
over TCP of type <samp>SOCK_STREAM</samp>, the maximum value the
<samp>SO_SNDBUF</samp> option can be set to is 8 megabytes. Anything greater
results in an error of <samp>[ENOBUFS]</samp>. If the <samp>SO_SNDBUF</samp>
option value is set to a positive value that is less than 512 bytes, the system
automatically uses 512 bytes as the <samp>SO_SNDBUF</samp> size.<br>
<br>
</li>
<li>For <samp>AF_INET</samp> and
<samp>AF_INET6</samp> sockets
over UDP of type <samp>SOCK_DGRAM</samp>, the maximum value the
<samp>SO_SNDBUF</samp> option can be set to is 65535 bytes less the IP and UDP
header sizes. Anything greater results in an error of
<samp>[EINVAL]</samp>.</li>
</ul>
<br>
</li>
<li>For <samp>AF_INET</samp> sockets over SNA of type <samp>SOCK_STREAM</samp>,
<samp>SO_RCVBUF</samp> should be set before connection is established. After
connection is established, any changes are ignored. Also, only the client can
affect the receive buffer size. The server cannot affect it.<br>
<br>
</li>
<li>For <samp>AF_INET</samp> sockets over SNA of type <samp>SOCK_DGRAM</samp>,
both <samp>SO_SNDBUF</samp> and <samp>SO_RCVBUF</samp> are ignored and have no
effect on processing.<br>
<br>
</li>
<li>When a TCP connection is closed for a socket using the <samp>AF_INET</samp>
or <samp>AF_INET6</samp> address family, the port associated
with that connection is not made available until twice the Maximum Segment Life
(MSL) time in seconds has passed. The MSL time is approximately 2 minutes. The
<samp>SO_REUSEADDR</samp> option allows a <em>bind()</em> to succeed when
requesting a port that is being held during this time frame. This can be
especially useful if a server is abruptly ended and restarted.
<p><strong>Notes:</strong></p>
<ul>
<li>For AF_INET and AF_INET6,
SOCK_STREAM sockets, this
option does <strong>not</strong> allow two servers to successfully issue a
<em>bind()</em> requesting the same port number and local address combination.
For AF_INET and AF_INET6, SOCK_DGRAM sockets, the SO_REUSEADDR
option does allow multiple servers to successfully bind to the same port. When
broadcast or multicast datagrams are received for a given port, each server
that is bound to that port receives a copy of the datagram provided each server
has enabled the SO_REUSEADDR option.<br><br>
</li>
<li>This option does not affect unicast datagram delivery.</li>
</ul>
<br>
</li>
<li>The following <samp>SOL_SOCKET</samp> options are not supported by AF_INET
sockets over SNA. <em>setsockopt()</em> appears to succeed, but has no effect
on the function of AF_INET sockets over SNA.
<ul>
<li><samp>SO_BROADCAST</samp></li>
<li><samp>SO_DONTROUTE</samp></li>
<li><samp>SO_KEEPALIVE</samp></li>
<li><samp>SO_LINGER</samp></li>
</ul>
<br>
</li>
<li>The option <samp>IP_DONTFRAG</samp> <img src="delta.gif" alt="Start of change">
and <samp>IPV6_DONTFRAG</samp> are <img src="deltaend.gif" alt="End of change">not
valid for multicast group destinations.<br>
<br>
</li>
<li>When you develop in C-based
languages and an application is compiled with the _XOPEN_SOURCE macro defined
to the value 520 or greater, the <em>setsockopt()</em> API is mapped to
<em>qso_setsockopt98()</em>.</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li><a href=
"_xopen_source.htm">_XOPEN_SOURCE</a>--Using _XOPEN_SOURCE for the UNIX 98
compatible interface<br>
<br>
</li>
<li><a href="gsocko.htm">getsockopt()</a>--Retrieve Information about Socket
Options</li>
</ul>
<br>
<hr>
API introduced: V3R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a> </td>
</tr>
</table></center>
</body>
</html>
Reference in New Issue Copy Permalink