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

1082 lines
35 KiB
HTML
Raw Blame History

<!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>getsockopt()--Retrieve Information about Socket Options</title>
<!-- Begin Header Records ========================================== -->
<!-- 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. -->
<!-- Change History: -->
<!-- Unix8 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- 040405 MULLENBA Added IPV6_DONTFRAG and misc other. -->
<!-- 041207 MULLENBA Added SO_ACCEPTECONNABORTED -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!--End Header Records -->
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<h2>getsockopt()--Retrieve Information about Socket Options</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;BSD 4.3 Syntax<br>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;sys/socket.h&gt;
int getsockopt(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: 70%;">
<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 getsockopt(int <em>socket_descriptor</em>,
int <em>level</em>,
int <em>option_name</em>,
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>getsockopt()</em> function is used to retrieve information about
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 information is to be
retrieved.<br>
<br>
</dd>
<dt><strong>level</strong></dt>
<dd>(Input) Value indicating whether the request applies to the socket itself
or to the underlying protocol being used. Supported values are:<br>
<br>
<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>
<br>
</dd>
<dt><strong>option_name</strong></dt>
<dd>(Input) The option name for which information is to be retrieved. The
following tables list the options supported, and for which level the option
applies. 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 <em>level</em>
<samp>SOL_SOCKET</samp> usually completes successfully. If the underlying
protocol does not provide support for the option, the socket library retrieves
one of the following:</p>
<ul>
<li>The default value for the option.</li>
<li>The value previously set with a <em>setsockopt()</em>.</li>
</ul>
<p>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-3">Socket Options That Apply to the IP Layer
(<samp>IPPROTO_IP</samp>)</a></strong></p>
<table border cellpadding="5">
<!-- cols="20 80" -->
<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">Determine what options are set in the IP header.
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">Get 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">Get Time To Live (TTL) 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_MULTICAST_IF</samp> </td>
<td align="left" valign="top">Get interface over which outgoing multicast
datagrams will be sent. An <em>option_value</em> parameter of type in_addr is
used to retrieve the local IP address that is associated with the interface
over which outgoing multicast datagrams will be sent. 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">Get Time To Live (TTL) from the IP header for
outgoing multicast datagrams. An <em>option_value</em> parameter of type char
is used into which a value between 0 and 255 is retrieved. 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_DONTFRAG</samp> </td>
<td align="left" valign="top">Return the current Don't fragment flag setting in
the IP header. A value of 0 indicates that it is reset. A value of 1 indicates
that it is set. 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>
<tr>
<td align="left" valign="top"><samp>IP_MULTICAST_LOOP</samp> </td>
<td align="left" valign="top">Determine the multicast looping mode. A non-zero
value 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 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
retrieve the current setting. 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">Determine if the local interface that a datagram
was received will 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>
</table>
<br>
<br>
<p><strong><a name="Table_1-4">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 <samp>TCP_NODELAY</samp> to force TCP to always send data
immediately. A non-zero <em>option_value</em> returned by getsockopt indicates
<samp>TCP_NODELAY</samp> is enabled. For example, <samp>TCP_NODELAY</samp>
should be used when there is an appliciation 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
<samp>SOCK_STREAM</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>TCP_MAXSEG</samp> </td>
<td align="left" valign="top">Determine TCP maximum segment size. This option
is only supported for sockets with an address family of
<samp>AF_INET</samp> or
<samp>AF_INET6</samp> and type
<samp>SOCK_STREAM</samp>.</td>
</tr>
</table>
<br>
<br>
<p><strong><a name="Table_1-7">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"><samp>SO_ACCEPTCONN</samp> </td>
<td align="left" valign="top">Reports whether socket listening is enabled. This
option stores an int value. This is a boolean option.</td>
</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">
Determine if the listening socket will return ECONNABORTED when a connection
on the listening backlog is reset prior to a blocking <em>accept()</em>.
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">Determine if messages can be sent to the
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 can be determined by issuing an
<em>ioctl()</em> specifying the <samp>SIOCGIFBRDADDR</samp> request.<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_DEBUG</samp> </td>
<td align="left" valign="top">Determine if low level-debugging is active.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_DONTROUTE</samp> </td>
<td align="left" valign="top">Determine if the normal routing mechanism is
being bypassed. 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_ERROR</samp> </td>
<td align="left" valign="top">Return any pending errors in the socket. The
value returned corresponds to the standard error codes defined in
<strong>&lt;errno.h&gt;</strong> </td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_KEEPALIVE</samp> </td>
<td align="left" valign="top">Determine if the connection is being kept up by
periodic transmissions. This option is only supported for sockets with 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">Determine whether the system attempts to deliver
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">Determine if 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">Determine the size of the receive buffer.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_RCVLOWAT</samp> </td>
<td align="left" valign="top">Determine the size of the receive low-water mark.
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">Determine 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">Determine 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">Determine the size of the send buffer.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_SNDLOWAT</samp> </td>
<td align="left" valign="top">Determine 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">Determine 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_TYPE</samp> </td>
<td align="left" valign="top">Determine the value for the socket
<em>type</em>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>SO_USELOOPBACK</samp> </td>
<td align="left" valign="top">Determine if the loopback feature is being used.
This option is not supported.</td>
</tr>
</table>
<br>
<br>
<p><strong><a name="Table_1-8">
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">Get 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 retrieve the current setting. This option is
only supported for sockets with an address family of
<samp>AF_INET6</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IPV6_MULTICAST_IF</samp> </td>
<td align="left" valign="top">Get the interface over which outgoing multicast
datagrams will be sent. An <em>option_value</em> parameter of type unsigned int
is used to retrieve 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">Get 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 retrieve the current setting.
<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">Determine 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 retrieve the current setting. <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">Determine 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
only supported for sockets with an address family of
<samp>AF_INET6</samp>.</td>
</tr>
<tr>
<td align="left" valign="top"><samp>IPV6_CHECKSUM</samp></td>
<td align="left" valign="top">Determine 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 retrieve the current setting. 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 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">Determine 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. A value of 0 disables the option meaning the default of
automatic insertion will be used. A non-zero value indicates that the option
is set meaning 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-9">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">Determine the current 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 retrieve the
current setting. The following macros, defined in
<strong>&lt;netinet/icmp6.h&gt;</strong> can be used after retrieval of the
type filtering structure to determine whether or not specific ICMPv6 message
types will be passed to the application or be blocked: ICMP6_FILTER_WILLPASS
and ICMP6_FILTER_WILLBLOCK. 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>(Output) A pointer to the option value. Integer flags/values are returned
by <em>getsockopt()</em> for all the socket options except for
<samp>SO_LINGER</samp> , <samp>IP_OPTIONS</samp> , <samp>IP_MULTICAST_IF</samp>
, <samp>IP_MULTICAST_TTL</samp>, <samp>IP_MULTICAST_LOOP</samp>, and <samp>ICMP6_FILTER</samp>.
<p>The following options should be considered as set if a nonzero value for the
<em>option_value</em> parameter is returned:</p>
<ul>
<li><samp>SO_ACCEPTCONN</samp></li>
<li><img src="delta.gif" alt="Start of change">
<samp>SO_ACCEPTECONNABORTED</samp><img src="deltaend.gif" alt="End of change"></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>SO_USELOOPBACK</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_IF</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
where the structure <strong>linger</strong> is stored. The structure
<strong>linger</strong> is 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>.</li>
</ul>
<br>
</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>.</li>
</ul>
<br>
</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>
<br>
<p>For the <samp>IP_OPTIONS</samp> option, <em>option_value</em> is a pointer
to storage in which data representing the IP options (as specified in RFC 791)
is stored. <em>getsockopt()</em> returns the options in the following
format:</p>
<table border cellpadding="5">
<tr>
<td align="left" valign="middle"><strong>IP address</strong></td>
<td align="left" valign="middle"><strong>IP options</strong></td>
<td align="left" valign="middle"><strong>...</strong></td>
<td align="left" valign="middle"><strong>IP options</strong></td>
</tr>
</table>
<p>IP address is a 4-byte IP address, and IP options identifies the IP options
that were set using <em>setsockopt()</em>. If an IP option set using
<em>setsockopt()</em> contained a source routing option (strict or loose), the
first IP address in the source routing option list is removed. The IP options
are adjusted accordingly. (For this adjustment, the length in the IP options
portion is changed, and alignment is kept by adding no-operation option). The
buffer is returned in the same format. The first 4 bytes are the IP address
that was removed, and this is followed by the remaining IP options, if any. If
the IP options portion does not contain a source routing option, the first 4
bytes are set to zero.</p>
<p>For the <samp>IP_MULTICAST_IF</samp> option, <em>option_value</em> is a
pointer to storage in which the structure <strong>in_addr</strong>, defined in
<strong>&lt;netinet/in.h&gt;</strong> as the following, will be stored:</p>
<pre>
struct in_addr {
u_long s_addr; /* IP address */
};
</pre>
<p>The <strong>s_addr</strong> field that is returned will be the local IP
address that is associated with the interface over which outgoing multicast
datagrams are being sent.</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).<br>
<br>
</li>
<li>The structure <strong>ip_opts</strong> (defined in
<strong>&lt;netinet/in.h&gt;</strong>) can be used to receive IP options.</li>
</ol>
<br>
<br>
</dd>
<dt><strong>option_length</strong></dt>
<dd>(I/O) The length of the <em>option_value</em>. The <em>option_length</em>
parameter must be initially set by the caller. <em>option_length</em> is
changed on return to indicate the actual amount of storage used.
<p><strong>Note:</strong> For option values that are of type integer, the
length of the <em>option_value</em> pointed to by the <em>option_length</em>
parameter must be set to a value that is greater or equal to the size of an
integer. If the length is not set correctly, a correct option value is not
received.</p>
</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>getsockopt()</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>getsockopt()</em> fails, <em>errno</em> can be set to one of the
following:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>[EBADF]</em></td>
<td align="left" valign="top">Descriptor not valid.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ECONNABORTED]</em></td>
<td align="left" valign="top">Connection ended abnormally.
<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.<br>
<br>
</li>
<li>A protocol error was detected.<br>
</li>
</ul>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EFAULT]</em></td>
<td align="left" valign="top">Bad address.
<p>The system detected an address which was not valid while attempting to
access the <em>option_value</em> or <em>option_length</em> parameters.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EINVAL]</em></td>
<td align="left" valign="top">Parameter not valid.
<p>This error code indicates one of the following:</p>
<ul>
<li>The <em>level</em> parameter specifies a level that is not supported.
(except for when the socket has an address family of <samp>AF_UNIX</samp>, in
which case <samp>[ENOPROTOOPT]</samp> is returned).<br>
<br>
</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).<br>
<br>
</li>
<li>The <em>option_length</em> parameter points to an integer that has a
negative value.<br>
</li>
</ul>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EIO]</em></td>
<td align="left" valign="top">Input/output error.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENOBUFS]</em></td>
<td align="left" valign="top">There is not enough buffer space for the
requested operation.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENOPROTOOPT]</em></td>
<td align="left" valign="top">The protocol does not support the specified
option.
<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> .<br>
<br>
</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.<br>
</li>
</ul>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENOTCONN]</em></td>
<td align="left" valign="top">Requested operation requires a connection.
<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>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[ENOTSOCK]</em></td>
<td align="left" valign="top">The specified descriptor does not reference a
socket.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EPERM]</em></td>
<td align="left" valign="top">Operation not permitted.
<p>The executing user profile must have <samp>*IOSYSCFG</samp> special
authority to get 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>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EUNKNOWN]</em></td>
<td align="left" valign="top">Unknown system state.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>[EUNATCH]</em></td>
<td align="left" valign="top">The protocol required to support the specified
address family is not available at this time.</td>
</tr>
</table>
<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 width="15%" valign="top">CPE3418 E</td>
<td width="85%" 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>When a TCP connection is closed for a socket using the <samp>AF_INET</samp>
or <samp>AF_INET6</samp> address families, 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>
<ol>
<li>For <samp>AF_INET</samp> and <samp>AF_INET6</samp>,
<samp>SOCK_STREAM</samp> 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 <samp>AF_INET</samp> and <samp>AF_INET6</samp>, <samp>SOCK_DGRAM</samp>
sockets, the <samp>SO_REUSEADDR</samp>
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 <samp>SO_REUSEADDR</samp> option.<br>
<br>
</li>
<li>This option does not affect unicast datagram delivery.</li>
</ol>
<br>
<br>
</li>
<li>Issuing a <em>getsockopt()</em> with the <samp>SO_ERROR</samp> option
results in the resetting of the <samp>SO_ERROR</samp> option to zero. Issuing
another <em>getsockopt()</em> with the <samp>SO_ERROR</samp> option also
returns a value of zero, assuming no errors occur on the socket. Other
functions, when issued, also reset the <samp>SO_ERROR</samp> option to zero.
These functions are:
<ul>
<li><em>read()</em>, <em>readv()</em>, <em>recv()</em>, <em>recvmsg()</em>,
<em>recvfrom()</em><br>
<br>
</li>
<li><em>connect()</em> (only when using a connectionless transport
service)</li>
</ul>
</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>getsockopt()</em> API is mapped to
<em>qso_getsockopt98()</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="ssocko.htm">setsockopt()</a>--Set 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 View Git Blame Copy Permalink