XtRealloc() XtRealloc()
Name
XtRealloc - change the size of an allocated block of storage.
Synopsis
char *XtRealloc(ptr, num);
char *ptr;
Cardinal num;
Inputs
ptr Specifies a pointer to memory allocated with XtMalloc(), XtCalloc(), or XtRealloc(), or NULL.
num Specifies the new number of bytes of memory desired in the block.
Returns
A pointer to allocated memory.
Description
XtRealloc() changes the size of the block of allocated memory pointed to by ptr to be at least num bytes large. In order to make this size
change, it may have to allocate a new block of memory and copy the contents of the old block (or as much as will fit) into the new block.
If it allocates a new block of memory, it frees the old block. In either case, it returns a pointer to a block of memory which is of the
requested size. If there is insufficient memory to allocate the new block, XtRealloc() terminates by calling XtErrorMsg().
If ptr is NULL, XtRealloc() simply calls XtMalloc() to allocate a block of memory of the requested size.
Usage
Note that XtRealloc() may move the contents of your allocated memory to a new location; the return value may or may not be the same as ptr.
Not all memory can be safely reallocated. If there are multiple pointers to a block of memory scattered through out an application (such
as pointers to a widget record), then reallocating that memory is not safe, because all pointers to it cannot be updated. Other memory
(such as the array of children maintained privately by the Composite widget class) can be safely updated because there should be only one
pointer to it in the application (in this case the pointer is the composite.children field of the widget). These cautions are no different
than those required with the standard realloc() function.
In most cases, you will have to cast the return value of XtRealloc() to an appropriate pointer type.
Note that because XtRealloc() behaves like XtMalloc() when passed a NULL pointer, (something that realloc() does not do), you don't have to
write special case code to allocate the first chunk of memory with XtMalloc() and subsequent chunks with XtRealloc(); you can simply use
XtRealloc() everywhere.
Memory allocated with XtRealloc() must be deallocated with XtFree(). The function XtRealloc() is implemented by the Toolkit independently
of the particular environment, so programs ported to a system not supporting malloc will still work.
See Also
XtCalloc(1), XtFree(1), XtMalloc(1), XtNew(1), XtNewString(1).
Xt - Memory Allocation XtRealloc()