FSCTL_GET_RETRIEVAL_POINTERS control code

The FSCTL_GET_RETRIEVAL_POINTERS control code retrieves a variably sized data structure that describes the allocation and location on disk of a specific file. The structure describes the mapping between virtual cluster numbers (VCN, offsets within the file/stream space) and logical cluster numbers (LCN, offsets within the volume space).

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

For more information about reparse points and the FSCTL_GET_RETRIEVAL_POINTERS control code, see the Microsoft Windows SDK documentation.

Parameters

FileObject

FltFsControlFile only. A file object pointer for the alternate stream, file, or directory for which FSCTL_GET_RETRIEVAL_POINTERS retrieves a mapping. This parameter is required and cannot be NULL.

FileHandle

ZwFsControlFile only. A file handle for the alternate stream, file, or directory for which FSCTL_GET_RETRIEVAL_POINTERS retrieves a mapping. If the value in FileHandle is the handle for an entire volume, the routine returns a map of the VCNs and extents for the bad clusters file. This parameter is required and cannot be NULL.

FsControlCode

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

InputBuffer

A pointer to a STARTING_VCN_INPUT_BUFFER structure that indicates the virtual cluster number (VCN) that marks the beginning of the alternate stream, file, or directory. The STARTING_VCN_INPUT_BUFFER structure is defined as follows:


typedef struct {
  LARGE_INTEGER  ;
} STARTING_VCN_INPUT_BUFFER, *PSTARTING_VCN_INPUT_BUFFER;

Members

StartingVcn

The VCN at which FSCTL_GET_RETRIEVAL_POINTERS begins enumerating extents and the associated virtual and logical cluster numbers. On the first call to FltFsControlFile or ZwFsControlFile with a file system control code of FSCTL_GET_RETRIEVAL_POINTERS, StartingVcn should be set to zero.

If OutputBuffer is not large enough to hold the entire map of VCNs and extents for the file, the caller must request more map data by using the value returned in the NextVcn member of the RETRIEVAL_POINTERS_BUFFER structure as the starting VCN.

InputBufferLength

Length, in bytes, of the input buffer at InputBuffer.

OutputBuffer

A pointer to a variably sized structure of type RETRIEVAL_POINTERS_BUFFER that contains an enumeration of the extents on the disk that correspond to the alternate stream, file, or directory:


typedef struct RETRIEVAL_POINTERS_BUFFER {
 ULONG  ExtentCount;
  LARGE_INTEGER  StartingVcn;
 struct {
    LARGE_INTEGER  NextVcn;
    LARGE_INTEGER  Lcn;
  } Extents[1];
} RETRIEVAL_POINTERS_BUFFER, *PRETRIEVAL_POINTERS_BUFFER;

Members

ExtentCount

Count of elements in the Extents array.

StartingVcn

Starting VCN returned by the function call. This is not necessarily the VCN requested by the function call, as the file system driver might round down to the first VCN of the extent in which the requested starting VCN is found.

Extents

Array of extents structures. For the number of members in the array, see ExtentCount. Each member of the array has the following members.

NextVcn

The VCN at which the next extent begins. This value minus either StartingVcn (for the first Extents array member) or the NextVcn of the previous member of the array (for all other Extents array members) is the length, in clusters, of the current extent.

Lcn

The LCN at which the current extent begins on the volume. On NTFS, the value (LONGLONG) -1 indicates either a compression unit that is partially allocated, or an unallocated region of a sparse file.

OutputBufferLength

Size, in bytes, of the buffer pointed to by the OutputBuffer parameter.

Return Value

FltFsControlFile and ZwFsControlFile both return STATUS_SUCCESS or an appropriate NTSTATUS error value.

If the VCN / extents map does not fit in OutputBuffer, both routines return a value of STATUS_BUFFER_OVERFLOW, and the caller must request more map data using the value returned in the NextVcn member of the RETRIEVAL_POINTERS_BUFFER structure as the starting VCN (StartingVcn) in the next call to FltFsControlFile or ZwFsControlFile.

If the value that is specified in StartingVcn is beyond the end of the file, STATUS_END_OF_FILE is returned.

Remarks

The FSCTL_GET_RETRIEVAL_POINTERS control code can be used on FastFAT and exFAT devices. This capability supports the use of BitLocker for devices such as flash drives.

Requirements

Header

Ntifs.h (include Ntifs.h)

See also

FltFsControlFile
ZwFsControlFile

 

 

Send comments about this topic to Microsoft

Show: