t_optmgmt(3) Library Functions Manual t_optmgmt(3)
NAME
t_optmgmt() - manage options for a transport endpoint
SYNOPSIS
DESCRIPTION
The function enables a transport user to retrieve, verify or negotiate protocol options with the transport provider. The argument fd iden-
tifies 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 specifies 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 connection-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 buf-
fer should be of struct for connection-oriented service, or struct for connectionless 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 argument, but must be set in the ret argument to specify the maximum number of bytes the options buffer can hold. The actual con-
tent 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 information about the success or failure of a negotiation.
Each option in the input or output option buffer must start at a boundary. 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 negotiation. 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 negotiation 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 sta-
tus field set to if it is supported, if it is not or needs additional user privileges, 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 single result of the
option checks, whereby the rating is the same as for
Note that no negotiation takes place. All currently 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_get-
info(3), t_open(3)) before the call.
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 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 effec-
tive 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 sup-
ported 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 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 and/or functionalities. 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 pro-
tocol addressed by the call resides on a separate controller. It may also block due to flow control constraints, i.e. if data set 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 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 negotiated 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 activate
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 implementation- 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 pending data within the linger period before closing the endpoint. Data still
pending after the linger period has elapsed is discarded.
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 implementation 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-volume connections, or decreased to limit the possible backlog of incom-
ing 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 depending upon the under-
lying 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 accumulated in the receive buffer before they become visible to the trans-
port 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 controlled 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 accumulated 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 (Transport 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 ALSO
t_accept(3), t_alloc(3), t_connect(3), t_getinfo(3), t_listen(3), t_open(3), t_rcvconnect(3), thread_safety(5).
STANDARDS CONFORMANCE
t_optmgmt(3)