FSCTL_QUERY_FILE_LAYOUT control code

The FSCTL_QUERY_FILE_LAYOUT control code retrieves file layout information for a file system volume. The results of this request are a collection of file layout information entries. The type of entries returned is controlled by setting inclusion flags in the QUERY_FILE_LAYOUT_INPUT structure. You can optionally filter the results by providing a set of file extents to restrict the selection of layout information.

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

Parameters

FileObject

FltFsControlFile only. A file object pointer for the file system volume. This parameter is required and cannot be NULL.

FileHandle

ZwFsControlFile only. A file handle for the file system volume. This parameter is required and cannot be NULL.

FsControlCode

The control code for the operation. Use The FSCTL_QUERY_FILE_LAYOUT control code for this operation.

InputBuffer

A pointer to a caller-allocated QUERY_FILE_LAYOUT_INPUT structure. This structure contains the selection options. The optional file extents are included after QUERY_FILE_LAYOUT_INPUT.

InputBufferLength

The size, in bytes, of the buffer pointed to by the InputBuffer parameter. The size of InputBuffer must be at least sizeof(QUERY_FILE_LAYOUT_INPUT) + (sizeof(Filter) * (NumberOfPairs - 1)), when NumberOfPairs > 0. Otherwise, set InputBufferLength = sizeof(QUERY_FILE_LAYOUT_INPUT).

OutputBuffer

A pointer to a caller-allocated QUERY_FILE_LAYOUT_OUTPUT structure. This is the header for the file layout entries that follow in this buffer.

OutputBufferLength

The size, in bytes, of the buffer pointed to by the OutputBuffer parameter. The size of OutputBuffer must be large enough to contain a QUERY_FILE_LAYOUT_OUTPUT along with the file layout and stream layout structures returned.

Return Value

FltFsControlFile or ZwFsControlFile returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as one of these values:

STATUS_INVALID_PARAMETER

The file system volume is not an open user volume, or a buffer length value is incorrect, or an invalid query option is set.

STATUS_ACCESS_DENIED

The caller cannot access the file system volume.

STATUS_INVALID_USER_BUFFER

The pointer for either InputBuffer or OutputBuffer is not properly aligned.

STATUS_BUFFER_TOO_SMALL

The value in OutputBufferLength indicates that OutputBuffer is too small to contain at least one layout entry.

STATUS_END_OF_FILE

There are no more layout entries to return.

Remarks

To retrieve all the layout entries for a volume, the FSCTL_QUERY_FILE_LAYOUT request is issued multiple times until STATUS_END_OF_FILE is returned. While STATUS_SUCCESS is returned, a caller can continue to send an FSCTL_QUERY_FILE_LAYOUT request for the remaining layout entries.

The enumeration of layout entries may be restarted at any time by including the QUERY_FILE_LAYOUT_RESTART flag in the Flags member of QUERY_FILE_LAYOUT_INPUT. Also, after FSCTL_QUERY_FILE_LAYOUT has returned STATUS_END_OF_FILE, it is necessary to include the QUERY_FILE_LAYOUT_RESTART flag in the next FSCTL_QUERY_FILE_LAYOUT request to begin another layout entry enumeration.

ReFS:  This code is not supported.

Requirements

Version

Available starting in Windows 8.

Header

Ntifs.h (include Ntifs.h)

See also

QUERY_FILE_LAYOUT_INPUT
QUERY_FILE_LAYOUT_OUTPUT
FltFsControlFile
ZwFsControlFile

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft