t_alloc Subroutine for Transport Layer Interface

Communications Technical Reference, Volume 2

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

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:

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.

Implementation Specifics

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

Related Information

The t_free subroutine, t_getinfo subroutine, t_open subroutine.

List of Streams Programming References and STREAMS Overview in AIX Version 4.3 Communications Programming Concepts.