GlobalAlloc

Description

Allocates the specified number of bytes from the heap.

Note The global functions have greater overhead and provide fewer features than other memory management functions. New applications should use the heap functions unless documentation states that a global function should be used.

Syntax

HGLOBAL WINAPI GlobalAlloc(
  _In_ UINT   uFlags,
  _In_ SIZE_T dwBytes
);

Parameters

uFlags [in]

The memory allocation attributes. If zero is specified, the default is GMEM_FIXED. This parameter can be one or more of the following values, except for the incompatible combinations that are specifically noted.

Value	Meaning
GHND 0x0042	Combines GMEM_MOVEABLE and GMEM_ZEROINIT.
GMEM_FIXED 0x0000	Allocates fixed memory. The return value is a pointer.
GMEM_MOVEABLE 0x0002	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 into a pointer, use the GlobalLock function. This value cannot be combined with GMEM_FIXED.
GMEM_ZEROINIT 0x0040	Initializes memory contents to zero.
GPTR 0x0040	Combines GMEM_FIXED and GMEM_ZEROINIT.

The following values are obsolete, but are provided for compatibility with 16-bit Windows. They are ignored.

• GMEM_DDESHARE
• GMEM_DISCARDABLE
• GMEM_LOWER
• GMEM_NOCOMPACT
• GMEM_NODISCARD
• GMEM_NOT_BANKED
• GMEM_NOTIFY
• GMEM_SHARE

dwBytes [in]

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

Return value

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.