GlobalAlloc

The GlobalAlloc 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.

HGLOBAL GlobalAlloc(
  UINT uFlags,    // allocation attributes
  DWORD dwBytes   // number of bytes to allocate
);
 

Parameters

uFlags

Specifies how to allocate memory. If zero is specified, the default is GMEM_FIXED. This value can be one or more of the following flags, except for the incompatible combinations that are specifically noted.

Flag	Meaning
GMEM_FIXED	Allocates fixed memory. The return value is a pointer.
GMEM_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 into a pointer, use the GlobalLock function. This flag cannot be combined with the GMEM_FIXED flag.
GPTR	Combines the GMEM_FIXED and GMEM_ZEROINIT flags.
GHND	Combines the GMEM_MOVEABLE and GMEM_ZEROINIT flags.
GMEM_DDESHARE GMEM_SHARE	This flag is provided primarily for compatibility with 16-bit Windows. However, this flag may be used by some applications to enhance the performance of DDE operations and therefore can be specified if the memory is to be used for DDE. .
GMEM_DISCARDABLE	Ignored. This flag is provided only for compatibility with 16-bit Windows. In Win32, you must explicitly call the GlobalDiscard function to discard a block. This flag cannot be combined with the GMEM_FIXED flag.
GMEM_LOWER	Ignored. This flag is provided only for compatibility with 16-bit Windows.
GMEM_NOCOMPACT	Ignored. This flag is provided only for compatibility with 16-bit Windows.
GMEM_NODISCARD	Ignored. This flag is provided only for compatibility with 16-bit Windows.
GMEM_NOT_BANKED	Ignored. This flag is provided only for compatibility with 16-bit Windows.
GMEM_NOTIFY	Ignored. This flag is provided only for compatibility with 16-bit Windows.
GMEM_ZEROINIT	Initializes memory contents to zero.

dwBytes

Specifies the number of bytes to allocate. If this parameter is zero and the uFlags parameter specifies the GMEM_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, GlobalAlloc 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.

Memory allocated with this function is guaranteed to be aligned on an 8-byte boundary. All memory is created with execute access; no special function is required to execute dynamically generated code.

If this function succeeds, it allocates at least the amount of memory requested. If the actual 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 GlobalSize function.

To free the memory, use the GlobalFree function.

QuickInfo

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

See Also

Memory Management Overview, Memory Management Functions, GlobalDiscard, GlobalFree, GlobalLock, GlobalSize