#include <db_cxx.h> int DbEnv::backup(const char *target, u_int32_t flags);
The DbEnv::backup() method performs a hot
backup of the open environment. All files used by the environment
are backed up, so long as the normal rules for file placement are
followed. For information on how files are normally placed relative
to the environment directory, see
Berkeley DB File Naming in the Berkeley DB Programmer's Reference Guide.
By default, data directories and the log directory specified
relative to the home directory will be recreated relative to the
target directory. If absolute path names are used, then specify
DB_BACKUP_SINGLE_DIR to the flags
parameter.
This method provides the same functionality as the
db_hotbackup
utility. However, this method does not perform the housekeeping
actions performed by the db_hotbackup utility.
In particular, you may want to run a checkpoint before calling this
method. To run a checkpoint, use the
DbEnv::txn_checkpoint()
method. For more information on checkpoints, see
Checkpoints in the Berkeley DB Programmer's Reference Guide.
To back up a single database file contained within the environment, use the DbEnv::dbbackup() method.
This method's default behavior can be changed by setting backup callbacks. See DbEnv::set_backup_callbacks() for more information. Additional tuning parameters can also be set using the DbEnv::set_backup_config() method.
The DbEnv::backup() method may only be
called after the environment handle has been opened.
The DbEnv::backup()
method either returns a non-zero error value or throws an
exception that encapsulates a non-zero error value on
failure, and returns 0 on success.
Identifies the directory in which the back up will be
placed. Any subdirectories required to contain the backup
must be placed relative to this directory. Note that if
the backup callbacks are set, then the value specified to
this parameter is passed on to the open_func()
callback. If this parameter is NULL, then the target must
be specified to the open_func()
callback.
This directory, and any required subdirectories, will be
created for you if you specify the
DB_CREATE flag on the call to this
method. Otherwise, if the target does not exist, this
method exits with an ENOENT
error return.
The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the values:
DB_BACKUP_CLEAN
Before performing the backup, first remove all files from the target backup directory tree.
DB_BACKUP_DEEP_COPY
Copy databases in any sub-directories in the environment home and any supplied data directories.
DB_BACKUP_FILES
Back up all ordinary files that might exist in the environment, and the environment's subdirectories.
DB_BACKUP_NO_LOGS
Back up only the *.db
files. Do not backup the log files.
DB_BACKUP_SINGLE_DIR
Regardless of the directory structure used by the
source environment, place all back up files in the
single directory identified by the
target parameter. Use this
option if absolute path names to your environment
directory and the files within that directory are
required by your application.
DB_BACKUP_UPDATE
Perform an incremental back up, instead of a full back up. When this option is specified, only log files are copied to the target directory.
DB_CREATE
If the target directory does not exist, create it and any required subdirectories.
DB_EXCL
Return an EEXIST error if a
target backup file already exists.
The DbEnv::backup()
method may fail and throw a DbException
exception, encapsulating one of the following non-zero errors, or return one
of the following non-zero errors:
DB_EXCL was specified for the
flags parameter, and an existing target
file was discovered when attempting to back up a source
file.