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 增加不必要的額外負荷，而且需要安全地使用鎖定。除非檔特別指出應該使用，否則應避免它們。

除非檔特別指出應該使用全域函式，否則新的應用程式應該使用堆積函式來配置和管理記憶體。例如，全域函式仍與動態資料交換 (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)
程式庫	Kernel32.lib
DLL	Kernel32.dll