t_optmgmt Subroutine for X/Open Transport Interface

Purpose

Manage options for a transport endpoint.

Library

X/Open Transport Interface Library (libxti.a)

Syntax

#include <xti.h>

int t_optmgmt(
    int fd,
    const struct t_optmgmt *req,
    struct t_optmgmt *ret)

Description

The t_optmgmt subroutine enables a transport user to retrieve, verify, or negotiate protocol options with the transport provider.

The req and ret parameters both point to a t_optmgmt structure containing the following members:

struct netbuf opt;
long flags;

Within this structure, the fields have the following meaning:

Field	Description
opt	Identifies protocol options. The options are represented by a netbuf structure in a manner similar to the address in the t_bind subroutine: len Specifies the number of bytes in the options and on return, specifies the number of bytes of options returned. buf Points to the options buffer. For the ret parameter, buf points to the buffer where the options are to be placed. Each option in the options buffer is of the form struct t_opthdr possibly followed by an option value. The fields of this structure and the values are: level Identifies the X/Open Transport Interface level or a protocol of the transport provider. name Identifies the option within the level. len Contains its total length, for example, 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. status Contains information about the success or failure of a negotiation. Each option in the input or output option buffer must start at a long-word boundary. The macro OPT_NEXTHDR (pbuf, buflen, poption) can be used for that purpose. The macro parameters are as follows: pbuf Specifies a pointer to an option buffer opt.buf. buflen The length of the option buffer pointed to by pbuf. poption Points to the current option in the option buffer. OPT_NEXTHDR 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 the xti.h header file for the exact definition of this structure. 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 fails with TBADOPT. If the error is detected, some options may have successfully negotiated. The transport user can check the current status by calling the t_optmgmt subroutine with the T_CURRENT flag set. Note: "The Use of Options" contains a detailed description about the use of options and should be read before using this subroutine. maxlen Has no meaning for the req parameter, but must be set in the ret parameter to specify the maximum size of the options buffer. On return, len specifies the number of bytes of options returned. The value in maxlen has no meaning for the req argument,
flags	Specifies the action to take with those options. The flags field of req must specify one of the following actions: T_CHECK This action enables the user to verify whether the options specified in the req parameter are supported by the transport provider. If an option is specified with no option value, (that is, it consists only of a t_opthdr structure), the option is returned with its status field set to one of the following: T_SUCCESS - if it is supported. T_NOTSUPPORT - if it is not or needs additional user privileges. T_READONLY - if it is read-only (in the current X/Open Transport Interface 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 the flags field of the netbuf structure pointed to by the ret parameter. This field contains the worst single result of the option checks, where the rating is the same as for T_NEGOTIATE. Note, that no negotiation takes place. All currently effective option values remain unchanged. T_CURRENT This action enables the transport user to retrieve the currently effective option values. The user specifies the options of interest in the opt fields in the netbuf structure pointed to by the req parameter. The option values are irrelevant and will be ignored; it is sufficient to specify the t_opthdr part of an option only. The currently effective values are then returned in opt fields in the netbuf structure pointed to by the ret parameter. The status field returned is on of the following: 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. T_SUCCESS in all other cases. The overall result of the option checks is returned in the flags field of the netbuf structure pointed to by the ret parameter. This field contains the worst single result of the option checks, where the rating is the same as for T_NEGOTIATE. For each level, the T_ALLOPT option (see below) can be requested on input. All supported options of this level with their default values are then returned.
	T_DEFAULT This action enables the transport user to retrieve the default option values. The user specifies the options of interest in the opt fields in the netbuf structure pointed to by the req parameter. 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 the opt field of the netbuf structure pointed to by the ret parameter. The status field returned is one of the following: 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. T_SUCCESS in all other cases. The overall result of the option checks is returned in the flags field of the ret parameter netbuf structure. This field contains the worst single result of the option checks, where the rating is the same as for T_NEGOTIATE. For each level, the T_ALLOPT option (see below) can be requested on input. All supported options of this level with their default values are then returned. In this case, the maxlen value of the opt field in the ret parameter netbuf structure must be given at least the value of the options field of the info parameter (see the t_getinfo or t_open subroutines) before the call.
	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 in the req parameter netbuf structure. The negotiated option values are returned in the buffer pointed to by the opt field of the ret parameter netbuf structure. The status field of each returned option is set to indicate the result of the negotiation. The value is one of the following: T_SUCCESS if the proposed value was negotiated. T_PARTSUCCESS if a degraded value was negotiated. T_FAILURE is 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 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 the flags field of the ret parameter netbuf structure. This field contains the worst single result, whereby the rating is done according to the following order, where T_NOTSUPPORT is the worst result and T_SUCCESS is the best: T_NOTSUPPORT T_READONLY T_FAILURE T_PARTSUCCESS T_SUCCESS. For each level, the T_ALLOPT option (see below) can be requested on input. This option has no value and consists of a t_opthdr only. This input requests negotiation of all supported options of this level to their default values. The result is returned option by option in the opt field of the structure pointed to in the ret parameter. Depending on the state of the transport endpoint, not all requests to negotiate the default value may be successful.
	The T_ALLOPT option can only be used with the t_optmgmt structure and the actions T_NEGOTIATE, T_DEFAULT and T_CURRENT. This option can be used with any supported level and addresses all supported options of this level. The option has no value and consists of a t_opthdr only. Since only options of one level may be addressed in a t_optmgmt call, this option should not be requested together with other options. The subroutine 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 subroutine t_optmgmt may block under various circumstances and depending on the implementation. For example, the subroutine will block if the protocol addressed by the call resides on a separate controller. It may also block due to flow control constraints, if data previously sent across this transport endpoint has not yet been fully processed. If the subroutine is interrupted by a signal, the option negotiations that have been done so far may remain valid. The behavior of the subroutine is not changed if O_NONBLOCK is set.

Parameters

Item	Description
fd	Identifies a transport endpoint.
req	Requests a specific action of the provider.
ret	Returns options and flag values to the user.

-Level Options

X/Open Transport Interface (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 the bound transport endpoint identified by the fd parameter relates to specific transport providers.

The subsequent options are not association-related (see Chapter 5, The Use of Options) . They may be negotiated in all XTI states except T_UNINIT.

The protocol level is XTI_GENERIC. For this level, the following options are defined (the type of each option value is of type unsigned long unless otherwise indicated):

XTI-Level Options

Option Name	Legal Option Value	Meaning
XTI_DEBUG (array of unsigned longs)	see text	enable debugging
XTI_LINGER (struct linger)	see text	linger on close if data is present
XTI_RCVBUF	size in octets	receive buffer size
XTI_RCVLOWAT	size in octets	receive low-water mark
XTI_SNDBUF0	size in octets	send buffer size
XTI_SNDLOWAT	size in octets	send low-water mark

A request for XTI_DEBUG is an absolute requirement. A request to activate XTI_LINGER is an absolute requirement; the timeout value to this option is not. XTI_RCVBUF, XTI_RCVLOWAT, XTI_SNDBUF and XTI_SNDLOWAT are not absolute requirements.

Option	Description
XTI_DEBUG	Enables debugging. The values of this option are implementation-defined. Debugging is disabled if the option is specified with no value (for example, with an option header only). The system supplies utilities to process the traces. An implementation may also provide other means for debugging.
XTI_LINGER	Lingers the execution of a t_close subroutine or the close exec if send data is still queued in the send buffer. The option value specifies the linger period. If a close exec or t_close subroutine 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, the t_close subroutine or close exec either, at a maximum, block the linger period, or immediately return, whereupon, at most, the system holds the connection in existence for the linger period. The option value consists of a structure t_linger declared as: `struct t_linger { long l_onoff; long l_linger; }` The fields of the structure and the legal values are: l_onoff Switches the option on or off. The value l_onoff is an absolute requirement. The possible values are: T_NO switch option off T_YES activate option l_linger Determines the linger period in seconds. The transport user can request the default value by setting the field to T_UNSPEC. The default timeout value depends on the underlying transport provider (it is often T_INFINITE). Legal values for this field are T_UNSPEC, T_INFINITE 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: Note that this option does not linger the execution of the t_snddis subroutine.
XTI_RCVBUF	Adjusts 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 incoming data. 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.
XTI_RCVLOWAT	Sets a low-water mark in the receive buffer. The option value gives the minimal number of bytes that must have accumulated 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 T_DATA event is created, an event mechanism (for example, the poll or select subroutines) indicates the data, and the data can be read by the t_rcv or t_rcvudata subroutines. 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.
XTI_SNDBUF	Adjusts the internal buffer size allocated for the send buffer. 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.
XTI_SNDLOWAT	Sets 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 - except from T_UNINIT.

Return Values

Item	Description
0	Successful completion.
-1	t_errno is set to indicate an error.

Error Codes

On failure, t_errno is set to one of the following:

Value	Description
TACCES	The user does not have permission to negotiate the specified options.
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.
TOUTSTATE	The subroutine was issued in the wrong sequence.
TPROTO	This error indicates that a communication problem has been detected between the X/Open Transport Interface and the transport provider for which there is no other suitable X/Open Transport Interface (t_errno).
TSYSERR	A system error has occurred during execution of this subroutine.