fileset Reference

Synopsis:

fileset [-6] [-b backupdir] [-c fname] [-m] [-P perms] [-p pattern]
        [-t savetime] [-v] [-x] [load | save | test] prmdir tmpdir

Options:

-6

Limit DMA so it doesn't cross a 64K boundary.

-b backupdir

(load command)

Use this directory instead of prmdir as a backup if the check file is missing or bad.

-c fname

Create a check file called fname; the default name is _FILESET_.

-m

Create any necessary directories.

-P perms

Assign access permissions to backup files. For more information, see "Access permissions" in the QNX Neutrino C Library Reference.

-p pattern

Define a set of files to copy based on a filename pattern. You can specify multiple file sets by using up to 16 -p options.

By default, only the "*" (all files) pattern is defined. When you define a pattern for a file set, the default pattern is overridden.

-t savetime

(save command)

Use the provided time value for the access and modification times.

-v

Increase output verbosity. Messages are written to stdout. This option is cumulative, allowing you to specify up to three -v options for maximum verbosity.

This option is handy when you're trying to understand the operation of QDB, but when many -v arguments are used, the logging becomes quite significant and can change timing noticeably. The verbosity setting is good for systems under development but should probably not be used in production systems or when performance testing.

-x

Don't copy files that haven't changed. By default, all files are copied.

load

Load the set of files listed in the check file into the temporary directory. QDB issues the load command at startup, causing fileset to look for a check file in the path defined by prmdir. On success, each file listed in the check file is copied from prmdir to tmpdir and fileset returns an exit status of 0 (EOK).

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

• The check file doesn't exist.
• The CRC (checksum) for the check file is wrong.
• A file has a size or modification time that doesn't match the information in the check file.
• A file listed in the check file is missing from the database.
• An error occurs during a file copy.

When it encounters an erroneous condition, fileset sets errno and removes the links to any files it copied before the error occurred.

save

Save the files during shutdown or at any other time as needed. When given the save command, fileset looks for a valid check file in the path defined by prmdir, then performs one of these actions based on the check file status:

Missing or invalid check file

If the check file doesn't exist or the CRC (checksum) for its data is wrong, fileset creates a new check file, based on the patterns defined with -p.

Valid check file

If the check file exists and has a valid CRC (checksum), fileset:

1. Loads the check file (which has the list of files to copy) into memory.
2. Deletes any existing check file in the permanent directory (prmdir), because it's about to modify files in that directory.
3. Copies some or all files listed in the check file to the permanent directory, depending on the -x setting. When this last option is specified, fileset compares the size and modification time for each listed file with the information of the actual file in the temporary directory (tmpdir). If the values match, fileset assumes that the file is unchanged and doesn't copy it. If they don't match, fileset copies the file to the permanent directory. When -x isn't specified, all files are copied, whether they've changed or not.
4. Creates a new check file in the permanent directory to mark the directory as valid.

test

Test the information in the check file against the contents of the permanent directory. When given this command, fileset returns an exit status as follows:

0

The size and modification time for each file listed in the check file matches the information of the actual file in prmdir.

<>0

There's a mismatch in the size or modification time for a file listed in the check file, or there's a problem with the prmdir directory.

Description:

The fileset utility is used by QDB to copy files during database backups when the diocopy compression option is set in the database's configuration object. QDB launches fileset when you call qdb_backup() and when the database is restored on startup.

While fileset can copy a set of files between any directories on any filesystem (disk, flash, or tmpfs), the utility optimizes the copy path between disk and tmpfs by using DMA transfer to move files between these filesystem types. It requires about one-tenth of the CPU used to move data by a traditional read/write transfer from a program, and it can achieve better platter/interface transfer rates.

In this release, fileset can copy files to multiple backup directories specified in the BackupDir:: parameter in the database configuration object.

Limitations

The efficiency of fileset imposes some limitations. This utility:

• Doesn't read or copy subdirectory contents.
• Doesn't create a source directory.
• Creates a destination directory only if you use -m.
• Either completely succeeds or completely fails. There are no partial results. If it encounters an error while copying any file, it unlinks from the destination directory any files already copied and then exits with an error.

Examples

The following is a typical sequence of events:

1. At startup:

   # fileset load /fs/hd0/myMediaDB /tmpfs/myMediaDB

   If this sequence fails, the system must take action; typically, this entails creating a new set of database files.
2. At shutdown:

   # fileset -p "*.dat" save /fs/hd0/myTunes /tmpfs/myTunes

   If there's no check file (because it's the command is being run for the first time or a serious error occurred), the system creates a check file, using the -p option to define the file set.