Функция VirtualAllocEx (memoryapi.h)

Статья
07/16/2024

Резервирует, фиксирует или изменяет состояние области памяти в виртуальном адресном пространстве указанного процесса. Функция инициализирует память, выделенную нулю.

Чтобы указать узел NUMA для физической памяти, см. VirtualAllocExNuma.

Синтаксис

LPVOID VirtualAllocEx(
  [in]           HANDLE hProcess,
  [in, optional] LPVOID lpAddress,
  [in]           SIZE_T dwSize,
  [in]           DWORD  flAllocationType,
  [in]           DWORD  flProtect
);

Параметры

[in] hProcess

Дескриптор процесса. Функция выделяет память в виртуальном адресном пространстве этого процесса.

Дескриптор должен иметь право PROCESS_VM_OPERATION доступа. Дополнительные сведения см. в "Безопасность процессов и доступ".

[in, optional] lpAddress

Указатель, указывающий нужный начальный адрес для области страниц, которую нужно выделить.

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

Если вы фиксируете память, которая уже зарезервирована, функция округляет этот адрес до ближайшей границы страницы. Чтобы определить размер страницы и степень детализации выделения на хост-компьютере, используйте функцию GetSystemInfo.

Если lpAddressNULL, функция определяет, где выделить регион.

Если этот адрес находится в анклаве, который не инициализирован путем вызова InitializeEnclave, VirtualAllocEx выделяет страницу нуля для анклава на этом адресе. Страница должна быть ранее незафиксирована и не будет измеряться с помощью инструкции EEXTEND модели программирования расширений Intel Software Guard.

Если адрес в анклавах, который вы инициализировали, операция выделения завершается ошибкой ERROR_INVALID_ADDRESS. Это верно для анклава, которые не поддерживают динамическое управление памятью (т. е. SGX1). Анклавы SGX2 разрешают выделение, и страница должна приниматься анклава после выделения.

[in] dwSize

Размер выделенной области памяти в байтах.

Если lpAddressNULL, функция округляет dwSize до следующей границы страницы.

Если lpAddress не NULL, функция выделяет все страницы, содержащие один или несколько байтов в диапазоне от lpAddress до lpAddress+dwSize. Это означает, например, что диапазон 2-байтов, который перестраивает границу страницы, приводит к выделению обеих страниц функцией.

[in] flAllocationType

Тип выделения памяти. Этот параметр должен содержать одно из следующих значений.

Ценность	Значение
MEM_COMMIT 0x00001000	Выделяет расходы на память (от общего размера памяти и файлов разбиения по страницам на диске) для указанных зарезервированных страниц памяти. Функция также гарантирует, что, когда вызывающий объект позже обращается к памяти, содержимое будет равно нулю. Фактические физические страницы не выделяются, если только не будут доступны виртуальные адреса. Чтобы зарезервировать и зафиксировать страницы на одном шаге, вызовите VirtualAllocEx с `MEM_COMMIT \| MEM_RESERVE`. Попытка зафиксировать определенный диапазон адресов путем указания MEM_COMMIT без MEM_RESERVE и неNULLlpAddress завершается ошибкой, если весь диапазон еще не зарезервирован. Полученный код ошибки ERROR_INVALID_ADDRESS. Попытка зафиксировать страницу, которая уже зафиксирована, не приводит к сбою функции. Это означает, что страницы можно зафиксировать, не определяя текущее состояние обязательств каждой страницы. Если lpAddress указывает адрес в анклавах, flAllocationType должны быть MEM_COMMIT.
MEM_RESERVE 0x00002000	Резервирует диапазон виртуального адресного пространства процесса без выделения фактического физического хранилища в памяти или в файле разбиения на диск. Зарезервированные страницы фиксируются путем вызова VirtualAllocEx снова с MEM_COMMIT. Чтобы зарезервировать и зафиксировать страницы на одном шаге, вызовите VirtualAllocEx с `MEM_COMMIT \| MEM_RESERVE`. Другие функции выделения памяти, такие как malloc и LocalAlloc, не могут использовать зарезервированную память, пока она не будет освобождена.
MEM_RESET 0x00080000	Указывает, что данные в диапазоне памяти, заданном lpAddress и dwSize больше не являются интересом. Страницы не должны быть считываются или записываются в файл разбиения на страницы. Однако блок памяти будет использоваться снова позже, поэтому его не следует выводить. Это значение нельзя использовать с любым другим значением. Использование этого значения не гарантирует, что диапазон, на котором работает MEM_RESET, будет содержать нули. Если вы хотите, чтобы диапазон содержал нули, удалите память, а затем снова зафиксируете его. При использовании MEM_RESETфункция VirtualAllocEx игнорирует значение fProtect. Однако необходимо задать fProtect допустимому значению защиты, например PAGE_NOACCESS. VirtualAllocEx возвращает ошибку, если используется MEM_RESET, а диапазон памяти сопоставляется с файлом. Общее представление допускается только в том случае, если оно сопоставлено с файлом разбиения на страницы.
MEM_RESET_UNDO 0x1000000	MEM_RESET_UNDO следует вызывать только в диапазоне адресов, к которому MEM_RESET успешно применено ранее. Он указывает, что данные в указанном диапазоне памяти, указанные lpAddress и dwSize, заинтересованы в вызывающем объекте и пытается отменить эффекты MEM_RESET. Если функция выполнена успешно, это означает, что все данные в указанном диапазоне адресов не сохраняются. Если функция завершается ошибкой, по крайней мере некоторые данные в диапазоне адресов заменены нулями. Это значение нельзя использовать с любым другим значением. Если MEM_RESET_UNDO вызывается в диапазоне адресов, который не был MEM_RESET ранее, поведение не определено. При указании MEM_RESETфункция VirtualAllocEx игнорирует значение flProtect. Однако необходимо установить flProtect допустимым значением защиты, например PAGE_NOACCESS. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Флаг MEM_RESET_UNDO не поддерживается до Windows 8 и Windows Server 2012.

