 |
Index for
Section 3 |
|
 |
Alphabetical
listing for T |
|
 |
Bottom of
page |
|
t_alloc(3)
NAME
t_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 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.
PARAMETERS
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:
y This is a meaningful parameter.
n This is not a meaningful parameter.
fd 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.
struct_type
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.
fields
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,
tsdu
All relevant members of
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).
DESCRIPTION
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.
ERRORS
If the t_alloc() function fails, t_errno may be set to one of the following
values:
[TBADF]
The fd file descriptor does not refer to a valid transport endpoint.
[TSYSERR]
A system error occurred during execution of this function.
[TNOSTRUCTYPE]
An unsupported structure type is specified.
[TPROTO]
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).
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for T |
|
 |
Top of
page |
|