t_optmgmt(3) — Subroutines
NAME
t_optmgmt − Manages protocol options for a transport endpoint
LIBRARY
XTI Library (libxti.a)
SYNOPSIS
#include <xti.h>
int t_optmgmt(
int fd,
struct t_optmgmt ∗req,
struct t_optmgmt ∗ret) ;
PARAMETERS
The t_optmgmt() function can only be called in the T_IDLE transport provider state. The following table summarizes the relevance of input and output parameters before and after t_optmgmt() is called:
| Parameter | Before Call | After Call |
| fd | y | n |
| req->opt.maxlen | n | n |
| req->opt.len | y | n |
| req->opt.buf | y(y) | n |
| req->flags | y | n |
| ret->opt.maxlen | y | n |
| ret->opt.len | n | y |
| ret->opt.buf | y | (y) |
| ret->flags | n | — |
Notes to Table:
yThis a meaningful parameter.
nThis is not a meaningful parameter.
(y)The content of the object pointed to by y is meaningful.
fd Specifies a file descriptor returned by t_open() function that identifies the local transport endpoint.
req Points to a type t_optmgmt structure. This structure is used to reserve space for a transport-user options data buffer that stores negotiable protocol options. The type t_optmgmt structure has the following members:
struct netbuf opt
Specifies a buffer for protocol-optional parameters associated with the referenced transport endpoint. The type netbuf structure pointed to by this member is defined in the xti.h include file. This structure, which is used to define buffer parameters, has the following members:
unsigned int maxlen
Specifies maximum byte length of the data buffer.
unsigned int len
Specifies the actual byte length of data written to the buffer.
char ∗buf
Points to the buffer location.
flags A longword (least significant bit rightmost) that specifies the response action that must be taken by a transport provider when the t_optmgmt() function is processed. Corresponding values and symbolic names for the following flag bits are defined in the xti.h include file. Note that the flags parameter can specify only one of these values, not a combination.
| Bit | Symbolic Name | Meaning |
| 2 | T_NEGOTIATE | The transport user wants to negotiate the values of the options stored in the options buffer. In response, the transport provider evaluates the options and writes acceptable (negotiated) values to the data buffer pointed to by ret->opt.buf. |
| 3 | T_CHECK | The transport user wants to verify that the options specified in the data buffer pointed to by req->opt.buf are supported by the transport provider. On return, the transport provider writes a ret->flags> value, which is either T_SUCCESS or T_FAILURE. |
| 4 | T_DEFAULT | The transport user wants to know what the default options supported by the transport provider are. The transport provider writes default data into the options data buffer pointed to by ret->opt.buf. The req->opt.len parameter must be set to 0 (zero). The req->opt.buf member may be set to its null value. |
ret Points to a second type t_optmgmt structure. The ret->opt.maxlen parameter specifies the maximum length of the transport provider options data buffer. The ret->opt.len parameter specifies the actual length of the transport provider options data buffer. The ret->opt.buf parameter points to the transport provider options data buffer. On return, if T_CHECK was specified in req->flags, the ret->flags parameter is set to T_SUCCESS or T_FAILURE, indicating whether the transport provider supports the options specified by the transport user.
DESCRIPTION
The t_optmgmt() XTI function is used in connectionless and connection-oriented transport service. The t_optmgmt() function associates specific optional parameters with a bound transport endpoint previously defined by a file descriptor returned by the t_open() function. The t_optmgmt() function permits a transport user to retrieve, verify, or negotiate desired options with a transport provider.
A type t_optmgmt structure defined in the xti.h include file is used to specify options.
RETURN VALUE
Upon successful completion, a value of 0 (zero) is returned. Otherwise, a value of -1 is returned and t_errno is set to indicate the error.
ERRORS
If the t_optmgmt() function fails, t_errno may be set to one of the following values:
[TBADF] File descriptor fd does not refer to a valid transport endpoint.
[TOUTSTATE]
This function was called in the wrong sequence.
[TBADOPT]
The specified protocol options are either of an incorrect format or contain illegal information.
[TBADFLAG]
The specified flag is invalid.
[TACCES] The transport user does not have permission to negotiate the specified options.
[TBUFOVFLW]
The number of bytes allowed for an incoming argument is not sufficient to store the value of that argument. The information intended for the data buffer pointed to by the ret parameter is discarded.
[TSYSERR] A system error occurred during execution of the t_optmgmt() function.
[TNOTSUPPORT]
This function is not supported by the underlying transport provider.
RELATED INFORMATION
Functions: t_accept(3), t_alloc(3), t_connect(3), t_getinfo(3), t_listen(3), t_open(3), t_rcvconnect(3)