IoCreateFile-Funktion (wdm.h)

Artikel
02/07/2025

Die IoCreateFile Routine bewirkt entweder, dass eine neue Datei oder ein neues Verzeichnis erstellt wird, oder es öffnet eine vorhandene Datei, ein Gerät, ein Verzeichnis oder ein Volume, wodurch der Aufrufer ein Handle für das Dateiobjekt erhält.

Syntax

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
);

Parameter

[out] FileHandle

Zeigen Sie auf eine Variable, die das Dateihandle empfängt, wenn der Aufruf erfolgreich ist. Der Fahrer muss den Handle mit ZwClose schließen, sobald der Griff nicht mehr verwendet wird.

[in] DesiredAccess

Eine Bitmaske von Flags, die den Typ des Zugriffs auf die Datei oder das Verzeichnis angibt, die der Aufrufer benötigt. Weitere Informationen zu diesem Parameter und zur Liste der Flagwerte finden Sie im DesiredAccess Parameter von IoCreateFileEx.

[in] ObjectAttributes

Zeiger auf eine undurchsichtige OBJECT_ATTRIBUTES Struktur, die bereits mit InitializeObjectAttributesinitialisiert wurde. Weitere Informationen und eine Beschreibung jedes Strukturelements finden Sie im ObjectAttributes Parameter von IoCreateFileEx.

[out] IoStatusBlock

Zeigen Sie auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und Informationen zum angeforderten Vorgang empfängt. Siehe den IoStatusBlock Parameter von IoCreateFileEx.

[in, optional] AllocationSize

Gibt optional die anfängliche Zuordnungsgröße in Bytes für die Datei an. Ein Wert ungleich Null hat keine Auswirkung, es sei denn, die Datei wird erstellt, überschrieben oder abgelöst.

[in] FileAttributes

Explizit angegebene Attribute werden nur angewendet, wenn die Datei erstellt, abgelöst oder in einigen Fällen überschrieben wird. Standardmäßig ist dieser Wert FILE_ATTRIBUTE_NORMAL, der durch eine ORed-Kombination aus einer oder mehreren FILE_ATTRIBUTE_XXX- Flags überschrieben werden kann, die in Wdm.h definiert sind. Eine Liste der Flags, die mit IoCreateFile-verwendet werden können, finden Sie unter CreateFile.

[in] ShareAccess

Gibt den Typ des Freigabezugriffs auf die Datei an, die der Aufrufer als Null oder 1 oder eine Kombination der Flags benötigt. Weitere Details und die Liste der Flags finden Sie im ShareAccess Parameter von IoCreateFileEx.

[in] Disposition

Gibt einen Wert an, der die auszuführende Aktion bestimmt, je nachdem, ob die Datei bereits vorhanden ist. Die Liste der möglichen Werte finden Sie im Disposition Parameter von IoCreateFileEx.

[in] CreateOptions

Gibt die Optionen an, die beim Erstellen oder Öffnen der Datei angewendet werden sollen. Dieser Parameter ist eine kompatible Kombination der im CreateOptions Parameter von IoCreateFileExaufgeführten und beschriebenen Flags.

[in, optional] EaBuffer

Bei Geräte- und Zwischentreibern muss dieser Parameter ein NULL- Zeiger sein.

[in] EaLength

Für Geräte- und Zwischentreiber muss dieser Parameter null sein.

[in] CreateFileType

Treiber müssen diesen Parameter auf CreateFileTypeNonefestlegen.

[in, optional] InternalParameters

Treiber müssen diesen Parameter auf NULL-festlegen.

[in] Options

Gibt Optionen an, die während der Erstellung der Erstellung der Erstellungsanforderung verwendet werden sollen. Die Liste der möglichen Optionen finden Sie unter Options Parameter von IoCreateFileEx.

Rückgabewert

IoCreateFile- gibt entweder STATUS_SUCCESS oder einen entsprechenden Fehlerstatus zurück. NTSTATUS-Wert. Eine Liste möglicher Rückgabecodes finden Sie im Abschnitt RückgabewertIoCreateFileEx.

