# libdar::archive Class Reference
[API]

the archive class realizes the most general operations on archives More...

`#include <archive.hpp>`

List of all members.

## Public Types
enum | listformat
| defines the way archive listing is done:
## Public Member Functions
| archive (user_interaction &dialog, const path &chem, const std::string &basename, const std::string &extension, crypto_algo crypto, const std::string &pass, U_32 crypto_size, const std::string &input_pipe, const std::string &output_pipe, const std::string &execute, bool info_details)
| this constructor opens an already existing archive (for reading) [this is the "read" constructor]
| archive (user_interaction &dialog, const path &fs_root, const path &sauv_path, archive *ref_arch, const mask &selection, const mask &subtree, const std::string &filename, const std::string &extension, bool allow_over, bool warn_over, bool info_details, const infinint &pause, bool empty_dir, compression algo, U_I compression_level, const infinint &file_size, const infinint &first_file_size, const mask &ea_mask, const std::string &execute, crypto_algo crypto, const std::string &pass, U_32 crypto_size, const mask &compr_mask, const infinint &min_compr_size, bool nodump, inode::comparison_fields what_to_check, const infinint &hourshift, bool empty, bool alter_atime, bool same_fs, bool snapshot, bool cache_directory_tagging, bool display_skipped, const infinint &fixed_date, statistics *progressive_report)
| this constuctor create an archive (full or differential) [this is the "create" constructor]
| archive (user_interaction &dialog, const path &sauv_path, archive *ref_arch, const std::string &filename, const std::string &extension, bool allow_over, bool warn_over, bool info_details, const infinint &pause, compression algo, U_I compression_level, const infinint &file_size, const infinint &first_file_size, const std::string &execute, crypto_algo crypto, const std::string &pass, U_32 crypto_size, bool empty)
| this constructor isolates a catalogue of a given archive [this is the "isolate" constructor]
| archive (user_interaction &dialog, const path &sauv_path, archive *ref_arch1, archive *ref_arch2, const mask &selection, const mask &subtree, const std::string &filename, const std::string &extension, bool allow_over, bool warn_over, bool info_details, const infinint &pause, bool empty_dir, compression algo, U_I compression_level, const infinint &file_size, const infinint &first_file_size, const mask &ea_mask, const std::string &execute, crypto_algo crypto, const std::string &pass, U_32 crypto_size, const mask &compr_mask, const infinint &min_compr_size, bool empty, bool display_skipped, bool keep_compressed, statistics *progressive_report)
| this constructor builds an archive from two given archive [this is the "merge" constructor]
| ~archive ()
| the destructor
statistics | op_extract (user_interaction &dialog, const path &fs_root, const mask &selection, const mask &subtree, bool allow_over, bool warn_over, bool info_details, bool detruire, bool only_more_recent, const mask &ea_mask, bool flat, inode::comparison_fields what_to_check, bool warn_remove_no_match, const infinint &hourshift, bool empty, bool ea_erase, bool display_skipped, statistics *progressive_report)
| extraction of data from an archive
void | op_listing (user_interaction &dialog, bool info_details, archive::listformat list_mode, const mask &selection, bool filter_unsaved)
| listing of the archive contents
statistics | op_diff (user_interaction &dialog, const path &fs_root, const mask &selection, const mask &subtree, bool info_details, const mask &ea_mask, inode::comparison_fields what_to_check, bool alter_atime, bool display_skipped, statistics *progressive_report)
| archive comparison with filesystem
statistics | op_test (user_interaction &dialog, const mask &selection, const mask &subtree, bool info_details, bool display_skipped, statistics *progressive_report)
| test the archive integrity
bool | get_children_of (user_interaction &dialog, const std::string &dir)
| getting information about a given directory
const entree_stats | get_stats () const
| retrieving statistics about archive contents
const catalogue & | get_catalogue () const
| gives access to internal catalogue (not to be used from the API)

## Detailed Description

the archive class realizes the most general operations on archives

