Library Version 18.1.40

DbEnv::backup()
Prev | Chapter 5. The DbEnv Handle | Next

## DbEnv::backup()

    #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.

### Parameters

#### target

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.

#### flags

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.

### Errors

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:

#### EEXIST

`DB_EXCL` was specified for the `flags` parameter, and an existing target file was discovered when attempting to back up a source file.

#### ENOENT

The target directory does not exist and `DB_CREATE` was not specified for the `flags` parameter.

#### EINVAL

An invalid flag value or parameter was specified.

### Class

DbEnv

### See Also

Database Environments and Related Methods

Prev | Up | Next
DbEnv::add_data_dir() | Home | DbEnv::close()