Função GlobalAlloc (winbase.h)

Aloca o número especificado de bytes do heap.

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.

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

Confira também

Funções globais e locais

GlobalDiscard

Globalfree

GlobalLock

GlobalSize

Funções heap

Funções de gerenciamento da memória