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 位元組數目。 此值必須是至少 sizeof(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 或系統不應對檔案執行任何循序的預先讀取作業。 |
|
無法在驅動程式的內部緩衝區中快取或緩衝處理檔案。 此旗標與 DesiredAccess |
|
檔案上的所有作業都會同步執行。 代表呼叫端的任何等候,都受限於警示的過早終止。 此旗標也會讓 I/O 系統維護檔案位置內容。 如果設定此旗標,也必須設定 DesiredAccessSYNCHRONIZE 旗標。 |
|
檔案上的所有作業都會同步執行。 系統等候同步處理 I/O 佇列和完成,不受警示限制。 此旗標也會讓 I/O 系統維護檔案位置內容。 如果設定此旗標,也必須設定 DesiredAccessSYNCHRONIZE 旗標。 |
|
建立此檔案的樹狀結構連線,以便透過網路開啟它。 裝置和中繼驅動程式不會使用此旗標。 |
|
如果開啟之現有檔案上的擴充屬性表示呼叫端必須瞭解 EA 才能正確解譯檔案,則失敗此要求,因為呼叫端無法瞭解如何處理 EA。 此旗標與裝置和中繼驅動程序無關。 |
|
使用重新分析點開啟檔案,並略過檔案的一般重新分析點處理。 如需詳細資訊,請參閱一節。 |
|
將最後一個句柄傳遞給 ntClose 時,請刪除檔案。 如果設定此旗標,必須在 desiredAccess 參數 |
|
ObjectAttributes 參數所指定的檔名包含檔案的 8 位元組檔案參考編號。 這個數位是由特定文件系統所指派,且專屬於特定文件系統。 如果檔案是重新分析點,檔名也會包含裝置的名稱。 請注意,FAT 檔系統不支援此旗標。 裝置和中繼驅動程式不會使用此旗標。 |
|
檔案正在開啟以供備份意圖使用。 因此,系統應該檢查特定訪問許可權,並在檢查 DesiredAccess 參數之前,先向呼叫者授與適當的檔案存取權,再檢查檔案的安全性描述元。 裝置和中繼驅動程式未使用這個旗標。 |
|
此旗標可讓應用程式要求篩選機會鎖定(oplock),以防止其他應用程式收到共用違規。 如果已經有開啟的句柄,建立要求將會失敗,並 STATUS_OPLOCK_NOT_GRANTED。 如需詳細資訊,請參閱一節。 |
|
檔案正在開啟,且檔案上的機會鎖定(oplock)會要求為單一不可部分完成的作業。 文件系統在執行建立作業之前會檢查 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 和 ShareAccess 規格相容,且先前尚未發行 NtClose。 也就是說,指定給指定檔案 NtCreateFile 指定的 DesiredAccess 參數不得與不允許其他檔案開啟者存取權衝突。
CreateDisposition 值 FILE_SUPERSEDE 要求呼叫端具有對現有檔案物件的存取權 DELETE。 若是如此,在現有檔案上成功呼叫 NtCreateFile,FILE_SUPERSEDE 會有效刪除該檔案,然後重新建立它。 這表示,如果檔案已由另一個線程開啟,則會指定已設定 FILE_SHARE_DELETE 旗標的 ShareAccess 參數,以開啟檔案。 請注意,這種類型的處置與覆寫檔案的POSIX樣式一致。 CreateDisposition 值 FILE_OVERWRITE_IF 和 FILE_SUPERSEDE 類似。 如果 ZwCreateFile 是以現有的檔案呼叫,且其中任一 CreateDisposition 值,則會取代檔案。
覆寫檔案在語意上相當於取代作業,但下列除外:
- 呼叫端必須具有檔案的寫入許可權,而不是刪除存取權。 這表示,如果檔案已由另一個線程開啟,則會開啟檔案,並在輸入 ShareAccess 參數中設定 FILE_SHARE_WRITE 旗標。
- 指定的檔案屬性在邏輯上是 ORed,且檔案上已有這些屬性。 這表示,如果檔案已由另一個線程開啟,則 NtCreateFile 的後續呼叫者 無法停用現有的 FileAttributes 旗標,但可以啟用相同檔案的其他旗標。 請注意,此覆寫檔案樣式與 MS-DOS、Windows 3.1 和 OS/2 操作系統一致。
CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING 旗標可防止文件系統代表呼叫端執行任何中繼緩衝。 指定此值會將呼叫端參數的某些限制放在其他 NtXXXFile 例程上,包括下列專案:
- 傳遞至 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 之間的時間,這可能會讓第三方開啟檔案,這會導致共享違規。 應用程式可以使用 FILE_OPEN_REQUIRING_OPLOCK 旗標搭配 NtCreateFile,然後要求任何 oplock。 這可確保 oplock 擁有者會收到導致共享違規的任何後續開啟要求通知。
在 Windows 7 中,如果應用程式使用此旗標時檔案上有其他句柄,則建立作業將會失敗,並 STATUS_OPLOCK_NOT_GRANTED。 從 Windows 8 開始,此限制已不存在。
如果此建立作業會中斷檔案上已經存在的 oplock,則設定 FILE_OPEN_REQUIRING_OPLOCK 旗標會導致建立作業失敗,並 STATUS_CANNOT_BREAK_OPLOCK。 此建立作業不會中斷現有的 oplock。
使用此旗標的應用程式必須在此呼叫成功之後要求 oplock,否則所有後續嘗試開啟檔案都會遭到封鎖,而不會因一般 oplock 處理而受益。 同樣地,如果此呼叫成功,但後續的 oplock 要求失敗,則使用此旗標的應用程式必須在偵測到 oplock 要求失敗之後關閉其句柄。
CreateOptions 參數的 FILE_RESERVE_OPFILTER 旗標可讓應用程式要求層級 1、Batch 或 Filter oplock,以防止其他應用程式收到共享違規。 不過,實際上,FILE_RESERVE_OPFILTER 僅適用於篩選作業鎖定。 若要使用它,您必須完成下列步驟:
- 發出建立要求,CreateOptionsFILE_RESERVE_OPFILTER、DesiredAccess 完全 FILE_READ_ATTRIBUTES,ShareAccess 完全
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)
。 可能的失敗如下:- 如果已經有開啟的句柄,則建立要求會失敗並 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,並使這些 oplock 類型的 FILE_RESERVE_OPFILTER 旗標無用。
NTFS 是唯一實作 FILE_RESERVE_OPFILTER的文件系統Microsoft。
如需 oplocks 的詳細資訊,請參閱 Oplock Semantics。
請注意,許多常數定義以及 InitializeObjectAttributes 宏都需要 WDK 頭檔 NtDef.h。 您也可以使用 LoadLibrary 和 GetProcAddress 函式動態連結至 NtDll.dll。
要求
要求 | 價值 |
---|---|
目標平臺 | 窗戶 |
標頭 | winternl.h |
連結庫 | ntdll.lib |
DLL | ntdll.dll |