t_alloc Subroutine for X/Open Transport Interface

Purpose

Allocate a library structure.

Library

X/Open Transport Interface Library (libxti.a)

Syntax

#include <xti.h>

void *t_alloc (
int fd
int struct_type,
int fields)

Description

The t_alloc subroutine dynamically allocates memory for the various transport function parameter 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 helps ensure the compatibility of user programs with future releases of the transport interface functions.

Parameters

Item	Description
fd	Specifies the transport endpoint through which the newly allocated structure will be passed.
struc_type	Specifies the structure to be allocated. The possible values are: 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. For each field of this type, the user may specify that the buffer for that field should be allocated as well. The length of the buffer allocated will be equal to or greater than the appropriate size as returned in the info paramenter of the t_open or t_getinfo subroutines.
fields	Specfies whether the buffer should be allocated for each field type. The fields parameter specifies which buffers to allocate, 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_underr structures. T_OPT The opt field of the t_optmgmt, t_call, t_unitdata or t_underr structures. T_UDATA The udata field of the t_call, t_discon or t_unitdata structures. T_ALL All relevant fields of the given structure. Fields which are not supported by the transport provider specified by the fd parameter are not allocated. For each relevant field specified in the fields parameter, the t_alloc subroutine allocates memory for the buffer associated with the field and initializes the len field to zero and initializes the buf pointer and maxlen field accordingly. Irrelevant or unknown values passed in fields are ignored. The length of the buffer allocated is based on the same size information returned to the user on a call to the t_open and t_getinfo subroutines. Thus, the fd paramenter must refer to the transport endpoint through which the newly allocated structure is passed so that the appropriate size information is accessed. If the size value associated with any specified field is -1 or -2, (see the t_open or t_getinfo subroutines), the t_alloc subroutine is unable to determine the size of the buffer to allocate and fails, setting t_errno to TSYSERR and errno to EINVAL. For any field not specified in fields, buf will be set to the null pointer and len and maxlen will be set to zero.

Item

Description

Specifies the transport endpoint through which the newly allocated structure will be passed.

struc_type

Specifies the structure to be allocated. The possible values are:

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. For each field of this type, the user may specify that the buffer for that field should be allocated as well. The length of the buffer allocated will be equal to or greater than the appropriate size as returned in the info paramenter of the t_open or t_getinfo subroutines.

fields

Specfies whether the buffer should be allocated for each field type. The fields parameter specifies which buffers to allocate, 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_underr structures.
T_OPT: The opt field of the t_optmgmt, t_call, t_unitdata or t_underr structures.
T_UDATA: The udata field of the t_call, t_discon or t_unitdata structures.
T_ALL: All relevant fields of the given structure. Fields which are not supported by the transport provider specified by the fd parameter are not allocated.

For each relevant field specified in the fields parameter, the t_alloc subroutine allocates memory for the buffer associated with the field and initializes the len field to zero and initializes the buf pointer and maxlen field accordingly. Irrelevant or unknown values passed in fields are ignored. The length of the buffer allocated is based on the same size information returned to the user on a call to the t_open and t_getinfo subroutines. Thus, the fd paramenter must refer to the transport endpoint through which the newly allocated structure is passed so that the appropriate size information is accessed. If the size value associated with any specified field is -1 or -2, (see the t_open or t_getinfo subroutines), the t_alloc subroutine is unable to determine the size of the buffer to allocate and fails, setting t_errno to TSYSERR and errno to EINVAL. For any field not specified in fields, buf will be set to the null pointer and len and maxlen will be set to zero.

Valid States

ALL - apart from T_UNINIT.

Return Values

On successful completion, the t_alloc subroutinereturns a pointer to the newly allocated structure. On failure, a null pointer is returned.

Error Codes

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

Value	Description
TBADF	The specified file descriptor does not refer to a transport endpoint.
TSYSERR	A system error has occurred during execution of this function.
TNOSTRUCTYPE	Unsupported structure type (struct_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.
TPROTO	This error indicates that a communication problem has been detected between the X/Open Transport Interface and the transport provider for which there is no other suitable X/Open Transport Interface (t_errno).