IoCreateFile-Funktion (wdm.h)

Artikel
08/08/2023

Die IoCreateFile-Routine bewirkt entweder, dass eine neue Datei oder ein neues Verzeichnis erstellt wird, oder sie öffnet eine vorhandene Datei, ein vorhandenes Gerät, ein Verzeichnis oder ein Volume, sodass 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

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

[in] DesiredAccess

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

[in] ObjectAttributes

Zeiger auf eine nicht transparente OBJECT_ATTRIBUTES Struktur, die bereits mit InitializeObjectAttributes initialisiert wurde. Weitere Informationen und eine Beschreibung der einzelnen Strukturmember finden Sie im Parameter ObjectAttributes von IoCreateFileEx .

[out] IoStatusBlock

Zeiger auf eine IO_STATUS_BLOCK-Struktur, die den endgültigen Abschluss status und Informationen zum angeforderten Vorgang empfängt. Weitere Informationen finden Sie unter dem IoStatusBlock-Parameter von IoCreateFileEx.

[in, optional] AllocationSize

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

[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 einem 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, den der Aufrufer benötigt, als Null oder 1 oder eine Kombination der Flags. Weitere Informationen und eine 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. Eine 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 Flags, die im CreateOptions-Parameter von IoCreateFileEx aufgeführt und beschrieben werden.

[in, optional] EaBuffer

Für Geräte- und Zwischentreiber 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 CreateFileTypeNone festlegen.

[in, optional] InternalParameters

Treiber müssen diesen Parameter auf NULL festlegen.

[in] Options

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

Rückgabewert

IoCreateFile gibt entweder STATUS_SUCCESS oder einen entsprechenden Fehler status zurück. NTSTATUS-Wert. Eine Liste der möglichen Rückgabecodes finden Sie im Abschnitt Rückgabewert von IoCreateFileEx .

Hinweise

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 von IoCreateFile abgerufene Handle kann von nachfolgenden Aufrufen verwendet werden, um Daten innerhalb der Datei oder des Zustands oder der Attribute des Dateiobjekts zu bearbeiten.

Es gibt zwei alternative Möglichkeiten, den Namen der Datei anzugeben, die mit IoCreateFile erstellt oder geöffnet werden soll:

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

Bestimmte DesiredAccess-Flags und Kombinationen von Flags haben die folgenden Auswirkungen:

Damit ein Aufrufer eine E/A-Vervollständigung synchronisieren kann, indem er auf die zurückgegebene FileHandle wartet, muss das SYNCHRONIZE-Flag festgelegt werden. Andernfalls muss ein Aufrufer, der ein Geräte- oder Zwischentreiber ist, eine E/A-Vervollständigung 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 automatisch erweitert, wenn dies für diese Art von Schreibvorgang erforderlich ist.
Das Festlegen des FILE_WRITE_DATA-Flags für eine Datei ermöglicht auch Schreibvorgänge über das Ende der Datei hinaus. Die Datei wird auch für diese Schreibart automatisch erweitert.
Wenn nur die Flags FILE_EXECUTE und SYNCHRONIZE festgelegt sind, kann der Aufrufer keine Daten in der Datei direkt mit dem zurückgegebenen FileHandle lesen oder schreiben. Das heißt, alle Vorgänge für die 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 ShareAccess-Parameter bestimmt, ob separate Threads möglicherweise gleichzeitig auf dieselbe Datei zugreifen können. Sofern beide Dateiöffner über die Berechtigung verfügen, auf die angegebene Weise auf eine Datei zuzugreifen, kann die Datei erfolgreich geöffnet und freigegeben werden. Wenn der ursprüngliche Aufrufer von IoCreateFile keine 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: Das heißt, der ursprüngliche Aufrufer erhält exklusiven Zugriff auf die Datei.

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

Der Dispositionswert FILE_SUPERSEDE erfordert, dass der Aufrufer über DELETE-Zugriff auf ein vorhandenes Dateiobjekt verfügt. Wenn ja, wird diese Datei bei einem erfolgreichen Aufruf von IoCreateFile mit FILE_SUPERSEDE für eine vorhandene Datei effektiv gelöscht und dann neu erstellt. Dies bedeutet, dass die Datei geöffnet wurde, wenn die Datei bereits von einem anderen Thread geöffnet wurde, indem sie einen ShareAccess-Parametermit festgelegtem FILE_SHARE_DELETE Flag angegeben hat. Beachten Sie, dass diese Art von Disposition mit dem POSIX-Stil des Überschreibens von Dateien konsistent ist.

Die Dispositionswerte FILE_OVERWRITE_IF und FILE_SUPERSEDE sind ähnlich. Wenn IoCreateFile mit einer vorhandenen Datei und einem dieser Dispositionswerte aufgerufen wird, wird die Datei ersetzt.

Das Überschreiben einer Datei entspricht semantisch einem Ablösungsvorgang, mit Ausnahme von Folgenden:

Der Aufrufer muss über Schreibzugriff auf die Datei verfügen, anstatt den Zugriff zu löschen. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, die Datei mit dem in der ShareAccess-Eingabe festgelegten FILE_SHARE_WRITE-Flag geöffnet wurde.
Die angegebenen Dateiattribute werden logisch mit denen, die sich bereits in der Datei befinden, aufgehoben. 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, sondern zusätzliche Flags für dieselbe Datei aktivieren kann.

Der Wert createOptions FILE_DIRECTORY_FILE gibt an, dass die zu erstellende oder zu öffnende 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 auf dem Datenträger dieses bestimmten Dateisystems darzustellen. Wenn diese Option angegeben wurde und die zu öffnende Datei keine Verzeichnisdatei ist, oder wenn der Aufrufer einen inkonsistenten CreateOptions - oder Disposition-Wert angegeben hat, schlägt der Aufruf von IoCreateFile fehl.

Das Flag CreateOptions FILE_NO_INTERMEDIATE_BUFFERING verhindert, dass das Dateisystem im Namen des Aufrufers Zwischenpufferungen ausführt. Wenn Sie diesen Wert angeben, gelten bestimmte Einschränkungen für die Parameter des Aufrufers für die Zw Xxx-Dateiroutinen, einschließlich der folgenden:

Jedes optionale ByteOffset , das an ZwReadFile oder ZwWriteFile übergeben wird, muss ein Integral der Sektorgröße sein.
Die anZwReadFile oder ZwWriteFile übergebene Länge muss ein Integral der Sektorgröße sein. Beachten Sie, dass die Angabe eines Lesevorgangs für einen Puffer, dessen Länge genau der Sektorgröße entspricht, dazu führen kann, dass eine geringere Anzahl signifikanter Bytes an diesen Puffer übertragen wird, 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 abgerufen werden, indem Sie IoCreateFile aufrufen, um ein Handle für das Dateiobjekt abzurufen, das das physische Gerät darstellt, und dann ZwQueryInformationFile mit diesem Handle aufrufen. Eine Liste der Systemwerte FILE_XXX_ALIGNMENT finden Sie unter DEVICE_OBJECT.
Aufrufe von ZwSetInformationFile mit dem FileInformationClass-Parameter , der auf FilePositionInformation festgelegt ist, müssen einen Offset angeben, der ein Integral der Sektorgröße ist.

Die CreateOptions-FILE_SYNCHRONOUS_IO_ALERT und FILE_SYNCHRONOUS_IO_NONALERT, die sich gegenseitig ausschließen, wie ihre Namen vermuten lassen, geben an, dass alle E/A-Vorgänge für die Datei synchron sein sollen, solange sie über das Dateiobjekt erfolgen, auf das vom zurückgegebenen FileHandle verwiesen wird. Alle E/A-Vorgänge in einer solchen Datei werden mithilfe des zurückgegebenen Handles über alle Threads serialisiert. Bei einer dieser CreateOptions muss das DesiredAccess SYNCHRONIZE-Flag festgelegt werden, damit der E/A-Manager das Dateiobjekt als Synchronisierungsobjekt verwendet. Wenn eines dieser CreateOptions festgelegt ist , 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 ZwSetInformationFile abgefragt oder festgelegt werden.

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

Das Flag CreateOptions FILE_OPEN_REQUIRING_OPLOCK entfernt die Zeit zwischen dem Öffnen der Datei und dem Anfordern eines Oplocks, der es einem Drittanbieter möglicherweise ermöglichen könnte, die Datei zu öffnen und einen Freigabeverstoß zu erhalten. Eine Anwendung kann das FILE_OPEN_REQUIRING_OPLOCK-Flag in IoCreateFile verwenden und dann einen beliebigen Oplock anfordern. Dadurch wird sichergestellt, dass ein Oplock-Besitzer über jede spätere offene Anforderung benachrichtigt wird, die einen Verstoß gegen die Freigabe verursacht.

Wenn in Windows 7 andere Handles für die Datei vorhanden sind, wenn eine Anwendung das flag FILE_OPEN_REQUIRING_OPLOCK 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 unterbrechen würde, der bereits für die 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 FILE_OPEN_REQUIRING_OPLOCK-Flag verwendet, muss nach erfolgreichem Aufruf einen Oplock anfordern. Andernfalls werden alle nachfolgenden Versuche zum Öffnen der Datei ohne den Vorteil der normalen Oplockverarbeitung blockiert. Wenn dieser Aufruf erfolgreich ist, aber die nachfolgende oplock-Anforderung fehlschlägt, muss eine Anwendung, die dieses Flag verwendet, ihr Handle schließen, nachdem erkannt wurde, dass die oplock-Anforderung fehlgeschlagen ist.

Das flag 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 Flag in Windows 7 implementieren, sind NTFS, FAT und exFAT.

Das CreateOptions-Flag FILE_RESERVE_OPFILTER ermöglicht es einer Anwendung, einen Oplock der Ebene 1, batch oder filter anzufordern, um zu verhindern, dass andere Anwendungen Freigabeverletzungen erhalten. FILE_RESERVE_OPFILTER ist jedoch nur für Filter oplocks nützlich. Um es verwenden zu können, müssen Sie die folgenden Schritte ausführen:

Stellen Sie eine Create-Anforderung mit CreateOptions von FILE_RESERVE_OPFILTER, DesiredAccess von genau FILE_READ_ATTRIBUTES und ShareAccess von 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 auch der nächste angeforderte Oplock schlägt 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 einen Oplock an.
Öffnen Sie ein weiteres Handle für die Datei, um E/A-Vorgänge zu erledigen.

Schritt 3 macht dies nur für Filter oplocks praktisch. Das in Schritt 3 geöffnete Handle kann einen DesiredAccess-Wert aufweisen, der maximal FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONISIEREN | READ_CONTROL einen Filter oplock nicht zu unterbrechen. Alle DesiredAccess-Werte , die größer als FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE unterbricht einen Oplock der Ebene 1 oder batch und macht das FILE_RESERVE_OPFILTER Flag für diese Oplock-Typen unbrauchbar.

Das Flag Optionen IO_NO_PARAMETER_CHECKING kann nützlich sein, wenn ein Treiber eine Erstellungsanforderung im Kernelmodus im Namen eines Vorgangs ausgibt, der von einer Benutzermodusanwendung initiiert wurde. Da die Anforderung in einem Benutzermoduskontext auftritt, prüft 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. Dieses Flag ermöglicht es dem Aufrufer, dieses Standardverhalten zu überschreiben und die Zugriffsverletzung zu vermeiden.

Wenn der Treiber bei Erstellungsanforderungen, die im Benutzermodus stammen, sowohl IO_NO_PARAMETER_CHECKING als auch IO_FORCE_ACCESS_CHECK im Options-Parameter von IoCreateFile festlegt, sollte er auch OBJ_FORCE_ACCESS_CHECK im ObjectAttributes-Parameter festlegen. Weitere Informationen zu diesem Flag finden Sie im Element Attributes 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 attribut OBJ_KERNEL_HANDLE für den ObjectAttributes-Parameter von IoCreateFile festlegen. Dadurch wird die Verwendung des von IoCreateFile zurückgegebenen Handles auf Prozesse beschränkt, die nur im Kernelmodus ausgeführt werden. Andernfalls kann der Prozess, in dessen Kontext der Treiber ausgeführt wird, auf das Handle zugreifen. 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	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)