globalAlloc 函数 (winbase.h)

项目
08/27/2023

从堆中分配指定的字节数。

注意与其他内存管理功能相比，全局函数具有更大的开销，并且提供的功能更少。除非文档指出应使用全局函数，否则新的应用程序应使用堆函数。有关详细信息，请参阅全局函数和本地函数。

语法

DECLSPEC_ALLOCATOR HGLOBAL GlobalAlloc(
  [in] UINT   uFlags,
  [in] SIZE_T dwBytes
);

参数

[in] uFlags

内存分配属性。如果指定零，则默认值为 GMEM_FIXED。此参数可以是以下一个或多个值，但专门指出的不兼容组合除外。

值	含义
GHND 0x0042	将 GMEM_MOVEABLE 和GMEM_ZEROINIT组合在一起。
GMEM_FIXED 0x0000	分配固定内存。返回值为指针。
GMEM_MOVEABLE 0x0002	分配可移动内存。内存块永远不会在物理内存中移动，但它们可以在默认堆中移动。返回值是内存对象的句柄。若要将句柄转换为指针，请使用 GlobalLock 函数。此值不能与 GMEM_FIXED 组合使用。
GMEM_ZEROINIT 0x0040	将内存内容初始化为零。
GPTR 0x0040	将 GMEM_FIXED 和GMEM_ZEROINIT组合在一起。

以下值已过时，但提供这些值是为了兼容 16 位 Windows。忽略它们。

GMEM_DDESHARE

GMEM_DISCARDABLE

GMEM_LOWER

GMEM_NOCOMPACT

GMEM_NODISCARD

GMEM_NOT_BANKED

GMEM_NOTIFY

GMEM_SHARE

[in] dwBytes

要分配的字节数。如果此参数为零，并且 uFlags 参数指定 GMEM_MOVEABLE，则函数将返回一个标记为已放弃的内存对象的句柄。

返回值

如果函数成功，则返回值是新分配的内存对象的句柄。

如果函数失败，则返回值为 NULL。要获得更多的错误信息，请调用 GetLastError。

注解

Windows 内存管理不提供单独的本地堆和全局堆。因此， GlobalAlloc 和 LocalAlloc 函数本质上是相同的。

可移动内存标志 GHND 和 GMEM_MOVABLE 增加了不必要的开销，并且需要锁定才能安全使用。除非文档明确指出应使用它们，否则应避免使用它们。

除非文档明确指出应使用全局函数，否则新应用程序应使用堆函数来分配和管理内存。例如，全局函数仍与 Dynamic Data Exchange (DDE) 、剪贴板函数和 OLE 数据对象一起使用。

如果 GlobalAlloc 函数成功，则至少分配请求的内存量。如果实际分配的金额大于请求的金额，则进程可以使用整个金额。若要确定实际分配的字节数，请使用 GlobalSize 函数。

如果堆中没有足够的可用空间来满足请求， 则 GlobalAlloc 返回 NULL。由于 NULL 用于指示错误，因此永远不会分配虚拟地址零。因此，很容易检测 NULL 指针的使用。

使用此函数分配的内存保证在 8 字节边界上对齐。若要执行动态生成的代码，请使用 VirtualAlloc 函数分配内存，使用 VirtualProtect 函数授予 PAGE_EXECUTE 访问权限。

若要释放内存，请使用 GlobalFree 函数。使用 LocalFree 释放 GlobalAlloc 分配的内存是不安全的。

示例

以下代码演示 了 GlobalAlloc 和 GlobalFree 的简单用法。

#include <windows.h>
#include <stdio.h>
#include <tchar.h>

void _cdecl main()
{
    PSECURITY_DESCRIPTOR pSD;

    pSD = (PSECURITY_DESCRIPTOR) GlobalAlloc(
           GMEM_FIXED,
           sizeof(PSECURITY_DESCRIPTOR));

    // Handle error condition
    if( pSD == NULL )
    {
       _tprintf(TEXT("GlobalAlloc failed (%d)\n"), GetLastError());
       return;
    }

    //see how much memory was allocated
    _tprintf(TEXT("GlobalAlloc allocated %d bytes\n"), GlobalSize(pSD));

    // Use the memory allocated

    // Free the memory when finished with it
    GlobalFree(pSD);
}

要求


最低受支持的客户端	Windows XP [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	winbase.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll