ZwWriteFile

ZwWriteFile

NTSTATUS
ZwWriteFile(
IN HANDLE FileHandle,
IN HANDLE Event,/* optional */
IN PIO_APC_ROUTINE ApcRoutine,/* optional */
IN PVOID ApcContext,/* optional */
OUT PIO_STATUS_BLOCK IoStatusBlock,
IN PVOID Buffer,
IN ULONG Length,
IN PLARGE_INTEGER ByteOffset,/* optional */
IN PULONG Key/* optional */
);

Data can be written to an open file with ZwWriteFile.

Parameters

FileHandle

Is the handle returned by a successful call to ZwCreateFile.

Event

Is an optional handle for an event to be set to the Signaled state when the write operation completes. Device and intermediate drivers should set this parameter to NULL.

ApcRoutine

Device and intermediate drivers should set this pointer to NULL.

ApcContext

Device and intermediate drivers should set this pointer to NULL.

IoStatusBlock

Points to a variable that receives the final completion status and information about the requested write operation.

Buffer

Points to a caller-allocated buffer containing the data to be written to the file.

Length

Specifies the size in bytes of the given Buffer. A successful call to ZwWriteFile transfers the given number of bytes to the file. If necessary, the length of the file is extended.

ByteOffset

Points to a variable specifying the starting byte offset within the file at which to begin the write operation. If a given Length and ByteOffset specify a write operation past the current end-of-file mark, ZwWriteFile automatically extends the file and updates the end-of-file mark; any bytes that are not explicitly written between such old and new end-of-file marks are defined to be zero.

If the call to ZwCreateFile set only the DesiredAccess flag FILE_APPEND_DATA, ByteOffset is ignored. Data in the given Buffer, for Length bytes, is written starting at the current end of file.

If the call to ZwCreateFile set either of the CreateOptions flags FILE_SYNCHRONOUS_IO_ALERT or FILE_SYNCHRONOUS_IO_NONALERT, the I/O Manager maintains the current file position. If so, the caller of ZwWriteFile can specify that the current file position offset be used instead of an explicit ByteOffset value in either of the following ways:

·Specify the system-defined value FILE_USE_FILE_POINTER_POSITION.

·Pass a NULL pointer for ByteOffset.

ZwWriteFile updates the current file position by adding the number of bytes written when it completes the write operation, if it is using the current file position maintained by the I/O Manager.

Even when the I/O Manager is maintaining the current file position, the caller can reset this position by passing an explicit ByteOffset value to ZwWriteFile. Doing this automatically changes the current file position to that ByteOffset, performs the write, and then updates the position according to the number of bytes actually written. This technique gives the caller atomic seek-and-write service.

It is also possible to cause a write to start at the current end of file by specifying FILE_WRITE_TO_END_OF_FILE for the ByteOffset parameter even if the I/O Manager is not maintaining the current file position.

Key

Device and intermediate drivers should set this pointer to NULL.

Return Value

ZwWriteFile either returns STATUS_SUCCESS or an appropriate error status. The number of bytes actually written to the file is returned in the Information member of IoStatusBlock.

Comments

Callers of ZwWriteFile must have already called ZwCreateFile with the DesiredAccess flags FILE_WRITE_DATA and/or FILE_APPEND_DATA set, either explicitly or by setting these flags with GENERIC_WRITE. Note that having only FILE_APPEND_DATA access to a file does not allow the caller to write anywhere in the file except at the current end-of-file mark, while having FILE_WRITE_DATA access to a file does not preclude the caller from writing to or beyond the end of a file.

If the preceding call to ZwCreateFile set the CreateOptions flag FILE_NO_INTERMEDIATE_BUFFERING, certain restrictions on the parameters to ZwWriteFile are enforced. See ZwCreateFile for specifics.

ZwWriteFile begins writing data from the given Buffer at the given ByteOffset in the file, at the current file position within the file, or at the end-of-file mark. It terminates the write operation when it has written Length bytes to the file, extending the length of the file if necessary, and resetting the end-of-file mark.

If the caller opened the file with the DesiredAccess SYNCHRONIZE flag set, the caller can wait on this routine's setting the given FileHandle to the Signaled state.

Callers of ZwWriteFile must be running at IRQL PASSIVE_LEVEL.