t_optmgmt.3.man

This a separate release of the OpenSS7 X/Open XTI/TLI library, TLI modules (timod, tirdwr) and the I

.I req->opt.len
is zero; that is, no option buffer is specified on input, then all options
known to the transport service provider are selected.
.PP
The result of options processing is returned in the
.I ret->opt.buf
buffer and the
.I ret->flags
overall result flags.
If
.I ret->opt.len
is zero; that is, no option buffer is provided for return,
.I ret->flags
will be set as described below, but the returned options and their status will be
discarded.
If
.I ret
is specified as
.BR NULL ,
option processing will be performed as described below, however, the returned
options and flags will be discarded.
.PP
Options processing may abort and
.BR t_optmgmt ()
will return
.RB [ TBADOPT ]
if an illegal option or an option with an unknown level is ecountered.
An illegal option consists of any an option header that does not completely
fit within the remaining option buffer, has a length less than the option
header size, has a length that exceeds the option buffer boundaries, has a
value length that is illegal for the option, or has a value that is illegal
for the option.
.PP
If
.BR t_optmgmt ()
encounters an illegal option, option processing ceases and
.RB [ TBADOPT ]
is returned.
If
.BR t_optmgmt ()
encounters an option level that is unknown to the transport
provider, option processing ceases and
.RB [ TBADOPT ]
is returned.
If
.BR t_optmgmt ()
encounters an option level that is known to the transport provider, but
an option name that is not, it returns
.B T_NOTSUPPORT
in the
.I status
field of the returned option.
When option processing is aborted and the action is
.BR T_NEGOTIATE ,
some options may have been succesfully negotiated before options processing
was aborted.  These options will retain their negotiated values.  To determine
which options may have retained a negotiated value, use the
.B T_CURRENT
management flag.
.\"
.\"
.SS T_DEFAULT
The
.B T_DEFAULT
management flag
allows the transport user to retrieve the default option values.
.PP
The user specifies the options of interest in
.IR req->opt.buf .
The option values are irrelevant and will be ignored; it is sufficient to
specify the
.B t_opthdr
part of an option only.
For each level, the option
.B 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,
.I ret->opt.maxlen
must be given at least the value
.I info->options
(see
.BR t_getinfo "(3), " t_open (3))
before the call. 
If
.I req->opt.len
is zero; that is, an empty option buffer is specified, then the options
selected are all options known to the transport service provider.
.PP
The default values are then returned in
.IR ret->opt.buf .
The
.I status
field returned is
.B T_NOTSUPPORT
if the protocol level does not support this option or the transport user
illegally requested a privileged option,
.B T_READONLY
if the option is read-only, and set to
.B T_SUCCESS
in all other cases.
The overall result of the request is returned in
.IR ret->flags .
This field contains the worst single result, whereby the rating is the same as
for
.BR T_NEGOTIATE .
.\"
.\"
.SS T_CURRENT
The
.B T_CURRENT
management flag allows the transport user to retrieve the currently effective
option values.
.PP
The user specifies the options of interest in
.IR req->opt.buf .
The option values are irrelevant and will be ignored; it is sufficient to
specify the
.B t_opthdr
part of an option only.
For each level, the option
.B T_ALLOPT
(see below) can be requested on input.  All supported options of this level
with their currently effective values are then returned. 
If
.I req->opt.len
is zero; that is, an emtpy option buffer is specified, then the options
selected are all options known to the transport service provider.
.PP
The currently effective values are then returned in
.IR ret->opt.buf .
The
.I status
field returned is
.B T_NOTSUPPORT
if the protocol level does not support this option or the transport user
illegally requested a privileged option,
.B T_READONLY
if the option is read-only, and set to
.B T_SUCCESS
in all other cases.
The overall result of the request is returned in
.IR ret->flags .
This field contains the worst single result, whereby the rating is the same as
for
.BR T_NEGOTIATE .
.\"
.\"
.SS T_CHECK
The
.B T_CHECK
management flag
allows the user to verify whether the options specified in the
.B T_OPTMGMT_REQ
are supported by the transport provider.
.PP
The user specifies the options of interest in
.IR req->opt.buf .
The special option name
.B T_ALLOPT
cannot be used for
.B T_CHECK
and will generate a
.RB [ TBADOPT ]
error if specified.  Also, if
.I req->opt.len
is zero,
.BR [ TBADOPT ]
will be returned.
.PP
If an option is specified with no option value (it consists of only a
.B t_opthdr
structure), the option is returned with its
.I status
field set to
.B T_SUCCESS
if it is supported,
.B T_NOTSUPPORT
if it is not or needs additional user priviledges, and
.B T_READONLY
if it is read-only (in the current XTI/TLI state).  No option value is returned.
If an option is specified with an option value, the
.I status
field of the
returned option has the same value as if the user had tried to negotiate this
value with
.BR T_NEGOTIATE .
If the
.I status
is
.BR T_SUCCESS ", " T_FAILURE ", " T_NOTSUPPORT " or " T_READONLY ,
the returned option value is the same as the one requested on input. 
.\"
.\"
.SS T_NEGOTIATE
The
.B T_NEGOTIATE
management flag
allows the transport user to negotiate option values.
.PP
The user specifies the options of interest and their values in the
.BR T_OPTMGMT_REQ .
The negotiated option values are returned in the
.BR T_OPTMGMT_ACK .
For each level the option
.B T_ALLOPT
can be requested on input.  No value is given with this option; only the
.B t_opthdr
part is specified.  This input request to negotiate all supported options of
this level to their default values.  The result is returned option by option
in
.BR T_OPTMGMT_ACK .
(Note that depending on the state of the transport endpoint, not all requests
to negotiate the default value may be successful.) 
If
.I req->opt.len
is zero; that is, an empty option buffer is specified, then the options
selected for negotation are all options known to the transport provider.  This
will initiate a negotiation of all options to their default values.
.PP
The
.I status
field of each returned option is set to indicate the result of the
negotiation.  The value is
.B T_SUCCESS
if the proposed value was negotiated,
.B T_PARTSUCCESS
if a degrated value was negotiated,
.B T_FAILURE
if the negotiation failed (according to the negotiation rules),
.B T_NOTSUPPORT
if the transport provider does not support this option or illegally request
negotiation of a privileged option, and
.B T_READONLY
if modification of a read-only option was requested.  If the
.I status
is
.BR 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
.IR ret->flags .
This field contains the worst single result, whereby the rating is done
according to the order
.BR T_NOTSUPPORT ", " T_READONLY ", " T_FAILURE ", " T_PARTSUCCESS ", " T_SUCCESS .
The value
.B T_NOTSUPPORT
is the worst result and
.B T_SUCCESS
is the best.
.\"
.\"
.SH CAVEATS
.PP
.BR t_optmgmt ()
is valid in any state other than
.BR T_UNINIT .
.PP
.BR t_optmgmt ()
is valid for all transport service providers regardless of service type.
Not all transport service providers necessarily support this function.
.\"
.\"
.SH "RETURN VALUE"
.PP
Upon success,
.BR t_optmgmt ()
returns zero (0).
Upon failure,
.BR t_optmgmt ()
returns -1 and sets
.IR t_errno (3)
to an appropriate error number.
.\"
.\"
.SH ERRORS
.PP
When
.BR t_optmgmt ()
fails, it returns -1 and sets
.IR t_errno (3)
to an appropriate error number as follows:
.TP \w'[TNOTSUPPORT]\(em'u
.RB [ TBADF ]
.I fd
is invalid.
.TP
.RB [ TBADFLAG ]
The argument
.I req->flags
contains invalid flags.
.TP
.RB [ TBADOPT ]
The options specified were of an invalid format or contained invalid information.
See
.IR "\(lqOPTIONS\(rq" ,
above, for more information on option formats.
.TP
.RB [ TBUFOVFLW ]
The \fImaxlen\fR field of a \fBnetbuf\fR(3) structure passed to the call was
non-zero, but insufficient to hold the available opaque information.  See,
\fBnetbuf\fR(3) for more information.
.TP
.RB [ TNOTSUPPORT ]
The call requires the use of a TLI primitive not supported by the underlying transport provider.
.TP
.RB [ TOUTSTATE ]
The call was issued with the interface in an incorrect state.
.TP
.RB [ TPROTO ]
A protocol error occured between the XTI/TLI library and the underlying transport provider.
.TP
.RB [ TSYSERR ]
A \fBLinux\fR system error occured and the \fBLinux\fR error number is set in \fIerrno\fR(3).
.\"
.\"
.SH "SEE ALSO"
.PP
.BR errno (3),
.BR netbuf (3),
.BR t_errno (3).
.\"
.\"
.SH "BUGS"
.PP
.BR t_optmgmt ()
has no known bugs.
.BR t_optmgmt ()
has been tested for the described behavior using the
.I /usr/bin/test-xnet
conformance test program.
.\"
.\"
.SH "CONFORMING TO"
.PP
XTI/TLI,
.[
XTI
.]
TPI,
.[
TPI Revision 2.0.0
.]
XPG5,
XNS 5.2,
.[
xns
.]
SUSv2.
.[
susv2
.]
.\"
.\"
.[
$LIST$
.]
.T4