CreateFileMappingNumaW 函数 （memoryapi.h）
为指定文件创建或打开命名或未命名的文件映射对象，并为物理内存指定 NUMA 节点。
语法
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
);
参数
[in] hFile
要从中创建文件映射对象的文件的句柄。
必须使用与 flProtect 参数指定的保护标志兼容的访问权限打开该文件。 这不是必需的，但建议打开要映射的文件进行独占访问。 有关详细信息，请参阅 文件安全和访问权限。
如果 INVALID_HANDLE_VALUEhFile，调用过程还必须在 dwMaximumSizeHigh 中指定文件映射对象的大小，并 dwMaximumSizeLow 参数。 在此方案中，CreateFileMappingNuma 创建由系统分页文件而不是文件系统中的文件提供支持的指定大小的文件映射对象。
[in, optional] lpFileMappingAttributes
指向 SECURITY_ATTRIBUTES 结构的指针，该结构确定返回的句柄是否可以由子进程继承。
lpSecurityDescriptor 成员
SECURITY_ATTRIBUTES 结构为新的文件映射对象指定安全描述符。
如果 lpFileMappingAttributesNULL，则无法继承句柄，并且文件映射对象获取默认的安全描述符。 文件映射对象的默认安全描述符中的访问控制列表（ACL）来自创建者的主要或模拟令牌。 有关详细信息，请参阅 文件映射安全和访问权限。
[in] flProtect
指定文件映射对象的页面保护。 对象的所有映射视图都必须与此保护兼容。
此参数可以是下列值之一。
应用程序可以通过将它们与前面的页面保护值之一组合，为文件映射对象指定以下一个或多个属性。
| 价值 | 意义 |
|---|---|
|
为所有页面分配内存中的物理存储或分页文件。
这是默认设置。 |
|
设置指定为可执行映像文件的文件。
SEC_IMAGE 属性必须与页面保护值（如 PAGE_READONLY）结合使用。 但是，此页面保护值对可执行文件的视图没有影响。 可执行映像文件的视图的页面保护由可执行文件本身决定。 没有其他属性对 SEC_IMAGE有效。 |
|
指定 hFile 参数指定的文件是不会执行的可执行映像文件，并且加载的图像文件不会运行强制完整性检查。
此外，使用 SEC_IMAGE_NO_EXECUTE 属性创建的文件映射对象的视图不会调用使用 PsSetLoadImageNotifyRoutine 内核 API 注册的驱动程序回调。
SEC_IMAGE_NO_EXECUTE 属性必须与 PAGE_READONLY 页保护值结合使用。 没有其他属性对 SEC_IMAGE_NO_EXECUTE有效。 Windows Server 2008 R2、Windows 7、Windows Server 2008 和 Windows Vista：Windows Server 2012 和 Windows 8 之前不支持此值。 |
|
允许在映射图像或从页面文件进行支持时使用大型页面，但在映射常规文件的数据时不能使用。 请务必将文件映射对象的最大大小指定为 GetLargePageMinimum 函数报告的大型页面的最小大小，并启用 SeLockMemoryPrivilege 特权。 |
|
将所有页面设置为不可访问。
应用程序不应使用此标志，除非设备明确需要时。 将互锁函数与与 SEC_NOCACHE 映射的内存配合使用可能会导致 EXCEPTION_ILLEGAL_INSTRUCTION 异常。 SEC_NOCACHE 需要设置 SEC_RESERVE 或 SEC_COMMIT。 |
|
保留所有页面，而无需分配物理存储。
在释放页面范围之前，任何其他分配操作都不能使用保留页范围。 可以在对 VirtualAllocExNuma 函数的后续调用中标识保留页。 仅当 hFile 参数 INVALID_HANDLE_VALUE（即系统分页文件支持的文件映射对象）时，此属性才有效。 |
|
设置要组合写入的所有页面。
应用程序不应使用此属性，除非设备明确需要时。 将互锁函数与与 SEC_WRITECOMBINE 映射的内存配合使用可能会导致 EXCEPTION_ILLEGAL_INSTRUCTION 异常。 SEC_WRITECOMBINE 要求设置 SEC_RESERVE 或 SEC_COMMIT 属性。 |
[in] dwMaximumSizeHigh
文件映射对象的最大大小的高阶 DWORD。
[in] dwMaximumSizeLow
文件映射对象最大大小的低序 DWORD。
如果此参数和 dwMaximumSizeHigh 参数为 0（零），则文件映射对象的最大大小等于 hFile 参数标识的文件的当前大小。
尝试映射长度为 0（零）的文件失败，错误代码为 ERROR_FILE_INVALID。 应用程序应测试长度为 0（零）的文件，并拒绝这些文件。
[in, optional] lpName
文件映射对象的名称。
如果此参数与现有文件映射对象的名称匹配，函数将请求访问具有 flProtect 参数所指定的保护的对象。
如果此参数 NULL，则创建文件映射对象时不带名称。
如果 lpName 参数与现有事件、信号灯、互斥体、可等待计时器或作业对象的名称匹配，则函数将失败，GetLastError 函数返回 ERROR_INVALID_HANDLE。 之所以发生这种情况，是因为这些对象共享相同的命名空间。
该名称可以具有“全局”或“本地”前缀，以在全局或会话命名空间中显式创建对象。 名称的其余部分可以包含除反斜杠字符（\）以外的任何字符。 在全局命名空间中创建文件映射对象需要 SeCreateGlobalPrivilege 特权。 有关详细信息，请参阅 内核对象命名空间。
使用终端服务会话实现快速用户切换。 第一个登录的用户使用会话 0 （零），下一个登录的用户使用会话 1（一），依此等。 内核对象名称必须遵循准则，以便应用程序能够支持多个用户。
[in] nndPreferred
物理内存应驻留的 NUMA 节点。
| 价值 | 意义 |
|---|---|
|
首选无 NUMA 节点。 这与调用 CreateFileMapping 函数相同。 |
返回值
如果函数成功，则返回值是文件映射对象的句柄。
如果在函数调用之前存在该对象，该函数将返回现有对象的句柄（其当前大小，而不是指定大小），GetLastError 函数返回 ERROR_ALREADY_EXISTS。
如果函数失败，则返回值 NULL。 若要获取扩展的错误信息，请调用 GetLastError 函数。
言论
创建文件映射对象后，文件的大小不得超过文件映射对象的大小;如果存在，则并非所有文件内容都可用于共享。
文件映射对象可以通过重复、继承或名称共享。 由页面文件支持的文件映射对象中页面的初始内容为 0（零）。
如果应用程序指定的文件映射对象的大小大于磁盘上实际命名文件的大小，并且如果页面保护允许写入访问（即，flProtect 参数指定 PAGE_READWRITE 或 PAGE_EXECUTE_READWRITE），则磁盘上的文件将增加以匹配文件映射对象的指定大小。 如果文件已扩展，则文件旧端和文件新端之间的内容不保证为零;行为由文件系统定义。
如果无法增加文件，则结果为创建文件映射对象失败，GetLastError 函数返回 ERROR_DISK_FULL。
CreateFileMappingNuma 函数返回的句柄对新文件映射对象具有完全访问权限，并且可以与需要文件映射对象的句柄的任何函数一起使用。 可以通过进程创建、处理重复或按名称共享文件映射对象。 有关详细信息，请参阅 DuplicateHandle 和 OpenFileMapping 函数。
创建文件映射对象可以映射文件的视图，但不映射视图。 MapViewOfFileExNuma 函数将文件的视图映射到进程地址空间中。
有一个重要例外，从单个文件映射对象派生的文件视图在特定时间是一致的或相同的。 如果多个进程具有同一文件映射对象的句柄，则它们会在映射文件的视图时看到数据的一致视图。
异常与远程文件相关。 尽管 CreateFileMappingNuma 函数适用于远程文件，但它不会使它们保持一致。 例如，如果两台计算机将文件映射为可写文件，并且两者都更改了同一页，则每台计算机只看到其自己的写入页。 在磁盘上更新数据时，不会合并页面。
使用输入和输出（I/O）函数（ReadFile 和 WriteFile）访问的映射文件和文件不一定是一致的。
若要完全关闭文件映射对象，应用程序必须通过调用 UnmapViewOfFile 函数来取消映射文件映射对象的所有映射视图，然后通过调用 CloseHandle 函数关闭文件映射对象句柄。
可以按任意顺序调用这些函数。 必须调用 UnmapViewOfFile 函数，因为文件映射对象的映射视图维护对象的内部打开句柄，并且文件映射对象在关闭所有打开句柄之前不会关闭。
通过映射视图修改文件时，可能不会自动更新上次修改时间戳。 如果需要，调用方应使用 SetFileTime 来设置时间戳。
从会话零以外的会话创建文件映射对象需要 SeCreateGlobalPrivilege 特权。 请注意，此特权检查仅限于创建文件映射对象，不适用于打开现有对象。 例如，如果服务或系统创建文件映射对象，则任何会话中运行的任何进程都可以访问该文件映射对象，前提是调用方具有所需的访问权限。
使用结构化异常处理来保护写入或读取内存映射视图的任何代码。 有关详细信息，请参阅 从文件视图读取和写入。
若要具有可执行权限的映射，应用程序必须使用 PAGE_EXECUTE_READWRITE 或 PAGE_EXECUTE_READ 调用 CreateFileMappingNuma 函数，然后使用 FILE_MAP_EXECUTE | FILE_MAP_WRITE 或 FILE_MAP_EXECUTE | FILE_MAP_READ调用 MapViewOfFileExNuma 函数。
在 Windows Server 2012 中，以下技术支持此函数。
| 科技 | 支持 |
|---|---|
| 服务器消息块 （SMB） 3.0 协议 | 是的 |
| SMB 3.0 透明故障转移 （TFO） | 是的 |
| 具有横向扩展文件共享的 SMB 3.0 （SO） | 是的 |
| 群集共享卷文件系统 （CsvFS） | 是的 |
| 可复原文件系统 （ReFS） | 是的 |
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows Vista [仅限桌面应用] |
| 支持的最低服务器 | Windows Server 2008 [仅限桌面应用] |
| 目标平台 | 窗户 |
| 标头 | memoryapi.h （包括 Windows.h、Memoryapi.h） |
| 库 | onecore.lib |
| DLL | Kernel32.dll |