Symantec logo

FCL record

An application reads the FCL file through the vxfs_fcl_read function. vxfs_fcl_read performs the following tasks:

Each fcl_record structure represents a logical event recorded in the FCL. It is defined as the following:

struct fcl_record {

uint32_t fr_reclen; /* Record length */

uint16_t fr_op; /* Operation type. */

uint16_t fr_unused1; /* unused field */

uint32_t fr_acsinfovalid : 1; /* fr_acsinfo field valid */

uint32_t fr_newnmvalid : 1; /* fr_newfilename field is valid */

uint32_t fr_pinogenvalid : 1; /* fr_fr_pinogen field is valid */

uint32_t fr_unused2 : 29; /* Future use */

uint64_t fr_inonum; /* Inode Number. */

uint32_t fr_inogen; /* Inode Generation Count. */

fcl_time_t fr_time; /* Time. */

union fcl_vardata {

char *fv_cmdname;

struct fcl_nminfo fv_nm;

struct fcl_iostats *fv_stats;

struct fcl_evmaskinfo fv_evmask;

} fr_var;

uint64_t fr_tdino; /* Target dir ino */

char *fr_newfilename; /* For rename */

struct fcl_acsinfo *fr_acsinfo; /* Access Info */

};

struct fcl_nminfo {

uint64_t fn_pinonum; /* Parent Inode Number. */

uint32_t fn_pinogen; /* Parent Inode Gen cnt. */

char *fn_filename;

};

struct fcl_evmaskinfo {

uint64_t oldmask; /* Old event mask. */

uint64_t newmask; /* New event mask. */

};

Defines

These defines are provided for easier access:
#define fr_cmdname
fr_var.fv_cmdname
#define fr_stats
fr_var.fv_stats
#define fr_oldmask
fr_var.fv_evmask.oldmask
#define fr_newmask
fr_var.fv_evmask.newmask
#define fr_pinonum
fr_var.fv_nm.fn_pinonum
#define fr_pinogen
fr_var.fv_nm.fn_pinogen
#define fr_filename
fr_var.fv_nm.fn_filename

fcl_iostats structure

VxFS 5.0 gathers file I/O statistics such as the number of reads /writes occurring on a file. The gathered statistics are maintained in a per-file in-core structure and the File Change Log acts as a persistent backing store for the statistics. The stats are written to the FCL under the following circumstances:

These statistics can be read from the FCL as VX_FCL_FILESTAT records. Each record contains information as defined by the following fcl_iostat structure:

struct fcl_iostats {

uint64_t nbytesread; /* Number of bytes read from the file*/

uint64_t nbyteswrite; /* Number of bytes written to the file*/

uint32_t nreads; /* Number of reads from the file */

uint32_t nwrites; /* Number of writes to the file */

uint32_t readtime; /* Total time in seconds for the reads */

uint32_t writetime; /* Total time in seconds for the writes */

struct {

uint32_t tv_sec;

uint32_t tv_nsec;

} lastreset; /* Last reset time for the stats */

uint32_t nodeid; /* Node from which the record was written */

uint32_t reset; /* Stats have been written due to a reset */

};

Each iostat record in the FCL contains I/O statistics accumulated over the time interval from the lastreset time to the next lastreset time. Over a period of time, the cumulative statistics and aggregate can be computed by the following:

For example, computing the aggregate for the total number of reads over a period of time requires traversing a set of FCL files to obtain I/O statistics records. This informations contains a sequence of records of the type VX_FCL_FILESTATS with the same lastreset time followed by another sequence of records with a later lastreset time for a specific file.

The aggregation considers values only from the latest record from records with the same lastreset time and then sums up the number of reads for each such record.

fcl_acsinfo structure

When tracking access-info is enabled, VxFS logs the access information such as:

When the application reads the FCL, the information is returned in the fr_acsinfo field. The fr_acsinfo points to an FCL_acsinfo structure, defined as follows:

struct fcl_acsinfo {

uint32_t fa_ruid;

uint32_t fa_rgid;

uint32_t fa_euid;

uint32_t fa_egid;

uint32_t fa_pid;

uint32_t fa_nodeid;

};


  Note   The accessinfo is not returned as a separate record type but as additional information along with the other records. In addition, the accessinfo information is not always present with every record (if it is not enabled). However, even when accessinfo is enabled in some file system internal operations, (such as truncating a file), the access information may not always be present. To help determine if access information is available, the FCL record contains a flag called fcl_acsinfovalid which is non-zero only if the accessinfo is present with a particular record.


Several of the fields in the fcl_acsinfo structure are pointers and need memory to store the actual contents. This is handled by storing the actual data immediately after the FCL record, and updating the pointer to point to the data. The record length fr_reclen field is updated to account for the whole data. Thus, each FCL record returned by vxfs_fcl_read is a variable size record, whose length is indicated by fr_reclen_field. Sample link record shows how the data is laid out in a sample link record.

Click the thumbnail above to view full-sized image.

Sample link record

The following code sample traverses the set of records returned by a call to vxfs_fcl_read and prints the user ID:

Struct fcl_record *fr;

Char *tbuf;

...

error = vxfs_fcl_read(fh, buf, &bufsz,

FCL_ALL_V4_EVENTS,

&nentries);

tbuf = buf;

while (--nentries) {

fr = (struct fcl_record *)tbuf;

if (fr->fr_acsinfovalid) {

printf("Uid %ld\n", fr->fr_acsinfo->uid;

}

tbuf += fr->fr_reclen;

}


  Note   FCL_ALL_V4_EVENTS are event masks.

See "vxfs_fcl_read" on page 29.


Record structure fields

FCL record structure fields briefly describes each field of the fcl_record structure and indicates the record types for which it is valid.

FCL record structure fields

Field

Description

Validity

fr_reclen 

Length of the FCL record. This includes length of the FCL record structure and length of the data stored immediately following the structure. This length should be used while traversing FCL records returned in the buffer by vxfs_fcl_read

Valid for all records. 

fr_inonum  

The inode number of the file being changed. To generate the full path name of the changed object, the inode number and generation count (fr_inogen) can be used with vxfs_inotopath_gen

Valid for all FCL records except when the record is FCL_EVNTMSK_CHG. For event mask change the file is implicitly the FCL file. 

fr_op 

The operation for this FCL record, for example, creation, unlink, write, file attributes change, or other change. fr_op takes on one of the values for the record types listed in Table 2-1. 

Use this parameter to determine which fields of the FCL record are valid.  

Valid for all records. 

fr_time 

The approximate time when the change was recorded in the FCL file. Use the ctime call to interpret this field. 

Valid for all records. 

fr_inogen 

The generation count of the changed file. The generation count in combination with the inode number (of the file) is passed to vxfs_inotopath_gen to provide the exact full path name of the object. Without the generation count, the returned path name can be a re-used inode.  

Valid for all FCL records except for event mask changes and unlinks. For event mask changes, the inode number and generation count are implicit. For unlink, the generation count is not needed to get the file name via reverse name lookup, since it is already present with the record. 

fr_pinonum 

fr_pinogen 

fr_filename 

For FCL records like file remove or rename, where the directory entry is removed, the file name cannot be determined by reverse name lookup. Similarly in the case of link record, the file name cannot be determined unambiguously. Therefore in these cases, the file name, inode number, and generation count of the parent directory (containing the file being changed) is recorded. The parent directory inode (fr_pinonum) and generation count (fr_pinogen) can be used with the reverse name lookup API to identify the full path name of the parent directory. Adding the trailing file name yields the object's full name. 

Valid when the FCL record is VX_FCL_UNLINK, VX_FCL_RENAME or VX_FCL_LINK. The unlink and rename; file name and the parent inode number; and generation count; contain information about the old file that was removed. For the link, they represent the new file name. 

fr_cmdname 

A short name of the command which opened the file represented by fr_inonum and fr_inogen

Valid only when the FCL record is VX_FCL_FILEOPEN

fr_stats 

A pointer to an FCL_iostat record. The fcl_iostat record contains I/O statistics such as the number of reads/ writes that happened on the file, average time for a read/ write, etc. These point-in-time records can be used to compute the aggregate or average I/O statistics for a file over a period of time. 

Valid only when the FCL record is VX_FCL_FILESTATS

fr_oldmask 

fr_newmask 

These fields contain the old and new event masks, respectively. Each event mask is a "logical or" of a set of masks defined in fcl.h

Valid only when the FCL record is VX_FCL_EVNTMASK_CHG

fr_acsinfo 

A pointer to an FCL_acsinfo structure. This structure contains information such as the user and group ID of the application that performed the particular operation, the process id and the ID of the accessing node.  

Validity is determined by the fcl_acsinfovalid bit-field. It can potentially exist with all kinds of records. This is an optional field.