the operations corresponds to the one the final user expects, these are the same abstraction level as the operation realized by the DAR command line tool.

Definition at line 50 of file archive.hpp.

## Constructor & Destructor Documentation

libdar::archive::archive | ( | user_interaction & | dialog,
|  | const path & | chem,
|  | const std::string & | basename,
|  | const std::string & | extension,
|  | crypto_algo | crypto,
|  | const std::string & | pass,
|  | U_32 | crypto_size,
|  | const std::string & | input_pipe,
|  | const std::string & | output_pipe,
|  | const std::string & | execute,
|  | bool | info_details |
| ) |  |  |

this constructor opens an already existing archive (for reading) [this is the "read" constructor]

Parameters:

  `[in,out]` | dialog | for user interaction
  `[in]` | chem | the path where to look for slices
  `[in]` | basename | the slices basename of the archive to read ("-" means standard input, and activates the output_pipe and input_pipe arguments)
  `[in]` | extension | the slice extension (should always be "dar")
  `[in]` | crypto | the crypto cypher to use to read the archive
  `[in]` | pass | the password or passphrase to decrypt (unused if encryption is not set) if an empty string is given and encryption is set, the password will be asked through the user_interaction object
  `[in]` | crypto_size | the encryption block size to use to decrypt (unused if encrytion is not set)
  `[in]` | input_pipe | the name of the input pipe to read data from (when basename is set to "-") if input_pipe is set to "" the information from dar_slave are expected in standard input else the given string must be the path to the a named pipe which will relay the information from dar_slave
  `[in]` | output_pipe | the name of the output pipe to send orders to (when basenale is set to "-") if output_pipe is set to "" the orders sent to dar_slave will exit by the standard output else the given string must be the path to a named pipe which will relay the orders to dar_slave
  `[in]` | execute | the command to execute before reading each slice (empty string for no script) several macros are available: %n : the slice number to be read %b : the archive basename %p : the slices path %e : the archive extension (usually "dar") %%% : substitued by %%
  `[in]` | info_details | whether the user needs detailed output of the operation

libdar::archive::archive | ( | user_interaction & | dialog,
|  | const path & | fs_root,
|  | const path & | sauv_path,
|  | archive * | ref_arch,
|  | const mask & | selection,
|  | const mask & | subtree,
|  | const std::string & | filename,
|  | const std::string & | extension,
|  | bool | allow_over,
|  | bool | warn_over,
|  | bool | info_details,
|  | const infinint & | pause,
|  | bool | empty_dir,
|  | compression | algo,
|  | U_I | compression_level,
|  | const infinint & | file_size,
|  | const infinint & | first_file_size,
|  | const mask & | ea_mask,
|  | const std::string & | execute,
|  | crypto_algo | crypto,
|  | const std::string & | pass,
|  | U_32 | crypto_size,
|  | const mask & | compr_mask,
|  | const infinint & | min_compr_size,
|  | bool | nodump,
|  | inode::comparison_fields | what_to_check,
|  | const infinint & | hourshift,
|  | bool | empty,
|  | bool | alter_atime,
|  | bool | same_fs,
|  | bool | snapshot,
|  | bool | cache_directory_tagging,
|  | bool | display_skipped,
|  | const infinint & | fixed_date,
|  | statistics * | progressive_report |
| ) |  |  |

this constuctor create an archive (full or differential) [this is the "create" constructor]

