共用方式為

IoCreateFile 函式 （wdm.h）

  • 發行項

IoCreateFile 例程會建立新的檔案或目錄，或是開啟現有的檔案、裝置、目錄或磁碟區，讓呼叫者擁有檔案物件的句柄。

語法

NTSTATUS IoCreateFile(
  [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              Disposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength,
  [in]           CREATE_FILE_TYPE   CreateFileType,
  [in, optional] PVOID              InternalParameters,
  [in]           ULONG              Options
);

參數

[out] FileHandle

如果呼叫成功，接收檔案句柄的變數指標。 驅動程序必須在不再使用句柄后關閉句柄，ZwClose。

[in] DesiredAccess

旗標的位掩碼，指定呼叫端所需的檔案或目錄存取類型。 如需此參數和旗標值清單的詳細資訊，請參閱 IoCreateFileExDesiredAccess 參數。

[in] ObjectAttributes

已使用 initializeObjectAttributes 初始化之不透明 OBJECT_ATTRIBUTES 結構的指標。 如需詳細資訊和每個結構成員的描述，請參閱 IoCreateFileExObjectAttributes 參數。

[out] IoStatusBlock

IO_STATUS_BLOCK 結構的指標，該結構會接收最終完成狀態和要求之作業的相關信息。 請參閱 IoCreateFileEx的 IoStatusBlock 參數。

[in, optional] AllocationSize

選擇性地指定檔案的初始配置大小，以位元組為單位。 除非檔案正在建立、覆寫或取代，否則非零值沒有任何作用。

[in] FileAttributes

只有在檔案建立、取代或在某些情況下覆寫時，才會套用明確指定的屬性。 根據預設，這個值是FILE_ATTRIBUTE_NORMAL，可由 Wdm.h 中定義的一或多個 FILE_ATTRIBUTE_XXX 旗標的 ORed 組合覆寫。 如需可與 IoCreateFile搭配使用的旗標清單，請參閱 CreateFile。

[in] ShareAccess

指定呼叫端所需檔案的共用存取類型，以零或一個，或旗標的組合。 如需詳細資訊和旗標清單，請參閱 IoCreateFileExShareAccess 參數。

[in] Disposition

指定值，根據檔案是否已經存在，決定要採取的動作。 如需可能的值清單，請參閱 IoCreateFileEx 的 Disposition 參數。

[in] CreateOptions

指定要在建立或開啟檔案時套用的選項。 此參數是 IoCreateFileExCreateOptions 參數中所列出的旗標兼容組合。

[in, optional] EaBuffer

針對裝置和中繼驅動程式，此參數必須是 NULL 指標。

[in] EaLength

針對裝置和中繼驅動程式，此參數必須是零。

[in] CreateFileType

驅動程式必須將此參數設定為 CreateFileTypeNone。

[in, optional] InternalParameters

驅動程式必須將此參數設定為 NULL。

[in] Options

指定要在建立要求期間使用的選項。 如需可能的選項清單，請參閱 IoCreateFileEx 的 Options 參數。

傳回值

IoCreateFile 會傳回STATUS_SUCCESS或適當的錯誤狀態。 NTSTATUS 值。 如需可能的傳回碼清單，請參閱 IoCreateFileEx 的 傳回值 一節。

言論

IoCreateFileEx 例程類似於 IoCreateFile 例程，但提供的功能比 IoCreateFile 例程更強，包括存取額外的建立參數 （ECPs）、裝置物件和交易資訊。

IoCreateFile 取得的句柄，可供後續呼叫來作檔案內的數據或檔案物件的狀態或屬性。

有兩種替代方式可指定要建立或開啟的檔名，IoCreateFile：

  1. 作為完整路徑名稱，提供於輸入 ObjectAttributes ObjectName 成員

  2. 做為路徑名稱，相對於 input ObjectAttributes 之 input RootDirectory 成員中句柄所代表的目錄檔案

某些 DesiredAccess 旗標和旗標的組合具有下列效果：

  • 若要讓呼叫端等候傳回 FileHandle來同步處理 I/O 完成，必須設定 SYNCHRONIZE 旗標。 否則，裝置或中繼驅動程式的呼叫端必須使用事件物件來同步處理 I/O 完成。

  • 如果只設定FILE_APPEND_DATA和 SYNCHRONIZE 旗標，呼叫端只能寫入檔案結尾，而且會忽略寫入檔案的任何位移資訊。 不過，此檔案會視需要自動擴充此類型的寫入作業。

  • 設定檔案的FILE_WRITE_DATA旗標也允許在檔案結尾以外進行寫入。 這個類型的寫入也會自動擴充檔案。

  • 如果只設定FILE_EXECUTE和 SYNCHRONIZE 旗標，呼叫端就無法使用傳回的 fileHandle直接讀取或寫入檔案中的任何數據：也就是說，檔案上的所有作業都會透過系統呼叫器進行，以回應指令和數據存取。 裝置和中繼驅動程式不應在 DesiredAccess 中設定FILE_EXECUTE 旗標。

ShareAccess 參數會決定個別線程是否可以同時存取相同的檔案。 如果這兩個檔案開啟者具有以指定方式存取檔案的許可權，就可以成功開啟和共用檔案。 如果 IoCreateFile 的原始呼叫端 未指定FILE_SHARE_READ、FILE_SHARE_WRITE或FILE_SHARE_DELETE，則無法對檔案執行其他開啟作業：也就是說，原始呼叫端會獲得檔案的獨佔存取權。

若要成功開啟共用檔案，要求 DesiredAccess 檔案必須與 DesiredAccess 和 ShareAccess 規格相容，且尚未發行 ZwClose。 也就是說，指定給指定檔案 IoCreateFile 所指定的 DesiredAccess，不得與不允許其他檔案開啟者存取權衝突。

Disposition 值FILE_SUPERSEDE要求呼叫端具有現有檔案物件的 DELETE 存取權。 如果是，成功呼叫 IoCreateFile，並在現有檔案上FILE_SUPERSEDE有效地刪除該檔案，然後重新建立它。 這表示，如果檔案已經由另一個線程開啟，它會指定已設定FILE_SHARE_DELETE旗標的 ShareAccess參數來開啟檔案。 請注意，這種類型的處置與覆寫檔案的POSIX樣式一致。

處置 值FILE_OVERWRITE_IF和FILE_SUPERSEDE類似。 如果使用現有的檔案呼叫 IoCreateFile，且其中任一個 處置 值，則會取代檔案。

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

  • 呼叫端必須具有檔案的寫入許可權，而不是刪除存取權。 這表示，如果檔案已由另一個線程開啟，則會使用shareAccess 輸入中設定的 FILE_SHARE_WRITE 旗標開啟檔案。

  • 指定的檔案屬性在邏輯上是 ORed，且檔案上已有這些屬性。 這表示，如果檔案已由另一個線程開啟，則後續 IoCreateFile 的呼叫者 無法停用現有的 FileAttributes 旗標，但可以啟用相同檔案的其他旗標。

CreateOptions FILE_DIRECTORY_FILE 值會指定要建立或開啟的檔案是目錄檔案。 建立目錄檔案時，文件系統會在磁碟上建立適當的結構，以代表該特定文件系統磁碟結構空的目錄。 如果已指定此選項且要開啟的指定檔案不是目錄檔案，或者呼叫者指定 了不一致的 createOptions 或 Disposition 值，則呼叫 ioCreateFile 會失敗。

CreateOptions FILE_NO_INTERMEDIATE_BUFFERING 旗標可防止文件系統代表呼叫端執行任何中繼緩衝。 指定此值會將呼叫端參數的某些限制放在 ZwXxx檔案 例程，包括下列各項：

  • 傳遞至 ZwReadFile或 ZwWriteFile 的任何選擇性ByteOffset 都必須是扇區大小的整數。

  • 傳遞 至 ZwReadFile 或 ZwWriteFileLength 必須是扇區大小的整數。 請注意，將讀取作業指定給長度正好是扇區大小的緩衝區，可能會導致在傳輸期間到達檔尾時，將較少的大量位元組傳送至該緩衝區。

  • 緩衝區必須符合基礎裝置的對齊需求。 呼叫 ioCreateFile 即可取得這項資訊，以取得代表實體裝置的檔案物件句柄，然後使用該句柄呼叫 ZwQueryInformationFile。 如需系統FILE_XXX_ALIGNMENT 值的清單，請參閱 DEVICE_OBJECT。

  • 呼叫 ZwSetInformationFile，並將 fileInformationClass 參數設定為 FilePositionInformation 必須指定扇區大小整數的位移。

CreateOptions FILE_SYNCHRONOUS_IO_ALERT 和 FILE_SYNCHRONOUS_IO_NONALERT，其名稱互斥，指定只要透過傳回 FileHandle所參考的檔案對象，檔案上的所有 I/O 作業都是同步的。 這類檔案上的所有 I/O 都會使用傳回的句柄，跨所有線程串行化。 使用上述任一 CreateOptions，必須設定 DesiredAccess SYNCHRONIZE 旗標，讓 I/O 管理員將使用該檔案物件做為同步處理物件。 使用這其中一個 CreateOptions 設定，I/O 管理員會維護檔案物件的「檔案位置內容」、內部、目前的檔案位置位移。 此位移可用於呼叫 ZwReadFile 和 ZwWriteFile。 您也可以使用 ZwQueryInformationFile 和 ZwSetInformationFile來查詢或設定其位置。

如果未指定 CreateOptions FILE_OPEN_REPARSE_POINT 旗標，且 IoCreateFile 嘗試開啟具有重新分析點的檔案，則檔案會發生一般重新分析點處理。 另一方面，如果指定FILE_OPEN_REPARSE_POINT旗標，則不會進行一般重新剖析處理，而且 IoCreateFile 嘗試直接開啟重新分析點檔案。 在任一情況下，如果開啟作業成功，IoCreateFile 傳回STATUS_SUCCESS;否則，例程會傳回NTSTATUS錯誤碼。 IoCreateFile 永遠不會傳回STATUS_REPARSE。

CreateOptions FILE_OPEN_REQUIRING_OPLOCK 旗標可消除開啟檔案並要求 oplock 的時間，而該檔案可能會讓第三方開啟檔案並取得共享違規。 應用程式可以在 IoCreateFile 上使用 FILE_OPEN_REQUIRING_OPLOCK 旗標，然後要求任何 oplock。 這可確保Oplock擁有者會收到任何稍後造成共用違規之開啟要求的通知。

在 Windows 7 中，如果應用程式使用 FILE_OPEN_REQUIRING_OPLOCK 旗標時檔案上存在其他句柄，則建立作業將會失敗併產生STATUS_OPLOCK_NOT_GRANTED。 從 Windows 8 開始，此限制已不存在。

如果此建立作業會中斷檔案上已經存在的 oplock，則設定 FILE_OPEN_REQUIRING_OPLOCK 旗標會導致建立作業失敗並出現STATUS_CANNOT_BREAK_OPLOCK。 此建立作業不會中斷現有的 oplock。

使用此FILE_OPEN_REQUIRING_OPLOCK旗標的應用程式必須在此呼叫成功之後要求 oplock，否則所有後續嘗試開啟檔案都會遭到封鎖，而不會因正常 oplock 處理而受益。 同樣地，如果此呼叫成功，但後續的 oplock 要求失敗，則使用此旗標的應用程式必須在偵測到 oplock 要求失敗之後關閉其句柄。

FILE_OPEN_REQUIRING_OPLOCK旗標適用於 Windows 7、Windows Server 2008 R2 和更新版本的 Windows。 在 Windows 7 中實作此旗標的Microsoft文件系統為 NTFS、FAT 和 exFAT。

CreateOptions 旗標FILE_RESERVE_OPFILTER，可讓應用程式要求層級 1、批次或篩選 oplock，以防止其他應用程式收到共享違規。 不過，FILE_RESERVE_OPFILTER只適用於篩選作業鎖定。 若要使用它，您必須遵循下列步驟：

  1. 發出 CreateOptions FILE_RESERVE_OPFILTER、DesiredAccess 完全FILE_READ_ATTRIBUTES的 createOptions 和 ShareAccess FILE_SHARE_READ |FILE_SHARE_WRITE |FILE_SHARE_DELETE。

    • 如果已經有開啟的句柄，則建立要求會因為STATUS_OPLOCK_NOT_GRANTED而失敗，而下一個要求的 oplock 也會失敗。

    • 如果您以較多的存取權或較少共享開啟，也會導致STATUS_OPLOCK_NOT_GRANTED失敗。

  2. 如果建立要求成功，請要求 oplock。

  3. 開啟檔案的另一個句柄以執行 I/O。

步驟 3 只會針對篩選作業鎖定進行這項作。 在步驟 3 中開啟的句柄可以有 DesiredAccess，其中包含最多FILE_READ_ATTRIBUTES |FILE_WRITE_ATTRIBUTES |FILE_READ_DATA |FILE_READ_EA |FILE_EXECUTE |SYNCHRONIZE |READ_CONTROL，仍然不會中斷篩選作業鎖定。 不過，任何 DesiredAccess 大於 FILE_READ_ATTRIBUTES |FILE_WRITE_ATTRIBUTES |SYNCHRONIZE 會中斷層級 1 或批次 oplock，並使這些 oplock 類型的FILE_RESERVE_OPFILTER旗標無用。

如果驅動程式代表使用者模式應用程式所起始的作業發出內核模式建立要求，則 選項 IO_NO_PARAMETER_CHECKING 旗標會很有用。 由於要求會在使用者模式內容中發生，因此 I/O 管理員預設會探查所提供的參數值，如果參數是內核模式位址，可能會導致存取違規。 此旗標可讓呼叫端覆寫此預設行為，並避免存取違規。

針對源自使用者模式的建立要求，如果驅動程式在 IoCreateFile 的 Options 參數中同時設定IO_NO_PARAMETER_CHECKING和IO_FORCE_ACCESS_CHECK，則也應該在 ObjectAttributes 參數中設定OBJ_FORCE_ACCESS_CHECK。 如需此旗標的資訊，請參閱 OBJECT_ATTRIBUTES的 屬性 成員。

NTFS 是唯一實作FILE_RESERVE_OPFILTER Microsoft文件系統。

在系統進程以外的進程內容中執行的驅動程式例程，必須針對 IoCreateFile的 ObjectAttributes 參數設定 OBJ_KERNEL_HANDLE 屬性。 這會將 ioCreateFile 所傳回的句柄 限制為只在核心模式中執行的進程。 否則，進程可以存取其內容中的驅動程序執行句柄。 驅動程式可以呼叫 InitializeObjectAttributes 來設定OBJ_KERNEL_HANDLE屬性，如下所示。

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

要求

要求 價值
目標平臺 普遍
標頭 wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h）
連結庫 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 合規性規則 HwStorPortProhibitedDIs（storport）、IrqlIoPassive4（wdm）、PowerIrpDDis（wdm）

另請參閱

ACCESS_MASK

InitializeObjectAttributes

IO_STATUS_BLOCK

IoCreateFileEx （DesiredAccess 参数）

OBJECT_ATTRIBUTES

ZwClose

ZwCreateFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile