Disk ARchive 2.3.10
Public Types | Public Member Functions
libdar::archive Class Reference

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

#include <archive.hpp>

List of all members.

Public Types

enum  listformat { normal, tree, xml }
 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 catalogueget_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]dialogfor user interaction
[in]chemthe path where to look for slices
[in]basenamethe slices basename of the archive to read ("-" means standard input, and activates the output_pipe and input_pipe arguments)
[in]extensionthe slice extension (should always be "dar")
[in]cryptothe crypto cypher to use to read the archive
[in]passthe 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_sizethe encryption block size to use to decrypt (unused if encrytion is not set)
[in]input_pipethe 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_pipethe 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]executethe 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_detailswhether 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]dialogfor user interaction
[in]fs_rootthe filesystem to take as root for the backup
[in]sauv_paththe path where to create slices
[in]ref_archthe archive to take as reference (NULL for a full backup)
[in]selectionto only save file (except directory) that match the given mask
[in]subtreedefine the directory and files to consider (this mask will be applied to the absolute path of files being proceeded)
[in]filenamebase name of the slices. If "-" is given the archive will be produced in standard output
[in]extensionslices extension ("dar")
[in]allow_overwhether overwritting is allowed
[in]warn_overwhether a warning shall be issued before overwriting
[in]info_detailswhether the user needs detailed output of the operation
[in]pausePause 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_dirwhether we need to store ignored directories as empty
[in]algothe compression algorithm used
[in]compression_levelthe compression level (from 1 to 9)
[in]file_sizethe slice size in byte (0 for a single slice whatever its size is)
[in]first_file_sizethe first file size (value 0 is forbidden unless file_size is also set to zero).
[in]ea_maskdefines which Extended Attributes to save
[in]executecommand to execute after each slice creation (see the "read" constructor for the available macros)
[in]cryptocypher to use
[in]passthe 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_sizethe size of the encryption by block to use
[in]compr_maskfiles to compress
[in]min_compr_sizefile size under which to never compress
[in]nodumpwhether to ignore files with the nodump flag set
[in]what_to_checkfields to consider when comparing inodes with reference archive (see inode::comparison_fields enumeration in catalogue.hpp)
[in]hourshiftignore differences of at most this integer number of hours while looking for changes in dates
[in]emptywhether to make a dry-run operation
[in]alter_atimewhether to alter atime or ctime in the filesystem when reading files to save
[in]same_fswhether to limit the backup to files located on the same filesystem as the directory taken as root of the backup
[in]snapshotwhether to make an emtpy archive only referencing the current state of files in the filesystem
[in]cache_directory_taggingwhether to consider the Cache Directory Tagging Standard
[in]display_skippedwhether to display files that have been excluded by filters
[in]fixed_datewhether 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_reportstatistics 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]dialogfor user interaction
[in]sauv_paththe path where to create slices
[in]ref_archthe archive to take as reference (NULL for a full backup)
[in]filenamebase name of the slices ("-" for standard output)
[in]extensionslices extension ("dar")
[in]allow_overwhether overwritting is allowed
[in]warn_overwhether a warning shall be issued before overwriting
[in]info_detailswhether the user needs detailed output of the operation
[in]pausePause 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]algothe compression algorithm used
[in]compression_levelthe compression level (from 1 to 9)
[in]file_sizethe slice size in byte (0 for a single slice whatever its size is)
[in]first_file_sizethe first file size (zero is allowed only if file_size is set to zero)
[in]executecommand to execute after each slice creation
[in]cryptocypher to use
[in]passthe password / passphrase to encrypt the data with (empty string for interactive question)
[in]crypto_sizethe size of the encryption by block to use
[in]emptywhether 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]dialogfor user interaction
[in]sauv_paththe path where to create slices
[in]ref_arch1the first input archive (NULL if no archive to give, thus building a subset of ref_arch2)
[in]ref_arch2the first input archive (NULL if no archive to give, thus building a subset of ref_arch1)
[in]selectionto only consider files (except directory) that match the given mask
[in]subtreedefine 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]filenamebase name of the slices. If "-" is given the archive will be produced in standard output
[in]extensionslices extension ("dar")
[in]allow_overwhether to allow slice overwriting
[in]warn_overwhether to warn before overwriting a slice
[in]info_detailswhether the user needs detailed output of the operation
[in]pausePause 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_dirwhether we need to store ignored directories as empty
[in]algois the compression algorithm used
[in]compression_levelis the compression level (from 1 to 9)
[in]file_sizethe slice size in byte (0 for a single slice whatever its size is)
[in]first_file_sizethe first file size (value 0 is forbidden unless file_size is also set to zero).
[in]ea_maskdefines which Extended Attributes to save
[in]executecommand to execute after each slice creation (see the "read" constructor for the available macros)
[in]cryptocypher to use
[in]passthe 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_sizethe size of the encryption by block to use
[in]compr_maskfiles to compress
[in]min_compr_sizefile size under which to never compress
[in]emptywhether to make a dry-run operation
[in]display_skippedwhether to display files that have been excluded by filters
[in]keep_compressedmake dar ignore the 'algo' argument and do not uncompress / compress files that are selected for merging
[out]progressive_reportstatistics 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]dialogfor user interaction
[in]dirrelative 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]dialogfor user interaction
[in]fs_rootthe filesystem to take as root for the comparison
[in]selectionto only consider file (except directory) that match the given mask
[in]subtreedefine the directory and files to consider (this mask will be applied to the absolute path of files being proceeded)
[in]info_detailswhether the user needs detailed output of the operation
[in]ea_maskis a mask that defines the Extended Attributes to compare
[in]what_to_checkfields to consider wien comparing inodes with those on filesystem (see inode::comparison_fields enumeration)
[in]alter_atimewhether to alter atime or ctime in the filesystem when reading files to compare
[in]display_skippedwhether to display files that have been excluded by filters
[in,out]progressive_reportpoints 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]dialogfor user interaction
[in]fs_rootthe filesystem to take as root for the restoration
[in]selectionto only restore file (except directory) that match the given mask
[in]subtreedefine the directory and files to consider (this mask will be applied to the absolute path of files being proceeded)
[in]allow_overwhether overwritting is allowed
[in]warn_overwhether a warning shall be issued before overwriting
[in]info_detailswhether the user needs detailed output of the operation
[in]detruirewhether the files recorded as removed from the archive of reference shall be removed from filesystem
[in]only_more_recentwhether to restore only file more recent than those on filesystem
[in]ea_maskmask which defines which EA to restore
[in]flatwhether to ignore directory structure and restore all files in the same directory
[in]what_to_checkfields 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_matchwhether a warning must be issue if a file to remove does not match the expected type of file
[in]hourshiftignore differences of at most this integer number of hours while looking for file to restore
[in]emptywhether to make a dry-run operation
[in]ea_eraseif set, all EA are first erased before being restored
[in]display_skippedwhether to display files that have been excluded by filters
[in,out]progressive_reportpoints 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]dialogfor user interaction
[in]info_detailswhether the user needs detailed output of the operation
[in]list_modewhether to list ala tar or in a tree like view
[in]selectionto only view some files (directories will always be seen)
[in]filter_unsavedwhether 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]dialogfor user interaction
[in]selectionto only test file (except directory) that match the given mask
[in]subtreedefine 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_detailswhether the user needs detailed output of the operation
[in]display_skippedwhether to display files that have been excluded by filters
[in,out]progressive_reportpoints 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:
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Defines