|
Description
The transport user calls the t_alloc() function to reserve memory dynamically for various types of structures. t_alloc() returns a pointer to the reserved structure object. Every structure object created with t_alloc() can be passed as a current parameter when specific XTI functions are called.
The user must specify the transport endpoint over which the structure object created with t_alloc() is passed when an XTI function is called (e.g. t_bind()), as the current parameter for fd. This allows t_alloc() to access the relevant size information. The size of the buffer that is created results from the same information that the user receives with t_open() and t_getinfo() for the transport endpoint concerned.
The struct_type parameter specifies the structure type. t_alloc() then reserves memory for the structure and for buffers to which this structure refers.
The user can specify the following values for struct_type when calling t_alloc():
T_BIND (for struct t_bind)
T_CALL (for struct t_call)
T_OPTMGMT (for struct t_optmgmt)
T_DIS (for struct t_discon)
T_UNITDATA (for struct t_unitdata)
T_UDERROR (for struct t_uderr)
T_INFO (for struct t_info)
Apart from t_info, all the above structures contain at least one component of type struct netbuf.
The netbuf structure is declared in <xti.h> as follows:
struct netbuf {
unsigned int maxlen;
unsigned int len;
char *buf;
};
The user sets the fields parameter to specify whether memory is also to be reserved for the buffer for each netbuf structure in the structure specified by struct_type. fields is formed by inclusive ORing of the bits in any combination of the values described below:
T_ADDR: addr component of the t_bind, t_call, t_unitdata or t_uderr structures
T_OPT: opt component of the t_optmgmt, t_call, t_unitdata or t_uderr structures
T_UDATA: udata component of the t_call, t_discon or t_unitdata structures
T_ALL: all relevant components of the structure specified by struct_type
t_alloc() reserves memory for the buffer assigned to each netbuf structure specified by the fields parameter. t_alloc() also correspondingly initializes the buf pointer and the value of maxlen in the separate netbuf structures.
If the value of maxlen in any of the netbuf structures specified by fields has the value -1 or-2 (see t_open() or t_getinfo()), t_alloc() cannot determine the size of the buffer and terminates with an error. t_errno is set to TSYSERR and errno to EINVAL. For each netbuf structure not specified in fields, buf is set to NULL and maxlen to 0.
Return value
If execution was successful, t_alloc() returns a pointer to the newly created structure.
In an error occurs, the null pointer is returned and t_ errno is set to indicate the error.
Errors
TBADF
The specified file descriptor does not reference a transport endpoint.
TSYSERR
A system error occurred during execution of this function.