Funzione WriteFile (fileapi.h)

Per annullare tutte le operazioni di I/O asincrone in sospeso, usare:

• CancelIo: questa funzione annulla solo le operazioni rilasciate dal thread chiamante per l'handle di file specificato.
• CancelIoEx: questa funzione annulla tutte le operazioni eseguite dai thread per l'handle di file specificato.

Le operazioni di I/O annullate vengono completate con l'errore ERROR_OPERATION_ABORTED.

La funzione WriteFile potrebbe non riuscire con ERROR_NOT_ENOUGH_QUOTA, il che significa che il buffer del processo chiamante non può essere bloccato a pagina. Per altre informazioni, vedere SetProcessWorkingSetSize.

Se parte del file è bloccata da un altro processo e l'operazione di scrittura si sovrappone alla parte bloccata, WriteFile ha esito negativo.

Quando si scrive in un file, l'ultima volta di scrittura non viene aggiornata completamente fino a quando non vengono chiusi tutti gli handle utilizzati per la scrittura. Pertanto, per garantire un'ora dell'ultima scrittura accurata, chiudere l'handle di file immediatamente dopo la scrittura nel file.

L'accesso al buffer di output mentre un'operazione di scrittura usa il buffer può causare il danneggiamento dei dati scritti da tale buffer. Le applicazioni non devono scrivere, riallocare o liberare il buffer di output usato da un'operazione di scrittura fino al completamento dell'operazione di scrittura. Ciò può essere particolarmente problematico quando si usa un handle di file asincrono. Altre informazioni relative agli handle di file sincroni e asincroni sono disponibili più avanti nella sezione sincronizzazione e posizione file e I/O sincrona e asincrona.

Si noti che i timestamp potrebbero non essere aggiornati correttamente per un file remoto. Per garantire risultati coerenti, usare l'I/O senza buffer.

Il sistema interpreta zero byte da scrivere come specifica un'operazione di scrittura Null e WriteFile non tronca o estende il file. Per troncare o estendere un file, usare la funzione SetEndOfFile.

I caratteri possono essere scritti nel buffer dello schermo usando WriteFile con un handle per l'output della console. Il comportamento esatto della funzione è determinato dalla modalità console. I dati sono scritti nella posizione corrente del cursore. La posizione del cursore viene aggiornata dopo l'operazione di scrittura. Per altre informazioni sugli handle della console, vedere CreateFile.

Quando si scrive in un dispositivo di comunicazione, il comportamento di WriteFile viene determinato dal timeout di comunicazione corrente impostato e recuperato usando le funzioni di SetCommTimeouts e GetCommTimeouts. I risultati imprevedibili possono verificarsi se non si impostano i valori di timeout. Per altre informazioni sui timeout delle comunicazioni, vedere COMMTIMEOUTS.

Anche se una scrittura a singolo settore è atomica, non è garantito che una scrittura multiseme sia atomica, a meno che non si usi una transazione, ovvero l'handle creato è un handle transazionale, ad esempio un handle creato usando CreateFileTransacted). Le scritture multi-settore memorizzate nella cache potrebbero non essere sempre scritte sul disco immediatamente; specificare pertanto FILE_FLAG_WRITE_THROUGH in CreateFile per assicurarsi che nel disco venga scritta un'intera scrittura multiseme senza potenziali ritardi nella memorizzazione nella cache.

Se si scrive direttamente in un volume con un file system montato, è prima necessario ottenere l'accesso esclusivo al volume. In caso contrario, si rischia di causare danneggiamento dei dati o instabilità del sistema, perché le scritture dell'applicazione potrebbero entrare in conflitto con altre modifiche provenienti dal file system e lasciare il contenuto del volume in uno stato incoerente. Per evitare questi problemi, sono state apportate le modifiche seguenti in Windows Vista e versioni successive:

• Una scrittura su un handle di volume avrà esito positivo se il volume non dispone di un file system montato o se una delle condizioni seguenti è vera:
  • I settori da scrivere in sono settori di avvio.
  • I settori da scrivere in si trovano all'esterno dello spazio del file system.
  • Il volume è stato bloccato o smontato in modo esplicito usando FSCTL_LOCK_VOLUME o FSCTL_DISMOUNT_VOLUME.
  • Il volume non ha un file system effettivo. In altre parole, ha un file system RAW montato.
• Una scrittura in un handle del disco avrà esito positivo se una delle condizioni seguenti è vera:
  • I settori da scrivere in non rientrano negli extent di un volume.
  • I settori da scrivere in rientrano in un volume montato, ma il volume è stato bloccato o smontato in modo esplicito usando FSCTL_LOCK_VOLUME o FSCTL_DISMOUNT_VOLUME.
  • I settori da scrivere in modo da rientrare in un volume che non dispone di un file system montato diverso da RAW.

Se hFile è stato aperto con FILE_FLAG_OVERLAPPED, sono effettive le condizioni seguenti:

• Il parametro lpOverlapped deve puntare a una struttura di OVERLAPPED valida e univoca. In caso contrario, la funzione può segnalare erroneamente che l'operazione di scrittura è stata completata.
• Il parametro lpNumberOfBytesWritten deve essere impostato su NULL. Per ottenere il numero di byte scritti, usare la funzione getOverlappedResult . Se il parametro hFile è associato a una porta di completamento I/O, è anche possibile ottenere il numero di byte scritti chiamando la funzione GetQueuedCompletionStatus.

sincronizzazione e posizione dei file

• writeFile può restituire prima del completamento dell'operazione di scrittura. In questo scenario, WriteFile restituisce FALSE e la funzione GetLastError restituisce ERROR_IO_PENDING, che consente al processo chiamante di continuare mentre il sistema completa l'operazione di scrittura.
• Il parametro lpOverlapped non deve essere NULL e deve essere usato tenendo presente quanto segue:
  • Anche se l'evento specificato nella struttura OVERLAPPED viene impostato e reimpostato automaticamente dal sistema, l'offset specificato nella struttura OVERLAPPED non viene aggiornato automaticamente.
  • WriteFile reimposta l'evento su uno stato non firmato all'avvio dell'operazione di I/O.
  • L'evento specificato nella struttura OVERLAPPED viene impostato su uno stato segnalato al termine dell'operazione di scrittura; fino a quel momento, l'operazione di scrittura viene considerata in sospeso.
  • Poiché l'operazione di scrittura inizia con l'offset specificato nella struttura OVERLAPPED e WriteFile può restituire prima che l'operazione di scrittura a livello di sistema sia stata completata (scrittura in sospeso), né l'offset né qualsiasi altra parte della struttura deve essere modificato, liberato o riutilizzato dall'applicazione fino a quando l'evento non viene segnalato (ovvero, la scrittura viene completata).

• Se lpOverlapped è NULL, l'operazione di scrittura inizia con la posizione del file corrente e writeFile non restituisce finché l'operazione non viene completata e il sistema aggiorna il puntatore al file prima di WriteFile restituisce.
• Se lpOverlapped non è null, l'operazione di scrittura inizia all'offset specificato nella struttura OVERLAPPED e WriteFile non restituisce fino al completamento dell'operazione di scrittura. Il sistema aggiorna i campi OVERLAPPED Interno e InternoHigh e il puntatore al file prima di WriteFile restituisce.

pipe

Se il buffer della pipe è pieno quando un'applicazione usa la funzione writeFile per scrivere in una pipe, l'operazione di scrittura potrebbe non terminare immediatamente. L'operazione di scrittura verrà completata quando un'operazione di lettura (usando la funzione ReadFile) rende disponibile più spazio del buffer di sistema per la pipe.

Quando si scrive in un handle pipe in modalità byte senza blocco con spazio buffer insufficiente, WriteFile restituisce true con *lpNumberOfBytesWritten<nNumberOfBytesToWrite.

Per altre informazioni sulle pipe, vedere Pipe.

operazioni transazionate

Esempi

Per alcuni esempi, vedere Creazione e uso di un file temporaneo e apertura di un file per la lettura o la scrittura di.

#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;
}

Fabbisogno

Vedere anche

CancelIo

CancelIoEx

CancelSynchronousIo

CreateFile

CreateFileTransacted

funzioni di gestione file

GetLastError

GetOverlappedResult

GetQueuedCompletionStatus

ReadFile

SetEndOfFile

WriteFileEx