NtCreateFile-Funktion (ntifs.h)

Artikel
01/23/2025

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 Standard Zugriffsrechten, 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-Kennzeichnung	Ermöglicht dem Aufrufer, dies zu tun
FILE_READ_DATA	Lesen von Daten aus der Datei.
FILE_READ_ATTRIBUTES	Lesen Sie 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 Kennzeichen ist für Geräte- und Zwischentreiber irrelevant.
FILE_WRITE_DATA	Schreiben Sie 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 Kennzeichen ist für Geräte- und Zwischentreiber irrelevant.
FILE_APPEND_DATA	Fügen Sie Daten an die Datei an.
FILE_EXECUTE	Verwenden Sie die System-Auslagerungs-E/A, um Daten aus der Datei in den Arbeitsspeicher zu lesen. Dieses Kennzeichen ist für Geräte- und Zwischentreiber irrelevant.

Anmerkung

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

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

Anmerkung

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

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

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 (jedoch nicht gleich).

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	Listet die Dateien im Verzeichnis auf.
FILE_TRAVERSE	Durchlaufen Sie das Verzeichnis, d. h., das Verzeichnis in den Pfad einer Datei.

Weitere Informationen zu Zugriffsrechten finden Sie unter ACCESS_MASK und Zugriffsberechtigungen.

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

