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

- Main Page
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | List of all members
libdar::archive Class Reference
API

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

`#include <archive.hpp>`

Inherits libdar::on_pool.

## Public Member Functions
| archive (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] More...
| archive (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] More...
| archive (user_interaction &dialog, const path &sauv_path, archive *ref_arch, const std::string &filename, const std::string &extension, const archive_options_isolate &options)
| archive (user_interaction &dialog, const path &sauv_path, 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] More...
| archive (const archive &ref)
| copy constructor (not implemented, throw an exception if called explicitely or implicitely) More...
archive & | operator= (const archive &ref)
| ~archive () throw (Ebug)
| the destructor
statistics | op_extract (user_interaction &dialog, const path &fs_root, const archive_options_extract &options, statistics *progressive_report)
| extraction of data from an archive More...
void | summary (user_interaction &dialog)
void | op_listing (user_interaction &dialog, const archive_options_listing &options)
| listing of the archive contents More...
statistics | op_diff (user_interaction &dialog, const path &fs_root, const archive_options_diff &options, statistics *progressive_report)
| archive comparison with filesystem More...
statistics | op_test (user_interaction &dialog, const archive_options_test &options, statistics *progressive_report)
| test the archive integrity More...
void | op_isolate (user_interaction &dialog, 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 More...
bool | get_children_of (user_interaction &dialog, const std::string &dir)
| getting information about a given directory More...
const std::vector< list_entry > | get_children_in_table (const std::string &dir) const
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 (user_interaction &dialog) const
const catalogue & | get_catalogue () const
| gives access to internal catalogue (not to be used from the API) More...
const catalogue & | get_catalogue (user_interaction &dialog) const
| gives access to internal catalogue (not to be used from the API) even in sequential read mode
void | drop_all_filedescriptors ()
| closes all filedescriptors and associated data, just keep the catalogue More...
void | drop_all_filedescriptors (user_interaction &dialog)
| 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)
std::string | free_and_check_memory () const
U_64 | get_first_slice_header_size () const
U_64 | get_non_first_slice_header_size () const
Public Member Functions inherited from libdar::on_pool
void * | operator new (size_t n_byte)
void * | operator new (size_t n_byte, const std::nothrow_t &nothrow_value)
void * | operator new[] (size_t n_byte)
void * | operator new[] (size_t n_byte, const std::nothrow_t &nothrow_value)
void * | operator new (size_t n_byte, memory_pool *p)
void * | operator new[] (size_t n_byte, memory_pool *p)
void | operator delete (void *ptr, memory_pool *p)
| this operator is called by the compiler if an exception is throw from the constructor of the allocated object
void | operator delete[] (void *ptr, memory_pool *p)
| this operator is called by the compiler if an exception is throw from the constructor of the allocated objects
void | operator delete (void *ptr)
| this is the usual delete operator, modified to handle allocated objects allocated on a memory pool or not
void | operator delete[] (void *ptr)
| this is the usual delete[] operator, modified to handle allocated objects allocated on a memory pool or not

## Additional Inherited Members
Protected Member Functions inherited from libdar::on_pool
memory_pool * | get_pool () const
template<class T >
void | meta_new (T *&ptr, size_t num)
template<class T >
void | meta_delete (T *ptr)

## 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 56 of file archive.hpp.

## Constructor & Destructor Documentation

libdar::archive::archive | ( | 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

libdar::archive::archive | ( | 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
  [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

libdar::archive::archive | ( | user_interaction & | dialog,
|  | const path & | sauv_path,
|  | archive * | ref_arch,
|  | const std::string & | filename,
|  | const std::string & | extension,
|  | const archive_options_isolate & | options
| ) |  |

WARNING this is a deprecated constructor, use the op_isolate() method for better performances

Note
  this method will be remove from the API in a future version of libdar

libdar::archive::archive | ( | user_interaction & | dialog,
|  | const path & | sauv_path,
|  | 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

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

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.

Definition at line 146 of file archive.hpp.

References libdar::dar_gettext().

## Member Function Documentation

void libdar::archive::drop_all_filedescriptors | ( |  | ) |

closes all filedescriptors and associated data, just keep the catalogue

Note
  once this method has been called, the archive object can only be used as reference for a differential archive.
  this method is not usable (throws an exception) if the archive has been open in sequential read mode and the catalogue has not yet been read; use the same method but with user_interaction argument instead in that situation

std::string libdar::archive::free_and_check_memory | ( |  | ) | const

check that the internal memory_pool has all its blocks properly freeed

Returns
  an empty string in normal situation, else a status report about the still allocated blocks that remain in the internal memory_pool

Note
  this must be the last call done to that object before destruction and it must be done only once

const catalogue& libdar::archive::get_catalogue | ( |  | ) | const

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
  this method is not usable (throws an exception) if the archive has been open in sequential read mode and the catalogue has not yet been read; use the same method but with user_interaction argument instead, in that situation or call init_catalogue() first.

const std::vector<list_entry> libdar::archive::get_children_in_table | ( | const std::string & | dir | ) | 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

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

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

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

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

void libdar::archive::init_catalogue | ( | user_interaction & | dialog | ) | const

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

statistics libdar::archive::op_diff | ( | user_interaction & | dialog,
|  | const path & | fs_root,
|  | const archive_options_diff & | options,
|  | 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] | 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

statistics libdar::archive::op_extract | ( | user_interaction & | dialog,
|  | const path & | fs_root,
|  | const archive_options_extract & | options,
|  | 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] | 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

void libdar::archive::op_isolate | ( | user_interaction & | dialog,
|  | 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,out] | dialog | for user interaction
  [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

void libdar::archive::op_listing | ( | user_interaction & | dialog,
|  | const archive_options_listing & | options
| ) |  |

listing of the archive contents

Parameters

  [in,out] | dialog | for user interaction
  [in] | options | list of optional parameters to use for the operation

Note
  this call covers the whole listing and uses the user_interaction to provide the archive contents (in particular using its listing() method if set and activated by its set_use_listing() method). There is however two alternative way to get archive contents: . archive::get_children_of() method . archive::init_catalogue()+get_children_in_table()

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

test the archive integrity

Parameters

  [in,out] | dialog | for user interaction
  [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

void libdar::archive::summary | ( | user_interaction & | dialog | ) |

display a summary of the archive

Note
  see also get_stats() method

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

- archive.hpp