t_optmgmt Subroutine for Transport Layer Interface

Purpose

Manages options for a transport end point.

Library

Transport Layer Interface Library (libtli.a)

Syntax

#include <tiuser.h>

int t_optmgmt(fd, req, ret)
int  fd;
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.

Parameters

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

Both the req and ret parameters 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 specifies the action to take with those options.

The options are represented by a netbuf structure in a manner similar to the address in the t_bind subroutine. The req parameter is used to send options to the provider. This netbuf structure contains the following fields:

Field Description
len Specifies the number of bytes in the options.
buf Points to the options buffer.
maxlen Has no meaning for the req parameter.

The ret parameter is used to return information to the user from the transport provider. On return, this netbuf structure contains the following fields:

Field Description
len Specifies the number of bytes of options returned.
buf Points to the buffer where the options are to be placed.
maxlen Specifies the maximum size of the options buffer. The maxlen field has no meaning for the req parameter, but must be set in the ret parameter to specify the maximum number of bytes the options buffer can hold. The actual structure and content of the options is imposed by the transport provider.

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

Action Description
T_NEGOTIATE Enables the user to negotiate the values of the options specified in the req parameter with the transport provider. The provider evaluates the requested options and negotiates the values, returning the negotiated values through the ret parameter.
T_CHECK Enables the user to verify if the options specified in the req parameter are supported by the transport provider. On return, the flags field of the ret parameter has either T_SUCCESS or T_FAILURE set to indicate to the user whether the options are supported or not. These flags are only meaningful for the T_CHECK request.
T_DEFAULT Enables a user to retrieve the default options supported by the transport provider into the opt field of the ret parameter. In the req parameter, the len field of the opt field must be zero, and the buf field can be NULL.

If issued as part of the connectionless-mode service, the t_optmgmt subroutine may become blocked due to flow control constraints. The subroutine does not complete until the transport provider has processed all previously sent data units.

Return Values

On successful completion, the t_optmgmt subroutine returns a value of 0. Otherwise, it returns a value of -1, and the t_errno variable is set to indicate the error.

Error Codes

If unsuccessful, the t_errno variable is set to one of the following:

Value Description
TACCES User does not have permission to negotiate the specified options.
TBADF Specified file descriptor does not refer to a transport endpoint.
TBADFLAG Unusable flag was specified.
TBADOPT Specified protocol options were in an incorrect format or contained unusable information.
TBUFOVFLW Number of bytes allowed for an incoming parameter is not sufficient to store the value of that parameter. Information to be returned in the ret parameter will be discarded.
TOUTSTATE Function was issued in the wrong sequence.
TSYSERR A system error has occurred during operation of this subroutine.