Función CreateFileMapping2 (memoryapi.h)

Crea o abre un objeto de asignación de archivos con nombre o sin nombre para un archivo especificado. Puede especificar un nodo NUMA preferido para la memoria física como parámetro extendido; consulte el parámetro ExtendedParameters.

Sintaxis

HANDLE CreateFileMapping2(
  HANDLE                 File,
  SECURITY_ATTRIBUTES    *SecurityAttributes,
  ULONG                  DesiredAccess,
  ULONG                  PageProtection,
  ULONG                  AllocationAttributes,
  ULONG64                MaximumSize,
  PCWSTR                 Name,
  MEM_EXTENDED_PARAMETER *ExtendedParameters,
  ULONG                  ParameterCount
);

Parámetros

File

Tipo: _In_ HANDLE

Identificador del archivo desde el que se va a crear un objeto de asignación de archivos.

El archivo debe abrirse con derechos de acceso compatibles con las marcas de protección que especifica el parámetro flProtect. No es necesario, pero se recomienda que los archivos que quiera asignar se abran para el acceso exclusivo. Para obtener más información, consulte Derechos de acceso y seguridad de archivos.

Si hFile es INVALID_HANDLE_VALUE, el proceso de llamada también debe especificar un tamaño para el objeto de asignación de archivos en el dwMaximumSizeHigh y parámetros dwMaximumSizeLow. En este escenario, CreateFileMapping crea un objeto de asignación de archivos de un tamaño especificado respaldado por el archivo de paginación del sistema en lugar de un archivo en el sistema de archivos.

SecurityAttributes

Tipo: _In_opt_ SECURITY_ATTRIBUTES*

Puntero a una estructura de SECURITY_ATTRIBUTES que determina si los procesos secundarios pueden heredar un identificador devuelto. El miembro lpSecurityDescriptor de la estructura SECURITY_ATTRIBUTES especifica un descriptor de seguridad para un nuevo objeto de asignación de archivos.

Si lpAttributes es null, el identificador no se puede heredar y el objeto de asignación de archivos obtiene un descriptor de seguridad predeterminado. Las listas de control de acceso (ACL) del descriptor de seguridad predeterminado para un objeto de asignación de archivos proceden del token principal o de suplantación del creador. Para obtener más información, vea seguridad de asignación de archivos y derechos de acceso.

DesiredAccess

Tipo: _In_ ULONG

Máscara de acceso deseada para el identificador de asignación de archivos devuelto. Para obtener una lista de los derechos de acceso, consulte seguridad de asignación de archivos y derechos de acceso.

PageProtection

Tipo: _In_ ULONG

Especifica la protección de páginas del objeto de asignación de archivos. Todas las vistas asignadas del objeto deben ser compatibles con esta protección.

Este parámetro puede ser uno de los siguientes valores.

Valor Significado
PAGE_EXECUTE_READ
0x20
Permite asignar vistas para el acceso de solo lectura, copia en escritura o ejecución.

El identificador de archivo especificado por el parámetro hFile debe crearse con los derechos de acceso GENERIC_READ y GENERIC_EXECUTE.

Windows Server 2003 y Windows XP: Este valor no está disponible hasta Windows XP con SP2 y Windows Server 2003 con SP1.

PAGE_EXECUTE_READWRITE
0x40
Permite asignar vistas para el acceso de solo lectura, copia en escritura, lectura y escritura o ejecución.

El identificador de archivo que especifica el parámetro hFile debe crearse con los derechos de acceso GENERIC_READ, GENERIC_WRITEy GENERIC_EXECUTE.

Windows Server 2003 y Windows XP: Este valor no está disponible hasta Windows XP con SP2 y Windows Server 2003 con SP1.

PAGE_EXECUTE_WRITECOPY
0x80
Permite asignar vistas para el acceso de solo lectura, copia en escritura o ejecución. Este valor es equivalente a PAGE_EXECUTE_READ.

El identificador de archivo que especifica el parámetro hFile debe crearse con los derechos de acceso GENERIC_READ y GENERIC_EXECUTE.

Windows Vista: Este valor no está disponible hasta Que Windows Vista con SP1.

Windows Server 2003 y Windows XP: Este valor no se admite.

PAGE_READONLY
0x02
Permite asignar vistas para el acceso de solo lectura o copia en escritura. Un intento de escribir en una región específica produce una infracción de acceso.

El identificador de archivo que el parámetro hFile especifica debe crearse con el derecho de acceso GENERIC_READ.

PAGE_READWRITE
0x04
Permite asignar vistas para el acceso de solo lectura, copia en escritura o lectura y escritura.

El identificador de archivo que el parámetro hFile especifica debe crearse con los derechos de acceso GENERIC_READ y GENERIC_WRITE.

