| Disk ARchive 2.8.3 Full featured and portable backup and archiving tool

Loading...
Searching...
No Matches
Classes | Public Member Functions | Private Attributes | Friends | List of all members
libdar::archive Class Reference
API

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

`#include <archive.hpp>`

## Classes
class | i_archive
| the archive::i_archive class implements the most general operations on archives More...

## Public Member Functions
| archive (const std::shared_ptr< user_interaction > &dialog, const path &chem, const std::string &basename, const std::string &extension, const archive_options_read &options)
| this constructor opens an already existing archive (for reading) [this is the "read" constructor]
| archive (const std::shared_ptr< user_interaction > &dialog, const path &fs_root, const path &sauv_path, const std::string &filename, const std::string &extension, const archive_options_create &options, statistics *progressive_report)
| this constuctor create an archive (full or differential) [this is the "create" constructor]
| archive (const std::shared_ptr< user_interaction > &dialog, const path &sauv_path, std::shared_ptr< archive > ref_arch1, const std::string &filename, const std::string &extension, const archive_options_merge &options, statistics *progressive_report)
| this constructor builds an archive from two given archive [this is the "merge" constructor]
| archive (const std::shared_ptr< user_interaction > &dialog, const path &chem_src, const std::string &basename_src, const std::string &extension_src, const archive_options_read &options_read, const path &chem_dst, const std::string &basename_dst, const std::string &extension_dst, const archive_options_repair &options_repair, statistics *progressive_report=nullptr)
| this constructor create a new archive from a damaged one [this is the "repair" constructor]
| archive (const archive &ref)=delete
| copy constructor (not implemented, throw an exception if called explicitely or implicitely)
| archive (archive &&ref)=delete
archive & | operator= (const archive &ref)=delete
archive & | operator= (archive &&ref)=delete
| ~archive ()
| the destructor
statistics | op_extract (const path &fs_root, const archive_options_extract &options, statistics *progressive_report)
| extraction of data from an archive
void | summary ()
| display a summary of the archive
archive_summary | summary_data ()
| same information as summary() but as broken out data
void | op_listing (archive_listing_callback callback, void *context, const archive_options_listing &options) const
| listing of the archive contents
statistics | op_diff (const path &fs_root, const archive_options_diff &options, statistics *progressive_report)
| archive comparison with filesystem
statistics | op_test (const archive_options_test &options, statistics *progressive_report)
| test the archive integrity
void | op_isolate (const path &sauv_path, const std::string &filename, const std::string &extension, const archive_options_isolate &options)
| this methodes isolates the catalogue of a the current archive into a separated archive
bool | get_children_of (archive_listing_callback callback, void *context, const std::string &dir, bool fetch_ea=false)
| getting information about a given directory
const std::vector< list_entry > | get_children_in_table (const std::string &dir, bool fetch_ea=false) const
| getting information about the given directory (alternative to get_children_of)
bool | has_subdirectory (const std::string &dir) const
| returns true if the pointed directory has one or more subdirectories
const entree_stats | get_stats () const
| retrieving statistics about archive contents
const std::list< signator > & | get_signatories () const
| retrieving signature information about the archive
void | init_catalogue () const
void | drop_all_filedescriptors (bool repairing=false)
| closes all filedescriptors and associated even when in sequential read mode
void | set_to_unsaved_data_and_FSA ()
| change all inode as unsaved (equal to differential backup with no change met)
U_64 | get_first_slice_header_size () const
| get the first slice header
U_64 | get_non_first_slice_header_size () const
| get the non first slice header
| archive (const std::shared_ptr< user_interaction > &dialog, const path &chem, const std::string &basename, const std::string &extension, const archive_options_read &options)
| this constructor opens an already existing archive (for reading) [this is the "read" constructor]
| archive (const std::shared_ptr< user_interaction > &dialog, const path &fs_root, const path &sauv_path, const std::string &filename, const std::string &extension, const archive_options_create &options, statistics *progressive_report)
| this constuctor create an archive (full or differential) [this is the "create" constructor]
| archive (const std::shared_ptr< user_interaction > &dialog, const path &sauv_path, std::shared_ptr< archive > ref_arch1, const std::string &filename, const std::string &extension, const archive_options_merge &options, statistics *progressive_report)
| this constructor builds an archive from two given archive [this is the "merge" constructor]
| archive (const std::shared_ptr< user_interaction > &dialog, const path &chem_src, const std::string &basename_src, const std::string &extension_src, const archive_options_read &options_read, const path &chem_dst, const std::string &basename_dst, const std::string &extension_dst, const archive_options_repair &options_repair, statistics *progressive_report=nullptr)
| this constructor create a new archive from a damaged one [this is the "repair" constructor]
| archive (const archive &ref)=delete
| copy constructor (not implemented, throw an exception if called explicitely or implicitely)
| archive (archive &&ref)=delete
archive & | operator= (const archive &ref)=delete
archive & | operator= (archive &&ref)=delete
| ~archive ()
| the destructor
statistics | op_extract (const path &fs_root, const archive_options_extract &options, statistics *progressive_report)
| extraction of data from an archive
void | summary ()
| display a summary of the archive
archive_summary | summary_data ()
| same information as summary() but as broken out data
void | op_listing (archive_listing_callback callback, void *context, const archive_options_listing &options) const
| listing of the archive contents
statistics | op_diff (const path &fs_root, const archive_options_diff &options, statistics *progressive_report)
| archive comparison with filesystem
statistics | op_test (const archive_options_test &options, statistics *progressive_report)
| test the archive integrity
void | op_isolate (const path &sauv_path, const std::string &filename, const std::string &extension, const archive_options_isolate &options)
| this methodes isolates the catalogue of a the current archive into a separated archive
bool | get_children_of (archive_listing_callback callback, void *context, const std::string &dir, bool fetch_ea=false)
| getting information about a given directory
const std::vector< list_entry > | get_children_in_table (const std::string &dir, bool fetch_ea=false) const
| getting information about the given directory (alternative to get_children_of)
bool | has_subdirectory (const std::string &dir) const
| returns true if the pointed directory has one or more subdirectories
const entree_stats | get_stats () const
| retrieving statistics about archive contents
const std::list< signator > & | get_signatories () const
| retrieving signature information about the archive
void | init_catalogue () const
void | drop_all_filedescriptors (bool repairing=false)
| closes all filedescriptors and associated even when in sequential read mode
void | set_to_unsaved_data_and_FSA ()
| change all inode as unsaved (equal to differential backup with no change met)
U_64 | get_first_slice_header_size () const
| get the first slice header
U_64 | get_non_first_slice_header_size () const
| get the non first slice header

