t_alloc - Allocate a library structure
#include <xti.h>
char *t_alloc(
int fd,
int struct_type,
int fields );
XTI Library (libxti.a)
Interfaces documented on this reference page conform to
industry standards as follows:
t_alloc(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
The following table summarizes the relevance of input and
output parameters 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 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 Name Structure Type Using Function
----------------------------------------------------------
T_BIND struct t_bind t_bind()
T_CALL struct t_call t_accept(), t_connect(),
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_sndudata()
T_UDERROR struct t_uderr t_rcvuderr()
T_INFO struct t_info t_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.
--------------------------------------------------------------
Symbol Name t_info Member Structure Reference
--------------------------------------------------------------
T_ADDR addr Member addr of structures
t_bind, t_call, t_unitdata,
t_underr.
T_OPT options Member opt of structures
t_optmgmt, t_call, t_unitdata,
t_underr.
T_UDATA tsdu 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_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 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).
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.
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).
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).
Upon successful completion, this function returns a
pointer to the newly allocated structure. Upon failure, a
null pointer is returned.
Functions: t_free(3), t_getinfo(3), t_open(3)
Standards: standards(5).
Network Programmer's Guide
t_alloc(3)
[ Back ] |