Этот параметр также может указать следующие значения, как указано.

Ценность	Значение
MEM_LARGE_PAGES 0x20000000	Выделяет память с помощью поддержки больших страниц. Размер и выравнивание должны быть несколькими из минимума больших страниц. Чтобы получить это значение, используйте функцию GetLargePageMinimum GetLargePageMinimum. Если указать это значение, необходимо также указать MEM_RESERVE и MEM_COMMIT.
MEM_PHYSICAL 0x00400000	Резервирует диапазон адресов, который можно использовать для сопоставления страницы расширений окна адресов (AWE). Это значение должно использоваться с MEM_RESERVE и никакими другими значениями.
MEM_TOP_DOWN 0x00100000	Выделяет память по максимально возможному адресу. Это может быть медленнее регулярных выделений, особенно при наличии большого количества выделений.

Ценность

Значение

MEM_LARGE_PAGES
0x20000000

Выделяет память с помощью поддержки больших страниц.

Размер и выравнивание должны быть несколькими из минимума больших страниц. Чтобы получить это значение, используйте функцию GetLargePageMinimum GetLargePageMinimum.

Если указать это значение, необходимо также указать MEM_RESERVE и MEM_COMMIT.

MEM_PHYSICAL
0x00400000

Резервирует диапазон адресов, который можно использовать для сопоставления страницы расширений окна адресов (AWE).

Это значение должно использоваться с MEM_RESERVE и никакими другими значениями.

MEM_TOP_DOWN
0x00100000

Выделяет память по максимально возможному адресу. Это может быть медленнее регулярных выделений, особенно при наличии большого количества выделений.

[in] flProtect

Защита памяти для выделенной области страниц. Если страницы фиксируются, можно указать любую из констант защиты памяти.

Если lpAddress указывает адрес в анклавах, flProtect не может быть любым из следующих значений:

PAGE_NOACCESS
PAGE_GUARD
PAGE_NOCACHE
PAGE_WRITECOMBINE

При выделении динамической памяти для анклава параметр flProtect должен быть PAGE_READWRITE или PAGE_EXECUTE_READWRITE.

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

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

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

Замечания

Каждая страница имеет связанное состояние страницы. Функция VirtualAllocEx может выполнять следующие операции:

Фиксация области зарезервированных страниц
Зарезервировать область бесплатных страниц
Одновременно зарезервируйте и зафиксируйте область бесплатных страниц

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

Вы можете использовать VirtualAllocEx, чтобы зарезервировать блок страниц, а затем выполнить дополнительные вызовы для VirtualAllocEx для фиксации отдельных страниц из зарезервированного блока. Это позволяет процессу резервировать диапазон своего виртуального адресного пространства без использования физического хранилища до тех пор, пока он не потребуется.

Если параметр lpAddress не NULL, функция использует lpAddress и dwSize для вычисления области страниц, выделенной. Текущее состояние всего диапазона страниц должно быть совместимо с типом выделения, указанным параметром flAllocationType. В противном случае функция завершается ошибкой, и ни одна из страниц не выделяется. Это требование совместимости не исключает фиксацию уже зафиксированной страницы; см. предыдущий список.

Чтобы выполнить динамически созданный код, используйте VirtualAllocEx для выделения памяти и функции VirtualProtectEx для предоставления доступа PAGE_EXECUTE.

Функцию VirtualAllocEx можно использовать для резервирования расширений окна адресов (AWE) памяти в виртуальном адресном пространстве указанного процесса. Затем этот регион памяти можно использовать для сопоставления физических страниц с виртуальной памятью и из нее, как это требуется приложению. Значения MEM_PHYSICAL и MEM_RESERVE должны быть заданы в параметре AllocationType. Значение MEM_COMMIT не должно быть задано. Для защиты страницы необходимо задать значение PAGE_READWRITE.

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

При создании региона, который будет исполняемым, вызывающая программа несет ответственность за обеспечение совместного использования кэша с помощью соответствующего вызова FlushInstructionCache после установки кода. В противном случае попытки выполнить код из только что исполняемого региона могут привести к непредсказуемым результатам.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	memoryapi.h (включая Windows.h, Memoryapi.h)
библиотеки	onecore.lib
DLL	Kernel32.dll