NtCreateFile-Funktion (ntifs.h)

Artikel
04/11/2023

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

Syntax

__kernel_entry NTSYSCALLAPI 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, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

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 Standardzugriffsrechten , die für alle Objekttypen definiert sind, kann der Aufrufer jedes der folgenden spezifischen Zugriffsrechte angeben: d. h. Rechte, die für Dateien spezifisch sind.

ACCESS_MASK-Flag	Ermöglicht dem Aufrufer, dies zu tun
FILE_READ_DATA	Liest Daten aus der Datei.
FILE_READ_ATTRIBUTES	Liest die Attribute der Datei. Weitere Informationen finden Sie in der Beschreibung des FileAttributes-Parameters .
FILE_READ_EA	Lesen Sie die erweiterten Attribute (EAs) der Datei. Dieses Flag ist für Geräte- und Zwischentreiber irrelevant.
FILE_WRITE_DATA	Schreiben von Daten in die Datei.
FILE_WRITE_ATTRIBUTES	Schreiben Sie die Attribute der Datei. Weitere Informationen finden Sie in der Beschreibung des FileAttributes-Parameters .
FILE_WRITE_EA	Ändern Sie die erweiterten Attribute (EAs) der Datei. Dieses Flag ist für Geräte- und Zwischentreiber irrelevant.
FILE_APPEND_DATA	Fügen Sie Daten an die Datei an.
FILE_EXECUTE	Verwenden Sie system paging E/A, um Daten aus der Datei in den Arbeitsspeicher zu lesen. Dieses Flag ist für Geräte- und Zwischentreiber irrelevant.

Hinweis

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 auch die folgenden generischen Zugriffsrechte angeben (Rechte, die für alle Objekttypen gelten, wobei die Bedeutung der einzelnen generischen Zugriffsrechte für den Objekttyp spezifisch ist). Generische Zugriffsrechte für Dateiobjekte entsprechen bestimmten Zugriffsrechten, wie in der folgenden Tabelle dargestellt. (Beachten Sie, dass "correspond" "zugeordnet zu" bedeutet und nicht bedeutet, dass der Wert des generischen Rechts "gleich" dem Wert des bitweisen OR seiner spezifischen Rechtezuordnung ist. Der E/A-Manager definiert die tatsächliche Zuordnung.

Generisches Zugriffsrecht	Zuordnung zu diesen spezifischen Zugriffsrechten
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA und SYNCHRONIZE
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA und SYNCHRONIZE
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, FILE_EXECUTE, FILE_READ_ATTRIBUTES und SYNCHRONIZE. Dieser Wert ist für Geräte- und Zwischentreiber irrelevant.
GENERIC_ALL	FILE_ALL_ACCESS

Hinweis

Generische Zugriffsrechte können nur für eine Datei angegeben werden. sie können nicht für ein Verzeichnis angegeben werden.

Einige CreateOptions-Flags erfordern, dass bestimmte Zugriffsflags in DesiredAccess festgelegt werden, wenn NtCreateFile aufgerufen wird. Weitere Informationen finden Sie im CreateOptions-Parameter .

Wenn Sie beispielsweise GENERIC_READ für ein Dateiobjekt angeben, ordnet die Routine diesen Wert der FILE_GENERIC_READ Bitmaske bestimmter Zugriffsrechte zu. In der obigen Tabelle entsprechen die spezifischen Zugriffsrechte, die für GENERIC_READ aufgeführt sind, den Zugriffsflags, die in der FILE_GENERIC_READ Bitmaske enthalten sind( entsprechen jedoch nicht).

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

DesiredAccess-Flag	Ermöglicht dem Aufrufer, dies zu tun
FILE_LIST_DIRECTORY	Listen Sie die Dateien im Verzeichnis auf.
FILE_TRAVERSE	Durchlaufen Sie das Verzeichnis, d. h. fügen Sie das Verzeichnis in den Pfad einer Datei ein.

Weitere Informationen zu Zugriffsrechten finden Sie unter ACCESS_MASK und Zugriffsrechte.

[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 er das attribut OBJ_KERNEL_HANDLE festlegen, wenn initializeObjectAttributes aufgerufen wird.

[out] IoStatusBlock

Ein Zeiger auf eine IO_STATUS_BLOCK-Struktur, die den endgültigen Abschluss status 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 datei enthält, die erstellt oder überschrieben wird. Wenn AllocationSizeNULL ist, wird keine Zuordnungsgröße angegeben. Wenn keine Datei erstellt oder überschrieben wird, wird AllocationSize ignoriert.

[in] FileAttributes

Gibt mindestens ein FILE_ATTRIBUTE_XXX-Flags an, die die Dateiattribute darstellen, die festgelegt werden sollen, wenn Sie eine Datei erstellen oder überschreiben. Der Aufrufer gibt in der Regel FILE_ATTRIBUTE_NORMAL an, die die Standardattribute festlegt. Eine Liste der gültigen FILE_ATTRIBUTE_XXX-Flags finden Sie in der Microsoft Windows SDK dokumentation 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.

ShareAccess-Flag	Ermöglicht es anderen Threads, dies zu tun
FILE_SHARE_READ	Lesen der Datei
FILE_SHARE_WRITE	Schreiben der Datei
FILE_SHARE_DELETE	Löschen der Datei

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 Aktion an, die ausgeführt werden soll, wenn die Datei vorhanden ist oder nicht. CreateDisposition kann einer der Werte in der folgenden Tabelle sein.

CreateDisposition-Wert	Aktion, wenn eine Datei vorhanden ist	Aktion, wenn die Datei nicht vorhanden ist
FILE_SUPERSEDE	Ersetzen Sie die Datei.	Erstellen Sie die Datei.
FILE_CREATE	Gibt einen Fehler zurück.	Erstellen Sie die Datei.
FILE_OPEN	Öffnen Sie die Datei.	Gibt einen Fehler zurück.
FILE_OPEN_IF	Öffnen Sie die Datei.	Erstellen Sie die Datei.
FILE_OVERWRITE	Öffnen Sie die Datei, und überschreiben Sie sie.	Gibt einen Fehler zurück.
FILE_OVERWRITE_IF	Öffnen Sie die Datei, und überschreiben Sie sie.	Erstellen Sie die Datei.

[in] CreateOptions

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

CreateOptions-Flag	Bedeutung
FILE_DIRECTORY_FILE (0x00000001)	Die Datei ist ein Verzeichnis. Kompatible CreateOptions-Flags sind FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT und FILE_OPEN_BY_FILE_ID. Der CreateDisposition-Parameter muss auf FILE_CREATE, FILE_OPEN oder FILE_OPEN_IF festgelegt werden.
FILE_WRITE_THROUGH (0x00000002)	Systemdienste, Dateisystemtreiber und Treiber, die Daten in die Datei schreiben, müssen die Daten tatsächlich in die Datei übertragen, bevor ein angeforderter Schreibvorgang als abgeschlossen betrachtet wird.
FILE_SEQUENTIAL_ONLY (0x00000004)	Der gesamte Zugriff auf die Datei erfolgt sequenziell.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	Die Datei kann nicht in den internen Puffern eines Treibers zwischengespeichert oder gepuffert werden. Dieses Flag ist mit dem FILE_APPEND_DATA Flag des DesiredAccess-Parameters nicht kompatibel.
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	Alle Vorgänge für die Datei werden synchron ausgeführt. Jede Wartezeit im Namen des Anrufers unterliegt der vorzeitigen Beendigung von Warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Dateipositionszeiger beibehält. Wenn dieses Flag festgelegt ist, muss das SYNCHRONIZE-Flag im DesiredAccess-Parameter festgelegt werden.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Alle Vorgänge für die Datei werden synchron ausgeführt. Wartezeiten im System, die E/A-Warteschlangen und Vervollständigung synchronisieren, unterliegen keinen Warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Dateipositionskontext beibehält. Wenn dieses Flag festgelegt ist, muss das SYNCHRONIZE-Flag im DesiredAccess-Parameter festgelegt werden.
FILE_NON_DIRECTORY_FILE (0x00000040)	Die Datei ist kein Verzeichnis. Das zu öffnende Dateiobjekt kann eine Datendatei darstellen. ein logisches, virtuelles oder physisches Gerät; oder ein Volume.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Erstellen Sie eine Strukturverbindung für diese Datei, um sie über das Netzwerk zu öffnen. Dieses Flag wird nicht von Geräte- und Zwischentreibern verwendet.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Schließen Sie diesen Vorgang sofort mit einem alternativen Erfolgscode STATUS_OPLOCK_BREAK_IN_PROGRESS ab, wenn die Zieldatei oplocked ist, anstatt den Thread des Aufrufers zu blockieren. Wenn die Datei oplocked ist, hat ein anderer Aufrufer bereits Zugriff auf die Datei. Dieses Flag wird nicht von Geräte- und Zwischentreibern verwendet.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Wenn die erweiterten Attribute (EAs) für eine vorhandene Datei, die geöffnet wird, angeben, dass der Aufrufer EAs verstehen muss, um die Datei ordnungsgemäß zu interpretieren, sollte NtCreateFile einen Fehler zurückgeben. Dieses Flag ist für Geräte- und Zwischentreiber irrelevant.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Für die Systemnutzung reserviert; nicht verwenden.
FILE_RANDOM_ACCESS (0x00000800)	Der Zugriff auf die Datei kann zufällig erfolgen, sodass keine sequenziellen Read-Ahead-Vorgänge von Dateisystemtreibern oder vom System ausgeführt werden sollten.
FILE_DELETE_ON_CLOSE (0x00001000)	Das System löscht die Datei, wenn das letzte Handle an die Datei an NtClose übergeben wird. Wenn dieses Flag festgelegt ist, muss das DELETE-Flag im DesiredAccess-Parameter festgelegt werden.
FILE_OPEN_BY_FILE_ID (0x00002000)	Der vom ObjectAttributes-Parameter angegebene Dateiname enthält je nach Dateisystem eine binäre 8-Byte- oder 16-Byte-Dateireferenznummer oder Objekt-ID für die Datei. Optional kann ein Gerätename gefolgt von einem umgekehrten Schrägstrich diese Binärwerte fortsetzen. Weitere Details und ein Beispiel finden Sie unter Hinweise.
FILE_OPEN_FOR_BACKUP_INTENT (0x00004000)	Die Datei wird zur Sicherungsabsicht geöffnet. Daher sollte das System bestimmte Zugriffsrechte überprüfen und dem Aufrufer den entsprechenden Zugriff auf die Datei gewähren, bevor der DesiredAccess-Parameter mit der Sicherheitsbeschreibung der Datei überprüft wird. Dieses Flag wird nicht von Geräte- und Zwischentreibern verwendet.
FILE_NO_COMPRESSION (0x00008000)	Unterdrücken der Vererbung von FILE_ATTRIBUTE_COMPRESSED aus dem übergeordneten Verzeichnis. Dies ermöglicht das Erstellen einer nicht komprimierten Datei in einem Verzeichnis, das komprimiert markiert ist.
FILE_OPEN_REQUIRING_OPLOCK (0x00010000)	Die Datei wird geöffnet, und eine opportunistische Sperre (Oplock) für die Datei wird als einzelner atomarer Vorgang angefordert. Das Dateisystem überprüft auf Oplocks, bevor es den Erstellungsvorgang ausführt, und schlägt beim Erstellen mit dem Rückgabecode STATUS_CANNOT_BREAK_OPLOCK fehl, wenn das Ergebnis wäre, einen vorhandenen Oplock zu unterbrechen. Dieses Flag ist ab Windows 7 und Windows Server 2008 R2 verfügbar.
FILE_DISALLOW_EXCLUSIVE (0x00020000)	Wenn beim Öffnen einer vorhandenen Datei FILE_SHARE_READ nicht angegeben ist und die Dateisystemzugriffsprüfungen dem Aufrufer keinen Schreibzugriff auf die Datei gewähren würden, schlägt dies mit STATUS_ACCESS_DENIED geöffnet. Dies war das Standardverhalten vor Windows 7. Dieses Flag ist ab Windows 7 und Windows Server 2008 R2 verfügbar.
FILE_SESSION_AWARE (0x00040000)	Der Client, der die Datei oder das Gerät öffnet, ist sitzungsfähig, und der Zugriff pro Sitzung wird bei Bedarf überprüft. Dieses Flag ist ab Windows 8 verfügbar.
FILE_RESERVE_OPFILTER (0x00100000)	Dieses Flag ermöglicht es einer Anwendung, eine opportunistische Filtersperre (Oplock) anzufordern, um zu verhindern, dass andere Anwendungen Freigabeverletzungen erhalten. Wenn bereits geöffnete Handles vorhanden sind, schlägt die Erstellungsanforderung mit STATUS_OPLOCK_NOT_GRANTED fehl. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
FILE_OPEN_REPARSE_POINT (0x00200000)	Öffnen Sie eine Datei mit einem Analysepunkt, und umgehen Sie die normale Analysepunktverarbeitung für die Datei. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
FILE_OPEN_NO_RECALL (0x00400000)	Weist filter, die Offlinespeicher oder Virtualisierung ausführen, an, den Inhalt der Datei nicht als Ergebnis dieses Öffnens zurückzurufen.
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000)	Dieses Flag weist das Dateisystem an, den Benutzer zu erfassen, der dem aufrufenden Thread zugeordnet ist. Alle nachfolgenden Aufrufe von FltQueryVolumeInformation oder ZwQueryVolumeInformationFile, die das zurückgegebene Handle verwenden, gehen von dem erfassten Benutzer und nicht vom aufrufenden Benutzer zu diesem Zeitpunkt aus, um den freien Speicherplatz zu berechnen, der dem Aufrufer zur Verfügung steht. Dies gilt für die folgenden FsInformationClass-Werte: FileFsSizeInformation, FileFsFullSizeInformation und FileFsFullSizeInformationEx.
FILE_CONTAINS_EXTENDED_CREATE_INFORMATION (0x10000000)	Interpretieren Sie den EaBuffer-Parameter als instance von EXTENDED_CREATE_INFORMATION. Dieses Flag ist ab Windows 11 Version 22H2 verfügbar.

[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

NtCreateFile gibt bei Erfolg STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Fehlercode bei Einem Fehler zurück. Im letzteren Fall kann der Aufrufer die Ursache des Fehlers ermitteln, indem er den IoStatusBlock-Parameter überprüft.

Hinweis

NtCreateFile 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 tritt nur auf, wenn die NTFS-Protokolldatei voll ist und ein Fehler auftritt, während NtCreateFile versucht, diese Situation zu behandeln.

Hinweise

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

Sobald das Handle, auf das von FileHandle verwiesen wird, nicht mehr verwendet wird, muss der Treiber NtClose aufrufen, um es zu schließen.

Wenn der Aufrufer nicht in einem Systemthreadkontext ausgeführt wird, muss sichergestellt werden, dass es sich bei allen von ihr erstellten Handles um private Handles handelt. Andernfalls kann der Prozess, in dessen Kontext der Treiber ausgeführt wird, auf das Handle zugreifen. Weitere Informationen finden Sie unter Objekthandles.

Es gibt zwei alternative Möglichkeiten, den Namen der Datei anzugeben, die mit NtCreateFile 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.

Das Festlegen bestimmter Flags im DesiredAccess-Parameter führt zu den 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 der Aufrufer nur die Flags FILE_APPEND_DATA und SYNCHRONIZE festlegt, kann er nur am 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 das 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 in die Datei lesen oder schreiben, indem er das zurückgegebene FileHandle verwendet. Das heißt, alle Vorgänge für die Datei erfolgen über den System-Pager als Reaktion auf Anweisungen und Datenzugriffsvorgänge. Geräte- und Zwischentreiber sollten das flag FILE_EXECUTE nicht festlegen.

Der ShareAccess-Parameter bestimmt, ob separate Threads möglicherweise 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 NtCreateFile keine 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.

Damit eine freigegebene Datei erfolgreich geöffnet werden kann, müssen die DesiredAccess-Flags mit den DesiredAccess- und ShareAccess-Flags aller vorherigen geöffneten Vorgänge kompatibel sein, die noch nicht über freigegeben wurden. Das heißt, der desiredAccess , der für ntCreateFile für eine bestimmte Datei angegeben wurde, darf keinen Konflikt mit den Zugriffen haben, die andere Öffnende 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 diese Datei bei einem erfolgreichen Aufruf von NtCreateFile 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-Parameter mit 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 CreateDisposition-Werte FILE_OVERWRITE_IF und FILE_SUPERSEDE sind ähnlich. Wenn NtCreateFile mit einer vorhandenen Datei und einem dieser CreateDisposition-Werte 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 NtCreateFile vorhandene FileAttributes-Flags nicht deaktivieren kann, sondern zusätzliche Flags für dieselbe Datei aktivieren kann. Beachten Sie, dass diese Art des Überschreibens von Dateien mit MS-DOS, Microsoft Windows 3.1 und OS/2 konsistent ist.

Der FILE_DIRECTORY_FILE CreateOptions-Wert gibt an, dass die zu erstellende oder zu öffnende 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 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 CreateDisposition-Wert angegeben hat, schlägt der Aufruf von NtCreateFile fehl.

Das FILE_NO_INTERMEDIATE_BUFFERING Flag CreateOptions verhindert, dass das Dateisystem im Auftrag des Aufrufers Zwischenpufferungen ausführt. Wenn Sie dieses Flag angeben, werden die folgenden Einschränkungen für die Parameter des Aufrufers auf andere Zw Xxx-Dateiroutinen festgelegt.

Jedes optionale ByteOffset , das an NtReadFile oder NtWriteFile übergeben wird, muss ein Vielfaches der Sektorgröße sein.
Die anNtReadFile oder NtWriteFile ü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. Um diese Informationen zu erhalten, rufen Sie NtCreateFile auf, um ein Handle für das Dateiobjekt abzurufen, das das physische Gerät darstellt, und übergeben Sie dieses Handle an NtQueryInformationFile. Eine Liste der FILE_XXX_ALIGNMENT-Werte des Systems finden Sie unter DEVICE_OBJECT.
Aufrufe von NtSetInformationFile mit dem FileInformationClass-Parameter , der auf FilePositionInformation festgelegt ist, müssen einen Offset angeben, der ein Vielfaches der Sektorgröße ist.

Die flags FILE_SYNCHRONOUS_IO_ALERT und FILE_SYNCHRONOUS_IO_NONALERT CreateOptions (die sich gegenseitig ausschließen) geben an, dass alle E/A-Vorgänge für die Datei synchron sind, solange die Vorgänge ü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. 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 nach, den Sie an NtReadFile und NtWriteFile übergeben können. Rufen Sie NtQueryInformationFile oder NtSetInformationFile auf, um diese Position abzurufen oder festzulegen.

Wenn das Flag CreateOptions FILE_OPEN_REPARSE_POINT nicht angegeben ist und NtCreateFile 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 NtCreateFile versucht, die Analysepunktdatei direkt zu öffnen. In beiden Fällen gibt NtCreateFile STATUS_SUCCESS zurück, wenn der Öffnenvorgang erfolgreich war. Andernfalls gibt die Routine einen NTSTATUS-Fehlercode zurück. NtCreateFile 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 für NtCreateFile verwenden und dann einen beliebigen 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 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.

Hinweis

Das flag FILE_OPEN_REQUIRING_OPLOCK ist unter Windows 7, Windows Server 2008 R2 und höher unter 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 Level 1-, Batch- oder Filter-Oplock anzufordern, um zu verhindern, dass andere Anwendungen Freigabeverletzungen erhalten. FILE_RESERVE_OPFILTER ist jedoch nur für Filter-Oplocks praktisch 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 auf und unterbricht sie immer noch nicht. Alle DesiredAccess-Werte , die größer als FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE unterbricht einen Level 1- oder Batch-Oplock und macht das FILE_RESERVE_OPFILTER Flag für diese Oplocktypen unbrauchbar.

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

Für das Flag CreateOptions FILE_OPEN_BY_FILE_ID weist ein Beispielgerätename das Format auf:

\??\C:\<FileID>
\device\HardDiskVolume1\<ObjectID>

Wobei FileID 8 Bytes und ObjectID 16 Bytes ist:

Unter NTFS kann dies eine 8-Byte- oder 16-Byte-Referenznummer oder Objekt-ID sein. Eine 16-Byte-Verweisnummer entspricht einer 8-Byte-Zahl, die mit Nullen aufgefüllt ist.
Bei ReFS kann dies eine 8-Byte- oder 16-Byte-Referenznummer sein. Eine 16-Byte-Zahl steht nicht im Zusammenhang mit einer 8-Byte-Zahl. Objekt-IDs werden nicht unterstützt.
Die Dateisysteme FAT, ExFAT, UDFS und CDFS unterstützen das Flag FILE_OPEN_BY_FILE_ID nicht.

Diese Nummer wird von und spezifisch für das jeweilige Dateisystem zugewiesen. Da das Feld "dateiname" teilweise ein binäres Blob enthält, ist es falsch anzunehmen, dass es sich um eine gültige Unicode-Zeichenfolge handelt, und noch wichtiger ist, dass es sich nicht um eine Zeichenfolge mit NULL-Beendigung handelt.

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

Hinweis

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, da sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000
Zielplattform	Universell
Header	ntifs.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt Hinweise)
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis