Função GlobalAlloc (winbase.h)

Artigo
03/08/2023

Aloca o número especificado de bytes do heap.

Nota As funções globais 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 global deve ser usada. Para obter mais informações, consulte Funções globais e locais.

Sintaxe

DECLSPEC_ALLOCATOR HGLOBAL GlobalAlloc(
  [in] UINT   uFlags,
  [in] SIZE_T dwBytes
);

Parâmetros

[in] uFlags

Os atributos de alocação de memória. Se zero for especificado, o padrão será GMEM_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
GHND 0x0042	Combina GMEM_MOVEABLE e GMEM_ZEROINIT.
GMEM_FIXED 0x0000	Aloca memória fixa. O valor retornado é um ponteiro.
GMEM_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 converter o identificador em um ponteiro, use a função GlobalLock . Esse valor não pode ser combinado com GMEM_FIXED.
GMEM_ZEROINIT 0x0040	Inicializa o conteúdo da memória como zero.
GPTR 0x0040	Combina GMEM_FIXED e GMEM_ZEROINIT.

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

GMEM_DDESHARE

GMEM_DISCARDABLE

GMEM_LOWER

GMEM_NOCOMPACT

GMEM_NODISCARD

GMEM_NOT_BANKED

GMEM_NOTIFY

GMEM_SHARE

[in] dwBytes

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

Valor retornado

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 separado e um heap global. Portanto, as funções GlobalAlloc e LocalAlloc são essencialmente as mesmas.

Os sinalizadores de memória móvel GHND e GMEM_MOVABLE 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.

Os novos aplicativos devem usar as funções de heap para alocar e gerenciar a memória, a menos que a documentação declare especificamente que uma função global deve ser usada. Por exemplo, as funções globais ainda são usadas com o DDE (Dynamic Data Exchange), as funções da área de transferência e os objetos de dados OLE.

Se a função GlobalAlloc for bem-sucedida, ela alocará pelo menos a quantidade de memória solicitada. Se o valor real 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 GlobalSize .

Se o heap não contiver espaço livre suficiente para atender à solicitação, GlobalAlloc 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 .

A memória alocada com essa função tem a garantia de estar alinhada em um limite de 8 bytes. Para executar o código gerado dinamicamente, use a função VirtualAlloc para alocar memória e a função VirtualProtect para conceder acesso PAGE_EXECUTE .

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

Exemplos

O código a seguir mostra um uso simples de GlobalAlloc e GlobalFree.

#include <windows.h>
#include <stdio.h>
#include <tchar.h>

void _cdecl main()
{
    PSECURITY_DESCRIPTOR pSD;

    pSD = (PSECURITY_DESCRIPTOR) GlobalAlloc(
           GMEM_FIXED,
           sizeof(PSECURITY_DESCRIPTOR));

    // Handle error condition
    if( pSD == NULL )
    {
       _tprintf(TEXT("GlobalAlloc failed (%d)\n"), GetLastError());
       return;
    }

    //see how much memory was allocated
    _tprintf(TEXT("GlobalAlloc allocated %d bytes\n"), GlobalSize(pSD));

    // Use the memory allocated

    // Free the memory when finished with it
    GlobalFree(pSD);
}

Requisitos


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 (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll