ZwCreateFile-Funktion (wdm.h)

Die ZwCreateFile-Routine erstellt eine neue Datei oder öffnet eine vorhandene Datei.

Syntax

NTSYSAPI NTSTATUS ZwCreateFile(
  [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, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

Die Parameter

[out] FileHandle

Ein Zeiger auf eine HANDLE-Variable, die ein Handle für die Datei empfängt.

[in] DesiredAccess

Gibt einen ACCESS_MASK Wert an, der den angeforderten Zugriff auf das Objekt bestimmt. Zusätzlich zu den Zugriffsrechten, die für alle Objekttypen definiert sind, kann der Aufrufer eine der folgenden Zugriffsrechte angeben, die spezifisch für Dateien sind.

Geben Sie beim Erstellen oder Öffnen eines Verzeichnisses keine FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA oder FILE_EXECUTE an.

Der Aufrufer kann nur ein generisches Zugriffsrecht( GENERIC_XXX) für eine Datei und kein Verzeichnis angeben. Generische Zugriffsrechte entsprechen bestimmten Zugriffsrechten, wie in der folgenden Tabelle dargestellt.

Wenn Sie z. B. GENERIC_READ für ein Dateiobjekt angeben, ordnet die Routine diesen Wert der FILE_GENERIC_READ Bitmaske bestimmter Zugriffsrechte zu. In der vorstehenden Tabelle entsprechen die speziellen Zugriffsrechte, die für GENERIC_READ aufgeführt sind, den Zugriffskennzeichnungen, die in der FILE_GENERIC_READ Bitmaske enthalten sind.

Wenn die Datei tatsächlich ein Verzeichnis ist, kann der Aufrufer auch die folgenden generischen Zugriffsrechte angeben.

Weitere Informationen zu Zugriffsrechten finden Sie unter ACCESS_MASK.

[in] ObjectAttributes

Ein Zeiger auf eine OBJECT_ATTRIBUTES Struktur, die den Objektnamen und andere Attribute angibt. Verwenden Sie InitializeObjectAttributes , um diese Struktur zu initialisieren. Wenn der Aufrufer nicht in einem Systemthreadkontext ausgeführt wird, muss das attribut OBJ_KERNEL_HANDLE festgelegt werden, wenn initializeObjectAttributes aufgerufen wird.

[out] IoStatusBlock

Ein Zeiger auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und andere Informationen zum angeforderten Vorgang empfängt. Insbesondere erhält das Information-Element einen der folgenden Werte:

• FILE_CREATED

• FILE_OPENED

• FILE_OVERWRITTEN

• FILE_SUPERSEDED

• FILE_EXISTS

• FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Ein Zeiger auf eine LARGE_INTEGER, die die anfängliche Zuordnungsgröße in Byte für eine erstellte oder überschriebene Datei enthält. Wenn "AllocationSize" NULL ist, wird keine Zuordnungsgröße angegeben. Wenn keine Datei erstellt oder überschrieben wird, wird AllocationSize ignoriert.

[in] FileAttributes

Gibt ein oder mehrere FILE_ATTRIBUTE_XXX-Flags an, die die festzulegenden Dateiattribute darstellen, wenn Sie eine Datei erstellen oder überschreiben. Der Aufrufer gibt in der Regel FILE_ATTRIBUTE_NORMAL an, wodurch die Standardattribute festgelegt werden. Eine Liste der gültigen FILE_ATTRIBUTE_XXX-Flags finden Sie in der CreateFile-Routine . Wenn keine Datei erstellt oder überschrieben wird, wird FileAttributes ignoriert.

[in] ShareAccess

Typ des Freigabezugriffs, der als Null oder eine beliebige Kombination der folgenden Flags angegeben wird.

Geräte- und Zwischentreiber legen ShareAccess in der Regel auf Null fest, wodurch der Aufrufer exklusiven Zugriff auf die geöffnete Datei erhält.

[in] CreateDisposition

Gibt die auszuführende Aktion an, wenn die Datei vorhanden ist oder nicht. CreateDisposition kann einer der Werte in der folgenden Tabelle sein.

[in] CreateOptions

Gibt die Optionen an, die angewendet werden sollen, wenn der Treiber die Datei erstellt oder öffnet. Verwenden Sie eine oder mehrere Flags in der folgenden Tabelle.

[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.

Rückgabewert

ZwCreateFile gibt STATUS_SUCCESS bei Erfolg oder einem geeigneten NTSTATUS-Fehlercode beim Fehler zurück. Im letzteren Fall kann der Aufrufer die Ursache des Fehlers ermitteln, indem der IoStatusBlock-Parameter überprüft wird.

ZwCreateFile gibt möglicherweise STATUS_FILE_LOCK_CONFLICT als Rückgabewert oder im Status-Element der IO_STATUS_BLOCK Struktur zurück, auf die der IoStatusBlock-Parameter verweist. Dies würde nur auftreten, wenn die NTFS-Protokolldatei voll ist und ein Fehler auftritt, während ZwCreateFile versucht, diese Situation zu behandeln.

Bemerkungen

ZwCreateFile stellt ein Handle bereit, mit dem der Aufrufer die Daten einer Datei oder den Status und Attribute des Dateiobjekts bearbeiten kann. Weitere Informationen finden Sie unter Verwenden von Dateien in einem Treiber.

Sobald der von FileHandle verwendete Handle nicht mehr verwendet wird, muss der Treiber ZwClose aufrufen, um es zu schließen.

Wenn der Aufrufer nicht in einem Systemthreadkontext ausgeführt wird, muss sichergestellt werden, dass es sich bei den erstellten Handles um private Handles handelt. Andernfalls kann über den Prozess, in dem der Treiber ausgeführt wird, auf das Handle zugegriffen werden kann. Weitere Informationen finden Sie unter Objekthandles.

Es gibt zwei alternative Möglichkeiten, den Namen der zu erstellenden oder mit ZwCreateFile zu öffnenden Datei anzugeben:

1. Als vollqualifizierter Pfadname, der im ObjectName-Element der Eingabe ObjectAttributes angegeben wird.

2. Als Pfadname relativ zur Verzeichnisdatei, die durch das Handle im RootDirectory-Element der eingabe ObjectAttributes dargestellt wird.

Das Festlegen bestimmter Flags im Parameter DesiredAccess führt zu den folgenden Effekten:

• Damit ein Aufrufer einen E/A-Abschluss synchronisieren kann, indem er auf das 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 der Aufrufer nur die Flags FILE_APPEND_DATA und SYNCHRONIZE festlegt, kann er nur an das Ende der Datei schreiben, und alle Offsetinformationen zu Schreibvorgängen in die Datei werden ignoriert. Die Datei wird bei Bedarf für diesen Vorgangstyp automatisch erweitert.

• Durch Festlegen des FILE_WRITE_DATA-Flags für eine Datei kann der Aufrufer auch über das Ende der Datei hinaus schreiben. Auch hier wird die Datei bei Bedarf automatisch erweitert.

• Wenn der Aufrufer nur die flags FILE_EXECUTE und SYNCHRONIZE festlegt, kann er keine Daten direkt mit dem zurückgegebenen FileHandle lesen oder in die Datei schreiben. Das heißt, alle Vorgänge in der Datei erfolgen über den System-Pager als Reaktion auf Anweisungs- und Datenzugriffsvorgänge. Geräte- und Zwischentreiber sollten das FILE_EXECUTE-Flag nicht festlegen.

Der parameter ShareAccess bestimmt, ob separate Threads gleichzeitig auf dieselbe Datei zugreifen können. Sofern beide Aufrufer über die entsprechenden Zugriffsberechtigungen verfügen, kann die Datei erfolgreich geöffnet und freigegeben werden. Wenn der ursprüngliche Aufrufer von ZwCreateFile nicht FILE_SHARE_READ, FILE_SHARE_WRITE oder FILE_SHARE_DELETE angibt, kann kein anderer Aufrufer die Datei öffnen, d. h. dem ursprünglichen Aufrufer wird exklusiver Zugriff gewährt.

Um eine freigegebene Datei erfolgreich zu öffnen, müssen die DesiredAccess-Flags mit den Flags DesiredAccess und ShareAccess aller vorherigen geöffneten Vorgänge kompatibel sein, die noch nicht freigegeben wurden. Das heißt, der für eine bestimmte Datei angegebene DesiredAccess darf nicht mit den Zugriffen in Konflikt stehen, die andere Opener der Datei nicht zugelassen haben.

Der CreateDisposition-Wert FILE_SUPERSEDE erfordert, dass der Aufrufer über DELETE-Zugriff auf ein vorhandenes Dateiobjekt verfügt. Wenn ja, wird ein erfolgreicher Aufruf von ZwCreateFile 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 CreateDisposition-Werte FILE_OVERWRITE_IF und FILE_SUPERSEDE ähneln. Wenn ZwCreateFile mit einer vorhandenen Datei und einem dieser CreateDisposition-Werte aufgerufen wird, 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 im Eingabe-ShareAccess festgelegten FILE_SHARE_WRITE Flag geöffnet wurde.

• Die angegebenen Dateiattribute werden logisch mit den bereits in der Datei gespeicherten Attributen versehen. Dies bedeutet, dass ein nachfolgender Aufrufer von ZwCreateFile vorhandene FileAttributes-Flags nicht deaktivieren kann, wenn die Datei bereits von einem anderen Thread geöffnet wurde, aber zusätzliche Flags für dieselbe Datei aktivieren kann.

Der wert FILE_DIRECTORY_FILE CreateOptions gibt an, dass die zu erstellende oder geöffnete Datei ein Verzeichnis 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 einen inkonsistenten CreateOptions - oder CreateDisposition-Wert angegeben hat, schlägt der Aufruf von ZwCreateFile fehl.

Das FILE_NO_INTERMEDIATE_BUFFERING CreateOptions-Flag verhindert, dass das Dateisystem im Auftrag des Aufrufers zwischenpuffert. Wenn Sie dieses Kennzeichen angeben, werden die folgenden Einschränkungen für die Parameter des Aufrufers auf andere ZwXxxFile-Routinen festgelegt:

• Jedes optionale ByteOffset , das an ZwReadFile oder ZwWriteFile übergeben wird, muss ein Vielfaches der Sektorgröße sein.

• Die länge , die an ZwReadFile oder ZwWriteFile übergeben wird, muss ein integraler Bestandteil 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. Rufen Sie zum Abrufen dieser Informationen ZwCreateFile auf, um ein Handle für das Dateiobjekt abzurufen, das das physische Gerät darstellt, und übergeben Sie dieses Handle an ZwQueryInformationFile. Eine Liste der FILE_XXX_ALIGNMENT werte des Systems finden Sie unter DEVICE_OBJECT.

• Aufrufe an ZwSetInformationFile mit dem Parameter FileInformationClass , der auf FilePositionInformation festgelegt ist, müssen einen Offset angeben, der ein Vielfaches der Sektorgröße ist.

Die FILE_SYNCHRONOUS_IO_ALERT- und FILE_SYNCHRONOUS_IO_NONALERT CreateOptions-Flags , die sich gegenseitig ausschließen, wie ihre Namen vorschlagen, geben an, dass alle E/A-Vorgänge in der Datei synchron sind – sofern sie über das dateiobjekt auftreten, auf das durch das zurückgegebene FileHandle verwiesen wird. Alle E/A-Vorgänge in einer solchen Datei werden über alle Threads serialisiert, indem das zurückgegebene Handle verwendet wird. Wenn eines dieser CreateOptions-Flags festgelegt ist, muss auch das Synchronize DesiredAccess-Flag festgelegt werden, um den E/A-Manager zu zwingen, das Dateiobjekt als Synchronisierungsobjekt zu verwenden. In diesen Fällen verfolgt der E/A-Manager den aktuellen Dateipositionsoffset, den Sie an ZwReadFile und ZwWriteFile übergeben können. Rufen Sie ZwQueryInformationFile oder ZwSetInformationFile auf, um diese Position abzurufen oder festzulegen.

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

Das Flag "CreateOptions " FILE_OPEN_REQUIRING_OPLOCK beseitigt die Zeit 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 in ZwCreateFile verwenden und dann ein beliebiges Oplock anfordern. Dadurch wird sichergestellt, dass ein Oplock-Besitzer über jede nachfolgende 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 FILE_OPEN_REQUIRING_OPLOCK-Flag ist unter Windows 7, Windows Server 2008 R2 und höher unter Windows-Betriebssystemen verfügbar. Die Microsoft-Dateisysteme, die dieses Kennzeichen 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 praktisch nützlich. Um sie zu verwenden, müssen Sie die folgenden Schritte ausführen:

1. Erstellen einer 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 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.

2. Wenn die Erstellungsanforderung erfolgreich ist, fordern Sie ein Oplock an.

3. Ö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 einen DesiredAccess-Wert aufweisen, der maximal FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONISIEREN | READ_CONTROL und trotzdem keinen Filter-Oplock aufheben. Jedoch alle DesiredAccess 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.

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

Aufrufer von ZwCreateFile müssen unter IRQL = PASSIVE_LEVEL und mit speziellen Kernel-APCs ausgeführt werden.

Wenn der Aufruf dieser Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtCreateFile" anstelle von "ZwCreateFile" verwenden.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx und ZwXxx- Versionen einer Windows Native System Services-Routine anders verhalten, wie sie Eingabeparameter behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den NtXxx und ZwXxx- Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.

Anforderungen

Siehe auch

ACCESS_MASK

DEVICE_OBJECT

IO_STATUS_BLOCK

InitializeObjectAttributes

Verwenden von Nt- und Zw-Versionen der systemeigenen Systemdienste-Routinen

ZwClose

ZwOpenFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile

  Opportunistische Sperren

Analysepunkte