LocalAlloc

The LocalAlloc function allocates the specified number of bytes from the heap. Win32 memory management does not provide a separate local heap and global heap.

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

HLOCAL LocalAlloc(
  UINT uFlags,  // allocation attributes
  UINT uBytes   // number of bytes to allocate
);
 

Parameters

uFlags

Specifies how to allocate memory. If zero is specified, the default is the LMEM_FIXED flag. Except for the incompatible combinations that are specifically noted, any combination of the following flags can be specified. To indicate whether the function allocates fixed or movable memory, specify one of the first six flags:

Flag	Meaning
LMEM_FIXED	Allocates fixed memory. The return value is a pointer to the memory object.
LMEM_MOVEABLE	Allocates movable memory. In Win32, memory blocks are never moved in physical memory, but they can be moved within the default heap. The return value is a handle to the memory object. To translate the handle to a pointer, use the LocalLock function. This flag cannot be combined with the LMEM_FIXED flag.
LPTR	Combines the LMEM_FIXED and LMEM_ZEROINIT flags.
LHND	Combines the LMEM_MOVEABLE and LMEM_ZEROINIT flags.
NONZEROLHND	Same as the LMEM_MOVEABLE flag.
NONZEROLPTR	Same as the LMEM_FIXED flag.
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. This flag cannot be combined with the LMEM_FIXED flag.
LMEM_NOCOMPACT	Ignored. This flag is provided only for compatibility with 16-bit Windows.
LMEM_NODISCARD	Ignored. This flag is provided only for compatibility with 16-bit Windows.
LMEM_ZEROINIT	Initializes memory contents to zero.

uBytes

Specifies the number of bytes to allocate. If this parameter is zero and the uFlags parameter specifies the LMEM_MOVEABLE flag, the function returns a handle to a memory object that is marked as discarded.

Return Values

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

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

Remarks

If the heap does not contain sufficient free space to satisfy the request, LocalAlloc returns NULL. Because NULL is used to indicate an error, virtual address zero is never allocated. It is, therefore, easy to detect the use of a NULL pointer.

If this function succeeds, it allocates at least the amount requested. If the amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual number of bytes allocated, use the LocalSize function.

To free the memory, use the LocalFree function.

Windows CE: Windows CE does not support the following uFlags flags:

LMEM_MOVEABLE

LHND

NONZEROLPTR

LMEM_DISCARDABLE

LMEM_NOCOMPACT

LMEM_NODISCARD

NONZEROLHND

The local heap for each process cannot exceed 1 megabyte. However, a process can create multiple heaps using the HeapCreate function and each of these heaps can be up to 1 megabyte.

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, LocalFree, LocalLock, LocalReAlloc, LocalSize