t_alloc Subroutine for Transport Layer Interface

Purpose

Allocates a library structure.

Library

Transport Layer Interface Library (libtli.a)

Syntax

#include <tiuser.h>

char *t_alloc (fd, struct_type, fields)
int  fd;
int  struct_type;
int  fields;

Description

The t_alloc subroutine dynamically assigns memory for the various transport-function argument structures. This subroutine allocates memory for the specified structure, and also allocates memory for buffers referenced by the structure.

Use of the t_alloc subroutine to allocate structures will help ensure the compatibility of user programs with future releases of the transport interface.

Parameters

Item Description
fd Specifies the transport end point through which the newly allocated structure will be passed.
struct_type Specifies the structure to be allocated. The structure to allocate is specified by the struct_type parameter, and can be one of the following:
T_BIND
struct t_bind
T_CALL
struct t_call
T_OPTMGMT
struct t_optmgmt
T_DIS
struct t_discon
T_UNITDATA
struct t_unitdata
T_UDERROR
struct t_uderr
T_INFO
struct t_info

Each of these structures may subsequently be used as a parameter to one or more transport functions.

Each of the above structures, except T_INFO, contains at least one field of the struct netbuf type. The netbuf structure is described in the tiuser.h file. For each field of this type, the user may specify that the buffer for that field should be allocated as well. The fields parameter specifies this option, where the parameter is the bitwise-OR of any of the following:

T_ADDR
The addr field of the t_bind, t_call, t_unitdata, or t_uderr structure.
T_OPT
The opt field of the t_optmgmt, t_call, t_unitdata, or t_uderr structure.
T_UDATA
The udata field of the t_call, t_discon, or t_unitdata structure.
T_ALL
All relevant fields of the given structure.
fields Specifies whether the buffer should be allocated for each field type. For each field specified in the fields parameter, the t_alloc subroutine allocates memory for the buffer associated with the field, initializes the len field to zero, and initializes the buf pointer and the maxlen field accordingly. The length of the buffer allocated is based on the same size information returned to the user from the t_open and t_getinfo subroutines. Thus, the fd parameter must refer to the transport end point through which the newly allocated structure will be passed, so that the appropriate size information can be accessed. If the size value associated with any specified field is -1 or -2, the t_alloc subroutine will be unable to determine the size of the buffer to allocate; it then fails, setting the t_errno variable to TSYSERR and the errno global variable to EINVAL. For any field not specified in the fields parameter, the buf field is set to null and the maxlen field is set to 0.

Return Values

On successful completion, the t_alloc subroutine returns a pointer to the newly allocated structure. Otherwise, it returns a null pointer.

Error Codes

On failure, the t_errno variable is set to one of the following:

Value Description
TBADF The specified file descriptor does not refer to a transport end point.
TNOSTRUCTYPE Unsupported structure type requested. This can include a request for a structure type which is inconsistent with the transport provider type specified, for example, connection-oriented or connectionless.
TSYSERR A system error has occurred during execution of this function.