Freigeben über


LocalAlloc-Funktion (winbase.h)

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

Siehe auch

Globale und lokale Funktionen

Heapfunktionen

LocalFree

LocalLock

LocalReAlloc

LocalSize

Speicherverwaltungsfunktionen