PURPOSE

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. System/T 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 System/T-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().

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

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

[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 in an improper context.
[TPESYSTEM]: A System/T 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(3C), realloc(3C), or free(3C) in the C library (for example, a buffer allocated with tpalloc() should not be freed with free()).