WriteFile, fonction (fileapi.h)

Écrit des données dans le fichier ou l’appareil d’entrée/sortie (E/S) spécifié.

Cette fonction est conçue pour une opération synchrone et asynchrone. Pour une fonction similaire conçue uniquement pour une opération asynchrone, consultez WriteFileEx.

Syntaxe

BOOL WriteFile(
  [in]                HANDLE       hFile,
  [in]                LPCVOID      lpBuffer,
  [in]                DWORD        nNumberOfBytesToWrite,
  [out, optional]     LPDWORD      lpNumberOfBytesWritten,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Paramètres

[in] hFile

Handle du fichier ou de l’appareil d’E/S (par exemple, un fichier, un flux de fichiers, un disque physique, un volume, une mémoire tampon de console, un lecteur de bande, un socket, une ressource de communication, un maillot ou un canal).

Le paramètre hFile doit avoir été créé avec l’accès en écriture. Pour plus d’informations, consultez droits d’accès génériques et sécurité des fichiers et droits d’accès.

Pour les opérations d’écriture asynchrones, hFile peut être n’importe quel handle ouvert avec la fonction CreateFile à l’aide de l’indicateur de FILE_FLAG_OVERLAPPED ou d’un handle de socket retourné par le socket ou accepter fonction.

[in] lpBuffer

Pointeur vers la mémoire tampon contenant les données à écrire dans le fichier ou l’appareil.

Cette mémoire tampon doit rester valide pendant la durée de l’opération d’écriture. L’appelant ne doit pas utiliser cette mémoire tampon tant que l’opération d’écriture n’est pas terminée.

[in] nNumberOfBytesToWrite

Nombre d’octets à écrire dans le fichier ou l’appareil.

La valeur zéro spécifie une opération d’écriture null. Le comportement d’une opération d’écriture null dépend de la technologie de système de fichiers ou de communication sous-jacente.

Windows Server 2003 et Windows XP : opérations d’écriture de canal sur un réseau sont limitées en taille par écriture. Le montant varie selon la plateforme. Pour les plateformes x86, il s’agit de 63,97 Mo. Pour les plateformes x64, il s’agit de 31,97 Mo. Pour Itanium, il est de 63,95 Mo. Pour plus d’informations sur les canaux, consultez la section Remarques.

[out, optional] lpNumberOfBytesWritten

Pointeur vers la variable qui reçoit le nombre d’octets écrits lors de l’utilisation d’un paramètre hFile synchrone. WriteFile définit cette valeur sur zéro avant d’effectuer une vérification de travail ou d’erreur. Utilisez NULL pour ce paramètre s’il s’agit d’une opération asynchrone pour éviter les résultats potentiellement erronés.

Ce paramètre peut être NULL uniquement lorsque le paramètre lpOverlapped n’est pas NULL.

Windows 7 : Ce paramètre ne peut pas être NULL.

Pour plus d’informations, consultez la section Remarques.

[in, out, optional] lpOverlapped

Un pointeur vers une structure de SUPERPOSÉe est nécessaire si le paramètre hFile a été ouvert avec FILE_FLAG_OVERLAPPED, sinon ce paramètre peut être NULL.

Pour un hFile qui prend en charge les décalages d’octets, si vous utilisez ce paramètre, vous devez spécifier un décalage d’octet à partir duquel commencer l’écriture dans le fichier ou l’appareil. Ce décalage est spécifié en définissant le offset et les membres OffsetHigh de la structure SE CHEVAUCHER. Pour un hFile qui ne prend pas en charge les décalages d’octets, offset et offsetHigh sont ignorés.

Pour écrire à la fin du fichier, spécifiez à la fois les membres offset et OffsetHigh de la structure SE CHEVAUCHER comme 0xFFFFFFFF. Cela équivaut fonctionnellement à appeler la fonction CreateFile pour ouvrir hFile à l’aide d’un accès FILE_APPEND_DATA.

Pour plus d’informations sur différentes combinaisons de lpOverlapped et de FILE_FLAG_OVERLAPPED, consultez la section Remarques et la section Synchronisation et position de fichier.

Valeur de retour

Si la fonction réussit, la valeur de retour est différente de zéro (TRUE).

Si la fonction échoue ou se termine de façon asynchrone, la valeur de retour est égale à zéro (FALSE). Pour obtenir des informations d’erreur étendues, appelez la fonction GetLastError.

Remarques

La fonction WriteFile retourne quand l’une des conditions suivantes se produit :

• Le nombre d’octets demandés est écrit.
• Une opération de lecture libère de l’espace tampon sur la fin de lecture du canal (si l’écriture a été bloquée). Pour plus d’informations, consultez la section Pipes.
• Un handle asynchrone est utilisé et l’écriture se produit de façon asynchrone.
• Une erreur se produit.

Pour annuler toutes les opérations d’E/S asynchrones en attente, utilisez :

• CancelIo: cette fonction annule uniquement les opérations émises par le thread appelant pour le handle de fichier spécifié.
• CancelIoEx: cette fonction annule toutes les opérations émises par les threads pour le handle de fichier spécifié.

Opérations d’E/S annulées avec l’erreur ERROR_OPERATION_ABORTED.

La fonction WriteFile peut échouer avec ERROR_NOT_ENOUGH_QUOTA, ce qui signifie que la mémoire tampon du processus appelant n’a pas pu être verrouillée sur les pages. Pour plus d’informations, consultez SetProcessWorkingSetSize.

Si une partie du fichier est verrouillée par un autre processus et que l’opération d’écriture chevauche la partie verrouillée, WriteFile échoue.

Lors de l’écriture dans un fichier, la dernière heure d’écriture n’est pas entièrement mise à jour tant que tous les handles utilisés pour l’écriture n’ont pas été fermés. Par conséquent, pour garantir une heure d’écriture précise, fermez le handle de fichier immédiatement après l’écriture dans le fichier.

L’accès à la mémoire tampon de sortie pendant qu’une opération d’écriture utilise la mémoire tampon peut entraîner une altération des données écrites à partir de cette mémoire tampon. Les applications ne doivent pas écrire, réallouer ou libérer la mémoire tampon de sortie qu’une opération d’écriture utilise tant que l’opération d’écriture n’est pas terminée. Cela peut être particulièrement problématique lors de l’utilisation d’un handle de fichier asynchrone. Des informations supplémentaires sur les handles de fichiers synchrones et asynchrones sont disponibles plus loin dans la section synchronisation et position de fichier et d’E/S synchrones et asynchrones.

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 nonbuffer.

Le système interprète zéro octets à écrire comme spécifiant une opération d’écriture null et WriteFile ne tronque pas ou n’étend pas le fichier. Pour tronquer ou étendre un fichier, utilisez la fonction SetEndOfFile.

Les caractères peuvent être écrits dans la mémoire tampon d’écran à l’aide de writeFile avec un handle dans la sortie de la console. Le comportement exact de la fonction est déterminé par le mode console. Les données sont écrites à la position actuelle du curseur. La position du curseur est mise à jour après l’opération d’écriture. Pour plus d’informations sur les handles de console, consultez CreateFile.

Lors de l’écriture sur un appareil de communication, le comportement de WriteFile est déterminé par le délai d’attente de communication actuel défini et récupéré à l’aide des fonctions SetCommTimeouts et GetCommTimeouts. Des résultats imprévisibles peuvent se produire si vous ne parvenez pas à définir les valeurs de délai d’attente. Pour plus d’informations sur les délais de communication, consultez COMMTIMEOUTS.

Bien qu’une écriture à secteur unique soit atomique, une écriture multi-secteur n’est pas garantie d’être atomique, sauf si vous utilisez une transaction (autrement dit, le handle créé est un handle transactionné ; par exemple, un handle créé à l’aide de CreateFileTransacted). Les écritures multi-secteurs mises en cache peuvent ne pas toujours être écrites sur le disque immédiatement ; par conséquent, spécifiez FILE_FLAG_WRITE_THROUGH dans CreateFile pour vous assurer qu’une écriture multi-secteur entière est écrite sur le disque sans délai de mise en cache potentielle.

Si vous écrivez directement dans un volume doté d’un système de fichiers monté, vous devez d’abord obtenir un accès exclusif au volume. Sinon, vous risquez de provoquer une altération des données ou une instabilité du système, car les écritures de votre application peuvent entrer en conflit avec d’autres modifications provenant du système de fichiers et laisser le contenu du volume dans un état incohérent. Pour éviter ces problèmes, les modifications suivantes ont été apportées dans Windows Vista et versions ultérieures :

• Une écriture sur un handle de volume réussit si le volume n’a pas de système de fichiers monté ou si l’une des conditions suivantes est remplie :
  • Les secteurs à écrire sont des secteurs de démarrage.
  • Secteurs à écrire pour résider en dehors de l’espace du système de fichiers.
  • Vous avez explicitement verrouillé ou démonté le volume à l’aide de FSCTL_LOCK_VOLUME ou de FSCTL_DISMOUNT_VOLUME.
  • Le volume n’a pas de système de fichiers réel. (En d’autres termes, il a un système de fichiers RAW monté.)
• Une écriture sur un handle de disque réussit si l’une des conditions suivantes est remplie :
  • Les secteurs à écrire ne relèvent pas des étendues d’un volume.
  • Les secteurs à écrire dans un volume monté, mais vous avez explicitement verrouillé ou démonté le volume à l’aide de FSCTL_LOCK_VOLUME ou de FSCTL_DISMOUNT_VOLUME.
  • Les secteurs à écrire dans un volume qui n’a pas de système de fichiers monté autre que RAW.

Si hFile a été ouvert avec FILE_FLAG_OVERLAPPED, les conditions suivantes sont en vigueur :

• Le paramètre lpOverlapped doit pointer vers une structure VALIDE et unique, sinon la fonction peut signaler de manière incorrecte que l’opération d’écriture est terminée.
• Le paramètre lpNumberOfBytesWritten doit être défini sur NULL. Pour obtenir le nombre d’octets écrits, utilisez la fonction GetOverlappedResult. Si le paramètre hFile est associé à un port d’achèvement d’E/S, vous pouvez également obtenir le nombre d’octets écrits en appelant la fonction GetQueuedCompletionStatus.

la synchronisation et la position du fichier

#include <windows.h>

#define ROUND_UP_SIZE(Value,Pow2) ((SIZE_T) ((((ULONG)(Value)) + (Pow2) - 1) & (~(((LONG)(Pow2)) - 1))))

#define ROUND_UP_PTR(Ptr,Pow2)  ((void *) ((((ULONG_PTR)(Ptr)) + (Pow2) - 1) & (~(((LONG_PTR)(Pow2)) - 1))))

int main()
{
   // Sample data
   unsigned long bytesPerSector = 65536; // obtained from the GetFreeDiskSpace function.
   unsigned long size = 15536; // Buffer size of your data to write.
   
   // Ensure you have one more sector than Size would require.
   size_t sizeNeeded = bytesPerSector + ROUND_UP_SIZE(size, bytesPerSector);
   
   // Replace this statement with any allocation routine.
   auto buffer = new uint8_t[SizeNeeded];
   
   // Actual alignment happens here.
   auto bufferAligned = ROUND_UP_PTR(buffer, bytesPerSector);

   // ... Add code using bufferAligned here.
   
   // Replace with corresponding free routine.
   delete buffer;
}