1 out of 3 rated this helpful - Rate this topic

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.

Copy

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
ERROR_INVALID_PARAMETER	One or more of the following: The handle used is not a file, directory, or volume. The size of the input buffer is smaller than `sizeof(STARTING_VCN_INPUT_BUFFER)`. The starting virtual cluster number (VCN) is less than zero. Another parameter is invalid.
ERROR_INSUFFICIENT_BUFFER	The size of the output buffer is smaller than `sizeof(RETRIEVAL_POINTERS_BUFFER)`.
ERROR_ACCESS_DENIED	The handle used was not created with sufficient access rights.
ERROR_NOT_READY	The volume is a supported file system volume and is unmounted.
ERROR_INVALID_USER_BUFFER	One or both of the buffers passed in were not within a valid address range.
ERROR_HANDLE_EOF	The volume is a supported file system volume and the requested starting VCN is past the end of the file.
NO_ERROR	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.
ERROR_MORE_DATA	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	WinIoCtl.h

FSCTL_GET_RETRIEVAL_POINTERS control code

Parameters

Return value

Remarks

Requirements

See also