Section 3c - C Functions

ATMI C Function Reference

tprealloc(3c)

Name

tprealloc()—Routine to change the size of a typed buffer.

Synopsis

#include <atmi.h>  
char * tprealloc(char *ptr, long size)

Description

tprealloc() changes the size of the buffer pointed to by ptr to size bytes and returns a pointer to the new (possibly moved) buffer. Similar to tpalloc(), the size of the 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. If the larger of the two is less than or equal to zero, then the buffer is unchanged and NULL is returned. A buffer's type remains the same after it is reallocated. After this function returns successfully, the returned pointer should be used to reference the buffer; ptr should no longer be used. The buffer's contents will not change up to the lesser of the new and old sizes.

Some buffer types require initialization before they can be used. tprealloc() reinitializes a buffer (in a communication manager-specific manner) after it is reallocated and before it is returned. Thus, the buffer returned to the caller is ready for use.

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

Return Values

Upon successful completion, tprealloc() returns a pointer to a buffer of the appropriate type aligned on a long word.

Upon failure, tprealloc() returns NULL and sets tperrno to indicate the error condition.

Errors

If the reinitialization function fails, tprealloc() fails, returning NULL and the contents of the buffer pointed to by ptr may not be valid. Upon failure, tprealloc() sets tperrno to one of the following values:

[TPEINVAL]

Invalid arguments were given (for example, ptr does not point to a buffer originally allocated by tpalloc()).

[TPEPROTO]

tprealloc() 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 reinitialization fails, tprealloc() fails returning NULL and the contents of the buffer pointed to by ptr may not be valid. This function should not be used in concert with malloc(), realloc() or free() in the C library (for example, a buffer allocated with tprealloc() should not be freed with free()).