Функция GlobalAlloc (winbase.h)

Статья
03/08/2023

Выделяет указанное количество байтов из кучи.

Примечание Глобальные функции имеют большую нагрузку и предоставляют меньше функций, чем другие функции управления памятью. Новые приложения должны использовать функции кучи , если в документации не указано, что следует использовать глобальную функцию. Дополнительные сведения см. в разделе Глобальные и локальные функции.

Синтаксис

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

Параметры

[in] uFlags

Атрибуты выделения памяти. Если указано ноль, значение по умолчанию — GMEM_FIXED. Этот параметр может быть одним или несколькими из указанных ниже значений, за исключением несовместимых сочетаний.

Значение	Значение
GHND 0x0042	Объединяет GMEM_MOVEABLE и GMEM_ZEROINIT.
GMEM_FIXED 0x0000	Выделяет фиксированную память. Возвращаемое значение является указателем.
GMEM_MOVEABLE 0x0002	Выделяет перемещаемую память. Блоки памяти никогда не перемещаются в физической памяти, но их можно переместить в кучу по умолчанию. Возвращаемое значение является дескриптором объекта памяти. Чтобы преобразовать дескриптор в указатель, используйте функцию GlobalLock . Это значение нельзя сочетать с GMEM_FIXED.
GMEM_ZEROINIT 0x0040	Инициализирует содержимое памяти до нуля.
GPTR 0x0040	Объединяет GMEM_FIXED и GMEM_ZEROINIT.

Следующие значения устарели, но предоставляются для совместимости с 16-разрядной версией Windows. Они игнорируются.

GMEM_DDESHARE

GMEM_DISCARDABLE

GMEM_LOWER

GMEM_NOCOMPACT

GMEM_NODISCARD

GMEM_NOT_BANKED

GMEM_NOTIFY

GMEM_SHARE

[in] dwBytes

Количество байтов, которые необходимо выделить. Если этот параметр равен нулю и параметр uFlags указывает GMEM_MOVEABLE, функция возвращает дескриптор в объект памяти, помеченный как отброшенный.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение является дескриптором для вновь выделенного объекта памяти.

Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Флаги перемещаемой памяти GHND и GMEM_MOVABLE добавить ненужные издержки и требуют блокировки для безопасного использования. Их следует избегать, если в документации не указано, что их следует использовать.

Новые приложения должны использовать функции кучи для выделения памяти и управления ими, если в документации не указано, что следует использовать глобальную функцию. Например, глобальные функции по-прежнему используются с динамическим обменом данными (DDE), функциями буфера обмена и объектами данных OLE.

Если функция GlobalAlloc выполняется успешно, она выделяет по крайней мере запрошенный объем памяти. Если фактически выделенная сумма больше запрошенной суммы, процесс может использовать всю сумму. Чтобы определить фактическое количество выделенных байтов, используйте функцию GlobalSize .

Если куча не содержит достаточно свободного места для выполнения запроса, GlobalAlloc возвращает значение NULL. Так как для указания ошибки используется значение NULL , нулевой виртуальный адрес никогда не выделяется. Поэтому легко обнаружить использование указателя NULL .

Память, выделенная этой функцией, гарантированно выравнивается по 8-байтовой границе. Чтобы выполнить динамически создаваемый код, используйте функцию VirtualAlloc для выделения памяти и функцию VirtualProtect , чтобы предоставить доступ к PAGE_EXECUTE .

Чтобы освободить память, используйте функцию GlobalFree . Освобождение памяти, выделенной с помощью GlobalAlloc с помощью LocalFree, небезопасно.

Примеры

В следующем коде показано простое использование GlobalAlloc и 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);
}

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll