[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Communications, Volume 2
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
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. |
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). |
Related Information
The t_free subroutine, t_getinfo subroutine, t_open
subroutine.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]