Funzione LocalAlloc (winbase.h)

Articolo
03/13/2024

Alloca il numero specificato di byte dall'heap.

Nota Le funzioni locali hanno un sovraccarico maggiore e forniscono meno funzionalità rispetto ad altre funzioni di gestione della memoria. Le nuove applicazioni devono usare le funzioni heap , a meno che non venga utilizzata una documentazione che indica che deve essere usata una funzione locale. Per altre informazioni, vedere Funzioni globali e locali.

Sintassi

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

Parametri

[in] uFlags

Attributi di allocazione della memoria. Il valore predefinito è il valore LMEM_FIXED . Questo parametro può essere uno o più dei valori seguenti, ad eccezione delle combinazioni incompatibili indicate in modo specifico.

Valore	Significato
LHND 0x0042	Combina LMEM_MOVEABLE e LMEM_ZEROINIT.
LMEM_FIXED 0x0000	Alloca la memoria fissa. Il valore restituito è un puntatore all'oggetto memory.
LMEM_MOVEABLE 0x0002	Alloca memoria rimovibile. I blocchi di memoria non vengono mai spostati nella memoria fisica, ma possono essere spostati all'interno dell'heap predefinito. Il valore restituito è un handle per l'oggetto memory. Per convertire l'handle in un puntatore, usare la funzione LocalLock . Questo valore non può essere combinato con LMEM_FIXED.
LMEM_ZEROINIT 0x0040	Inizializza il contenuto della memoria su zero.
LPTR 0x0040	Combina LMEM_FIXED e LMEM_ZEROINIT.
NONZEROLHND	Uguale a LMEM_MOVEABLE.
NONZEROLPTR	Uguale a LMEM_FIXED.

I valori seguenti sono obsoleti, ma sono disponibili per la compatibilità con Windows a 16 bit. Vengono ignorati.

LMEM_DISCARDABLE

LMEM_NOCOMPACT

LMEM_NODISCARD

[in] uBytes

Numero di byte da allocare. Se questo parametro è zero e il parametro uFlags specifica LMEM_MOVEABLE, la funzione restituisce un handle a un oggetto memoria contrassegnato come ignorato.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per l'oggetto memoria appena allocato.

Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La gestione della memoria di Windows non fornisce un heap locale separato e un heap globale. Pertanto, le funzioni LocalAlloc e GlobalAlloc sono essenzialmente uguali.

I flag di memoria rimovibile LHND, LMEM_MOVABLE e NONZEROLHND aggiungono sovraccarico non necessario e richiedono l'uso sicuro del blocco. Devono essere evitati a meno che la documentazione non indichi specificamente che devono essere usate.

Le nuove applicazioni devono usare le funzioni heap a meno che la documentazione non indichi in modo specifico che deve essere usata una funzione locale. Ad esempio, alcune funzioni di Windows allocano memoria che devono essere liberate con LocalFree.

Se l'heap non contiene spazio libero sufficiente per soddisfare la richiesta, LocalAlloc restituisce NULL. Poiché NULL viene usato per indicare un errore, l'indirizzo virtuale zero non viene mai allocato. È quindi facile rilevare l'uso di un puntatore NULL .

Se la funzione LocalAlloc ha esito positivo, alloca almeno l'importo richiesto. Se l'importo allocato è maggiore dell'importo richiesto, il processo può usare l'intero importo. Per determinare il numero effettivo di byte allocati, usare la funzione LocalSize .

Per liberare la memoria, usare la funzione LocalFree . Non è sicuro liberare memoria allocata con LocalAlloc usando GlobalFree.

Esempio

Il codice seguente mostra un semplice uso di LocalAlloc e 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);
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll