zGetFileMap

Returns an extent list for a file object and indicates which bytes are allocated.

Service:File System Services (64-Bit)

Syntax

#include <zPublics.h>

STATUS zGetFileMap(
   Key_t   key,
   Xid_t   xid,
   QUAD    startingOffset,
   NINT    extentListFormat,
   NINT    bytesForExtents,
   void   *retExtentList,
   QUAD   *retEndingOffset,
   NINT   *retExtentListCount);

Parameters

key

(IN) Specifies the file whose file map will be retrieved, as returned by zOpen or zCreate.

xid

(IN) Specifies the transaction associated with this request. If the requested action is not part of a transaction, pass in zNILXID.

startingOffset

(IN) Specifies the starting byte offset in the file at which the extent list is to begin. To get an extent list of the whole file, pass zero. If multiple calls are being made, pass the value of retEndingOffset that was returned by a previous function iteration.

extentListFormat

(IN) Specifies what format the extent list information should be returned in:

zFILEMAP_ALLOCATION

Returns a map of what portions of the file are physically allocated versus what portions are sparse. This is useful for operations such as backing up sparse files where only data that is actually allocated to a file object needs to be processed and all sparse holes in the file need to be ignored. If the file is not sparse, a single extent describing the entire file is returned.

zFILEMAP_LOGICAL

Returns a map of the logical extents being used on the volume, which shows how fragmented a file is. This is useful for operations like defragging because it can determine how fragmented a file is. Each extent contains exactly one entry for every allocation fragment in the file, even if the extents are logically adjacent to each other.

zFILEMAP_PHYSICAL

Returns a map of the physical blocks being used including what physical devices the blocks are on. This is useful for operations like backup where the backup devices can directly communicate with each other. Each extent contains information describing exactly where this file object’s data is physically stored.
bytesForExtents

(IN) Specifies the size (in bytes) of the retExtentList buffer. As many extent list elements as will fit in the buffer are returned. Each extent list element contains information for one extent. The size of an extent list element varies based on the format of the extent being returned.

retExtentList

(IN/OUT) Points to a preallocated buffer, which is filled in with an array of extent list elements. The number of extents returned is based on the size of this buffer. If the passed buffer is large enough to hold only one extent, retEndingOffset must be passed as the starting offset to get additional extents until zERR_END_OF_FILE is returned.

retEndingOffset

(OUT) Points to the the ending byte offset at which the last returned extent ends, which can be passed to a subsequent function iteration to get additional information.

retExtentListCount

(OUT) Points to the number of extent list elements for which information was returned in the retExtentList buffer.

Return Values

zERR_END_OF_FILE

All extents have been returned (in which case retEndingOffset is irrelevant).

Remarks

To guarantee that the information returned by zGetFileMap does not change, the file should be opened with zRR_DENY_WRITE for the requested rights.

If all of the file returned extent list elements do not fit in the retExtentList buffer, zGetFileMap can be called multiple times to return the complete file map information.

Each extent element identifies a different fragment of the file on a physical device (like a hard disk). All fragments, including sparse ones, are represented by an extent.

See Also

zCreate, zOpen