t_alloc(3)t_alloc(3)NAMEt_alloc - Allocate a library structure
SYNOPSIS
#include <xti.h>
char *t_alloc(
int fd,
int struct_type,
int fields );
LIBRARY
XTI Library (libxti.a)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
t_alloc(): XNS4.0, XNS5.0
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 param‐
eters before and after t_alloc() is called:
───────────────────────────────────────
Parameters Before Call After Call
───────────────────────────────────────
fd y n
struct_type y n
fields y n
───────────────────────────────────────
Notes to table: This is a meaningful parameter. This is not a meaning‐
ful 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 Name Structure Type Using Function
──────────────────────────────────────────────────────────
T_BIND struct t_bind t_bind()
T_CALL struct t_call t_accept(), t_con‐
nect(), t_listen(),
t_rcvconnect(),
t_snddis()
T_OPTMGMT struct t_optmgmt t_optmgmt()
T_DIS struct t_discon t_rcvdis()
T_UNITDATA struct t_unitdata t_rcvudata(), t_sndu‐
data()
T_UDERROR struct t_uderr t_rcvuderr()
T_INFO struct t_info t_info()
──────────────────────────────────────────────────────────
The structures listed in the Structure Type column of the pre‐
ceding 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_get‐
info() functions. Refer to the description of the fields parame‐
ter 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 func‐
tion. The following table lists the symbolic name that must be
specified for the fields parameter, identifies the t_info struc‐
ture member that is the source of relevant size information, and
lists the XTI function structure reference for which t_info Mem‐
ber 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.
──────────────────────────────────────────────────────────────
Symbol Name t_info Member Structure Reference
──────────────────────────────────────────────────────────────
T_ADDR addr Member addr of structures
t_bind, t_call, t_unit‐
data, t_underr.
T_OPT options Member opt of structures
t_optmgmt, t_call, t_unit‐
data, t_underr.
T_UDATA tsdu Member udata of structures
t_call, t_discon, t_unit‐
data.
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 mem‐
ber discon of structure
t_info.
For struct_type T_UNIT‐
DATA, size is the value of
member tsdu of structure
t_info.
T_ALL addr, options, All relevant members of
tsdu 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 mem‐
ber 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).
DESCRIPTION
The t_alloc() XTI memory utility function is used to dynamically allo‐
cate memory for structures required by various XTI transport interface
functions. The structure to allocate is specified by a structure sym‐
bolic 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 corre‐
sponding XTI transport interface functions in which the allocated
structures are used.
ERRORS
If the t_alloc() function fails, t_errno may be set to one of the fol‐
lowing values:
The fd file descriptor does not refer to a valid transport endpoint. A
system error occurred during execution of this function. An unsup‐
ported structure type is specified. This error indicates that a commu‐
nication problem has been detected between XTI and the transport
provider for which there is no other suitable XTI (t_errno).
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).
RETURN VALUE
Upon successful completion, this function returns a pointer to the
newly allocated structure. Upon failure, a null pointer is returned.
SEE ALSO
Functions: t_free(3), t_getinfo(3), t_open(3)
Standards: standards(5).
Network Programmer's Guide
t_alloc(3)
