Share via

FSCTL_SET_SPARSE IOCTL (winioctl.h)

  • Artikel

Menandai file yang ditunjukkan sebagai jarang atau tidak jarang. Dalam file jarang, rentang besar nol mungkin tidak memerlukan alokasi disk. Ruang untuk data bukan nol akan dialokasikan sesuai kebutuhan saat file ditulis.

Untuk melakukan operasi ini, panggil fungsi DeviceIoControl dengan parameter berikut.

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
);

Keterangan

Untuk implikasi I/O yang tumpang tindih pada operasi ini, lihat bagian Keterangan deviceIoControl.

Kode kontrol FSCTL_SET_SPARSE mengatur atau menghapus atribut FILE_ATTRIBUTE_SPARSE_FILE dari file yang ditentukan.

Windows Server 2008 R2, Windows 7, Windows Server 2008 dan Windows Vista: Operasi yang jelas hanya valid pada file yang tidak lagi memiliki wilayah jarang. Melakukan operasi yang jelas pada file dengan wilayah jarang dapat memiliki hasil yang tidak dapat diprediksi. Anda dapat menentukan apakah ada wilayah jarang dalam file dengan menggunakan kode kontrol FSCTL_QUERY_ALLOCATED_RANGES .

Jika parameter lpInBufferADALAH NULL, operasi akan berperilaku sama seolah-olah anggota SetSparse dari struktur FILE_SET_SPARSE_BUFFERTRUE. Dengan kata lain, operasi mengatur file ke file jarang.

Windows Server 2003 dan Windows XP: Jika struktur FILE_SET_SPARSE_BUFFER diteruskan dalam parameter lpInBuffer , satu-satunya nilai yang valid untuk anggota SetSparse adalah TRUE, yang mengatur file ke file jarang. Meneruskan FALSE dalam struktur FILE_SET_SPARSE_BUFFER akan menyebabkan panggilan fungsi ini gagal. Satu-satunya cara untuk menghapus atribut ini adalah dengan menimpa file (misalnya, dengan memanggil fungsi CreateFile dengan bendera CREATE_ALWAYS ).

Anda tidak dapat membuat file jarang dengan memanggil CreateFile dengan FILE_ATTRIBUTE_SPARSE_FILE di parameter dwFlagsAndAttributes . Anda harus menggunakan kode kontrol FSCTL_SET_SPARSE .

Perhatikan bahwa stempel waktu mungkin tidak diperbarui dengan benar untuk file jarak jauh. Untuk memastikan hasil yang konsisten, gunakan I/O yang tidak dibuffer.

Di Windows 8 dan Windows Server 2012, kode ini didukung oleh teknologi berikut.

Teknologi Didukung
Protokol Server Message Block (SMB) 3.0 Ya
SMB 3.0 Transparent Failover (TFO) Ya
SMB 3.0 dengan Berbagi File Peluasan Skala (SO) Ya
Sistem File Volume Bersama Kluster (CsvFS) Lihat Komentar
Sistem File Tangguh (ReFS) Ya

CsvF akan melakukan IO yang dialihkan untuk file jarang. CsvF memungkinkan pembuatan file jarang hanya ketika file dibuka secara eksklusif oleh node. Failover Transparan SMB 3.0 tidak mendukung penulisan buffer.

Persyaratan

   
Klien minimum yang didukung Windows XP [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2003 [hanya aplikasi desktop]
Header winioctl.h (termasuk Windows.h)

Lihat juga