The API uses the following type of functions:
These are general functions for accessing FCL records:
Users have the option to seek to a particular point in the File Change Log based on the offset from where they left off, or to the first record after a specified time. The following functions can seek offsets and time stamps in the FCL:
int vxfs_fcl_open(
char *pathname, int flags, void **handle
);
This function opens the FCL file and returns a handle which should be used for all further accesses to the FCL through the API (for example, vxfs_fcl_read
, vxfs_fcl_seek
, etc.).
vxfs_fcl_open
has two parameters: *pathname
and **handle
. The *pathname
can either be a pointer to an FCL file name or a mount point. If *pathname
is a mount point, vxfs_fcl_open
automatically determines if the FCL is activated on the mount point and opens the FCL file associated with the mount point (currently mount_point
/lost+found/changelog
).
vxfs_fcl_open
then determines if it is a valid FCL file, and if the FCL file version is compatible with the library. The vxfs_fcl_open
function then assimilates meta-information about the FCL file into an opaque internal data structure and populates **handle
with a pointer.
Just like the lseek
(2) and read
(2) system calls, the FCL file **handle
has an internal offset to indicate the position in the file from where the next read starts. When the FCL file is successfully opened, this offset is set to the first valid offset in the FCL file.
Upon successful completion, a "0" is returned to the caller and the handle is non-NULL. Otherwise, the API returns a non-zero value is and the handle is set to NULL. The global value errno is also set to indicate the error.
vxfs_fcl_close
closes the FCL file referenced by the handle. All data structures allocated with this handle are cleaned. You should not use this handle after a call to vxfs_fcl_close
.
void vxfs_fcl_close
(void *handle
)
*handle
is a valid handle returned by the previous call to vxfs_fcl_open
.
int vxfs_fcl_getinfo(
void *handle, struct fcl_info*fclinfo
);
The vxfs_fcl_getinfo
function returns information about the FCL file in the FCL information structure pointed to by fcl_info
. It obtains this information from the FCL superblock.
An intelligent application that is aware of the record types associated with each FCL version can use fcl_version
to determine whether the FCL file contains the needed information. For example, with a Version 3 FCL, an intelligent application can infer that there is no access information in the FCL record. In addition, if the fcl_state
is FCLS_OFF
, the application can also infer that there are no records added to the FCL file due to file system activity.
A "0" indicates success; otherwise, the errno is set to error and a non-zero value is returned.
This function lets the application read the actual file or directory change information recorded in the FCL as logical records. Each record returns a struct fcl_record
type.
vxfs_fcl_read
lets the application specify a filter comprising a set of desired events.
int vxfs_fcl_read(
void *hndl, char *buf, size_t *bufsz, uint64_t eventmask, uint32_t *nentries
);
This function has the following input:
*hndl
is a pointer returned by a previous call to vxfs_fcl_open
*buf
is a pointer to a buffer of size at least *bufsz
*bufsz
specifies the buffer size
eventmask
is a bit-mask that specifies a set of events which is of interest to the application. It should be a "logical or" of a set of event masks specified in the fcl.h
header. For example, if the eventmask
is (VX_FCL_CREATE_MASK | VX_FCL_UNLINK_MASK
), vxfs_fcl_read
returns only file create and delete records. If an application needs to read all the records listed in FCL record types, it can specify a default eventmask
mask as FCL_ALL_V4_EVENTS
. This returns all valid Version 4 FCL records in the FCL file.
Note
If VX_FCL_EVNTMASKCHG_MASK
is set in eventmask
and the records returned by vxfs_fcl_read
contain a VX_FCL_EVNTMASK_CHG
record, it is always the last record in the buffer. This lets the application readjust the eventmask
if required. In addition, if the application discovers from the eventmask
change record that a particular event is no longer recorded, it can decide to stop further reading.
*nentries
specifies the number of entries that should be read into the buffer in this call to vxfs_fcl_read.
If *nentries
is "0," vxfs_fcl_read
reads as many entries as will fit in the buffer. If *nentries
is a non-zero and the number of available records is less than *nentries
, vxfs_fcl_read
reads as many entries as are available and updates *nentries
to reflect the number of entries read.
*buf
contains *nentries
FCL records of the struct fcl_record
type if there is no error.
If the requested number of entries (*nentries
) cannot fit in the buffer size, an FCL_ENOSPC
error is returned. In this case, *bufsz
is updated to contain the buffer size required for the requested number of records. The application may use this to reallocate a larger sized buffer and invoke vxfs_fcl_read
again. *bufsz
is not changed if there is no error.
Even in the case where vxfs_fcl_read
returns an FCL_ENOSPC, it might try to read incomplete FCL records into the buffer. Therefore the contents of the buffer should not be trusted.
*nentries
is updated to contain the number of entries read in the buffer when vxfs_fcl_read
is called and there is no error. *nentries
and the returned value are both zero when the application has reached the end of file and there are no more records to be read.
Caution
When the number of available records is less than *nentries
, and an FCL_ENOSPC error is returned, the buffer may contain erroneous data..
A "0" indicates success; a non-zero indicates an error.
Note
FCL_ENOSPC
is returned if there is not enough space in the buffer to store the current record. The minimum size the buffer must be is returned in *bufsz.
After a successful call to vxfs_fcl_read
, the current file position is advanced, so that the next call to vxfs_fcl_read
reads the next set of records.
vxfs_fcl_copyrec
copies an FCL record of length len
from *src
to *tgt
and relocates the pointers in the target FCL record to point to copies of the data in *src
. A special operation to copy FCL records is needed because a simple memory copy of the FCL record from *src
to *tgt
leaves the pointers in *tgt
pointing to the data in source FCL record, instead of copies of the data. This may cause problems when the memory for the source FCL record is re-used.
int vxfs_fcl_copyrec
(struct fcl_record *src
, struct fcl_record *tgt
, size_t len
);
*src
must point to a valid fcl_record
structure
len
passed should be the length of the source FCL record, represented by the fr_reclen
field of the source FCL record.
*tgt
must point to a non-null memory address used to hold the target FCL record.
Note
The caller of vxfs_fcl_copyrec
must ensure that the space required to hold the target FCL record is allocated (i.e., at least the len
bytes).
The vxfs_fcl_getcookie
and vxfs_fcl_seek
functions are effective methods for remembering a position in the FCL file that the application had processed earlier. This then can be used as a restarting point. This is a highly useful tool for applications.
The vxfs_fcl_getcookie
function returns an opaque fcl_cookie
structure which embeds information comprising the current activation time of the FCL file and an offset indicating the current position in the FCL file. This cookie can be passed into vxfs_fcl_seek
to seek to the position in the FCL file defined by the cookie.
A typical incremental backup or index-update program can read to the end of the FCL file and perform actions based on the FCL records. The application can get information about the current position in the FCL file using vxfs_fcl_getcookie
and then store the cookie in a persistent structure such as a file. The next time the application needs to perform an incremental operation, it reads the cookie and passes it to vxfs_fcl_seek
to seek to the point where it left off. This enables the application to read only the new FCL records.
int vxfs_fcl_getcookie
(void *handle, struct fcl_cookie *cookie
)
*handle
is the FCL file handle returned by a call to vxf_fcl_open
*cookie
is a pointer to an opaque data block defined as follows:
The data stored in the cookie is internal to the VxFS library. The application should not assume any internal representation for the cookie or tamper with the data in the cookie.
You can use vxfs_fcl_seek
to seek to the start or end of an FCL file depending on the flag passed to it.
int vxfs_fcl_seek
(void *handle, struct fcl_cookie *cookie, int where
)
handle
should be the same handle that was returned by the most recent call to vxfs_fcl_open
. This is not necessarily the same handle used in vxfs_fcl_getcookie
. The application may open the FCL file, get the cookie, and close the FCL file in one session, and then open the FCL file and submit the saved cookie in a later session. For each open session on the FCL file, the valid handle is the one returned by vxfs_fcl_open
for that session.
vxfs_fcl_getcookie:
It is the responsibility of the user application to decide which FCL file is valid for a particular cookie and to use them in a sensible combination.
Note
*cookie may be NULL if where is FCL_SEEK_START
or FCL_SEEK_END
.
FCL_SEEK_START,
FCL_SEEK_END, FCL_SEEK_COOOKIE
.
FCL_SEEK_START
or FCL_SEEK_END
, the *cookie argument is ignored and vxfs_fcl_seek
seeks to either the start or end of the FCL file respectively, that is, where the first FCL record starts or where the last record ends
FCL_SEEK_COOKIE
, vxfs_fcl_seek
extracts the activation time and offset stored in the *cookie
If the FCL has been de-activated (switched off) from the time the application last did a vxfs_fcl_getcookie
function, or if the record at the offset contained in the *cookie was purged by a hole-punch, vxfs_fcl_seek
returns an FCL_EMISSEDRECORD
error. If not, vxfs_fcl_seek
sets the current file position to the offset contained in the cookie. Further calls to vxfs_fcl_read
return records from this offset.
A "0" indicates success; a non-zero indicates an error.
Note
vxfs_fcl_seek
returns FCL_EMISSEDRECORD
if the FCL has been reactivated, i.e., the activation time in FCL is different than that passed in the cookie, or the first valid offset in the FCL file is greater than the offset present in the cookie.
The vxfs_fcl_seektime
function seeks to the first record in the FCL file that has a time stamp greater than or equal to the specified time.
int vxfs_fcl_seektime
(void *handle, struct fcl_timeval time
)
*handle
is a valid handle returned by a previous call to vxfs_fcl_open
time
is an fcl_time_t
structure type defined as follows:
Note
The time specified in fcl_time_t
may be in seconds or nanoseconds, while the time that is returned by a standard system call such as gettimeofday
may be in seconds or microseconds. Therefore, a conversion may be needed.
vxfs_fcl_seektime
assumes that the entries in the FCL are in a non-decreasing order of the time stamps and does a faster-than-linear (binary) search to determine the FCL record with a time stamp greater than the specified time. This means that vxfs_fcl_seektime
can seek to a different record when compared to a seek done through a linear search.
As a result, the vxfs_fcl_seektime
interface is not 100% reliable. Under the following circumstances, the time stamps in the FCL might be out-of-order:
Caution
On a cluster file system, you must use a mechanism to keep the system clocks in sync (for example, Network Time Protocol—NTP), to help ensure that the vxfs_fcl_seektime
interface is kept reasonably accurate.
vxfs_fcl_seektime
returns "0" on success. If there are no records at or after the time
parameter, vxfs_fcl_seektime
returns EINVAL
.
The vxfs_fcl_sync
function sets a synchronization point within the FCL file. This function is kept for backward compatibility.
Before the availability of the VxFS 5.0 API to access the FCL file, applications would typically call vxfs_fcl_sync
to get the FCL to a stable state and set an offset in the FCL file to use as a reference point to stop reading. The application would then store the offset and use it to determine files changes since the last FCL read time. A vxfs_fcl_sync
call would then check if a file had been written to or opened. At least one corresponding write or open record would appear in the FCL after the synchronization offset. This would happen even if the time specified by fcl_winterval
or fcl_ointerval
had not elapsed since the last record was written.
With the VxFS 5.0 API FCL access, synchronization is now done automatically when the FCL file is opened through vxfs_fcl_open
. The vxfs_fcl_open
function sets a synchronization point and determines a reference end offset internally.
int vxfs_fcl_sync
(char *fname, uint64_t *offp
);
vxfs_fcl_sync
brings the FCL file to a stable state and updates *offp
with an offset that can be used by the application as a reference point.