ZwWriteFile

The ZwWriteFile routine writes data to an open file.

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
    );

Parameters

FileHandle

Handle to a file object. The handle is created by a successful call to ZwCreateFile.

Event

Optional. Handle to an event object that is set to the signaled state after the write operation completes. Device and intermediate drivers should set this parameter to NULL.

ApcRoutine

Reserved. Device and intermediate drivers should set this pointer to NULL.

ApcContext

Reserved. Device and intermediate drivers should set this pointer to NULL.

IoStatusBlock

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

Buffer

Pointer 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

Pointer to a variable that specifies the starting byte offset in the file where the write operation will begin. 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. This specification can be made by using one of the following methods:

• Specify a pointer to a LARGE_INTEGER value with the HighPart member set to -1 and the LowPart member set to 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 value, performs the write operation, 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 operation to start at the current end of file by specifying for ByteOffset a pointer to a LARGE_INTEGER value with HighPart set to -1 and LowPart set to FILE_WRITE_TO_END_OF_FILE. This works whether or not the I/O Manager is maintaining the current file position.

Key

Device and intermediate drivers should set this pointer to NULL.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

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, the Length and ByteOffset parameters to ZwWriteFile must be an integral of the sector size. For more information, see ZwCreateFile.

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 for this routine to set the given FileHandle to the signaled state.

Drivers should call ZwWriteFile in the context of the system process in three cases:

1. The driver creates the file handle that it passes to ZwWriteFile.
2. ZwWriteFile notifies the driver of I/O completion by means of an event created by the driver.
3. ZwWriteFile notifies the driver of I/O completion by means of an APC callback routine that the driver passes to ZwWriteFile.

File and event handles are only valid in the process context where the handles are created. Therefore, to avoid security holes, the driver should create any file or event handle that it passes to ZwWriteFile in the context of the system process instead of the process context that the driver is in.

Likewise, ZwWriteFile should be called in the context of the system process if it notifies the driver of I/O completion by means of an APC, because APCs are always fired in the context of the thread issuing the I/O request. If the driver calls ZwWriteFile in the context of a process other than the system process, the APC could be delayed indefinitely, or it might not fire at all.

Callers of ZwWriteFile must be running at IRQL = PASSIVE_LEVEL.

See Also

KeInitializeEvent, ZwCreateFile, ZwQueryInformationFile, ZwReadFile, ZwSetInformationFile