共用方式為


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 旗標會決定下列檔案物件的特定訪問許可權。

價值 意義
DELETE
檔案可以刪除。
FILE_READ_DATA
您可以從檔案讀取數據。
FILE_READ_ATTRIBUTES
FileAttributes 旗標,稍後可讀取。
FILE_READ_EA
可以讀取與檔案相關聯的擴充屬性。 此旗標與裝置和中繼驅動程序無關。
READ_CONTROL
可以讀取與檔案相關聯的訪問控制清單 (ACL) 和擁有權資訊。
FILE_WRITE_DATA
數據可以寫入檔案。
FILE_WRITE_ATTRIBUTES
FileAttributes 旗標可以寫入。
FILE_WRITE_EA
可以寫入與檔案相關聯的擴充屬性 (EAS)。 此旗標與裝置和中繼驅動程序無關。
FILE_APPEND_DATA
數據可以附加至檔案。
WRITE_DAC
可以寫入與檔案相關聯的任意訪問控制清單 (DACL)。
WRITE_OWNER
您可以撰寫與檔案相關聯的擁有權資訊。
SYNCHRONIZE
傳回 FileHandle 可以等候同步處理 I/O 作業完成。 如果 FileHandle 未針對同步 I/O 開啟,則會忽略此值。
FILE_EXECUTE
數據可以使用系統分頁 I/O 從檔案讀取到記憶體。 此旗標與裝置和中繼驅動程序無關。
 

當您建立或開啟目錄時,請勿指定 FILE_READ_DATAFILE_WRITE_DATAFILE_APPEND_DATAFILE_EXECUTE

NtCreateFile 的呼叫者可以針對任何不代表目錄檔案的檔案物件,使用位 OR 搭配上述 DesiredAccess 旗標清單的其他相容旗標,來指定下列其中一個或組合。

價值 意義
FILE_GENERIC_READ
STANDARD_RIGHTS_READ | FILE_READ_DATA | FILE_READ_ATTRIBUTES | FILE_READ_EA | SYNCHRONIZE
FILE_GENERIC_WRITE
STANDARD_RIGHTS_WRITE | FILE_WRITE_DATA | FILE_WRITE_ATTRIBUTES | FILE_WRITE_EA | FILE_APPEND_DATA | SYNCHRONIZE
FILE_GENERIC_EXECUTE
STANDARD_RIGHTS_EXECUTE | FILE_READ_ATTRIBUTES | FILE_EXECUTE | SYNCHRONIZE
 

FILE_GENERIC_EXECUTE 值與裝置和中繼驅動程序無關。

STANDARD_RIGHTS_XXX 是預先定義的系統值,用來強制執行系統對象的安全性。

若要開啟或建立目錄檔案,如 CreateOptions 參數所指示,NtCreateFile 的呼叫者可以指定下列其中一或多個組合,可能使用位 OR 搭配上述 DesiredAccess 旗標清單的一或多個相容旗標。

價值 意義
FILE_LIST_DIRECTORY
目錄中的檔案可以列出。
FILE_TRAVERSE
目錄可以周遊:也就是說,它可以是檔案路徑名稱的一部分。

[in] ObjectAttributes

InitializeObjectAttributes初始化之結構的指標。 檔案對象的這個結構成員包括下列專案。

價值 意義
ULONG 長度
指定提供的 ObjectAttributes 位元組數目。 此值必須是至少 sizeof(OBJECT_ATTRIBUTES)。
HANDLE RootDirectory
選擇性地指定先前呼叫 ntCreateFile 取得之目錄的句柄。 如果此值 NULL,則 ObjectName 成員必須是包含目標檔案完整路徑的完整檔案規格。 如果這個值不是非NULL,則 ObjectName 成員會指定相對於這個目錄的檔名。
PUNICODE_STRING ObjectName
指向將檔案命名為要建立或開啟的緩衝 Unicode 字串。 這個值必須是完整檔案規格或裝置對象的名稱,除非它是與 RootDirectory所指定的目錄相對的檔名。 例如,\Device\Floppy1\myfile.dat 或 \??\B:\myfile.dat可能是完整的檔案規格,前提是磁碟驅動器和過度載入文件系統。 如需詳細資訊,請參閱 檔名、路徑和命名空間
ULONG 屬性
這是一組旗標,可控制檔案物件屬性。 這個值可以是零或 OBJ_CASE_INSENSITIVE,表示名稱查閱程式代碼應該忽略 ObjectName 成員的情況,而不是執行完全相符的搜尋。 值 OBJ_INHERIT 與裝置和中繼驅動程序無關。
PSECURITY_DESCRIPTOR SecurityDescriptor
選擇性地指定要套用至檔案的安全性描述項。 這類安全性描述元所指定的 ACL 只會在建立檔案時套用至檔案。 如果在建立檔案時 NULL 值,則放置於檔案上的 ACL 與文件系統相依;大部分的文件系統都會從父目錄檔案傳播這類 ACL 的一部分,並結合呼叫端的預設 ACL。 裝置與中繼驅動程式可以將這個成員設定為 NULL
PSECURITY_QUALITY_OF_SERVICE SecurityQualityOfService
指定伺服器應提供給用戶端安全性內容的訪問許可權。 只有在建立與受保護伺服器的連線時,這個值是非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

呼叫端想要在檔案中使用的共用存取類型,為零,或做為下列值的一或組合。

價值 意義
FILE_SHARE_READ
檔案可以透過其他線程呼叫 ntCreateFile 開啟以讀取許可權。
FILE_SHARE_WRITE
檔案可以透過其他線程呼叫 ntCreateFile 開啟以進行寫入存取。
FILE_SHARE_DELETE
檔案可以透過其他線程呼叫 ntCreateFile 開啟以刪除存取。
 

如需詳細資訊,請參閱 Windows SDK。

[in] CreateDisposition

根據檔案是否已經存在,指定要執行的動作,做為下列其中一個值。

價值 意義
FILE_SUPERSEDE
如果檔案已經存在,請將它取代為指定的檔案。 如果沒有,請建立指定的檔案。
FILE_CREATE
如果檔案已經存在,則要求失敗,且不會建立或開啟指定的檔案。 如果沒有,請建立指定的檔案。
FILE_OPEN
如果檔案已經存在,請開啟它,而不是建立新的檔案。 如果沒有,請失敗要求,且不會建立新的檔案。
FILE_OPEN_IF
如果檔案已經存在,請加以開啟。 如果沒有,請建立指定的檔案。
FILE_OVERWRITE
如果檔案已經存在,請加以開啟並加以覆寫。 如果沒有,請失敗要求。
FILE_OVERWRITE_IF
如果檔案已經存在,請加以開啟並加以覆寫。 如果沒有,請建立指定的檔案。

[in] CreateOptions

建立或開啟檔案時要套用的選項,做為下列旗標的相容組合。

