GlobalReAlloc

The GlobalReAlloc function changes the size or attributes of a specified global memory object. The size can increase or decrease.

Note  The global functions are slower than other memory management functions and do not provide as many features. Therefore, new applications should use the heap functions. However, the global functions are still used with DDE and the clipboard functions.

HGLOBAL GlobalReAlloc(
  HGLOBAL hMem,   // handle to global memory object
  SIZE_T dwBytes, // new block size
  UINT uFlags     // how to reallocate object
);

Parameters

hMem

[in] Handle to the global memory object to be reallocated. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

dwBytes

[in] Specifies the new size, in bytes, of the memory block. If uFlags specifies GMEM_MODIFY, this parameter is ignored.

uFlags

[in] Specifies how to reallocate the global memory object. If GMEM_MODIFY is specified, this parameter modifies the attributes of the memory object, and the dwBytes parameter is ignored. Otherwise, this parameter controls the reallocation of the memory object.

You can combine GMEM_MODIFY with one or both of the following values.

Value	Meaning
GMEM_DISCARDABLE	Ignored. This value is provided only for compatibility with 16-bit Windows. In Win32, you must explicitly call the GlobalDiscard function to discard a block. In 16-bit Windows, allocates discardable memory, if GMEM_MODIFY is also specified. This value is ignored if the object was not previously allocated as movable or if GMEM_MOVEABLE is not specified.
GMEM_MOVEABLE	If GMEM_MODIFY is also specified, GMEM_MOVEABLE changes a fixed memory object to a movable memory object. If GMEM_MODIFY is not specified, then GMEM_MOVEABLE allows a locked GMEM_MOVEABLE memory block or a GMEM_FIXED memory block to be moved to a new fixed location. If neither GMEM_MODIFY nor GMEM_MOVEABLE is set, then fixed memory blocks and locked movable memory blocks will only be reallocated in place.

If this parameter does not specify GMEM_MODIFY, it can also be any combination of the following values.

Value	Meaning
GMEM_NOCOMPACT	Ignored. This value is provided only for compatibility with 16-bit Windows.
GMEM_ZEROINIT	Causes the additional memory contents to be initialized to zero if the memory object is growing in size.

Return Values

If the function succeeds, the return value is a handle to the reallocated memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If GlobalReAlloc reallocates a movable object, the return value is a handle to the memory object. To convert the handle to a pointer, use the GlobalLock function.

If GlobalReAlloc reallocates a fixed object, the value of the handle returned is the address of the first byte of the memory block. To access the memory, a process can simply cast the return value to a pointer.

If GlobalReAlloc fails, the original memory is not freed, and the original handle and pointer are still valid.

Windows 95/98: The heap managers are designed for memory blocks smaller than four megabytes. If you expect your memory blocks to be larger than one or two megabytes, you can avoid significant performance degradation by using the VirtualAlloc or VirtualAllocEx function instead.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

Memory Management Overview, Memory Management Functions, GlobalAlloc, GlobalDiscard, GlobalLock