fsckpt_fbmap - retrieve block map from a Storage Checkpoint file
int fsckpt_fbmap(void *filehandle, ckptoff_t *off, struct c_extent *cep);
fsckpt_fbmap() retrieves the block map from a Storage Checkpoint filehandle at file offset off. The structure c_extent pointed to by cep is filled in by this function and contains the following fields:
ckptoff_t ce_len; /* extent length */
unsigned int ce_flags; /* extent flags */
where flags are:
Every extent in the file has changed.
The extent at offset off has changed.
The current extent is not present in the old checkpoint. For example, if a file was 10K in the previous checkpoint and is now 20K in the new checkpoint, the 10K is marked as CE_EXTENDED.
The extent at offset off is a hole.
The information returned by this function can be used to determine the changed sections of a file. After obtaining the changed offset, an application may issue the lseek() and read() system calls at the specific offset to retrieve the requested data. When a file is completely changed, every offset will return the extent flag CE_ALLCHANGED. This can be used as an optimization to avoid unnecessarily repeated fsckpt_fbmap() calls. The CE_HOLE flag can be used to determine the location of all holes in a sparse file.
When the relckpt argument to the fsckpt_fopen() function is NULL, the fsckpt_fbmap() function returns the extent map of the opened file. This mode is useful for applications to find the holes in sparse files.
When the relckpt argument to the fsckpt_fopen() function is not NULL, fsckpt_fbmap() can determine the extents changed between the current Storage Checkpoint and a relative Storage Checkpoint. The result of such an operation returns the union of all changed blocks between the Storage Checkpoints in question.
The relative Storage Checkpoint must be an existing Storage Checkpoint.
The file offset specified by the argument off and the extent length specified by the ce_len field of the c_extent structure are declared to use the ckptoff_t type. This type is platform specific. It is defined as a 64-bit quantity on all platforms that support file offsets larger than two gigabytes, otherwise, it is defined as a 32-bit quantity.
Applications using this function must be compiled accordingly. Some platforms that can handle large files, however, have compilation options that allow an application to define the file offset as a 32-bit quantity. These applications either cannot use this function, or must ensure that they never operate on a Storage Checkpoint that is large file enabled (that is, has CI_LARGEFILES set).
fsckpt_fbmap() returns zero on success, non-zero on failure.
Internal API error.
The calling function issued a request with a file offset off past the EOF mark.
The function is being used incorrectly or the arguments to the function cannot be validated. This can occur when an application uses an fshandle that was not created by the same process.
An I/O error occurred on the device.
The relative Storage Checkpoint was removed.
The system is not licensed to perform the operation. The API issued a system request with an illegal address.
fsckptadm(1M), lseek(2), read(2), fsckpt_create(3), fsckpt_createall(3), fsckpt_fsopen(3), fsckpt_intro(3)