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
);

参数

File

类型:_In_ HANDLE

要从中创建文件映射对象的文件的句柄。

必须使用与 flProtect 参数指定的保护标志兼容的访问权限打开该文件。 这不是必需的,但建议打开要映射的文件进行独占访问。 有关详细信息,请参阅 文件安全性和访问权限

如果 INVALID_HANDLE_VALUEhFile,调用过程还必须在 dwMaximumSizeHigh 中指定文件映射对象的大小,并 dwMaximumSizeLow 参数。 在此方案中,CreateFileMapping 创建由系统分页文件而不是文件系统中的文件提供支持的指定大小的文件映射对象。

SecurityAttributes

类型:_In_opt_ SECURITY_ATTRIBUTES*

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

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

DesiredAccess

类型:_In_ ULONG

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

PageProtection

类型:_In_ ULONG

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

此参数可以是下列值之一。

价值 意义
PAGE_EXECUTE_READ
0x20
允许为只读、写入时复制或执行访问权限映射视图。

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

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

PAGE_EXECUTE_READWRITE
0x40
允许为只读、写入复制、读/写或执行访问权限映射视图。

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

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

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

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

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

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

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

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

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

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

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

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

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 之前不支持此值。

Windows XP:不支持此值。

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。 之所以发生这种情况,是因为这些对象共享相同的命名空间。

该名称可以具有“全局”或“本地”前缀,以在全局或会话命名空间中显式创建对象。 名称的其余部分可以包含除反斜杠字符(\)以外的任何字符。 从会话零以外的会话创建全局命名空间中的文件映射对象需要 SeCreateGlobalPrivilege 特权。 有关详细信息,请参阅 内核对象命名空间

使用终端服务会话实现快速用户切换。 第一个登录的用户使用会话 0 (零),下一个登录的用户使用会话 1(一),依此等。 内核对象名称必须遵循终端服务概述的准则,以便应用程序能够支持多个用户。

ExtendedParameters

类型:_Inout_updates_opt_(ParameterCount) MEM_EXTENDED_PARAMETER*

指向 MEM_EXTENDED_PARAMETER类型的一个或多个扩展参数的可选指针。 每个扩展参数值本身都可以具有 Type 字段,MemExtendedParameterAddressRequirementsMemExtendedParameterNumaNode。 如果未提供 MemExtendedParameterNumaNode 扩展参数,则行为与 VirtualAlloc/MapViewOfFile 函数(即,物理页的首选 NUMA 节点)是根据首次访问内存的线程的理想处理器确定的。

ParameterCount

ULONG ParameterCount 中的

ExtendedParameters指向的扩展参数数。

返回值

如果函数成功,则返回值是新创建的文件映射对象的句柄。

如果在函数调用之前存在该对象,该函数将返回现有对象的句柄(其当前大小,而不是指定大小),GetLastError 返回 ERROR_ALREADY_EXISTS

如果函数失败,则返回值 NULL。 若要获取扩展的错误信息,请调用 GetLastError

言论

请参阅 CreateFileMapping备注

例子

有关示例,请参阅 创建命名的共享内存,或 使用大型页面创建文件映射。

要求

要求 价值
最低支持的客户端 Windows 10 内部版本 20348
支持的最低服务器 Windows 10 内部版本 20348
目标平台 窗户
标头 memoryapi.h (包括 Windows.h、Memoryapi.h)
onecore.lib
DLL Kernel32.dll

另请参阅

CloseHandle

CreateFileMappingNuma

创建文件映射对象

DuplicateHandle

MapViewOfFile

MapViewOfFileEx

内存管理功能

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile