LocalAlloc-Funktion (winbase.h)

Ordnet die angegebene Anzahl von Bytes aus dem Heap zu.

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.

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

Siehe auch

Globale und lokale Funktionen

Heapfunktionen

LocalFree

LocalLock

LocalReAlloc

LocalSize

Speicherverwaltungsfunktionen