FSCTL_GET_RETRIEVAL_POINTERS Control Code (Windows)

FSCTL_GET_RETRIEVAL_POINTERS Control Code

Retrieves a data structure that describes the allocation and location on disk of a specific file.

To perform this operation, call the DeviceIoControl function with the following parameters.

DeviceIoControl(
  (HANDLE) hDevice,              // handle to 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 device handle, call the CreateFile function.

Encrypted files must be opened with the FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA, or FILE_EXECUTE access rights. Other files can be opened with only the FILE_READ_ATTRIBUTES access right. For more information, see File Security and Access Rights.

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 view index (such as $Quota). 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_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 operation is supported on NTFS, FAT, and exFAT file systems.

Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP/2000: The ability to use FSCTL_GET_RETRIEVAL_POINTERS to optionally query for the locations of bad clusters on the volume by passing a volume handle is supported only on NTFS.

For supported file systems, the FSCTL_GET_RETRIEVAL_POINTERS operation returns the extent locations of nonresident data. Resident data never has extent locations.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

Requirements

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	WinIoCtl.h

Parameters

Return Value

Remarks

Requirements

See Also