fileset Reference

Copy a file set

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
(For use with 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 information about permissions flags, see the description for the st_mode field in the stat structure.
-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
(For use with 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 what's given 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 whenever it's necessary. When given the save command, fileset looks for a valid check file in the path defined by prmdir, then performs one of the following actions based on the check file status:
Missing or invalid
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
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 -x is specified, fileset compares the size and modification time of each listed file with the information of the actual file in the temporary directory (tmpdir). If the values match, fileset assumes 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.
prmdir
The directory where the permanent copies of the files are kept. For the load command to succeed, the file names, sizes, and modification times must match what's listed in the check file, which is also kept in this directory. For the save command, fileset refreshes the contents of this directory by coping the latest files from tmpdir.
tmpdir
The directory where the temporary copies of the files are kept. Files are copied into this directory with the load command and then from this directory back into prmdir with the save command.

Description:

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

Note: The fileset binary must be in a path specified in QDB's PATH environment variable.

The fileset utility can copy files to multiple backup directories listed in the BackupDir parameter.

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 /tmp/myMediaDB
    If this command fails, the system must take action, usually by creating a new set of database files.
  2. At shutdown: 
    # fileset -p "*.dat" save /fs/hd0/myTunes /tmp/myTunes
    If there's no check file (because either 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.