Technical Reference: Communications, Volume 2

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

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:

`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:

`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:

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:

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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The t_getinfo subroutine, t_open subroutine.

List of Streams Programming References and STREAMS Overview in AIX 5L Version 5.1 Communications Programming Concepts.