T_OPTMGMT(3NSL)T_OPTMGMT(3NSL)NAMEt_optmgmt - manage options for a transport endpoint
SYNOPSIS
#include <xti.h>
int t_optmgmt(int fd, const struct t_optmgmt *req, struct t_optmgmt *ret);
DESCRIPTION
This routine is part of the XTI interfaces which evolved from the TLI
interfaces. XTI represents the future evolution of these interfaces.
However, TLI interfaces are supported for compatibility. When using a
TLI routine that has the same name as an XTI routine, the tiuser.h
header file must be used. Refer to the TLI COMPATIBILITY section for
a description of differences between the two interfaces.
The t_optmgmt() function enables a transport user to retrieve, verify
or negotiate protocol options with the transport provider. 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(3NSL). 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 possi‐
bly followed by an option value.
The level field of struct t_opthdr identifies the XTI level or a proto‐
col 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_NEXTHDR (nbp,tohp), T_OPT_DATA(tohp) are
provided for that purpose.
T_OPT_DATA(nhp)
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_NEXTHDR(nbp, tohp)
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(tohp)
If the argument is a pointer to a netbuf
structure associated with an option buf‐
fer, 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 unsup‐
ported, 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 call‐
ing 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 nego‐
tiated 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 negotia‐
tion. The value is T_SUCCESS if the pro‐
posed 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_NOTSUP‐
PORT 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 accord‐
ing to the order T_NOTSUPPORT, T_READ‐
ONLY, 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 can
be requested on input. No value is given
with this option; only the t_opthdr part
is specified. This input requests to nego‐
tiate 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 suc‐
cessful.
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 struc‐
ture), 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 cur‐
rent 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 irrele‐
vant 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 ille‐
gally 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 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 before the call. See
t_getinfo(3NSL) and t_open(3NSL).
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 specifiy the t_opthdr part
of an option only. The currently effective
values are then returned in req→opt.buf.
The status field returned is T_NOTSUPPORT
if the protocol level does not support
this option or the transport user ille‐
gally 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 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 buf‐
fer. 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 functionali‐
ties. 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 con‐
straints; 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 nego‐
tiations that have been done so far may
remain valid. The behavior of the function
is not changed if O_NONBLOCK is set.
RETURN VALUES
Upon successful completion, a value of 0 is returned. Otherwise, a
value of −1 is returned and t_errno is set to indicate an error.
VALID STATES
ALL - apart from T_UNINIT.
ERRORS
On failure, t_errno is set to one of the following:
TBADF
The specified file descriptor does not refer to a trans‐
port 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.
TLI COMPATIBILITY
The XTI and TLI interface definitions have common names but use differ‐
ent header files. This, and other semantic differences between the two
interfaces are described in the subsections below.
Interface Header
The XTI interfaces use the header file, xti.h. TLI interfaces should
not use this header. They should use the header:
#include <tiuser.h>
Error Description Values
The t_errno value TPROTO can be set by the XTI interface but not by the
TLI interface.
The t_errno values that this routine can return under different circum‐
stances than its XTI counterpart are TACCES and TBUFOVFLW.
TACCES
can be returned to indicate that the user does not have
permission to negotiate the specified options.
TBUFOVFLW
can be returned even when the maxlen field of the corre‐
sponding buffer has been set to zero.
Option Buffers
The format of the options in an opt buffer is dictated by the transport
provider. Unlike the XTI interface, the TLI interface does not fix the
buffer format. The macros T_OPT_DATA, T_OPT_NEXTHDR, and T_OPT_FIRSTHDR
described for XTI are not available for use by TLI interfaces.
Actions
The semantic meaning of various action values for the flags field of
req differs between the TLI and XTI interfaces. TLI interface users
should heed the following descriptions of the actions:
T_NEGOTIATE
This action enables the user to negotiate the values of
the options specified in req with the transport
provider. The provider will evaluate the requested
options and negotiate the values, returning the negoti‐
ated values through ret.
T_CHECK
This action enables the user to verify whether the
options specified in req are supported by the transport
provider. On return, the flags field of ret will have
either T_SUCCESS or T_FAILURE set to indicate to the
user whether the options are supported. These flags are
only meaningful for the T_CHECK request.
T_DEFAULT
This action enables a user to retrieve the default
options supported by the transport provider into the
opt field of ret. In req, the len field of opt must be
zero and the buf field may be NULL.
Connectionless Mode
If issued as part of the connectionless mode service, t_optmgmt() may
block due to flow control constraints. The function will not complete
until the transport provider has processed all previously sent data
units.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌───────────────┬─────────────────┐
│ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├───────────────┼─────────────────┤
│MT Level │ Safe │
└───────────────┴─────────────────┘
SEE ALSOclose(2), poll(2), select(3C), t_accept(3NSL), t_alloc(3NSL),
t_bind(3NSL), t_close(3NSL), t_connect(3NSL), t_getinfo(3NSL), t_lis‐
ten(3NSL), t_open(3NSL), t_rcv(3NSL), t_rcvconnect(3NSL), t_rcvu‐
data(3NSL), t_snddis(3NSL), attributes(5)
May 7, 1998 T_OPTMGMT(3NSL)
