t_optmgmt.html

unix 下的C开发手册,还用详细的例程。

All supported options of this level with their default values are then
returned.
In this case,
<I>ret-&gt;opt.maxlen</I>
must be given at least the value
<I>info-&gt;options</I>
(see
<i><a href="t_getinfo.html">t_getinfo()</a></i>,
<i><a href="t_open.html">t_open()</a></i>)
before the call.

<dt>T_CURRENT<dd>This action enables the transport user to retrieve the currently effective
option values.
The user specifies the options of interest in
<I>req-&gt;opt.buf</I>.
The option values are irrelevant and will be ignored;
it is sufficient to specify the
<B>t_opthdr</B>
part of an option only.
The currently effective values are then returned in
<I>ret-&gt;opt.buf</I>.

The <I>status</I> field returned is T_NOTSUPPORT if the protocol
level does not support this option or the transport user illegally
requested a privileged option, T_READONLY if the option is read-only,
and set to T_SUCCESS in all other cases.
The overall result of the request is returned in
<I>ret-&gt;flags</I>.
This field contains the worst single result, whereby the rating is the
same as for T_NEGOTIATE.

For each level, the option T_ALLOPT (see below) can be requested on input.
All supported options of this level with their currently effective
values are then returned.

</dl>
<p>
The option T_ALLOPT can only be used with
<i>t_optmgmt()</i>
and the actions T_NEGOTIATE, T_DEFAULT and T_CURRENT.  It can be used with any
supported level and addresses all supported options of this level.  The option
has no value; it consists of a
<B>t_opthdr</B>
only.  Since in a
<i>t_optmgmt()</i>
call only options of one level may be addressed, this option should not be
requested together with other options.
The function returns as soon as this option has been processed.
<p>
Options are independently processed in the order they appear in the input
option buffer.
If an option is multiply input, it depends on the implementation
whether it is multiply output or whether it is returned only once.
<p>
Transport providers may not be able to provide an interface
capable of supporting T_NEGOTIATE and/or T_CHECK functionalities.
When this is the case, the error [TNOTSUPPORT] is returned.
<p>
The function
<i>t_optmgmt()</i>
may block under various circumstances
and depending on the implementation.
The function will block, for instance, if the protocol addressed by
the call resides on a separate controller.
It may also block due to flow control constraints; that is, if data
sent previously across this transport endpoint has not yet been fully
processed.
If the function is interrupted by a signal, the option negotiations
that have been done so far may remain valid.
The behaviour of the function is not changed if O_NONBLOCK is set.
</blockquote><h4>XTI-LEVEL OPTIONS</h4><blockquote>
XTI-level options are not specific for a particular transport provider.
An XTI implementation supports none, all or any subset of the options
defined below.
An implementation may restrict the use of any of these options by
offering them only in the privileged or read-only mode,
or if
<I>fd</I>
relates to specific transport providers.
<p>
The subsequent options do not have end-to-end significance
(see 
<xref href=xtioptions></xref>).
They may be negotiated in all XTI states except T_UNINIT.
<br>
<p>
The protocol level is XTI_GENERIC.
For this level, the following options are defined:
<P><table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>option name</b>
<th align=center><b>type of option</b>
<th align=center><b>legal</b>
<th align=center><b>meaning</b>
<tr valign=top><th align=center><b></b>
<th align=center><b>value</b>
<th align=center><b>option value</b>
<th align=center><b></b>
<tr valign=top><td align=left>XTI_DEBUG
<td align=left>array of t_uscalar_t
<td align=left>see text
<td align=left>enable debugging
<tr valign=top><td align=left>XTI_LINGER
<td align=left>struct t_linger
<td align=left>see text
<td align=left> linger on close if data is present 
<tr valign=top><td align=left>XTI_RCVBUF
<td align=left>t_uscalar_t
<td align=left>size in octets
<td align=left>receive buffer size
<tr valign=top><td align=left>XTI_RCVLOWAT
<td align=left>t_uscalar_t
<td align=left>size in octets
<td align=left>receive low-water mark
<tr valign=top><td align=left>XTI_SNDBUF
<td align=left>t_uscalar_t
<td align=left>size in octets
<td align=left>send buffer size
<tr valign=top><td align=left>XTI_SNDLOWAT
<td align=left>t_uscalar_t
<td align=left>size in octets
<td align=left>send low-water mark
</table>
<h6 align=center><xref table="XTI-level Options"></xref>Table: XTI-level Options</h6>
<p>
A request for XTI_DEBUG is an absolute requirement.
A request to activate XTI_LINGER is an absolute requirement;
the timeout value to this option is not.
XTI_RCVBUF, XTI_RCVLOWAT, XTI_SNDBUF and XTI_SNDLOWAT are not absolute
requirements.
<dl compact>

<dt>XTI_DEBUG<dd>This option enables debugging.
The values of this option are implementation-defined.
Debugging is disabled if the option is specified with &quot;no value&quot;;
that is, with an option header only.

The system supplies utilities to process the traces.
Note that an implementation may also provide other means for
debugging.

<dt>XTI_LINGER<dd>This option is used to linger the execution of a
<i><a href="t_close.html">t_close()</a></i>
or
<i><a href="close.html">close()</a></i>
if send data is still queued in the send buffer.
The option value specifies the linger period.
If a
<i><a href="close.html">close()</a></i>
or
<i><a href="t_close.html">t_close()</a></i>
is issued and the send buffer is not empty, the system attempts to send the
pending data within the linger period before closing the endpoint.  Data still
pending after the linger period has elapsed is discarded.

Depending on the implementation,
<i><a href="t_close.html">t_close()</a></i>
or
<i><a href="close.html">close()</a></i>
either block for at
maximum the linger period, or immediately return, whereupon the system holds
the connection in existence for at most the linger period.

The option value consists of a structure
<B>t_linger</B>
declared as:
<pre>
<code>
struct t_linger {
    t_scalar_t l_onoff;   /* switch option on/off     */
    t_scalar_t l_linger;  /* linger period in seconds */
}
</code>
</pre>


Legal values for the field
<I>l_onoff</I>
are:
<pre>
<dl compact><dt> <dd>
T_NO    switch option off
T_YES   activate option
</dl>
</pre>
<p>
The value
<I>l_onoff</I>
is an absolute requirement.
<p>
The field
<I>l_linger</I>
determines the linger period in seconds.
The transport user can request the default value by setting the field
to T_UNSPEC.
The default timeout value depends on the underlying transport provider
(it is often T_INFINITE).
Legal values for this field are
T_UNSPEC, T_INFINITE and all non-negative numbers.
<p>
The
<I>l_linger</I>
value is not an absolute requirement.
The implementation may place upper and lower limits to this value.
Requests that fall short of the lower
limit are negotiated to the lower limit.
<p>
Note that this option does not linger the execution of
<i><a href="t_snddis.html">t_snddis()</a></i>.
<p>
<dt>XTI_RCVBUF<dd>This option is used to adjust the internal buffer size allocated for the
receive buffer.
The buffer size may be increased for high-volume connections,
or decreased to limit the possible backlog of incoming data.
<p>
This request is not an absolute requirement.
The implementation may place upper and lower limits on the option value.
Requests that fall short of the lower limit are negotiated to the lower limit.
<p>
Legal values are all positive numbers.
<p>
<dt>XTI_RCVLOWAT<dd>This option is used to set a low-water mark in the receive buffer.
The option value gives the minimal number of bytes that must have
accumulated in the
receive buffer before they become visible to the transport user.
If and when the
amount of accumulated receive data exceeds the low-water mark, a T_DATA
event is created, an event mechanism (for example,
<i><a href="poll.html">poll()</a></i>
or
<i><a href="select.html">select()</a></i>)
indicates the data, and the data can be read by
<i><a href="t_rcv.html">t_rcv()</a></i>
or
<i><a href="t_rcvudata.html">t_rcvudata()</a></i>.
<p>
This request is not an absolute requirement.
The implementation may place upper and lower limits on the option value.
Requests that fall short of the lower limit are negotiated to the lower limit.
<p>
Legal values are all positive numbers.
<p>
<dt>XTI_SNDBUF<dd>This option is used to adjust the internal buffer size allocated for the
send buffer.
<p>
This request is not an absolute requirement.
The implementation may place upper and lower limits on the option value.
Requests that fall short of the lower limit are negotiated to the lower limit.
<p>
Legal values are all positive numbers.
<p>
<dt>XTI_SNDLOWAT<dd>This option is used to set a low-water mark in the send buffer.
The option
value gives the minimal number of bytes that must have accumulated in the
send buffer before they are sent.
<p>
This request is not an absolute requirement.
The implementation may place upper and lower limits on the option value.
Requests that fall short of the lower limit are negotiated to the lower limit.
<p>
Legal values are all positive numbers.
<p>
</dl>
</blockquote><h4>VALID STATES</h4><blockquote>
ALL - apart from T_UNINIT
</blockquote><h4>ERRORS</h4><blockquote>
On failure,
<I>t_errno</I>
is set to one of the following:
<dl compact>

<dt>[TBADF]<dd>The specified file descriptor does not refer to a transport endpoint.

<dt>[TBADFLAG]<dd>An invalid flag was specified.

<dt>[TBADOPT]<dd>The specified options were in an incorrect format or
contained illegal information.


<dt>[TBUFOVFLW]<dd>The number of bytes allowed for an incoming argument
<I>(maxlen)</I>
is greater than 0 but not sufficient to store the value of that argument.
The information to be returned in
<I>ret</I>
will be discarded.

<dt>[TNOTSUPPORT]<dd>This action is not supported by the transport provider.

<dt>[TOUTSTATE]<dd>The communications endpoint referenced by 
<I>fd</I>
is not in one of the states in which a call to this function is valid.

<dt>[TPROTO]<dd>This error indicates that a communication problem has been detected
between XTI and the transport provider for which there is no other
suitable XTI error
<I>(t_errno)</I>.

<dt>[TSYSERR]<dd>A system error has occurred during execution of this function.

</dl>
</blockquote><h4>RETURN VALUE</h4><blockquote>
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and
<I>t_errno</I>
is set to indicate an error.
</blockquote><h4>SEE ALSO</h4><blockquote>
<i><a href="t_accept.html">t_accept()</a></i>,
<i><a href="t_alloc.html">t_alloc()</a></i>,
<i><a href="t_connect.html">t_connect()</a></i>,
<i><a href="t_getinfo.html">t_getinfo()</a></i>,
<i><a href="t_listen.html">t_listen()</a></i>,
<i><a href="t_open.html">t_open()</a></i>,
<i><a href="t_rcvconnect.html">t_rcvconnect()</a></i>,
<xref href=chap5></xref>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>