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,则调用进程还必须在 dwMaximumSizeHighdwMaximumSizeLow 参数中指定文件映射对象的大小。 在此方案中, CreateFileMapping 会创建一个指定大小的文件映射对象,该对象由系统分页文件而不是文件系统中的文件提供支持。

SecurityAttributes

类型:_In_opt_ SECURITY_ATTRIBUTES*

指向 SECURITY_ATTRIBUTES 结构的指针,该结构确定是否可由子进程继承返回的句柄。 SECURITY_ATTRIBUTES 结构的 lpSecurityDescriptor 成员为新的文件映射对象指定安全描述符。

如果 lpAttributesNULL,则无法继承句柄,并且文件映射对象将获取默认的安全描述符。 访问控制列出了来自创建者的主要令牌或模拟令牌的文件映射对象的默认安全描述符中 (ACL) 。 有关详细信息,请参阅 文件映射安全性和访问权限

DesiredAccess

类型:_In_ ULONG

返回的文件映射句柄的所需访问掩码。 有关访问权限的列表,请参阅 文件映射安全性和访问权限

PageProtection

类型:_In_ ULONG

指定文件映射对象的页保护。 对象的所有映射视图都必须与此保护兼容。

此参数的取值可为下列值之一:

含义
PAGE_EXECUTE_READ
0x20
允许映射视图,以便进行只读、写入时复制或执行访问。

必须使用GENERIC_READ创建 hFile 参数指定的文件句柄,并GENERIC_EXECUTE访问权限。

Windows Server 2003 和 Windows XP: 此值在 Windows XP SP2 和 Windows Server 2003 SP1 之前不可用。

PAGE_EXECUTE_READWRITE
0x40
允许映射视图,以便进行只读、写入时复制、读/写或执行访问。

必须使用GENERIC_READGENERIC_WRITEGENERIC_EXECUTE访问权限创建 hFile 参数指定的文件句柄。

Windows Server 2003 和 Windows XP: 此值在 Windows XP SP2 和 Windows Server 2003 SP1 之前不可用。

PAGE_EXECUTE_WRITECOPY
0x80
允许映射视图,以便进行只读、写入时复制或执行访问。 此值等效于 PAGE_EXECUTE_READ

必须使用 GENERIC_READ 创建 hFile 参数指定的文件句柄,并GENERIC_EXECUTE访问权限。

Windows Vista: 此值在 Windows Vista SP1 中之前不可用。

Windows Server 2003 和 Windows XP: 不支持此值。

PAGE_READONLY
0x02
允许映射视图,以便进行只读或写入时复制访问。 尝试写入特定区域会导致访问冲突。

必须使用GENERIC_READ访问权限创建 hFile 参数指定的文件句柄。

PAGE_READWRITE
0x04
允许映射视图,以便进行只读、写入时复制或读/写访问。

必须使用 GENERIC_READ 创建 hFile 参数指定的文件句柄,GENERIC_WRITE访问权限。

PAGE_WRITECOPY
0x08
允许映射视图,以便进行只读或写入时复制访问。 此值等效于 PAGE_READONLY

必须使用GENERIC_READ访问权限创建 hFile 参数指定的文件句柄。

AllocationAttributes

类型:_In_ ULONG

可以为文件映射对象指定以下一个或多个属性。 另请参阅 PageProtection 参数。

含义
SEC_COMMIT
0x8000000
如果文件映射对象由操作系统分页文件提供支持, (hfile 参数 INVALID_HANDLE_VALUE) ,则指定在将文件的视图映射到进程地址空间时,将提交而不是保留整个页面范围。 系统必须有足够的可提交页面来保存整个映射。 否则, CreateFileMapping 将失败。

对于由可执行图像文件或数据文件支持的文件映射对象, (hfile 参数是文件) 句柄,则此属性不起作用。

SEC_COMMIT 不能与 SEC_RESERVE结合使用。

如果未指定任何属性,则假定 SEC_COMMIT

SEC_IMAGE
0x1000000
指定 hFile 参数指定的文件是可执行映像文件。

SEC_IMAGE 属性必须与页面保护值(如PAGE_READONLY)结合使用。 但是,此页面保护值对可执行映像文件的视图没有影响。 对可执行映像文件视图的页面保护由可执行文件本身确定。

没有其他属性对 SEC_IMAGE有效。

SEC_IMAGE_NO_EXECUTE
0x11000000
指定 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 之前不支持此值。

SEC_LARGE_PAGES
0x80000000
使大型页面可用于操作系统分页文件支持的文件映射对象, (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
0x10000000
将所有页面设置为不可缓存。

应用程序不应使用此属性,除非设备显式需要。 将互锁 函数与SEC_NOCACHE 映射的内存配合使用可能会导致 EXCEPTION_ILLEGAL_INSTRUCTION 异常。

SEC_NOCACHE 需要设置 SEC_RESERVESEC_COMMIT 属性。

SEC_RESERVE
0x4000000
如果文件映射对象由操作系统分页文件支持, (hfile 参数 INVALID_HANDLE_VALUE) ,则指定当文件视图映射到进程地址空间时,将保留整个页面范围供进程以后使用,而不是提交。

可以在后续调用 VirtualAlloc 函数时提交保留页。 提交页面后,无法使用 VirtualFree 函数释放或取消提交页面。

对于由可执行图像文件或数据文件支持的文件映射对象, (hfile 参数是文件) 句柄,则此属性不起作用。

SEC_RESERVE 不能与 SEC_COMMIT 结合使用。

SEC_WRITECOMBINE
0x40000000
设置要写入组合的所有页面。

应用程序不应使用此属性,除非设备显式需要。 将互锁 函数与SEC_WRITECOMBINE 映射的内存结合使用可能会导致 EXCEPTION_ILLEGAL_INSTRUCTION 异常。

SEC_WRITECOMBINE 需要设置 SEC_RESERVESEC_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类型的一个或多个扩展参数的可选指针。 每个扩展参数值本身都可以具有 MemExtendedParameterAddressRequirementsMemExtendedParameterNumaNode的 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

另请参阅

CloseHandle

CreateFileMappingNuma

创建文件映射对象

DuplicateHandle

MapViewOfFile

MapViewOfFileEx

内存管理功能

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile