General Information
System Calls
Error Codes
Implementing Hooks

Backup Manager 3.0
General Information

Contents

This document describes the general internal backup system of Backup Manager. This information is written for those who want to implement new shells or features in Backup Manager.

Overview

Backup Manager works by making archived copies of files that are backed up in a special backup folder, ωbman3. In addition to merely copying the files to this folder and archiving them, it has to keep track of other information, such as the original folder where each file was located. It also must have some way to keep apart files that have the same names but exist in different folders without mixing them up. Finally, it has to know which groups the backups belong to, keep up with the different versions stored for the files, and so on.

To do this, Backup Manager uses a database in the backup folder, which consists of a collection of various variables (mainly lists) that hold information about the backup files. A copy of the database is always kept archived along with the backup files so that backups can be restored in the event of RAM erasure. The database is vital for accessing the backups, so it is especially important that the database is not lost or damaged.

Backup Manager was also designed to be extendible. It has support for storing extra information about each backup or group. It can also use any front-end, or shell, that calls the base routines. Finally, Backup Manager 3.0 introduces hooks, which allow other programs to manipulate key backup operations. This may be used, for instance, to allow an ASM program to compress/decompress or encrypt/decrypt backups as they're stored or restored.

The backup database

The following variables make up the database:

bd* files

These are lists that contain the information about each individual backup. The list "bd" contains codes that indicate how many other lists there are and what data they contain. The first five lists, bd1 to bd5, are reserved by the system and always contain the following data (one element per backup).

bd1 The original paths of the backed up files
bd2 The names of the corresponding backed up files' copies in the backup folder
bd3 Whether the backups are stored away (true or false expression)
bd4 A "string-encoded list" (a list encoded into a string with the string() function) of the backup's version comments
bd5 Another string-encoded list of the backup's version file names in the backup folder (for each corresponding version comment)

bg* files

These are lists that contain the information about each group, one element per group. Again, the bg list contains codes representing the data held in the other bg* lists. The reserved group data is:

bg1 The names of all existing groups
bg2 A string-encoded list of the paths of the original files for the backups belonging to each group

Extended data

Backup Manager allows for storing extra information about backup files in the database so that shells and hooks can easily add new functionality. This extended data is stored by creating additional bd* or bg* lists, where each element represents the data for one backup or one group, respectively.

To create, remove, and find these extended database lists, the Backup Manager system calls regbd, unregbd, and getbd are used. These calls ensure that existing database data is not accidentally removed or overwritten and that the data is properly registered in the database so the system will recognize it. For this reason, programs should always use these calls when using extended data, and never directly remove or create extended lists on their own.

See the calls.html document for more information on using Backup Manager system calls, including the ones for extended data.

Hooks

Hooks allow the alteration of certain aspects of the key Backup Manager operations. This can be used to add features such as date/time-stamping backups as they're modified or restored, or compressing/decompressing backup files.

A list named bhooks is used to register hooks with the Backup Manager system. The list contains a command to execute for each hook. Different hooks are called during different operations. The code in this file can be used to call a program, which can obtain data about the current operation, alter it if necessary, and then return and allow Backup Manager to complete the operation.

For more information about hooks, see the hooks.html document.

Currently, no routines are used for accessing bhooks. The bhooks file may simply be altered directly, either by hand or by an automated installation program, to install or uninstall hooks.

The following is a list of operations that can be hooked, along with some examples of what the hook can be used for:

Hook#OperationUsage example
1Creation of a new backup (just before the operation actually takes place) Compression of the backup file
2Creation of a new backup (just after the operation takes place) Addition of extended backup data as soon as the backup is created
3Updating of a backup Compression of the backup file
4Restoration of a backup Decompression of the backup file as it is restored
5Deletion of a backup Removal of data (created by an external hook or shell) specific to the backup being deleted
6Creation of a backup version Creation of any custom data related to the new version
7Changing of a version's comment Updating of any custom data related to the version
8Deletion of a version Removal of any custom data related to the version
9Occurrence of any error in an operation (before any action is taken by Backup Manager's error handler) Customization of error handler behavior
10Occurrence of an unknown (unexpected) error in an operation Handling of custom error codes for externally implemented features