createFileMapping2 函数 (memoryapi.h)
为指定文件创建或打开命名或未命名的文件映射对象。 可以将物理内存的首选 NUMA 节点指定为扩展参数;请参阅 ExtendedParameters 参数。
语法
HANDLE CreateFileMapping2(
HANDLE File,
SECURITY_ATTRIBUTES *SecurityAttributes,
ULONG DesiredAccess,
ULONG PageProtection,
ULONG AllocationAttributes,
ULONG64 MaximumSize,
PCWSTR Name,
MEM_EXTENDED_PARAMETER *ExtendedParameters,
ULONG ParameterCount
);
parameters
File
类型：_In_ HANDLE
要从中创建文件映射对象的文件的句柄。
必须使用与 flProtect 参数指定的保护标志兼容的访问权限打开文件。 这不是必需的，但建议打开要映射的文件进行独占访问。 有关详细信息，请参阅 文件安全性和访问权限。
如果 hFile是INVALID_HANDLE_VALUE，则调用进程还必须在 dwMaximumSizeHigh 和 dwMaximumSizeLow 参数中指定文件映射对象的大小。 在此方案中， CreateFileMapping 会创建一个指定大小的文件映射对象，该对象由系统分页文件而不是文件系统中的文件提供支持。
SecurityAttributes
类型：_In_opt_ SECURITY_ATTRIBUTES*
指向 SECURITY_ATTRIBUTES 结构的指针，该结构确定是否可由子进程继承返回的句柄。 SECURITY_ATTRIBUTES 结构的 lpSecurityDescriptor 成员为新的文件映射对象指定安全描述符。
如果 lpAttributes 为 NULL，则无法继承句柄，并且文件映射对象将获取默认的安全描述符。 访问控制列出了来自创建者的主要令牌或模拟令牌的文件映射对象的默认安全描述符中 (ACL) 。 有关详细信息，请参阅 文件映射安全性和访问权限。
DesiredAccess
类型：_In_ ULONG
返回的文件映射句柄的所需访问掩码。 有关访问权限的列表，请参阅 文件映射安全性和访问权限。
PageProtection
类型：_In_ ULONG
指定文件映射对象的页保护。 对象的所有映射视图都必须与此保护兼容。
此参数的取值可为下列值之一：
AllocationAttributes
类型：_In_ ULONG
可以为文件映射对象指定以下一个或多个属性。 另请参阅 PageProtection 参数。
| 值 | 含义 |
|---|---|
|
如果文件映射对象由操作系统分页文件提供支持， (hfile 参数 INVALID_HANDLE_VALUE) ，则指定在将文件的视图映射到进程地址空间时，将提交而不是保留整个页面范围。 系统必须有足够的可提交页面来保存整个映射。 否则， CreateFileMapping 将失败。
对于由可执行图像文件或数据文件支持的文件映射对象， (hfile 参数是文件) 句柄，则此属性不起作用。 SEC_COMMIT 不能与 SEC_RESERVE结合使用。 如果未指定任何属性，则假定 SEC_COMMIT 。 |
|
指定 hFile 参数指定的文件是可执行映像文件。
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 2003 和 Windows XP： 在 Windows Server 2012 和 Windows 8 之前不支持此值。 |
|
使大型页面可用于操作系统分页文件支持的文件映射对象， (hfile 参数 INVALID_HANDLE_VALUE) 。 由可执行图像文件或数据文件支持的文件映射对象不支持此属性， (hFile 参数是可执行映像或数据文件的句柄) 。
文件映射对象的最大大小必须是 GetLargePageMinimum 函数返回的大页最小大小的倍数。 否则， CreateFileMapping 将失败。 映射使用 SEC_LARGE_PAGES 创建的文件映射对象的视图时，基址和视图大小也必须是最小大页面大小的倍数。 SEC_LARGE_PAGES 要求在调用方令牌中启用 SeLockMemoryPrivilege 特权。 如果指定 了SEC_LARGE_PAGES ，还必须指定 SEC_COMMIT 。 Windows Server 2003： 直到 Windows Server 2003 SP1 才支持此值。 Windowsxp： 不支持此值。 |
|
将所有页面设置为不可缓存。
应用程序不应使用此属性，除非设备显式需要。 将互锁 函数与SEC_NOCACHE 映射的内存配合使用可能会导致 EXCEPTION_ILLEGAL_INSTRUCTION 异常。 SEC_NOCACHE 需要设置 SEC_RESERVE 或 SEC_COMMIT 属性。 |
|
如果文件映射对象由操作系统分页文件支持， (hfile 参数 INVALID_HANDLE_VALUE) ，则指定当文件视图映射到进程地址空间时，将保留整个页面范围供进程以后使用，而不是提交。
可以在后续调用 VirtualAlloc 函数时提交保留页。 提交页面后，无法使用 VirtualFree 函数释放或取消提交页面。 对于由可执行图像文件或数据文件支持的文件映射对象， (hfile 参数是文件) 句柄，则此属性不起作用。 SEC_RESERVE 不能与 SEC_COMMIT 结合使用。 |
|
设置要写入组合的所有页面。
应用程序不应使用此属性，除非设备显式需要。 将互锁 函数与SEC_WRITECOMBINE 映射的内存结合使用可能会导致 EXCEPTION_ILLEGAL_INSTRUCTION 异常。 SEC_WRITECOMBINE 需要设置 SEC_RESERVE 或 SEC_COMMIT 属性。 Windows Server 2003 和 Windows XP： 此标志在 Windows Vista 之前不受支持。 |
MaximumSize
类型：_In_ ULONG64
文件映射对象的最大大小。
如果此参数为 0 (零) ，则文件映射对象的最大大小等于 hFile 标识的文件的当前大小。
尝试映射长度为 0 (零的文件) 失败，错误代码为 ERROR_FILE_INVALID。 应测试长度为 0 (零) 的文件，并拒绝这些文件。
Name
类型：_In_opt_ PCWSTR
文件映射对象的名称。
如果此参数与现有映射对象的名称匹配，则该函数将请求访问具有 flProtect 指定的保护的对象。
如果此参数为 NULL，则创建不带名称的文件映射对象。
如果 lpName 与现有事件、信号灯、互斥体、可等待计时器或作业对象的名称匹配，则函数将失败， GetLastError 函数将返回 ERROR_INVALID_HANDLE。 发生这种情况的原因是这些对象共享相同的命名空间。
名称可以具有“Global”或“Local”前缀，以在全局命名空间或会话命名空间中显式创建对象。 名称的其余部分可以包含除反斜杠字符 (\) 以外的任何字符。 从会话 0 以外的会话在全局命名空间中创建文件映射对象需要 SeCreateGlobalPrivilege 特权。 有关详细信息，请参阅 内核对象命名空间。
使用终端服务会话实现快速用户切换。 第一个登录用户使用会话 0 (零) ，下一个登录用户使用会话 1 (一个) ，依此依此。 内核对象名称必须遵循终端服务概述的准则，以便应用程序可以支持多个用户。
ExtendedParameters
类型：_Inout_updates_opt_ (ParameterCount) MEM_EXTENDED_PARAMETER*
指向 MEM_EXTENDED_PARAMETER类型的一个或多个扩展参数的可选指针。 每个扩展参数值本身都可以具有 MemExtendedParameterAddressRequirements 或 MemExtendedParameterNumaNode的 Type 字段。 如果未提供 MemExtendedParameterNumaNode 扩展参数，则行为与 VirtualAlloc/MapViewOfFile 函数 (相同，也就是说，物理页的首选 NUMA 节点是根据首先访问内存) 线程的理想处理器确定的。
ParameterCount
In ULONG 参数计数
ExtendedParameters 指向的扩展参数数。
返回值
如果函数成功，则返回值是新创建的文件映射对象的句柄。
如果对象在函数调用之前存在，则函数将 (当前大小（而不是指定大小) ）返回现有对象的句柄， GetLastError 返回 ERROR_ALREADY_EXISTS。
如果函数失败，则返回值为 NULL。 要获得更多的错误信息，请调用 GetLastError。
注解
请参阅 CreateFileMapping 的备注。
示例
有关示例，请参阅 创建命名共享内存或使用 大页创建文件映射。
要求
| 最低受支持的客户端 | Windows 10内部版本 20348 |
| 最低受支持的服务器 | Windows 10内部版本 20348 |
| 目标平台 | Windows |
| 标头 | memoryapi.h (包括 Windows.h、Memoryapi.h) |
| Library | onecore.lib |
| DLL | Kernel32.dll |