Networking Services Library Functions toptmgmt(3NSL)
NAME
toptmgmt - manage options for a transport endpoint
SYNOPSIS
#include
int toptmgmt(int fd, const struct toptmgmt *req, struct toptmgmt *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 toptmgmt() 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 toptmgmt structure
containing the following members:
struct netbuf opt;
tscalart 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 tbind(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 argu-
ment. 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
SunOS 5.11 Last change: 7 May 1998 1
Networking Services Library Functions toptmgmt(3NSL)
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
topthdr possibly followed by an option value.
The level field of struct topthdr 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
topthdr plus the length of the option value. If
toptmgmt() is called with the action TNEGOTIATE 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
TOPTFIRSTHDR(nbp), TOPTNEXTHDR (nbp,tohp),
TOPTDATA(tohp) are provided for that purpose.
TOPTDATA(nhp) If argument is a pointer to a
topthdr structure, this macro
returns an unsigned character
pointer to the data associated
with the topthdr.
TOPTNEXTHDR(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 topthdr structure
within that option buffer, this
macro returns a pointer to the
next topthdr structure or a
null pointer if this topthdr
is the last topthdr in the
option buffer.
TOPTFIRSTHDR(tohp) If the argument is a pointer to
a netbuf structure associated
with an option buffer, this
macro returns the pointer to
the first topthdr structure in
the associated option buffer,
SunOS 5.11 Last change: 7 May 1998 2
Networking Services Library Functions toptmgmt(3NSL)
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.
TOPTFIRSTHDR is useful for
finding an appropriately
aligned start of the option
buffer. TOPTNEXTHDR is useful
for moving to the start of the
next appropriately aligned
option in the option buffer.
Note that OPTNEXTHDR is also
available for backward compati-
bility requirements.
TOPTDATA is useful for find-
ing the start of the data part
in the option buffer where the
contents of its values start on
an appropriately aligned boun-
dary.
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
toptmgmt() 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 toptmgmt() with the
TCURENT flag set.
The flags field of req must
specify one of the following
actions:
TNEGOTIATE This action enables the tran-
sport user to negotiate option
values.
SunOS 5.11 Last change: 7 May 1998 3
Networking Services Library Functions toptmgmt(3NSL)
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 TSUCES if the pro-
posed value was negotiated,
TPARTSUCES if a degraded
value was negotiated,
TFAILURE if the negotiation
failed (according to the nego-
tiation rules), TNOTSUPORT
if the transport provider does
not support this option or
illegally requests negotiation
of a privileged option, and
TREADONLY if modification of a
read-only option was requested.
If the status is TSUCES,
TFAILURE, TNOTSUPORT or
TREADONLY, the returned option
value is the same as the one
requested on input.
The overall result of the nego-
tiation is returned in
ret->flags.
This field contains the worst
single result, whereby the rat-
ing is done according to the
order TNOTSUPORT,
TREADONLY, TFAILURE,
TPARTSUCES, TSUCES. The
value TNOTSUPORT is the
worst result and TSUCES is
the best.
For each level, the option
TALOPT can be requested on
input. No value is given with
this option; only the topthdr
part is specified. This input
requests to negotiate all sup-
ported options of this level to
their default values. The
result is returned option by
SunOS 5.11 Last change: 7 May 1998 4
Networking Services Library Functions toptmgmt(3NSL)
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 success-
ful.
TCHECK 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 topthdr structure), the
option is returned with its
status field set to TSUCES
if it is supported,
TNOTSUPORT if it is not or
needs additional user
privileges, and TREADONLY 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 TNEGOTIATE.
If the status is TSUCES,
TFAILURE, TNOTSUPORT or
TREADONLY, 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 rat-
ing is the same as for
TNEGOTIATE .
Note that no negotiation takes
place. All currently effective
option values remain unchanged.
TDEFAULT This action enables the tran-
sport user to retrieve the
SunOS 5.11 Last change: 7 May 1998 5
Networking Services Library Functions toptmgmt(3NSL)
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 suf-
ficient to specify the topthdr
part of an option only. The
default values are then
returned in ret->opt.buf.
The status field returned is
TNOTSUPORT if the protocol
level does not support this
option or the transport user
illegally requested a
privileged option, TREADONLY
if the option is read-only, and
set to TSUCES 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 TNEGOTIATE.
For each level, the option
TALOPT 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 tgetinfo(3NSL) and
topen(3NSL).
TCURENT This action enables the tran-
sport 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 topthdr part of
an option only. The currently
effective values are then
returned in req->opt.buf.
The status field returned is
TNOTSUPORT if the protocol
SunOS 5.11 Last change: 7 May 1998 6
Networking Services Library Functions toptmgmt(3NSL)
level does not support this
option or the transport user
illegally requested a
privileged option, TREADONLY
if the option is read-only, and
set to TSUCES 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 TNEGOTIATE.
For each level, the option
TALOPT can be requested on
input. All supported options of
this level with their currently
effective values are then
returned.
The option TALOPT can only
be used with toptmgmt() and
the actions TNEGOTIATE,
TDEFAULT and TCURENT. It
can be used with any supported
level and addresses all sup-
ported options of this level.
The option has no value; it
consists of a topthdr only.
Since in a toptmgmt() 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 pro-
cessed 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
TNEGOTIATE and/or TCHECK
functionalities. When this is
the case, the error TNOTSUPORT
SunOS 5.11 Last change: 7 May 1998 7
Networking Services Library Functions toptmgmt(3NSL)
is returned.
The function toptmgmt() may
block under various cir-
cumstances and depending on the
implementation. The function
will block, for instance, if
the protocol addressed by the
call resides on a separate con-
troller. It may also block due
to flow control constraints;
that is, if data sent previ-
ously 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
ONONBLOCK is set.
RETURN VALUES
Upon successful completion, a value of 0 is returned. Oth-
erwise, a value of -1 is returned and terrno is set to
indicate an error.
VALID STATES
AL - apart from TUNINIT.
ERORS
On failure, terrno 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 argu-
ment. The information to be returned in ret
will be discarded.
SunOS 5.11 Last change: 7 May 1998 8
Networking Services Library Functions toptmgmt(3NSL)
TNOTSUPORT 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 (terrno).
TSYSER 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 differ-
ences between the two interfaces are described in the sub-
sections below.
Interface Header
The XTI interfaces use the header file, xti.h. TLI inter-
faces should not use this header. They should use the
header:
#include
Error Description Values
The terrno value TPROTO can be set by the XTI interface but
not by the TLI interface.
The terrno values that this routine can return under dif-
ferent circumstances than its XTI counterpart are TACES and
TBUFOVFLW.
TACES 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.
SunOS 5.11 Last change: 7 May 1998 9
Networking Services Library Functions toptmgmt(3NSL)
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
TOPTDATA, TOPTNEXTHDR, and TOPTFIRSTHDR 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:
TNEGOTIATE 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 nego-
tiated values through ret.
TCHECK 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 TSUCES or TFAILURE set to indi-
cate to the user whether the options are
supported. These flags are only meaningful
for the TCHECK request.
TDEFAULT 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 NUL.
Connectionless Mode
If issued as part of the connectionless mode service,
toptmgmt() may block due to flow control constraints. The
function will not complete until the transport provider has
processed all previously sent data units.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 7 May 1998 10
Networking Services Library Functions toptmgmt(3NSL)
ATRIBUTE TYPE ATRIBUTE VALUE
MT Level Safe
SEE ALSO
close(2), poll(2), select(3C), taccept(3NSL),
talloc(3NSL), tbind(3NSL), tclose(3NSL), tconnect(3NSL),
tgetinfo(3NSL), tlisten(3NSL), topen(3NSL), trcv(3NSL),
trcvconnect(3NSL), trcvudata(3NSL), tsnddis(3NSL), attri-
butes(5)
SunOS 5.11 Last change: 7 May 1998 11
|
