FSCTL_SET_SPARSE IOCTL (winioctl.h)

  • Article

Marque le fichier indiqué comme étant partiellement alloué ou non. Dans un fichier partiellement alloué, les grandes plages de zéros peuvent ne pas nécessiter d’allocation disque. L’espace pour les données non nulles est alloué en fonction des besoins à mesure que le fichier est écrit.

Pour effectuer cette opération, appelez la fonction DeviceIoControl avec les paramètres suivants.

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

Remarques

Pour connaître les implications des E/S qui se chevauchent sur cette opération, consultez la section Remarques de DeviceIoControl.

Le code de contrôle FSCTL_SET_SPARSE définit ou efface l’attribut FILE_ATTRIBUTE_SPARSE_FILE du fichier spécifié.

Windows Server 2008 R2, Windows 7, Windows Server 2008 et Windows Vista : Une opération en clair est valide uniquement sur les fichiers qui n’ont plus de régions éparses. L’exécution d’une opération claire sur un fichier avec des régions éparses peut avoir des résultats imprévisibles. Vous pouvez déterminer s’il existe des régions éparses dans un fichier à l’aide du code de contrôle FSCTL_QUERY_ALLOCATED_RANGES .

Si le paramètre lpInBuffer a la valeur NULL, l’opération se comporte comme si le membre SetSparse de la structure FILE_SET_SPARSE_BUFFER était TRUE. En d’autres termes, l’opération définit le fichier sur un fichier partiellement alloué.

Windows Server 2003 et Windows XP : Si une structure FILE_SET_SPARSE_BUFFER est passée dans le paramètre lpInBuffer , la seule valeur valide pour le membre SetSparse est TRUE, ce qui définit le fichier sur un fichier partiellement alloué. Le passage de FALSE dans la structure FILE_SET_SPARSE_BUFFER entraîne l’échec de cet appel de fonction. La seule façon d’effacer cet attribut consiste à remplacer le fichier (par exemple, en appelant la fonction CreateFile avec l’indicateur CREATE_ALWAYS ).

Vous ne pouvez pas créer un fichier partiellement alloué en appelant CreateFile avec FILE_ATTRIBUTE_SPARSE_FILE dans le paramètre dwFlagsAndAttributes . Vous devez utiliser le code de contrôle FSCTL_SET_SPARSE .

Notez que les horodatages peuvent ne pas être mis à jour correctement pour un fichier distant. Pour garantir des résultats cohérents, utilisez des E/S non déboguées.

Dans Windows 8 et Windows Server 2012, ce code est pris en charge par les technologies suivantes.

Technologie Prise en charge
Protocole Server Message Block (SMB) 3.0 Oui
Basculement transparent SMB 3.0 (TFO) Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO) Oui
Système de fichiers du volume partagé de cluster (CsvFS) Voir commentaire
Système de fichiers résilient (ReFS) Oui

Les csvFs effectuent des E/S redirigées pour les fichiers partiellement alloués. CsvFs permet d’éparser le fichier uniquement lorsque le fichier est ouvert exclusivement par un nœud. Le basculement transparent SMB 3.0 ne prend pas en charge l’écriture en mémoire tampon.

Configuration requise

   
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau uniquement]
En-tête winioctl.h (inclure Windows.h)

Voir aussi