270 lines
11 KiB
HTML
270 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>getsockopt</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
|
|
<basefont size="3"> <a name="getsockopt"></a> <a name="tag_03_252"></a><!-- getsockopt -->
|
|
<!--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_252_01"></a>NAME</h4>
|
|
|
|
<blockquote>getsockopt - get the socket options</blockquote>
|
|
|
|
<h4><a name="tag_03_252_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 getsockopt(int</tt> <i>socket</i><tt>, int</tt> <i>level</i><tt>, int</tt> <i>option_name,</i><tt><br>
|
|
void *restrict</tt> <i>option_value</i><tt>, socklen_t *restrict</tt>
|
|
<i>option_len</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_252_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>getsockopt</i>() function manipulates options associated with a socket.</p>
|
|
|
|
<p>The <i>getsockopt</i>() function shall retrieve the value for the option specified by the <i>option_name</i> argument for the
|
|
socket specified by the <i>socket</i> argument. If the size of the option value is greater than <i>option_len</i>, the value stored
|
|
in the object pointed to by the <i>option_value</i> argument shall be silently truncated. Otherwise, the object pointed to by the
|
|
<i>option_len</i> argument shall be modified to indicate the actual length of the value.</p>
|
|
|
|
<p>The <i>level</i> argument specifies the protocol level at which the option resides. To retrieve options at the socket level,
|
|
specify the <i>level</i> argument as SOL_SOCKET. To retrieve options at other levels, supply the appropriate level identifier for
|
|
the protocol controlling the option. For example, to indicate that an option is interpreted by the TCP (Transmission 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 socket in use may require the process to have appropriate privileges to use the <i>getsockopt</i>() function.</p>
|
|
|
|
<p>The <i>option_name</i> argument specifies a single option to be retrieved. It can be one of the following values defined in <a
|
|
href="../basedefs/sys/socket.h.html"><i><sys/socket.h></i></a>:</p>
|
|
|
|
<dl compact>
|
|
<dt>SO_DEBUG</dt>
|
|
|
|
<dd>Reports whether debugging information is being recorded. This option shall store an <b>int</b> value. This is a Boolean
|
|
option.</dd>
|
|
|
|
<dt>SO_ACCEPTCONN</dt>
|
|
|
|
<dd>Reports whether socket listening is enabled. This option shall store an <b>int</b> value. This is a Boolean option.</dd>
|
|
|
|
<dt>SO_BROADCAST</dt>
|
|
|
|
<dd>Reports whether transmission of broadcast messages is supported, if this is supported by the protocol. This option shall store
|
|
an <b>int</b> value. This is a Boolean option.</dd>
|
|
|
|
<dt>SO_REUSEADDR</dt>
|
|
|
|
<dd>Reports whether 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 shall store an <b>int</b> value. This is a
|
|
Boolean option.</dd>
|
|
|
|
<dt>SO_KEEPALIVE</dt>
|
|
|
|
<dd>Reports whether connections are kept active with periodic transmission of messages, if this is supported by the protocol.
|
|
|
|
<p>If the connected socket fails to respond to these messages, the connection shall be broken and threads writing to that socket
|
|
shall be notified with a SIGPIPE signal. This option shall store an <b>int</b> value. This is a Boolean option.</p>
|
|
</dd>
|
|
|
|
<dt>SO_LINGER</dt>
|
|
|
|
<dd>Reports whether the socket lingers on <a href="../functions/close.html"><i>close</i>()</a> if data is present. If SO_LINGER is
|
|
set, the system blocks the process during <a href="../functions/close.html"><i>close</i>()</a> until it can transmit the data or
|
|
until the end of the interval indicated by the <i>l_linger</i> member, whichever comes first. 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 shall store a <b>linger</b> structure.</dd>
|
|
|
|
<dt>SO_OOBINLINE</dt>
|
|
|
|
<dd>Reports whether the socket leaves received out-of-band data (data marked urgent) inline. This option shall store an <b>int</b>
|
|
value. This is a Boolean option.</dd>
|
|
|
|
<dt>SO_SNDBUF</dt>
|
|
|
|
<dd>Reports send buffer size information. This option shall store an <b>int</b> value.</dd>
|
|
|
|
<dt>SO_RCVBUF</dt>
|
|
|
|
<dd>Reports receive buffer size information. This option shall store an <b>int</b> value.</dd>
|
|
|
|
<dt>SO_ERROR</dt>
|
|
|
|
<dd>Reports information about error status and clears it. This option shall store an <b>int</b> value.</dd>
|
|
|
|
<dt>SO_TYPE</dt>
|
|
|
|
<dd>Reports the socket type. This option shall store an <b>int</b> value. Socket types are described in <a href=
|
|
"xsh_chap02_10.html#tag_02_10_06"><i>Socket Types</i></a> .</dd>
|
|
|
|
<dt>SO_DONTROUTE</dt>
|
|
|
|
<dd>Reports whether 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 shall store an <b>int</b> value. This is a Boolean option.</dd>
|
|
|
|
<dt>SO_RCVLOWAT</dt>
|
|
|
|
<dd>Reports 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 shall store an
|
|
<b>int</b> value. Note that not all implementations allow this option to be retrieved.</dd>
|
|
|
|
<dt>SO_RCVTIMEO</dt>
|
|
|
|
<dd>Reports the timeout value for input operations. This option shall store 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 was received. The default for this option is zero, which indicates that a receive operation shall not time
|
|
out. Note that not all implementations allow this option to be retrieved.</dd>
|
|
|
|
<dt>SO_SNDLOWAT</dt>
|
|
|
|
<dd>Reports 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
|
|
shall store an <b>int</b> value. Note that not all implementations allow this option to be retrieved.</dd>
|
|
|
|
<dt>SO_SNDTIMEO</dt>
|
|
|
|
<dd>Reports 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 was sent. The default for this option is zero, which indicates that a send operation shall not
|
|
time out. The option shall store a <b>timeval</b> structure. Note that not all implementations allow this option to be
|
|
retrieved.</dd>
|
|
</dl>
|
|
|
|
<p>For Boolean options, a zero value indicates that the option is disabled and a non-zero value indicates that the option is
|
|
enabled.</p>
|
|
|
|
<p>Options at other protocol levels vary in format and name.</p>
|
|
|
|
<p>The socket in use may require the process to have appropriate privileges to use the <i>getsockopt</i>() function.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_252_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, <i>getsockopt</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_252_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>getsockopt</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>[EINVAL]</dt>
|
|
|
|
<dd>The specified option is invalid at the specified socket level.</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>getsockopt</i>() function may fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EACCES]</dt>
|
|
|
|
<dd>The calling process does not have the appropriate privileges.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The socket has been shut down.</dd>
|
|
|
|
<dt>[ENOBUFS]</dt>
|
|
|
|
<dd>Insufficient resources are available in the system to complete the function.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_252_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_252_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_252_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_252_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_252_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="bind.html"><i>bind</i>()</a> , <a href="close.html"><i>close</i>()</a> , <a href=
|
|
"endprotoent.html"><i>endprotoent</i>()</a> , <a href="setsockopt.html"><i>setsockopt</i>()</a> , <a href=
|
|
"socket.html"><i>socket</i>()</a> , the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/sys/socket.h.html"><i><sys/socket.h></i></a>, <a href=
|
|
"../basedefs/netinet/in.h.html"><i><netinet/in.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_252_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 6. Derived from the XNS, Issue 5.2 specification.</p>
|
|
|
|
<p>The <b>restrict</b> keyword is added to the <i>getsockopt</i>() prototype for alignment with the ISO/IEC 9899:1999
|
|
standard.</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>
|
|
|