T_OPTMGMT(3NSL) Networking Services Library Functions T_OPTMGMT(3NSL)
NAME
t_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 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_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 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 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 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 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 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 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
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.
TLI COMPATIBILITY
The
XTI and
TLI interface definitions have common names but use different
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
circumstances 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
corresponding 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 negotiated 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(7) for descriptions of the following attributes:
+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT Level | Safe |
+---------------+-----------------+
SEE ALSO
close(2),
poll(2),
select(3C),
t_accept(3NSL),
t_alloc(3NSL),
t_bind(3NSL),
t_close(3NSL),
t_connect(3NSL),
t_getinfo(3NSL),
t_listen(3NSL),
t_open(3NSL),
t_rcv(3NSL),
t_rcvconnect(3NSL),
t_rcvudata(3NSL),
t_snddis(3NSL),
attributes(7) May 7, 1998
T_OPTMGMT(3NSL)