# API

APlication Interface. More...

## Classes
class | libdar::archive
| the archive class realizes the most general operations on archives More...
class | libdar::database
| the database class defines the dar_manager database More...
class | libdar::Egeneric
| this is the parent class of all exception classes. More...
class | libdar::Ememory
| exception used when memory has been exhausted More...
class | libdar::Ebug
| exception used to signal a bug. A bug is triggered when reaching some code that should never be reached More...
class | libdar::Einfinint
| exception used when arithmetic error is detected when operating on infinint More...
class | libdar::Elimitint
| exception used when a limitint overflow is detected, the maximum value of the limitint has been exceeded More...
class | libdar::Erange
| exception used to signal range error More...
class | libdar::Edeci
| exception used to signal convertion problem between infinint and string (decimal representation) More...
class | libdar::Efeature
| exception used when a requested feature is not (yet) implemented More...
class | libdar::Ehardware
| exception used when hardware problem is found More...
class | libdar::Euser_abort
| exception used to signal that the user has aborted the operation More...
class | libdar::Edata
| exception used when an error concerning the treated data has been met More...
class | libdar::Escript
| exception used when error the inter-slice user command returned an error code More...
class | libdar::Elibcall
| exception used to signal an error in the argument given to libdar call of the API More...
class | libdar::Ecompilation
| exception used when a requested fearture has not beed activated at compilation time More...
class | libdar::Ethread_cancel
| exception used when the thread libdar is running in is asked to stop More...
class | libdar::mask
| the generic class, parent of all masks More...
class | libdar::bool_mask
| boolean mask, either always true or false More...
class | libdar::simple_mask
| matches as done on shell command lines (see "man 7 glob") More...
class | libdar::regular_mask
| matches regular expressions (see "man 7 regex") More...
class | libdar::not_mask
| negation of another mask More...
class | libdar::et_mask
| makes an *AND* operator between two or more masks More...
class | libdar::ou_mask
| makes the *OR* operator between two or more masks More...
class | libdar::simple_path_mask
| string matches if it is subdir of mask or mask is a subdir of expression More...
class | libdar::same_path_mask
| matches if string is exactly the given mask (no wilde card expression) More...
class | libdar::exclude_dir_mask
| matches if string is the given string or a sub directory of it More...
class | libdar::mask_list
| the mask_list class, matches string that are present in a given file More...
class | libdar::path
| the class path is here to manipulate paths in the Unix notation: using'/' More...
class | libdar::statistics
| structure returned by libdar call to give a summary of the operation done in term of file treated More...
class | libdar::user_interaction
| This is a pure virtual class that is used by libdar when interaction with the user is required. More...
class | libdar::user_interaction_callback
| full implemented class for user_interaction based on callback functions. More...
## Defines
#define | LIBDAR_XXXXXXXX
| The following macro are used in the "exception" argument of the *_noexcept() functions.
#define | LIBDAR_NOEXCEPT 0
| normal return no exception has been thrown
#define | LIBDAR_EMEMORY 1
| memory has been exhausted
#define | LIBDAR_EBUG 2
| internal bug error.
#define | LIBDAR_EINFININT 3
| division by zero or other arithmetic error
#define | LIBDAR_ELIMITINT 4
| limitint overflow
#define | LIBDAR_ERANGE 5
| range error
#define | LIBDAR_EDECI 6
| decimal representation error
#define | LIBDAR_EFEATURE 7
| feature not (yet) implemented
#define | LIBDAR_EHARDWARE 8
| hardware failure
#define | LIBDAR_EUSER_ABORT 9
| user has aborted the operation
#define | LIBDAR_EDATA 10
| data inconsistency, error concerning the treated data
#define | LIBDAR_ESCRIPT 11
| inter slice script failure
#define | LIBDAR_ELIBCALL 12
| libdar invalid call (wrong argument given to call, etc.)
#define | LIBDAR_UNKNOWN 13
| unknown error
#define | LIBDAR_ECOMPILATION 14
| feature not activated at compilation time
#define | LIBDAR_THREAD_CANCEL 15
| thread cancellation has been requested
## Enumerations
enum | libdar::compression { libdar::none = 'n', libdar::zip = 'p', libdar::gzip = 'z', libdar::bzip2 = 'y' }
| the different compression algorithm available More...
enum | libdar::crypto_algo { libdar::crypto_none, libdar::crypto_scrambling, libdar::crypto_blowfish, libdar::crypto_blowfish_weak }
| the different cypher available for encryption (strong or weak) More...
## Functions
void | libdar::get_version (U_I &major, U_I &medium, U_I &minor)
| return the libdar version, and make libdar initialization (may throw Exceptions)
void | libdar::get_version_noexcept (U_I &major, U_I &medium, U_I &minor, U_16 &exception, std::string &except_msg)
| return the libdar version, and make libdar initialization (does not throw exceptions)
void | libdar::get_compile_time_features (bool &ea, bool &largefile, bool &nodump, bool &special_alloc, U_I &bits, bool &thread_safe, bool &libz, bool &libbz2, bool &libcrypto, bool &new_blowfish)
| return the options activated that have been activated at compilation time
archive * | libdar::open_archive_noexcept (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, U_16 &exception, std::string &except_msg)
| this is a wrapper around the archive constructor known as the "read" constructor
archive * | libdar::create_archive_noexcept (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, U_16 &exception, std::string &except_msg)
| this is a wrapper around the archive constructor known as the "create" constructor
archive * | libdar::isolate_archive_noexcept (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, U_16 &exception, std::string &except_msg)
| this is a wrapper around the archive constructor known as the "isolate" constructor
archive * | libdar::merge_archive_noexcept (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, U_16 &exception, std::string &except_msg)
| this is a wrapper around the archive constructor known as the "merging" constructor
void | libdar::close_archive_noexcept (archive *ptr, U_16 &exception, std::string &except_msg)
| this is wrapper around the archive destructor
statistics | libdar::op_extract_noexcept (user_interaction &dialog, archive *ptr, 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, U_16 &exception, std::string &except_msg)
| this is wrapper around the op_extract method
void | libdar::op_listing_noexcept (user_interaction &dialog, archive *ptr, bool info_details, archive::listformat list_mode, const mask &selection, bool filter_unsaved, U_16 &exception, std::string &except_msg)
| this is wrapper around the op_listing method
statistics | libdar::op_diff_noexcept (user_interaction &dialog, archive *ptr, 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, U_16 &exception, std::string &except_msg)
| this is wrapper around the op_diff method
statistics | libdar::op_test_noexcept (user_interaction &dialog, archive *ptr, const mask &selection, const mask &subtree, bool info_details, bool display_skipped, statistics *progressive_report, U_16 &exception, std::string &except_msg)
| this is wrapper around the op_test method
bool | libdar::get_children_of_noexcept (user_interaction &dialog, archive *ptr, const std::string &dir, U_16 &exception, std::string &except_msg)
| this is wrapper around the get_children_of method
char * | libdar::libdar_str2charptr_noexcept (const std::string &x, U_16 &exception, std::string &except_msg)
| routine provided to convert std::string to char *
## Variables
const U_I | libdar::LIBDAR_COMPILE_TIME_MAJOR = 4
| libdar Major version defined at compilation time
const U_I | libdar::LIBDAR_COMPILE_TIME_MEDIUM = 4
| libdar Medium version defined at compilation time
const U_I | libdar::LIBDAR_COMPILE_TIME_MINOR = 4
| libdar Minor version defined at compilation time

## Detailed Description

APlication Interface.

This gather all symbols that may be accessed from an external program. Other symbols are not as much documented, and may change or be removed without any warning or backward compatibility. So only use the function, macro, types defined as member of the API in you external programs.

## Enumeration Type Documentation

enum libdar::compression

the different compression algorithm available

values to be used as argument of libdar API calls

Enumerator:

  none | no compression
  zip | zip compression (not implemented)
  gzip | gzip compression
  bzip2 | bzip2 compression

Definition at line 44 of file compressor.hpp.

enum libdar::crypto_algo

the different cypher available for encryption (strong or weak)

values to be used as argument of libdar API calls

Enumerator:

  crypto_none | no encryption
  crypto_scrambling | scrambling weak encryption
  crypto_blowfish | blowfish strong encryption
  crypto_blowfish_weak | blowfish strong encryption old implementation with frequent IV collision (=weakness)

Definition at line 52 of file crypto.hpp.

## Function Documentation

void libdar::close_archive_noexcept | ( | archive * | ptr,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

this is wrapper around the archive destructor

check the archive class for details for an explaination of the two extra arguments exception and except_msg check the get_version_noexcept function

archive* libdar::create_archive_noexcept | ( | 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,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

this is a wrapper around the archive constructor known as the "create" constructor

check the archive class for details for an explaination of the two extra arguments exception and except_msg check the get_version_noexcept function

bool libdar::get_children_of_noexcept | ( | user_interaction & | dialog,
|  | archive * | ptr,
|  | const std::string & | dir,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

this is wrapper around the get_children_of method

check the archive class for details for an explaination of the two extra arguments exception and except_msg check the get_version_noexcept function

void libdar::get_compile_time_features | ( | bool & | ea,
|  | bool & | largefile,
|  | bool & | nodump,
|  | bool & | special_alloc,
|  | U_I & | bits,
|  | bool & | thread_safe,
|  | bool & | libz,
|  | bool & | libbz2,
|  | bool & | libcrypto,
|  | bool & | new_blowfish |
| ) |  |  |

return the options activated that have been activated at compilation time

Parameters:

  `[out]` | ea | whether Extended Attribute support is available
  `[out]` | largefile | whether large file support is available
  `[out]` | nodump | whether the nodump feature is available
  `[out]` | special_alloc | whether special allocation is activated
  `[out]` | bits | the internal integer type used
  `[out]` | thread_safe | whether thread safe support is available
  `[out]` | libz | whether gzip compression is available
  `[out]` | libbz2 | whether bz2 compression is available
  `[out]` | libcrypto | whether strong encryption is available
  `[out]` | new_blowfish | whether new blowfish implementation is available

Note:
  This function does never throw exceptions, so there is no get_compile_time_features_noexcept() function available.

void libdar::get_version | ( | U_I & | major,
|  | U_I & | medium,
|  | U_I & | minor |
| ) |  |  |

return the libdar version, and make libdar initialization (may throw Exceptions)

It is mandatory to call this function (or another one of the get_version* family)

Parameters:

  `[out]` | major | the major number of the version
  `[out]` | medium | the medium number of the version
  `[out]` | minor | the minor number of the version

Note:
  the calling application must match that the major function is the same as the libdar used at compilation time. See API tutorial for a sample code.

void libdar::get_version_noexcept | ( | U_I & | major,
|  | U_I & | medium,
|  | U_I & | minor,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

return the libdar version, and make libdar initialization (does not throw exceptions)

It is mandatory to call this function (or another one of the get_version* family)

Parameters:

  `[out]` | major | the major number of the version
  `[out]` | medium | the medium number of the version
  `[out]` | minor | the minor number of the version
  `[out]` | exception | is to be compared with the LIBDAR_* macro to know whether the call succeeded
  `[out]` | except_msg | in case exception is not equal to LIBDAR_NOEXCEPT this argument contains a human readable explaination of the error met.

Note:
  the calling application must match that the major function is the same as the libdar used at compilation time. See API tutorial for a sample code.

archive* libdar::isolate_archive_noexcept | ( | 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,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

this is a wrapper around the archive constructor known as the "isolate" constructor

check the archive class for details for an explaination of the two extra arguments exception and except_msg check the get_version_noexcept function

char* libdar::libdar_str2charptr_noexcept | ( | const std::string & | x,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

routine provided to convert std::string to char *

Parameters:

  `[in]` | x | the string to convert
  `[out]` | exception | the return status of the call
  `[out]` | except_msg | the message taken from the caught exception in case of error for an explaination of the two last arguments exception and except_msg check the get_version_noexcept function

Returns:
  the address of a newly allocated memory which must be released calling the "delete []" operator when no more needed.

  NULL in case of error

archive* libdar::merge_archive_noexcept | ( | 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,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

this is a wrapper around the archive constructor known as the "merging" constructor

check the archive class for details for an explaination of the two extra arguments exception and except_msg check the get_version_noexcept function

statistics libdar::op_diff_noexcept | ( | user_interaction & | dialog,
|  | archive * | ptr,
|  | 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,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

this is wrapper around the op_diff method

check the archive class for details for an explaination of the two extra arguments exception and except_msg check the get_version_noexcept function

statistics libdar::op_extract_noexcept | ( | user_interaction & | dialog,
|  | archive * | ptr,
|  | 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,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

this is wrapper around the op_extract method

check the archive class for details for an explaination of the two extra arguments exception and except_msg check the get_version_noexcept function

void libdar::op_listing_noexcept | ( | user_interaction & | dialog,
|  | archive * | ptr,
|  | bool | info_details,
|  | archive::listformat | list_mode,
|  | const mask & | selection,
|  | bool | filter_unsaved,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

this is wrapper around the op_listing method

check the archive class for details for an explaination of the two extra arguments exception and except_msg check the get_version_noexcept function

statistics libdar::op_test_noexcept | ( | user_interaction & | dialog,
|  | archive * | ptr,
|  | const mask & | selection,
|  | const mask & | subtree,
|  | bool | info_details,
|  | bool | display_skipped,
|  | statistics * | progressive_report,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

this is wrapper around the op_test method

check the archive class for details for an explaination of the two extra arguments exception and except_msg check the get_version_noexcept function

archive* libdar::open_archive_noexcept | ( | 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,
|  | U_16 & | exception,
|  | std::string & | except_msg |
| ) |  |  |

this is a wrapper around the archive constructor known as the "read" constructor

check the archive class for details for an explaination of the two extra arguments exception and except_msg check the get_version_noexcept function