// ntifs.h
// CTL_CODE(0x0009, 0x01c, METHOD_NEITHER, FILE_ANY_ACCESS)
#define FSCTL_GET_RETRIEVAL_POINTERS 0x00090073
View the official Windows Driver Kit DDI reference// winioctl.h
// CTL_CODE(0x0009, 0x01c, METHOD_NEITHER, FILE_ANY_ACCESS)
#define FSCTL_GET_RETRIEVAL_POINTERS 0x00090073
View the official Win32 API reference// ntifs.h
// CTL_CODE(0x0009, 0x01c, METHOD_NEITHER, FILE_ANY_ACCESS)
#define FSCTL_GET_RETRIEVAL_POINTERS 0x00090073
View the official Windows hardware development documentationNo description available.
Given a file handle, the FSCTL_GET_RETRIEVAL_POINTERS control code retrieves a data structure that describes the allocation and location on disk of a specified file; or, given a volume handle, it retrieves the locations of bad clusters on the volume.
FSCTL_GET_RETRIEVAL_POINTERS
To perform this operation, call FltFsControlFile or ZwFsControlFile.
See FSCTL_GET_RETRIEVAL_POINTERS IOCTL (winioctl.h) for more information.
RETRIEVAL_POINTERS_BUFFER structure (winioctl.h)
Given a file handle, retrieves a data structure that describes the allocation and location on disk of a specific file, or, given a volume handle, the locations of bad clusters on a volume.
To perform this operation, call the DeviceIoControl function with the following parameters.
DeviceIoControl(
(HANDLE) hDevice, // handle to file, directory, or volume
FSCTL_GET_RETRIEVAL_POINTERS, // dwIoControlCode
(LPVOID) lpInBuffer, // input buffer
(DWORD) nInBufferSize, // size of input buffer
(LPVOID) lpOutBuffer, // output buffer
(DWORD) nOutBufferSize, // size of output buffer
(LPDWORD) lpBytesReturned, // number of bytes returned
(LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);
Irp->IoStatus.Status is set to STATUS_SUCCESS if the request is successful.
Otherwise, Status to the appropriate error condition as a NTSTATUS code.
For more information, see NTSTATUS Values.
The FSCTL_GET_RETRIEVAL_POINTERS operation 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 or stream space) and logical cluster numbers (LCN offsets within the volume space).
The FSCTL_GET_RETRIEVAL_POINTERS control code is supported for file or directory operations on NTFS, FAT, exFAT, UDF, and ReFS file systems.
On supported file systems, the FSCTL_GET_RETRIEVAL_POINTERS operation returns the extent locations of nonresident data. Resident data never has extent locations.
The FSCTL_GET_RETRIEVAL_POINTERS control code also supports the alternate functionality of locating bad clusters. To query for the locations of bad clusters on a volume formatted with NTFS, FAT, or exFAT, use a volume handle as the hDevice parameter. This functionality is supported only on NTFS, FAT, and exFAT, and the caller must have MANAGE_VOLUME_ACCESS permission to the volume.
For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.
In Windows 8 and Windows Server 2012, this code is supported by the following technologies.
| Technology | Supported |
|---|---|
| Server Message Block (SMB) 3.0 protocol | No |
| SMB 3.0 Transparent Failover (TFO) | No |
| SMB 3.0 with Scale-out File Shares (SO) | No |
| Cluster Shared Volume File System (CsvFS) | Yes |
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.
FileObject [in]: 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 [in]: 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 [in]: The control code for the operation. Use FSCTL_GET_RETRIEVAL_POINTER for this operation.
InputBuffer [in]: 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. StartingVcn is 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 [in]: Length, in bytes, of the input buffer at InputBuffer.
OutputBuffer [out]: 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.
OutputBufferLength [out]: Size, in bytes, of the buffer pointed to by the OutputBuffer parameter.
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.
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.
| Requirement type | Requirement |
|---|---|
| Header | Ntifs.h (include Ntifs.h) |