t_optmgmt - Manage protocol options for a transport endpoint
#include <xti.h>
int t_optmgmt(
int fd,
struct t_optmgmt *req,
struct t_optmgmt *ret );
XTI Library (libxti.a)
Interfaces documented on this reference page conform to
industry standards as follows:
t_optmgmt(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
The following table summarizes the relevance of input and
output parameters before and after t_optmgmt() is called:
-------------------------------------------
Parameter Before Call After Call
-------------------------------------------
fd y n
req->opt.maxlen n n
req->opt.len y n
req->opt.buf y(y) n
req->options y n
ret->opt.maxlen y n
ret->opt.len n y
ret->opt.buf o (o)
ret->options n y
-------------------------------------------
Notes to Table: This a meaningful parameter. The content
of the object pointed to by y is meaningful. This is not
a meaningful parameter. This is an optional parameter.
The content of the object pointed to by o is optional.
Specifies a file descriptor returned by t_open() function
that identifies the local transport endpoint. The argument
req is used to request a specific action of the
provider and to send options to the provider. The argument
ret is used by the transport provider to return options
and option values to the user.
Both arguments point to a type t_optmgmt structure.
This structure is used to reserve space for a
transport-user options data buffer that stores
negotiable protocol options. The type t_optmgmt
structure has the following members: Specifies a
buffer for protocol options associated with the
referenced transport endpoint. The type netbuf
structure pointed to by this member is defined in
the xti.h include file. This structure, which is
used to define buffer parameters, has the following
members: For the req argument, this has no meaning.
For the ret argument, it specifies the maximum byte
length of the options buffer. For the req argument,
this specifies the number of bytes in the
options. For the ret argument, it specifies the
number of bytes of options returned. For the req
argument, this points to the options buffer. For
the ret argument, it points to the buffer where the
options are placed.
Each option in the options buffer is of the form
struct t_opthdr, possibly followed by an option
value. The t_opthdr structure, which is defined in
the xti.h file, has the following members: Contains
its total length (the length of the option header
t_opthdr plus the length of the option value).
Identifies the XTI level or a protocol of the
transport provider. Identifies the option within
the level. If t_optmgmt() is called with the
action T_NEGOTIATE set, the status field of the
returned options contains information about the
success or failure of the negotiation.
Each option in the input or output option buffer
must start at a longword boundary. The macro
OPT_NEXTHDR(pbuf, buflen, poption) can be used for
that purpose. This macro is defined in the xti.h
file.
If the transport user specifies several options on
input, all the options must address the same level.
If any option in the options buffer does not indicate
the same level as the first option, or the
level specified is unsupported, the t_optmgmt()
request will fail with the error [TBADOPT]. Some
options may have been successfully negotiated when
this error is detected. The transport user can
check the current status by calling t_optmgmt()
with the T_CURRENT option set. A longword (least
significant bit rightmost) that specifies the
response action that must be taken by a transport
provider when the t_optmgmt() function is processed.
The symbolic names for indicating various
actions are defined in the xti.h include file. The
flags field of req must specify one of the symbolic
names shown in the following table.
----------------------------------------------------------
Symbolic Name Meaning
----------------------------------------------------------
T_NEGOTIATE The transport user wants to negotiate the
values of the options stored in the
options buffer. In response, the transport
provider evaluates the options and
writes acceptable (negotiated) values to
the data buffer pointed to by
ret->opt.buf.
T_CHECK The transport user wants to verify that
the options specified in the data buffer
pointed to by req->opt.buf are supported
by the transport provider. On return, the
transport provider writes a ret->flags
value, which is either T_SUCCESS or
T_FAILURE.
T_DEFAULT The transport user wants to know what the
default options supported by the transport
provider are. The transport provider
writes default data into the options data
buffer pointed to by ret->opt.buf. The
req->opt.lenparameter must be set to 0
(zero). The req->opt.buf member may be
set to its null value.
T_CURRENT The transport user wants to retrieve the
currently effective option values, for
options specified in req->opt.buf. It is
sufficient to specify only the t_opthdr
part of an option. The currently effective
values are then returned in
ret->opt.buf.
----------------------------------------------------------
The option T_ALLOPT can only be used with t_optmgmt()
and the actions T_NEGOTIATE, T_DEFAULT, and
T_CURRENT. It can be used with any supported level,
and it addresses all supported options of this
level. The option has no value; it consists only
of a t_opthdr. In a t_optmgmt() call, only options
of one level may be addressed, so this option
should not be requested together with other
options. The function returns as soon as this
option has been processed.
Options are processed independently in the order
they appear in the input option buffer. If an
option is input multiple times, it may be output
multiple times or only once, depending on the
implementation.
If the transport provider is not able to provide an
interface that can support the T_NEGOTIATE or
T_CHECK functions, the error [TNOTSUPPORT] is
returned.
The t_optmgmt() XTI function is used in connectionless and
connection-oriented transport service. The t_optmgmt()
function associates specific optional parameters with a
bound transport endpoint previously defined by a file
descriptor returned by the t_open() function. The t_optmgmt()
function permits a transport user to retrieve, verify,
or negotiate desired options with a transport
provider.
A type t_optmgmt structure defined in the xti.h include
file is used to specify options.
If the t_optmgmt() function fails, t_errno may be set to
one of the following values: File descriptor fd does not
refer to a valid transport endpoint. This function was
called in the wrong sequence. The specified protocol
options are either of an incorrect format or contain illegal
information. The specified option is invalid. The
transport user does not have permission to negotiate the
specified options. The number of bytes allowed for an
incoming argument is not sufficient to store the value of
that argument. The information intended for the data
buffer pointed to by the ret parameter is discarded. A
system error occurred during execution of the t_optmgmt()
function. This function is not supported by the
underlying transport provider. This error indicates that
a communication problem has been detected between XTI and
the transport provider for which there is no other suitable
XTI (t_errno).
XTI-level options are not specific for a particular transport
provider. This operating system's XTI implementation
supports all of the options defined in this section.
The options described in this section are associationrelated.
They may be negotiated in all XTI states except
T_UNINIT.
The protocol level is XTI_GENERIC. The options defined for
this level are listed in the following table.
-----------------------------------------------------------------------
Option Name Type of Option Legal Option Meaning
Value Value
-----------------------------------------------------------------------
XTI_DEBUG array of unsigned See text enable debuglongs
ging
XTI_LINGER struct linger See text linger on close
if data is present
XTI_RCVBUF unsigned long size in octets receive buffer
size
XTI_RCVLOWAT unsigned long size in octets receive lowwater
mark
XTI_SNDBUF unsigned long size in octets send buffer
size
XTI_SNDLOWAT unsigned long size in octets send low-water
mark
-----------------------------------------------------------------------
A request for XTI_DEBUG is an absolute requirement. A
request to activate XTI_LINGER is also an absolute
requirement; the timeout value for this option is not.
XTI_RCVBUF, XTI_RCVLOWAT, XTI_SNDBUF, and XTI_SNDLOWAT are
not absolute requirements. This option controls debugging.
Debugging is disabled if the option is specified
with "no value", that is, with only an option header.
Tru64 UNIX accepts a single value for this option. A nonzero
value enables socket level debugging and a zero value
disables it.
The actual effects of the debugging depend upon the
underlying transport provider. For example, you
can set the XTI_DEBUG option for any transport endpoint
in the TCP/IP family. However, TCP is the
only protocol that looks at the option. trpt can
be used to report the trace records for TCP. Other
transport providers may supply utilities to process
the traces. The system supplies utilities to process
the traces. Lingers the execution of a
t_close() or close() if send data is still queued
in the send buffer. The option value specifies the
linger period. If a close() or a t_close() 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 transport, t_close() or close()
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 t_linger,
which is declared as shown here:
struct t_linger {
long l_onoff; /* switch option on/off */
long l_linger; /* linger period in seconds */ }
The value for l_onoff is an absolute requirement.
The legal values for this field are as follows:
switch option off activate option
The field l_linger 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; the value is often T_INFINITE. Legal values
for this field are as follows: T_UNSPEC,
T_INFINITE, and all non-negative numbers.
The l_linger value is not an absolute requirement.
The implementation may place upper and lower limits
on this value. Requests that fall short of the
lower limit are negotiated to the lower limit.
Note that this option does not linger the execution
of t_snddis(). Adjusts 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.
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.
Sets 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 poll() or select(),
indicates the data, and the data can be read by
t_rcv() or t_rcvdata().
Legal values for this field are all positive numbers.
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.
Adjusts the internal buffer size allocated for the
send buffer.
Legal values for this field are all positive numbers.
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.
Sets 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.
Legal values for this field are all positive numbers.
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.
The t_optmgmt() function can be called in all the transport
provider states, except T_UNINIT.
Upon successful completion, a value of 0 (zero) is
returned. Otherwise, a value of -1 is returned and
t_errno is set to indicate the error.
Functions: t_accept(3), t_alloc(3), t_connect(3), t_getinfo(3), t_listen(3), t_open(3), t_rcvconnect(3)
Standards: standards(5)
Network Programmer's Guide
t_optmgmt(3)
[ Back ] |
