The t_optmgmt() function enables a transport user to
retrieve, verify or negotiate protocol options with the transport
provider.
Parameters
Before call
After call
fd
x
/
req->opt.maxlen
=
=
req->opt.len
x
=
req->opt.buf
x (x)
=
req->flags
x
=
ret->opt.maxlen
x
=
ret->opt.len
/
x
ret->opt.buf
?
(?)
ret->flags
/
x
The argument fd identifies a transport endpoint. The
req and ret arguments point to a t_optmgmt structure
containing the following members:
struct netbuf opt;
t_scalar_t flags;
The opt field identifies protocol options and the
flags field is used to specify the action to take with those
options.
The options are represented by a netbuf structure in a manner
similar to the address in t_bind(). The argument req is used
to request a specific action of the provider and to send options to
the provider. The argument len specifies the number of bytes
in the options, buf points to the options buffer, and
maxlen has no meaning for the req argument. The
transport provider may return options and flag values to the user
through ret. For ret, maxlen specifies the
maximum size of the options buffer and buf points to the
buffer where the options are to be placed. If maxlen in
ret is set to zero, no options values are returned. On
return, len specifies the number of bytes of options
returned. The value in maxlen has no meaning for the
req argument, but must be set in the ret argument to
specify the maximum number of bytes the options buffer can
hold.
Each option in the options buffer is of the form struct t_opthdr
possibly followed by an option value.
The level field of struct t_opthdr identifies the XTI
level or a protocol of the transport provider. The name
field identifies the option within the level, and len
contains its total length; that is, the length of the option header
t_opthdr plus the length of the option value. 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 a negotiation.
Several options can be concatenated. The option user has,
however to ensure that each options header and value part starts at
a boundary appropriate for the architecture-specific alignment
rules. The macros T_OPT_FIRSTHDR(nbp), T_OPT_NXTHDR(nbp, tohp),
T_OPT_DATA(tohp) are provided for that purpose.
T_OPT_DATA
If argument is a pointer to a t_opthdr structure, this macro
returns an unsigned character pointer to the data associated with
the t_opthdr.
T_OPT_NXTHDR
If the first argument is a pointer to a netbuf structure
associated with an option buffer and second argument is a pointer
to a t_opthdr structure within that option buffer, this macro
returns a pointer to the next t_opthdr structure or a null pointer
if this t_opthdr is the last t_opthdr in the option buffer.
T_OPT_FIRSTHDR
If the argument is a pointer to a netbuf structure associated
with an option buffer, this macro returns the pointer to the first
t_opthdr structure in the associated option buffer, or a null
pointer if there is no option buffer associated with this netbuf or
if it is not possible or the associated option buffer is too small
to accommodate even the first aligned option header.
T_OPT_FIRSTHDR is useful for finding an appropriately aligned
start of the option buffer. T_OPT_NEXTHDR is useful for moving to
the start of the next appropriately aligned option in the option
buffer. Note that OPT_NEXTHDR is also available for backward
compatibility requirements. T_OPT_DATA is useful for finding the
start of the data part in the option buffer where the contents of
its values start on an appropriately aligned boundary.
If the transport user specifies several options on input, all
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,
then the t_optmgmt() request will fail with [TBADOPT]. If the error
is detected, some options have possibly been successfully
negotiated. The transport user can check the current status by
calling t_optmgmt() with the T_CURRENT flag set.
The flags field of req must specify one of the
following actions:
T_NEGOTIATE
This action enables the transport user to negotiate option
values. The user specifies the options of interest and their values
in the buffer specified by req->opt.buf and
req->opt.len. The negotiated option values are returned
in the buffer pointed to by ret->opt.buf. The
status field of each returned option is set to indicate the
result of the negotiation. The value is T_SUCCESS if the proposed
value was negotiated, T_PARTSUCCESS if a degraded value was
negotiated, T_FAILURE if the negotiation failed (according to the
negotiation rules), T_NOTSUPPORT if the transport provider does not
support this option or illegally requests negotiation of a
privileged option, and T_READONLY if modification of a read-only
option was requested. If the status is T_SUCCESS, T_FAILURE,
T_NOTSUPPORT or T_READONLY, the returned option value is the same
as the one requested on input. The overall result of the
negotiation is returned in ret->flags. This field
contains the worst single result, whereby the rating is done
according to the order T_NOTSUPPORT, T_READONLY, T_FAILURE,
T_PARTSUCCESS, T_SUCCESS. The value T_NOTSUPPORT is the worst
result and T_SUCCESS is the best. For each level, the option
T_ALLOPT (see below) can be requested on input. No value is given
with this option; only the t_opthdr part is specified. This input
requests to negotiate all supported options of this level to their
default values. The result is returned option by option in
ret->opt.buf. (Note that depending on the state of the
transport endpoint, not all requests to negotiate the default value
may be successful.)
T_CHECK
This action enables the user to verify whether the options
specified in req are supported by the transport provider. If
an option is specified with no option value (it consists only of a
t_opthdr structure), the option is returned with its status
field set to T_SUCCESS if it is supported, T_NOTSUPPORT if it is
not or needs additional user privileges, and T_READONLY if it is
read-only (in the current XTI state). No option value is returned.
If an option is specified with an option value, the status
field of the returned option has the same value, as if the user had
tried to negotiate this value with T_NEGOTIATE. If the status is
T_SUCCESS, T_FAILURE, T_NOTSUPPORT or T_READONLY, the returned
option value is the same as the one requested on input. The overall
result of the option checks is returned in ret->flags.
This field contains the worst single result of the option checks,
whereby the rating is the same as for T_NEGOTIATE. Note that no
negotiation takes place. All currently effective option values
remain unchanged.
T_DEFAULT
This action enables the transport user to retrieve the default
option values. The user specifies the options of interest in
req->opt.buf. The option values are irrelevant and will
be ignored; it is sufficient to specify the t_opthdr part of an
option only. The default values are then returned in
ret->opt.buf. The status 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
ret->flags. 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 default values are then
returned. In this case, ret->opt.maxlen must be given at
least the value info->options (see t_getinfo(3), t_open(3))
before the call.
T_CURRENT
This action enables the transport user to retrieve the
currently effective option values. The user specifies the options
of interest in req->opt.buf. The option values are
irrelevant and will be ignored; it is sufficient to specify the
t_opthdr part of an option only. The currently effective values are
then returned in ret->opt.buf. The status 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 ret->flags. 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.
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 addresses all supported options of
this level. The option has no value; it consists of a t_opthdr
only. Since in a t_optmgmt() 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.
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.
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.
The function t_optmgmt() 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.
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 fd relates to specific transport
providers.
The subsequent options do not have end-to-end significance. They
may be negotiated in all XTI states except T_UNINIT.
The protocol level is XTI_GENERIC. For this level, the following
options are defined:
option name
type of option value
legal option value
meaning
XTI_DEBUG
array of t_uscalar_t
see text
enable debugging
XTI_LINGER
struct t_linger
see text
linger on close if data is present
XTI_RCVBUF
t_uscalar_t
size in octets
receive buffer size
XTI_RCVLOWAT
t_uscalar_t
size in octets
receive low-water mark
XTI_SNDBUF
t_uscalar_t
size in octets
send buffer size
XTI_SNDLOWAT
t_uscalar_t
size in octets
send low-water mark
A request for XTI_DEBUG is an absolute requirement. A request to
activate XTI_LINGER is an absolute requirement; the time-out value
to this option is not. XTI_RCVBUF, XTI_RCVLOWAT, XTI_SNDBUF and
XTI_SNDLOWAT are not absolute requirements.
XTI_DEBUG
This option enables debugging. The values of this option are
implementation-defined. Debugging is disabled if the option is
specified with "no value"; 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.
XTI_LINGER
This option is used to linger the execution of a close(2) or
t_close(3) if send data is still queued in the
send buffer. The option value specifies the linger period. If a
close(2)
or t_close(3) 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, close(2) or t_close(3) 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 declared as:
struct t_linger {
t_scalar_t l_onoff; /* switch option on/off */
t_scalar_t l_linger; /* linger period in seconds */
}
Legal values for the field l_onoff are:
T_NO switch option off
T_YES activate option
The value l_onoff is an absolute requirement.
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 time-out 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.
The l_linger 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.
Note that this option does not linger the execution of t_snddis(3).
XTI_RCVBUF
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.
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.
Legal values are all positive numbers.
XTI_RCVLOWAT
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, poll() or
select(2)) indicates the data, and the data can
be read by t_rcv(3) or t_rcvudata(3). 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.
Legal values are all positive numbers.
XTI_SNDBUF
This option is used to adjust the internal buffer size
allocated for the send buffer. 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.
Legal values are all positive numbers.
XTI_SNDLOWAT
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. 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.
On failure, t_errno is set to one of the following:
[TBADF]
The specified file descriptor does not refer to a transport
endpoint.
[TBADFLAG]
An invalid flag was specified.
[TBADOPT]
The specified options were in an incorrect format or contained
illegal information.
[TBUFOVFLW]
The number of bytes allowed for an incoming argument
(maxlen) is greater than 0 but not sufficient to store the
value of that argument. The information to be returned in
ret will be discarded.
[TNOTSUPPORT]
This action is not supported by the transport provider.
[TOUTSTATE]
The communications endpoint referenced by fd is not in
one of the states in which a call to this function is valid.
[TPROTO]
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 (t_errno).
[TSYSERR]
A system error has occurred during execution of this
function.