SetFileAttributesA-Funktion (fileapi.h)

Artikel
06/02/2023

Legt die Attribute für eine Datei oder ein Verzeichnis fest.

Um diesen Vorgang als transaktionierten Vorgang auszuführen, verwenden Sie die SetFileAttributesTransacted-Funktion .

Syntax

BOOL SetFileAttributesA(
  [in] LPCSTR lpFileName,
  [in] DWORD  dwFileAttributes
);

Parameter

[in] lpFileName

Der Name der Datei, deren Attribute festgelegt werden sollen.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um diesen Grenzwert auf 32.767 Breitzeichen zu erweitern, stellen Sie dem Pfad "\\?\" voran. 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 aufheben, ohne "\\?\" vorab ausstehen zu müssen. Ausführliche Informationen finden Sie im Abschnitt "Maximale Längenbeschränkung für Pfade" unter Benennen von Dateien, Pfaden und Namespaces .

[in] dwFileAttributes

Die Dateiattribute, die für die Datei festgelegt werden sollen.

Dieser Parameter kann ein oder mehrere Werte sein, kombiniert mit dem bitweisen OR-Operator. Alle anderen Werte überschreiben jedoch FILE_ATTRIBUTE_NORMAL.

Nicht alle Attribute werden von dieser Funktion unterstützt. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

Im Folgenden ist eine Liste der unterstützten Attributwerte aufgeführt.

Wert	Bedeutung
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	Eine Datei oder ein Verzeichnis, bei dem es sich um eine Archivdatei oder ein Verzeichnis handelt. Anwendungen verwenden dieses Attribut in der Regel, um Dateien für die Sicherung oder Entfernung zu markieren.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	Die Datei oder das Verzeichnis ist ausgeblendet. Es ist nicht in einer gewöhnlichen Verzeichnisauflistung enthalten.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	Eine Datei, für die keine anderen Attribute festgelegt sind. Dieses Attribut ist nur gültig, wenn es allein verwendet wird.
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 8192 (0x2000)	Die Datei oder das Verzeichnis darf nicht vom Inhaltsindizierungsdienst indiziert werden.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	Die Daten einer Datei sind nicht sofort verfügbar. Dieses Attribut gibt an, dass die Dateidaten physisch in den Offlinespeicher verschoben werden. Dieses Attribut wird vom Remotespeicher verwendet, der hierarchischen Speicherverwaltungssoftware. Anwendungen sollten dieses Attribut nicht willkürlich ändern.
FILE_ATTRIBUTE_READONLY 1 (0x1)	Eine datei, die schreibgeschützt ist. Anwendungen können die Datei lesen, aber nicht in sie schreiben oder löschen. Dieses Attribut wird in Verzeichnissen nicht berücksichtigt. Weitere Informationen finden Sie unter "Sie können die schreibgeschützten oder Systemattribute von Ordnern in Windows Server 2003, Windows XP oder Windows Vista nicht anzeigen oder ändern.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	Eine Datei oder ein Verzeichnis, von dem das Betriebssystem einen Teil oder ausschließlich verwendet.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	Eine Datei, die für den temporären Speicher verwendet wird. Dateisysteme vermeiden das Zurückschreiben von Daten in den Massenspeicher, wenn genügend Cachespeicher verfügbar ist, da in der Regel eine Anwendung eine temporäre Datei löscht, nachdem das Handle geschlossen wurde. In diesem Szenario kann das System das Schreiben der Daten vollständig vermeiden. Andernfalls werden die Daten geschrieben, nachdem das Handle geschlossen wurde.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Bemerkungen

In der folgenden Tabelle wird beschrieben, wie die Attribute festgelegt werden, die nicht mit SetFileAttributes festgelegt werden können. Eine vollständige Liste aller Dateiattributewerte und deren Beschreibungen finden Sie unter Dateiattributekonstanten.

attribute	Festlegen
FILE_ATTRIBUTE_COMPRESSED 0x800	Um den Komprimierungsstatus einer Datei festzulegen, verwenden Sie die DeviceIoControl-Funktion mit dem vorgang FSCTL_SET_COMPRESSION .
FILE_ATTRIBUTE_DEVICE 0x40	Reserviert; nicht verwenden.
FILE_ATTRIBUTE_DIRECTORY 0x10	Dateien können nicht in Verzeichnisse konvertiert werden. Verwenden Sie zum Erstellen eines Verzeichnisses die Funktion CreateDirectory oder CreateDirectoryEx .
FILE_ATTRIBUTE_ENCRYPTED 0x4000	Verwenden Sie zum Erstellen einer verschlüsselten Datei die CreateFile-Funktion mit dem attribut FILE_ATTRIBUTE_ENCRYPTED . Verwenden Sie die Funktion EncryptFile , um eine vorhandene Datei in eine verschlüsselte Datei zu konvertieren.
FILE_ATTRIBUTE_REPARSE_POINT 0x400	Um einen Analysepunkt einer Datei oder einem Verzeichnis zuzuordnen, verwenden Sie die DeviceIoControl-Funktion mit dem vorgang FSCTL_SET_REPARSE_POINT .
FILE_ATTRIBUTE_SPARSE_FILE 0x200	Um das Sparse-Attribut einer Datei festzulegen, verwenden Sie die DeviceIoControl-Funktion mit dem vorgang FSCTL_SET_SPARSE .

Transaktionierte Vorgänge

Wenn eine Datei zur Änderung in einer Transaktion geöffnet ist, kann kein anderer Thread die Datei zur Änderung öffnen, bis ein Commit für die Transaktion ausgeführt wird. Wenn also ein transaktionsfähiger Thread die Datei zuerst öffnet, erhalten alle nachfolgenden Threads, die versuchen, die Datei zu ändern, bevor die Transaktion committet wird, einen Freigabeverstoß. Wenn ein nicht transaktioniertes Thread die Datei ändert, bevor der transaktionierte Thread dies tut, und die Datei weiterhin geöffnet ist, wenn die Transaktion versucht, sie zu öffnen, empfängt die Transaktion den Fehler ERROR_TRANSACTIONAL_CONFLICT.

In Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Unterstützt
Server Message Block (SMB) 3.0-Protokoll	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Horizontalskalieren von Dateifreigaben (SO)	Ja
Freigegebenes Clustervolume-Dateisystem (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

Beispiele

Ein Beispiel finden Sie unter Abrufen und Ändern von Dateiattributen.

Hinweis

Der fileapi.h-Header definiert SetFileAttributes als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	fileapi.h (Einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll