t_optmgmt(3N)

NAME

t_optmgmt − manage options for a transport endpoint

SYNOPSIS

cc [ flag ... ] file ... −lnsl [ library ... ]

#include <xti.h>

int t_optmgmt(int fd, const struct t_optmgmt ∗req, struct t_optmgmt ∗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, a different header file, tiuser.h , must be used. Refer to the section, TLI COMPATIBILITY , for a description of differences between the two interfaces.

The t_optmgmt() 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 t_optmgmt structure containing the following members:

struct netbuf opt;
long 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 (see t_connect(3N)) in a manner similar to the address in t_bind(3N).

The argument req is used to request a specific action of the provider and to send options to the provider. The len field specifies the number of bytes in the options, the buf field points to the options buffer, and the maxlen field has no meaning for the req argument. The transport provider may return options and flag values to the user through ret. For ret, the maxlen field specifies the maximum size of the options buffer and the buf field points to the buffer where the options are to be placed. If the maxlen field in ret is set to zero, no options values are returned. ( TLI users should refer to the error description for TBUFOVFLW in the TLI COMPATIBILITY section for important differences.) On return, the len field specifies the number of bytes of options returned. The value in the maxlen field 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.

Options are conveyed in two buffers. Access to these buffers is moderated through two instances of the structure type netbuf, which in turn are referenced through the opt field of the t_optmgmt structures that are referenced by ret and req.

The following text graphic illustrates the layout of the option buffer. Note: TLI users please notice the option buffer differences mentioned in the TLI COMPATIBILITY section. XTI users please read the Warnings subsection.

The opt buffers can hold various options, each of which is an instance of the structure type t_opthdr followed by a variable-length option value, the meaning of which is context-dependent.

The values of fields in the t_opthdr determine the context for a particular option value:

len Specifies the total length that the option value occupies in the buffer, not counting any padding bytes for boundary-alignment purposes. It is the sum of the length of the header (t_opthdr) and the length of the option value that usually follows.

level Identifies the protocol or API associated with the option.

name Identifies a particular option applicable to the protocol or API corresponding to level.

status Indicates the success or failure of a negotiation, one of many possible types of actions that the flags field can specify.

Several options can be concatenated into a single opt buffer. However, in doing so, the transport user has to ensure that each option starts at a 32-bit or uint32_t boundary (same as long word boundary in ILP32 representation).

Each option in both the input (req) and output (ret) option buffers must start at a 32-bit boundary.

The macro OPT_NEXTHDR(pbuf, buflen, poption) can help dispatch these alignment requirements. This function macro can be an aid for both writing to and reading from the option buffers. It returns a pointer to the position of the next option or returns a null pointer if the option buffer is exhausted. In calls to this function macro, the parameter pbuf denotes a pointer to an option buffer opt.buf, and buflen is its length. The parameter poption points to the current option in the option buffer.

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 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 t_optmgmt() with the T_CURRENT flag set.

The flags field of req can specify one of the following actions:

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 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 T_SUCCESS if the proposed value was negotiated, T_PARTSUCCESS if a degraded value was negotiated, T_FAILURE if 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, and 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 ret→flags.

This field contains the worst single result, whereby the rating is done according to the order T_NOTSUPPORT , T_READONLY , T_FAILURE , T_PARTSUCCESS , T_SUCCESS . The value T_NOTSUPPORT is the worst result and T_SUCCESS is the best.

For each level, the option T_ALLOPT (see below) can be requested on input. No value is given with this option; only the t_opthdr 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 value may be successful.)

T_CHECK 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 t_opthdr structure), the option is returned with its status field set to T_SUCCESS if it is supported, T_NOTSUPPORT if it is not or needs additional user privileges, and T_READONLY 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 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 ret→flags. This field contains the worst single result of the option checks, whereby the rating is the same as for T_NEGOTIATE .

Note that no negotiation takes place. All currently effective option values remain unchanged.

T_DEFAULT This action enables the transport user to retrieve the 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 sufficient to specify the t_opthdr part of an option only. The default values are then returned in ret→opt.buf.

The status field returned is 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, and set to T_SUCCESS 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 T_NEGOTIATE .

For each level, the option 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, ret→opt.maxlen must be given at least the value info→options before a call to t_optmgmt() (see t_getinfo(3N) or t_open(3N)).

T_CURRENT 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 t_opthdr part of an option only. The currently effective values are then returned in ret→opt.buf.

The status field returned is 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, and set to T_SUCCESS 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 T_NEGOTIATE .

For each level, the option T_ALLOPT (see below) can be requested on input. All supported options of this level with their currently effective values are then returned.

The option T_ALLOPT can only be used with t_optmgmt() and the actions T_NEGOTIATE , T_DEFAULT , and T_CURRENT . 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 t_opthdr only. Since in a t_optmgmt() 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 T_NEGOTIATE and/or T_CHECK functionalities. When this is the case, the error TNOTSUPPORT is returned.

The function t_optmgmt() 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; that is, if data sent 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 behaviour of the function is not changed if O_NONBLOCK is set.

VALID STATES

Legitimate states (see t_getstate(3N)) for a call to this routine are every one except T_UNINIT .

RETURN VALUES

t_optmgmt() returns:

0 On success.

−1 On failure.

On failure, t_errno is set to indicate the error, and possibly errno is set.

ERRORS

On failure, t_errno 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 protocol options were in an incorrect format or contained illegal information.

TBUFOVFLW The number of bytes allowed (maxlen) for an incoming argument is greater than 0 but still insufficient to store the value of that argument. The information to be returned in ret will be discarded.

TNOTSUPPORT This action is not supported by the transport provider.

TOUTSTATE The function was issued in the wrong sequence. the communications endpoint referenced by fd or resfd 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 t_errno value.

TSYSERR A system error has occurred during execution of this function; errno will be set to the specific error.

Warning

Using OPT_NEXTHDR , and not using knowledge of 32-bit boundary layouts, is recommended for applications. Future versions of LP 64 architectures will provide more macros. This area of specification is evolving. For maximal portability, using only one option in a buffer and multiple t_optmgmt() calls is recommended, instead of packing multiple option requests in a buffer.

TLI COMPATIBILITY

The XTI and TLI interface definitions have common names but use different header files. This, and other semantic differences between the two interfaces are described in the subsections below.

Interface Header

The XTI interfaces use the header file, xti.h . TLI interfaces should not use this header. They should use the header:

#include <tiuser.h>

Error Description Values

The t_errno value that can be set by the XTI interface and cannot be set by the TLI interface is:

TPROTO

The t_errno values that this routine can return under different circumstances than its XTI counterpart are TACCES and TBUFOVFLW .

TACCES 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.

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.

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:

T_NEGOTIATE
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 negotiated values through ret.

T_CHECK 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 T_SUCCESS or T_FAILURE set to indicate to the user whether the options are supported. These flags are only meaningful for the T_CHECK request.

T_DEFAULT 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 NULL .

Connectionlessness

If issued as part of the connectionless-mode service, t_optmgmt() may block due to flow control constraints. The function will not complete until the transport provider has processed all previously sent data units.

For more information refer to the Transport Interfaces Programming Guide.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe

Museum

Related Articles