localAlloc 函数 (winbase.h)

项目
08/27/2023

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

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

语法

DECLSPEC_ALLOCATOR HLOCAL LocalAlloc(
  [in] UINT   uFlags,
  [in] SIZE_T uBytes
);

参数

[in] uFlags

内存分配属性。默认值为 LMEM_FIXED 值。此参数可以是以下一个或多个值，但特别指出的不兼容组合除外。

值	含义
LHND 0x0042	合并 LMEM_MOVEABLE 和 LMEM_ZEROINIT。
LMEM_FIXED 0x0000	分配固定内存。返回值是指向内存对象的指针。
LMEM_MOVEABLE 0x0002	分配可移动内存。内存块永远不会在物理内存中移动，但它们可以在默认堆中移动。返回值是内存对象的句柄。若要将句柄转换为指针，请使用 LocalLock 函数。此值不能与 LMEM_FIXED组合使用。
LMEM_ZEROINIT 0x0040	将内存内容初始化为零。
LPTR 0x0040	合并 LMEM_FIXED 和 LMEM_ZEROINIT。
NONZEROLHND	与 LMEM_MOVEABLE 相同。
NONZEROLPTR	与 LMEM_FIXED 相同。

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

LMEM_DISCARDABLE

LMEM_NOCOMPACT

LMEM_NODISCARD

[in] uBytes

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

返回值

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

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

注解

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

可移动内存标志 LHND、 LMEM_MOVABLE 和 NONZEROLHND 会增加不必要的开销，并要求安全使用锁定。除非文档明确指出应使用它们，否则应避免使用它们。

除非文档特别指出应使用本地函数，否则新应用程序应使用堆函数。例如，某些 Windows 函数分配必须使用 LocalFree 释放的内存。

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

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

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

示例

以下代码演示 了 LocalAlloc 和 LocalFree 的简单用法。

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

void _cdecl _tmain()
{
    LPTSTR pszBuf=NULL;

    pszBuf = (LPTSTR)LocalAlloc(
              LPTR,
              MAX_PATH*sizeof(TCHAR));

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

    //see how much memory was allocated
    _tprintf(TEXT("LocalAlloc allocated %d bytes\n"), LocalSize(pszBuf));

    // Use the memory allocated

    // Free the memory when finished with it
    LocalFree(pszBuf);
}

要求

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