Content-type: text/html Man page of t_alloc

t_alloc

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

t_alloc - Allocates a library structure  

LIBRARY

XTI Library (libxti.a)  

SYNOPSIS

#include <xti.h>

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

STANDARDS

Interfaces documented on this reference page conform to industry standards as follows:

t_alloc: XPG4-UNIX

Refer to the standards(5) reference page for more information about industry standards and associated tags.  

PARAMETERS

The following table summarizes the relevance of input and output parameters before and after t_alloc() is called:

ParametersBefore CallAfter Call

fd@yn
struct_typeyn
fieldsyn
Notes to table:

y    This is a meaningful parameter.
n    This is not a meaningful parameter.
Specifies a file descriptor that identifies the local transport endpoint. Because the length of the allocated buffer is based on size information that is returned to the user on a call to the t_open() and t_getinfo() functions, the fd parameter must refer to the transport endpoint through which a newly allocated structure passes. Specifies the structure type for the function for which memory is to be allocated; the struct_type parameter must specify one of the symbolic names listed in the Symbolic Name column of the following table.
Symbolic NameStructure TypeUsing Function

T_BINDstruct t_bindt_bind()
T_CALLstruct t_call t_accept(), t_connect(), t_listen(), t_rcvconnect(), t_snddis()
T_OPTMGMTstruct t_optmgmtt_optmgmt()
T_DISstruct t_discont_rcvdis()
T_UNITDATAstruct t_unitdata t_rcvudata(), t_sndudata()
T_UDERRORstruct t_uderrt_rcvuderr()
T_INFOstruct t_infot_info()

The structures listed in the Structure Type column of the preceding table are referenced as a parameter in one or more of the various XTI transport service functions. Each structure type, except struct t_info, contains at least one member of structure type struct netbuf, which is defined in the xti.h include file. For each structure type in the preceding table, you may specify that the buffer for the struct netbuf member should be allocated as well. The length of the buffer allocated for the referenced structure member depends on protocol-specific size limits returned as info member information of the t_open() and t_getinfo() functions. Refer to the description of the fields parameter for the relevant sizes returned in info. Specifies buffers for t_info type structures that are allocated for members of structures named by the struct_type parameter for a given function. The following table lists the symbolic name that must be specified for the fields parameter, identifies the t_info structure member that is the source of relevant size information, and lists the XTI function structure reference for which t_info Member memory space is reserved. The value of this parameter must be the bitwise logical OR of any of the symbolic names listed in the Symbol Name column.

Symbolt_infoStructure
NameMemberReference

T_ADDRaddr Member addr of structures t_bind, t_call, t_unitdata, t_underr.
T_OPToptions Member opt of structures t_optmgmt, t_call, t_unitdata, t_underr.
T_UDATAtsdu Member udata of structures t_call, t_discon, t_unitdata.
For struct_type T_CALL, size is the greater value of members connect and discon of structure t_info.
For struct_type T_DIS, size is the value of member discon of structure t_info.
For struct_type T_UNITDATA, size is the value of member tsdu of structure t_info.
T_ALLaddr, options,
tsdu All relevant members of the specified structures.

For each field type specified by the fields parameter, the t_alloc() function reserves function memory for the associated buffer. Additionally, its len member is set to 0 (zero) and its buf pointer and maxlen members are initialized.

When the size value associated with any specified t_info structure member is -1 or -2 (see the t_open() or t_getinfo() functions), the t_alloc() function can not determine the size of the buffer, causing failure. On failure, t_errno is set to [TSYSERR] and errno is set to [EINVAL]. For any structure member not specified by this parameter, its buf member is set to the null pointer and its maxlen member is set to 0 (zero).  

VALID STATES

The t_alloc() function can be called in any transport provider state except T_UNINIT. (If called in T_UNIT, the function returns the TBADF error and an invalid fd).  

DESCRIPTION

The t_alloc() XTI memory utility function is used to dynamically allocate memory for structures required by various XTI transport interface functions. The structure to allocate is specified by a structure symbolic name used as a mnemonic. In most cases, the mnemonic is similar to the name of the corresponding function in which the structure is used.

The t_alloc() function allocates memory for the named structure as well as for other buffers referenced by the named structure. Use of this function to allocate structures ensures compatibility with the corresponding XTI transport interface functions in which the allocated structures are used.  

RETURN VALUE

Upon successful completion, this function returns a pointer to the newly allocated structure. Upon failure, a null pointer is returned.  

ERRORS

If the t_alloc() function fails, t_errno may be set to one of the following values:

The fd file descriptor does not refer to a valid transport endpoint. A system error occurred during execution of this function. An unsupported structure type is specified. This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI(t_errno).  

RELATED INFORMATION

Functions: t_free(3), t_getinfo(3), t_open(3) delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
VALID STATES
DESCRIPTION
RETURN VALUE
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:41:58 GMT, October 02, 2010