Platform SDK: Memory |
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.
Note The global functions are slower than other memory management functions and do not provide as many features. Therefore, new applications should use the heap functions. However, the global functions are still used with DDE and the clipboard functions.
HGLOBAL GlobalAlloc( UINT uFlags, // allocation attributes SIZE_T dwBytes // number of bytes to allocate );
Value | Meaning |
---|---|
GHND | Combines GMEM_MOVEABLE and GMEM_ZEROINIT. |
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 value cannot be combined with GMEM_FIXED. |
GMEM_ZEROINIT | Initializes memory contents to zero. |
GPTR | Combines GMEM_FIXED and GMEM_ZEROINIT. |
The following values are obsolete.
Value | Meaning |
---|---|
GMEM_DDESHARE | Ignored. This value is provided only for compatibility with 16-bit Windows. |
GMEM_DISCARDABLE | Ignored. This value is provided only for compatibility with 16-bit Windows.
In Win32, you must explicitly call the GlobalDiscard function to discard a block. This value cannot be combined with GMEM_FIXED. |
GMEM_LOWER | Ignored. This value is provided only for compatibility with 16-bit Windows. |
GMEM_NOCOMPACT | Ignored. This value is provided only for compatibility with 16-bit Windows. |
GMEM_NODISCARD | Ignored. This value is provided only for compatibility with 16-bit Windows. |
GMEM_NOT_BANKED | Ignored. This value is provided only for compatibility with 16-bit Windows. |
GMEM_NOTIFY | Ignored. This value is provided only for compatibility with 16-bit Windows. |
GMEM_SHARE | Ignored. This value is provided only for compatibility with 16-bit Windows. |
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.
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.
Windows 95/98: The heap managers are designed for memory blocks smaller than four megabytes. If you expect your memory blocks to be larger than one or two megabytes, you can avoid significant performance degradation by using the VirtualAlloc or VirtualAllocEx function instead.
Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98: Requires Windows 95 or later.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.
Memory Management Overview, Memory Management Functions, GlobalDiscard, GlobalFree, GlobalLock, GlobalSize