Função NtWriteFile (ntifs.h)
A rotina de ZwWriteFile grava dados em um arquivo aberto.
Sintaxe
__kernel_entry NTSYSCALLAPI NTSTATUS NtWriteFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] PVOID Buffer,
[in] ULONG Length,
[in, optional] PLARGE_INTEGER ByteOffset,
[in, optional] PULONG Key
);
Parâmetros
[in] FileHandle
Manipule para o objeto de arquivo. Esse identificador é criado por uma chamada bem-sucedida para NtCreateFile ou NtOpenFile.
[in, optional] Event
Opcionalmente, um identificador para um objeto de evento a ser definido como o estado sinalizado após a conclusão da operação de gravação. Os drivers intermediários e de dispositivo devem definir esse parâmetro como NULL.
[in, optional] ApcRoutine
Esse parâmetro é reservado. Os drivers intermediários e de dispositivo devem definir esse ponteiro como NULL.
[in, optional] ApcContext
Esse parâmetro é reservado. Os drivers intermediários e de dispositivo devem definir esse ponteiro como NULL.
[out] IoStatusBlock
Ponteiro para uma estrutura de IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação de gravação solicitada. O membro Information recebe o número de bytes realmente gravados no arquivo.
[in] Buffer
Ponteiro para um buffer alocado pelo chamador que contém os dados a serem gravados no arquivo.
[in] Length
O tamanho, em bytes, do buffer apontado por buffer.
[in, optional] ByteOffset
Ponteiro para uma variável que especifica o deslocamento de bytes inicial no arquivo para iniciar a operação de gravação. Se Length e ByteOffset especificar uma operação de gravação após a marca de fim de arquivo atual, NtWriteFile estenderá automaticamente o arquivo e atualizará a marca de fim de arquivo; todos os bytes que não são escritos explicitamente entre essas marcas de fim de arquivo antigas e novas são definidos como zero.
Se a chamada para NtCreateFile definir apenas o sinalizador DesiredAccess FILE_APPEND_DATA, byteOffset será ignorado. Os dados no de Buffer defornecido, para Length bytes, são gravados a partir do final atual do arquivo.
Se a chamada para NtCreateFile definir um dos sinalizadores CreateOptions, FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT, o Gerenciador de E/S manterá a posição atual do arquivo. Nesse caso, o chamador de NtWriteFile pode especificar que o deslocamento de posição do arquivo atual seja usado em vez de um valor byteOffset explícito. Essa especificação pode ser feita usando um dos seguintes métodos:
- *Especifique um ponteiro para um valor de LARGE_INTEGER com o membro HighPart definido como -1 e o membro LowPart definido como o valor definido pelo sistema FILE_USE_FILE_POINTER_POSITION.
- Passe um ponteiro NULL para byteOffset.
NtWriteFile atualiza a posição do arquivo atual adicionando o número de bytes gravados quando concluir a operação de gravação, se ela estiver usando a posição de arquivo atual mantida pelo Gerenciador de E/S.
Mesmo quando o Gerenciador de E/S está mantendo a posição atual do arquivo, o chamador pode redefinir essa posição passando um valor byteOffset explícito para NtWriteFile. Fazer isso altera automaticamente a posição do arquivo atual para esse valor ByteOffset, executa a operação de gravação e atualiza a posição de acordo com o número de bytes realmente gravados. Essa técnica fornece ao chamador o serviço de busca e gravação atômica.
Também é possível fazer com que uma operação de gravação comece no final atual do arquivo especificando para ByteOffset um ponteiro para um valor de LARGE_INTEGER com highpart definido como -1 e LowPart definido como FILE_WRITE_TO_END_OF_FILE. Isso funciona independentemente de o Gerenciador de E/S manter a posição atual do arquivo.
[in, optional] Key
Os drivers intermediários e de dispositivo devem definir esse ponteiro como NULL.
Valor de retorno
NtWriteFile retorna STATUS_SUCCESS com êxito ou o código de erro NTSTATUS apropriado em caso de falha.
Observações
Os chamadores de NtWriteFile já devem ter chamado NtCreateFile com o sinalizador FILE_WRITE_DATA, FILE_APPEND_DATA ou GENERIC_WRITE definido no parâmetro DesiredAccess. Observe que ter apenas FILE_APPEND_DATA acesso a um arquivo não permite que o chamador grave em qualquer lugar do arquivo, exceto na marca de fim do arquivo atual, enquanto ter FILE_WRITE_DATA acesso a um arquivo não impede o chamador de gravar para ou além do final de um arquivo.
Se a chamada anterior para NtCreateFile definir os FILE_NO_INTERMEDIATE_BUFFERING do sinalizador CreateOptions, os parâmetros Length e ByteOffset para NtWriteFile deverão ser parte integrante do tamanho do setor. Para obter mais informações, consulte NtCreateFile.
NtWriteFile inicia a operação de gravação no arquivo em byteOffset, na posição do arquivo atual ou na marca de fim do arquivo. Ele encerra a operação de gravação quando é gravada Comprimento bytes de buffer. Se necessário, ele estende o comprimento do arquivo e redefine a marca de fim do arquivo.
Se o chamador abriu o arquivo com o sinalizador DesiredAccess SYNCHRONIZE definido, o chamador poderá aguardar essa rotina para definir o FileHandle para o estado sinalizado.
Os drivers devem chamar NtWriteFile no contexto do processo do sistema em três casos:
- O driver cria o identificador de arquivo que ele passa para NtWriteFile.
- NtWriteFile notifica o driver de conclusão de E/S por meio de um evento criado pelo driver.
- NtWriteFile notifica o driver de conclusão de E/S por meio de uma rotina de retorno de chamada de APC que o driver passa para NtWriteFile.
Identificadores de arquivo e evento só são válidos no contexto do processo em que os identificadores são criados. Portanto, para evitar falhas de segurança, o driver deve criar qualquer identificador de arquivo ou evento que ele passa para NtWriteFile no contexto do processo do sistema em vez do contexto do processo em que o driver está.
Da mesma forma, NtWriteFile devem ser chamados no contexto do processo do sistema se ele notificar o driver de conclusão de E/S por meio de um APC, pois as APCs sempre são acionadas no contexto do thread que emite a solicitação de E/S. Se o driver chamar NtWriteFile no contexto de um processo diferente do processo do sistema, o APC poderá ser adiado indefinidamente ou pode não ser acionado, pois o thread de origem pode nunca entrar em um estado de espera alertável.
Para obter mais informações sobre como trabalhar com arquivos, consulte Usando arquivos em um driver.
Os chamadores de NtWriteFile devem estar em execução em IRQL = PASSIVE_LEVEL e com APCs de kernel especiais habilitadas.
Se a chamada para essa função ocorrer no modo de usuário, você deverá usar o nome "NtWriteFile" em vez de "ZwWriteFile".
Para chamadas de drivers no modo kernel, as versões NtXxx e Zwxxx versões de uma rotina dos Serviços de Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Usando versões Nt e Zw das rotinas de serviços do sistema nativo.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 2000 |
| da Plataforma de Destino | Universal |
| cabeçalho | ntifs.h (incluem Wdm.h, Ntddk.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (consulte a seção Comentários) |
| regras de conformidade de DDI | HwStorPortProhibitedDIs, PowerIrpDDis |