fileset

Copy a file set

Syntax:

fileset [-b backupdir] [-c fname] [-m] [-p pattern] [-v] command

Runs on:

ARM, SH, x86

Options:

-b backupdir
(load command only) Use a backup directory instead of permdir.
-c fname
Create a check file: fname for check file; the default is _FILESET_.
-m
Make destination directories as required.
-p pattern
A pattern that defines a file set on initial creation; the default * (all).
-v
Enable verbosity levels. More vs increases the verbosity level, providing greater levels of detail.

Valid commands are load, save and test.

Description:

The fileset utility does checkpointing to ensure that all databases are backed up and restored as a complete set. QDB launches fileset when you call qdb_backup(), as well as on startup when the database is restored.

The fileset utility copies a set of files from one directory to another. While the copy can be between any directories on any file system (disk, flash or tmpfs), this utility optimizes the copy path between disk and tmpfs by employing a direct DMA transfer from the file on disk to and from the file in tmpfs. It requires about one-tenth of the CPU used to move data by a traditional read/write from a program, and can achieve platter/interface transfer rates.

Limitations

The efficiency achieved by fileset imposes some limitations. This utility:


Note: Currently, fileset supports only one backup directory defined in the qdb.cfg file.

load command

The load command is used at startup. The syntax is:

# fileset [options] load permdir tmpdir

When the load command is used, fileset looks for a check file in the path defined by permdir.

On success each file defined in the check file will be copied from permdir into tmpdir. A total success is rewarded with an exit status on 0 (EOK).

Any of following conditions cause fileset to exit with an error:

When it encounters a condition that will cause it to exit with an error, fileset:

save command

The save command is used to commit changes at shutdown, or at any other time as required. The syntax is:

# fileset [options] save permdir tmpdir

When the save command is used, fileset looks for a valid check file in the path defined by permdir, then takes one of the actions describe below.

Missing or invalid check file

If the check file does not exist, or the CRC (checksum) for its data is wrong, fileset creates a new check file set in memory, using the parameters defined by the -p option.

Check file is valid

If the check file exists and has a valid CRC (checksum), then fileset procedes as follows. It:

  1. Loads the check file into memory; this has the list of files to be copied.
  2. Deletes any existing check file in the permanent directory (permdir), since it is about to modify files in the set in that directory.
  3. For each file, compares the file size and modified time in the check file with the file in the temporary directory (tmpdir). If these values match, fileset assumes that the file is unchanged and does not copy the file. I these values do not match, fileset copies the file to the permanent directory.
  4. After it has successfully copied all required files, fileset creates a new check file in the permanent directory to mark the directory as valid.

test command

The test command tests the check file against the permanent directory, returning an exit status as follows:

The syntax is:

# fileset [options] test permdir

Using fileset

To use fileset:


Note: Currently, fileset supports only one backup directory defined in the qdb.cfg file.

Using fileset to restore factory defaults

The fileset utility can be used to restore factory defaults in the event that the permanent directory is corrupted by, for example, an unexpected power outage.

To be able to restore a factory default, when you set up your system, create a backup directory with the defaults. If the permanent directory is corrupted, use the -b option to load the factory default directory. For example:

# fileset -b load /factorydefault /tmpdir

Creating a new file set

To create a file set, use the save command with the -p option to save the files you want in the set to a directory that does not have a check file. The -p sets the selection criteria used by fileset to determine the files it will include in a new check file, and creates and saves the new check file.

Using the check file

The fileset utility uses a check file to determine the files in a set it will copy. This check file contains the name, size and modification date of each file in the set fileset loads into memory or saves, and is required to by fileset when it loads a file set. This file is defined as follows:

struct  check {
    struct cheader {
        unsigned crc;
        unsigned nfiles
        unsigned ver;
        unsigned spare;
    } header;
    struct cfile {
        unsigned mtime;
        unsigned size;
        char fname[128-2*sizeof(unsigned)];
    } files[nfiles];    // from header.nfiles
} ;

To create a check file for an existing file set, use the -c option.

Examples:

The following sequence of events is typical in a running system.

At startup:

# fileset load /hd/mme /tmpfs/mme

If this sequence fails, the system needs to take action. This action is typically to create a new default initial set of files.

At shutdown:

# fileset -p "*.dat" save /hd/mme /tmpfs/mme

If there is no check file (first-time run, or after a hard error) the system will create a check file, using the -p option to define the set. See Using the check file for a definition of the check file.

See also:

QDB Developer's Guide