ZwReadFile

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

Data can be read from an opened file with ZwReadFile.

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 read 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 read operation.

Buffer

Points to a caller-allocated buffer to receive 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

Points to a variable specifying the starting byte offset within the file at which to begin the read operation. If an attempt is made to start reading beyond the end of 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 in either of the following ways:

• Specify 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, performs the read, 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.

Return Value

ZwReadFile either returns STATUS_SUCCESS or an 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 with GENERIC_READ.

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

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 on this routine’s setting the given FileHandle to the Signaled state.

Callers of ZwReadFile must be running at IRQL PASSIVE_LEVEL.

See Also

KeInitializeEvent, ZwCreateFile, ZwQueryInformationFile, ZwSetInformationFile, ZwWriteFile