Bemerkungen

Die IoCreateFileEx Routine ähnelt der IoCreateFile Routine, bietet jedoch eine größere Funktionalität als die IoCreateFile Routine, einschließlich Des Zugriffs auf zusätzliche Erstellungsparameter (ECPs), Geräteobjekte und Transaktionsinformationen.

Das handle, das von IoCreateFile abgerufen wird, kann durch nachfolgende Aufrufe zum Bearbeiten von Daten innerhalb der Datei oder des Zustands oder der Attribute des Dateiobjekts verwendet werden.

Es gibt zwei alternative Möglichkeiten, den Namen der zu erstellenden oder geöffneten Datei mit IoCreateFile-anzugeben:

Als vollqualifizierter Pfadname, der im ObjectName Member der Eingabe ObjectAttributes-
Als Pfadname relativ zur Verzeichnisdatei, die durch das Handle im RootDirectory Member der Eingabe ObjectAttributes dargestellt wird

Bestimmte DesiredAccess Flags und Kombinationen von Flags haben folgende Auswirkungen:

Damit ein Aufrufer einen E/A-Abschluss synchronisiert, indem er auf die zurückgegebene FileHandle-wartet, muss das SYNCHRONIZE-Flag festgelegt werden. Andernfalls muss ein Aufrufer, der ein Gerät oder ein Zwischentreiber ist, einen E/A-Abschluss mithilfe eines Ereignisobjekts synchronisieren.
Wenn nur die Flags FILE_APPEND_DATA und SYNCHRONIZE festgelegt sind, kann der Aufrufer nur an das Ende der Datei schreiben, und alle Offsetinformationen zu Schreibvorgängen in die Datei werden ignoriert. Die Datei wird jedoch bei Bedarf für diesen Schreibvorgang automatisch erweitert.
Das Festlegen des FILE_WRITE_DATA Flags für eine Datei ermöglicht auch das Auftreten von Schreibvorgängen über das Ende der Datei hinaus. Die Datei wird für diesen Schreibtyp automatisch erweitert.
Wenn nur die FILE_EXECUTE- und SYNCHRONIZE-Flags festgelegt sind, kann der Aufrufer keine Daten in der Datei mithilfe der zurückgegebenen FileHandle-direkt lesen oder schreiben: d. h., alle Vorgänge der Datei erfolgen über den System-Pager als Reaktion auf Anweisungen und Datenzugriffe. Geräte- und Zwischentreiber sollten das FILE_EXECUTE Flag in DesiredAccess-nicht festlegen.

Der parameter ShareAccess bestimmt, ob separate Threads gleichzeitig auf dieselbe Datei zugreifen können. Sofern beide Dateiöffner über die Berechtigung verfügen, auf eine Datei auf die angegebene Weise zuzugreifen, kann die Datei erfolgreich geöffnet und freigegeben werden. Wenn der ursprüngliche Aufrufer von IoCreateFile- nicht FILE_SHARE_READ, FILE_SHARE_WRITE oder FILE_SHARE_DELETE angibt, können keine anderen Geöffneten Vorgänge für die Datei ausgeführt werden: d. h. der ursprüngliche Aufrufer erhält exklusiven Zugriff auf die Datei.

Damit eine freigegebene Datei erfolgreich geöffnet werden kann, muss die angeforderte DesiredAccess- mit der Datei kompatibel sein, sowohl mit der DesiredAccess- als auch mit ShareAccess- Spezifikationen aller vorherigen Öffnen, die noch nicht mit ZwCloseveröffentlicht wurden. Das heißt, die DesiredAccess-, die für IoCreateFile- für eine bestimmte Datei angegeben wurde, darf nicht mit den Zugriffen in Konflikt stehen, die andere Opener der Datei nicht zugelassen haben.

Der Dispositionswert FILE_SUPERSEDE erfordert, dass der Aufrufer DELETE-Zugriff auf ein vorhandenes Dateiobjekt hat. Wenn ja, wird ein erfolgreicher Aufruf von IoCreateFile mit FILE_SUPERSEDE für eine vorhandene Datei effektiv gelöscht und anschließend neu erstellt. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, die Datei durch Angeben eines ShareAccess--Parameters mit dem FILE_SHARE_DELETE Flagsatz geöffnet wurde. Beachten Sie, dass diese Art von Löschung mit dem POSIX-Stil des Überschreibens von Dateien konsistent ist.

Die Disposition Werte FILE_OVERWRITE_IF und FILE_SUPERSEDE ähneln. Wenn IoCreateFile- mit einer vorhandenen Datei aufgerufen wird und einer dieser Disposition Werte, wird die Datei ersetzt.

Das Überschreiben einer Datei entspricht semantisch einem Supersede-Vorgang, mit Ausnahme der folgenden Aktionen:

Der Aufrufer muss Schreibzugriff auf die Datei haben, anstatt den Zugriff zu löschen. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, die Datei mit dem FILE_SHARE_WRITE Flag geöffnet wurde, das in der Eingabe ShareAccessfestgelegt ist.
Die angegebenen Dateiattribute werden logisch mit den bereits in der Datei gespeicherten Attributen versehen. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, ein nachfolgender Aufrufer von IoCreateFile vorhandene FileAttributes Flags nicht deaktivieren kann, aber zusätzliche Flags für dieselbe Datei aktivieren kann.

Der wert CreateOptions FILE_DIRECTORY_FILE gibt an, dass die zu erstellende oder geöffnete Datei eine Verzeichnisdatei ist. Wenn eine Verzeichnisdatei erstellt wird, erstellt das Dateisystem eine geeignete Struktur auf dem Datenträger, um ein leeres Verzeichnis für die Struktur des jeweiligen Dateisystems auf dem Datenträger darzustellen. Wenn diese Option angegeben wurde und die zu öffnende Datei keine Verzeichnisdatei ist oder wenn der Aufrufer eine inkonsistente CreateOptions oder Disposition Wert angegeben hat, schlägt der Aufruf von IoCreateFile fehl.

Das CreateOptions FILE_NO_INTERMEDIATE_BUFFERING Flag verhindert, dass das Dateisystem im Auftrag des Aufrufers zwischenpuffert. Wenn Sie diesen Wert angeben, werden bestimmte Einschränkungen für die Parameter des Aufrufers an die ZwXxxFile Routinen, einschließlich der folgenden:

Alle optionalen ByteOffset-, die an ZwReadFile oder ZwWriteFile übergeben werden, müssen ein Integral der Sektorgröße sein.
Die Length an ZwReadFile oder ZwWriteFileübergeben wurde, muss ein Integral der Sektorgröße sein. Beachten Sie, dass das Angeben eines Lesevorgangs an einen Puffer, dessen Länge genau die Sektorgröße ist, zu einer geringeren Anzahl signifikanter Bytes führen kann, die an diesen Puffer übertragen werden, wenn das Ende der Datei während der Übertragung erreicht wurde.
Puffer müssen entsprechend der Ausrichtungsanforderung des zugrunde liegenden Geräts ausgerichtet werden. Diese Informationen können durch Aufrufen von IoCreateFile- abgerufen werden, um ein Handle für das Dateiobjekt abzurufen, das das physische Gerät darstellt, und anschließend ZwQueryInformationFile- mit diesem Handle aufrufen. Eine Liste der Systemwerte FILE_XXX-_ALIGNMENT finden Sie unter DEVICE_OBJECT.
Aufrufe von ZwSetInformationFile mit dem parameter FileInformationClass auf FilePositionInformation müssen einen Offset angeben, der ein integraler Bereich der Sektorgröße ist.