## Private Attributes
std::shared_ptr< i_archive > | pimpl

## Friends
class | database

## 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 67 of file dar64-2.8.3-win64/include/dar/archive.hpp.

## Constructor & Destructor Documentation

## ◆ archive() [1/5]

libdar::archive::archive | ( | const std::shared_ptr< user_interaction > & | dialog,
|  | const path & | chem,
|  | const std::string & | basename,
|  | const std::string & | extension,
|  | const archive_options_read & | options )

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] | options | A set of option to use to read the archive

## ◆ archive() [2/5]

libdar::archive::archive | ( | const std::shared_ptr< user_interaction > & | dialog,
|  | const path & | fs_root,
|  | const path & | sauv_path,
|  | const std::string & | filename,
|  | const std::string & | extension,
|  | const archive_options_create & | options,
|  | 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 (if relative path is given it is made absolute using the current working directory of the process libdar runs in)
  [in] | sauv_path | the path where to create slices
  [in] | filename | base name of the slices. If "-" is given the archive will be produced in standard output
  [in] | extension | slices extension ("dar")
  [in] | options | optional parameters to use for the operation
  [out] | progressive_report | statistics about the operation, considering the treated files (nullptr 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 and that could not be resaved (due to repeat limit or byte limit)
  - 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
  - ea_treated: number of entry having some EA
  - byte_amount : number of wasted bytes due to repeat on change feature

## ◆ archive() [3/5]

libdar::archive::archive | ( | const std::shared_ptr< user_interaction > & | dialog,
|  | const path & | sauv_path,
|  | std::shared_ptr< archive > | ref_arch1,
|  | const std::string & | filename,
|  | const std::string & | extension,
|  | const archive_options_merge & | options,
|  | 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 mandatory input archive (the second is optional and provided within the 'option' argument
  [in] | filename | base name of the slices. If "-" is given the archive will be produced in standard output
  [in] | extension | slices extension ("dar")
  [in] | options | optional parameters to be used for the operation
  [out] | progressive_report | statistics about the operation, considering the treated files (nullptr 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
  - ea_treated: number of entry with EA

## ◆ archive() [4/5]

libdar::archive::archive | ( | const std::shared_ptr< user_interaction > & | dialog,
|  | const path & | chem_src,
|  | const std::string & | basename_src,
|  | const std::string & | extension_src,
|  | const archive_options_read & | options_read,
|  | const path & | chem_dst,
|  | const std::string & | basename_dst,
|  | const std::string & | extension_dst,
|  | const archive_options_repair & | options_repair,
|  | statistics * | progressive_report = nullptr )

this constructor create a new archive from a damaged one [this is the "repair" constructor]

Parameters

  [in,out] | dialog | for user interaction
  [in] | chem_src | the path where to look for slices of the archive to repair
  [in] | basename_src | the slices basename of the archive to repair
  [in] | extension_src | the slices extension of the archive to repair
  [in] | options_read | the set of option to use to read the archive repair
  [in] | chem_dst | the path where to write the repaired archive
  [in] | basename_dst | the slices basename of the repaired archive
  [in] | extension_dst | the slices extension of the repaired archive
  [in] | options_repair | the set of option to use to write the repaired archive
  [out] | progressive_report | statistics about the operation, considering the treated files (nullptr can be given if you don't want to use this feature)

Note
  the statistics fieds used are the same as the ones used for archive creation, though no entry should be ignored as no file or path filtering exists for this operation, and no skipped or tooold should increase as no comparison is performed to an existing filesystem:
  - treated: the total number of files seen
  - hard_link: the number of hard linked inodes
  - errored: number of files concerned by filesystem error
  - deleted: number of files recorded as deleted
  - ea_treated: number of entry having some EA
  - byte_amount : number of wasted bytes due to repeat on change feature nullptr given for backward compatibility

## ◆ archive() [5/5]

libdar::archive::archive | ( | const archive & | ref | ) |
| delete

copy constructor (not implemented, throw an exception if called explicitely or implicitely)

Note
  this lack of implementation is intentionnal, Archive should rather be manipulated using pointers, or passed as constant reference (const &) in arguments or returned values. Moreover, having two objets one copy of the other may lead to unexpected behaviors while merging or creating, isolating or merging archives.

References archive().

## Member Function Documentation

## ◆ drop_all_filedescriptors()

void libdar::archive::drop_all_filedescriptors | ( | bool | repairing = false | ) |

closes all filedescriptors and associated even when in sequential read mode

Note
  once this method has been called, the archive object can only be used as reference for a differential archive.

## ◆ get_children_in_table()

const std::vector< list_entry > libdar::archive::get_children_in_table | ( | const std::string & | dir,
|  | bool | fetch_ea = false ) const

getting information about the given directory (alternative to get_children_of)

Parameters

  [in] | dir | relative path the directory to get information about, use empty string for root directory
  [in] | fetch_ea | whether to fetch Extended Attributes relative information in each returned list_entry (not possible in sequential read mode)

Returns
  a table information about all subdir and subfile for the given directory

Note
  at the difference of get_children_of, this call does not rely on a user_interaction class to provide the information, but rather returns a table of children. To allow new fields to be added to the future the table contains an object that provide a method per field.
  before calling this method on this object, a single call to init_catalogue() is mandatory

## ◆ get_children_of()

bool libdar::archive::get_children_of | ( | archive_listing_callback | callback,
|  | void * | context,
|  | const std::string & | dir,
|  | bool | fetch_ea = false )

getting information about a given directory

Parameters

  [in] | callback | callback function used to provide data in splitted field
  [in] | context | will be passed as first argument of the callback as is provided here
  [in] | dir | relative path the directory to get information about
  [in] | fetch_ea | whether to look for EA (not possible in sequential read mode)

Returns
  true if some children have been found and the callback has been run at least once

## ◆ get_first_slice_header_size()

U_64 libdar::archive::get_first_slice_header_size | ( |  | ) | const

get the first slice header

get_first_slice_header_size() and get_non_first_slice_header_size() can be used to translate from archive offset as reported by the list_entry::get_archive_offset_*() methods to file offset. This can be done by adding the first_slice_header_size to the archive offset, if the resulting number is larger than the first slice size, substract the it and add the non_first_slice header_size, and so on. This way you can determin the slice number to look into and the file offset in that file. Unit for all value is the byte (= octet).

Note
  may return 0 if the slice header is not known

## ◆ get_non_first_slice_header_size()

U_64 libdar::archive::get_non_first_slice_header_size | ( |  | ) | const

get the non first slice header

Note
  may return 0 if the slice header is not known

## ◆ init_catalogue()

void libdar::archive::init_catalogue | ( |  | ) | const

necessary to get the catalogue fully loaded in memory in any situation in particular in sequential reading mode

## ◆ op_diff()

statistics libdar::archive::op_diff | ( | const path & | fs_root,
|  | const archive_options_diff & | options,
|  | statistics * | progressive_report )

archive comparison with filesystem

Parameters

  [in] | fs_root | the filesystem to take as root for the comparison (if relative path is given it is made absolute using the current working directory of the process libdar runs in)
  [in] | options | optional parameters to be used with the operation
  [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), nullptr 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

## ◆ op_extract()

statistics libdar::archive::op_extract | ( | const path & | fs_root,
|  | const archive_options_extract & | options,
|  | statistics * | progressive_report )

extraction of data from an archive

Parameters

  [in] | fs_root | the filesystem to take as root for the restoration (if relative path is given it is made absolute using the current working directory of the process libdar runs in)
  [in] | options | optional parameter to be used for the operation
  [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), nullptr 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 restored
  - skipped: number of files not saved in the archive
  - tooold: number of file not restored due to overwriting policy decision
  - errored: number of files concerned by filesystem error
  - ignored: number of files excluded by filters
  - deleted: number of files deleted
  - hard_links: number of hard link restored
  - ea_treated: number of entry having some EA

## ◆ op_isolate()

void libdar::archive::op_isolate | ( | const path & | sauv_path,
|  | const std::string & | filename,
|  | const std::string & | extension,
|  | const archive_options_isolate & | options )

this methodes isolates the catalogue of a the current archive into a separated archive

Parameters

  [in] | sauv_path | the path where to create slices
  [in] | filename | base name of the slices ("-" for standard output)
  [in] | extension | slices extension ("dar")
  [in] | options | optional parameters to use for the operation

Note
  that if the archive contains delta sig and isolation options, specifying not to keep them in the resulting isolated catalogue leads the current archive object (but not the corresponding archive stored on filesystem) to be modified (delta signature are removed) — this is not a const method.

## ◆ op_listing()

void libdar::archive::op_listing | ( | archive_listing_callback | callback,
|  | void * | context,
|  | const archive_options_listing & | options ) const

listing of the archive contents

Parameters

  [in] | callback | callback function used to provide data in splitted field (not used if null is given)
  [in] | context | will be passed as is to the last argument of the provided callback
  [in] | options | list of optional parameters to use for the operation

Note
  if callback is nullptr (or NULL), the output is done using user_interaction provided with archive constructor
  alternative way to get archive contents:
  - archive::get_children_of() method
  - archive::init_catalogue()+get_children_in_table()

## ◆ op_test()

statistics libdar::archive::op_test | ( | const archive_options_test & | options,
|  | statistics * | progressive_report )

test the archive integrity

Parameters

  [in] | options | optional parameter to use for the operation
  [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), nullptr 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

## ◆ summary()

void libdar::archive::summary | ( |  | ) |

display a summary of the archive

Note
  see also get_stats() method

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

- dar64-2.8.3-win64/include/dar/archive.hpp
- src/libdar/archive.hpp