Función CreateFileMappingNumaW (memoryapi.h)
Crea o abre un objeto de asignación de archivos con nombre o sin nombre para un archivo especificado y especifica el nodo NUMA para la memoria física.
Sintaxis
HANDLE CreateFileMappingNumaW(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCWSTR lpName,
[in] DWORD nndPreferred
);
Parámetros
[in] hFile
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, vea Seguridad de archivos y derechos de acceso.
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 los parámetros dwMaximumSizeHizeHigh y dwMaximumSizeLow . En este escenario, CreateFileMappingNuma 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.
[in, optional] lpFileMappingAttributes
Puntero a una estructura de SECURITY_ATTRIBUTES que determina si los procesos secundarios pueden heredar un identificador devuelto. El miembro lpSecurityDescriptor del
SECURITY_ATTRIBUTES estructura especifica un descriptor de seguridad para un nuevo objeto de asignación de archivos.
Si lpFileMappingAttributes 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.
[in] flProtect
Especifica la protección de página 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 valores siguientes.
Una aplicación puede especificar uno o varios de los siguientes atributos para el objeto de asignación de archivos combinándolos con uno de los valores de protección de página anteriores.
| Valor | Significado |
|---|---|
|
Asigna almacenamiento físico en memoria o el archivo de paginación de todas las páginas.
Esta es la configuración predeterminada. |
|
Establece el archivo especificado para que sea 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. |
|
Especifica que el archivo que especifica el parámetro hFile es un archivo de imagen ejecutable que no se ejecutará y que 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 del kernel 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 y Windows Vista: Este valor no se admite antes de Windows Server 2012 y Windows 8. |
|
Permite usar páginas grandes al asignar imágenes o realizar copias de seguridad desde el archivo de páginas, pero no al asignar datos para archivos normales. Asegúrese de especificar el tamaño máximo del objeto de asignación de archivos como el tamaño mínimo de una página grande notificada por la función GetLargePageMinimum y para habilitar el privilegio SeLockMemoryPrivilege . |
|
Establece todas las páginas en que no se pueden almacenar en caché.
Las aplicaciones no deben usar esta marca 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 SEC_RESERVE o SEC_COMMIT establecer. |
|
Reserva todas las páginas sin asignar almacenamiento físico.
Las demás operaciones de asignación no pueden usar el intervalo reservado de páginas hasta que se libere el intervalo de páginas. Las páginas reservadas se pueden identificar en llamadas posteriores a la función VirtualAllocExNuma . Este atributo solo es válido si el parámetro hFile es INVALID_HANDLE_VALUE (es decir, un objeto de asignación de archivos respaldado por el archivo de paginación del sistema). |
|
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 . |
[in] dwMaximumSizeHigh
DWORD de orden superior del tamaño máximo del objeto de asignación de archivos.
[in] dwMaximumSizeLow
DWORD de orden bajo del tamaño máximo del objeto de asignación de archivos.
Si este parámetro y el parámetro dwMaximumSizeHigh son 0 (cero), el tamaño máximo del objeto de asignación de archivos es igual al tamaño actual del archivo que identifica el parámetro hFile .
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. Las aplicaciones deben probar los archivos con una longitud de 0 (cero) y rechazar esos archivos.
[in, optional] lpName
Nombre del objeto de asignación de archivos.
Si este parámetro coincide con el nombre de un objeto de asignación de archivos existente, la función solicita acceso al objeto con la protección que especifica el parámetro flProtect .
Si este parámetro es NULL, el objeto de asignación de archivos se crea sin un nombre.
Si el parámetro 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 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 para que las aplicaciones puedan admitir varios usuarios.
[in] nndPreferred
Nodo NUMA donde debe residir la memoria física.
| Valor | Significado |
|---|---|
|
No se prefiere ningún nodo NUMA. Esto es lo mismo que llamar a la función CreateFileMapping . |
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es un identificador para el objeto de asignación de archivos.
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 la función GetLastError devuelve ERROR_ALREADY_EXISTS.
Si la función no se realiza correctamente, el valor devuelto es NULL. Para obtener información ampliada de los errores, llame a la función GetLastError.
Comentarios
Una vez creado un objeto de asignación de archivos, el tamaño del archivo no debe superar el tamaño del objeto de asignación de archivos; si es así, no todo el contenido del archivo está disponible para compartirlo.
El objeto de asignación de archivos se puede compartir por duplicación, herencia o por nombre. El contenido inicial de las páginas de un objeto de asignación de archivos respaldado por el archivo de página es 0 (cero).
Si una aplicación especifica un tamaño para el objeto de asignación de archivos que es mayor que el tamaño del archivo con nombre real en el disco y si la protección de páginas permite el acceso de escritura (es decir, el parámetro flProtect especifica PAGE_READWRITE o PAGE_EXECUTE_READWRITE), el archivo en disco aumenta para que coincida con el tamaño especificado del objeto de asignación de archivos. Si el archivo se extiende, no se garantiza que el contenido del archivo entre el extremo anterior del archivo y el nuevo final del archivo sea cero; el comportamiento se define mediante el sistema de archivos.
Si no se puede aumentar el archivo, el resultado es un error al crear el objeto de asignación de archivos y la función GetLastError devuelve ERROR_DISK_FULL.
El identificador que devuelve la función CreateFileMappingNuma tiene acceso completo a un nuevo objeto de asignación de archivos y se puede usar con cualquier función que requiera un identificador para un objeto de asignación de archivos. Un objeto de asignación de archivos se puede compartir mediante la creación de procesos, controlar la duplicación o por nombre. Para obtener más información, consulte las funciones DuplicateHandle y OpenFileMapping .
La creación de un objeto de asignación de archivos crea la posibilidad de asignar una vista del archivo, pero no asigna la vista. La función MapViewOfFileExNuma asigna una vista de un archivo a un espacio de direcciones de proceso.
Con una excepción importante, las vistas de archivo derivadas de un único objeto de asignación de archivos son coherentes o idénticas en un momento específico. Si varios procesos tienen identificadores del mismo objeto de asignación de archivos, verán una vista coherente de los datos cuando asignan una vista del archivo.
La excepción está relacionada con los archivos remotos. Aunque la función CreateFileMappingNuma funciona con archivos remotos, no las mantiene coherentes. Por ejemplo, si dos equipos asignan un archivo como grabable y ambos cambian la misma página, cada equipo solo ve sus propias escrituras en la página. Cuando los datos se actualizan en el disco, la página no se combina.
Un archivo asignado y un archivo al que se tiene acceso mediante las funciones de entrada y salida (E/S) (ReadFile y WriteFile) no son necesariamente coherentes.
Para cerrar completamente un objeto de asignación de archivos, una aplicación debe desasignar todas las vistas asignadas del objeto de asignación de archivos mediante una llamada a la función UnmapViewOfFile y, a continuación, cerrar el identificador del objeto de asignación de archivos mediante una llamada a la función CloseHandle .
Estas funciones se pueden llamar en cualquier orden. La llamada a la función UnmapViewOfFile es necesaria, porque las vistas asignadas de un objeto de asignación de archivos mantienen identificadores abiertos internos al objeto y un objeto de asignación de archivos no se cierra hasta que se cierran todos los identificadores abiertos.
Al modificar un archivo a través de una vista asignada, es posible que la última marca de tiempo de modificación no se actualice automáticamente. Si es necesario, el autor de la llamada debe usar SetFileTime para establecer la marca de tiempo.
La creación de un objeto de asignación de archivos a partir de una sesión distinta de la sesión cero requiere el privilegio SeCreateGlobalPrivilege . Tenga en cuenta que esta comprobación de privilegios se limita a la creación de objetos de asignación de archivos y no se aplica a abrir las existentes. Por ejemplo, si un servicio o el sistema crean un objeto de asignación de archivos, cualquier proceso que se ejecute en cualquier sesión puede tener acceso a ese objeto de asignación de archivos siempre que el autor de la llamada tenga los derechos de acceso necesarios.
Use el control estructurado de excepciones para proteger cualquier código que escriba o lea desde una vista asignada de memoria. Para obtener más información, vea Lectura y escritura desde una vista de archivo.
Para tener una asignación con permisos ejecutables, una aplicación debe llamar a la función CreateFileMappingNuma con PAGE_EXECUTE_READWRITE o PAGE_EXECUTE_READ y, a continuación, llamar a la función MapViewOfFileExNuma con FILE_MAP_EXECUTE | FILE_MAP_WRITE o FILE_MAP_EXECUTE | FILE_MAP_READ.
En Windows Server 2012, esta función es compatible con las siguientes tecnologías.
| Tecnología | Compatible |
|---|---|
| Protocolo Bloque de mensajes del servidor (SMB) 3.0 | Sí |
| Conmutación por error transparente (TFO) de SMB 3.0 | Sí |
| SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO) | Sí |
| Sistema de archivos de Volumen compartido de clúster (CsvFS) | Sí |
| Sistema de archivos resistente a errores (ReFS) | Sí |
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | memoryapi.h (incluye Windows.h, Memoryapi.h) |
| Library | onecore.lib |
| Archivo DLL | Kernel32.dll |
Vea también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de