CreateFileMappingW 函式 （memoryapi.h）
建立或開啟指定檔案的具名或未命名檔案對應物件。
若要指定實體記憶體的 NUMA 節點，請參閱 CreateFileMappingNuma。
語法
HANDLE CreateFileMappingW(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCWSTR lpName
);
參數
[in] hFile
要從中建立檔案對應物件的檔案句柄。
檔案必須以與 flProtect 參數所指定之保護旗標相容的訪問許可權開啟。 這不是必要專案，但建議您針對獨佔存取開啟您要對應的檔案。 如需詳細資訊，請參閱 檔案安全性和存取權限。
如果 hFile 是 INVALID_HANDLE_VALUE，則呼叫進程也必須在 dwMaximumSizeHigh 中指定檔案對應物件的大小，dwMaximumSizeLow 參數。 在此案例中，CreateFileMapping 建立指定大小的檔案對應物件，該物件是由系統分頁檔案所支援，而不是由文件系統中的檔案所支援。
[in, optional] lpFileMappingAttributes
SECURITY_ATTRIBUTES 結構的指標，決定子進程是否可以繼承傳回的句柄。 lpSecurityDescriptorSECURITY_ATTRIBUTES 結構的成員會指定新檔案對應對象的安全性描述項。
如果 lpAttributesNULL，則無法繼承句柄，而且檔案對應物件會取得預設的安全性描述元。 檔案對應對象的預設安全性描述元中的訪問控制清單 （ACL）來自建立者的主要或模擬令牌。 如需詳細資訊，請參閱 檔案對應安全性和存取權限。
[in] flProtect
指定檔案對應對象的頁面保護。 物件的所有對應檢視都必須與這個保護相容。
此參數可以是下列其中一個值。
應用程式可以藉由結合檔案對應物件與前一個頁面保護值，為檔案對應物件指定下列一或多個屬性。
| 價值 | 意義 |
|---|---|
|
如果檔案對應物件是由操作系統分頁檔案所支援（hfile 參數是 INVALID_HANDLE_VALUE），則指定當檔案的檢視對應到進程地址空間時，會認可整個頁面範圍，而不是保留。 系統必須有足夠的可認可頁面來保存整個對應。 否則，CreateFileMapping 失敗。
此屬性對於可執行檔或數據檔所支援的檔案對應對象沒有作用（hfile 參數是檔案的句柄）。 SEC_COMMIT 無法與 SEC_RESERVE結合。 如果未指定任何屬性，則會假設 SEC_COMMIT。 不過，SEC_COMMIT 與需要它的另一個 SEC_ 屬性結合時，必須明確指定 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 之前不支援此值。 Windows XP：不支援此值。 |
|
將所有頁面設定為不可快取。
應用程式不應該使用此屬性，除非裝置明確需要時才使用此屬性。 使用與 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 之前不支援此旗標。 |
[in] dwMaximumSizeHigh
高階 DWORD 檔案對應物件的大小上限。
[in] dwMaximumSizeLow
低序 DWORD 檔案對應物件的大小上限。
如果此參數和 dwMaximumSizeHigh 為 0（零），則檔案對應物件的大小上限等於 hFile 識別的檔案目前大小。
嘗試對應長度為 0 的檔案失敗，錯誤碼為 ERROR_FILE_INVALID。 應用程式應該測試長度為 0 的檔案（零），並拒絕這些檔案。
[in, optional] lpName
檔案對應物件的名稱。
如果此參數符合現有對應物件的名稱，函式會要求存取具有 flProtect
如果此參數 NULL，則會建立沒有名稱的檔案對應物件。
如果 lpName 符合現有事件、旗號、mutex、可等候定時器或工作物件的名稱，則函式會失敗，GetLastError 函式會傳回 ERROR_INVALID_HANDLE。 這是因為這些對象共用相同的命名空間。
名稱可以有 「Global」 或 「Local」 前置詞，以明確在全域或會話命名空間中建立物件。 名稱的其餘部分可以包含反斜杠字元 （\） 以外的任何字元。 從會話零以外的會話建立全域命名空間中的檔案對應物件需要 SeCreateGlobalPrivilege 許可權。 如需詳細資訊，請參閱 Kernel Object Namespaces。
使用終端機服務會話實作快速使用者切換。 第一個登入的使用者會使用會話 0 （零），下一個登入的使用者會使用會話 1 （一），依此方式登入。 核心物件名稱必須遵循終端機服務概述的指導方針，讓應用程式可以支援多個使用者。
傳回值
如果函式成功，傳回值就是新建立檔案對應物件的句柄。
如果物件存在於函數呼叫之前，函式會傳回現有物件的句柄（其目前大小，而非指定的大小），GetLastError 會傳回 ERROR_ALREADY_EXISTS。
如果函式失敗，則傳回值 NULL。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
言論
建立檔案對應物件之後，檔案的大小不得超過檔案對應物件的大小;如果這樣做，則並非所有檔案內容都可供共用。
如果應用程式指定大於磁碟上實際具名檔案大小的檔案對應物件大小，而且如果頁面保護允許寫入存取權（也就是說，flProtect 參數指定 PAGE_READWRITE 或 PAGE_EXECUTE_READWRITE），則磁碟上的檔案會增加以符合檔案對應物件的指定大小。 如果擴充檔案，則檔案的舊端與檔案新端之間的檔案內容不保證為零：行為是由檔案系統所定義。 如果無法增加磁碟上的檔案，CreateFileMapping 會失敗，GetLastError 會傳回 ERROR_DISK_FULL。
操作系統分頁檔案所支援之檔案對應對象中頁面的初始內容為 0（零）。
CreateFileMapping 傳回的句柄具有新檔案對應物件的完整存取權，並可搭配任何需要檔案對應物件的句柄的函式使用。
多個進程可以使用單一共享檔案對應物件，或建立相同檔案支援的個別檔案對應物件，來共用相同檔案的檢視。 透過在進程建立時繼承句柄、複製句柄，或依名稱開啟檔案對應物件，可以由多個進程共用單一檔案對應物件。 如需詳細資訊，請參閱 CreateProcess、DuplicateHandle 和 OpenFileMapping 函式。
建立檔案對應對象實際上不會將檢視對應到進程位址空間。 MapViewOfFile 和 MapViewOfFileEx 函式會將檔案的檢視對應至進程地址空間。
有一個重要的例外狀況，衍生自相同檔案所支援之任何檔案對應對象的檔案檢視在特定時間是一致或完全相同的。 針對進程內的檢視，以及由不同進程對應的檢視，保證一致性。
例外狀況與遠端檔案相關。 雖然 CreateFileMapping 可搭配遠端檔案運作，但不會讓檔案保持一致。 例如，如果兩部計算機將檔案對應為可寫入，而且兩者都變更了相同的頁面，則每部計算機只會看到自己的寫入頁面。 當數據在磁碟上更新時，它不會合併。
使用輸入和輸出函式存取的對應檔案和檔案（ReadFile 和 WriteFile），不一定一致。
檔案對應對象的對應檢視會維護對象的內部參考，而且檔案對應對象在發行所有參考之前不會關閉。 因此，若要完全關閉檔案對應物件，應用程式必須藉由呼叫 UnmapViewOfFile
透過對應檢視修改檔案時，可能不會自動更新上次修改時間戳。 如有需要，呼叫端應該使用 SetFileTime 來設定時間戳。
從會話零以外的會話建立全域命名空間中的檔案對應物件需要 SeCreateGlobalPrivilege 許可權。 請注意，此許可權檢查僅限於建立檔案對應物件，不適用於開啟現有的物件。 例如，如果服務或系統在全域命名空間中建立檔案對應物件，則任何會話中執行的任何進程都可以存取該檔案對應物件，前提是呼叫端具有必要的訪問許可權。
Windows XP：上一段所述的需求是在 Windows Server 2003 和 Windows XP SP2 中引進的
使用結構化例外狀況處理來保護寫入或讀取檔案檢視的任何程序代碼。 如需詳細資訊，請參閱 從檔案檢視讀取和寫入。
若要具有可執行許可權的對應，應用程式必須使用
在 Windows Server 2012 中，下列技術支援此功能。
| 科技 | 支援 |
|---|---|
| 伺服器消息塊 （SMB） 3.0 通訊協定 | 是的 |
| SMB 3.0 透明故障轉移 （TFO） | 是的 |
| 具有向外延展檔案共用的SMB 3.0（SO） | 是的 |
| 叢集共用磁碟區檔案系統 （CsvFS） | 是的 |
| 復原檔案系統 （ReFS） | 是的 |
例子
如需範例，請參閱 建立具名共用記憶體 或 使用大型頁面建立檔案對應。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 支援的最低伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | memoryapi.h （包括 Windows.h、Memoryapi.h） |
| 連結庫 | onecore.lib |
| DLL | Kernel32.dll |
另請參閱
檔案對應函式