Allocates the specified number of bytes from the heap.
DECLSPEC_ALLOCATOR HLOCAL LocalAlloc( UINT uFlags, SIZE_T uBytes );
The memory allocation attributes. The default is the LMEM_FIXED value. This parameter can be one or more of the following values, except for the incompatible combinations that are specifically noted.
||Combines LMEM_MOVEABLE and LMEM_ZEROINIT.|
||Allocates fixed memory. The return value is a pointer to the memory object.|
Allocates movable memory. 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 value cannot be combined with LMEM_FIXED.
||Initializes memory contents to zero.|
||Combines LMEM_FIXED and LMEM_ZEROINIT.|
||Same as LMEM_MOVEABLE.|
||Same as LMEM_FIXED.|
The following values are obsolete, but are provided for compatibility with 16-bit Windows. They are ignored.
The number of bytes to allocate. If this parameter is zero and the uFlags parameter specifies LMEM_MOVEABLE, the function returns a handle to a memory object that is marked as discarded.
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.
Windows memory management does not provide a separate local heap and global heap. Therefore, the LocalAlloc and GlobalAlloc functions are essentially the same.
The movable-memory flags LHND, LMEM_MOVABLE, and NONZEROLHND add unnecessary overhead and require locking to be used safely. They should be avoided unless documentation specifically states that they should be used.
New applications should use the heap functions unless the documentation specifically states that a local function should be used. For example, some Windows functions allocate memory that must be freed with LocalFree.
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 the LocalAlloc 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.
The following code shows a simple use of LocalAlloc and LocalFree.
#include <windows.h> #include <stdio.h> #include <tchar.h>
|Minimum supported client||Windows XP [desktop apps | UWP apps]|
|Minimum supported server||Windows Server 2003 [desktop apps | UWP apps]|
|Header||winbase.h (include Windows.h)|