Compartilhar via


Função LocalAlloc (winbase.h)

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

Confira também

Funções globais e locais

Funções heap

Localfree

LocalLock

Localrealloc

LocalSize

Funções de gerenciamento da memória