LocalReAlloc

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

This function is provided only for compatibility with 16-bit versions of Windows.

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

Parameters

hMem

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

uBytes

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

uFlags

Flag that specifies how to reallocate the local memory object. If the LMEM_MODIFY flag 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.

The LMEM_MODIFY flag can be combined with either or both of the following flags:

Flag	Meaning
LMEM_DISCARDABLE	Ignored. This flag is provided only for compatibility with 16-bit Windows. In Win32, you must explicitly call the LocalDiscard function to discard a block. In 16-bit Windows, this flag allocates discardable memory if the LMEM_MODIFY flag is also specified. This flag is ignored if the object was not previously allocated as movable or if the LMEM_MOVEABLE flag is not specified.
LMEM_MOVEABLE	You cannot combine LMEM_MOVEABLE with LMEM_MODIFY to change a fixed memory object into a movable one. If you do so, the function returns an error.

If this parameter does not specify LMEM_MODIFY, this parameter can be any combination of the following flags:

Flag	Meaning
LMEM_MOVEABLE	In 16-bit Windows, if uBytes is zero, this flag discards a previously movable and discardable memory block. If the object's lock count is not zero or the block is not movable and discardable, the function fails. If uBytes is nonzero, this flag enables the system to move the reallocated block to a new location without changing the movable or fixed attribute of the memory object. If the object is fixed, the handle returned may be different from the handle specified in the hMem parameter. If the object is movable, the block can be moved without invalidating the handle, even if the object is currently locked by a previous call to the LocalLock function. To get the new address of the memory block, use LocalLock.
LMEM_NOCOMPACT	Ignored. This flag 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 movable object, the return value is a handle to the memory object. To convert the handle to a pointer, use the LocalLock function.

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 CE: Windows CE does not support the LMEM_DISCARDABLE and LMEM_NOCOMPACT flags for the uFlags parameter.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Requires version 1.0 or later.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.

See Also

Memory Management Overview, Memory Management Functions, LocalAlloc, LocalFree, LocalLock