[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 Mitglied 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 AllocationSizeNULL-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 gültiger 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 anderen Threads dies
FILE_SHARE_READ	Lesen der Datei
FILE_SHARE_WRITE	Schreiben der Datei
FILE_SHARE_DELETE	Löschen der Datei

Geräte- und Zwischentreiber legen in der Regel ShareAccess- 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.

CreateDisposition Wert	Aktion, wenn datei vorhanden ist	Aktion, wenn 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 eine oder mehrere 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 parameter CreateDisposition 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 an 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 zwischengespeichert oder in den internen Puffern eines Treibers gepuffert werden. Dieses Flag ist nicht mit dem DesiredAccess-FILE_APPEND_DATA-Flag des Parameters kompatibel.
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	Alle Vorgänge in der Datei werden synchron ausgeführt. Jede Wartezeit im Auftrag des Anrufers unterliegt einer vorzeitigen Kündigung durch Warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Dateipositionszeiger verwaltet. Wenn dieses Flag festgelegt ist, muss das SYNCHRONIZE-Flag im parameter DesiredAccess festgelegt werden.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Alle Vorgänge in der Datei werden synchron ausgeführt. Waits in the system that synchronize I/O queuing and completion are not subject to alerts. Dieses Kennzeichen bewirkt auch, dass das E/A-System den Dateipositionskontext verwaltet. Wenn dieses Flag festgelegt ist, muss das SYNCHRONIZE-Flag im parameter DesiredAccess 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. Ab Windows 11, Version 24H2, berücksichtigt NTFS dieses Kennzeichen jetzt beim Öffnen eines $INDEX_ALLOCATION-Attributs.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Erstellen Sie eine Strukturverbindung für diese Datei, um sie über das Netzwerk zu öffnen. Dieses Kennzeichen wird nicht von Geräte- und Zwischentreibern verwendet.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Schließen Sie diesen Vorgang sofort mit einem alternativen Erfolgscode von 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 Kennzeichen 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 Kennzeichen ist für Geräte- und Zwischentreiber irrelevant.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Reserviert für die Systemnutzung; nicht verwenden.
FILE_RANDOM_ACCESS (0x00000800)	Der Zugriff auf die Datei kann zufällig sein, sodass keine sequenziellen Lese-/Vorlesevorgä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 für die Datei an NtClose-übergeben wird. Wenn dieses Flag festgelegt ist, muss das DELETE-Flag im parameter DesiredAccess festgelegt werden.
FILE_OPEN_BY_FILE_ID (0x00002000)	Der dateiname, der durch den ObjectAttributes Parameter angegeben wird, 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 in den Hinweisen.
FILE_OPEN_FOR_BACKUP_INTENT (0x00004000)	Die Datei wird zur Sicherung geöffnet. Daher sollte das System auf bestimmte Zugriffsrechte prüfen und dem Aufrufer den entsprechenden Zugriff auf die Datei gewähren, bevor der parameter DesiredAccess auf den Sicherheitsdeskriptor der Datei überprüft wird. Dieses Kennzeichen wird von Geräte- und Zwischentreibern nicht verwendet.
FILE_NO_COMPRESSION (0x00008000)	Vererbung von FILE_ATTRIBUTE_COMPRESSED aus dem übergeordneten Verzeichnis unterdrücken. Dies ermöglicht die Erstellung einer nicht komprimierten Datei in einem Verzeichnis, das als komprimiert markiert ist.
FILE_OPEN_REQUIRING_OPLOCK (0x00010000)	Die Datei wird geöffnet, und eine opportunistische Sperre (Oplock) auf der Datei wird als einzelner atomischer Vorgang angefordert. Das Dateisystem sucht vor dem Ausführen des Erstellungsvorgangs nach Oplocks und schlägt die Erstellung mit einem Rückgabecode von STATUS_CANNOT_BREAK_OPLOCK fehl, wenn das Ergebnis ein vorhandenes Oplock unterbrechen würde. Dieses Kennzeichen ist ab Windows 7 und Windows Server 2008 R2 verfügbar.
FILE_DISALLOW_EXCLUSIVE (0x00020000)	Wenn eine vorhandene Datei geöffnet wird, wenn FILE_SHARE_READ nicht angegeben ist und dateisystemzugriffsprüfungen dem Aufrufer keinen Schreibzugriff auf die Datei gewähren würden, schlägt dies mit STATUS_ACCESS_DENIED fehl. Dies war das Standardverhalten vor Windows 7. Dieses Kennzeichen 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 pro Sitzungszugriff wird bei Bedarf überprüft. Dieses Kennzeichen ist ab Windows 8 verfügbar.
FILE_RESERVE_OPFILTER (0x00100000)	Mit dieser Kennzeichnung kann eine Anwendung eine opportunistische Filtersperre (Oplock) anfordern, um zu verhindern, dass andere Anwendungen Verstöße gegen die Freigabe 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 alle Filter an, die Offlinespeicherung oder Virtualisierung ausführen, 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 dem aufrufenden Thread zugeordneten Benutzer zu erfassen. Alle nachfolgenden Aufrufe von FltQueryVolumeInformation oder ZwQueryVolumeInformationFile mithilfe des zurückgegebenen Handles gehen davon aus, dass der erfasste Benutzer anstelle des aufrufenden Benutzers zur Zeit zum Zwecke der Berechnung des freien Speicherplatzes, der für den Aufrufer verfügbar ist, verwendet wird. Dies gilt für die folgenden FsInformationClass-Werte: FileFsSizeInformation, FileFsFullSizeInformation und FileFsFullSizeInformationEx.
FILE_CONTAINS_EXTENDED_CREATE_INFORMATION (0x10000000)	Interpretieren Sie den EaBuffer Parameter als Instanz von EXTENDED_CREATE_INFORMATION. Dieses Kennzeichen ist ab Windows 11, Version 22H2, verfügbar.

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

Rückgabewert

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

Anmerkung

NtCreateFile- kann STATUS_FILE_LOCK_CONFLICT als Rückgabewert oder im Status- Element der IO_STATUS_BLOCK-Struktur zurückgeben, auf das vom IoStatusBlock-Parameter verwiesen wird. Dies tritt nur auf, wenn die NTFS-Protokolldatei voll ist und ein Fehler auftritt, während NtCreateFile- versucht, diese Situation zu behandeln.

Bemerkungen

NtCreateFile 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- darauf verwiesene Handle 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 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 Object Handles.

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

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

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

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 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 mithilfe der zurückgegebenen FileHandle-in die Datei lesen oder 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 NtCreateFile- 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 dem DesiredAccess kompatibel sein und ShareAccess Flags aller vorherigen geöffneten Vorgänge, die noch nicht freigegeben wurden. Das heißt, die DesiredAccess-, die für NtCreateFile- für eine bestimmte Datei angegeben wurde, darf nicht mit den Zugriffen in Konflikt stehen, die andere Öffnende der Datei nicht zugelassen haben.

Der CreateDisposition Werts FILE_SUPERSEDE erfordert, dass der Aufrufer über DELETE-Zugriff auf ein vorhandenes Dateiobjekt verfügt. Wenn ja, wird ein erfolgreicher Aufruf von NtCreateFile 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 NtCreateFile- mit einer vorhandenen Datei aufgerufen wird und einer dieser CreateDisposition- 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 NtCreateFile vorhandene FileAttributes Flags nicht deaktivieren kann, aber zusätzliche Flags für dieselbe Datei aktivieren kann. Beachten Sie, dass diese Art von Überschreiben von Dateien mit MS-DOS, Microsoft Windows 3.1 und OS/2 konsistent ist.

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 eine inkonsistente CreateOptions- oder CreateDisposition--Wert angegeben hat, schlägt der Aufruf von NtCreateFile- 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.

Alle optionalen ByteOffset-, die an NtReadFile- oder NtWriteFile- übergeben werden, müssen ein Vielfaches der Sektorgröße sein.
Die Length-, die an NtReadFile oder NtWriteFile ü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 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 an NtSetInformationFile mit dem Parameter FileInformationClass auf FilePositionInformation festgelegt 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) geben an, dass alle E/A-Vorgänge in der Datei synchron sind, solange die Vorgänge über das dateiobjekt auftreten, auf das durch die 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 das Flag SYNCHRONIZE DesiredAccess auch so festgelegt werden, dass der E/A-Manager das Dateiobjekt als Synchronisierungsobjekt verwendet. In diesen Fällen verfolgt der E/A-Manager den aktuellen Dateipositionsoffset, den Sie an NtReadFile- und NtWriteFile-übergeben können. Rufen Sie NtQueryInformationFile- oder NtSetInformationFile- auf, um diese Position abzurufen oder festzulegen.

Wenn das CreateOptions- FILE_OPEN_REPARSE_POINT Flag nicht angegeben ist und NtCreateFile- 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 NtCreateFile versucht, die Analysepunktdatei direkt zu öffnen. Wenn der Öffnenvorgang erfolgreich war, gibt NtCreateFile- in beiden Fällen STATUS_SUCCESS zurück; andernfalls gibt die Routine einen NTSTATUS-Fehlercode zurück. NtCreateFile- gibt nie STATUS_REPARSE zurück.

Die CreateOptions- FILE_OPEN_REQUIRING_OPLOCK Flag 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 für NtCreateFile- verwenden und dann 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. Die Anwendung darf keinen anderen Dateisystemvorgang für die Datei ausführen, bevor Sie den Oplock anfordern (neben dem Schließen des Dateihandles), andernfalls kann ein Deadlock auftreten.

Anmerkung

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.

Die 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:

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.

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

Für das CreateOptions- FILE_OPEN_BY_FILE_ID Flag weist ein Beispiel für den Gerätenamen das Format auf:

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

dabei beträgt FileID- 8 Byte und ObjectID- 16 Byte:

Bei NTFS kann es sich um eine 8-Byte- oder 16-Byte-Referenznummer oder Objekt-ID handeln. Eine 16-Byte-Bezugsnummer 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 ist nicht mit einer 8-Byte-Zahl verknüpft. Objekt-IDs werden nicht unterstützt.
Die Dateisysteme FAT, ExFAT, UDFS und CDFS unterstützen das FILE_OPEN_BY_FILE_ID Flag nicht.

Diese Nummer wird dem jeweiligen Dateisystem zugewiesen und spezifisch. Da das Dateinamenfeld teilweise ein binäres Blob enthält, ist es falsch, davon auszugehen, dass es sich um eine gültige Unicode-Zeichenfolge handelt, und wichtiger ist, dass es sich möglicherweise nicht um eine null beendete Zeichenfolge handelt.

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

Anmerkung

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

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000
Zielplattform-	Universal
Header-	ntifs.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis