IMalloc::Realloc
Changes the
size of a previously allocated memory block.
void *Realloc(
|
void *pv, |
//Pointer to memory block to be reallocated |
|
ULONG cb |
//Size of the memory block in bytes |
|
); |
|
Parameters
pv
[in] Pointer
to the memory block to be reallocated. The pointer can have a NULL value, as
discussed in the following Remarks section.
cb
[in] Size of
the memory block (in bytes) to be reallocated. It can be zero, as discussed in
the following remarks.
Return Values
Reallocated
memory block
Memory block
successfully reallocated.
NULL
Insufficient
memory or cb is zero and pv is not NULL.
Remarks
IMalloc::Realloc reallocates a block of memory, but does guarantee
that the contents of the returned memory block are initialized. Therefore, the
caller is responsible for intializing it in code, subsequent to the
reallocation. The allocated block may be larger than cb bytes because of
the space required for alignment and for maintenance information.
The pv
argument points to the beginning of the memory block. If pv is NULL, IMalloc::Realloc
allocates a new memory block in the same way that IMalloc::Alloc does. If pv is not
NULL, it should be a pointer returned by a prior call to IMalloc::Alloc.
The cb
argument specifies the size (in bytes) of the new block. The contents of the
block are unchanged up to the shorter of the new and old sizes, although the
new block can be in a different location. Because the new block can be in a
different memory location, the pointer returned by IMalloc::Realloc is
not guaranteed to be the pointer passed through the pv argument. If pv
is not NULL and cb is zero, then the memory pointed to by pv is
freed.
IMalloc::Realloc returns a void pointer to the reallocated (and
possibly moved) memory block. The return value is NULL if the size is zero and
the buffer argument is not NULL, or if there is not enough memory available to
expand the block to the given size. In the first case, the original block is
freed; in the second, the original block is unchanged.
The storage
space pointed to by the return value is guaranteed to be suitably aligned for
storage of any type of object. To get a pointer to a type other than void,
use a type cast on the return value.
See Also
IMalloc::Alloc, IMalloc::Free