t_optmgmt(3)

NAME

t_optmgmt() — manage options for a transport endpoint

SYNOPSIS

#include <xti.h>            /* for X/OPEN Transport Interface - XTI */
/* or */
#include <tiuser.h>         /* for Transport Layer Interface - TLI  */

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

DESCRIPTION

The t_optmgmt() function enables a transport user to retrieve, verify or negotiate protocol options with the transport provider. The argument fd identifies a bound transport endpoint.

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

struct netbuf opt; 
t_scalar_t flags; 

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 netbuf structure in a manner similar to the address in t_bind(). 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 isoco_options for connection-oriented service, or struct isocl_options 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 isoco_options for connection-oriented service, or struct isocl_options 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 content of the options is imposed by the transport provider.

Each option in the options buffer is of the form struct t_opthdr possibly followed by an option value.

The level field of struct t_opthdr 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 t_opthdr plus the length of the option value. If t_optmgmt() is called with the action T_NEGOTIATE 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 t_uscalar_t boundary. The macro OPT_NEXTHDR(pbuf, buflen, option) 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. 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 <xti.h> in the CAE Specification X/Open Transport Interface (XTI) 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 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 must 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 status is one of the following:

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.
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 of 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 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 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 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 option 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 one of the following:

T_NOTSUPPORT: if the protocol level does not support this option or if 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 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 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.

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 default values are then returned in ret->opt.buf.

The status field returned is one of the following:

T_NOTSUPPORT: if the protocol level does not support this option or if 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 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 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 T_NOTSUPPORT 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, 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 O_NONBLOCK 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 T_UNINIT.

The protocol level is XTI_GENERIC. For this level, the following options are defined. 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_RECVLOWAT, XTI_SNDBUF, and XTI_SNDLOWAT are not absolute requirements.

XTI_DEBUG

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.

XTI_LINGER

This option is used to linger the execution of a t_close() or close() if send data is still queued in the send buffer. The option value specifies the linger period. If a close() or t_close() 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, t_close() or close() 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 t_linger declared as:

struct t_linger{ 
   t_uscalar_t l_onoff;  /* switch option on/off     */ 
   t_uscalar_t l_linger; /* linger period in seconds */ 
} 

Legal values for the l_onoff are:

T_NO: switch option off
T_YES: 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 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 that this option does not linger the execution of t_snddis().

XTI_RCVBUF

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 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 ndd variables tcp_recv_hiwater_max and udp_recv_hiwater_max depending 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.

XTI_RCVLOWAT

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 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 (e.g. poll() or select()) indicates the data, and the data can be read by t_rcv() or t_rcvudata().

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

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 ndd variable tcp_xmit_hiwater_max.

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

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

Fork Safety

t_optmgmt is not fork-safe.

RETURN VALUE

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned, and t_errno 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 t_* routines by linking with /usr/lib/libnsl_s.a. For more information on TLI, see the TLI section of STREAMS/UX for HP 9000 Reference Manual.

ERRORS

On failure, t_errno is set to the following:

TBADF: The specified identifier does not refer to a transport endpoint.
TOUTSTATE: The function was issued in the wrong sequence.
TACCES: The user does not have the permission to negotiate the specified options.
TBADOPT: The specified protocol options were in an incorrect format or contained illegal information.
TBADFLAG: An invalid flag was specified.
TBUFOVFLW: 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.
TSYSERR: A system error has occurred during execution of this function.
TPROTO: (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 t_errno.
TNOTSUPPORT: (XTI only) This action is not supported by the underlying transport provider.

STANDARDS CONFORMANCE

t_optmgmt(): SVID2, XPG3, XPG4

t_optmgmt(3)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

DESCRIPTION

XTI-Level Options

Valid States

Fork Safety

RETURN VALUE

ERRORS

SEE ALSO

STANDARDS CONFORMANCE