NtReadFile - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers
#ifndef _NTIOAPI_H

/**
 * The NtReadFile function reads data from an open file.
 *
 * \param[in] FileHandle A handle to the file object representing the file or directory on which the specified action is to be performed.
 * \param[in] Event A handle for a caller-created event. This parameter is optional and can be NULL. It must be NULL if the caller will wait for the FileHandle to be set to the Signaled state.
 * \param[in] ApcRoutine Address of a caller-supplied APC routine to be called when the requested operation completes. This parameter is optional and can be NULL.
 * \param[in] ApcContext Pointer to a caller-determined context area. This parameter value is used as the APC context if the caller supplies an APC, or is used as the completion context if an I/O completion object has been associated with the file object.
 * \param[out] IoStatusBlock Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the operation.
 * \param[out] Buffer Pointer to a caller-allocated buffer that receives the data read from the file.
 * \param[in] Length The size, in bytes, of the buffer pointed to by Buffer.
 * \param[in] ByteOffset Pointer to a variable that specifies the starting byte offset in the file where the read operation will begin.
 * \param[in] Key Device and intermediate drivers should set this pointer to NULL.
 * \return NTSTATUS Successful or errant status.
 * \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwreadfile
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtReadFile(
    _In_ HANDLE FileHandle,
    _In_opt_ HANDLE Event,
    _In_opt_ PIO_APC_ROUTINE ApcRoutine,
    _In_opt_ PVOID ApcContext,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _Out_writes_bytes_(Length) PVOID Buffer,
    _In_ ULONG Length,
    _In_opt_ PLARGE_INTEGER ByteOffset,
    _In_opt_ PULONG Key
    );

#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwReadFile(
    _In_ HANDLE FileHandle,
    _In_opt_ HANDLE Event,
    _In_opt_ PIO_APC_ROUTINE ApcRoutine,
    _In_opt_ PVOID ApcContext,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _Out_writes_bytes_(Length) PVOID Buffer,
    _In_ ULONG Length,
    _In_opt_ PLARGE_INTEGER ByteOffset,
    _In_opt_ PULONG Key
    );

#endif

View code on GitHub
// ntifs.h

__kernel_entry NTSYSCALLAPI NTSTATUS NtReadFile(
  [in]           HANDLE           FileHandle,
  [in, optional] HANDLE           Event,
  [in, optional] PIO_APC_ROUTINE  ApcRoutine,
  [in, optional] PVOID            ApcContext,
  [out]          PIO_STATUS_BLOCK IoStatusBlock,
  [out]          PVOID            Buffer,
  [in]           ULONG            Length,
  [in, optional] PLARGE_INTEGER   ByteOffset,
  [in, optional] PULONG           Key
);

View the official Windows Driver Kit DDI reference
// wdm.h

NTSYSAPI NTSTATUS ZwReadFile(
  [in]           HANDLE           FileHandle,
  [in, optional] HANDLE           Event,
  [in, optional] PIO_APC_ROUTINE  ApcRoutine,
  [in, optional] PVOID            ApcContext,
  [out]          PIO_STATUS_BLOCK IoStatusBlock,
  [out]          PVOID            Buffer,
  [in]           ULONG            Length,
  [in, optional] PLARGE_INTEGER   ByteOffset,
  [in, optional] PULONG           Key
);

View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Windows Driver Kit DDI reference (nf-ntifs-ntreadfile)

NtReadFile function

Description

The NtReadFile routine reads data from an open file.

Parameters

FileHandle [in]

Handle to the file object. This handle is created by a successful call to NtCreateFile or NtOpenFile.

Event [in, optional]

Optionally, a handle to an event object to set to the signaled state after the read operation completes. Device and intermediate drivers should set this parameter to NULL.

ApcRoutine [in, optional]

This parameter is reserved. Device and intermediate drivers should set this pointer to NULL.

ApcContext [in, optional]

This parameter is reserved. Device and intermediate drivers should set this pointer to NULL.

IoStatusBlock [out]

Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the requested read operation. The Information member receives the number of bytes actually read from the file.

Buffer [out]

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

Length [in]

The size, in bytes, of the buffer pointed to by Buffer.

ByteOffset [in, optional]

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, NtReadFile returns an error.

If the call to NtCreateFile 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 NtReadFile 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:

NtReadFile 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 NtReadFile. 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 [in, optional]

Device and intermediate drivers should set this pointer to NULL.

Return value

NtReadFile returns either STATUS_SUCCESS or the appropriate NTSTATUS error code.

Remarks

Callers of NtReadFile must have already called NtCreateFile with the FILE_READ_DATA or GENERIC_READ value set in the DesiredAccess parameter.

If the preceding call to NtCreateFile set the FILE_NO_INTERMEDIATE_BUFFERING flag in the CreateOptions parameter to NtCreateFile, the Length and ByteOffset parameters to NtReadFile must be multiples of the sector size.

NtReadFile 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:

If the caller opened the file with the SYNCHRONIZE flag set in DesiredAccess, the calling thread can synchronize to the completion of the read operation by waiting on the file handle, FileHandle. The handle is signaled each time that an I/O operation that was issued on the handle completes. However, the caller must not wait on a handle that was opened for synchronous file access (FILE_SYNCHRONOUS_IO_NONALERT or FILE_SYNCHRONOUS_IO_ALERT). In this case, NtReadFile waits on behalf of the caller and does not return until the read operation is complete. The caller can safely wait on the file handle only if all three of the following conditions are met:

A driver should call NtReadFile in the context of the system process if any of the following conditions exist:

File and event handles are valid only 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 NtReadFile in the context of the system process rather than the context of the process that the driver is in.

Likewise, NtReadFile 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 that issues the I/O request. If the driver calls NtReadFile in the context of a process other than the system one, the APC could be delayed indefinitely, or it might not fire at all.

For more information about working with files, see Using Files in a Driver.

Callers of NtReadFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

If the call to this function occurs in user mode, you should use the name "NtReadFile" instead of "ZwReadFile".

For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

KeInitializeEvent

ZwCreateFile

NtQueryInformationFile

NtSetInformationFile

NtWriteFile


Windows Driver Kit DDI reference (nf-wdm-zwreadfile)

Description

The ZwReadFile routine reads data from an open file.

Parameters

FileHandle [in]

Handle to the file object. This handle is created by a successful call to ZwCreateFile or ZwOpenFile.

Event [in, optional]

Optionally, a handle to an event object to set to the signaled state after the read operation completes. Device and intermediate drivers should set this parameter to NULL.

ApcRoutine [in, optional]

This parameter is reserved. Device and intermediate drivers should set this pointer to NULL.

ApcContext [in, optional]

This parameter is reserved. Device and intermediate drivers should set this pointer to NULL.

IoStatusBlock [out]

Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the requested read operation. The Information member receives the number of bytes actually read from the file.

Buffer [out]

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

Length [in]

The size, in bytes, of the buffer pointed to by Buffer.

ByteOffset [in, optional]

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:

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 [in, optional]

Device and intermediate drivers should set this pointer to NULL.

Return value

ZwReadFile returns either STATUS_SUCCESS or the appropriate NTSTATUS error code.

Remarks

Callers of ZwReadFile must have already called ZwCreateFile with the FILE_READ_DATA or GENERIC_READ value set in the DesiredAccess parameter.

If the preceding call to ZwCreateFile set the FILE_NO_INTERMEDIATE_BUFFERING flag in the CreateOptions parameter to ZwCreateFile, the Length and ByteOffset parameters to ZwReadFile must be multiples 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:

If the caller opened the file with the SYNCHRONIZE flag set in DesiredAccess, the calling thread can synchronize to the completion of the read operation by waiting on the file handle, FileHandle. The handle is signaled each time that an I/O operation that was issued on the handle completes. However, the caller must not wait on a handle that was opened for synchronous file access (FILE_SYNCHRONOUS_IO_NONALERT or FILE_SYNCHRONOUS_IO_ALERT). In this case, ZwReadFile waits on behalf of the caller and does not return until the read operation is complete. The caller can safely wait on the file handle only if all three of the following conditions are met:

A driver should call ZwReadFile in the context of the system process if any of the following conditions exist:

File and event handles are valid only 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 rather than the context of the process 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 that issues the I/O request. If the driver calls ZwReadFile in the context of a process other than the system one, the APC could be delayed indefinitely, or it might not fire at all.

For more information about working with files, see Using Files in a Driver.

Callers of ZwReadFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

If the call to this function occurs in user mode, you should use the name "NtReadFile" instead of "ZwReadFile".

See also

KeInitializeEvent

ZwCreateFile

ZwQueryInformationFile

ZwSetInformationFile

ZwWriteFile


NTinternals.net (undocumented.ntinternals.net)

This function is documented in Windows Driver Kit here and here.


(Also described in Win2000 DDK)

FileHandle

HANDLE to File Object opened with FILE_READ_DATA access.

Event

Optional HANDLE to Event Object signaled when reading is done.

ApcRoutine

User defined APC routine queued for execute after reading is done.

ApcContext

User parameter to ApcRoutine.

IoStatusBlock

Pointer to IO_STATUS structure received IO status of file reading.

Buffer

User-allocated buffer for read data.

Length

Length of Buffer, in bytes.

ByteOffset

Offset from beginning of file, in bytes.

Key

??? (In my opinion: use this, if you previously lock file, and now you want read it, but without unlocking).

Related Win32 API

Documented by

See also