Die CreateOptions FILE_SYNCHRONOUS_IO_ALERT und FILE_SYNCHRONOUS_IO_NONALERT, die sich gegenseitig ausschließen, wie ihre Namen vorschlagen, geben an, dass alle E/A-Vorgänge in der Datei synchron sein sollen, solange sie über das dateiobjekt auftreten, das durch die zurückgegebene FileHandle-bezeichnet wird. Alle E/A-Vorgänge in einer solchen Datei werden über alle Threads serialisiert, indem das zurückgegebene Handle verwendet wird. Bei einem dieser CreateOptions-muss das flag DesiredAccess SYNCHRONIZE so festgelegt werden, dass der E/A-Manager das Dateiobjekt als Synchronisierungsobjekt verwendet. Mit einer dieser CreateOptions festgelegt, verwaltet der E/A-Manager den "Dateipositionskontext" für das Dateiobjekt, einen internen, aktuellen Dateipositionsoffset. Dieser Offset kann in Aufrufen von ZwReadFile- und ZwWriteFile-verwendet werden. Seine Position kann auch mit ZwQueryInformationFile und ZwSetInformationFileabgefragt oder festgelegt werden.

Wenn das CreateOptions- FILE_OPEN_REPARSE_POINT Flag nicht angegeben ist und IoCreateFile versucht, eine Datei mit einem Analysepunkt zu öffnen, tritt eine normale Analysepunktverarbeitung für die Datei auf. Wenn dagegen das FILE_OPEN_REPARSE_POINT Flag angegeben ist, erfolgt die normale Analyseverarbeitung nicht und IoCreateFile versucht, die Analysepunktdatei direkt zu öffnen. Wenn der Öffnenvorgang erfolgreich war, gibt IoCreateFile- in beiden Fällen STATUS_SUCCESS zurück; andernfalls gibt die Routine einen NTSTATUS-Fehlercode zurück. IoCreateFile- gibt nie STATUS_REPARSE zurück.

Die CreateOptions- FILE_OPEN_REQUIRING_OPLOCK Flag beseitigt den Zeitraum zwischen dem Öffnen der Datei und dem Anfordern eines Oplocks, der es einem Drittanbieter ermöglichen könnte, die Datei zu öffnen und einen Freigabeverstoß zu erhalten. Eine Anwendung kann das FILE_OPEN_REQUIRING_OPLOCK-Flag für IoCreateFile- verwenden und dann oplock anfordern. Dadurch wird sichergestellt, dass ein Oplock-Besitzer über jede spätere offene Anforderung benachrichtigt wird, die einen Freigabeverstoß verursacht.

Wenn in Windows 7 andere Handles in der Datei vorhanden sind, wenn eine Anwendung das FILE_OPEN_REQUIRING_OPLOCK Flag verwendet, schlägt der Erstellungsvorgang mit STATUS_OPLOCK_NOT_GRANTED fehl. Diese Einschränkung ist ab Windows 8 nicht mehr vorhanden.

Wenn dieser Erstellungsvorgang einen Oplock unterbricht, der bereits in der Datei vorhanden ist, führt das Festlegen des FILE_OPEN_REQUIRING_OPLOCK Flags dazu, dass der Erstellungsvorgang mit STATUS_CANNOT_BREAK_OPLOCK fehlschlägt. Der vorhandene Oplock wird durch diesen Erstellungsvorgang nicht unterbrochen.

Eine Anwendung, die das flag FILE_OPEN_REQUIRING_OPLOCK verwendet, muss ein Oplock anfordern, nachdem dieser Aufruf erfolgreich war, oder alle nachfolgenden Versuche zum Öffnen der Datei werden ohne den Vorteil der normalen Oplock-Verarbeitung blockiert. Wenn dieser Aufruf erfolgreich ausgeführt wird, aber die nachfolgende Oplock-Anforderung fehlschlägt, muss eine Anwendung, die dieses Flag verwendet, sein Handle schließen, nachdem erkannt wird, dass die Oplock-Anforderung fehlgeschlagen ist.

