socklib.html

Vxworks API操作系统和驱动程序设计API。压缩的HTML文件

    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine receives a message from a datagram socket.  It may be used in
place of <b><a href="./sockLib.html#recvfrom">recvfrom</a>(&nbsp;)</b> to decrease the overhead of breaking down the
message-header structure <b>msghdr</b> for each message.
<p>
For BSD 4.4 sockets a copy of the <i>mp</i>->msg_iov array will be made.  This
requires a cluster from the network stack system pool of size 
<i>mp</i>->msg_iovlen * sizeof (struct iovec) or 8 bytes. 
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
The number of bytes received, or ERROR if the call fails.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./sockLib.html#top">sockLib</a></b>

<hr>
<a name="setsockopt"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>setsockopt(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>setsockopt(&nbsp;)</strong> - set socket options</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS setsockopt
    (
    int    s,                 /* target socket */
    int    level,             /* protocol level of option */
    int    optname,           /* option name */
    char * optval,            /* pointer to option value */
    int    optlen             /* option length */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine sets the options associated with a socket.
To manipulate options at the "socket" level, <i>level</i> should be <b>SOL_SOCKET</b>.
Any other levels should use the appropriate protocol number.
<p>
</blockquote><h4>OPTIONS FOR STREAM SOCKETS</h4><blockquote><p>
The following sections discuss the socket options available for
stream (TCP) sockets.
<p>
</blockQuote><h4>SO_KEEPALIVE -- Detecting a Dead Connection</h4><blockQuote>
Specify the <b>SO_KEEPALIVE</b> option to make the transport protocol (TCP)
initiate a timer to detect a dead connection:
<pre>    setsockopt (sock, SOL_SOCKET, SO_KEEPALIVE, &amp;optval, sizeof (optval));
</pre>
This prevents an application from  hanging on an invalid connection.
The value at <i>optval</i> for this option is an integer (type <b>int</b>),
either 1 (on) or 0 (off).
<p>
The integrity of a connection is verified by transmitting
zero-length TCP segments triggered by a timer, to force a response
from a peer node.  If the peer does not respond after repeated
transmissions of the KEEPALIVE segments, the connection is dropped,
all protocol data structures are reclaimed, and processes sleeping
on the connection are awakened with an ETIMEDOUT error.
<p>
The ETIMEDOUT timeout can happen in two ways.  If the connection is
not yet established, the KEEPALIVE timer expires after idling
for <b>TCPTV_KEEP_INIT</b>.  If the connection is established, the
KEEPALIVE timer starts up when there is no traffic for
<b>TCPTV_KEEP_IDLE</b>.  If no response is received from the peer after
sending the KEEPALIVE segment <b>TCPTV_KEEPCNT</b> times with interval
<b>TCPTV_KEEPINTVL</b>, TCP assumes that the connection is invalid.
The <b>TCPTV_KEEP_INIT</b>, <b>TCPTV_KEEP_IDLE</b>, <b>TCPTV_KEEPCNT</b>, and <b>TCPTV_KEEPINTVL</b> 
parameters are defined in the file <b>target/h/netinet/tcp_timer.h</b>.
<p>
</blockQuote><h4>SO_LINGER -- Closing a Connection</h4><blockQuote>
Specify the <b>SO_LINGER</b> option to determine whether TCP should perform a
"graceful" close:
<pre>    setsockopt (sock, SOL_SOCKET, SO_LINGER, &amp;optval, sizeof (optval));
</pre>
To achieve a "graceful" close in response to the shutdown of a connection,
TCP puts itself through an elaborate set of state transitions.  The goal is 
to assure that all the unacknowledged data in the transmission channel are 
acknowledged, and that the peer is shut down properly.
<p>
The value at <i>optval</i> indicates the amount of time to linger if
there is unacknowledged data, using <b>struct linger</b> in
<b>target/h/sys/socket.h</b>.  The <b>linger</b> structure has two members:
<b>l_onoff</b> and <b>l_linger</b>.  <b>l_onoff</b> can be set to 1 to turn on the
<b>SO_LINGER</b> option, or set to 0 to turn off the <b>SO_LINGER</b> option.
<b>l_linger</b> indicates the amount of time to linger.  If <b>l_onoff</b> is
turned on and <b>l_linger</b> is set to 0, a default value <b>TCP_LINGERTIME</b>
(specified in <b>netinet/tcp_timer.h</b>) is used for incoming
connections accepted on the socket.
<p>
When <b>SO_LINGER</b> is turned on and the <b>l_linger</b> field is set to 0,
TCP simply drops the connection by sending out an RST (if a
connection is already established).  This frees up the space for the TCP
protocol control block, and wakes up all tasks sleeping on the
socket.
<p>
For the client side socket, the value of <b>l_linger</b> is not changed
if it is set to 0.  To make sure that the value of <b>l_linger</b> is 0
on a newly accepted socket connection, issue another <b><a href="./sockLib.html#setsockopt">setsockopt</a>(&nbsp;)</b>
after the <b><a href="./sockLib.html#accept">accept</a>(&nbsp;)</b> call.
<p>
Currently the exact value of <b>l_linger</b> time is actually ignored
(other than checking for 0); that is, TCP performs the state
transitions if <b>l_linger</b> is not 0, but does not explicitly use its
value.
<p>
</blockQuote><h4>TCP_NODELAY -- Delivering Messages Immediately</h4><blockQuote>
Specify the <b>TCP_NODELAY</b> option for real-time protocols, such as the X
Window System Protocol, that require immediate delivery of many small
messages:
<pre>setsockopt (sock, IPPROTO_TCP, TCP_NODELAY, &amp;optval, sizeof (optval));
</pre>
The value at <i>optval</i> is an integer (type <b>int</b>) set to either 1
(on) or 0 (off).
<p>
By default, the VxWorks TCP implementation employs an algorithm that
attempts to avoid the congestion that can be produced by a large number
of small TCP segments. This typically arises with virtual terminal
applications (such as telnet or rlogin) across networks that have
low bandwidth and long delays.  The algorithm attempts to have no
more than one outstanding unacknowledged segment in the transmission
channel while queueing up the rest of the smaller segments for later
transmission.  Another segment is sent only if enough new data is
available to make up a maximum sized segment, or if the outstanding
data is acknowledged.
<p>
This congestion-avoidance algorithm works well for virtual terminal
protocols and bulk data transfer protocols such as FTP without any
noticeable side effects.  However, real-time protocols that require
immediate delivery of many small messages, such as the X Window
System Protocol, need to defeat this facility to guarantee proper
responsiveness in their operation.
<p>
<b>TCP_NODELAY</b> is a mechanism to turn off the use of this algorithm.
If this option is turned on and there is data to be sent out, TCP
bypasses the congestion-avoidance algorithm: any available data
segments are sent out if there is enough space in the send window.
<p>
</blockQuote><h4>TCP_MAXSEG -- Changing TCP MSS for the connection</h4><blockQuote>
Specify the <b>TCP_MAXSEG</b> option to decrease the maximum allowable size of an
outgoing TCP segment. This option cannot be used to increase the MSS.
<pre>setsockopt (sock, IPPROTO_TCP, TCP_MAXSEG, &amp;optval, sizeof (optval));
</pre>
The value at <i>optval</i> is an integer set to the desired MSS (eg. 1024).
<p>
When a TCP socket is created, the MSS is initialized to the default MSS
value which is determined by the configuration parameter <b>TCP_MSS_DFLT</b> (512
by default). When a connection request is received from the other end with
an MSS option, the MSS is modified depending on the value of the received
MSS and on the results of Path MTU Discovery (which is enabled by default). 
The MSS may be set as high as the outgoing interface MTU (1460 for an 
Ethernet). Therefore, after a call to <b>socket</b> but before a connection is 
established, an application can only decrease the MSS from its default of 512. 
After a connection is established, the application can decrease the MSS from 
whatever value was selected.
<p>
</blockQuote><h4>SO_DEBUG -- Debugging the  underlying protocol</h4><blockQuote>
Specify the <b>SO_DEBUG</b> option to let the underlying protocol module record
debug information.
<pre>    setsockopt (sock, SOL_SOCKET, SO_DEBUG, &amp;optval, sizeof (optval));
</pre>
The value at <i>optval</i> for this option is an integer (type <b>int</b>),
either 1 (on) or 0 (off).
<p>
</blockquote><h4>OPTION FOR DATAGRAM SOCKETS</h4><blockquote><p>
The following section discusses an option for datagram (UDP) sockets.
<p>
</blockQuote><h4>SO_BROADCAST -- Sending to Multiple Destinations</h4><blockQuote>
Specify the <b>SO_BROADCAST</b> option when an application needs to send
data to more than one destination:
<pre>    setsockopt (sock, SOL_SOCKET, SO_BROADCAST, &amp;optval, sizeof (optval));
</pre>
The value at <i>optval</i> is an integer (type <i>int</i>), either 1 (on) or 0
(off).
<p>
</blockquote><h4>OPTIONS FOR DATAGRAM AND RAW SOCKETS</h4><blockquote><p>
The following section discusses options for multicasting on UDP and RAW
sockets.
<p>
</blockQuote><h4>IP_ADD_MEMBERSHIP -- Join a Multicast Group</h4><blockQuote>
Specify the <b>IP_ADD_MEMBERSHIP</b> option when a process needs to join
multicast group:
<pre>    setsockopt (sock, IPPROTO_IP, IP_ADD_MEMBERSHIP, (char *)&amp;ipMreq,
                sizeof (ipMreq));
</pre>
The value of <i>ipMreq</i> is an <b>ip_mreq</b> structure. 
<b>ipMreq.imr_multiaddr.s_addr</b> is the internet multicast address
<b>ipMreq.imr_interface.s_addr</b> is the internet unicast address of the 
interface through which the multicast packet needs to pass.
<p>
</blockQuote><h4>IP_DROP_MEMBERSHIP -- Leave a Multicast Group</h4><blockQuote>
Specify the <b>IP_DROP_MEMBERSHIP</b> option when a process needs to leave
a previously joined multicast group:
<pre>    setsockopt (sock, IPPROTO_IP, IP_DROP_MEMBERSHIP, (char *)&amp;ipMreq,
                sizeof (ipMreq));
</pre>
The value of <i>ipMreq</i> is an <b>ip_mreq</b> structure.  
<b>ipMreq.imr_multiaddr.s_addr</b> is the internet multicast address.
<b>ipMreq.imr_interface.s_addr</b> is the internet unicast address of the 
interface to which the multicast address was bound.
<p>
</blockQuote><h4>IP_MULTICAST_IF -- Select a Default Interface for Outgoing Multicasts</h4><blockQuote>
Specify the <b>IP_MULTICAST_IF</b> option when an application needs to specify
an outgoing network interface through which all multicast packets
are sent:
<pre>    setsockopt (sock, IPPROTO_IP, IP_MULTICAST_IF, (char *)&amp;ifAddr,
                sizeof (mCastAddr));
</pre>
The value of <i>ifAddr</i> is an <b>in_addr</b> structure.  
<b>ifAddr.s_addr</b> is the internet network interface address.
<p>
</blockQuote><h4>IP_MULTICAST_TTL -- Select a Default TTL</h4><blockQuote>
Specify the <b>IP_MULTICAST_TTL</b> option when an application needs to select
a default TTL (time to live) for outgoing multicast
packets:
<p>
<pre>    setsockopt (sock, IPPROTO_IP, IP_MULTICAST_TTL, &amp;optval, sizeof(optval));
</pre>
The value at <i>optval</i> is an integer (type <i>int</i>), time to live value.
<p>
<table>
<tr valign=top>
<th align=left>optval(TTL)  </th><th align=left>  Application                   </th><th align=left> Scope</tr>
<tr><td colspan="3"><hr></tr>
<tr valign=top>
<td align=left>0            </td><td align=left>                                </td><td align=left> same interface</tr>
<tr valign=top>
<td align=left>1            </td><td align=left>                                </td><td align=left> same subnet</tr>
<tr valign=top>
<td align=left>31           </td><td align=left> local event video              </td><td align=left> </tr>
<tr valign=top>
<td align=left>32           </td><td align=left>                                </td><td align=left> same site</tr>
<tr valign=top>
<td align=left>63           </td><td align=left> local event audio              </td><td align=left> </tr>
<tr valign=top>
<td align=left>64           </td><td align=left>                                </td><td align=left> same region</tr>
<tr valign=top>
<td align=left>95           </td><td align=left> IETF channel 2 video           </td><td align=left> </tr>
<tr valign=top>
<td align=left>127          </td><td align=left> IETF channel 1 video           </td><td align=left> </tr>
<tr valign=top>
<td align=left>128          </td><td align=left>                                </td><td align=left> same continent</tr>
<tr valign=top>
<td align=left>159          </td><td align=left> IETF channel 2 audio           </td><td align=left> </tr>
<tr valign=top>
<td align=left>191          </td><td align=left> IETF channel 1 audio           </td><td align=left> </tr>
<tr valign=top>
<td align=left>223          </td><td align=left> IETF channel 2 low-rate audio  </td><td align=left> </tr>
<tr valign=top>
<td align=left>255          </td><td align=left> IETF channel 1 low-rate audio  </td><td align=left></tr>
<tr valign=top>
<td align=left>             </td><td align=left> unrestricted in scope          </td><td align=left></tr>
<tr valign=top>
<td align=left></tr>
</tr>

</table>

</blockQuote><h4>IP_MULTICAST_LOOP -- Enable or Disable Loopback</h4><blockQuote>
Enable or disable loopback of outgoing multicasts.
<pre>    setsockopt (sock, IPPROTO_IP, IP_MULTICAST_LOOP, &amp;optval, sizeof(optval));
</pre>
The value at <i>optval</i> is an integer (type <i>int</i>), either 1(on) or 0
(off).
<p>
</blockquote><h4>OPTIONS FOR DATAGRAM, STREAM AND RAW SOCKETS</h4><blockquote><p>
The following section discusses options for RAW, DGRAM or STREAM
sockets.
<p>
</blockQuote><h4>IP_OPTIONS -- set options to be included in outgoing datagrams</h4><blockQuote>
Sets the IP options sent from this socket with every packet.
<pre>    setsockopt (sock, IPPROTO_IP, IP_OPTIONS, optbuf, optbuflen);
</pre>
Here <i>optbuf</i> is a buffer containing the options.
<p>
</blockQuote><h4>IP_TOS-- set options to be included in outgoing datagrams</h4><blockQuote>
Sets the Type-Of-Service field for each packet sent from this socket.
<pre>    setsockopt (sock, IPPROTO_IP, IP_TOS, &amp;optval, sizeof(optval));
</pre>
Here <i>optval</i> is an integer (type <i>int</i>).  This integer can be set to
<b>IPTOS_LOWDELAY</b>, <b>IPTOS_THROUGHPUT</b>, <b>IPTOS_RELIABILITY</b>, or <b>IPTOS_MINCOST</b>,
to indicate how the packets sent on this socket should be prioritized.
<p>