FSCTL_SET_SPARSE IOCTL (winioctl.h)
Markiert die angegebene Datei als Datei mit oder ohne geringer Speicherdichte. In einer Datei mit geringer Speicherdichte ist für große Bereiche von Nullen möglicherweise keine Datenträgerzuordnung erforderlich. Speicherplatz für nichtzero-Daten wird nach Bedarf zugewiesen, wenn die Datei geschrieben wird.
Um diesen Vorgang auszuführen, rufen Sie die Funktion DeviceIoControl mit den folgenden Parametern auf.
BOOL DeviceIoControl(
(HANDLE) hDevice, // handle to a file
FSCTL_SET_SPARSE, // dwIoControlCode
(PFILE_SET_SPARSE_BUFFER) lpInBuffer, // input buffer
(DWORD) nInBufferSize, // size of input buffer
NULL, // lpOutBuffer
0, // nOutBufferSize
(LPDWORD) lpBytesReturned, // number of bytes returned
(LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);
Hinweise
Die Auswirkungen von überlappenden E/A-Vorgängen auf diesen Vorgang finden Sie im Abschnitt Hinweise von DeviceIoControl.
Der FSCTL_SET_SPARSE-Steuerelementcode legt das FILE_ATTRIBUTE_SPARSE_FILE-Attribut der angegebenen Datei fest oder löscht es.
Windows Server 2008 R2, Windows 7, Windows Server 2008 und Windows Vista: Ein eindeutiger Vorgang ist nur für Dateien gültig, die keine Sparsebereiche mehr aufweisen. Das Ausführen eines eindeutigen Vorgangs für eine Datei mit Sparsebereichen kann unvorhersehbare Ergebnisse haben. Sie können bestimmen, ob in einer Datei Sparsebereiche vorhanden sind, indem Sie den FSCTL_QUERY_ALLOCATED_RANGES-Steuerelementcode verwenden.
Wenn der lpInBuffer-ParameterNULL ist, verhält sich der Vorgang genauso, als wäre das SetSparse-Element der FILE_SET_SPARSE_BUFFER Struktur TRUE. Anders ausgedrückt: Der Vorgang legt die Datei auf eine Sparsedatei fest.
Windows Server 2003 und Windows XP: Wenn eine FILE_SET_SPARSE_BUFFER-Struktur im lpInBuffer-Parameter übergeben wird, ist der einzige gültige Wert für das SetSparse-ElementTRUE, wodurch die Datei auf eine Sparsedatei festgelegt wird. Das Übergeben von FALSE in der FILE_SET_SPARSE_BUFFER-Struktur führt dazu, dass dieser Funktionsaufruf fehlschlägt. Die einzige Möglichkeit, dieses Attribut zu löschen, besteht darin, die Datei zu überschreiben (z. B. durch Aufrufen der CreateFile-Funktion mit dem CREATE_ALWAYS Flag).
Sie können keine Sparsedatei erstellen, indem Sie CreateFile mit FILE_ATTRIBUTE_SPARSE_FILE im dwFlagsAndAttributes-Parameter aufrufen. Sie müssen den FSCTL_SET_SPARSE-Steuerelementcode verwenden.
Beachten Sie, dass die Zeitstempel für eine Remotedatei möglicherweise nicht ordnungsgemäß aktualisiert werden. Verwenden Sie nicht gepufferte E/A, um konsistente Ergebnisse zu gewährleisten.
In Windows 8 und Windows Server 2012 wird dieser Code von den folgenden Technologien unterstützt.
| Technologie | Unterstützt |
|---|---|
| SMB 3.0-Protokoll (Server Message Block) | Ja |
| SMB 3.0 Transparent Failover (TFO) | Ja |
| SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) | Ja |
| Dateisystem mit freigegebenen Clustervolumes (CsvFS) | Siehe Kommentar |
| Robustes Dateisystem (Resilient File System, ReFS) | Ja |
CsvFs werden für Sparsedateien umgeleitet. CsvFs ermöglicht das Erstellen von Dateisparse nur, wenn die Datei ausschließlich von einem Knoten geöffnet wird. Das transparente SMB 3.0-Failover unterstützt keine gepufferten Schreibvorgänge.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Kopfzeile | winioctl.h (einschließlich Windows.h) |