Tribblix: manual page: t

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