共用方式為


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 參數所指定之保護旗標相容的存取權限開啟。 這並非必要專案,但建議您針對獨佔存取開啟您要對應的檔案。 如需詳細資訊,請參閱 檔案安全性和存取權限

如果 hFileINVALID_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
允許對檢視進行唯讀、寫入複製或執行存取。

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

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 符合現有事件、旗號、mutex、可等候的計時器或工作物件的名稱,則函式會失敗, 而且 GetLastError 函式會傳回 ERROR_INVALID_HANDLE。 這是因為這些物件共用相同的命名空間。

名稱可以有 「Global」 或 「Local」 前置詞,以在全域或會話命名空間中明確建立物件。 名稱的其餘部分可以包含任何字元,但反斜線字元 (\) 除外。 從會話零以外的會話建立全域命名空間中的檔案對應物件需要 SeCreateGlobalPrivilege 許可權。 如需詳細資訊,請參閱 核心物件命名空間

使用終端機服務會話實作快速使用者切換。 第一個登入的使用者會使用會話 0 (零) ,下一個使用者登入會使用會話 1 (一個) 等等。 核心物件名稱必須遵循終端機服務概述的指導方針,讓應用程式可以支援多個使用者。

ExtendedParameters

類型:_Inout_updates_opt_ (ParameterCount) MEM_EXTENDED_PARAMETER*

MEM_EXTENDED_PARAMETER 類型的一或多個擴充參數的選擇性指標。 這些擴充參數值本身可以有MemExtendedParameterAddressRequirementsMemExtendedParameterNumaNodeType欄位。 如果未提供MemExtendedParameterNumaNode擴充參數,則行為與VirtualAlloc/MapViewOfFile函式 (相同,實體頁面的慣用 NUMA 節點會根據第一次存取記憶體) 執行緒的理想處理器來決定。

ParameterCount

In ULONG ParameterCount

ExtendedParameters所指向的擴充參數數目。

傳回值

如果函式成功,則傳回值是新建立之檔案對應物件的控制碼。

如果物件存在於函式呼叫之前,函式會傳回現有物件的控制碼 (其目前大小,而不是指定的大小) , 而 GetLastError 會傳回 ERROR_ALREADY_EXISTS

如果函式失敗,則傳回值為 Null。 若要取得擴充的錯誤資訊,請呼叫 GetLastError

備註

請參閱CreateFileMapping

範例

如需範例,請參閱 建立具名的共用記憶體,或使用 大型頁面建立檔案對應

需求

   
最低支援的用戶端 Windows 10組建 20348
最低支援的伺服器 Windows 10組建 20348
目標平台 Windows
標頭 memoryapi.h (包括 Windows.h、Memoryapi.h)
程式庫 onecore.lib
DLL Kernel32.dll

另請參閱

CloseHandle

CreateFileMappingNuma

建立檔案對應物件

DuplicateHandle

MapViewOfFile

MapViewOfFileEx

記憶體管理函式

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile