localAlloc 函式 (winbase.h)

發行項
03/03/2024

從堆積配置指定的位元組數目。

注意本機函式具有更大的額外負荷，並提供比其他記憶體管理功能少的功能。除非檔指出應該使用本機函式，否則新的應用程式應該使用堆積函式。如需詳細資訊，請參閱全域和區域函式。

語法

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 是用來指出錯誤，所以永遠不會配置虛擬位址零。因此，很容易偵測 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)
程式庫	Kernel32.lib
DLL	Kernel32.dll