Fonction WriteFile (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 l’opération synchrone et asynchrone. Pour une fonction similaire conçue uniquement pour l’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 vers le fichier ou 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 asynchrone, hFile peut être n’importe quel handle ouvert avec la fonction CreateFile à l’aide de l’indicateur FILE_FLAG_OVERLAPPED ou d’un handle de socket retourné par la fonction socket ou accepter .
[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.
Une valeur de 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 : Les 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 Notes.
[in, out, optional] lpOverlapped
Un pointeur vers une structure QUI SE CHEVAUCHE est requis si le paramètre hFile a été ouvert avec FILE_FLAG_OVERLAPPED, sinon ce paramètre peut être NULL.
Pour un fichier 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 au niveau duquel commencer l’écriture dans le fichier ou l’appareil. Ce décalage est spécifié en définissant les membres Offset et OffsetHigh de la structure CHEVAUCHEMENT . Pour un fichier 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 en tant que 0xFFFFFFFF. Cela équivaut à appeler précédemment la fonction CreateFile pour ouvrir hFile à l’aide de l’accès FILE_APPEND_DATA .
Pour plus d’informations sur différentes combinaisons de lpOverlapped et FILE_FLAG_OVERLAPPED, consultez la section Remarques et la section Synchronisation et Position du fichier .
Valeur retournée
Si la fonction réussit, la valeur de retour est différente de zéro (TRUE).
Si la fonction échoue ou s’effectue 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 l’espace tampon sur la fin de lecture du canal (si l’écriture a été bloquée). Pour plus d’informations, consultez la section Canaux .
- 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 par page. 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 ont été fermés. Par conséquent, pour garantir une dernière 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 dans, réaffecter ou libérer la mémoire tampon de sortie utilisée par une opération d’écriture jusqu’à ce que l’opération d’écriture se termine. 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, ainsi que les 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 non déboguées.
Le système interprète zéro octets à écrire comme spécifiant une opération d’écriture null et WriteFile ne tronque pas ni étend 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 d’WriteFile avec un handle pour 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 d’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 . Les 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 mono-secteur 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 transacted; 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 qui a un système de fichiers monté, vous devez d’abord obtenir un accès exclusif au volume. Sinon, vous risquez d’entraîner une altération des données ou une instabilité du système, car les écritures de votre application peuvent être 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 ultérieurement :
- 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 vraie :
- 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 en utilisant FSCTL_LOCK_VOLUME ou 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 true :
- Les secteurs à écrire ne se trouvent pas dans les étendues d’un volume.
- Les secteurs à écrire doivent se trouver dans un volume monté, mais vous avez explicitement verrouillé ou démonté le volume en utilisant FSCTL_LOCK_VOLUME ou FSCTL_DISMOUNT_VOLUME.
- Les secteurs à écrire doivent se trouver 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 SE CHEVAUCHER 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 .
| Technology | Pris en charge |
|---|---|
| Protocole SMB (Server Message Block) 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 de volume partagé de cluster (CsvFS) | Oui |
| Système de fichiers résilient (ReFS) | Oui |
Synchronisation et position du fichier
Si hFile est ouvert avec FILE_FLAG_OVERLAPPED, il s’agit d’un handle de fichier asynchrone ; sinon, il est synchrone. Les règles d’utilisation de la structure SE CHEVAUCHENT sont légèrement différentes pour chacune d’elles, comme indiqué précédemment.- WriteFile peut retourner avant la fin de l’opération d’écriture. Dans ce scénario, WriteFile retourne FALSE et la fonction GetLastError retourne ERROR_IO_PENDING, ce qui permet au processus appelant de continuer pendant que le système termine l’opération d’écriture.
- Le paramètre lpOverlapped ne doit pas être NULL et doit être utilisé avec les faits suivants à l’esprit :
- Bien que l’événement spécifié dans la structure CHEVAUCHER soit défini et réinitialisé automatiquement par le système, le décalage spécifié dans la structure SE CHEVAUCHER n’est pas automatiquement mis à jour.
- WriteFile réinitialise l’événement à un état non signé lors du début de l’opération d’E/S.
- L’événement spécifié dans la structure CHEVAUCHEMENT EST défini sur un état signalé lorsque l’opération d’écriture est terminée; jusqu’à ce moment-là, l’opération d’écriture est considérée comme en attente.
- Étant donné que l’opération d’écriture commence au décalage spécifié dans la structure SE CHEVAUCHER , et WriteFile peut retourner avant que l’opération d’écriture au niveau du système soit terminée (en attente d’écriture), ni l’offset ni toute autre partie de la structure ne doit être modifié, libéré ou réutilisé par l’application jusqu’à ce que l’événement soit signalé (autrement dit, l’écriture se termine).
- Si lpOverlapped est NULL, l’opération d’écriture démarre à la position de fichier actuelle et WriteFile ne retourne pas tant que l’opération n’est pas terminée, et le système met à jour le pointeur de fichier avant que WriteFile ne retourne.
- Si lpOverlapped n’est pas NULL, l’opération d’écriture commence à l’offset spécifié dans la structure CHEVAUCHEMENTED et WriteFile ne retourne pas tant que l’opération d’écriture n’est pas terminée. Le système met à jour les champs Interne et InternalHigh QUI SE CHEVAUCHEnt et le pointeur de fichier avant que WriteFile ne retourne.
Tuyaux
Si un canal anonyme est utilisé et que le handle de lecture a été fermé, lorsque WriteFile tente d’écrire à l’aide du handle d’écriture correspondant du canal, la fonction retourne FALSE et GetLastError retourne ERROR_BROKEN_PIPE.Si la mémoire tampon de canal est complète lorsqu’une application utilise la fonction WriteFile pour écrire dans un canal, l’opération d’écriture peut ne pas se terminer immédiatement. L’opération d’écriture est terminée lorsqu’une opération de lecture (à l’aide de la fonction ReadFile ) rend plus d’espace de mémoire tampon système disponible pour le canal.
Lors de l’écriture dans un handle de canal en mode octet avec un espace tampon insuffisant, WriteFile retourne TRUE avec *lpNumberOfBytesWritten<nNumberOfBytesToWrite.
Pour plus d’informations sur les canaux, consultez Canaux.
Opérations transactionnelles
S’il existe une transaction liée au handle de fichier, l’écriture du fichier est traitée. Pour plus d’informations, consultez À propos de NTFS transactionnel.Exemples
Pour obtenir des exemples, consultez Création et utilisation d’un fichier temporaire etouverture d’un fichier pour la lecture ou l’écriture.
L’exemple C++ suivant montre comment aligner les secteurs pour les écritures de fichiers non déboguées. La variable Taille est la taille du bloc de données d’origine que vous souhaitez écrire dans le fichier. Pour obtenir des règles supplémentaires concernant les E/S de fichiers non débogués, consultez Mise en mémoire tampon des fichiers.#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;
}
Spécifications
| Client minimal pris en charge | Windows XP [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| Plateforme cible | Windows |
| En-tête | fileapi.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |