Função WriteFile (fileapi.h)
Grava dados no arquivo especificado ou no dispositivo de E/S (entrada/saída).
Essa função foi projetada para operação síncrona e assíncrona. Para uma função semelhante projetada exclusivamente para operação assíncrona, consulte WriteFileEx.
Sintaxe
BOOL WriteFile(
[in] HANDLE hFile,
[in] LPCVOID lpBuffer,
[in] DWORD nNumberOfBytesToWrite,
[out, optional] LPDWORD lpNumberOfBytesWritten,
[in, out, optional] LPOVERLAPPED lpOverlapped
);
Parâmetros
[in] hFile
Um identificador para o arquivo ou dispositivo de E/S (por exemplo, um arquivo, fluxo de arquivos, disco físico, volume, buffer de console, unidade de fita, soquete, recurso de comunicação, maillot ou pipe).
O parâmetro hFile deve ter sido criado com o acesso de gravação. Para obter mais informações, consulte Direitos de Acesso Genéricos e Segurança de Arquivos e Direitos de Acesso.
Para operações de gravação assíncronas, hFile pode ser qualquer identificador aberto com a função CreateFile usando o sinalizador FILE_FLAG_OVERLAPPED ou um identificador de soquete retornado pelo soquete ou função accept .
[in] lpBuffer
Um ponteiro para o buffer que contém os dados a serem gravados no arquivo ou dispositivo.
Esse buffer deve permanecer válido durante a operação de gravação. O chamador não deve usar esse buffer até que a operação de gravação seja concluída.
[in] nNumberOfBytesToWrite
O número de bytes a serem gravados no arquivo ou dispositivo.
Um valor igual a zero especifica uma operação de gravação nula. O comportamento de uma operação de gravação nula depende do sistema de arquivos subjacente ou da tecnologia de comunicação.
Windows Server 2003 e Windows XP: As operações de gravação de pipe em uma rede são limitadas em tamanho por gravação. O valor varia de acordo com a plataforma. Para plataformas x86, são 63,97 MB. Para plataformas x64, são 31,97 MB. Para Itanium, são 63,95 MB. Para obter mais informações sobre pipes, consulte a seção Comentários.
[out, optional] lpNumberOfBytesWritten
Um ponteiro para a variável que recebe o número de bytes gravados ao usar um parâmetro hFile síncrono. WriteFile define esse valor como zero antes de fazer qualquer verificação de erro ou trabalho. Use NULL para esse parâmetro se esta for uma operação assíncrona para evitar resultados potencialmente incorretos.
Esse parâmetro só pode ser NULL quando o parâmetro lpOverlapped não é NULL.
Windows 7: Esse parâmetro não pode ser NULL.
Para obter mais informações, consulte a seção Comentários.
[in, out, optional] lpOverlapped
Um ponteiro para uma estrutura OVERLAPPED será necessário se o parâmetro hFile tiver sido aberto com FILE_FLAG_OVERLAPPED, caso contrário, esse parâmetro poderá ser NULL.
Para um hFile que dá suporte a deslocamentos de bytes, se você usar esse parâmetro, deverá especificar um deslocamento de bytes no qual começar a gravar no arquivo ou dispositivo. Esse deslocamento é especificado definindo os membros Offset e OffsetHigh da estrutura OVERLAPPED . Para um hFile que não dá suporte a deslocamentos de bytes, Offset e OffsetHigh são ignorados.
Para gravar no final do arquivo, especifique os membros Offset e OffsetHigh da estrutura OVERLAPPED como 0xFFFFFFFF. Isso é funcionalmente equivalente a chamar anteriormente a função CreateFile para abrir o hFile usando FILE_APPEND_DATA acesso.
Para obter mais informações sobre diferentes combinações de lpOverlapped e FILE_FLAG_OVERLAPPED, consulte a seção Comentários e a seção Sincronização e Posição do Arquivo .
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero (TRUE).
Se a função falhar ou estiver concluindo de forma assíncrona, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame a função GetLastError.
Comentários
A função WriteFile retorna quando ocorre uma das seguintes condições:
- O número de bytes solicitados é gravado.
- Uma operação de leitura libera espaço em buffer na extremidade de leitura do pipe (se a gravação foi bloqueada). Para obter mais informações, consulte a seção Pipes .
- Um identificador assíncrono está sendo usado e a gravação está ocorrendo de forma assíncrona.
- Ocorrerá um erro.
Para cancelar todas as operações de E/S assíncronas pendentes, use:
- CancelIo — essa função cancela apenas as operações emitidas pelo thread de chamada para o identificador de arquivo especificado.
- CancelIoEx: essa função cancela todas as operações emitidas pelos threads para o identificador de arquivo especificado.
As operações de E/S canceladas são concluídas com o erro ERROR_OPERATION_ABORTED.
A função WriteFile pode falhar com ERROR_NOT_ENOUGH_QUOTA, o que significa que o buffer do processo de chamada não pôde ser bloqueado por página. Para obter mais informações, consulte SetProcessWorkingSetSize.
Se parte do arquivo estiver bloqueada por outro processo e a operação de gravação se sobrepor à parte bloqueada, WriteFile falhará.
Ao gravar em um arquivo, o último tempo de gravação não será totalmente atualizado até que todos os identificadores usados para gravação sejam fechados. Portanto, para garantir uma hora de última gravação precisa, feche o identificador de arquivo imediatamente após a gravação no arquivo.
Acessar o buffer de saída enquanto uma operação de gravação estiver usando o buffer pode levar à corrupção dos dados gravados nesse buffer. Os aplicativos não devem gravar, realocar ou liberar o buffer de saída que uma operação de gravação está usando até que a operação de gravação seja concluída. Isso pode ser particularmente problemático ao usar um identificador de arquivo assíncrono. Informações adicionais sobre identificadores de arquivo síncronos versus assíncronos podem ser encontradas posteriormente na seção Sincronização e Posição do Arquivo e E /S síncrona e assíncrona.
Observe que os carimbos de data/hora podem não ser atualizados corretamente para um arquivo remoto. Para garantir resultados consistentes, use E/S sem cofres.
O sistema interpreta zero bytes a serem gravados como especificando uma operação de gravação nula e WriteFile não trunca nem estende o arquivo. Para truncar ou estender um arquivo, use a função SetEndOfFile .
Os caracteres podem ser gravados no buffer de tela usando WriteFile com um identificador para a saída do console. O comportamento exato da função é determinado pelo modo de console. Os dados são gravados na posição atual do cursor. A posição do cursor é atualizada após a operação de gravação. Para obter mais informações sobre identificadores de console, consulte CreateFile.
Ao gravar em um dispositivo de comunicação, o comportamento de WriteFile é determinado pelo tempo limite de comunicação atual como definido e recuperado usando as funções SetCommTimeouts e GetCommTimeouts . Resultados imprevisíveis podem ocorrer se você não definir os valores de tempo limite. Para obter mais informações sobre tempos limite de comunicação, consulte COMMTIMEOUTS.
Embora uma gravação de setor único seja atômica, não há garantia de que uma gravação de vários setores seja atômica, a menos que você esteja usando uma transação (ou seja, o identificador criado é um identificador transacionado; por exemplo, um identificador criado usando CreateFileTransacted). As gravações de vários setores armazenadas em cache nem sempre podem ser gravadas no disco imediatamente; portanto, especifique FILE_FLAG_WRITE_THROUGH em CreateFile para garantir que toda uma gravação de vários setores seja gravada no disco sem possíveis atrasos de cache.
Se você gravar diretamente em um volume que tenha um sistema de arquivos montado, primeiro deverá obter acesso exclusivo ao volume. Caso contrário, você corre o risco de causar corrupção de dados ou instabilidade do sistema, pois as gravações do aplicativo podem entrar em conflito com outras alterações provenientes do sistema de arquivos e deixar o conteúdo do volume em um estado inconsistente. Para evitar esses problemas, as seguintes alterações foram feitas no Windows Vista e posteriores:
- Uma gravação em um identificador de volume terá êxito se o volume não tiver um sistema de arquivos montado ou se uma das seguintes condições for verdadeira:
- Os setores a serem escritos são setores de inicialização.
- Os setores a serem gravados para residir fora do espaço do sistema de arquivos.
- Você bloqueou ou desmontou explicitamente o volume usando FSCTL_LOCK_VOLUME ou FSCTL_DISMOUNT_VOLUME.
- O volume não tem um sistema de arquivos real. (Em outras palavras, ele tem um sistema de arquivos RAW montado.)
- Uma gravação em um identificador de disco terá êxito se uma das seguintes condições for verdadeira:
- Os setores a serem gravados não se enquadram nas extensões de um volume.
- Os setores a serem gravados para se enquadrarem em um volume montado, mas você bloqueou ou desmontou explicitamente o volume usando FSCTL_LOCK_VOLUME ou FSCTL_DISMOUNT_VOLUME.
- Os setores a serem gravados para se enquadrarem em um volume que não tem nenhum sistema de arquivos montado diferente de RAW.
Se hFile foi aberto com FILE_FLAG_OVERLAPPED, as seguintes condições estão em vigor:
- O parâmetro lpOverlapped deve apontar para uma estrutura OVERLAPPED válida e exclusiva, caso contrário, a função poderá relatar incorretamente que a operação de gravação está concluída.
- O parâmetro lpNumberOfBytesWritten deve ser definido como NULL. Para obter o número de bytes gravados, use a função GetOverlappedResult . Se o parâmetro hFile estiver associado a uma porta de conclusão de E/S, você também poderá obter o número de bytes gravados chamando a função GetQueuedCompletionStatus .
| Tecnologia | Com suporte |
|---|---|
| Protocolo SMB (SMB) 3.0 | Sim |
| TFO (Failover transparente) do SMB 3.0 | Sim |
| SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | Sim |
| Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) | Sim |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
Sincronização e posição do arquivo
Se hFile for aberto com FILE_FLAG_OVERLAPPED, ele será um identificador de arquivo assíncrono; caso contrário, ele será síncrono. As regras para usar a estrutura OVERLAPPED são ligeiramente diferentes para cada uma, conforme observado anteriormente.- WriteFile pode retornar antes da conclusão da operação de gravação. Nesse cenário, WriteFile retorna FALSE e a função GetLastError retorna ERROR_IO_PENDING, o que permite que o processo de chamada continue enquanto o sistema conclui a operação de gravação.
- O parâmetro lpOverlapped não deve ser NULL e deve ser usado com os seguintes fatos em mente:
- Embora o evento especificado na estrutura OVERLAPPED seja definido e redefinido automaticamente pelo sistema, o deslocamento especificado na estrutura OVERLAPPED não é atualizado automaticamente.
- WriteFile redefine o evento para um estado não atribuído quando ele inicia a operação de E/S.
- O evento especificado na estrutura OVERLAPPED é definido como um estado sinalizado quando a operação de gravação é concluída; até esse momento, a operação de gravação é considerada pendente.
- Como a operação de gravação começa no deslocamento especificado na estrutura OVERLAPPED e WriteFile pode retornar antes que a operação de gravação no nível do sistema seja concluída (gravação pendente), nem o deslocamento nem qualquer outra parte da estrutura devem ser modificados, liberados ou reutilizados pelo aplicativo até que o evento seja sinalizado (ou seja, a gravação é concluída).
- Se lpOverlapped for NULL, a operação de gravação começará na posição do arquivo atual e WriteFile não retornará até que a operação seja concluída e o sistema atualizará o ponteiro do arquivo antes que WriteFile retorne.
- Se lpOverlapped não for NULL, a operação de gravação começará no deslocamento especificado na estrutura OVERLAPPED e WriteFile não retornará até que a operação de gravação seja concluída. O sistema atualiza os campos OVERLAPPED Interno e InternalHigh e o ponteiro do arquivo antes que WriteFile retorne.
Tubos
Se um pipe anônimo estiver sendo usado e o identificador de leitura tiver sido fechado, quando WriteFile tentar gravar usando o identificador de gravação correspondente do pipe, a função retornará FALSE e GetLastError retornará ERROR_BROKEN_PIPE.Se o buffer de pipe estiver cheio quando um aplicativo usar a função WriteFile para gravar em um pipe, a operação de gravação poderá não ser concluída imediatamente. A operação de gravação será concluída quando uma operação de leitura (usando a função ReadFile ) disponibilizar mais espaço de buffer do sistema para o pipe.
Ao gravar em um identificador de pipe de modo byte sem bloqueio com espaço em buffer insuficiente, WriteFile retorna TRUE com *lpNumberOfBytesWritten<nNumberOfBytesToWrite.
Para obter mais informações sobre pipes, consulte Pipes.
Operações transacionadas
Se houver uma transação associada ao identificador de arquivo, a gravação do arquivo será transacionada. Para obter mais informações, consulte Sobre o NTFS transacional.Exemplos
Para obter alguns exemplos, consulte Criando e usando um arquivo temporário e abrindo um arquivo para leitura ou gravação.
O exemplo C++ a seguir mostra como alinhar setores para gravações de arquivo não armazenadas em buffer. A variável Size é o tamanho do bloco de dados original que você está interessado em gravar no arquivo. Para obter regras adicionais sobre E/S de arquivo não armazenado em buffer, consulte Buffer de arquivos.#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;
}
Requisitos
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | fileapi.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |