Library Version 12.1.6.0

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

## DbEnv::set_backup_callbacks()

    #include <db_cxx.h>

    DB_ENV->set_backup_callbacks(
            int (*open_func)(DB_ENV *, const char *dbname,
                             const char *target, void **handle),
            int (*write_func)(DB_ENV *, u_int32_t offset_gbytes,
                              u_int32_t offset_bytes, u_int32_t size,
                              u_int8_t *buf, void *handle),
            int (*close_func)(DB_ENV *, const char *dbname, void *handle));

The `DbEnv::set_backup_callbacks()` method configures three callback functions which can be used by the DbEnv::backup() or DbEnv::dbbackup() methods to override their default behavior. If one callback is configured, then all three callbacks must be configured. These callbacks are required if the `target` parameter is set to `NULL` for the DbEnv::backup() or DbEnv::dbbackup() methods.

The `DbEnv::set_backup_callbacks()` method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The `DbEnv::set_backup_callbacks()` method may be called at any time during the life of the application.

The `DbEnv::set_backup_callbacks()` 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

#### open_func

The open_func parameter is the function used when a target location is opened during a backup. This function should do whatever is necessary to prepare the backup destination for writing the data.

This function takes four parameters:

- `dbenv`

  The dbenv parameter is the enclosing database environment handle.

- `dbname`

  The dbname parameter is the name of the database being backed up.

- `target`

  The target parameter is the backup's directory destination.

- `handle`

  The handle parameter references the handle (usually a file handle) to which the backup will be written.

#### write_func

The write_func parameter is the function used to write data during a backup. The function takes six parameters:

- `dbenv`

  The dbenv parameter is the enclosing database environment handle.

- `offset_gbytes`

  The offset_gbytes parameter specifies the number of gigabytes into the output handle where the data can should be written. This value, plus the value specified on `offset_bytes`, indicates the offset within the output handle where the backup should begin.

- `offset_bytes`

  The offset_bytes parameter specifies the number of bytes into the output handle where the data can be located. This value, plus the value specified on `offset_gbytes`, indicates the offset within the output handle where the backup should begin.

- `size`

  The size parameter specifies the number of bytes to back up from the buffer.

- `buf`

  The buf parameter is the buffer which contains the data to be backed up.

- `handle`

  The handle parameter references the handle (usually a file handle) to which the backup will be written.

#### close_func

The close_func parameter is the function used when ending a backup and closing a backup target. The function takes three parameters:

- `dbenv`

  The dbenv parameter is the enclosing database environment handle.

- `dbname`

  The dbname parameter is the name of the database that has now been backed up.

- `handle`

  The handle parameter references the handle (usually a file handle) to which the backup was written, and which now must be closed or otherwise discarded.

### Class

DbEnv

### See Also

Database Environments and Related Methods, DbEnv::get_backup_callbacks(), DbEnv::backup(), and DbEnv::dbbackup().

Prev | Up | Next
DbEnv::set_app_dispatch() | Home | DbEnv::set_backup_config()