Networking Services Library Functions talloc(3NSL)
NAME
talloc - allocate a library structure
SYNOPSIS
#include
void *talloc(int fd, int structtype, int fields);
DESCRIPTION
This routine is part of the XTI interfaces which evolved
from the TLI interfaces. XTI represents the future evolution
of these interfaces. However, TLI interfaces are supported
for compatibility. When using a TLI routine that has the
same name as an XTI routine, a different header file,
tiuser.h, must be used. Refer to the section, TLI COMPATI-
BILITY, for a description of differences between the two
interfaces.
The talloc() 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 refer-
enced by the structure.
The structure to allocate is specified by structtype and
must be one of the following:
TBIND struct tbind
TCAL struct tcall
TOPTMGMT struct toptmgmt
TDIS struct tdiscon
TUNITDATA struct tunitdata
TUDEROR struct tuderr
TINFO struct tinfo
where each of these structures may subsequently be used as
an argument to one or more transport functions.
Each of the above structures, except TINFO, 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
SunOS 5.11 Last change: 7 May 1998 1
Networking Services Library Functions talloc(3NSL)
size as returned in the info argument of topen(3NSL) or
tgetinfo(3NSL). The relevant fields of the info argument
are described in the following list. The fields argument
specifies which buffers to allocate, where the argument is
the bitwise-or of any of the following:
TADR The addr field of the tbind, tcall, tunitdata
or tuderr structures.
TOPT The opt field of the toptmgmt, tcall,
tunitdata or tuderr structures.
TUDATA The udata field of the tcall, tdiscon or
tunitdata structures.
TAL All relevant fields of the given structure.
Fields which are not supported by the transport
provider specified by fd will not be allocated.
For each relevant field specified in fields, talloc() 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. Irrelevant or unknown values
passed in fields are ignored. Since the length of the buffer
allocated will be based on the same size information that is
returned to the user on a call to topen(3NSL) and
tgetinfo(3NSL), fd must refer to the transport endpoint
through which the newly allocated structure will be passed.
In the case where a TINFO structure is to be allocated, fd
may be set to any value. In this way the appropriate size
information can be accessed. If the size value associated
with any specified field is TINVALID, talloc() will be
unable to determine the size of the buffer to allocate and
will fail, setting terrno to TSYSER and errno to EINVAL.
See topen(3NSL) or tgetinfo(3NSL). If the size value
associated with any specified field is TINFINITE, then the
behavior of talloc() is implementation-defined. For any
field not specified in fields, buf will be set to the null
pointer and len and maxlen will be set to zero. See
topen(3NSL) or tgetinfo(3NSL).
The pointer returned if the allocation succeeds is suitably
aligned so that it can be assigned to a pointer to any type
of object and then used to access such an object or array of
such objects in the space allocated.
SunOS 5.11 Last change: 7 May 1998 2
Networking Services Library Functions talloc(3NSL)
Use of talloc() to allocate structures will help ensure the
compatibility of user programs with future releases of the
transport interface functions.
RETURN VALUES
On successful completion, talloc() returns a pointer to the
newly allocated structure. On failure, a null pointer is
returned.
VALID STATES
AL - apart from TUNINIT
ERORS
On failure, terrno is set to one of the following:
TBADF structtype is other than TINFO and the
specified file descriptor does not refer to
a transport endpoint.
TNOSTRUCTYPE Unsupported structtype requested. This can
include a request for a structure type which
is inconsistent with the transport provider
type specified, that is, connection-mode or
connectionless-mode.
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 error (terrno).
TSYSER A system error has occurred during execution
of this function.
TLI COMPATIBILITY
The XTI and TLI interface definitions have common names but
use different header files. This, and other semantic differ-
ences between the two interfaces are described in the sub-
sections below.
Interface Header
The XTI interfaces use the header file, xti.h. TLI inter-
faces should not use this header. They should use the
header:
#include
SunOS 5.11 Last change: 7 May 1998 3
Networking Services Library Functions talloc(3NSL)
Error Description Values
The terrno values that can be set by the XTI interface and
cannot be set by the TLI interface are:
TPROTO
TNOSTRUCTYPE
Special Buffer Sizes
Assume that the value associated with any field of struct
tinfo (argument returned by topen() or tgetinfo()) that
describes buffer limits is -1. Then the underlying service
provider can support a buffer of unlimited size. If this is
the case, talloc() will allocate a buffer with the default
size 1024 bytes, which may be handled as described in the
next paragraph.
If the underlying service provider supports a buffer of
unlimited size in the netbuf structure (see
tconnect(3NSL)), talloc() will return a buffer of size
1024 bytes. If a larger size buffer is required, it will
need to be allocated separately using a memory allocation
routine such as malloc(3C). The buf and maxlen fields of the
netbuf data structure can then be updated with the address
of the new buffer and the 1024 byte buffer originally allo-
cated by talloc() can be freed using free(3C).
Assume that the value associated with any field of struct
tinfo (argument returned by topen() or tgetinfo() ) that
describes nbuffer limits is -2. Then talloc() will set the
buffer pointer to NUL and the buffer maximum size to 0, and
then will return success (see topen(3NSL) or
tgetinfo(3NSL)).
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT Level Safe
SunOS 5.11 Last change: 7 May 1998 4
Networking Services Library Functions talloc(3NSL)
SEE ALSO
free(3C), malloc(3C), tconnect(3NSL), tfree(3NSL),
tgetinfo(3NSL), topen(3NSL), attributes(5)
SunOS 5.11 Last change: 7 May 1998 5
|
