Função LocalAlloc (winbase.h)

Aloca o número especificado de bytes do heap.

Sintaxe

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

Parâmetros

[in] uFlags

Os atributos de alocação de memória. O padrão é o valor LMEM_FIXED . Esse parâmetro pode ser um ou mais dos valores a seguir, exceto para as combinações incompatíveis que são especificamente indicadas.

Os valores a seguir são obsoletos, mas são fornecidos para compatibilidade com o Windows de 16 bits. Eles são ignorados.

LMEM_DISCARDABLE

LMEM_NOCOMPACT

LMEM_NODISCARD

[in] uBytes

O número de bytes a serem alocados. Se esse parâmetro for zero e o parâmetro uFlags especificar LMEM_MOVEABLE, a função retornará um identificador para um objeto de memória marcado como descartado.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador para o objeto de memória recém-alocado.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Comentários

O gerenciamento de memória do Windows não fornece um heap local e um heap global separados. Portanto, as funções LocalAlloc e GlobalAlloc são essencialmente as mesmas.

Os sinalizadores de memória móvel LHND, LMEM_MOVABLE e NONZEROLHND adicionam sobrecarga desnecessária e exigem que o bloqueio seja usado com segurança. Eles devem ser evitados, a menos que a documentação especificamente declare que eles devem ser usados.

Novos aplicativos devem usar as funções de heap , a menos que a documentação declare especificamente que uma função local deve ser usada. Por exemplo, algumas funções do Windows alocam memória que deve ser liberada com LocalFree.

Se o heap não contiver espaço livre suficiente para atender à solicitação, LocalAlloc retornará NULL. Como NULL é usado para indicar um erro, o endereço virtual zero nunca é alocado. Portanto, é fácil detectar o uso de um ponteiro NULL .

Se a função LocalAlloc for bem-sucedida, ela alocará pelo menos o valor solicitado. Se o valor alocado for maior que o valor solicitado, o processo poderá usar todo o valor. Para determinar o número real de bytes alocados, use a função LocalSize .

Para liberar a memória, use a função LocalFree . Não é seguro liberar memória alocada com LocalAlloc usando GlobalFree.

Exemplos

O código a seguir mostra um uso simples de 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);
}

Requisitos

Confira também

Funções globais e locais

Funções heap

Localfree

LocalLock

Localrealloc

LocalSize

Funções de gerenciamento da memória