NtCreateFile 函式 (winternl.h)
建立新的檔案或目錄,或開啟現有的檔案、裝置、目錄或磁碟區。
此函式是使用者模式,相當於 Windows 驅動程式套件 (WDK) 中所述的 ZwCreateFile 函式。
語法
__kernel_entry NTSTATUS NtCreateFile(
[out] PHANDLE FileHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in, optional] PLARGE_INTEGER AllocationSize,
[in] ULONG FileAttributes,
[in] ULONG ShareAccess,
[in] ULONG CreateDisposition,
[in] ULONG CreateOptions,
[in] PVOID EaBuffer,
[in] ULONG EaLength
);
參數
[out] FileHandle
如果呼叫成功,則為接收檔案句柄之變數的指標。
[in] DesiredAccess
ACCESS_MASK值,表示呼叫端對檔案或目錄所需的存取類型。 系統定義的 DesiredAccess 旗標集合會決定下列檔案物件的特定訪問許可權。
當您建立或開啟目錄時,請勿指定 FILE_READ_DATA、 FILE_WRITE_DATA、 FILE_APPEND_DATA或 FILE_EXECUTE 。
NtCreateFile 的呼叫端可以針對任何不代表目錄檔案的檔案物件,使用位 OR 搭配上述 DesiredAccess 旗標清單中的其他相容旗標,來指定下列其中一個或組合。
FILE_GENERIC_EXECUTE值與裝置和中繼驅動程序無關。
STANDARD_RIGHTS_XXX 是預先定義的系統值,用來在系統對象上強制執行安全性。
若要開啟或建立目錄檔案,如 CreateOptions 參數所指出, NtCreateFile 的呼叫端可以指定下列其中一個或多個組合,可能使用位 OR 搭配上述 DesiredAccess 旗標列表中的一或多個相容旗標。
值 | 意義 |
---|---|
|
目錄中的檔案可以列出。 |
|
目錄可以周遊:也就是說,它可以是檔案路徑名稱的一部分。 |
[in] ObjectAttributes
已使用 InitializeObjectAttributes 初始化之結構的指標。 檔案對象的這個結構成員包括下列專案。
值 | 意義 |
---|---|
|
指定提供的 ObjectAttributes 數據位元組數目。 此值必須至少為大小 (OBJECT_ATTRIBUTES) 。 |
|
選擇性地指定先前呼叫 NtCreateFile 所取得之目錄的句柄。 如果此值為 NULL,ObjectName 成員必須是包含目標檔案完整路徑的完整檔案規格。 如果此值不是 NULL,ObjectName 成員會指定相對於這個目錄的檔名。 |
|
指向緩衝的 Unicode 字串,以命名要建立或開啟的檔案。 此值必須是完整檔案規格或裝置對象的名稱,除非它是 與 RootDirectory 所指定目錄相對的檔名。 例如,\Device\Floppy1\myfile.dat 或 \??\B:\myfile.dat可能是完整的檔案規格,前提是磁碟驅動器和過度載入文件系統。 如需詳細資訊,請參閱 檔名、路徑和命名空間。 |
|
這是一組旗標,可控制檔案物件屬性。 這個值可以是零或 OBJ_CASE_INSENSITIVE,這表示名稱查閱程式代碼應該忽略 ObjectName 成員的大小寫,而不是執行完全相符的搜尋。 OBJ_INHERIT值與裝置和中繼驅動程序無關。 |
|
選擇性地指定要套用至檔案的安全性描述元。 這類安全性描述元指定的 ACL 只會在建立檔案時套用至檔案。 如果建立檔案時值為 NULL ,則放置於檔案上的 ACL 會相依於文件系統;大部分文件系統都會從與呼叫端的預設 ACL 結合的父目錄檔案傳播這類 ACL 的一部分。 裝置和中繼驅動程式可以將此成員設定為 NULL。 |
|
指定伺服器應提供給用戶端安全性內容的訪問許可權。 只有在建立受保護伺服器的連線時,這個值是非 NULL 的,允許呼叫端控制呼叫端的安全性內容哪些部分可供伺服器使用,以及伺服器是否允許模擬呼叫端。 |
[out] IoStatusBlock
接收最終完成狀態的變數指標,以及所要求作業的相關信息。 從 NtCreateFile 傳回時, Information 成員包含下列其中一個值:
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
[in, optional] AllocationSize
檔案的初始配置大小以位元組為單位。 除非檔案正在建立、覆寫或取代,否則非零值沒有任何作用。
[in] FileAttributes
檔案屬性。 只有在檔案建立、取代或在某些情況下覆寫時,才會套用明確指定的屬性。 根據預設,這個值是 FILE_ATTRIBUTE_NORMAL,可由一或多個 FILE_ATTRIBUTE_xxxx 旗標的 ORed 組合覆寫,這些旗標定義於 Wdm.h 和 NtDdk.h 中。 如需可與 NtCreateFile 搭配使用的旗標清單,請參閱 CreateFile。
[in] ShareAccess
呼叫端想要在檔案中使用的共用存取類型,做為零,或是下列值的一或組合。
值 | 意義 |
---|---|
|
其他線程對 NtCreateFile 的呼叫可以開啟檔案以供讀取存取。 |
|
檔案可由其他線程對 NtCreateFile 的呼叫開啟以供寫入存取。 |
|
其他線程對 NtCreateFile 的呼叫可以開啟檔案以刪除存取權。 |
如需詳細資訊,請參閱 Windows SDK。
[in] CreateDisposition
根據檔案是否已存在,指定要執行的動作,做為下列其中一個值。
[in] CreateOptions
建立或開啟檔案時要套用的選項,做為下列旗標的相容組合。
值 | 意義 |
---|---|
|
正在建立或開啟的檔案是目錄檔案。 使用此旗標時, CreateDisposition 參數必須設定為 FILE_CREATE、 FILE_OPEN或 FILE_OPEN_IF。 使用此旗標時,其他相容的 CreateOptions 旗標只包含下列專案: FILE_SYNCHRONOUS_IO_ALERT、 FILE_SYNCHRONOUS_IO _NONALERT、 FILE_WRITE_THROUGH、 FILE_OPEN_FOR_BACKUP_INTENT和 FILE_OPEN_BY_FILE_ID。 |
|
正在開啟的檔案不得為目錄檔案,否則此呼叫會失敗。 正在開啟的檔案物件可以代表數據檔、邏輯、虛擬或實體裝置或磁碟區。 |
|
將數據寫入檔案的應用程式必須實際將數據傳輸到檔案,才能將任何要求的寫入作業視為完成。 如果已設定 CreateOptions 旗標 FILE_NO_INTERMEDIATE _BUFFERING ,就會自動設定此旗標。 |
|
對檔案的所有存取都是循序的。 |
|
檔案的存取權可以是隨機的,因此 FSD 或系統不應該對檔案執行任何循序的預先讀取作業。 |
|
檔案無法在驅動程式的內部緩衝區中快取或緩衝處理。 此旗標與 DesiredAccessFILE_APPEND_DATA 旗標不相容。 |
|
檔案上的所有作業都會同步執行。 任何代表呼叫端的等候,都受限於警示的提前終止。 此旗標也會讓 I/O 系統維護檔案位置內容。 如果已設定此旗標,則也必須設定 DesiredAccessSYNCHRONIZE 旗標。 |
|
檔案上的所有作業都會同步執行。 在系統中等候同步處理 I/O 佇列和完成,不受警示限制。 此旗標也會讓 I/O 系統維護檔案位置內容。 如果已設定此旗標,則也必須設定 DesiredAccessSYNCHRONIZE 旗標。 |
|
建立此檔案的樹狀結構連線,以透過網路開啟它。 裝置和中繼驅動程式不會使用此旗標。 |
|
如果開啟現有檔案上的擴充屬性表示呼叫端必須瞭解 EA 才能正確解譯檔案,請失敗此要求,因為呼叫端無法瞭解如何處理 EA。 此旗標與裝置和中繼驅動程序無關。 |
|
使用重新分析點開啟檔案,並略過檔案的一般重新分析點處理。 如需詳細資訊,請參閱<備註>一節。 |
|
將最後一個句柄傳遞給 NtClose 時,請刪除檔案。 如果設定此旗標,DELETE 旗標必須在 DesiredAccess 參數中設定。 |
|
ObjectAttributes 參數指定的檔名包含檔案的 8 位元組檔案參考編號。 這個數位是由 特定文件系統所指派,而且是特定的。 如果檔案是重新分析點,檔名也會包含裝置的名稱。 請注意,FAT 檔系統不支援此旗標。 裝置和中繼驅動程式不會使用此旗標。 |
|
正在開啟檔案以供備份意圖使用。 因此,系統應該先檢查特定訪問許可權,並授與呼叫端對檔案的適當存取權,再根據檔案的安全性描述元檢查 DesiredAccess 參數。 裝置和中繼驅動程式不會使用此旗標。 |
|
此旗標可讓應用程式要求篩選機率鎖定 (oplock) ,以防止其他應用程式收到共用違規。 如果已經有開啟的句柄,則建立要求將會失敗,且 STATUS_OPLOCK_NOT_GRANTED。 如需詳細資訊,請參閱<備註>一節。 |
|
檔案正在開啟,而檔案上的作業鎖定 (作業) 要求為單一不可部分完成的作業。 文件系統會在執行建立作業之前檢查 oplock,如果結果會中斷現有的 oplock,則會失敗並傳回 STATUS_CANNOT_BREAK_OPLOCK 傳回碼的建立。 如需詳細資訊,請參閱一節。Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP: 不支援此旗標。
下列檔案系統支援此旗標:NTFS、FAT 和exFAT。 |
|
如果目標檔案為 oplock,而不是封鎖呼叫端的線程,請立即完成此作業, 並 STATUS_OPLOCK_BREAK_IN_PROGRESS替代成功代碼。 如果檔案是 oplocked,另一個呼叫端已經可以存取該檔案。 裝置和中繼驅動程式不會使用此旗標。 |
[in] EaBuffer
用來傳遞擴充屬性的EA緩衝區指標。
[in] EaLength
EA 緩衝區的長度。
傳回值
NtCreateFile 會傳回 STATUS_SUCCESS 或適當的錯誤狀態。 如果傳回錯誤狀態,呼叫端可以藉由檢查 IoStatusBlock 來尋找失敗原因的詳細資訊。 為了簡化此檢查,應用程式可以使用 NT_SUCCESS、 NT_ERROR和 NT_WARNING 宏。
備註
NtCreateFile 所提供的句柄可供後續呼叫使用,以操作檔案內的數據或檔案物件的狀態或屬性。
有兩種替代方式可指定要使用 NtCreateFile 建立或開啟的檔名:
- 作為完整路徑名稱,在輸入 ObjectAttributes 的 ObjectName 成員中提供
- 作為路徑名稱,相對於輸入 ObjectAttributes 之 RootDirectory 成員中句柄所代表的目錄檔案
- 若要讓呼叫端等候傳回的 FileHandle 同步處理 I/O 完成,必須設定 SYNCHRONIZE 旗標。
- 將零傳遞至 DesiredFlags 無效。
- 如果只設定 FILE_APPEND_DATA 和 SYNCHRONIZE 旗標,則呼叫端只能寫入檔案結尾,並忽略寫入檔案的任何位移資訊。 不過,這類寫入作業會視需要自動擴充檔案。
- 設定檔案 的FILE_WRITE_DATA 旗標,也允許寫入檔案結尾以外的寫入。 此檔案也會針對這種類型的寫入自動擴充。
- 如果只設定 FILE_EXECUTE 和 SYNCHRONIZE 旗標,呼叫端就無法使用傳回的 FileHandle 直接讀取或寫入檔案中的任何數據,也就是說,檔案上的所有作業都會透過系統呼叫器進行,以回應指令和數據存取。
若要成功開啟共用檔案,要求之 DesiredAccess 參數與檔案的 DesiredAccess 參數必須相容於先前所有尚未使用 NtClose 發行的 DesiredAccess 和 ShareAccess 規格。 也就是說,指定給指定檔案之 NtCreateFile 的 DesiredAccess 參數不得與其他檔案開啟者不允許的存取發生衝突。
CreateDisposition 值FILE_SUPERSEDE要求呼叫端具有現有檔案物件的 DELETE 存取權。 如果是,在現有檔案上成功呼叫具有FILE_SUPERSEDE的 NtCreateFile 會有效地刪除該檔案,然後重新建立它。 這表示,如果檔案已經由另一個線程開啟,它會使用設定FILE_SHARE_DELETE旗標來指定 ShareAccess 參數來開啟檔案。 請注意,這種類型的處置與覆寫檔案的POSIX樣式一致。 CreateDisposition 值FILE_OVERWRITE_IF和FILE_SUPERSEDE類似。 如果使用現有的檔案和其中一個 CreateDisposition 值呼叫 ZwCreateFile,則會取代檔案。
覆寫檔案的語意相當於取代作業,但下列專案除外:
- 呼叫端必須具有檔案的寫入許可權,而不是刪除存取權。 這表示,如果檔案已由另一個線程開啟,則會開啟檔案,並在輸入ShareAccess參數中設定FILE_SHARE_WRITE旗標。
- 指定的檔案屬性在邏輯上為 ORed,且檔案上已有這些屬性。 這表示,如果檔案已由另一個線程開啟, 則 NtCreateFile 的後續呼叫端無法停用現有的 FileAttributes 旗標,但可以啟用相同檔案的其他旗標。 請注意,此覆寫檔案的樣式與 MS-DOS、Windows 3.1 和 OS/2 操作系統一致。
CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING 旗標可防止文件系統代表呼叫端執行任何中繼緩衝。 指定此值會將呼叫端參數的特定限制放在其他 NtXXX 檔案 例程上,包括下列專案:
- 任何傳遞至 NtReadFile 或 NtWriteFile 函式的選擇性 ByteOffset 都必須是扇區大小的整數。
- 傳遞至 NtReadFile 或 NtWriteFile 的 Length 必須是扇區大小的整數。 請注意,指定讀取作業給長度完全是扇區大小的緩衝區,可能會導致在傳輸期間到達檔案結尾時,傳送到該緩衝區的顯著位元組數目較少。
- 緩衝區必須根據基礎裝置的對齊需求進行調整。 您可以呼叫 NtCreateFile 來取得此資訊,以取得代表實體裝置的檔案物件句柄,然後使用該句柄呼叫 NtQueryInformationFile 。 如需系統FILE_XXX_ALIGNMENT值的清單,請參閱 Windows SDK 檔。
- 呼叫 NtSetInformationFile 並將 FileInformationClass 參數設定為 FilePositionInformation 必須指定位移,這是扇區大小的整數。
如果 CreateOptions 參數指定 FILE_OPEN_REPARSE_POINT 旗標, 而 NtCreateFile 會開啟具有重新分析點的檔案,則不會進行一般重新分析處理, 而且 NtCreateFile 會嘗試直接開啟重新分析點檔案。 如果未指定 FILE_OPEN_REPARSE_POINT 旗標,則檔案會發生一般重新分析點處理。 在任一情況下,如果開啟作業成功, NtCreateFile 會傳回 STATUS_SUCCESS;否則為錯誤碼。 NtCreateFile 函式永遠不會傳回STATUS_REPARSE。
CreateOptions 參數的FILE_OPEN_REQUIRING_OPLOCK旗標會消除開啟檔案並要求可能允許第三方開啟檔案的 oplock 之間的時間,這會導致共享違規。 應用程式可以搭配 NtCreateFile 使用FILE_OPEN_REQUIRING_OPLOCK旗標,然後要求任何 oplock。 這可確保 oplock 擁有者會收到任何後續開啟要求而導致共用違規的通知。
在 Windows 7 中,如果應用程式使用此旗標時檔案上有其他句柄,則建立作業將會失敗,並 STATUS_OPLOCK_NOT_GRANTED。 從 Windows 8 開始,此限制已不存在。
如果此建立作業會中斷檔案上已經存在的 oplock,則設定 FILE_OPEN_REQUIRING_OPLOCK 旗標會導致建立作業失敗,並 STATUS_CANNOT_BREAK_OPLOCK。 此建立作業不會中斷現有的 oplock。
使用此旗標的應用程式必須在呼叫成功之後要求 oplock,或者所有後續嘗試開啟檔案都會遭到封鎖,而不需要正常作業處理的優點。 同樣地,如果此呼叫成功,但後續的 oplock 要求失敗,則使用此旗標的應用程式必須在偵測到 oplock 要求失敗之後關閉其句柄。
CreateOptions 參數的FILE_RESERVE_OPFILTER旗標可讓應用程式要求層級 1、Batch 或 Filter oplock,以防止其他應用程式收到共享違規。 不過,實際上, FILE_RESERVE_OPFILTER 僅適用於篩選作業鎖定。 若要使用它,您必須完成下列步驟:
- 使用 FILE_RESERVE_OPFILTER 的CreateOptions、完全FILE_READ_ATTRIBUTES的 DesiredAccess 和完全
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)
的 ShareAccess 發出建立要求。 可能的失敗如下所示:- 如果已經有開啟的句柄,則建立要求會失敗 並STATUS_OPLOCK_NOT_GRANTED,而下一個要求的 oplock 也會失敗。
- 如果您開啟的存取權超過 FILE_READ_ATTRIBUTES 或小於 共用
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)
,則要求會失敗 並STATUS_OPLOCK_NOT_GRANTED。
- 如果建立要求成功,請要求 oplock。
- 開啟檔案的另一個句柄以執行 I/O。
(FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL)
,但仍不會中斷篩選作業。 不過,大於(FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE)
的任何 DesiredAccess 都會中斷層級 1 或 Batch oplock,並讓FILE_RESERVE_OPFILTER旗標不適用於這些 oplock 類型。
NTFS 是唯一實作 FILE_RESERVE_OPFILTER的 Microsoft 文件系統。
如需 oplock 的詳細資訊,請參閱 Oplock 語意。
請注意,許多常數定義以及 InitializeObjectAttributes 宏都需要 WDK 頭檔 NtDef.h。 您也可以使用 LoadLibrary 和 GetProcAddress 函式,動態連結至 NtDll.dll。
規格需求
需求 | 值 |
---|---|
目標平台 | Windows |
標頭 | winternl.h |
程式庫 | ntdll.lib |
Dll | ntdll.dll |
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應