fsckpt_fbmap

NAME

fsckpt_fbmap - retrieve block map from a Storage Checkpointed file

SYNOPSIS

AVAILABILITY

VRTSvxfs

DESCRIPTION

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:

where flags are:

CE_ALLCHANGED

Every extent in the file has changed.

CE_CHANGED

The extent at offset off has changed.

CE_HOLE

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).

RETURN VALUES

fsckpt_fbmap() returns zero on success, non-zero on failure.

ERRORS

EFAULT

Internal API error.

EFBIG

The calling function issued a request with a file offset off past the EOF mark.

EINVAL

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.

EIO

An I/O error occurred on the device.

ENOENT

The relative Storage Checkpoint was removed.

ENOSYS

The system is not licensed to perform the operation. The API issued a system request with an illegal address.

SEE ALSO

fsckptadm (1M), lseek(2), read(2), fsckpt_create (3), fsckpt_createall (3), fsckpt_fsopen (3), fsckpt_intro (3)