|
|
| CFAllocatorReallocate | Header: CFBase.h |
Reallocates memory using the specified allocator.
void *CFAllocatorReallocate (
CFAllocatorRef allocator,
void *ptr,
CFIndex newsize,
CFOptionFlags hint
);
A reference of type CFAllocatorRef that refers to the allocator object to be used for reallocating memory. Pass a reference to a valid allocator or NULL to request the default allocator.
An untyped pointer to a block of memory that you want reallocated to a new size. If ptr is NULL and newsize is greater than zero, memory is allocated (using the allocate function callback of the allocator's context). If ptr is NULL and newsize is zero, the result is NULL.
An integer value of type CFIndex. Pass the number of bytes you want allocated. If you pass zero and the ptr parameter is non-NULL, the block of memory that ptr points to is typically deallocated. If you pass zero for this parameter and the ptr parameter is NULL, nothing happens and the result returned is NULL.
A bitfield of type CFOptionsFlags. Pass flags to the allocator that suggest how memory is to be allocated. Zero indicates no hints.
An untyped pointer to a block of memory. The result is NULL if there was a problem allocating memory or if no allocation was requested.
The CFAllocatorReallocate function's primary purpose is to reallocate a block of memory to a new (and usually larger) size. However, based on the values passed in certain of the parameters, this function can also allocate memory afresh or deallocate a given block of memory. The following summarizes the semantical combinations:
* If the ptr parameter is non-NULL and the newsize parameter is greater than zero, the behavior is to reallocate.
* If the ptr parameter is NULL and the newsize parameter is greater than zero, the behavior is to allocate.
* If the ptr parameter is non-NULL and the newsize parameter is zero, the behavior is to deallocate.
The result of the CFAllocatorReallocate function is either an untyped pointer to a block of memory or NULL. A NULL result indicates either a failure to allocate memory or some other outcome, the precise interpretation of which is determined by the values of certain parameters and the presence or absence of callbacks in the allocator context. To summarize, a NULL result can mean one of the following:
* An error occurred in the attempt to allocate memory, such as insufficient free space.
* No allocate, reallocate, or deallocate function callback (depending on parameters) was defined in the allocator context.
* The semantic operation is "deallocate" (that is, there is no need to return anything).
* The ptr parameter is NULL and the requested size is zero.