OpenTP1 Version 7 Programming Reference C Language
tpalloc - Allocate a typed buffer
Format
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 |
Description
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().
<<Arguments>>
<<type
Specify the type name.>>
<<subtype
Specify the subtype name.>>
<<size
Specify the size of the buffer to be allocated.>>
Return value
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. |
Application usage
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()).
See also
tpfree(), tprealloc(), tptypes().
<<Notes on use with OpenTP1>>
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.