JCL Help:NtfsQueryAllocRanges
JCL Help: NtfsQueryAllocRanges Function
Search in JCL Help
Search in all projects
Summary
Queries the specified sparse file for the ranges that are actually allocated.
Pascal
function NtfsQueryAllocRanges(const FileName: string; Offset: Int64; Count: Int64; var Ranges: TNtfsAllocRanges): Boolean;
Parameters
| Parameters | Description |
| const FileName: string | The name of the file whose allocated ranges you want to know. |
| Offset: Int64 | The starting offset, in bytes, of the range to query. |
| Count: Int64 | The length, in bytes, of the range to query. |
| Range | On return contains the allocated ranges in the specified file within the boundaries of the specified range (Offset..Offset + Length). |
Return Value
If the function succeeds the function returns True, otherwise it returns False.
Description
A sparse file is a normal file but one which only uses disk space for those portions of the file that actually contain data. This however is not automatic, see the other NtfsXxxx functions and the Platform SDK for details. The NtfsQueryAllocRanges function queries the filesytem about the ranges of the specified sparse file that actually contain data and as such occupy disk space. For a normal, non-sparse file, the returned range is always 0 - FileSize. However, for a sparse file any number of ranges are possible. This function assumes that the file contains at most 256 ranges. If the file contains more ranges only the first 256 are returned. To query for the other ranges call NtfsQueryAllocRanges again, this time starting at offset = Entry.FileOffset + Entry.Length and with count = FILE_SIZE - offset (FILE_SIZE is the total size of the file and Entry is the last entry returned by the previous call). The TNtfsAllocRanges.MoreData is set to True if the file contains more than 256 ranges. You can use the NtfsGetAllocRangeEntry function to extract the individual ranges from the returned Ranges variable.
See Also
NtfsSetSparse TNtfsAllocRanges NtfsGetAllocRangeEntry
About
Unit
Donator
Marcel van Brakel
Notes
The caller is responsible for freeing the memory associated with the Data member of the TNtfsAllocRanges record. Sparse files are only supported by NTFS version 5.0 and higher.
Contribute to this help topic
This documentation wiki is based on the collaborative effort of Project JEDI users. Your edits are welcome in order to improve documentation quality: edit this page
