ZwReadFile

The ZwReadFile routine reads data from an open file.

NTSTATUS 
  ZwReadFile(
    IN HANDLE  FileHandle,
    IN HANDLE  Event  OPTIONAL,
    IN PIO_APC_ROUTINE  ApcRoutine  OPTIONAL,
    IN PVOID  ApcContext  OPTIONAL,
    OUT PIO_STATUS_BLOCK  IoStatusBlock,
    OUT 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 or ZwOpenFile.

Event

Optional. Handle to an event object that is set to the signaled state after the read 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 an IO_STATUS_BLOCK structure that receives the final completion status and information about the requested read operation.

Buffer

Pointer to a caller-allocated buffer that receives the data read from the file.

Length

Specifies the size in bytes of the given Buffer. A successful call to ZwReadFile returns the given number of bytes from the file, unless this routine reaches the end of file first.

ByteOffset

Pointer to a variable that specifies the starting byte offset in the file where the read operation will begin. If an attempt is made to read beyond the end of the file, ZwReadFile returns an error.

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 ZwReadFile 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.

ZwReadFile updates the current file position by adding the number of bytes read when it completes the read 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 ZwReadFile. Doing this automatically changes the current file position to that ByteOffset value, performs the read operation, and then updates the position according to the number of bytes actually read. This technique gives the caller atomic seek-and-read service.

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

ZwReadFile either returns STATUS_SUCCESS or the appropriate error status. The number of bytes actually read from the file is returned in the Information member of the IoStatusBlock.

Comments

Callers of ZwReadFile must have already called ZwCreateFile with the DesiredAccess flag FILE_READ_DATA set, either explicitly or by setting this flag using GENERIC_READ.

If the preceding call to ZwCreateFile set the CreateOptions flag FILE_NO_INTERMEDIATE_BUFFERING, the Length and ByteOffset parameters to ZwReadFile must be an integral of the sector size. For more information, see ZwCreateFile.

ZwReadFile begins reading from the given ByteOffset or the current file position into the given Buffer. It terminates the read operation under one of the following conditions:

• The buffer is full because the number of bytes specified by the Length parameter has been read. Therefore, no more data can be placed into the buffer without an overflow.
• The end of file is reached during the read operation, so there is no more data in the file to be transferred into the buffer.

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 ZwReadFile in the context of the system process in three cases:

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

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 ZwReadFile in the context of the system process instead of the process context that the driver is in.

Likewise, ZwReadFile 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 ZwReadFile 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 ZwReadFile must be running at IRQL = PASSIVE_LEVEL.

See Also

KeInitializeEvent, ZwCreateFile, ZwQueryInformationFile, ZwSetInformationFile, ZwWriteFile