fcladm

NAME

fcladm - VxFS File Change Log administration utility

SYNOPSIS

fcladm on mount_point
fcladm off mount_point
fcladm rm mount_point
fcladm state mount_point
fcladm sync mount_point
fcladm [-cdfghit] print offset mount_point

AVAILABILITY

VRTSvxfs

DESCRIPTION

The fcladm command performs online administration functions for the VERITAS File system File Change Log (FCL) feature. Activating, deactivating, and removing the FCL can be done only with the fcladm command on VxFS file systems.

Using the fcladm command, you can also set a synchronization point in the FCL, display the current FCL state, or print the contents of the FCL in ASCII format.

mount_point specifies the directory on which the file system is mounted.

offset specifies the offset in bytes into the FCL file from which to begin printing the contents.

The data within the FCL resides in the lost+found/changelog file, a quasi-regular file in the file system namespace. This file can be opened, read, and closed, and you can seek offsets within the file. However, to prevent corruption of the FCL, operations such as write, rename, and memory mapping are prohibited.

The contents of the FCL file are FCL records, file names, and the FCL on-disk super-block. An FCL record (struct fcl_ent) is a fixed-size data structure consisting of the information required to determine the changes that occurred in the file system:

struct fcl_ent {
    uint64_t        fe_ino;     /* inode number */
    uint64_t        fe_dino;    /* directory inode number */
    fcl_timeval32_t fe_time;    /* timestamp */
    uint32_t        fe_gen;     /* generation count */
    uint16_t        fe_type;    /* change type */
    uint16_t        fe_nmlen;   /* filename length */
};

..IP The information stored in struct fcl_ent includes the inode number for the file being changed, a time stamp indicating the time of the change, the generation count of the file, and the type of change that occurred. Additionally, the directory inode number for a file being removed, linked or renamed is stored with the name of the file and the length of the file name, although the file names immediately follow FCL remove, link or rename records. The file name stored with the link record is the target file name.

The following are the types of changes recorded by the FCL:

VX_FCL_INFO_CHG,         /* file info change */
VX_FCL_CREATE,           /* file create */
VX_FCL_LINK,             /* file link added */
VX_FCL_UNLINK,           /* file unlink / file deleted */
VX_FCL_RENAME,           /* file rename */
VX_FCL_UNDELETE,         /* file undelete */
VX_FCL_DATA_EXTNDWRITE,  /* file data extending write */
VX_FCL_DATA_OVERWRITE,   /* file data overwrite */
VX_FCL_DATA_TRUNCATE,    /* file data truncate */
VX_FCL_EATTR_CHG,        /* file extended attribute change */
VX_FCL_HOLE_PUNCHED,     /* file hole punched */
VX_FCL_SYMLINK,          /* symbolic link created */
VX_FCL_INOEX_CHG,        /* inode extent attributes changed */
VX_FCL_INORES_CHG        /* inode reservation changed */
VX_FCL_IMODE_CHG,        /* inode mode changed. */
VX_FCL_IOWN_CHG,         /* inode owner changed. */
VX_FCL_IGRP_CHG,         /* inode grp changed. */
VX_FCL_MTIME_CHG,       /* inode times changed. */

Applications can use the information stored in the FCL to determine the full path name of every file changed in the file system, based on several categories of changes. To obtain the full file path name from the root of the file system, the inode number acquired from the FCL record must be passed to the VxFS Reverse Name Lookup (RNL) API (see the vxlsino(1M), vxfs_inotopath(3) and vxfs_inotopath_gen(3) manual pages). In cases where the file was renamed or removed, the directory inode number can be given to the RNL API and, after the full path name from the root of the file system is ascertained for the directory in which the file resided, the file name stored in the FCL record can be appended to this path to get the full file path name. With the remove record the fe_gen field stored in the record is the generation count of the directory inode stored in the fe_dino field and not of the inode which has been removed.

The file generation count can be used to determine whether an inode number was reused in comparison with another FCL record with the same inode number.

The FCL on-disk super-block contains information about the current state of the FCL.

struct fcl_sb {
    uint32_t        fc_magic;       /* magic number */
    uint32_t        fc_version;     /* version number */
    fcl_state_t     fc_state;       /* state */
    uint32_t        fc_sync;        /* sync count */
    fcl_timeval32_t fc_atime;       /* activation time */
    uint64_t        fc_foff;        /* first valid offset */
    uint64_t        fc_loff;        /* last valid offset */
    uint32_t        fc_padding[2];  /* padding */
};

Every time an application starts to read from the FCL file, the super-block must be read to determine:

Whether the FCL is activated or deactivated
Whether the FCL has been active continuously since the last time that the application has read the FCL
The first and last valid offsets in the FCL that can be read from

The FCL can be turned off and on by a privileged user while the application is reading the FCL record. Under these circumstances, some changes to the file system may not be recorded in the FCL record. After reading the FCL record, the application must reread the super-block to verify that the FCL record is correct.

The magic number stored in the first four bytes of the FCL super-block can be used by applications to ensure that the file opened is the FCL file. The FCL version number is incremented whenever there is a layout change in the FCL super-block or FCL records.

Details on FCL data structures, types, and definitions are available in the /opt/VRTS/include/sys/fs/fcl.h header file.

CLUSTER FILE SYSTEM ISSUES

No cluster issues; command operates the same on cluster file systems.

NOTES

The synchronization point in the FCL can also be set using the VxFS FCL sync API (see the vxfs_fcl_sync(3) manual page).

fcladm operates only on file systems using the Version 6 or higher disk layout.

The VX_FCL_MTIME_CHG record is emitted when the time stamps of the inode are changed by an external event, such as by the touch command. During read or write access of the file, the record is not emitted for atime or mtime changes.

KEYWORDS

Activates the FCL on a mounted file system.

off

Deactivates the FCL on a mounted file system.

Removes the FCL file. You must deactivate the FCL before removing it.

state

Writes the current state of the FCL to the standard output.

sync

Returns the offset into the FCL file corresponding to the moment that the FCL sync occurs. This also resets the FCL write interval for data write records, which forces the next write to each file in the file system to write a record in the FCL.

print

Prints the FCL records starting from the specified offset to the end of the FCL file. Output displays in ASCII to standard out. If offset is 0, print displays the on-disk FCL super-block, which occupies the first block of the FCL file.

OPTIONS

The following options are valid only with the print keyword.

-c

Prints the change type field.

-d

Prints the directory inode number field. The directory inode is only stored in an FCL record when the record is either a VX_FCL_UNLINK or VX_FCL_RENAME FCL change type.

-f

Prints the file name field. The file name is only stored after an FCL record when the record is either a VX_FCL_UNLINK or VX_FCL_RENAME FCL change type.

-g

Prints the inode generation count field.

-h

Displays the field names before printing the contents of the FCL.

-i

Prints the inode number field.

-t

Prints the time stamp field.

EXAMPLES

To turn on the FCL for the file system mounted on /home:

# fcladm on /home

To turn off the FCL for a file system mounted on /export/data:

# fcladm off /export/data

The following example removes the FCL file for a file system mounted on /export/reports. The FCL must be OFF before it can be removed.

# fcladm rm /export/reports

Call fcl_sync to reset the write interval for data write records and to set a synchronization point in the FCL file for a file system mounted on /home/usr1. The offset into the FCL file at the moment that the fcl_sync occurred is written to standard output.

# fcladm sync /home/usr1

Obtain the current FCL state for a file system mounted on /home:

# fcladm state /home

Print in ASCII the on-disk FCL super-block from offset 0 to obtain information about the FCL for the file system mounted on /export/data:

# fcladm print 0 /export/data
magic a506fcf5  version 2
time 1087979247 930092  (Wed 23 Jun 2004 04:27:27 PM CST CDT)
state ON  sync 1
foff 1024  loff 63744

Print in ASCII the FCL records from offset 1024 into the FCL file for a file system with a 1K block size mounted on /home/usr2. Use the -h option to display the field names and the -citdf options to display the change type, inode number, timestamp, directory inode number, and file name for each record (directory inode numbers and file names are only stored in an FCL record for unlink and rename records). The offset argument must always be 32-byte aligned.

# fcladm -h -citdf print 0x400 /home/usr2
Change Type  Inode Number        Timestamp
Dir Inode Number    Filename
Create                         5 Thu Apr 10 13:49:54 2003
Extend                         5 Thu Apr 10 13:50:02 2003
Create                         6 Thu Apr 10 13:50:30 2003
Unlink                         6 Thu Apr 10 13:50:38 2003
                  2 bar

Note Because the FCL on-disk super-block occupies the first block of the FCL file, the first valid offset into the FCL file can be determined by reading the FCL on-disk super-block and checking the fc_foff field.

To change the time stamp of the inode with an external event:

# touch /export/data/x
# fcladm print 1024 /export/data/x
ItimeChg 4 20183 Thu 01 Jul 2004 12:51:10 AM CST

FILES

lost+found/changelog

The FCL file.

/opt/VRTS/include/sys/fs/fcl.h

The header file containing the data structures and definitions used by the FCL.

/etc/vx/tunefstab

VxFS tuning parameters table.


^ Return to Top	< Previous \| Next >

Product: File System Manual Pages for Storage Foundation
Manual: Maintenance Commands (1m)
VERITAS Software Corporation www.veritas.com