價值 意義
FILE_DIRECTORY_FILE
正在建立或開啟的檔案是目錄檔案。 使用此旗標,CreateDisposition 參數必須設定為 FILE_CREATEFILE_OPENFILE_OPEN_IF。 使用此旗標時,其他相容 CreateOptions 旗標只包含下列專案:FILE_SYNCHRONOUS_IO_ALERTFILE_SYNCHRONOUS_IO _NONALERTFILE_WRITE_THROUGHFILE_OPEN_FOR_BACKUP_INTENTFILE_OPEN_BY_FILE_ID
FILE_NON_DIRECTORY_FILE
開啟的檔案不得為目錄檔案,否則此呼叫會失敗。 正在開啟的檔案物件可以代表數據檔、邏輯、虛擬或實體裝置,或磁碟區。
FILE_WRITE_THROUGH
將數據寫入檔案的應用程式必須實際將數據傳輸到檔案,才能將任何要求的寫入作業視為完成。 如果設定 CreateOptions 旗標 FILE_NO_INTERMEDIATE _BUFFERING,則會自動設定此旗標。
FILE_SEQUENTIAL_ONLY
對檔案的所有存取都是循序的。
FILE_RANDOM_ACCESS
對檔案的存取可以是隨機的,因此 FSD 或系統不應對檔案執行任何循序的預先讀取作業。
FILE_NO_INTERMEDIATE_BUFFERING
無法在驅動程式的內部緩衝區中快取或緩衝處理檔案。 此旗標與 DesiredAccessFILE_APPEND_DATA 旗標 不相容。
FILE_SYNCHRONOUS_IO_ALERT
檔案上的所有作業都會同步執行。 代表呼叫端的任何等候,都受限於警示的過早終止。 此旗標也會讓 I/O 系統維護檔案位置內容。 如果設定此旗標,也必須設定 DesiredAccessSYNCHRONIZE 旗標。
FILE_SYNCHRONOUS_IO_NONALERT
檔案上的所有作業都會同步執行。 系統等候同步處理 I/O 佇列和完成,不受警示限制。 此旗標也會讓 I/O 系統維護檔案位置內容。 如果設定此旗標,也必須設定 DesiredAccessSYNCHRONIZE 旗標。
FILE_CREATE_TREE_CONNECTION
建立此檔案的樹狀結構連線,以便透過網路開啟它。 裝置和中繼驅動程式不會使用此旗標。
FILE_NO_EA_KNOWLEDGE
如果開啟之現有檔案上的擴充屬性表示呼叫端必須瞭解 EA 才能正確解譯檔案,則失敗此要求,因為呼叫端無法瞭解如何處理 EA。 此旗標與裝置和中繼驅動程序無關。
FILE_OPEN_REPARSE_POINT
使用重新分析點開啟檔案,並略過檔案的一般重新分析點處理。 如需詳細資訊,請參閱一節。
FILE_DELETE_ON_CLOSE
將最後一個句柄傳遞給 ntClose 時,請刪除檔案。 如果設定此旗標,必須在 desiredAccess 參數 設定 DELETE 旗標。
FILE_OPEN_BY_FILE_ID
ObjectAttributes 參數所指定的檔名包含檔案的 8 位元組檔案參考編號。 這個數位是由特定文件系統所指派,且專屬於特定文件系統。 如果檔案是重新分析點,檔名也會包含裝置的名稱。 請注意,FAT 檔系統不支援此旗標。 裝置和中繼驅動程式不會使用此旗標。
FILE_OPEN_FOR_BACKUP_INTENT
檔案正在開啟以供備份意圖使用。 因此,系統應該檢查特定訪問許可權,並在檢查 DesiredAccess 參數之前,先向呼叫者授與適當的檔案存取權,再檢查檔案的安全性描述元。 裝置和中繼驅動程式未使用這個旗標。
FILE_RESERVE_OPFILTER
此旗標可讓應用程式要求篩選機會鎖定(oplock),以防止其他應用程式收到共用違規。 如果已經有開啟的句柄,建立要求將會失敗,並 STATUS_OPLOCK_NOT_GRANTED。 如需詳細資訊,請參閱一節。
FILE_OPEN_REQUIRING_OPLOCK
檔案正在開啟,且檔案上的機會鎖定(oplock)會要求為單一不可部分完成的作業。 文件系統在執行建立作業之前會檢查 oplock,如果結果會中斷現有的 oplock,則建立將會失敗,並傳回 STATUS_CANNOT_BREAK_OPLOCK 碼。 如需詳細資訊,請參閱一節。Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP:不支援此旗標。

下列檔案系統支援此旗標:NTFS、FAT 和exFAT。

FILE_COMPLETE_IF_OPLOCKED
如果目標檔案為 oplock,而不是封鎖呼叫端的線程,請立即完成此作業,並 STATUS_OPLOCK_BREAK_IN_PROGRESS 替代成功碼。 如果檔案 oplocked,則另一個呼叫端已經可以存取檔案。 裝置和中繼驅動程式不會使用此旗標。

[in] EaBuffer

用來傳遞擴充屬性的EA緩衝區指標。

注意 某些文件系統可能不支援EA緩衝區。
 

[in] EaLength

EA 緩衝區的長度。

傳回值

NtCreateFile 會傳回 STATUS_SUCCESS 或適當的錯誤狀態。 如果傳回錯誤狀態,呼叫端可以藉由檢查 ioStatusBlock來尋找失敗原因的詳細資訊。 為了簡化這項檢查,應用程式可以使用 NT_SUCCESSNT_ERRORNT_WARNING 宏。

言論

NtCreateFile所提供的句柄,可供後續呼叫來操作檔案內的數據或檔案物件的狀態或屬性。

有兩種替代方式可指定要建立或開啟的檔名,NtCreateFile

  • 作為完整路徑名稱,提供於輸入 ObjectAttributes ObjectName 成員
  • 做為路徑名稱,相對於輸入 ObjectAttributes RootDirectory 中句柄所代表的目錄檔案
某些 DesiredAccess 旗標和旗標的組合具有下列效果:
  • 若要讓呼叫端等候傳回 的 FileHandle來同步處理 I/O 完成,必須設定 SYNCHRONIZE 旗標。
  • 將零傳遞至 DesiredFlags 無效。
  • 如果只設定 FILE_APPEND_DATASYNCHRONIZE 旗標,則呼叫端只能寫入檔案結尾,而且會忽略寫入檔案的任何位移資訊。 不過,此檔案會視需要自動擴充此類型的寫入作業。
  • 設定檔案的 FILE_WRITE_DATA 旗標也允許寫入檔案結尾之後發生。 這個類型的寫入也會自動擴充檔案。
  • 如果只設定 FILE_EXECUTESYNCHRONIZE 旗標,則呼叫端無法使用傳回 FileHandle直接讀取或寫入檔案中的任何數據,也就是說,檔案上的所有作業都會透過系統呼叫器來回應指令和數據存取。
ShareAccess 參數會決定個別線程是否可以同時存取相同的檔案。 如果這兩個檔案開啟者具有以指定方式存取檔案的許可權,就可以成功開啟和共用檔案。 如果 ntCreateFile 的原始呼叫者未指定 FILE_SHARE_READFILE_SHARE_WRITEFILE_SHARE_DELETE,則無法對檔案執行任何其他開啟作業:也就是說,原始呼叫端會獲得檔案的獨佔存取權。

若要成功開啟共用檔案,要求的 DesiredAccess 參數與檔案的 DesiredAccessShareAccess 規格相容,且先前尚未發行 NtClose。 也就是說,指定給指定檔案 NtCreateFile 指定的 DesiredAccess 參數不得與不允許其他檔案開啟者存取權衝突。

CreateDispositionFILE_SUPERSEDE 要求呼叫端具有對現有檔案物件的存取權 DELETE。 若是如此,在現有檔案上成功呼叫 NtCreateFileFILE_SUPERSEDE 會有效刪除該檔案,然後重新建立它。 這表示,如果檔案已由另一個線程開啟,則會指定已設定 FILE_SHARE_DELETE 旗標的 ShareAccess 參數,以開啟檔案。 請注意,這種類型的處置與覆寫檔案的POSIX樣式一致。 CreateDispositionFILE_OVERWRITE_IFFILE_SUPERSEDE 類似。 如果 ZwCreateFile 是以現有的檔案呼叫,且其中任一 CreateDisposition 值,則會取代檔案。

覆寫檔案在語意上相當於取代作業,但下列除外:

  • 呼叫端必須具有檔案的寫入許可權,而不是刪除存取權。 這表示,如果檔案已由另一個線程開啟,則會開啟檔案,並在輸入 ShareAccess 參數中設定 FILE_SHARE_WRITE 旗標。
  • 指定的檔案屬性在邏輯上是 ORed,且檔案上已有這些屬性。 這表示,如果檔案已由另一個線程開啟,則 NtCreateFile 的後續呼叫者 無法停用現有的 FileAttributes 旗標,但可以啟用相同檔案的其他旗標。 請注意,此覆寫檔案樣式與 MS-DOS、Windows 3.1 和 OS/2 操作系統一致。
CreateOptionsFILE_DIRECTORY_FILE 值會指定要建立或開啟的檔案是目錄檔案。 建立目錄檔案時,文件系統會在磁碟上建立適當的結構,以代表該特定文件系統磁碟結構空的目錄。 如果已指定此選項且要開啟的指定檔案不是目錄檔案,或者呼叫者指定 了不一致的 createOptionsCreateDisposition 值,則對 ntCreateFile 呼叫失敗。

CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING 旗標可防止文件系統代表呼叫端執行任何中繼緩衝。 指定此值會將呼叫端參數的某些限制放在其他 NtXXXFile 例程上,包括下列專案:

  • 傳遞至 NtReadFileNtWriteFile 函式的任何選擇性 ByteOffset 都必須是扇區大小的整數。
  • 傳遞至 NtReadFileNtWriteFileLength 必須是扇區大小的整數。 請注意,將讀取作業指定給長度正好是扇區大小的緩衝區,可能會導致在傳輸期間到達檔尾時,將較少的大量位元組傳送至該緩衝區。
  • 緩衝區必須根據基礎裝置的對齊需求進行調整。 您可以呼叫 NtCreateFile 取得此資訊,以取得代表實體裝置的檔案物件句柄,然後使用該句柄呼叫 NtQueryInformationFile。 如需系統 FILE_XXX_ALIGNMENT 值的清單,請參閱 Windows SDK 檔。
  • 呼叫 NtSetInformationFile,並將 fileInformationClass 參數設定為 FilePositionInformation 必須指定扇區大小整數的位移。
CreateOptionsFILE_SYNCHRONOUS_IO_ALERTFILE_SYNCHRONOUS_IO_NONALERT 旗標,其名稱互斥,指定只要透過傳回 FileHandle所參考的檔案對象,檔案上的所有 I/O 作業都是同步的。 這類檔案上的所有 I/O 都會使用傳回的句柄,跨所有線程串行化。 使用上述任一 CreateOptions,必須設定 DesiredAccessSYNCHRONIZE 旗標,讓 I/O 管理員使用檔案物件做為同步處理物件。 設定下列任一 CreateOptions,I/O 管理員會維護檔案物件的「檔案位置內容」,這是內部、目前的檔案位置位移。 此位移可用於呼叫 NtReadFileNtWriteFile。 其位置也可以透過 NtQueryInformationFileNtSetInformationFile進行查詢或設定。

如果 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 要求失敗之後關閉其句柄。

附註 Windows 7、Windows Server 2008 R2 和更新版本的操作系統中提供 FILE_OPEN_REQUIRING_OPLOCK 旗標,適用於下列文件系統:NTFS、FAT 和 exFAT。
 

CreateOptions 參數的 FILE_RESERVE_OPFILTER 旗標可讓應用程式要求層級 1、Batch 或 Filter oplock,以防止其他應用程式收到共享違規。 不過,實際上,FILE_RESERVE_OPFILTER 僅適用於篩選作業鎖定。 若要使用它,您必須完成下列步驟:

  1. 發出建立要求,CreateOptionsFILE_RESERVE_OPFILTERDesiredAccess 完全 FILE_READ_ATTRIBUTESShareAccess 完全 (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
  2. 如果建立要求成功,請要求 oplock。
  3. 開啟檔案的另一個句柄以執行 I/O。
步驟 3 讓這項操作僅適用於篩選作業鎖定。 在步驟三中開啟的句柄可以有一個 DesiredAccess,其中包含最多 (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。 您也可以使用 LoadLibraryGetProcAddress 函式動態連結至 NtDll.dll。

要求

要求 價值
目標平臺 窗戶
標頭 winternl.h
連結庫 ntdll.lib
DLL ntdll.dll