# mco_backup_list_db_name
RT

> List the contents of a backup file for a specified database name.

### For an overview see page Incremental Online Backup in C

### Prototype

        void mco_backup_list_db_name(
            /*IN*/  const char *db_name,
            /*IN*/  const char *file_name,
            /*OUT*/ mco_size_t *backup_list_size,
            /*OUT*/ mco_backup_info_t **backup_list,
            /*IN*/  char *err_buf,
            /*IN-OUT*/ unsigned int *err_buf_sz
        );

### Arguments

`db_name`
Name of the database.
`file_name`
Name of the backup file to inspect.
`backup_list_size`
Pointer to a variable that will receive the number of matching backup records.
`backup_list`
Pointer to a variable that will be set to an array of `mco_backup_info_t` descriptors. The memory is allocated internally and must be freed by the caller using `mco_sys_free()`.
`err_buf`
Buffer for error message
`err_buf_sz`
On input: size of `err_buf`. On output: number of characters written. If `NULL`, the function returns `MCO_E_ILLEGAL_PARAM`.

### Description

> This function reads the specified backup file and returns a list of backup records that match the given `db_name`. Each record includes metadata such as `name`, `type`, `label`, timestamp, and size.

> Unlike `mco_backup_list()`, this function allows filtering by database name, which is useful when a single backup file contains records from multiple databases.

> The returned array must be explicitly deallocated using `mco_sys_free()` to avoid memory leaks.

> See Incremental Backup and Restore for more details.

### Return Codes

`MCO_S_OK`
Backup record list successfully retrieved.
`MCO_E_DISK_OPEN`
Failed to open the specified backup file.
`MCO_E_ILLEGAL_PARAM`
Required parameter is missing (e.g., `db_name`, `file_name`, or `err_buf_sz` is `NULL`).
`MCO_E_BACKUP`
Corrupted or invalid backup file format.

### Files

Header file:
mco.h
Source file:
mcobackup.c
Library:
libmcobackup.a