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.
| Valor | Significado |
|---|---|
|
Combina LMEM_MOVEABLE e LMEM_ZEROINIT. |
|
Aloca memória fixa. O valor retornado é um ponteiro para o objeto de memória. |
|
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. |
|
Inicializa o conteúdo da memória como zero. |
|
Combina LMEM_FIXED e LMEM_ZEROINIT. |
|
O mesmo que LMEM_MOVEABLE. |
|
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 |