Función VirtualAllocEx (memoryapi.h)

Artículo
07/16/2024

Reserva, confirma o cambia el estado de una región de memoria dentro del espacio de direcciones virtuales de un proceso especificado. La función inicializa la memoria que asigna a cero.

Para especificar el nodo NUMA para la memoria física, consulte VirtualAllocExNuma.

Sintaxis

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

Parámetros

[in] hProcess

Identificador de un proceso. La función asigna memoria dentro del espacio de direcciones virtual de este proceso.

El identificador debe tener el PROCESS_VM_OPERATION derecho de acceso. Para obtener más información, consulte Derechos de acceso y seguridad de procesos.

[in, optional] lpAddress

Puntero que especifica una dirección inicial deseada para la región de páginas que desea asignar.

Si reserva memoria, la función redondea esta dirección hasta el múltiplo más cercano de la granularidad de asignación.

Si confirma la memoria que ya está reservada, la función redondea esta dirección hasta el límite de página más cercano. Para determinar el tamaño de una página y la granularidad de asignación en el equipo host, use la función GetSystemInfo.

Si lpAddress es NULL, la función determina dónde asignar la región.

Si esta dirección está dentro de un enclave que no se ha inicializado llamando a InitializeEnclave, VirtualAllocEx asigna una página de ceros para el enclave en esa dirección. La página debe no confirmarse previamente y no se medirá con la instrucción EEXTEND del modelo de programación intel Software Guard Extensions.

Si la dirección de dentro de un enclave inicializado, se produce un error en la operación de asignación con el error ERROR_INVALID_ADDRESS. Esto es cierto para enclaves que no admiten la administración dinámica de memoria (es decir, SGX1). Los enclaves SGX2 permitirán la asignación y el enclave debe aceptar la página una vez asignado.

[in] dwSize

Tamaño de la región de memoria que se va a asignar, en bytes.

Si lpAddress es NULL, la función redondea dwSize hasta el límite de la página siguiente.

Si lpAddress no es NULL, la función asigna todas las páginas que contienen uno o más bytes en el intervalo desde lpAddress a lpAddress+dwSize. Esto significa, por ejemplo, que un intervalo de 2 bytes que extiende un límite de página hace que la función asigne ambas páginas.

[in] flAllocationType

Tipo de asignación de memoria. Este parámetro debe contener uno de los siguientes valores.

Valor	Significado
MEM_COMMIT 0x00001000	Asigna cargos de memoria (del tamaño general de la memoria y de los archivos de paginación en el disco) para las páginas de memoria reservadas especificadas. La función también garantiza que cuando el autor de la llamada accede inicialmente a la memoria, el contenido será cero. Las páginas físicas reales no se asignan a menos que se acceda realmente a las direcciones virtuales o hasta que se acceda a ellas. Para reservar y confirmar páginas en un paso, llame a virtualAllocEx con `MEM_COMMIT \| MEM_RESERVE`. Si intenta confirmar un intervalo de direcciones específico, especifique MEM_COMMIT sin MEM_RESERVE y unNULLlpAddress produce un error a menos que ya se haya reservado todo el intervalo. El código de error resultante es ERROR_INVALID_ADDRESS. Un intento de confirmar una página que ya está confirmada no hace que se produzca un error en la función. Esto significa que puede confirmar páginas sin determinar primero el estado de compromiso actual de cada página. Si lpAddress especifica una dirección dentro de un enclave, flAllocationType debe ser MEM_COMMIT.
MEM_RESERVE 0x00002000	Reserva un intervalo del espacio de direcciones virtuales del proceso sin asignar ningún almacenamiento físico real en memoria o en el archivo de paginación en el disco. Las páginas reservadas se confirman llamando a virtualAllocEx de nuevo con MEM_COMMIT. Para reservar y confirmar páginas en un paso, llame a virtualAllocEx con `MEM_COMMIT \| MEM_RESERVE`. Otras funciones de asignación de memoria, como malloc y LocalAlloc, no pueden usar memoria reservada hasta que se haya liberado.
MEM_RESET 0x00080000	Indica que los datos del intervalo de memoria especificados por lpAddress y dwSize ya no son de interés. Las páginas no deben leerse ni escribirse en el archivo de paginación. Sin embargo, el bloque de memoria se usará de nuevo más adelante, por lo que no debe descommitido. Este valor no se puede usar con ningún otro valor. El uso de este valor no garantiza que el intervalo operado con MEM_RESET contendrá ceros. Si desea que el intervalo contenga ceros, descommita la memoria y, a continuación, vuelva a enviarla. Cuando se usa MEM_RESET, la función VirtualAllocEx omite el valor de fProtect. Sin embargo, debe establecer fProtect en un valor de protección válido, como PAGE_NOACCESS. virtualAllocEx devuelve un error si usa MEM_RESET y el intervalo de memoria se asigna a un archivo. Una vista compartida solo es aceptable si se asigna a un archivo de paginación.
MEM_RESET_UNDO 0x1000000	MEM_RESET_UNDO solo se debe llamar en un intervalo de direcciones al que MEM_RESET se aplicó correctamente anteriormente. Indica que los datos del intervalo de memoria especificado por lpAddress y dwSize es de interés para el autor de la llamada e intenta invertir los efectos de MEM_RESET. Si la función se ejecuta correctamente, significa que todos los datos del intervalo de direcciones especificados están intactos. Si se produce un error en la función, al menos algunos de los datos del intervalo de direcciones se han reemplazado por ceros. Este valor no se puede usar con ningún otro valor. Si se llama a MEM_RESET_UNDO en un intervalo de direcciones que no se MEM_RESET anteriormente, el comportamiento no está definido. Al especificar MEM_RESET, la función VirtualAllocEx omite el valor de flProtect. Sin embargo, todavía debe establecer flProtect en un valor de protección válido, como PAGE_NOACCESS. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: La marca de MEM_RESET_UNDO no se admite hasta Windows 8 y Windows Server 2012.

