t_alloc(3xti)
Name
t_alloc − allocate a library structure
Syntax
#include <xti.h>
char *t_alloc(fd, struct_type, fields)
int fd;
int struct_type;
int fields;
Arguments
fdRefers to the transport endpoint through which the newly allocated structure is passed.
struct_type
Specifies the allocated structure where each structure can subsequently be used as an argument to one or more transport functions.
The struct_type argument must specify one of the following:
T_BIND_STR struct t_bind
T_CALL_STR struct t_call
T_OPTMGMT_STRstruct t_optmgmt
T_DIS_STR struct t_discon
T_UNITDATA_STRstruct t_unitdata
T_UDERROR_STR struct t_uderr
T_INFO_STR struct t_info
fieldsSpecifies which buffers to allocate, where the argument is the bitwise-OR of any of the following:
T_ADDRThe addr field of the t_bind, t_call, t_unitdata, or t_uderr structures (size obtained from info_addr).
T_OPTThe opt field of the t_optmgmt, t_call, t_unitdata, or t_uderr structures (size obtained from info_options).
T_UDATAThe udata field of the t_call, t_discon, or t_uderr structures (for T_CALL_STR, size is the maximum value of info_connect and info_discon; for T_DIS_STR, size is the value of info_discon; for T_UNITDATA_STR, size is the value of info_tsdu).
T_ALLAll relevant fields of the given structure.
Description
The t_alloc() function dynamically allocates memory for the various transport function argument structures as listed under the ARGUMENTS section. This function allocates memory for the specified structure and also allocates memory for buffers referenced by the structure.
Each of the accepted structures, except t_info(), contains at least one field of type struct netbuf. For each field of this type, the user can specify that the buffer for that field should be allocated as well. The length of the buffer allocated is based on the size information returned in the t_open() or t_getinfo().
For each field specified in fields, t_alloc() allocates memory for the buffer associated with the field and initializes the len field to zero and the buf pointer and maxlen field accordingly. Because the length of the buffer allocated is based on the same size information that is returned to the user on t_open() and t_getinfo(), fd must refer to the transport endpoint through which the newly allocated structure will be passed. In this way, the appropriate size information can be accessed. If the size value associated with any specified field is −1 or −2, t_alloc() will be unable to determine the size of the buffer to allocate and will fail, setting t_errno to [TSYSERR] and errno to [EINVAL]. For any field not specified in fields, buf will be set to NULL and maxlen will be set to zero.
Use of t_alloc() to allocate structures helps to ensure the compatibility of user programs with future releases of the transport interface functions.
| Parameters | Before Call | After Call |
| fd | x | / |
| struct_type | x | / |
| fields | x | / |
Return Values
Upon successful completion, t_alloc() returns a pointer to the newly allocated structure. On failure, NULL is returned.
Diagnostics
On failure, t_errno is set to one of the following:
[TBADF] The specified file descriptor does not refer to a transport endpoint.
[TNOTSUPPORT] This function is not supported by the current implementation of XTI.
[TSYSERR] A system error has occurred during execution of this function.
[TNOSTRUCTYPE] An unsupported struct_type has been requested.