Parameters:

  `[in,out]` | dialog | for user interaction
  `[in]` | fs_root | the filesystem to take as root for the backup
  `[in]` | sauv_path | the path where to create slices
  `[in]` | ref_arch | the archive to take as reference (NULL for a full backup)
  `[in]` | selection | to only save file (except directory) that match the given mask
  `[in]` | subtree | define the directory and files to consider (this mask will be applied to the absolute path of files being proceeded)
  `[in]` | filename | base name of the slices. If "-" is given the archive will be produced in standard output
  `[in]` | extension | slices extension ("dar")
  `[in]` | allow_over | whether overwritting is allowed
  `[in]` | warn_over | whether a warning shall be issued before overwriting
  `[in]` | info_details | whether the user needs detailed output of the operation
  `[in]` | pause | Pause beteween slices. Set to zero does not pause at all, set to 1 makes libdar pauses each slice, set to 2 makes libdar pause each 2 slices and so on.
  `[in]` | empty_dir | whether we need to store ignored directories as empty
  `[in]` | algo | the compression algorithm used
  `[in]` | compression_level | the compression level (from 1 to 9)
  `[in]` | file_size | the slice size in byte (0 for a single slice whatever its size is)
  `[in]` | first_file_size | the first file size (value 0 is forbidden unless file_size is also set to zero).
  `[in]` | ea_mask | defines which Extended Attributes to save
  `[in]` | execute | command to execute after each slice creation (see the "read" constructor for the available macros)
  `[in]` | crypto | cypher to use
  `[in]` | pass | the password / passphrase to encrypt the data with. Giving an empty string makes the password asked interactively through the dialog argument if encryption has been set.
  `[in]` | crypto_size | the size of the encryption by block to use
  `[in]` | compr_mask | files to compress
  `[in]` | min_compr_size | file size under which to never compress
  `[in]` | nodump | whether to ignore files with the nodump flag set
  `[in]` | what_to_check | fields to consider when comparing inodes with reference archive (see inode::comparison_fields enumeration in catalogue.hpp)
  `[in]` | hourshift | ignore differences of at most this integer number of hours while looking for changes in dates
  `[in]` | empty | whether to make a dry-run operation
  `[in]` | alter_atime | whether to alter atime or ctime in the filesystem when reading files to save
  `[in]` | same_fs | whether to limit the backup to files located on the same filesystem as the directory taken as root of the backup
  `[in]` | snapshot | whether to make an emtpy archive only referencing the current state of files in the filesystem
  `[in]` | cache_directory_tagging | whether to consider the Cache Directory Tagging Standard
  `[in]` | display_skipped | whether to display files that have been excluded by filters
  `[in]` | fixed_date | whether to ignore any archive of reference and only save file which modification is more recent that the given "fixed_date". To not use this feature set fixed_date to zero.
  `[out]` | progressive_report | statistics about the operation, considering the treated files (NULL can be given if you don't want to use this feature)

Note:
  the statistics fields used are:
  - .treated: the total number of files seen
  - .hard_link: the number of hard linked inodes
  - .tooold: the number of files that changed at the time they were saved
  - .skipped: number of files not changed (differential backup)
  - .errored: number of files concerned by filesystem error
  - .ignored: number of files excluded by filters
  - .deleted: number of files recorded as deleted

libdar::archive::archive | ( | user_interaction & | dialog,
|  | const path & | sauv_path,
|  | archive * | ref_arch,
|  | const std::string & | filename,
|  | const std::string & | extension,
|  | bool | allow_over,
|  | bool | warn_over,
|  | bool | info_details,
|  | const infinint & | pause,
|  | compression | algo,
|  | U_I | compression_level,
|  | const infinint & | file_size,
|  | const infinint & | first_file_size,
|  | const std::string & | execute,
|  | crypto_algo | crypto,
|  | const std::string & | pass,
|  | U_32 | crypto_size,
|  | bool | empty |
| ) |  |  |

this constructor isolates a catalogue of a given archive [this is the "isolate" constructor]

Parameters:

  `[in,out]` | dialog | for user interaction
  `[in]` | sauv_path | the path where to create slices
  `[in]` | ref_arch | the archive to take as reference (NULL for a full backup)
  `[in]` | filename | base name of the slices ("-" for standard output)
  `[in]` | extension | slices extension ("dar")
  `[in]` | allow_over | whether overwritting is allowed
  `[in]` | warn_over | whether a warning shall be issued before overwriting
  `[in]` | info_details | whether the user needs detailed output of the operation
  `[in]` | pause | Pause beteween slices. Set to zero does not pause at all, set to 1 makes libdar pauses each slice, set to 2 makes libdar pause each 2 slices and so on.
  `[in]` | algo | the compression algorithm used
  `[in]` | compression_level | the compression level (from 1 to 9)
  `[in]` | file_size | the slice size in byte (0 for a single slice whatever its size is)
  `[in]` | first_file_size | the first file size (zero is allowed only if file_size is set to zero)
  `[in]` | execute | command to execute after each slice creation
  `[in]` | crypto | cypher to use
  `[in]` | pass | the password / passphrase to encrypt the data with (empty string for interactive question)
  `[in]` | crypto_size | the size of the encryption by block to use
  `[in]` | empty | whether to make a dry-run operation

libdar::archive::archive | ( | user_interaction & | dialog,
|  | const path & | sauv_path,
|  | archive * | ref_arch1,
|  | archive * | ref_arch2,
|  | const mask & | selection,
|  | const mask & | subtree,
|  | const std::string & | filename,
|  | const std::string & | extension,
|  | bool | allow_over,
|  | bool | warn_over,
|  | bool | info_details,
|  | const infinint & | pause,
|  | bool | empty_dir,
|  | compression | algo,
|  | U_I | compression_level,
|  | const infinint & | file_size,
|  | const infinint & | first_file_size,
|  | const mask & | ea_mask,
|  | const std::string & | execute,
|  | crypto_algo | crypto,
|  | const std::string & | pass,
|  | U_32 | crypto_size,
|  | const mask & | compr_mask,
|  | const infinint & | min_compr_size,
|  | bool | empty,
|  | bool | display_skipped,
|  | bool | keep_compressed,
|  | statistics * | progressive_report |
| ) |  |  |

this constructor builds an archive from two given archive [this is the "merge" constructor]

Parameters:

  `[in,out]` | dialog | for user interaction
  `[in]` | sauv_path | the path where to create slices
  `[in]` | ref_arch1 | the first input archive (NULL if no archive to give, thus building a subset of ref_arch2)
  `[in]` | ref_arch2 | the first input archive (NULL if no archive to give, thus building a subset of ref_arch1)
  `[in]` | selection | to only consider files (except directory) that match the given mask
  `[in]` | subtree | define the directory and files to consider (this mask will be applied to the absolute path of files being proceeded, * assuming a "<ROOT>" is the root of all paths)
  `[in]` | filename | base name of the slices. If "-" is given the archive will be produced in standard output
  `[in]` | extension | slices extension ("dar")
  `[in]` | allow_over | whether to allow slice overwriting
  `[in]` | warn_over | whether to warn before overwriting a slice
  `[in]` | info_details | whether the user needs detailed output of the operation
  `[in]` | pause | Pause beteween slices. Set to zero does not pause at all, set to 1 makes libdar pauses each slice, set to 2 makes libdar pause each 2 slices and so on.
  `[in]` | empty_dir | whether we need to store ignored directories as empty
  `[in]` | algo | is the compression algorithm used
  `[in]` | compression_level | is the compression level (from 1 to 9)
  `[in]` | file_size | the slice size in byte (0 for a single slice whatever its size is)
  `[in]` | first_file_size | the first file size (value 0 is forbidden unless file_size is also set to zero).
  `[in]` | ea_mask | defines which Extended Attributes to save
  `[in]` | execute | command to execute after each slice creation (see the "read" constructor for the available macros)
  `[in]` | crypto | cypher to use
  `[in]` | pass | the password / passphrase to encrypt the data with. Giving an empty string makes the password asked interactively through the dialog argument if encryption has been set.
  `[in]` | crypto_size | the size of the encryption by block to use
  `[in]` | compr_mask | files to compress
  `[in]` | min_compr_size | file size under which to never compress
  `[in]` | empty | whether to make a dry-run operation
  `[in]` | display_skipped | whether to display files that have been excluded by filters
  `[in]` | keep_compressed | make dar ignore the 'algo' argument and do not uncompress / compress files that are selected for merging
  `[out]` | progressive_report | statistics about the operation, considering the treated files (NULL can be given if you don't want to use this feature)

Note:
  the statistics fields used are:
  - .treated: the total number of files seen
  - .hard_link: the number of hard linked inodes
  - .ignored: number of files excluded by filters
  - .deleted: number of files recorded as deleted

## Member Function Documentation

const catalogue& libdar::archive::get_catalogue | ( |  | ) | const`[inline]`

gives access to internal catalogue (not to be used from the API)

Returns:
  the catalogue reference contained in this archive

Note:
  this method is not to be used directly from external application, it is not part of the API but must remain a public method for been usable by the database class

Definition at line 451 of file archive.hpp.

bool libdar::archive::get_children_of | ( | user_interaction & | dialog,
|  | const std::string & | dir |
| ) |  |  |

getting information about a given directory

Parameters:

  `[in,out]` | dialog | for user interaction
  `[in]` | dir | relative path the directory to get information about

Returns:
  true if some children have been found and thus if the dialog.listing() method has been called at least once.

Note:
  the get_children_of() call uses the listing() method to send back data to the user. If it is not redifined in the dialog object nothing will get sent back to the user

statistics libdar::archive::op_diff | ( | user_interaction & | dialog,
|  | const path & | fs_root,
|  | const mask & | selection,
|  | const mask & | subtree,
|  | bool | info_details,
|  | const mask & | ea_mask,
|  | inode::comparison_fields | what_to_check,
|  | bool | alter_atime,
|  | bool | display_skipped,
|  | statistics * | progressive_report |
| ) |  |  |

archive comparison with filesystem

Parameters:

  `[in,out]` | dialog | for user interaction
  `[in]` | fs_root | the filesystem to take as root for the comparison
  `[in]` | selection | to only consider file (except directory) that match the given mask
  `[in]` | subtree | define the directory and files to consider (this mask will be applied to the absolute path of files being proceeded)
  `[in]` | info_details | whether the user needs detailed output of the operation
  `[in]` | ea_mask | is a mask that defines the Extended Attributes to compare
  `[in]` | what_to_check | fields to consider wien comparing inodes with those on filesystem (see inode::comparison_fields enumeration)
  `[in]` | alter_atime | whether to alter atime or ctime in the filesystem when reading files to compare
  `[in]` | display_skipped | whether to display files that have been excluded by filters
  `[in,out]` | progressive_report | points to an already existing statistics object that can be consulted at any time during the call (see the returned value to know the useful fields and their meining), NULL can be given in argument if you only need the result at the end of the operation through the returned value of this call this should speed up the operation by a little amount.

Returns:
  the statistics about the operation, considering the treated files

Note:
  the statistics fields used are:
  - .treated: the total number of files seen
  - .errored: number of files that do not match or could not be read
  - .ignored: number of files excluded by filters

statistics libdar::archive::op_extract | ( | user_interaction & | dialog,
|  | const path & | fs_root,
|  | const mask & | selection,
|  | const mask & | subtree,
|  | bool | allow_over,
|  | bool | warn_over,
|  | bool | info_details,
|  | bool | detruire,
|  | bool | only_more_recent,
|  | const mask & | ea_mask,
|  | bool | flat,
|  | inode::comparison_fields | what_to_check,
|  | bool | warn_remove_no_match,
|  | const infinint & | hourshift,
|  | bool | empty,
|  | bool | ea_erase,
|  | bool | display_skipped,
|  | statistics * | progressive_report |
| ) |  |  |

extraction of data from an archive

Parameters:

  `[in,out]` | dialog | for user interaction
  `[in]` | fs_root | the filesystem to take as root for the restoration
  `[in]` | selection | to only restore file (except directory) that match the given mask
  `[in]` | subtree | define the directory and files to consider (this mask will be applied to the absolute path of files being proceeded)
  `[in]` | allow_over | whether overwritting is allowed
  `[in]` | warn_over | whether a warning shall be issued before overwriting
  `[in]` | info_details | whether the user needs detailed output of the operation
  `[in]` | detruire | whether the files recorded as removed from the archive of reference shall be removed from filesystem
  `[in]` | only_more_recent | whether to restore only file more recent than those on filesystem
  `[in]` | ea_mask | mask which defines which EA to restore
  `[in]` | flat | whether to ignore directory structure and restore all files in the same directory
  `[in]` | what_to_check | fields to consider when comparing inodes with those on filesystem to determine if it is more recent (see inode::comparison_fields enumeration), also defines which if mtime has to be restored (cf_mtime) if permission have to be too (cf_ignore_owner) if ownership has to be restored too (cf_all)
  `[in]` | warn_remove_no_match | whether a warning must be issue if a file to remove does not match the expected type of file
  `[in]` | hourshift | ignore differences of at most this integer number of hours while looking for file to restore
  `[in]` | empty | whether to make a dry-run operation
  `[in]` | ea_erase | if set, all EA are first erased before being restored
  `[in]` | display_skipped | whether to display files that have been excluded by filters
  `[in,out]` | progressive_report | points to an already existing statistics object that can be consulted at any time during the call (see the returned value to know the useful fields and their meining), NULL can be given in argument if you only need the result at the end of the operation through the returned value of this call this should speed up the operation by a little amount.

Returns:
  the statistics about the operation, considering the treated files

Note:
  the statistics fields used are:
  - .treated: the total number of files seen
  - .skipped: number of files not saved in the archive
  - .tooold: number of file older than the one on filesystem
  - .errored: number of files concerned by filesystem error
  - .ignored: number of files excluded by filters
  - .deleted: number of files deleted

void libdar::archive::op_listing | ( | user_interaction & | dialog,
|  | bool | info_details,
|  | archive::listformat | list_mode,
|  | const mask & | selection,
|  | bool | filter_unsaved |
| ) |  |  |

listing of the archive contents

Parameters:

  `[in,out]` | dialog | for user interaction
  `[in]` | info_details | whether the user needs detailed output of the operation
  `[in]` | list_mode | whether to list ala tar or in a tree like view
  `[in]` | selection | to only view some files (directories will always be seen)
  `[in]` | filter_unsaved | whether to ignore unsaved files

statistics libdar::archive::op_test | ( | user_interaction & | dialog,
|  | const mask & | selection,
|  | const mask & | subtree,
|  | bool | info_details,
|  | bool | display_skipped,
|  | statistics * | progressive_report |
| ) |  |  |

test the archive integrity

Parameters:

  `[in,out]` | dialog | for user interaction
  `[in]` | selection | to only test file (except directory) that match the given mask
  `[in]` | subtree | define the directory and files to consider (this mask will be applied to the string "<ROOT>/<relative filename>" of the files being proceeded, where "<ROOT>" is the litteral string "<ROOT>" without the quotes)
  `[in]` | info_details | whether the user needs detailed output of the operation
  `[in]` | display_skipped | whether to display files that have been excluded by filters
  `[in,out]` | progressive_report | points to an already existing statistics object that can be consulted at any time during the call (see the returned value to know the useful fields and their meining), NULL can be given in argument if you only need the result at the end of the operation through the returned value of this call this should speed up the operation by a little amount.

Note:
  op_test will generate an error message if used on an archive that has been created by the isolate or creation constructor this is not only an implementation limitation but also a choice. testing an file archive using the C++ object used to create the file is not a good idea. You need to first destroy this C++ object then create a new one with the reading constructor this way only you can be sure your archive is properly tested.

Returns:
  the statistics about the operation, considering the treated files

Note:
  the statistics fields used are:
  - .treated: the total number of files seen
  - .skipped: number of file older than the one on filesystem
  - .errored: number of files with error

The documentation for this class was generated from the following file:

- archive.hpp