Das kennzeichen FILE_OPEN_REQUIRING_OPLOCK ist in Windows 7, Windows Server 2008 R2 und höheren Versionen von Windows verfügbar. Die Microsoft-Dateisysteme, die dieses Kennzeichen in Windows 7 implementieren, sind NTFS, FAT und exFAT.

Die CreateOptions- Flag, FILE_RESERVE_OPFILTER, ermöglicht einer Anwendung das Anfordern eines Oplocks der Ebene 1, eines Batchs oder eines Filters, um zu verhindern, dass andere Anwendungen Freigabeverletzungen erhalten. FILE_RESERVE_OPFILTER ist jedoch nur für Filter-Oplocks nützlich. Um sie zu verwenden, müssen Sie die folgenden Schritte ausführen:

Erstellen einer Anforderung mit CreateOptions- von FILE_RESERVE_OPFILTER, DesiredAccess- genau FILE_READ_ATTRIBUTES und ShareAccess- genau FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Wenn bereits geöffnete Handles vorhanden sind, schlägt die Erstellungsanforderung mit STATUS_OPLOCK_NOT_GRANTED fehl, und das nächste angeforderte Oplock schlägt ebenfalls fehl.
- Wenn Sie mit mehr Zugriff oder weniger Freigabe öffnen, tritt auch ein Fehler von STATUS_OPLOCK_NOT_GRANTED auf.
Wenn die Erstellungsanforderung erfolgreich ist, fordern Sie ein Oplock an.
Öffnen Sie ein weiteres Handle für die Datei, um E/A zu erledigen.

Schritt 3 macht dies nur für Filter oplocks praktisch. Der in Schritt 3 geöffnete Handle kann eine DesiredAccess- haben, die maximal FILE_READ_ATTRIBUTES enthält | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONISIEREN | READ_CONTROL und trotzdem keinen Filter-Oplock aufheben. Alle DesiredAccess jedoch größer als FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE unterbricht einen Oplock der Ebene 1 oder eines Batches und macht das FILE_RESERVE_OPFILTER Flag für diese Oplock-Typen nutzlos.

Die Optionen IO_NO_PARAMETER_CHECKING Flags können nützlich sein, wenn ein Treiber eine Kernelmodus-Erstellungsanforderung im Auftrag eines Vorgangs ausgibt, der von einer Benutzermodusanwendung initiiert wird. Da die Anforderung innerhalb eines Benutzermoduskontexts auftritt, durchläuft der E/A-Manager standardmäßig die angegebenen Parameterwerte, was zu einer Zugriffsverletzung führen kann, wenn es sich bei den Parametern um Kernelmodusadressen handelt. Mit dieser Kennzeichnung kann der Aufrufer dieses Standardverhalten außer Kraft setzen und die Zugriffsverletzung vermeiden.

Wenn der Treiber sowohl IO_NO_PARAMETER_CHECKING als auch IO_FORCE_ACCESS_CHECK im Parameter Options von IoCreateFile festgelegt wird, sollte er auch im parameter ObjectAttributes OBJ_FORCE_ACCESS_CHECK festlegen. Informationen zu diesem Flag finden Sie im Attributes Member von OBJECT_ATTRIBUTES.

NTFS ist das einzige Microsoft-Dateisystem, das FILE_RESERVE_OPFILTER implementiert.

Treiberroutinen, die in einem anderen Prozesskontext als dem des Systemprozesses ausgeführt werden, müssen das OBJ_KERNEL_HANDLE-Attribut für den parameter ObjectAttributes parameter von IoCreateFilefestlegen. Dadurch wird die Verwendung des von IoCreateFile zurückgegebenen Handle auf Prozesse beschränkt, die nur im Kernelmodus ausgeführt werden. Andernfalls kann über den Prozess, in dem der Treiber ausgeführt wird, auf das Handle zugegriffen werden kann. Treiber können InitializeObjectAttributes- aufrufen, um das attribut OBJ_KERNEL_HANDLE wie folgt festzulegen.

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

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)