t_optmgmt(3)t_optmgmt(3)NAMEt_optmgmt() - manage options for a transport endpoint
SYNOPSISDESCRIPTION
The function enables a transport user to retrieve, verify or negotiate
protocol options with the transport provider. The argument fd identi‐
fies a bound transport endpoint.
The req and ret arguments point to a structure containing the following
members:
The opt field identifies protocol options. The flags field is used to
specify the action to take with those options.
The options are represented by a structure in a manner similar to the
address in The argument req is used to request a specific action of the
provider and to send options to the provider. The argument len speci‐
fies the number of bytes in the options. buf points to the options
buffer. maxlen has no meaning for the req argument. For XTI over the
OSI transport provider, the options buffer should be of struct for con‐
nection-oriented service, or struct for connectionless service. For
TLI, see the documentation of the transport provider being used.
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. For XTI over the OSI transport provider, the options buffer
should be of struct for connection-oriented service, or struct for con‐
nectionless service. For TLI, see the documentation of the transport
provider being used. On return, len specifies the number of bytes of
options returned. The value in maxlen has no meaning for the req argu‐
ment, but must be set in the ret argument to specify the maximum number
of bytes the options buffer can hold. The actual content of the
options is imposed by the transport provider.
Each option in the options buffer is of the form possibly followed by
an option value.
The level field of struct identifies the XTI level or a protocol of the
transport provider. The name field identifies the option within the
level. len contains its total length; i.e. the length of the option
header plus the length of the option value. If is called with the
action set, the status field of the returned options contains informa‐
tion about the success or failure of a negotiation.
Each option in the input or output option buffer must start at a bound‐
ary. The macro can be used for that purpose. The parameter pbuf
denotes a pointer to an option buffer opt.buf, and buflen is its
length. The parameter option points to a current option in the option
buffer. returns a pointer to the position of the next option or
returns a null pointer if the option buffer is exhausted. The macro is
helpful for writing and reading. See in the manual from X/Open Company
Limited for the exact definition.
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
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 with the flag set.
The flags field of req must specify one of the following actions:
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 negoti‐
ation. The status is one of the following:
if the proposed value was negotiated.
if a degraded value was negotiated.
if the negotiation failed according to the negotia‐
tion rules.
if the transport provider does not support this
option or illegally
requests negotiation of a
privileged option.
if modification of a read-only option was
requested.
If the status is or 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
of The value is the worst result and is the best.
For each level, the option can be requested on
input. No value is given with this option; only
the 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 may be
successful.)
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 structure), the option is
returned with its status field set to if it is sup‐
ported, if it is not or needs additional user priv‐
ileges, and if it is read-only (in the current
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 If the status is or 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 sin‐
gle result of the option checks, whereby the rating
is the same as for
Note that no negotiation takes place. All cur‐
rently effective option values remain unchanged.
This action enables the transport user to retrieve the default option
values. The user specifies the option of interest
in req->opt.buf. The option values are irrelevant
and will be ignored; it is sufficient to specify
the part of an option only. The default values are
then returned in ret->opt.buf.
The status field returned is one of the following:
if the protocol level does not
support this option or if the
transport user illegally
requested a privileged
option.
if the option is read-only.
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
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 (see t_getinfo(3),
t_open(3)) before the call.
This action enables the transport user to retrieve the currently effec‐
tive
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 part of an option only. The default
values are then returned in ret->opt.buf.
The status field returned is one of the following:
if the protocol level does not support this option
or if the transport
user illegally requested a
privileged option.
if the option is read-only.
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
For each level, the option can be requested on
input. All supported options of this level with
their currently effective values are then returned.
The option can only be used with and the actions
and 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 only. Since
in a 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 imple‐
mentation 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 and/or functionali‐
ties. When this is the case, the error is
returned.
The function 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, i.e. if data set 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 is set.
XTI-Level Options
XTI level options are not specific for a particular transport provider.
An XTI implementation supports none, all or any subset of the options
defined below. An implementation may restrict the use of any of these
options by offering them only in the privileged or read-only mode, or
if fd relates to specific transport providers.
The subsequent options are not association-related. They may be nego‐
tiated in all XTI states except
The protocol level is For this level, the following options are
defined. A request for is an absolute requirement. A request to acti‐
vate is an absolute requirement; the timeout value to this option is
not. and are not absolute requirements.
This option enables debugging. The values of this option are implemen‐
tation- defined. Debugging is disabled if the option is specified with
"no value", i.e. with an option header only.
The system supplies utilities to process the traces. Note that
an implementation may also provide other means for debugging.
This option is used to linger the execution of a
or if send data is still queued in the send buffer. The option
value specifies the linger period. If a or is issued and the
send buffer is not empty, the system attempts to send the pend‐
ing data within the linger period before closing the endpoint.
Data still pending after the linger period has elapsed is dis‐
carded.
Depending on the implementation, or either block for at maximum
the linger period, or immediately return, whereupon the system
holds the connection in existence for at most the linger period.
The option constists of a structure declared as:
Legal values for the l_onoff are:
switch option off
activate option
The value of l_onoff is an absolute requirement.
The field l_linger determines the linger period in seconds. The
transport user can request the default value by setting the
field to The default timeout value depends on the underlying
transport provider (it is often Legal values for this field are
and all non-negative numbers.
The l_linger value is not an absolute requirement. The imple‐
mentation may place upper and lower limits to this value.
Requests that fall short of the lower limit are negotiated to
the lower limit.
Note that this option does not linger the execution of
This option is used to adjust the internal buffer size allocated for
the
receive buffer. The buffer size may be increased for high-vol‐
ume connections, or decreased to limit the possible backlog of
incoming data. Default and maximum buffer sizes are protocol-
dependent; see individual protocol manual entries, such as
tcp(7P) and udp(7P). Maximum buffer size is controlled by the
variables tcp_recv_hiwater_max and udp_recv_hiwater_max depend‐
ing upon the underlying protocol in use.
This request is not an absolute requirement. The implementation
may place upper and lower limits on the option value. Requests
that fall short of the lower limit are negotiated to the lower
limit.
Legal values are all positive numbers.
This option is used to set a low-water mark in the receive buffer. The
option
values gives the minimal number of bytes that must have accumu‐
lated in the receive buffer before they become visible to the
transport user. If and when the amount of accumulated receive
data exceeds the low-water mark, a event is created, an event
mechanism (e.g. or indicates the data, and the data can be read
by or
This request is not an absolute requirement. The implementation
may place upper and lower limits on the option value. Requests
that fall short of the lower limit are negotiated to the lower
limit.
Legal values are all positive numbers.
This option is used to adjust the internal buffer size allocated for
the
send buffer. The default maximum size of this buffer is con‐
trolled by the variable
This request is not an absolute requirement. The implementation
may place upper and lower limits on the option value. Requests
that fall short of the lower limit are negotiated to the lower
limit.
Legal values are all positive numbers.
This option is used to set a low-water mark in the send buffer. The
option
value gives the minimal number of bytes that must have accumu‐
lated in the send buffer before they are sent.
This request is not an absolute requirement. The implementation
may place upper and lower limits on the option value. Requests
that fall short of the lower limit are negotiated to the lower
limit.
Legal values are all positive numbers.
Valid States
All - apart from
Fork Safety
is not fork-safe.
RETURN VALUE
Upon successful completion, a value of 0 is returned. Otherwise, a
value of −1 is returned, and is set to indicate the error.
TLI supports any transport provider which is compliant with TPI (Trans‐
port Provider Interface). Users can access TLI versions of the rou‐
tines by linking with For more information on TLI, see the TLI section
of
ERRORS
On failure, is set to the following:
The specified identifier does not refer to a transport endpoint.
The function was issued in the wrong sequence.
The user does not have the permission to negotiate the specified
options.
The specified protocol options were in an incorrect format or contained
illegal
information.
An invalid flag was specified.
The number of bytes allowed for an incoming argument (
maxlen) is greater than 0 and not sufficient to
store the value of that argument. The information
to be returned in ret will be discarded.
A system error has occurred during execution of this function.
(XTI only) This error indicates that a communication problem has been
detected
between XTI and the transport provider for which
there is no existing XTI
(XTI only) This action is not supported by the underlying transport
provider.
SEE ALSOt_accept(3), t_alloc(3), t_connect(3), t_getinfo(3), t_listen(3),
t_open(3), t_rcvconnect(3), thread_safety(5).
STANDARDS CONFORMANCEt_optmgmt(3)
