tpalloc - Allocate a typed buffer

ANSI C, C++

#include <xatmi.h>
char *tpalloc (char *type, char *subtype, long size)

K&R C

#include <xatmi.h>
char  *tpalloc (type, subtype, size)
char  *type;
char  *subtype;
long  size

The function tpalloc() returns a pointer to a buffer of type type. Depending on the type of buffer, both subtype and size are optional.

If multiple subtypes are available for a particular buffer type, subtype must be specified when tpalloc() is called. If the type specified does not have a subtype, *subtype is ignored (and may be null). The allocated buffer is at least as large as size.

Note that only the first eight bytes of type and the first 16 bytes of subtype are significant.

Because some buffer types require initialization before they can be used, tpalloc() initializes a buffer (in a communication-resource-manager-specific manner) after it is allocated and before it is returned. Thus, the buffer returned to the caller is ready for use. Note that unless the initialization processing cleared the buffer, the buffer is not initialized to zeros by tpalloc().

<<type

Specify the type name.>>

<<subtype

Specify the subtype name.>>

<<size

Specify the size of the buffer to be allocated.>>

Upon successful completion, tpalloc() returns a pointer to a buffer of the appropriate type aligned on a long word. Otherwise it returns NULL and sets tperrno to indicate the error condition.

Errors

Under the following conditions, tpalloc() fails and sets tperrno to one of the following values:

Return value	Return value (numeric)	Explanation
TPEINVAL	4	Invalid arguments were given (for example, type is NULL).
TPENOENT	6	The value for type or subtype does not exist.
TPEPROTO	9	tpalloc() was called in an improper context.
TPESYSTEM	12	A communication resource manager system error has occurred. The exact nature of the error is determined in a product-specific manner.
TPEOS	7	An operating system error has occurred. The exact nature of the error is determined in a product-specific manner.

If buffer initialization processing fails, the allocated buffer is freed and tpalloc() fails returning NULL.

This function should not be used in concert with malloc(), realloc() or free() in the C library (for example, a buffer allocated with tpalloc() should not be freed with free()).

<<Under the OpenTP1, the buffer returned by the function tpalloc() is initialized to 0.>>
<<The behavior caused by XATMI errors encountered during OSI TP communication may be different from the behavior caused by errors encountered conventional TCP/IP communication.>>