NtCreateFile-Funktion (winternl.h)
Erstellt eine neue Datei oder ein neues Verzeichnis, oder öffnet eine vorhandene Datei, ein Gerät, ein Verzeichnis oder ein Volume.
Diese Funktion ist der Benutzermodus, der dem im Windows Driver Kit (WDK) dokumentierten ZwCreateFile--Funktion entspricht.
Syntax
__kernel_entry 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] PVOID EaBuffer,
[in] ULONG EaLength
);
Parameter
[out] FileHandle
Ein Zeiger auf eine Variable, die das Dateihandle empfängt, wenn der Aufruf erfolgreich ist.
[in] DesiredAccess
Der ACCESS_MASK Wert, der den Typ des Zugriffs ausdrückt, den der Aufrufer für die Datei oder das Verzeichnis benötigt. Der Satz systemdefinierter DesiredAccess Flags bestimmt die folgenden spezifischen Zugriffsrechte für Dateiobjekte.
Aufrufer von NtCreateFile- können eine oder eine Kombination der folgenden angeben, möglicherweise mit einem bitweisen ODER mit zusätzlichen kompatiblen Flags aus der vorherigen DesiredAccess Flagsliste für jedes Dateiobjekt, das keine Verzeichnisdatei darstellt.
Der FILE_GENERIC_EXECUTE Wert ist für Geräte- und Zwischentreiber irrelevant.
Die STANDARD_RIGHTS_XXX- sind vordefinierte Systemwerte, die zum Erzwingen der Sicherheit auf Systemobjekten verwendet werden.
Um eine Verzeichnisdatei zu öffnen oder zu erstellen, wie auch mit dem CreateOptions Parameter angegeben, können Aufrufer von NtCreateFile- eine oder eine Kombination der folgenden angeben, möglicherweise eine bitweise ODER mit mindestens einem kompatiblen Flag aus der vorherigen DesiredAccess Flags-Liste.
| Wert | Bedeutung |
|---|---|
|
Dateien im Verzeichnis können aufgelistet werden. |
|
Das Verzeichnis kann durchlaufen werden: d. h. es kann Teil des Pfadnamens einer Datei sein. |
[in] ObjectAttributes
Ein Zeiger auf eine Struktur, die bereits mit InitializeObjectAttributesinitialisiert wurde. Elemente dieser Struktur für ein Dateiobjekt enthalten Folgendes.
| Wert | Bedeutung |
|---|---|
|
Gibt die Anzahl der Bytes von ObjectAttributes bereitgestellten Daten an. Dieser Wert muss mindestens sizeof(OBJECT_ATTRIBUTES) sein. |
|
Gibt optional ein Handle für ein Verzeichnis an, das durch einen vorherigen Aufruf von NtCreateFileabgerufen wird. Wenn dieser Wert NULL-ist, muss der ObjectName Member eine vollqualifizierte Dateispezifikation sein, die den vollständigen Pfad zur Zieldatei enthält. Wenn dieser Wert nichtNULL-ist, gibt das element ObjectName einen Dateinamen relativ zu diesem Verzeichnis an. |
|
Verweist auf eine gepufferte Unicode-Zeichenfolge, die die zu erstellende oder geöffnete Datei benennt. Dieser Wert muss eine vollqualifizierte Dateispezifikation oder der Name eines Geräteobjekts sein, es sei denn, es handelt sich um den Namen einer Datei relativ zum verzeichnis, das durch RootDirectoryangegeben wird. Beispiel: \Device\Floppy1\myfile.dat oder \?? \B:\myfile.dat könnte die vollqualifizierte Dateispezifikation sein, vorausgesetzt, der Diskettentreiber und das Überladen des Dateisystems sind bereits geladen. Weitere Informationen finden Sie unter Dateinamen, Pfade und Namespaces. |
|
Ist eine Reihe von Flags, die die Dateiobjektattribute steuern. Dieser Wert kann null oder OBJ_CASE_INSENSITIVEsein, was angibt, dass der Name-Nachschlagecode die Groß-/Kleinschreibung des ObjectName Members ignorieren sollte, anstatt eine Suche mit exakter Übereinstimmung durchzuführen. Der Wert OBJ_INHERIT ist für Geräte- und Zwischentreiber irrelevant. |
|
Gibt optional einen Sicherheitsdeskriptor an, der auf eine Datei angewendet werden soll. AcLs, die durch einen solchen Sicherheitsdeskriptor angegeben werden, werden nur dann auf die Datei angewendet, wenn sie erstellt wird. Wenn der Wert NULL- ist, wenn eine Datei erstellt wird, ist die in der Datei platzierte ACL dateisystemabhängig; Die meisten Dateisysteme verteilen einen Teil einer solchen ACL aus der übergeordneten Verzeichnisdatei in Kombination mit der Standard-ACL des Aufrufers. Geräte- und Zwischentreiber können dieses Element auf NULL-festlegen. |
|
Gibt die Zugriffsrechte an, die ein Server dem Sicherheitskontext des Clients zugewiesen werden soll. Dieser Wert ist nichtNULL- nur, wenn eine Verbindung mit einem geschützten Server hergestellt wird, sodass der Aufrufer steuern kann, welche Teile des Sicherheitskontexts des Aufrufers dem Server zur Verfügung gestellt werden und ob der Server die Identität des Aufrufers annehmen darf. |
[out] IoStatusBlock
Ein Zeiger auf eine Variable, die den endgültigen Abschlussstatus und Informationen zum angeforderten Vorgang empfängt. Bei rückgabe von NtCreateFileenthält das Information Member einen der folgenden Werte:
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
[in, optional] AllocationSize
Die anfängliche Zuordnungsgröße in Byte für die Datei. Ein Wert ungleich Null hat keine Auswirkung, es sei denn, die Datei wird erstellt, überschrieben oder abgelöst.
[in] FileAttributes
Die Dateiattribute. Explizit angegebene Attribute werden nur angewendet, wenn die Datei erstellt, abgelöst oder in einigen Fällen überschrieben wird. Dieser Wert ist standardmäßig eine FILE_ATTRIBUTE_NORMAL, die durch eine ORed-Kombination aus einer oder mehreren FILE_ATTRIBUTE_xxxx- Flags überschrieben werden kann, die in Wdm.h und NtDdk.h definiert sind. Eine Liste der Flags, die mit NtCreateFile-verwendet werden können, finden Sie unter CreateFile-.
[in] ShareAccess
Der Typ des Freigabezugriffs, den der Aufrufer in der Datei verwenden möchte, als Null oder als eine oder eine Kombination der folgenden Werte.
Weitere Informationen finden Sie im Windows SDK.
[in] CreateDisposition
Gibt an, was zu tun ist, je nachdem, ob die Datei bereits vorhanden ist, als einer der folgenden Werte.
[in] CreateOptions
Die Beim Erstellen oder Öffnen der Datei anzuwendenden Optionen als kompatible Kombination der folgenden Flags.
[in] EaBuffer
Zeiger auf einen EA-Puffer, der zum Übergeben erweiterter Attribute verwendet wird.
[in] EaLength
Länge des EA-Puffers.
Rückgabewert
NtCreateFile- gibt entweder STATUS_SUCCESS oder einen geeigneten Fehlerstatus zurück. Wenn ein Fehlerstatus zurückgegeben wird, kann der Aufrufer weitere Informationen zur Ursache des Fehlers finden, indem er die IoStatusBlock-überprüft. Um diese Überprüfung zu vereinfachen, kann eine Anwendung die makros NT_SUCCESS, NT_ERRORund NT_WARNING verwenden.
Bemerkungen
Das Handle, das von NtCreateFileangegeben wird, kann von nachfolgenden Aufrufen zum Bearbeiten von Daten innerhalb der Datei oder des Zustands oder der Attribute des Dateiobjekts verwendet werden.
Es gibt zwei alternative Möglichkeiten, den Namen der zu erstellenden oder geöffneten Datei mit NtCreateFile-anzugeben:
- Als vollqualifizierter Pfadname, der im ObjectName Member der Eingabe ObjectAttributes-
- Als Pfadname relativ zur Verzeichnisdatei, die durch das Handle im RootDirectory Member der Eingabe ObjectAttributes dargestellt wird
Bestimmte DesiredAccess Flags und Kombinationen von Flags haben folgende Auswirkungen:
- Damit ein Aufrufer einen E/A-Abschluss synchronisieren kann, indem auf das zurückgegebene FileHandle-gewartet wird, muss das flag SYNCHRONIZE festgelegt werden.
- Das Übergeben einer Null an DesiredFlags ist ungültig.
- Wenn nur die FILE_APPEND_DATA und SYNCHRONIZE Flags festgelegt sind, kann der Aufrufer nur an das Ende der Datei schreiben, und alle Offsetinformationen zu Schreibvorgängen in die Datei werden ignoriert. Die Datei wird jedoch bei Bedarf automatisch für diesen Schreibvorgangstyp erweitert.
- Das Festlegen des FILE_WRITE_DATA Flags für eine Datei ermöglicht auch das Auftreten von Schreibvorgängen über das Ende der Datei hinaus. Die Datei wird für diesen Schreibtyp automatisch erweitert.
- Wenn nur die FILE_EXECUTE und SYNCHRONIZE Flags festgelegt sind, kann der Aufrufer keine Daten in der Datei direkt lesen oder schreiben, indem die zurückgegebene FileHandle-verwendet wird, d. h., alle Vorgänge der Datei erfolgen über den System-Pager als Reaktion auf Anweisungen und Datenzugriffe.
Der parameter ShareAccess bestimmt, ob separate Threads gleichzeitig auf dieselbe Datei zugreifen können. Sofern beide Dateiöffner über die Berechtigung verfügen, auf eine Datei auf die angegebene Weise zuzugreifen, kann die Datei erfolgreich geöffnet und freigegeben werden. Wenn der ursprüngliche Aufrufer von NtCreateFile- nicht FILE_SHARE_READ, FILE_SHARE_WRITEoder FILE_SHARE_DELETEangibt, können keine anderen Geöffneten Vorgänge für die Datei ausgeführt werden; d. h., der ursprüngliche Aufrufer erhält exklusiven Zugriff auf die Datei.
Damit eine freigegebene Datei erfolgreich geöffnet werden kann, muss der angeforderte DesiredAccess-Parameter mit der Datei kompatibel sein, sowohl mit der DesiredAccess- als auch mit ShareAccess- Spezifikationen aller vorherigen Öffnen, die noch nicht mit NtClose-veröffentlicht wurden. Das heißt, der DesiredAccess Parameter, der 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-wertFILE_SUPERSEDE erfordert, dass der Aufrufer DELETE Zugriff auf ein vorhandenes Dateiobjekt hat. Wenn ja, wird ein erfolgreicher Aufruf von NtCreateFile mit FILE_SUPERSEDE für eine vorhandene Datei effektiv gelöscht und anschließend erneut 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 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 im Eingabeparameter ShareAccess festgelegt 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 des Überschreibens von Dateien mit MS-DOS, Windows 3.1 und Betriebssystemen/2 konsistent ist.
Der wert CreateOptionsFILE_DIRECTORY_FILE gibt an, dass die zu erstellende oder geöffnete Datei eine Verzeichnisdatei ist. Wenn eine Verzeichnisdatei erstellt wird, erstellt das Dateisystem eine geeignete Struktur auf dem Datenträger, um ein leeres Verzeichnis für die Struktur des jeweiligen Dateisystems auf dem Datenträger darzustellen. Wenn diese Option angegeben wurde und die zu öffnende Datei keine Verzeichnisdatei ist oder wenn der Aufrufer eine inkonsistente CreateOptions- oder CreateDisposition--Wert angegeben hat, schlägt der Aufruf von NtCreateFile fehl.
Das CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING Flag verhindert, dass das Dateisystem im Auftrag des Aufrufers zwischenpuffert. Wenn Sie diesen Wert angeben, werden bestimmte Einschränkungen für die Parameter des Aufrufers auf andere NtXXXFile Routinen festgelegt, einschließlich der folgenden:
- Alle optionalen ByteOffset-, die an die NtReadFile- oder NtWriteFile--Funktion übergeben werden, muss ein Integral der Sektorgröße sein.
- Die Length-, die an NtReadFile oder NtWriteFileübergeben wurde, 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 angepasst werden. Diese Informationen können abgerufen werden, indem sie NtCreateFile- aufrufen, um ein Handle für das Dateiobjekt abzurufen, das das physische Gerät darstellt, und anschließend NtQueryInformationFile mit diesem Handle aufrufen. Eine Liste der System-FILE_XXX-_ALIGNMENT-Werte finden Sie in der Windows SDK-Dokumentation.
- Aufrufe an NtSetInformationFile mit dem parameter FileInformationClass auf FilePositionInformation festgelegt müssen einen Offset angeben, der ein integraler Bereich der Sektorgröße ist.
Wenn der CreateOptions Parameter das flag FILE_OPEN_REPARSE_POINT angibt und NtCreateFile eine Datei mit einem Analysepunkt öffnet, tritt keine normale Analyseverarbeitung auf und NtCreateFile versucht, die Analysepunktdatei direkt zu öffnen. Wenn das FILE_OPEN_REPARSE_POINT Flag nicht angegeben ist, erfolgt die normale Analysepunktverarbeitung für die Datei. Wenn der Öffnenvorgang erfolgreich war, gibt NtCreateFile in beiden Fällen STATUS_SUCCESSzurück; andernfalls ein Fehlercode. Die NtCreateFile--Funktion gibt nie STATUS_REPARSEzurück.
Das CreateOptions- Flag des Parameters FILE_OPEN_REQUIRING_OPLOCK beseitigt den Zeitraum zwischen dem Öffnen der Datei und dem Anfordern eines Oplocks, der es einem Drittanbieter ermöglichen könnte, die Datei zu öffnen, was zu einer Freigabeverletzung führen würde. Eine Anwendung kann das FILE_OPEN_REQUIRING_OPLOCK-Flag mit 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 dieses Flag verwendet, schlägt der Erstellungsvorgang mit STATUS_OPLOCK_NOT_GRANTEDfehl. 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_OPLOCKfehlschlägt. Der vorhandene Oplock wird durch diesen Erstellungsvorgang nicht unterbrochen.
Eine Anwendung, die dieses Flag verwendet, muss einen 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 CreateOptions- Attribut FILE_RESERVE_OPFILTER des Parameters ermöglicht es einer Anwendung, einen Oplock der Ebene 1, batch oder Filter anzufordern, um zu verhindern, dass andere Anwendungen Freigabeverstöße erhalten. In der Praxis ist die FILE_RESERVE_OPFILTER jedoch nur für Filter-Oplocks nützlich. Um sie zu verwenden, müssen Sie die folgenden Schritte ausführen:
- Stellen Sie eine Create-Anforderung mit CreateOptions von FILE_RESERVE_OPFILTER, DesiredAccess genau FILE_READ_ATTRIBUTESaus, und ShareAccess- genau
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE). Mögliche Fehler sind wie folgt:- Wenn bereits geöffnete Handles vorhanden sind, schlägt die Erstellungsanforderung mit STATUS_OPLOCK_NOT_GRANTEDfehl, und der nächste angeforderte Oplock schlägt ebenfalls fehl.
- Wenn Sie mehr Zugriff als FILE_READ_ATTRIBUTES oder weniger Freigabe als
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)öffnen, schlägt die Anforderung mit STATUS_OPLOCK_NOT_GRANTEDfehl.
- Wenn die Erstellungsanforderung erfolgreich ist, fordern Sie ein Oplock an.
- Öffnen Sie ein weiteres Handle für die Datei, um E/A zu erledigen.
(FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL) enthält und trotzdem keinen Filter-Oplock unterbricht. Jedes DesiredAccess- größer als (FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE) unterbricht jedoch einen Oplock der Ebene 1 oder batch und macht das FILE_RESERVE_OPFILTER Flag für diese Oplock-Typen nutzlos.
NTFS ist das einzige Microsoft-Dateisystem, das FILE_RESERVE_OPFILTERimplementiert.
Weitere Informationen zu Oplocks finden Sie unter Opportunistic Locks.
Beachten Sie, dass die WDK-Headerdatei NtDef.h für viele Konstantendefinitionen sowie das InitializeObjectAttributes Makros erforderlich ist. Sie können auch die funktionen LoadLibrary und GetProcAddress verwenden, um dynamisch mit NtDll.dllzu verknüpfen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Fenster |
| Header- | winternl.h |
| Library | ntdll.lib |
| DLL- | ntdll.dll |