ReadFileScatter function (fileapi.h)

Article
01/08/2024

Reads data from a file and stores it in an array of buffers.

The function starts reading data from the file at a position that is specified by an OVERLAPPED structure. The ReadFileScatter function operates asynchronously.

Syntax

BOOL ReadFileScatter(
  [in]      HANDLE                  hFile,
  [in]      FILE_SEGMENT_ELEMENT [] aSegmentArray,
  [in]      DWORD                   nNumberOfBytesToRead,
            LPDWORD                 lpReserved,
  [in, out] LPOVERLAPPED            lpOverlapped
);

Parameters

[in] hFile

A handle to the file to be read.

The file handle must be created with the GENERIC_READ right, and the FILE_FLAG_OVERLAPPED and FILE_FLAG_NO_BUFFERING flags. For more information, see File Security and Access Rights.

[in] aSegmentArray

A pointer to an array of FILE_SEGMENT_ELEMENT structure buffers that receives the data. For a description of this union, see Remarks.

Each element represents one page of data.

Note

To determine the size of a system page, use GetSystemInfo.

The array must contain enough elements to represent nNumberOfBytesToRead bytes of data. For example, if there are 40 KB to be read and the page size is 4 KB, the array must have 10 elements.

Each buffer must be at least the size of a system memory page and must be aligned on a system memory page size boundary. The system reads one system memory page of data into each buffer.

The function stores the data in the buffers in sequential order. For example, it stores data into the first buffer, then into the second buffer, and so on until each buffer is filled and all the data is stored, or nNumberOfBytesToRead bytes have been read.

[in] nNumberOfBytesToRead

The total number of bytes to be read from the file. Each element of aSegmentArray contains a one-page chunk of this total. Because the file must be opened with FILE_FLAG_NO_BUFFERING, the number of bytes must be a multiple of the sector size of the file system where the file is located.

lpReserved

This parameter is reserved for future use and must be NULL.

[in, out] lpOverlapped

A pointer to an OVERLAPPED data structure.

The ReadFileScatter function requires a valid OVERLAPPED structure. The lpOverlapped parameter cannot be NULL.

The ReadFileScatter function starts reading data from the file at a position that is specified by the Offset and OffsetHigh members of the OVERLAPPED structure.

The ReadFileScatter function may return before the read operation is complete. In that scenario, the ReadFileScatter function returns the value 0 (zero), and the GetLastError function returns the value ERROR_IO_PENDING. This asynchronous operation of ReadFileScatter lets the calling process continue while the read operation completes. You can call the GetOverlappedResult, HasOverlappedIoCompleted, or GetQueuedCompletionStatus functions to obtain information about the completion of the read operation. For more information, see Synchronous and Asynchronous I/O.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero (0). To get extended error information, call the GetLastError function.

If ReadFileScatter attempts to read past the end-of-file (EOF), the call to GetOverlappedResult for that operation returns FALSE and GetLastError returns ERROR_HANDLE_EOF.

If the function returns before the read operation is complete, the function returns zero (0), and GetLastError returns ERROR_IO_PENDING.

Remarks

This function is not supported for 32-bit applications by WOW64 on Itanium-based systems.

The FILE_SEGMENT_ELEMENT structure is defined as follows:

typedef union _FILE_SEGMENT_ELEMENT {
    PVOID64 Buffer;
    ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;

Assigning a pointer to the Buffer member will sign-extend the value if the code is compiled as 32-bits; this can break large-address aware applications running on systems configured with 4-Gigabyte Tuning or running on under WOW64 on 64-bit Windows. Therefore, use the PtrToPtr64 macro when assigning pointers to Buffer.

In Windows 8 and Windows Server 2012, this function is supported by the following technologies.

Technology	Supported
Server Message Block (SMB) 3.0 protocol	Yes
SMB 3.0 Transparent Failover (TFO)	Yes
SMB 3.0 with Scale-out File Shares (SO)	Yes
Cluster Shared Volume File System (CsvFS)	Yes
Resilient File System (ReFS)	Yes

Transacted Operations

If there is a transaction bound to the file handle, then the function returns data from the transacted view of the file. A transacted read handle is guaranteed to show the same view of a file for the duration of the handle.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	fileapi.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll