| HGLOBAL GlobalReAlloc(hglb, cbNewSize, fuAlloc) | |||||
| HGLOBAL hglb; | /* handle of memory object to reallocate | */ | |||
| DWORD cbNewSize; | /* new size of object | */ | |||
| UINT fuAlloc; | /* how object is reallocated | */ | |||
The GlobalReAlloc function changes the size or attributes of the given global memory object.
hglb
Identifies the global memory object to be reallocated.
cbNewSize
Specifies the new size of the memory object.
fuAlloc
Specifies how to reallocate the global object. If this parameter includes GMEM_MODIFY, the GlobalReAlloc function ignores the cbNewSize parameter.
| Value | Meaning |
| GMEM_DISCARDABLE | Causes a previously movable object to become discardable. This flag can be used only with GMEM_MODIFY. |
| GMEM_MODIFY | Modifies the object's memory flags. This flag can be used with GMEM_DISCARDABLE and GMEM_MOVEABLE. |
| GMEM_MOVEABLE | Causes a previously movable and discardable object to be discarded, if the cbNewSize parameter is zero and the object's lock count is zero. If cbNewSize is zero and the object is not movable and discardable, this flag causes the GlobalReAlloc function to fail. |
| If cbNewSize is nonzero and the object identified by the hglb parameter is fixed, this flag allows the reallocated object to be moved to a new fixed location. | |
| If a movable object is locked, this flag allows the object to be moved to a new locked location without invalidating the handle. This may occur even if the object is currently locked by a previous call to the GlobalLock function. | |
| If this flag is used with GMEM_MODIFY, the GlobalReAlloc function changes a fixed memory object to a movable memory object. | |
| GMEM_NODISCARD | Prevents memory from being discarded to satisfy the allocation request. This flag cannot be used with GMEM_MODIFY. |
| GMEM_ZEROINIT | Causes the additional memory to be initialized to zero if the object is growing. This flag cannot be used with GMEM_MODIFY. |
The return value is the handle of the reallocated global memory if the function is successful. It is NULL if the object cannot be reallocated as specified.
If GlobalReAlloc reallocates a movable object, the return value is a handle to the memory. To access the memory, an application must use the GlobalLock function to convert the handle to a pointer.
To free a global memory object, an application should use the GlobalFree function.
The GMEM_ZEROINIT flag will cause applications to fail if it is used as shown in the following sequence:
hMem = GlobalAlloc(GMEM_ZEROINIT | (other flags), dwSize1);
.
.
.
hMem = GlobalReAlloc(hMem, dwSize2, GMEM_ZEROINIT | (other flags));
/* where dwSize2 > dwSize1. */
.
.
.
hMem = GlobalReAlloc(hMem, dwSize3, GMEM_ZEROINIT | (other flags));
/* where dwSize3 < dwSize2. */
.
.
.
hMem = GlobalReAlloc(hMem, dwSize4, GMEM_ZEROINIT | (other flags));
/* GMEM_ZEROINIT fails when dwSize4 > dwSize3. */In the last step of the preceding example, the memory between dwSize3 and the internal allocation boundary is not set to zero. After the last step, the contents of the buffer equal its contents prior to the call to GlobalReAlloc that specified dwSize3.