Section 3c - C Functions

ATMI C Function Reference

tpalloc(3c)

Name

tpalloc()—Routine for allocating typed buffers.

Synopsis

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

Description

tpalloc() returns a pointer to a buffer of type type. Depending on the type of buffer, both subtype and size are optional. The BEA Tuxedo ATMI system provides a variety of typed buffers, and applications are free to add their own buffer types. Consult tuxtypes(5) for more details.

If subtype is non-NULL in tmtype_sw for a particular buffer type, then subtype must be specified when tpalloc() is called. The allocated buffer will be at least as large as the larger of size and dfltsize, where dfltsize is the default buffer size specified in tmtype_sw for the particular buffer type. For buffer type STRING the minimum is 512 bytes; for buffer types FML and VIEW the minimum is 1024 bytes.

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 BEA Tuxedo ATMI system-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 routine cleared the buffer, the buffer is not initialized to zeros by tpalloc().

A thread in a multithreaded application may issue a call to tpalloc() while running in any context state, including TPINVALIDCONTEXT.

Return Values

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 condition.

Errors

Upon failure, tpalloc() sets tperrno to one of the following values:

[TPEINVAL]

Invalid arguments were given (for example, type is NULL).

[TPENOENT]

No entry in tmtype_sw matches type and, if non-NULL, subtype.

[TPEPROTO]

tpalloc() was called improperly.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

Usage

If buffer initialization 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()).

Two buffer types are supported by any compliant implementation of the BEA Tuxedo ATMI system extension. Details are in the Introduction to the C Language Application-to-Transaction Monitor Interface.