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
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
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
Pour écrire à la fin du fichier, spécifiez à la fois les membres offset
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
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 structureVALIDE 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.
| Technologie | Supporté |
|---|---|
| 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 |
| Cluster Shared Volume File System (CsvFS) | Oui |
| Système de fichiers résilient (ReFS) | Oui |
la synchronisation et la 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 de- writeFile peut retourner avant la fin de l’opération d’écriture. Dans ce scénario, WriteFile retourne FAUX 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 de
SE CHEVAUCHER soit défini et réinitialisé automatiquement par le système, le décalage spécifié dans la structure SUPERPOSÉE n’est pas automatiquement mis à jour. - WriteFile réinitialise l’événement à un état non signé lorsqu’il démarre l’opération d’E/S.
- L’événement spécifié dans la structure de
SE CHEVAUCHER est défini sur un état signalé lorsque l’opération d’écriture est terminée ; jusqu’à ce stade, l’opération d’écriture est considérée comme en attente. - Étant donné que l’opération d’écriture démarre au décalage spécifié dans la structure
SE CHEVAUCHER et que WriteFile peut retourner avant la fin de l’opération d’écriture au niveau du système (écriture en attente), ni le décalage ni toute autre partie de la structure ne doivent être modifiés, libérés ou réutilisés par l’application jusqu’à ce que l’événement soit signalé (autrement dit, l’écriture se termine).
- Bien que l’événement spécifié dans la structure de
- Si lpOverlapped est NULL, l’opération d’écriture commence à la position de fichier actuelle et WriteFile ne retourne pas tant que l’opération n’est pas terminée, et que le système met à jour le pointeur de fichier avant WriteFile retourne.
- Si
lpOverlapped n’est pasNULL, l’opération d’écriture démarre au décalage spécifié dans la structure SE CHEVAUCHER et WriteFile ne retourne pas tant que l’opération d’écriture n’est pas terminée. Le système met à jour les champs SE CHEVAUCHER champs Internal et InternalHigh et le pointeur de fichier avant que WriteFile retourne.
canaux
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 pleine 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 sans espace tampon insuffisant, WriteFile retourne TRUE avec *lpNumberOfBytesWritten<nNumberOfBytesToWrite.
Pour plus d’informations sur les canaux, consultez Pipes.
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 About Transactional NTFS.Exemples
Pour obtenir des exemples, consultez Création et utilisation d’un fichier temporaire et Ouverture d’un fichier pour la lecture ou l’écriture.
L’exemple C++ suivant montre comment aligner les secteurs pour les écritures de fichiers non sauvegardées. La variable Size correspond à 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 chiffrées, consultez de mise en mémoire tampon de 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;
}
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | fileapi.h (include Windows.h) |
| bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |