CreateFileMappingNumaW 函式 (memoryapi.h)
為指定的檔案建立或開啟具名或未命名的檔案對應物件，並指定物理記憶體的 NUMA 節點。
語法
HANDLE CreateFileMappingNumaW(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCWSTR lpName,
[in] DWORD nndPreferred
);
參數
[in] hFile
要從中建立檔案對應物件的檔案句柄。
檔案必須以與 flProtect 參數所指定之保護旗標相容的訪問許可權開啟。 這並非必要專案，但建議您針對獨佔存取開啟您要對應的檔案。 如需詳細資訊，請參閱 檔案安全性和訪問許可權。
如果 hFileINVALID_HANDLE_VALUE，呼叫進程也必須在 dwMaximumSizeHigh 和 dwMaximumSizeLow 參數中指定檔案對應物件的大小。 在此案例中， CreateFileMappingNuma 會建立指定大小的檔案對應物件，該物件是由系統分頁檔案所支援，而不是由文件系統中的檔案所支援。
[in, optional] lpFileMappingAttributes
SECURITY_ATTRIBUTES 結構的指標，決定子進程是否可以繼承傳回的句柄。 的 lpSecurityDescriptor 成員
SECURITY_ATTRIBUTES 結構會指定新檔案對應物件的安全性描述項。
如果 lpFileMappingAttributes 為 NULL，則無法繼承句柄，而且檔案對應物件會取得預設的安全性描述元。 訪問控制清單 (ACL) 檔案對應對象的預設安全性描述項中，來自建立者的主要或模擬令牌。 如需詳細資訊，請參閱 檔案對應安全性和訪問許可權。
[in] flProtect
指定檔案對應對象的頁面保護。 物件的所有對應檢視都必須與此保護相容。
此參數可以是下列其中一個值。
應用程式可以藉由將它們與上述其中一個頁面保護值結合，為檔案對應物件指定下列一或多個屬性。
| 值 | 意義 |
|---|---|
|
在記憶體或分頁檔案中配置所有頁面的實體記憶體。
這是預設值。 |
|
將指定的檔案設定為可執行圖像檔案。
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 2012 和 Windows 8 之前，不支援此值。 |
|
啟用在對應影像或從頁面文件支援時使用大型頁面，但在對應一般檔案的數據時則不會使用。 請務必將檔案對應物件的大小上限指定為 GetLargePageMinimum 函式所報告大型頁面的大小下限，並啟用 SeLockMemoryPrivilege 許可權。 |
|
將所有頁面設定為不可快取。
應用程式不應該使用此旗標，除非明確要求裝置。 使用內嵌函式搭配與 SEC_NOCACHE 對應的記憶體，可能會導致 EXCEPTION_ILLEGAL_INSTRUCTION 例外狀況。 SEC_NOCACHE 需要 設定SEC_RESERVE 或 SEC_COMMIT 。 |
|
保留所有頁面，而不配置實體記憶體。
在釋放頁面範圍之前，任何其他配置作業都無法使用保留的頁面範圍。 在 後續呼叫 VirtualAllocExNuma 函 式時，可以識別保留的頁面。 只有當 hFile 參數 INVALID_HANDLE_VALUE (，也就是系統分頁檔案所支援的檔案對應物件) 時，此屬性才有效。 |
|
設定要合併的所有頁面。
應用程式不應該使用此屬性，除非裝置明確需要時。 使用與 SEC_WRITECOMBINE 對應記憶體的內嵌函式可能會導致 EXCEPTION_ILLEGAL_INSTRUCTION例外狀況 。 SEC_WRITECOMBINE 需要設定 SEC_RESERVE 或 SEC_COMMIT 屬性。 |
[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 許可權。 如需詳細資訊，請參閱 核心物件命名空間。
使用終端機服務會話實作快速使用者切換。 第一個登入的使用者會使用會話 0 (零) 、下一個登入的使用者會使用會話 1 (一個) 等等。 核心物件名稱必須遵循指導方針，讓應用程式可以支援多個使用者。
[in] nndPreferred
實體記憶體應該所在的 NUMA 節點。
| 值 | 意義 |
|---|---|
|
不偏好 NUMA 節點。 這與呼叫 CreateFileMapping 函式 相同。 |
傳回值
如果函式成功，則傳回值是檔案對應物件的句柄。
如果物件存在於函數調用之前，函式會傳回現有物件的句柄 (目前的大小，而不是指定的大小) ，而 GetLastError 函 式會 傳回ERROR_ALREADY_EXISTS。
如果函式失敗，傳回值為 NULL。 若要取得擴充的錯誤資訊，請呼叫 GetLastError 函 式。
備註
建立檔案對應物件之後，檔案的大小不得超過檔案對應物件的大小;如果是，則並非所有檔案內容都可供共用。
檔案對應物件可以透過重複、繼承或名稱來共用。 頁面對應對象中頁面的初始內容是由頁面檔案支援的 0 (零) 。
如果應用程式指定大於磁碟上實際具名檔案大小的檔案對應物件大小，而且如果頁面保護允許寫入存取 (，flProtect 參數會指定 PAGE_READWRITE 或 PAGE_EXECUTE_READWRITE) ，則磁碟上的檔案會增加以符合指定的檔案對應物件大小。 如果擴充檔案，檔案的舊端與檔案新端之間的檔案內容不保證為零;行為是由檔案系統所定義。
如果無法增加檔案，則結果是無法建立檔案對應物件，而 GetLastError 函 式會 傳回ERROR_DISK_FULL。
CreateFileMappingNuma 函式所傳回的句柄具有新檔案對應物件的完整存取權，並可搭配任何需要檔案對應物件的句柄使用的函式。 檔案對應物件可以透過程式建立、處理重複或依名稱共用。 如需詳細資訊，請參閱 DuplicateHandle 和 OpenFileMapping 函式 。
建立檔案對應物件會建立對應檔案檢視的可能性，但不會對應檢視。 MapViewOfFileExNuma 函式會將檔案的檢視對應至進程地址空間。
有一個重要的例外狀況，衍生自單一檔案對應對象的檔案檢視在特定時間是一致或相同的。 如果多個進程具有相同檔案對應物件的句柄，當處理檔案的檢視對應時，它們會看到數據的一致檢視。
例外狀況與遠端檔案有關。 雖然 CreateFileMappingNuma 函式適用於遠端檔案，但不會讓它們保持一致。 例如，如果兩部計算機將檔案對應為可寫入，且兩者都變更相同的頁面，則每部計算機只會看到自己的寫入頁面。 當數據在磁碟上更新時，不會合併頁面。
使用輸入和輸出存取的對應檔案和檔案， (I/O) 函式 (ReadFile 和 WriteFile) 不一定一致。
若要完全關閉檔案對應物件，應用程式必須呼叫 UnmapViewOfFile 函式來取消對應檔案對應物件的所有對應檢視，然後呼叫 CloseHandle 函式來關閉檔案對應物件句柄。
您可以依任何順序呼叫這些函式。 需要 UnmapViewOfFile 函式的呼叫，因為檔案對應對象的對應檢視會維護對對對象的內部開啟句柄，而且檔案對應物件在關閉所有開啟的句柄之前都不會關閉。
透過對應檢視修改檔案時，可能不會自動更新上次修改時間戳。 如有必要，呼叫端應該使用 SetFileTime 來設定時間戳。
從會話零以外的會話建立檔案對應物件需要 SeCreateGlobalPrivilege 許可權。 請注意，此許可權檢查僅限於建立檔案對應物件，不適用於開啟現有的物件。 例如，如果服務或系統建立檔案對應物件，則任何會話中執行的任何進程都可以存取該檔案對應物件，前提是呼叫端具有必要的訪問許可權。
使用結構化例外狀況處理來保護寫入記憶體對應檢視或讀取的任何程序代碼。 如需詳細資訊，請參閱 從檔案檢視讀取和寫入。
若要具有可執行許可權的對應，應用程式必須使用 PAGE_EXECUTE_READWRITE 或 PAGE_EXECUTE_READ 呼叫 CreateFileMappingNuma 函式，然後使用 或 FILE_MAP_EXECUTE | FILE_MAP_READ呼叫 MapViewOfFileExNuma 函式FILE_MAP_EXECUTE | FILE_MAP_WRITE。
在 Windows Server 2012 中，下列技術支援此函式。
| 技術 | 支援 |
|---|---|
| 伺服器消息塊 (SMB) 3.0 通訊協定 | Yes |
| SMB 3.0 透明故障轉移 (TFO) | Yes |
| 具有向外延展檔案共用的SMB 3.0 (SO) | Yes |
| 叢集共用磁碟區文件系統 (CsvFS) | Yes |
| 彈性檔案系統 (ReFS) | Yes |
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Vista [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | memoryapi.h (包括 Windows.h、Memoryapi.h) |
| 程式庫 | onecore.lib |
| DLL | Kernel32.dll |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應