t_optmgmt(3xti)


t_optmgmt -- manage options for a transport endpoint

Synopsis

cc [options] file -lnsl
#include <xti.h>

int t_optmgmt (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 associated with the bound transport endpoint specified by fd. t_optmgmt is a TLI/XTI local management routine that may be used with both connection-mode and connectionless protocol services.


NOTE: UnixWare transport providers do not support XPG4 options management unless the value of the environment variable XTI_OPTMGMT is set to 1 and exported. See if(7tcp) for more information.

UnixWare 2.0 transport providers do not support XPG4 options management. Some features of t_optmgmt may also not be supported by third-party transport providers. Limited transport-independent options management is provided by netdir_options(3N).


Parameters


fd
the file descriptor for the transport endpoint

req
points to the t_optmgmt structure used to specify the request.

info
points to the t_optmgmt structure used to identify the return.

Structure definitions

The req and ret arguments point to a t_optmgmt structure containing the following members:
   struct netbuf opt;      /* protocol options     */
   long flags;             /* actions              */
The opt field identifies protocol options and the flags field is used to specify the action to take with those options. The members of the netbuf structure are described in intro(3xti).

The req argument is used to request a specific action of the provider and to send options to the provider. The maxlen field of the netbuf structure has no meaning for req. The len field specifies the number of bytes in the options. The buf field points to the list of options and their headers.

The ret argument is used to return options and flag values from the transport provider. The maxlen field of the netbuf structure must be set to specify the maximum number of bytes that the options buffer can hold. The buf field points to the buffer where the options are to be placed. On return, len specifies the number of bytes of options returned.

Each option in the options buffer consists of a struct t_opthdr option header which may be followed by an option value. The level member identifies the XTI level or the transport provider protocol. The name member identifies the option within the level, and the len member stores its total length (length of t_opthdr plus option value). If t_optmgmt is called with the action T_NEGOTIATE set, the status member of the returned options indicates whether the negotiation succeeded or failed.

You can use the macro OPT_NEXTHDR(pbuf,buflen,poption) to help in reading from or writing to an option buffer. This macro also automatically aligns each option in an input or output option buffer on a long-word boundary. pbuf points to an option buffer (opt.buf), buflen is its length, and poption points to the current option in the buffer. The macro returns a pointer to the position of the next option or returns a null pointer if the end of the buffer is reached.

The actual structure and content of the options is imposed by the transport provider (for example, see if(7tcp)).

All options specified on input must address the same level.

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


T_NEGOTIATE
Negotiate the values of the options specified in req->opt.buf and req->opt.len with the transport provider.

The provider will evaluate the requested options and negotiate the values, returning the negotiated values through ret->opt.buf. The status member of each returned option indicates the result of negotiation:


T_SUCCESS
proposed value was negotiated

T_PARTSUCCESS
degraded value was negotiated

T_FAILURE
negotiation failed according to rules

T_NOTSUPPORT
transport provider does not support option, or option is privileged

T_READONLY
option is read-only
If status is T_SUCCESS, T_FAILURE, T_NOTSUPPORT or T_READONLY, the returned option value is the same as that requested.

The overall result of the negotiation is returned in ret->flags. This member contains the worst result in the list: T_NOTSUPPORT (worst), T_READONLY, T_FAILURE, T_PARTSUCCESS, and T_SUCCESS (best).

If the option T_ALLOPT is requested, all supported options of this level are requested to be negotiated to their default values. On output, ret->opt.buf contains the result, option by option.


T_CHECK
Verify whether the options specified in req are supported by the transport provider.

If an option consists only of a t_opthdr option header, the status member of the returned option indicates the following:


T_SUCCESS
option is supported

T_NOTSUPPORT
transport provider does not support option, or option is privileged

T_READONLY
option is read-only
If an option is specified with an option value, status is returned with the same value as if the option value were negotiated using T_NEGOTIATE. If status is T_SUCCESS, T_FAILURE, T_NOTSUPPORT, or T_READONLY, the returned option value is the same as the requested value.

On return, ret->flags will be set to the worst value as for T_NEGOTIATE. All currently effective option values remain unchanged.


T_DEFAULT
Retrieve the default options supported by the transport provider into ret->opt.buf. Only the t_opthdr option header need be specified.

The returned status member indicates the following:


T_SUCCESS
option is supported

T_NOTSUPPORT
transport provider does not support option, or option is privileged

T_READONLY
option is read-only
On return, ret->flags will be set to the worst value as for T_NEGOTIATE.

If the option T_ALLOPT is requested, all supported options of this level with their default values are returned. On input, ret->opt.maxlen must have at least the value info->options.


T_CURRENT
Retrieve the option values that are currently effective for the options specified by req->opt.buf. Only the t_opthdr option header need be specified. On return, req->opt.buf will contain the currently effective values.

The returned status member indicates the following:


T_SUCCESS
option is supported

T_NOTSUPPORT
transport provider does not support option, or option is privileged

T_READONLY
option is read-only
On return, ret->flags will be set to the worst value as for T_NEGOTIATE.

If the option T_ALLOPT is requested, all supported options of this level are returned with their currently effective values.

The option T_ALLOPT can be used with the actions T_NEGOTIATE, T_DEFAULT, and T_CURRENT at any level. Only the t_opthdr option header need be specified. This option should not be requested with other options.

t_optmgmt may block if data previously sent across the transport endpoint has not yet been fully processed. If interrupted by a signal, option negotiations that are yet to be processed remain valid. t_optmgmt is also unaffected by the setting of O_NONBLOCK.

XTI-level options

The following XTI-level options are generic (with protocol level XTI_GENERIC) and are not specific to any transport provider:

XTI_DEBUG
Enable debugging. If the option is specified with only an option header, disable debugging.

XTI_LINGER
Prolong the execution of a t_open or t_close (but not t_snddis) if send data is still queued in the send buffer. The linger period is specified by the option value consisting of a struct t_linger:
struct t_linger {
	long l_onoff;	/* switch option on (T_ON) or off (T_OFF) */
	long l_linger;	/* linger period in seconds */
}
Legal values for l_linger are T_UNSPEC (default), T_INFINITE, or a non-negative integer.

The system will attempt to send pending data within the linger period before closing the endpoint. Data that is then still remaining to be sent is discarded.


XTI_RCVBUF
Adjust the internal size of the receive buffer. The size may be increased for high-volume connections, or reduced to prevent incoming data backing-up.

XTI_RCVLOWAT
Set a low-end threshold on the receive buffer. This is the minimum number of bytes that must be received in the buffer before the transport user is notified via a T_DATA event.

XTI_SNDBUF
Adjust the internal size of the send buffer.

XTI_SNDLOWAT
Set a low-end threshold on the send buffer. This is the minimum number of bytes that must have accumulated in the buffer before they will be sent.

State transitions

t_optmgmt may be issued from any valid state except T_UNINIT and has no effect on the entry state at exit.

Files


/usr/lib/libxti.so
X/Open® Transport Interface Library (shared object)

/usr/lib/libnsl.so
Network Services Library (shared object)

Usage

If issued as part of a connectionless 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.

Return values

t_optmgmt returns 0 on success and -1 on failure and t_errno is set to indicate the error.

Errors

On failure, t_errno may be set to one of the following:

TBADF
The specified file descriptor does not refer to a transport endpoint.

TOUTSTATE
The function was issued in the wrong sequence.

TACCES
The user does not have 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 (maxlen) allocated for an incoming argument is greater than zero but 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
A communication problem has been detected with the transport provider and there is no other value of t_errno to describe the error condition.

TNOTSUPPORT
The action is not supported by the transport provider.

Warnings

The transport provider interface may not support the functionality for T_NEGOTIATE and/or T_CHECK, causing t_optmgmt to fail with a TNOTSUPPORT error.

References

intro(3xti), t_accept(3xti), t_alloc(3xti), t_bind(3xti), t_connect(3xti), t_getinfo(3xti), t_listen(3xti), t_open(3xti), t_optmgmt(3xti_ipx), t_optmgmt(3xti_spx), t_rcvconnect(3xti)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004