Este parámetro también puede especificar los siguientes valores como se indica.

Valor	Significado
MEM_LARGE_PAGES 0x20000000	Asigna memoria mediante compatibilidad con páginas grandes. El tamaño y la alineación deben ser varios de los mínimos de página grande. Para obtener este valor, use la función GetLargePageMinimum. Si especifica este valor, también debe especificar MEM_RESERVE y MEM_COMMIT.
MEM_PHYSICAL 0x00400000	Reserva un intervalo de direcciones que se puede usar para asignar páginas extensiones de ventana de direcciones (AWE). Este valor se debe usar con MEM_RESERVE y ningún otro valor.
MEM_TOP_DOWN 0x00100000	Asigna memoria en la dirección más alta posible. Esto puede ser más lento que las asignaciones normales, especialmente cuando hay muchas asignaciones.

Valor

Significado

MEM_LARGE_PAGES
0x20000000

Asigna memoria mediante compatibilidad con páginas grandes.

El tamaño y la alineación deben ser varios de los mínimos de página grande. Para obtener este valor, use la función GetLargePageMinimum.

Si especifica este valor, también debe especificar MEM_RESERVE y MEM_COMMIT.

MEM_PHYSICAL
0x00400000

Reserva un intervalo de direcciones que se puede usar para asignar páginas extensiones de ventana de direcciones (AWE).

Este valor se debe usar con MEM_RESERVE y ningún otro valor.

MEM_TOP_DOWN
0x00100000

Asigna memoria en la dirección más alta posible. Esto puede ser más lento que las asignaciones normales, especialmente cuando hay muchas asignaciones.

[in] flProtect

Protección de memoria para la región de páginas que se va a asignar. Si se confirman las páginas, puede especificar cualquiera de las constantes de protección de memoria .

Si lpAddress especifica una dirección dentro de un enclave, flProtect no puede ser ninguno de los valores siguientes:

PAGE_NOACCESS
PAGE_GUARD
PAGE_NOCACHE
PAGE_WRITECOMBINE

Al asignar memoria dinámica para un enclave, el parámetro flProtect debe ser PAGE_READWRITE o PAGE_EXECUTE_READWRITE.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es la dirección base de la región asignada de páginas.

Si se produce un error en la función, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Observaciones

Cada página tiene un estado de página de asociado. La función virtualAllocEx puede realizar las siguientes operaciones:

Confirmación de una región de páginas reservadas
Reserva de una región de páginas gratuitas
Reservar y confirmar simultáneamente una región de páginas gratuitas

virtualAllocEx no puede reservar una página reservada. Puede confirmar una página que ya está confirmada. Esto significa que puede confirmar un intervalo de páginas, independientemente de si ya se han confirmado y la función no producirá un error.

Puede usar VirtualAllocEx para reservar un bloque de páginas y, a continuación, realizar llamadas adicionales a VirtualAllocEx para confirmar páginas individuales desde el bloque reservado. Esto permite que un proceso reserve un intervalo de su espacio de direcciones virtual sin consumir almacenamiento físico hasta que sea necesario.

Si el parámetro de lpAddress no es null, la función usa el lpAddress y dwSize parámetros para calcular la región de las páginas que se van a asignar. El estado actual de todo el intervalo de páginas debe ser compatible con el tipo de asignación especificado por el parámetro flAllocationType. De lo contrario, se produce un error en la función y no se asigna ninguna de las páginas. Este requisito de compatibilidad no impide confirmar una página ya confirmada; consulte la lista anterior.

Para ejecutar código generado dinámicamente, use VirtualAllocEx para asignar memoria y la función VirtualProtectEx para conceder acceso a PAGE_EXECUTE.

La función virtualAllocEx se puede usar para reservar una extensiones de ventana de direcciones (AWE) región de memoria dentro del espacio de direcciones virtual de un proceso especificado. Después, esta región de memoria se puede usar para asignar páginas físicas dentro y fuera de la memoria virtual según lo requiera la aplicación. Los valores MEM_PHYSICAL y MEM_RESERVE deben establecerse en el parámetro allocationType de . No se debe establecer el valor de MEM_COMMIT. La protección de páginas debe establecerse en PAGE_READWRITE.

La función VirtualFreeEx puede descommitir una página confirmada, liberar el almacenamiento de la página o puede descommitir y liberar simultáneamente una página confirmada. También puede liberar una página reservada, lo que lo convierte en una página gratuita.

Al crear una región que será ejecutable, el programa de llamada asume la responsabilidad de garantizar la coherencia de caché a través de una llamada adecuada a FlushInstructionCache una vez establecido el código. De lo contrario, los intentos de ejecutar código fuera de la región ejecutable recién pueden producir resultados impredecibles.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2003 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	memoryapi.h (incluya Windows.h, Memoryapi.h)
biblioteca de	onecore.lib
DLL de	Kernel32.dll