GlobalAlloc-Funktion (winbase.h)

Artikel
08/27/2023

Ordnet die angegebene Anzahl von Bytes aus dem Heap zu.

Hinweis Die globalen Funktionen weisen einen größeren Mehraufwand auf und bieten weniger Features als andere Speicherverwaltungsfunktionen. Neue Anwendungen sollten die Heapfunktionen verwenden, es sei denn, die Dokumentation besagt, dass eine globale Funktion verwendet werden soll. Weitere Informationen finden Sie unter Globale und lokale Funktionen.

Syntax

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

Parameter

[in] uFlags

Die Speicherzuordnungsattribute. Wenn null angegeben wird, ist der Standardwert GMEM_FIXED. Bei diesem Parameter kann es sich um einen oder mehrere der folgenden Werte handeln, mit Ausnahme der inkompatiblen Kombinationen, die speziell erwähnt werden.

Wert	Bedeutung
GHND 0x0042	Kombiniert GMEM_MOVEABLE und GMEM_ZEROINIT.
GMEM_FIXED 0x0000	Ordnet festen Arbeitsspeicher zu. Der Rückgabewert ist ein Zeiger.
GMEM_MOVEABLE 0x0002	Ordnet beweglichen Arbeitsspeicher zu. Speicherblöcke werden nie im physischen Arbeitsspeicher verschoben, können aber innerhalb des Standardheaps verschoben werden. Der Rückgabewert ist ein Handle für das Speicherobjekt. Verwenden Sie die GlobalLock-Funktion , um den Handle in einen Zeiger zu übersetzen. Dieser Wert kann nicht mit GMEM_FIXED kombiniert werden.
GMEM_ZEROINIT 0x0040	Initialisiert Den Speicherinhalt auf Null.
GPTR 0x0040	Kombiniert GMEM_FIXED und GMEM_ZEROINIT.

Die folgenden Werte sind veraltet, werden aber aus Gründen der Kompatibilität mit 16-Bit-Windows bereitgestellt. Sie werden ignoriert.

GMEM_DDESHARE

GMEM_DISCARDABLE

GMEM_LOWER

GMEM_NOCOMPACT

GMEM_NODISCARD

GMEM_NOT_BANKED

GMEM_NOTIFY

GMEM_SHARE

[in] dwBytes

Die Anzahl der zu belegenden Bytes. Wenn dieser Parameter null ist und der uFlags-ParameterGMEM_MOVEABLE angibt, gibt die Funktion ein Handle an ein Speicherobjekt zurück, das als verworfen markiert ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das neu zugewiesene Speicherobjekt.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die Windows-Speicherverwaltung bietet keinen separaten lokalen heap und globalen Heap. Daher sind die Funktionen GlobalAlloc und LocalAlloc im Wesentlichen identisch.

Die Movable-Memory-Flags GHND und GMEM_MOVABLE verursachen unnötigen Mehraufwand und erfordern eine sichere Verwendung der Sperrung. Sie sollten vermieden werden, es sei denn, die Dokumentation besagt ausdrücklich, dass sie verwendet werden sollten.

Neue Anwendungen sollten die Heapfunktionen verwenden, um Arbeitsspeicher zuzuweisen und zu verwalten, es sei denn, die Dokumentation weist ausdrücklich darauf hin, dass eine globale Funktion verwendet werden soll. Beispielsweise werden die globalen Funktionen weiterhin mit Dynamic Data Exchange (DDE), den Zwischenablagefunktionen und OLE-Datenobjekten verwendet.

Wenn die GlobalAlloc-Funktion erfolgreich ist, ordnet sie mindestens die angeforderte Arbeitsspeichermenge zu. Wenn der tatsächlich zugewiesene Betrag größer als der angeforderte Betrag ist, kann der Prozess den gesamten Betrag verwenden. Verwenden Sie die GlobalSize-Funktion , um die tatsächliche Anzahl der zugewiesenen Bytes zu ermitteln.

Wenn der Heap nicht genügend freien Speicherplatz zum Erfüllen der Anforderung enthält, gibt GlobalAllocNULL zurück. Da NULL verwendet wird, um einen Fehler anzugeben, wird die virtuelle Adresse 0 nie zugeordnet. Daher ist es einfach, die Verwendung eines NULL-Zeigers zu erkennen.

Der dieser Funktion zugeordnete Arbeitsspeicher wird garantiert an einer 8-Byte-Grenze ausgerichtet. Um dynamisch generierten Code auszuführen, verwenden Sie die VirtualAlloc-Funktion , um Arbeitsspeicher und die VirtualProtect-Funktion zuzuweisen , um PAGE_EXECUTE Zugriff zu gewähren.

Verwenden Sie die GlobalFree-Funktion , um den Arbeitsspeicher freizugeben. Es ist nicht sicher, den mit GlobalAlloc zugewiesenen Arbeitsspeicher mithilfe von LocalFree freizugeben.

Beispiele

Der folgende Code zeigt eine einfache Verwendung von GlobalAlloc und 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);
}

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll