FSCTL_GET_RETRIEVAL_POINTERS control code
Applies to: desktop apps only
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
Parameters
- hDevice
-
A handle to the alternate stream, file, or directory for which file mapping is to be retrieved. To retrieve a handle, call the CreateFile function.
This handle must be opened with at least the FILE_READ_ATTRIBUTES access right for file mapping retrieval. For more information about access rights, see File Security and Access Rights.
This parameter can optionally be a handle to an NTFS volume. For more information, see the Remarks section.
- dwIoControlCode
-
The control code for the operation. Use FSCTL_GET_RETRIEVAL_POINTERS for this operation.
- lpInBuffer
-
A pointer to the input buffer, a STARTING_VCN_INPUT_BUFFER structure.
- nInBufferSize
-
The size of the input buffer, in bytes.
- lpOutBuffer
-
A pointer to the output buffer, a RETRIEVAL_POINTERS_BUFFER variably sized structure.
- nOutBufferSize
-
The size of the output buffer, in bytes.
- lpBytesReturned
-
A pointer to a variable that receives the size of the data stored in the output buffer, in bytes.
If the output buffer is too small, the call fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and lpBytesReturned is zero.
If lpOverlapped is NULL, lpBytesReturned cannot be NULL. Even when an operation returns no output data and lpOutBuffer is NULL, DeviceIoControl uses lpBytesReturned. After such an operation, the value of lpBytesReturned is meaningless.
If lpOverlapped is not NULL, lpBytesReturned can be NULL. If this parameter is not NULL and the operation returns data, lpBytesReturned is meaningless until the overlapped operation is complete. To retrieve the number of bytes returned, call GetOverlappedResult. If hDevice is associated with an I/O completion port, you can retrieve the number of bytes returned by calling GetQueuedCompletionStatus.
- lpOverlapped
-
A pointer to an OVERLAPPED structure.
If hDevice is opened without specifying FILE_FLAG_OVERLAPPED, lpOverlapped is ignored.
If hDevice is opened with the FILE_FLAG_OVERLAPPED flag, the operation is performed as an overlapped (asynchronous) operation. In this case, lpOverlapped must point to a valid OVERLAPPED structure that contains a handle to an event object. Otherwise, the function fails in unpredictable ways.
For overlapped operations, DeviceIoControl returns immediately, and the event object is signaled when the operation is complete. Otherwise, the function does not return until the operation is complete or an error occurs.
Return value
If the operation completes successfully, DeviceIoControl returns a nonzero value.
If the operation fails or is pending, DeviceIoControl returns zero. To get extended error information, call GetLastError.
The following table identifies the possible return values.
| Return code | Description |
|---|---|
|
One or more of the following:
|
|
The size of the output buffer is smaller than |
|
The handle used was not created with sufficient access rights. |
|
The volume is a supported file system volume and is unmounted. |
|
One or both of the buffers passed in were not within a valid address range. |
|
The volume is a supported file system volume and the requested starting VCN is past the end of the file. |
|
The output buffer contains the full list of VCN-to-LCN mappings from the starting VCN through to the end of the file or stream. |
|
The output buffer contains a partial list of VCN-to-LCN mappings for the file. More entries exist beyond this list, but the buffer is too small to include them. The caller should call again with a larger buffer, a higher starting VCN, or both. The first member of the return structure contains a count of extents actually returned. |
Remarks
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, and UDF 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.
Requirements
|
Minimum supported client | Windows XP |
|---|---|
|
Minimum supported server | Windows Server 2003 |
|
Header |
|
See also
- CreateFile
- Defragmentation
- DeviceIoControl
- Disk Management Control Codes
- FSCTL_GET_RETRIEVAL_POINTER_BASE
- GetLastError
- GetOverlappedResult
- GetQueuedCompletionStatus
- OVERLAPPED
- RETRIEVAL_POINTERS_BUFFER
- STARTING_VCN_INPUT_BUFFER
Send comments about this topic to Microsoft
Build date: 4/17/2012