PAGE_WRITECOPY
0x08
Permite asignar vistas para el acceso de solo lectura o copia en escritura. Este valor es equivalente a PAGE_READONLY.

El identificador de archivo que el parámetro hFile especifica debe crearse con el derecho de acceso GENERIC_READ.

AllocationAttributes

Tipo: _In_ ULONG

Puede especificar uno o varios de los atributos siguientes para el objeto de asignación de archivos. Consulte también el parámetro PageProtection.

Valor Significado
SEC_COMMIT
0x8000000
Si el archivo de paginación del sistema operativo respalda el objeto de asignación de archivos (el parámetro hfile es INVALID_HANDLE_VALUE), especifica que cuando se asigna una vista del archivo a un espacio de direcciones de proceso, se confirma todo el intervalo de páginas en lugar de reservado. El sistema debe tener suficientes páginas confirmables para contener toda la asignación. De lo contrario, error CreateFileMapping.

Este atributo no tiene ningún efecto para los objetos de asignación de archivos respaldados por archivos de imagen ejecutables o archivos de datos (el parámetro hfile es un identificador de un archivo).

SEC_COMMIT no se puede combinar con SEC_RESERVE.

Si no se especifica ningún atributo, se supone SEC_COMMIT.

SEC_IMAGE
0x1000000
Especifica que el archivo que especifica el parámetro hFile es un archivo de imagen ejecutable.

El atributo SEC_IMAGE debe combinarse con un valor de protección de páginas, como PAGE_READONLY. Sin embargo, este valor de protección de páginas no tiene ningún efecto en las vistas del archivo de imagen ejecutable. La protección de páginas para vistas de un archivo de imagen ejecutable viene determinada por el propio archivo ejecutable.

Ningún otro atributo es válido con SEC_IMAGE.

SEC_IMAGE_NO_EXECUTE
0x11000000
Especifica que el archivo que especifica el parámetro hFile es un archivo de imagen ejecutable que no se ejecutará y el archivo de imagen cargado no tendrá ninguna comprobación de integridad forzada ejecutada. Además, la asignación de una vista de un objeto de asignación de archivos creado con el atributo SEC_IMAGE_NO_EXECUTE no invocará las devoluciones de llamada del controlador registradas mediante la API de kernel de psSetLoadImageNotifyRoutine .

El atributo SEC_IMAGE_NO_EXECUTE debe combinarse con el valor de protección de página PAGE_READONLY. Ningún otro atributo es válido con SEC_IMAGE_NO_EXECUTE.

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este valor no se admite antes de Windows Server 2012 y Windows 8.

SEC_LARGE_PAGES
0x80000000
Permite usar páginas grandes para los objetos de asignación de archivos respaldados por el archivo de paginación del sistema operativo (el parámetro hfile es INVALID_HANDLE_VALUE). Este atributo no se admite para los objetos de asignación de archivos respaldados por archivos de imagen ejecutables o archivos de datos (el parámetro hFile es un identificador de una imagen ejecutable o un archivo de datos).

El tamaño máximo del objeto de asignación de archivos debe ser un múltiplo del tamaño mínimo de una página grande devuelta por la función GetLargePageMinimum. Si no es así, error CreateFileMapping. Al asignar una vista de un objeto de asignación de archivos creado con SEC_LARGE_PAGES, la dirección base y el tamaño de la vista también deben ser múltiplo del tamaño mínimo de página grande.

SEC_LARGE_PAGES requiere que el privilegio SeLockMemoryPrivilege esté habilitado en el token del autor de la llamada.

Si se especifica SEC_LARGE_PAGES, también se debe especificar SEC_COMMIT.

Windows Server 2003: Este valor no se admite hasta Windows Server 2003 con SP1.

Windows XP: Este valor no se admite.

SEC_NOCACHE
0x10000000
Establece que todas las páginas no se puedan almacenar en caché.

Las aplicaciones no deben usar este atributo, excepto cuando se requiera explícitamente para un dispositivo. El uso de las funciones interbloqueadas con memoria asignada con SEC_NOCACHE puede dar lugar a una excepción de EXCEPTION_ILLEGAL_INSTRUCTION.

SEC_NOCACHE requiere que se establezca el atributo SEC_RESERVE o SEC_COMMIT.

SEC_RESERVE
0x4000000
Si el archivo de paginación del sistema operativo respalda el objeto de asignación de archivos (el parámetro hfile es INVALID_HANDLE_VALUE), especifica que cuando se asigna una vista del archivo a un espacio de direcciones de proceso, el intervalo completo de páginas se reserva para su uso posterior en lugar de confirmarse.

Las páginas reservadas se pueden confirmar en llamadas posteriores a la función VirtualAlloc. Una vez confirmadas las páginas, no se pueden liberar ni descommitar con la función virtualFree de .

Este atributo no tiene ningún efecto para los objetos de asignación de archivos respaldados por archivos de imagen ejecutables o archivos de datos (el parámetro hfile es un identificador de un archivo).

SEC_RESERVE no se puede combinar con SEC_COMMIT.

SEC_WRITECOMBINE
0x40000000
Establece todas las páginas que se van a combinar.

Las aplicaciones no deben usar este atributo, excepto cuando se requiera explícitamente para un dispositivo. El uso de las funciones interbloqueadas con memoria asignada con SEC_WRITECOMBINE puede dar lugar a una excepción de EXCEPTION_ILLEGAL_INSTRUCTION.

SEC_WRITECOMBINE requiere que se establezca el atributo SEC_RESERVE o SEC_COMMIT.

Windows Server 2003 y Windows XP: Esta marca no se admite hasta Windows Vista.

MaximumSize

Tipo: _In_ ULONG64

Tamaño máximo del objeto de asignación de archivos.

Si este parámetro es 0 (cero), el tamaño máximo del objeto de asignación de archivos es igual al tamaño actual del archivo que hFile identifica.

Se produce un error al intentar asignar un archivo con una longitud de 0 (cero) con un código de error de ERROR_FILE_INVALID. Debe probar los archivos con una longitud de 0 (cero) y rechazar esos archivos.

Name

Tipo: PCWSTR de _In_opt_

Nombre del objeto de asignación de archivos.

Si este parámetro coincide con el nombre de un objeto de asignación existente, la función solicita acceso al objeto con la protección que flProtect especifica.

Si este parámetro es NULL, el objeto de asignación de archivos se crea sin un nombre.

Si lpName coincide con el nombre de un evento existente, semáforo, exclusión mutua, temporizador de espera o objeto de trabajo, se produce un error en la función y la función GetLastError devuelve ERROR_INVALID_HANDLE. Esto ocurre porque estos objetos comparten el mismo espacio de nombres.

El nombre puede tener un prefijo "Global" o "Local" para crear explícitamente el objeto en el espacio de nombres global o de sesión. El resto del nombre puede contener cualquier carácter excepto el carácter de barra diagonal inversa (\). La creación de un objeto de asignación de archivos en el espacio de nombres global desde una sesión distinta de la sesión cero requiere el privilegio SeCreateGlobalPrivilege. Para obtener más información, vea espacios de nombres de objeto kernel.

El cambio rápido de usuario se implementa mediante sesiones de Terminal Services. El primer usuario en iniciar sesión usa la sesión 0 (cero), el siguiente usuario para iniciar sesión usa la sesión 1 (una), etc. Los nombres de objeto de kernel deben seguir las directrices que se describen para Terminal Services para que las aplicaciones puedan admitir varios usuarios.

ExtendedParameters

Tipo: MEM_EXTENDED_PARAMETER* _Inout_updates_opt_(ParameterCount)

Puntero opcional a uno o varios parámetros extendidos de tipo MEM_EXTENDED_PARAMETER. Cada uno de esos valores de parámetro extendidos puede tener un campo Type de MemExtendedParameterAddressRequirements o MemExtendedParameterNumaNode. Si no se proporciona ningún parámetro extendido MemExtendedParameterNumaNode, el comportamiento es el mismo que para las funciones VirtualAlloc/MapViewOfFile (es decir, el nodo NUMA preferido para las páginas físicas se determina en función del procesador ideal del subproceso que accede primero a la memoria).

ParameterCount

En ParámetroS de ULONGCount

Número de parámetros extendidos a los que apunta ExtendedParameters.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador del objeto de asignación de archivos recién creado.

Si el objeto existe antes de la llamada de función, la función devuelve un identificador al objeto existente (con su tamaño actual, no el tamaño especificado) y GetLastError devuelve ERROR_ALREADY_EXISTS.

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

Consulte el comentarios de para CreateFileMapping.

Ejemplos

Para obtener un ejemplo, vea Crear memoria compartida con nombreo Creación de una asignación de archivos mediante páginas grandes.

Requisitos

Requisito Valor
cliente mínimo admitido Compilación 20348 de Windows 10
servidor mínimo admitido Compilación 20348 de Windows 10
de la plataforma de destino de Windows
encabezado de memoryapi.h (incluya Windows.h, Memoryapi.h)
biblioteca de onecore.lib
DLL de Kernel32.dll

Consulte también

CloseHandle

CreateFileMappingNuma

Creación de un objeto de asignación de archivos

DuplicateHandle

MapViewOfFile

MapViewOfFileEx

funciones de administración de memoria de

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile