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.

Item

Description

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.