GlobalAlloc Function

Allocates memory from the global heap.

LPVOID GlobalAlloc(
    UINT flags,
    SIZE_T bytes
);

Parameters

Parameter Description
flags The memory allocation attributes. This parameter can be a combination of the following values:
  • GMEM_FIXED: Allocates memory that cannot be moved. The return value is a pointer to the allocated memory.
  • GMEM_ZEROINIT: Initializes memory to zero.
  • GMEM_MOVEABLE: Allocates memory that can be moved. The return value is a handle to the allocated memory.
  • GMEM_NODISCARD: Prevents memory from being discarded.
  • GMEM_LOWER: Allocates memory in the lower 16 MB of address space. (Obsolete)
  • GMEM_NOCOMPACT: Do not compact free space to perform the allocation.
  • GMEM_BIG ​: Allocates memory in the high-performance 64-bit space.
  • GMEM_NOT_BANKED: Allocates memory that is not in the banked memory.
  • GMEM_SHARE: Initializes memory to zero.
  • GPTR: Equivalent to GMEM_FIXED.
  • GHND: A combination of GMEM_MOVEABLE and GMEM_ZEROINIT.
bytes The number of bytes to allocate. If this parameter is zero and flags specifies GMEM_MODIFY, the memory is freed.

Return Value

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

If the function fails, the return value is NULL. The function can fail for the following reasons:
  • The specified amount of memory could not be allocated.
  • Not enough available memory.
To get extended error information, call GetLastError.

Remarks

The global heap is a shared memory area accessible by all processes. When allocating memory with GMEM_MOVEABLE, you must lock the memory object by calling the GlobalLock function before you can access it. When you are finished with the memory, you must unlock it by calling the GlobalUnlock function.

For more efficient memory management, consider using heap allocation functions like HeapAlloc.

Note: The GlobalAlloc function is generally superseded by the HeapAlloc function. For new applications, it is recommended to use the heap functions.

Requirements
Minimum supported client Windows 2000 Professional
Minimum supported server Windows 2000 Server
Header WinBase.h (include Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

See Also