LocalReAlloc

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

Note  The local functions are slower than other memory management functions and do not provide as many features. Therefore, new applications should use the heap functions.

HLOCAL LocalReAlloc(
  HLOCAL hMem,    // handle to local memory object
  SIZE_T uBytes,  // new block size
  UINT uFlags     // how to reallocate object
);

Parameters

hMem

[in] Handle to the local memory object to be reallocated. This handle is returned by either the LocalAlloc or LocalReAlloc function.

uBytes

[in] New size, in bytes, of the memory block. If uFlags specifies LMEM_MODIFY, this parameter is ignored.

uFlags

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

You can combine LMEM_MODIFY with the following value.

Value	Meaning
LMEM_DISCARDABLE	Ignored. This value is provided only for compatibility with 16-bit Windows. In Win32, you must explicitly call the LocalDiscard function to discard a block.

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

Value	Meaning
LMEM_MOVEABLE	Allocates movable memory. Otherwise, the memory will only be reallocated in place. The return value is a handle to the memory object. To convert the handle to a pointer, use the LocalLock function.
LMEM_NOCOMPACT	Ignored. This value is provided only for compatibility with 16-bit Windows.
LMEM_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 LocalReAlloc fails, the original memory is not freed, and the original handle and pointer are still valid.

If LocalReAlloc 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.

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, LocalAlloc, LocalFree, LocalLock