Função LocalAlloc (winbase.h)

Artigo
08/27/2023

Aloca o número especificado de bytes do heap.

Nota As funções locais têm maior sobrecarga e fornecem menos recursos do que outras funções de gerenciamento de memória. Novos aplicativos devem usar as funções heap , a menos que a documentação declare que uma função local deve ser usada. Para obter mais informações, consulte Funções globais e locais.

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.

Valor	Significado
LHND 0x0042	Combina LMEM_MOVEABLE e LMEM_ZEROINIT.
LMEM_FIXED 0x0000	Aloca memória fixa. O valor retornado é um ponteiro para o objeto de memória.
LMEM_MOVEABLE 0x0002	Aloca memória móvel. Os blocos de memória nunca são movidos na memória física, mas podem ser movidos dentro do heap padrão. O valor retornado é um identificador para o objeto de memória. Para traduzir o identificador para um ponteiro, use a função LocalLock . Esse valor não pode ser combinado com LMEM_FIXED.
LMEM_ZEROINIT 0x0040	Inicializa o conteúdo da memória como zero.
LPTR 0x0040	Combina LMEM_FIXED e LMEM_ZEROINIT.
NONZEROLHND	O mesmo que LMEM_MOVEABLE.
NONZEROLPTR	O mesmo que LMEM_FIXED.

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

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (incluir Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll