Symantec logo

API functions

The API uses the following type of functions:

Functions for accessing FCL records

vxfs_fcl_open

Opens the FCL file and returns a handle which can be used for further operations. All subsequent accesses of the FCL file through the API must use this handle. 

vxfs_fcl_close

Closes the FCL file and cleans up resources associated with the handle 

vxfs_fcl_getinfo

Returns the FCL version number along with the state (on/off) of the FCL file 

vxfs_fcl_read

Reads FCL records of interest to the user into a buffer passed in by the user 

vxfs_fcl_copyrec

Copies an FCL record. If the source record contains pointers, it relocates them to point to the new location. 

These are general functions for accessing FCL records:

Functions for seeking offsets and time stamps in the FCL

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:

vxfs_fcl_getcookie

Returns an opaque structure (referred hereinafter as a cookie) which embeds the current FCL activation time and the current offset. This cookie can be saved and later passed into vxfs_fcl_seek to continue reading from where the application left off last time. 

vxfs_fcl_seek

Extracts data from the cookie passed and seeks to the specified offset. A cookie is embedded with the FCL activation time and file offset  

vxfs_fcl_seektime

Seeks to the first record in the FCL after the specified time 

vxfs_fcl_open

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.


Return Value

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

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.


Parameters

void vxfs_fcl_close(void *handle)

*handle is a valid handle returned by the previous call to vxfs_fcl_open.

vxfs_fcl_getinfo

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.

struct fcl_info {

uint32_t fcl_version;

uint32_t fcl_state;

};

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.


Return Values

A "0" indicates success; otherwise, the errno is set to error and a non-zero value is returned.

vxfs_fcl_read

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.


Parameters

int vxfs_fcl_read(void *hndl, char *buf, size_t *bufsz, uint64_t eventmask, uint32_t *nentries);


Input

This function has the following input:


Output

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



Return Values

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

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.


Parameters

int vxfs_fcl_copyrec(struct fcl_record *src , struct fcl_record *tgt, size_t len);

vxfs_fcl_getcookie

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.

See "vxfs_fcl_seek" on page 32.

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.


Parameters

int vxfs_fcl_getcookie(void *handle, struct fcl_cookie *cookie)

struct fcl_cookie {

char fc_bytes[24];

};

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.

vxfs_fcl_seek

You can use vxfs_fcl_seek to seek to the start or end of an FCL file depending on the flag passed to it.

See "vxfs_fcl_getcookie" on page 31.


Parameters

int vxfs_fcl_seek(void *handle, struct fcl_cookie *cookie, int where)


Return values

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.


vxfs_fcl_seektime

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.


Parameters

int vxfs_fcl_seektime(void *handle, struct fcl_timeval time)

uint32_t tv sec;

unit32_t tv_nsec;

} fcl_time t;


  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:


Return values

vxfs_fcl_seektime returns "0" on success. If there are no records at or after the time parameter, vxfs_fcl_seektime returns EINVAL.

vxfs_fcl_sync

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.


Parameters

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.