NAME
t_alloc() — allocate a library structure
SYNOPSIS
#include <xti.h> /* for X/OPEN Transport Interface - XTI */
/* or */
#include <tiuser.h> /* for Transport Layer Interface - TLI */
char *t_alloc (fd, struct_type, fields);
int fd;
int struct_type;
int fields;
DESCRIPTION
The
t_alloc()
function dynamically allocates memory for the
various transport function argument structures as specified below.
This function will allocate memory for the specified structure and
will also allocate memory for buffers referenced by the structure.
The structure to allocate is specified by
struct_type
and must be one of the following:
where each of these structures may subsequently be used as an argument to
one or more transport functions.
Each of the above structures, except T_INFO, contains at least one field of
type
struct netbuf.
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 returned
in the
info
argument of
t_open()
or
t_getinfo().
The relevant fields of the
info
argument are described in the following list.
The
fields
argument specifies which buffer to allocate, where the
argument is the bitwise-OR of any of the following:
- T_ADDR
The
addr
field of the
t_bind,
t_call,
t_unitdata,
or
t_uderr
structures.
- T_OPT
The
opt
field of the
t_optmgmt,
t_call,
t_unitdata,
or
t_uderr
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
e transport provider specified by
fd
will not be allocated (info
values are <= 0).
For each field specified in
fields,
t_alloc()
will allocate memory for the
buffer associated with the field, and initialize the
len
field to zero
and the
buf
pointer and
maxlen
field accordingly. Since the length
of the buffer allocated will be based on the same size information that is
returned to the user on
t_open()
or
t_getinfo(),
fd
must refer to the transport endpoint through which the newly allocated
structure will be passed. In this way the appropriate size information
can be accessed. If
the size value associated with any specified field is -1 or -2 ( see
t_open(3)
or
t_getinfo(3)),
t_alloc()
will be unable to determine the
size of the buffer to allocate and will fail, setting
t_errno
to [TSYSERR] and
errno
to [EINVAL]. For any field not specified in
fields,
buf
will be set to a null pointer and
maxlen
will be set to zero.
Use of
t_alloc()
to allocate structures will help ensure the compatibility
of user programs with future releases of the transport interface functions.
Thread-Safeness
The
t_alloc()
function is safe to be called by multithreaded applications, and it is
thread-safe for both POSIX Threads and DCE User Threads.
It has a cancellation point.
It is neither async-cancel safe nor async-signal safe.
Finally, it is not fork-safe.
Valid States
All - apart from
T_UNINIT
RETURN VALUE
Upon successful completion,
t_alloc()
returns a pointer to the newly
allocated structure. On failure, a null pointer is returned.
ERRORS
On failure,
t_errno
is set to one of the following:
- [TBADF]
fd
The specified endpoint identifier does not refer to a transport endpoint
- [TSYSERR]
A system error has occurred during execution of this function.
- [TPROTO]
(XTI only) This error indicates that a communication problem has been detected
between XTI and the transport provider for which there is no suitable XTI (t_errno).
- [TNOSTRUCTYPE]
Unsupported
struct_type
requested. This can include a request
for a structure type which is inconsistent with the transport provider type
specified, that is, connection-oriented or connectionless.
STANDARDS CONFORMANCE
R t_alloc() ": SVID2, XPG3, XPG4"
