FCL record
An application reads the FCL file through the vxfs_fcl_read
function. vxfs_fcl_read
performs the following tasks:
-
Reads the data from the FCL file
-
Assembles the data into fcl_record structures
-
Fills the buffer passed in by the application with these records
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:
-
When the stats are reset
-
At periodic intervals
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:
-
Traversing the FCL
-
Looking for records of type
VX_FCL_FILESTATS
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:
-
The real and effective user and group ID of the accessing application
-
The node from where the file was accessed
-
The process id of the user application along with each record
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
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.
|