Edit

FSCTL_OFFLOAD_READ control code

  • Article

The FSCTL_OFFLOAD_READ control code initiates an offload read for a block of data in a storage system that supports offload read primitives.

To perform this operation, call FltFsControlFile or ZwFsControlFile with the following parameters.

Parameters

  • Instance [in]: FltFsControlFile only. An opaque instance pointer for the caller. This parameter is required and cannot be NULL.

  • FileObject [in]: FltFsControlFile only. The file pointer object specifying the file to read from. This parameter is required and cannot be NULL.

  • FileHandle [in]: ZwFsControlFile only. The file handle of the file to read from. This parameter is required and cannot be NULL.

  • FsControlCode [in]: The control code for the operation. Use FSCTL_OFFLOAD_READ for this operation.

  • InputBuffer [in]: A pointer to a FSCTL_OFFLOAD_READ_INPUT structure, which contains the size and offset of a data block to read.

  • InputBufferLength [in]: The size, in bytes, of the buffer pointed to by InputBuffer. This value is sizeof(FSCTL_OFFLOAD_READ_INPUT).

  • OutputBuffer [out]: A pointer to a FSCTL_OFFLOAD_READ_OUTPUT structure, which receives the results of the offload read operation.

  • OutputBufferLength [out]: The size, in bytes, of the buffer pointed to by the OutputBuffer parameter. This value must be at least sizeof(FSCTL_OFFLOAD_READ_OUTPUT).

Status block

FltFsControlFile or ZwFsControlFile returns STATUS_SUCCESS if the operation succeeds. Otherwise, the appropriate function might return one of the following NTSTATUS values.

Code Meaning
STATUS_INVALID_DEVICE_REQUEST The handle specified is not a valid file handle
STATUS_INVALID_PARAMETER A parameter is invalid. See Remarks.
STATUS_VOLUME_DISMOUNTED The file system volume is dismounted.
STATUS_NOT_SUPPORTED Offload read operations are not supported on this volume.
STATUS_OFFLOAD_READ_FILE_NOT_SUPPORTED The requested file type is not supported. Offload operations are not supported on these file types: A transacted file (TxF); Non-user files; Compressed files; Encrypted files; Sparse files; NTFS Metatdata files.
STATUS_FILE_DELETED The data stream for this file is invalid.
STATUS_FILE_CLOSED The file handle is closed.
STATUS_INVALID_HANDLE The file handle specified is invalid.
STATUS_FILE_LOCK_CONFLICT Insufficient read access due to the current file locking state.
STATUS_END_OF_FILE The FileOffset member of FSCTL_OFFLOAD_READ_INPUT begins after end-of-file (EOF).
STATUS_DISMOUNTED_VOLUME An offload read cannot occur on a dismounted volume.
STATUS_INSUFFICIENT_RESOUCES Insufficient resources are available to complete the request.
STATUS_BUFFER_TOO_SMALL OutputBufferLength is too small for OutputBuffer to receive an FSCTL_OFFLOAD_READ_OUTPUT structure.

Remarks

Offload read is available for normal files only. See the description for STATUS_OFFLOAD_READ_FILE_NOT_SUPPORTED for a list of unsupported file types.

It is possible for reads to start beyond the Valid Data Length (VDL), but not beyond EOF.

When STATUS_INVALID_PARAMETER is returned, the error could be one of the following invalid parameters:

  • File size is less than PAGE_SIZE.
  • InputBufferLength < sizeof(FSCTL_OFFLOAD_READ_INPUT).
  • One or more of these members of FSCTL_OFFLOAD_READ_INPUT are incorrect:
    • FileOffset is not a multiple of the logical sector size of the volume.
    • CopyLength is not a multiple of the logical sector size of the volume.
    • Size is not the size of the FSCTL_OFFLOAD_READ_INPUT structure.
    • FileOffset + CopyLength > MAXULONGLONG.

Requirements

Requirement type Requirement
Minimum supported client Windows 8
Header Ntifs.h (include Ntifs.h or Fltkernel.h)

See also

FltFsControlFile

ZwFsControlFile

FSCTL_OFFLOAD_READ_INPUT

FSCTL_OFFLOAD_READ_OUTPUT