LocalAlloc-Funktion (winbase.h)

Artikel
03/06/2024

Ordnet die angegebene Anzahl von Bytes aus dem Heap zu.

Hinweis Die lokalen 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 lokale Funktion verwendet werden soll. Weitere Informationen finden Sie unter Globale und lokale Funktionen.

Syntax

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

Parameter

[in] uFlags

Die Speicherzuordnungsattribute. Der Standardwert ist der LMEM_FIXED Wert. 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
LHND 0x0042	Kombiniert LMEM_MOVEABLE und LMEM_ZEROINIT.
LMEM_FIXED 0x0000	Ordnet festen Arbeitsspeicher zu. Der Rückgabewert ist ein Zeiger auf das Speicherobjekt.
LMEM_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 LocalLock-Funktion , um das Handle in einen Zeiger zu übersetzen. Dieser Wert kann nicht mit LMEM_FIXED kombiniert werden.
LMEM_ZEROINIT 0x0040	Initialisiert Den Speicherinhalt auf Null.
LPTR 0x0040	Kombiniert LMEM_FIXED und LMEM_ZEROINIT.
NONZEROLHND	Identisch mit LMEM_MOVEABLE.
NONZEROLPTR	Identisch mit LMEM_FIXED.

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

LMEM_DISCARDABLE

LMEM_NOCOMPACT

LMEM_NODISCARD

[in] uBytes

Die Anzahl der zu belegenden Bytes. Wenn dieser Parameter null ist und der uFlags-ParameterLMEM_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 LocalAlloc und GlobalAlloc im Wesentlichen identisch.

Die Movable-Memory-Flags LHND, LMEM_MOVABLE und NONZEROLHND verursachen unnötigen Mehraufwand und erfordern sperren, um sicher verwendet zu werden. Sie sollten vermieden werden, es sei denn, die Dokumentation besagt ausdrücklich, dass sie verwendet werden sollten.

Neue Anwendungen sollten die Heapfunktionen verwenden, es sei denn, in der Dokumentation wird ausdrücklich angegeben, dass eine lokale Funktion verwendet werden soll. Beispielsweise weisen einige Windows-Funktionen Arbeitsspeicher zu, der mit LocalFree freigegeben werden muss.

Wenn der Heap nicht genügend freien Speicherplatz zum Erfüllen der Anforderung enthält, gibt LocalAllocNULL 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.

Wenn die LocalAlloc-Funktion erfolgreich ist, weist sie mindestens den angeforderten Betrag zu. Wenn der zugewiesene Betrag größer als der angeforderte Betrag ist, kann der Prozess den gesamten Betrag verwenden. Verwenden Sie die LocalSize-Funktion , um die tatsächliche Anzahl der zugewiesenen Bytes zu ermitteln.

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

Beispiele

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

Anforderungen

Anforderung	Wert
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