CreateFileA-Funktion (fileapi.h)
Erstellt oder öffnet eine Datei oder ein E/A-Gerät. Folgende E/A-Geräte werden am häufigsten verwendet: Datei, Dateistream, Verzeichnis, physischer Datenträger, Volume, Konsolenpuffer, Bandlaufwerk, Kommunikationsressource, Mailslot und Pipe. Die Funktion gibt ein Handle zurück, das für den Zugriff auf die Datei oder das Gerät für verschiedene E/A-Typen verwendet werden kann, abhängig von der Datei oder dem Gerät und den angegebenen Flags und Attributen.
Verwenden Sie die CreateFileTransacted-Funktion , um diesen Vorgang als transaktionierten Vorgang auszuführen, der zu einem Handle führt, das für transaktionsfähige E/A-Vorgänge verwendet werden kann.
Syntax
HANDLE CreateFileA(
[in] LPCSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwCreationDisposition,
[in] DWORD dwFlagsAndAttributes,
[in, optional] HANDLE hTemplateFile
);
Parameter
[in] lpFileName
Der Name der Datei oder des Geräts, die erstellt oder geöffnet werden soll. In diesem Namen können Sie schräge Schrägstriche (/) oder umgekehrte Schrägstriche (\) verwenden.
Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um dieses Limit auf 32.767 breite Zeichen zu erweitern, müssen Sie dem Pfad "\\?\" voranstellen. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.
Tipp
Ab Windows 10 Version 1607 können Sie die MAX_PATH-Einschränkung entfernen, ohne "\\?\" vorauszustellen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbegrenzung" unter Benennung von Dateien, Pfaden und Namespaces .
Informationen zu speziellen Gerätenamen finden Sie unter Definieren eines MS-DOS-Gerätenamens.
Geben Sie zum Erstellen eines Dateidatenstroms den Namen der Datei, einen Doppelpunkt und dann den Namen des Datenstroms an. Weitere Informationen finden Sie unter Dateistreams.
[in] dwDesiredAccess
Der angeforderte Zugriff auf die Datei oder das Gerät, der als Lese-, Schreib-, beides oder 0 zusammengefasst werden kann, um keines anzugeben).
Die am häufigsten verwendeten Werte sind GENERIC_READ, GENERIC_WRITE oder beides (GENERIC_READ | GENERIC_WRITE). Weitere Informationen finden Sie unter Generische Zugriffsrechte, Dateisicherheit und Zugriffsrechte, Dateizugriffsrechtkonstanten und ACCESS_MASK.
Wenn dieser Parameter null ist, kann die Anwendung bestimmte Metadaten wie Datei-, Verzeichnis- oder Geräteattribute abfragen, ohne auf diese Datei oder das Gerät zuzugreifen, auch wenn GENERIC_READ Zugriff verweigert worden wäre.
Sie können keinen Zugriffsmodus anfordern, der mit dem Freigabemodus in Konflikt steht, der durch den dwShareMode-Parameter in einer offenen Anforderung angegeben wird, die bereits über ein geöffnetes Handle verfügt.
Weitere Informationen finden Sie im Abschnitt Hinweise zu diesem Thema und Erstellen und Öffnen von Dateien.
[in] dwShareMode
Der angeforderte Freigabemodus der Datei oder des Geräts, der gelesen, geschrieben, beide, gelöscht, alle oder keine (siehe folgende Tabelle) sein kann. Zugriffsanforderungen auf Attribute oder erweiterte Attribute sind von diesem Flag nicht betroffen.
Wenn dieser Parameter null ist und CreateFile erfolgreich ist, kann die Datei oder das Gerät nicht freigegeben und nicht erneut geöffnet werden, bis das Handle für die Datei oder das Gerät geschlossen ist. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
Sie können keinen Freigabemodus anfordern, der mit dem Zugriffsmodus in Konflikt steht, der in einer vorhandenen Anforderung mit einem geöffneten Handle angegeben ist. CreateFile schlägt fehl, und die GetLastError-Funktion gibt ERROR_SHARING_VIOLATION zurück.
Damit ein Prozess eine Datei oder ein Gerät freigeben kann, während die Datei oder das Gerät in einem anderen Prozess geöffnet ist, verwenden Sie eine kompatible Kombination aus mindestens einem der folgenden Werte. Weitere Informationen zu gültigen Kombinationen dieses Parameters mit dem dwDesiredAccess-Parameter finden Sie unter Erstellen und Öffnen von Dateien.
[in, optional] lpSecurityAttributes
Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur , die zwei separate, aber verwandte Datenmember enthält: einen optionalen Sicherheitsdeskriptor und einen booleschen Wert, der bestimmt, ob das zurückgegebene Handle von untergeordneten Prozessen geerbt werden kann.
Dieser Parameter kann NULL sein.
Wenn dieser Parameter NULL ist, kann das von CreateFile zurückgegebene Handle nicht von untergeordneten Prozessen geerbt werden, die die Anwendung möglicherweise erstellt, und die Datei oder das Gerät, das dem zurückgegebenen Handle zugeordnet ist, erhält einen Standardsicherheitsdeskriptor.
Das lpSecurityDescriptor-Element der Struktur gibt einen SECURITY_DESCRIPTOR für eine Datei oder ein Gerät an. Wenn dieses Element NULL ist, wird der Datei oder dem gerät, das dem zurückgegebenen Handle zugeordnet ist, eine Standardsicherheitsbeschreibung zugewiesen.
CreateFile ignoriert den lpSecurityDescriptor-Member beim Öffnen einer vorhandenen Datei oder eines vorhandenen Geräts, verwendet aber weiterhin den bInheritHandle-Member .
Das bInheritHandle-Element der Struktur gibt an, ob das zurückgegebene Handle geerbt werden kann.
Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
[in] dwCreationDisposition
Eine Aktion, die für eine Datei oder ein Gerät ausgeführt werden soll, die vorhanden ist oder nicht vorhanden ist.
Für andere Geräte als Dateien ist dieser Parameter normalerweise auf OPEN_EXISTING festgelegt.
Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
Dieser Parameter muss einer der folgenden Werte sein, die nicht kombiniert werden können:
[in] dwFlagsAndAttributes
Die Datei- oder Geräteattribute und -flags FILE_ATTRIBUTE_NORMAL der häufigste Standardwert für Dateien.
Dieser Parameter kann eine beliebige Kombination der verfügbaren Dateiattribute (FILE_ATTRIBUTE_*) enthalten. Alle anderen Dateiattribute überschreiben FILE_ATTRIBUTE_NORMAL.
Dieser Parameter kann auch Kombinationen von Flags (FILE_FLAG_*) für die Steuerung des Zwischenspeicherverhaltens von Dateien oder Geräten, Zugriffsmodi und anderen Sonderflags enthalten. Diese werden mit beliebigen FILE_ATTRIBUTE_* -Werten kombiniert.
Dieser Parameter kann auch SQOS-Informationen (Security Quality of Service) enthalten, indem er das SECURITY_SQOS_PRESENT-Flag angibt. Zusätzliche Informationen zu SQOS-bezogenen Flags werden in der Tabelle nach den Attributen und Flags-Tabellen angezeigt.
Erweiterte Zugriffsmöglichkeiten auf Dateiattribute finden Sie unter SetFileAttributes. Eine vollständige Liste aller Dateiattribute mit ihren Werten und Beschreibungen finden Sie unter Dateiattributekonstanten.
| attribute | Bedeutung |
|---|---|
|
Die Datei sollte archiviert werden. Anwendungen verwenden dieses Attribut, um Dateien für die Sicherung oder Entfernung zu markieren. |
|
Die Datei oder das Verzeichnis ist verschlüsselt. Bei einer Datei bedeutet dies, dass alle Daten in der Datei verschlüsselt sind. Für ein Verzeichnis bedeutet dies, dass die Verschlüsselung der Standard für neu erstellte Dateien und Unterverzeichnisse ist. Weitere Informationen finden Sie unter Dateiverschlüsselung.
Dieses Flag hat keine Auswirkung, wenn auch FILE_ATTRIBUTE_SYSTEM angegeben wird. Dieses Flag wird in den Windows-Editionen Home, Home Premium, Starter oder ARM nicht unterstützt. |
|
Die Datei ist ausgeblendet. Fügen Sie es nicht in eine normale Verzeichnisliste ein. |
|
Für die Datei sind keine anderen Attribute festgelegt. Dieses Attribut ist nur gültig, wenn es allein verwendet wird. |
|
Die Daten einer Datei sind nicht sofort verfügbar. Dieses Attribut gibt an, dass Dateidaten physisch in den Offlinespeicher verschoben werden. Dieses Attribut wird von Remote storage verwendet, der hierarchischen Speicherverwaltungssoftware. Anwendungen sollten dieses Attribut nicht willkürlich ändern. |
|
Die Datei ist schreibgeschützt. Anwendungen können die Datei lesen, aber nicht in sie schreiben oder löschen. |
|
Die Datei ist Teil oder wird ausschließlich von einem Betriebssystem verwendet. |
|
Die Datei wird für die temporäre Speicherung verwendet.
Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas. |
| Flag | Bedeutung |
|---|---|
|
Die Datei wird für einen Sicherungs- oder Wiederherstellungsvorgang geöffnet oder erstellt. Das System stellt sicher, dass der aufrufende Prozess Dateisicherheitsprüfungen außer Kraft setzt, wenn der Prozess über SE_BACKUP_NAME - und SE_RESTORE_NAME-Berechtigungen verfügt. Weitere Informationen finden Sie unter Ändern von Berechtigungen in einem Token.
Sie müssen dieses Flag festlegen, um ein Handle für ein Verzeichnis abzurufen. Ein Verzeichnishandle kann anstelle eines Dateihandles an einige Funktionen übergeben werden. Weitere Informationen finden Sie im Abschnitt mit Hinweisen. |
|
Die Datei ist sofort zu löschen, nachdem alle ihre Handles geschlossen wurden, einschließlich des angegebenen Handles und aller anderen geöffneten oder duplizierten Handles.
Wenn für eine Datei geöffnete Handles vorhanden sind, schlägt der Aufruf fehl, es sei denn, sie wurden alle mit dem FILE_SHARE_DELETE Freigabemodus geöffnet. Nachfolgende Öffnungsanforderungen für die Datei fehlschlagen, es sei denn, der Freigabemodus FILE_SHARE_DELETE ist angegeben. |
|
Die Datei oder das Gerät wird ohne Systemzwischenspeicherung für Lese- und Schreibvorgänge von Daten geöffnet. Dieses Flag wirkt sich nicht auf die Zwischenspeicherung von Festplatten oder speicherzuordnungen Dateien aus.
Es gibt strenge Anforderungen für die erfolgreiche Arbeit mit Dateien, die mit CreateFile mithilfe des FILE_FLAG_NO_BUFFERING-Flags geöffnet wurden. Weitere Informationen finden Sie unter Dateipufferung. |
|
Die Dateidaten werden angefordert, sollten sich aber weiterhin im Remotespeicher befinden. Es sollte nicht zurück in den lokalen Speicher transportiert werden. Dieses Flag ist für die Verwendung durch Remotespeichersysteme vorgesehen. |
|
Die normale Analysepunktverarbeitung wird nicht durchgeführt. CreateFile versucht, den Analysepunkt zu öffnen. Wenn eine Datei geöffnet wird, wird ein Dateihandle zurückgegeben, unabhängig davon, ob der Filter, der den Analysepunkt steuert, betriebsbereit ist.
Dieses Flag kann nicht mit dem CREATE_ALWAYS-Flag verwendet werden. Wenn die Datei kein Analysepunkt ist, wird dieses Flag ignoriert. Weitere Informationen finden Sie im Abschnitt mit Hinweisen. |
|
Die Datei oder das Gerät wird für asynchrone E/A-Vorgänge geöffnet oder erstellt.
Wenn nachfolgende E/A-Vorgänge für dieses Handle abgeschlossen werden, wird das in der OVERLAPPED-Struktur angegebene Ereignis auf den signalierten Zustand festgelegt. Wenn dieses Flag angegeben ist, kann die Datei für gleichzeitige Lese- und Schreibvorgänge verwendet werden. Wenn dieses Flag nicht angegeben ist, werden E/A-Vorgänge serialisiert, auch wenn die Aufrufe der Lese- und Schreibfunktionen eine OVERLAPPED-Struktur angeben. Informationen zu Überlegungen bei der Verwendung eines mit diesem Flag erstellten Dateihandles finden Sie im Abschnitt Synchrone und asynchrone E/A-Handles dieses Themas. |
|
Der Zugriff erfolgt gemäß POSIX-Regeln. Dies schließt das Zulassen mehrerer Dateien mit Namen ein, die sich nur für den Fall unterscheiden, für Dateisysteme, die diese Benennung unterstützen. Verwenden Sie diese Option vorsichtig, da dateien, die mit diesem Flag erstellt wurden, möglicherweise nicht für Anwendungen zugänglich sind, die für MS-DOS oder 16-Bit-Windows geschrieben wurden. |
|
Der Zugriff ist als zufällig vorgesehen. Das System kann dies als Hinweis zur Optimierung der Zwischenspeicherung von Dateien verwenden.
Dieses Flag hat keine Auswirkung, wenn das Dateisystem zwischengespeicherte E/A- und FILE_FLAG_NO_BUFFERING nicht unterstützt. Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas. |
|
Die Datei oder das Gerät wird mit Sitzungsbewusstsein geöffnet. Wenn dieses Flag nicht angegeben ist, können Geräte pro Sitzung (z. B. ein Gerät mit RemoteFX-USB-Umleitung) nicht von Prozessen geöffnet werden, die in Sitzung 0 ausgeführt werden.
Dieses Flag hat keine Auswirkungen auf Aufrufer, die sich nicht in Sitzung 0 befinden. Dieses Flag wird nur in Servereditionen von Windows unterstützt.
Windows Server 2008 R2 und Windows Server 2008: Dieses Flag wird vor Windows Server 2012 nicht unterstützt. |
|
Der Zugriff soll von Anfang bis Ende sequenziell erfolgen. Das System kann dies als Hinweis zur Optimierung der Zwischenspeicherung von Dateien verwenden.
Dieses Flag sollte nicht verwendet werden, wenn Read-Behind (d. h. umgekehrte Überprüfungen) verwendet wird. Dieses Flag hat keine Auswirkung, wenn das Dateisystem keine zwischengespeicherten E/A- und FILE_FLAG_NO_BUFFERING unterstützt. Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas. |
|
Schreibvorgänge durchlaufen keinen Zwischencache, sie werden direkt auf den Datenträger weitergeleitet.
Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas. |
Der dwFlagsAndAttributes-Parameter kann auch SQOS-Informationen angeben. Weitere Informationen finden Sie unter Identitätswechsel. Wenn die aufrufende Anwendung das SECURITY_SQOS_PRESENT-Flag als Teil von dwFlagsAndAttributes angibt, kann sie auch einen oder mehrere der folgenden Werte enthalten.
[in, optional] hTemplateFile
Ein gültiges Handle für eine Vorlagendatei mit dem zugriffsrecht GENERIC_READ . Die Vorlagendatei stellt Dateiattribute und erweiterte Attribute für die Datei bereit, die erstellt wird.
Dieser Parameter kann NULL sein.
Beim Öffnen einer vorhandenen Datei ignoriert CreateFile diesen Parameter.
Beim Öffnen einer neuen verschlüsselten Datei erbt die Datei die liste der zugriffskontrollberechtigten Elemente aus dem übergeordneten Verzeichnis. Weitere Informationen finden Sie unter Dateiverschlüsselung.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein geöffnetes Handle für die angegebene Datei, das angegebene Gerät, die angegebene Named Pipe oder den angegebenen E-Mail-Slot.
Wenn die Funktion fehlschlägt, ist der Rückgabewert INVALID_HANDLE_VALUE. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Hinweise
CreateFile wurde ursprünglich speziell für die Dateiinteraktion entwickelt, wurde aber seitdem erweitert und erweitert, um die meisten anderen Typen von E/A-Geräten und Mechanismen einzuschließen, die Windows-Entwicklern zur Verfügung stehen. In diesem Abschnitt wird versucht, die verschiedenen Probleme zu behandeln, die Entwickler bei der Verwendung von CreateFile in verschiedenen Kontexten und mit unterschiedlichen E/A-Typen haben können. Der Text versucht, das Wort Datei nur zu verwenden, wenn er sich speziell auf Daten bezieht, die in einer tatsächlichen Datei in einem Dateisystem gespeichert sind. Einige Verwendungen von datei beziehen sich jedoch möglicherweise allgemeiner auf ein E/A-Objekt, das dateiähnliche Mechanismen unterstützt. Diese liberale Verwendung des Begriffs Datei ist aus den zuvor genannten historischen Gründen besonders bei Konstantennamen und Parameternamen verbreitet.
Wenn eine Anwendung das von CreateFile zurückgegebene Objekthandle verwendet, verwenden Sie die CloseHandle-Funktion , um das Handle zu schließen. Dies gibt nicht nur Systemressourcen frei, sondern kann auch einen größeren Einfluss auf Die Freigabe der Datei oder des Geräts und das Committen von Daten auf den Datenträger haben. Einzelheiten werden in diesem Thema nach Bedarf notiert.
Windows Server 2003 und Windows XP: Ein Freigabeverstoß tritt auf, wenn versucht wird, eine Datei oder ein Verzeichnis zum Löschen auf einem Remotecomputer zu öffnen, wenn der Wert des dwDesiredAccess-Parameters das DELETE-Zugriffsflag (0x00010000) ODER mit einem anderen Zugriffsflag ist und die Remotedatei oder das Remoteverzeichnis nicht mit FILE_SHARE_DELETE geöffnet wurde. Um den Freigabeverstoß in diesem Szenario zu vermeiden, öffnen Sie die Remotedatei oder das Remoteverzeichnis nur mit dem Delete-Zugriffsrecht , oder rufen Sie DeleteFile auf , ohne zuerst die Datei oder das Verzeichnis zum Löschen zu öffnen.
Einige Dateisysteme, z. B. das NTFS-Dateisystem, unterstützen die Komprimierung oder Verschlüsselung für einzelne Dateien und Verzeichnisse. Auf Volumes, die über ein eingebundenes Dateisystem mit dieser Unterstützung verfügen, erbt eine neue Datei die Komprimierungs- und Verschlüsselungsattribute ihres Verzeichnisses.
Sie können CreateFile nicht verwenden, um die Komprimierung, Dekomprimierung oder Entschlüsselung für eine Datei oder ein Verzeichnis zu steuern. Weitere Informationen finden Sie unter Erstellen und Öffnen von Dateien, Dateikomprimierung und Dekomprimierung und Dateiverschlüsselung.
Windows Server 2003 und Windows XP: Aus Gründen der Abwärtskompatibilität wendet CreateFile keine Vererbungsregeln an, wenn Sie einen Sicherheitsdeskriptor in lpSecurityAttributes angeben. Zur Unterstützung der Vererbung können Funktionen, die später den Sicherheitsdeskriptor dieser Datei abfragen, heuristisch bestimmen und melden, dass die Vererbung wirksam ist. Weitere Informationen finden Sie unter Automatische Weitergabe von vererbbaren ACEs.
Wie bereits erwähnt, kann das von CreateFile zurückgegebene Handle nicht von untergeordneten Prozessen geerbt werden, wenn der lpSecurityAttributes-ParameterNULL ist. Die folgenden Informationen zu diesem Parameter gelten ebenfalls:
- Wenn die bInheritHandle-Membervariable nicht FALSE ist, was ein beliebiger Wert ungleich null ist, kann das Handle geerbt werden. Daher ist es wichtig, dass dieser Strukturmember ordnungsgemäß mit FALSE initialisiert wird, wenn Sie nicht beabsichtigen, dass das Handle vererbbar ist.
- Die Zugriffssteuerungslisten (Access Control Lists, ACL) in der Standardsicherheitsbeschreibung für eine Datei oder ein Verzeichnis werden vom übergeordneten Verzeichnis geerbt.
- Das Zieldateisystem muss die Sicherheit von Dateien und Verzeichnissen unterstützen, damit der lpSecurityDescriptor-Member auswirkungen kann, was mithilfe von GetVolumeInformation bestimmt werden kann.
| Technologie | Unterstützt |
|---|---|
| SMB 3.0-Protokoll (Server Message Block) | Ja |
| SMB 3.0 Transparent Failover (TFO) | Weitere Informationen finden Sie unter Hinweise. |
| SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) | Weitere Informationen finden Sie unter Hinweise. |
| Dateisystem mit freigegebenen Clustervolumes (CsvFS) | Ja |
| Robustes Dateisystem (Resilient File System, ReFS) | Ja |
Beachten Sie, dass CreateFile mit Ablösungsdisposition fehlschlägt, wenn es für eine Datei ausgeführt wird, in der bereits ein alternativer Datenstrom geöffnet ist.
Verhalten symbolischer Verknüpfungen
Wenn der Aufruf dieser Funktion eine Datei erstellt, gibt es keine Verhaltensänderung. Beachten Sie auch die folgenden Informationen zu FILE_FLAG_OPEN_REPARSE_POINT:-
Wenn FILE_FLAG_OPEN_REPARSE_POINT angegeben ist:
- Wenn eine vorhandene Datei geöffnet wird und es sich um einen symbolischen Link handelt, ist das zurückgegebene Handle ein Handle für den symbolischen Link.
- Wenn TRUNCATE_EXISTING oder FILE_FLAG_DELETE_ON_CLOSE angegeben sind, ist die betroffene Datei ein symbolischer Link.
-
Wenn FILE_FLAG_OPEN_REPARSE_POINT nicht angegeben ist:
- Wenn eine vorhandene Datei geöffnet wird und es sich um einen symbolischen Link handelt, ist das zurückgegebene Handle ein Handle für das Ziel.
- Wenn CREATE_ALWAYS, TRUNCATE_EXISTING oder FILE_FLAG_DELETE_ON_CLOSE angegeben sind, ist die betroffene Datei das Ziel.
Zwischenspeicherungsverhalten
Mehrere der möglichen Werte für den dwFlagsAndAttributes-Parameter werden von CreateFile verwendet, um zu steuern oder zu beeinflussen, wie die dem Handle zugeordneten Daten vom System zwischengespeichert werden. Sie lauten wie folgt:- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
Einige dieser Flags sollten nicht kombiniert werden. Für instance ist die Kombination von FILE_FLAG_RANDOM_ACCESS mit FILE_FLAG_SEQUENTIAL_SCAN selbstbezwingend.
Die Angabe des FILE_FLAG_SEQUENTIAL_SCAN-Flags kann die Leistung für Anwendungen erhöhen, die große Dateien mithilfe des sequenziellen Zugriffs lesen. Die Leistungssteigerung kann für Anwendungen noch deutlicher sein, die große Dateien meist sequenziell lesen, aber gelegentlich über kleine Bytebereiche überspringen. Wenn eine Anwendung den Dateizeiger für den zufälligen Zugriff verschiebt, tritt höchstwahrscheinlich keine optimale Zwischenspeicherungsleistung auf. Der korrekte Betrieb ist jedoch weiterhin gewährleistet.
Die Flags FILE_FLAG_WRITE_THROUGH und FILE_FLAG_NO_BUFFERING sind unabhängig und können kombiniert werden.
Wenn FILE_FLAG_WRITE_THROUGH verwendet wird, aber nicht auch FILE_FLAG_NO_BUFFERING angegeben ist, sodass die Systemzwischenspeicherung wirksam ist, werden die Daten in den Systemcache geschrieben, aber ohne Verzögerung auf den Datenträger geleert.
Wenn beide FILE_FLAG_WRITE_THROUGH und FILE_FLAG_NO_BUFFERING angegeben sind, sodass die Systemzwischenspeicherung nicht wirksam ist, werden die Daten sofort auf den Datenträger geleert, ohne den Windows-Systemcache zu durchlaufen. Das Betriebssystem fordert auch einen Schreibvorgang des lokalen Hardwarecaches der Festplatte auf persistente Medien an.
Eine Durchschreibanforderung über FILE_FLAG_WRITE_THROUGH bewirkt auch, dass NTFS metadatenbezogene Änderungen, z. B. eine Zeitstempelaktualisierung oder einen Umbenennungsvorgang, die sich aus der Verarbeitung der Anforderung ergeben, leert. Aus diesem Grund wird das flag FILE_FLAG_WRITE_THROUGH häufig mit dem flag FILE_FLAG_NO_BUFFERING als Ersatz für den Aufruf der FlushFileBuffers-Funktion nach jedem Schreibvorgang verwendet, was zu unnötigen Leistungseinbußen führen kann. Wenn Sie diese Flags zusammen verwenden, werden diese Strafen vermieden. Allgemeine Informationen zum Zwischenspeichern von Dateien und Metadaten finden Sie unter Zwischenspeichern von Dateien.
Wenn FILE_FLAG_NO_BUFFERING mit FILE_FLAG_OVERLAPPED kombiniert wird, bieten die Flags eine maximale asynchrone Leistung, da die E/A nicht auf den synchronen Vorgängen des Speicher-Managers basiert. Einige E/A-Vorgänge nehmen jedoch mehr Zeit in Anspruch, da die Daten nicht im Cache gespeichert werden. Außerdem können die Dateimetadaten weiterhin zwischengespeichert werden (z. B. beim Erstellen einer leeren Datei). Verwenden Sie die FlushFileBuffers-Funktion , um sicherzustellen, dass die Metadaten auf den Datenträger geleert werden.
Die Angabe des FILE_ATTRIBUTE_TEMPORARY-Attributs bewirkt, dass Dateisysteme das Zurückschreiben von Daten in den Massenspeicher vermeiden, wenn genügend Cachespeicher verfügbar ist, da eine Anwendung eine temporäre Datei löscht, nachdem ein Handle geschlossen wurde. In diesem Fall kann das System das Schreiben der Daten vollständig vermeiden. Obwohl die Datenzwischenspeicherung nicht auf die gleiche Weise wie die zuvor erwähnten Flags direkt gesteuert wird, weist das attribut FILE_ATTRIBUTE_TEMPORARY das System an, so viel wie möglich im Systemcache zu speichern, ohne zu schreiben, und kann daher für bestimmte Anwendungen von Bedenklich sein.
Dateien
Wenn Sie eine Datei umbenennen oder löschen und sie dann kurz danach wiederherstellen, durchsucht das System den Cache nach den wiederherzustellenden Dateiinformationen. Die zwischengespeicherten Informationen umfassen das Kurz-/Lange-Namenspaar und die Erstellungszeit.Wenn Sie CreateFile für eine Datei aufrufen, die aufgrund eines vorherigen Aufrufs von DeleteFile gelöscht wird, schlägt die Funktion fehl. Das Betriebssystem verzögert das Löschen von Dateien, bis alle Handles für die Datei geschlossen sind. GetLastError gibt ERROR_ACCESS_DENIED zurück.
Der dwDesiredAccess-Parameter kann null sein, sodass die Anwendung Dateiattribute abfragen kann, ohne auf die Datei zuzugreifen, wenn die Anwendung mit angemessenen Sicherheitseinstellungen ausgeführt wird. Dies ist nützlich, um zu testen, ob eine Datei vorhanden ist, ohne sie für Lese- und/oder Schreibzugriff zu öffnen, oder um andere Statistiken über die Datei oder das Verzeichnis zu erhalten. Weitere Informationen finden Sie unter Abrufen und Festlegen von Dateiinformationen und GetFileInformationByHandle.
Wenn CREATE_ALWAYS und FILE_ATTRIBUTE_NORMAL angegeben sind, schlägt CreateFile fehl und legt den letzten Fehler auf ERROR_ACCESS_DENIED fest, wenn die Datei vorhanden ist und über das attribut FILE_ATTRIBUTE_HIDDEN oder FILE_ATTRIBUTE_SYSTEM verfügt. Um den Fehler zu vermeiden, geben Sie die gleichen Attribute wie die vorhandene Datei an.
Wenn eine Anwendung eine Datei über ein Netzwerk erstellt, ist es besser, für dwDesiredAccess zu verwendenGENERIC_READ | GENERIC_WRITE, als GENERIC_WRITE allein zu verwenden. Der resultierende Code ist schneller, da der Redirector den Cache-Manager verwenden und weniger SMBs mit mehr Daten senden kann.
Durch diese Kombination wird auch ein Problem vermieden, bei dem das Schreiben in eine Datei in einem Netzwerk gelegentlich ERROR_ACCESS_DENIED zurückgibt.
Weitere Informationen finden Sie unter Erstellen und Öffnen von Dateien.
Synchrone und asynchrone E/A-Handles
CreateFile ermöglicht das Erstellen eines Datei- oder Gerätehandles, das entweder synchron oder asynchron ist. Ein synchrones Handle verhält sich so, dass E/A-Funktionsaufrufe mit diesem Handle blockiert werden, bis sie abgeschlossen sind, während ein asynchrones Dateihandle es ermöglicht, dass das System sofort von E/A-Funktionsaufrufen zurückgibt, unabhängig davon, ob sie den E/A-Vorgang abgeschlossen haben oder nicht. Wie bereits erwähnt, wird dieses synchrone und asynchrone Verhalten bestimmt, indem FILE_FLAG_OVERLAPPED innerhalb des dwFlagsAndAttributes-Parameters angegeben wird. Bei der Verwendung asynchroner E/A-Vorgänge gibt es mehrere Komplexitäten und potenzielle Fallstricke. Weitere Informationen finden Sie unter Synchrone und asynchrone E/A.Dateistreams
Auf NTFS-Dateisystemen können Sie CreateFile verwenden, um separate Streams innerhalb einer Datei zu erstellen. Weitere Informationen finden Sie unter Dateistreams.Verzeichnisse
Eine Anwendung kann kein Verzeichnis mithilfe von CreateFile erstellen, daher ist für diesen Anwendungsfall nur der wert OPEN_EXISTING für dwCreationDisposition gültig. Um ein Verzeichnis zu erstellen, muss die Anwendung CreateDirectory oder CreateDirectoryEx aufrufen.Um ein Verzeichnis mit CreateFile zu öffnen, geben Sie das FILE_FLAG_BACKUP_SEMANTICS-Flag als Teil von dwFlagsAndAttributes an. Entsprechende Sicherheitsüberprüfungen gelten weiterhin, wenn dieses Flag ohne SE_BACKUP_NAME und SE_RESTORE_NAME Berechtigungen verwendet wird.
Wenn Sie CreateFile verwenden, um ein Verzeichnis während der Defragmentierung eines FAT- oder FAT32-Dateisystemvolumes zu öffnen, geben Sie nicht das MAXIMUM_ALLOWED-Zugriffsrecht an. Wenn dies der Fall ist, wird der Zugriff auf das Verzeichnis verweigert. Geben Sie stattdessen das GENERIC_READ Zugriffsrecht an.
Weitere Informationen finden Sie unter Informationen zur Verzeichnisverwaltung.
Physische Datenträger und Volumes
Der direkte Zugriff auf den Datenträger oder auf ein Volume ist eingeschränkt.Windows Server 2003 und Windows XP: Der direkte Zugriff auf den Datenträger oder auf ein Volume ist auf diese Weise nicht eingeschränkt.
Sie können die CreateFile-Funktion verwenden, um ein physisches Laufwerk oder ein Volume zu öffnen, das ein DASD-Handle (Direct Access Storage Device) zurückgibt, das mit der DeviceIoControl-Funktion verwendet werden kann. Dadurch können Sie direkt auf den Datenträger oder das Volume zugreifen, z. B. auf Datenträgermetadaten wie die Partitionstabelle. Dieser Zugriffstyp macht jedoch auch das Laufwerk oder das Volume potenziellen Datenverlusten aus, da ein falscher Schreibvorgang auf einen Datenträger mit diesem Mechanismus den Zugriff auf dessen Inhalt für das Betriebssystem unzugänglich machen könnte. Um die Datenintegrität sicherzustellen, sollten Sie sich mit DeviceIoControl vertraut machen und wie sich andere APIs mit einem direkten Zugriffshandle anders verhalten als mit einem Dateisystemhandle.
Die folgenden Anforderungen müssen erfüllt sein, damit ein solcher Aufruf erfolgreich ist:
- Der Aufrufer muss über Administratorrechte verfügen. Weitere Informationen finden Sie unter Ausführen mit speziellen Berechtigungen.
- Der dwCreationDisposition-Parameter muss über das flag OPEN_EXISTING verfügen.
- Wenn Sie einen Volume- oder Diskettendatenträger öffnen, muss der dwShareMode-Parameter das flag FILE_SHARE_WRITE aufweisen.
| String | Bedeutung |
|---|---|
| "\\.\PhysicalDrive0" | Öffnet das erste physische Laufwerk. |
| "\\.\PhysicalDrive2" | Öffnet das dritte physische Laufwerk. |
Um den Bezeichner des physischen Laufwerks für ein Volume abzurufen, öffnen Sie ein Handle für das Volume, und rufen Sie die DeviceIoControl-Funktion mit IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS auf. Dieser Steuercode gibt die Datenträgernummer und den Offset für jede der Blöcke des Volumes zurück. Ein Volume kann mehrere physische Datenträger umfassen.
Ein Beispiel für das Öffnen eines physischen Laufwerks finden Sie unter Aufrufen von DeviceIoControl.
Beim Öffnen eines Volumes oder Wechselmedienlaufwerks (z. B. eines Diskettenlaufwerks oder eines Flash-Speicher-USB-Laufwerks) sollte die lpFileName-Zeichenfolge die folgende Form aufweisen: "\.\X:". Verwenden Sie keinen nachgestellten umgekehrten Schrägstrich (\), der das Stammverzeichnis eines Laufwerks angibt. Die folgende Tabelle enthält einige Beispiele für Laufwerkszeichenfolgen.
| String | Bedeutung |
|---|---|
| "\\.\A:" | Öffnet Das Diskettenlaufwerk A. |
| "\\.\C:" | Öffnet das C:-Volume. |
| "\\.\C:\" | Öffnet das Dateisystem des Volumes C: |
Sie können ein Volume auch öffnen, indem Sie auf seinen Volumenamen verweisen. Weitere Informationen finden Sie unter Benennen eines Volumes.
Ein Volume enthält mindestens ein eingebundenes Dateisystem. Volumehandles können nach Ermessen des jeweiligen Dateisystems als nicht zwischengespeichert geöffnet werden, auch wenn die Option nicht zwischengespeichert in CreateFile nicht angegeben ist. Sie sollten davon ausgehen, dass alle offenen Microsoft-Dateisysteme das Volume als nicht zwischengespeichert behandeln. Die Einschränkungen für nicht zwischengespeicherte E/A für Dateien gelten auch für Volumes.
Ein Dateisystem erfordert möglicherweise eine Pufferausrichtung, obwohl die Daten nicht zwischengespeichert sind. Wenn beim Öffnen eines Volumes jedoch die Option ohne Zwischenspeicherung angegeben wird, wird die Pufferausrichtung unabhängig vom Dateisystem auf dem Volume erzwungen. Es wird empfohlen, für alle Dateisysteme, die Sie das Volume öffnen, als nicht zwischengespeichert zu behandeln und die nicht zwischengespeicherten E/A-Einschränkungen zu befolgen.
Veränderergerät
Die IOCTL_CHANGER_* -Steuerungscodes für DeviceIoControl akzeptieren ein Handle für ein Veränderergerät. Um ein Veränderergerät zu öffnen, verwenden Sie einen Dateinamen der folgenden Form: "\\.\Changerx", wobei x eine Zahl ist, die angibt, welches Gerät geöffnet werden soll, beginnend mit null. Verwenden Sie den folgenden Dateinamen, um changer device zero in einer Anwendung zu öffnen, die in C oder C++ geschrieben ist: "\\.\Changer0".Bandlaufwerke
Sie können Bandlaufwerke öffnen, indem Sie einen Dateinamen der folgenden Form verwenden: "\\.\TAPEx", wobei x eine Zahl ist, die angibt, welches Laufwerk geöffnet werden soll, beginnend mit Bandlaufwerk 0. Um bandlaufwerk null in einer Anwendung zu öffnen, die in C oder C++ geschrieben ist, verwenden Sie den folgenden Dateinamen: "\\.\TAPE0".Weitere Informationen finden Sie unter Sicherung.
Kommunikationsressourcen
Die CreateFile-Funktion kann ein Handle für eine Kommunikationsressource wie den seriellen Port COM1 erstellen. Für Kommunikationsressourcen muss der dwCreationDisposition-ParameterOPEN_EXISTING, der dwShareMode-Parameter 0 (exklusiver Zugriff) und der hTemplateFile-ParameterNULL sein. Lese-, Schreib- oder Lese-/Schreibzugriff kann angegeben werden, und das Handle kann für überlappende E/A-Vorgänge geöffnet werden.Um eine COM-Portnummer größer als 9 anzugeben, verwenden Sie die folgende Syntax: "\\.\COM10". Diese Syntax funktioniert für alle Portnummern und Hardware, die die Angabe von COM-Portnummern ermöglicht.
Weitere Informationen zur Kommunikation finden Sie unter Kommunikation.
Konsolen
Die CreateFile-Funktion kann ein Handle to Console Input (CONIN$) erstellen. Wenn der Prozess aufgrund von Vererbung oder Duplizierung über ein geöffnetes Handle verfügt, kann er auch ein Handle für den aktiven Bildschirmpuffer (CONOUT$) erstellen. Der aufrufende Prozess muss an eine geerbte oder von der Funktion AllocConsole zugewiesene Konsole angefügt werden. Legen Sie für Konsolenhandles die CreateFile-Parameter wie folgt fest.| Parameter | Wert |
|---|---|
| lpFileName |
Verwenden Sie den CONIN$-Wert, um die Konsoleneingabe anzugeben.
Verwenden Sie den CONOUT$-Wert, um die Konsolenausgabe anzugeben. CONIN$ ruft ein Handle an den Konsoleneingabepuffer ab, auch wenn die SetStdHandle-Funktion das Standardeingabehandle umleitet. Verwenden Sie zum Abrufen des Standardeingabehandles die GetStdHandle-Funktion . CONOUT$ erhält ein Handle an den aktiven Bildschirmpuffer, auch wenn SetStdHandle das Standardausgabehandle umleitet. Verwenden Sie GetStdHandle, um das Standardausgabehandle abzurufen. |
| dwDesiredAccess |
GENERIC_READ | GENERIC_WRITE wird bevorzugt, aber beide können den Zugriff einschränken.
|
| dwShareMode |
Geben Sie beim Öffnen von CONIN$ FILE_SHARE_READ an. Geben Sie beim Öffnen von CONOUT$ FILE_SHARE_WRITE an.
Wenn der aufrufende Prozess die Konsole erbt oder ein untergeordneter Prozess auf die Konsole zugreifen kann, muss dieser Parameter lauten |
| lpSecurityAttributes | Wenn die Konsole geerbt werden soll, muss das bInheritHandle-Element der SECURITY_ATTRIBUTES-StrukturTRUE sein. |
| dwCreationDisposition | Sie sollten OPEN_EXISTING angeben, wenn Sie CreateFile verwenden, um die Konsole zu öffnen. |
| dwFlagsAndAttributes | Ignoriert. |
| hTemplateFile | Ignoriert. |
Die folgende Tabelle zeigt verschiedene Einstellungen von dwDesiredAccess und lpFileName.
| lpFileName | dwDesiredAccess | Ergebnis |
|---|---|---|
| "CON" | GENERIC_READ | Öffnet die Konsole für die Eingabe. |
| "CON" | GENERIC_WRITE | Öffnet die Konsole für die Ausgabe. |
| "CON" | GENERIC_READ | GENERIC_WRITE |
Führt dazu , dass CreateFile fehlschlägt; GetLastError gibt ERROR_FILE_NOT_FOUND zurück. |
Mailslots
Wenn CreateFile das Clientende eines Mailslots öffnet, gibt die Funktion INVALID_HANDLE_VALUE zurück, wenn der maillot-Client versucht, ein lokales maillot zu öffnen, bevor es vom maillot-Server mit der CreateMailSlot-Funktion erstellt wurde.Weitere Informationen finden Sie unter Mailslots.
Rohre
Wenn CreateFile das Clientende einer Named Pipe öffnet, verwendet die Funktion jede instance der benannten Pipe, die sich im Lauschzustand befindet. Der Öffnungsprozess kann das Handle so oft wie erforderlich duplizieren, aber nach dem Öffnen kann die benannte Pipe instance nicht von einem anderen Client geöffnet werden. Der Zugriff, der beim Öffnen einer Pipe angegeben wird, muss mit dem Zugriff kompatibel sein, der im dwOpenMode-Parameter der CreateNamedPipe-Funktion angegeben ist.Wenn die CreateNamedPipe-Funktion auf dem Server vor diesem Vorgang nicht erfolgreich aufgerufen wurde, ist keine Pipe vorhanden, und CreateFile schlägt mit ERROR_FILE_NOT_FOUND fehl.
Wenn mindestens eine aktive Pipe instance vorhanden ist, aber keine Listenerpipes auf dem Server verfügbar sind, was bedeutet, dass alle Pipeinstanzen derzeit verbunden sind, schlägt CreateFile mit ERROR_PIPE_BUSY fehl.
Weitere Informationen finden Sie unter Pipes.
Beispiele
Beispieldateivorgänge werden in den folgenden Themen gezeigt:
- Anfügen einer Datei an eine andere Datei
- Abbrechen ausstehender E/A-Vorgänge
- Erstellen eines untergeordneten Prozesses mit umgeleiteter Eingabe und Ausgabe
- Erstellen und Verwenden einer temporären Datei
- FSCTL_RECALL_FILE
- GetFinalPathNameByHandle
- Sperren und Entsperren von Bytebereichen in Dateien
- Abrufen eines Dateinamens aus einem Dateihandle
- Abrufen von Informationen zur Dateisystemerkennung
- Öffnen einer Datei zum Lesen oder Schreiben
- Abrufen der Last-Write Zeit
- SetFileInformationByHandle
- Überprüfen auf das Ende einer Datei
- Verwenden von Fasern
- Verwenden von Datenströmen
- Durchlaufen eines Puffers mit Änderungsjournaldatensätzen
- Wow64DisableWow64FsRedirection
- Wow64EnableWow64FsRedirection
- Aufrufen von DeviceIoControl
- Konfigurieren einer Kommunikationsressource
- Überwachen von Kommunikationsereignissen
- Verarbeiten einer Anforderung zum Entfernen eines Geräts
Das Arbeiten mit einem Maillot wird unter Schreiben in ein Mailslot gezeigt.
Einen Codeausschnitt für die Bandsicherung finden Sie unter Erstellen einer Sicherungsanwendung.
Hinweis
Der Fileapi.h-Header definiert CreateFile als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | fileapi.h (Einschließen von Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |
Siehe auch
Informationen zur Verzeichnisverwaltung
Informationen zur Volumeverwaltung
Erstellen, Löschen und Verwalten von Dateien
Geräteeingabe- und Ausgabesteuerung (IOCTL)
Komprimierung und Dekomprimierung von Dateien
Dateisicherheit und Zugriffsberechtigungen
Funktionen
Abrufen und Festlegen von Dateiinformationen
Übersichtsthemen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für