class holding optional parameters used to create an archive More...

#include <archive_options.hpp>

Inherited by libdar5::archive_options_create.

Collaboration diagram for libdar::archive_options_create:

Public Member Functions
	archive_options_create (const archive_options_create &ref)

	archive_options_create (archive_options_create &&ref) noexcept

archive_options_create &	operator= (const archive_options_create &ref)

archive_options_create &	operator= (archive_options_create &&ref) noexcept

void	clear ()
	reset all the options to their default values

void	set_reference (std::shared_ptr< archive > ref_arch)
	set the archive to take as reference (nullptr for a full backup)

void	set_selection (const mask &selection)
	defines the filenames to only save (except directory) as those that match the given mask

void	set_subtree (const mask &subtree)
	defines the directories and files to consider More...

void	set_allow_over (bool allow_over)
	defines whether overwritting is allowed or not

void	set_warn_over (bool warn_over)
	defines whether a warning shall be issued before overwriting

void	set_info_details (bool info_details)
	defines whether the user needs detailed output of the operation More...

void	set_display_treated (bool display_treated, bool only_dir)
	defines whether to show treated files More...

void	set_display_skipped (bool display_skipped)
	whether to display files that have been excluded by filters

void	set_display_finished (bool display_finished)
	whether to display a summary for each completed directory with total saved data and compression ratio

void	set_pause (const infinint &pause)
	set a 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.

void	set_empty_dir (bool empty_dir)
	defines whether we need to store ignored directories as empty

void	set_compression (compression compr_algo)
	set the compression algorithm to be used

void	set_compression_level (U_I compression_level)
	set the compression level (from 1 to 9)

void	set_compression_block_size (U_I compression_block_size)
	set the compression block size More...

void	set_slicing (const infinint &file_size, const infinint &first_file_size=0)
	define the archive slicing More...

void	set_ea_mask (const mask &ea_mask)
	defines which Extended Attributes to save

void	set_execute (const std::string &execute)
	set the command to execute after each slice creation More...

void	set_crypto_algo (crypto_algo crypto)
	set the cypher to use

void	set_crypto_pass (const secu_string &pass)

void	set_crypto_size (U_32 crypto_size)
	set the size of the encryption by block to use

void	set_gnupg_recipients (const std::vector< std::string > &gnupg_recipients)
	set the list of recipients that will be able to read the archive More...

void	set_gnupg_signatories (const std::vector< std::string > &gnupg_signatories)

void	set_compr_mask (const mask &compr_mask)
	defines files to compress

void	set_min_compr_size (const infinint &min_compr_size)
	defines file size under which to never compress

void	set_nodump (bool nodump)
	defines whether to ignore files with the nodump flag set

void	set_exclude_by_ea (const std::string &ea_name)

void	set_what_to_check (comparison_fields what_to_check)
	set the fields to consider when comparing inodes with reference archive (see comparison_fields enumeration in catalogue.hpp)

void	set_hourshift (const infinint &hourshift)
	ignore differences of at most this integer number of hours while looking for changes in dates

void	set_empty (bool empty)
	whether to make a dry-run operation

void	set_alter_atime (bool alter_atime)
	whether to alter atime or ctime in the filesystem when reading files to save More...

void	set_furtive_read_mode (bool furtive_read)
	whether to use furtive read mode (if activated, alter_atime() has no meaning/use)

void	set_same_fs (bool same_fs)
	whether to limit the backup to files located on the same filesystem as the directory taken as root of the backup More...

void	set_same_fs_include (const std::string &included_path_to_fs)
	files on the filesystem pointed to by the given path will be considered for the backup operation if not excluded by set_same_fs_exclude() More...

void	set_same_fs_exclude (const std::string &excluded_path_to_fs)
	files on the filesystem pointed to by the given path will not be considered for backup operation More...

void	set_snapshot (bool snapshot)
	whether to make an emtpy archive only referencing the current state of files in the filesystem

void	set_cache_directory_tagging (bool cache_directory_tagging)
	whether to consider the Cache Directory Tagging Standard

void	set_fixed_date (const infinint &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 value of zero (which is the value by default)

void	set_slice_permission (const std::string &slice_permission)
	if not an empty string set the slice permission according to the octal value given.

void	set_slice_user_ownership (const std::string &slice_user_ownership)
	if not an empty string set the user ownership of slices accordingly

void	set_slice_group_ownership (const std::string &slice_group_ownership)
	if not an empty string set the group ownership of slices accordingly

void	set_retry_on_change (const infinint &count_max_per_file, const infinint &global_max_byte_overhead=0)
	how much time to retry saving a file if it changed while being read

void	set_sequential_marks (bool sequential)
	whether to add escape sequence aka tape marks to allow sequential reading of the archive

void	set_sparse_file_min_size (const infinint &size)
	whether to try to detect sparse files

void	set_security_check (bool check)
	whether to check for ctime changes since with the archive of reference

void	set_user_comment (const std::string &comment)
	specify a user comment in the archive (always in clear text!)

void	set_hash_algo (hash_algo hash)
	specify whether to produce a hash file of the slice and which hash algo to use More...

void	set_slice_min_digits (infinint val)
	defines the minimum digit a slice must have concerning its number, zeros will be prepended as much as necessary to respect this

void	set_backup_hook (const std::string &execute, const mask &which_files)
	defines the backup hook for files

void	set_ignore_unknown_inode_type (bool val)
	whether to ignore unknown inode types instead of issuing a warning

void	set_entrepot (const std::shared_ptr< entrepot > &entr)
	defines the protocol to use for slices

void	set_fsa_scope (const fsa_scope &scope)
	defines the FSA (Filesystem Specific Attribute) to only consider (by default all FSA activated at compilation time are considered)

void	set_multi_threaded (bool val)
	whether libdar is allowed to spawn several threads to possibily work faster on multicore CPU (requires libthreadar) More...

void	set_multi_threaded_crypto (U_I num)
	how much thread libdar will use for cryptography (need libthreadar to be effective)

void	set_multi_threaded_compress (U_I num)
	how much thread libdar will use for compression (need libthreadar too and compression_block_size > 0)

void	set_delta_diff (bool val)
	whether binary delta has to be computed for differential/incremental backup More...

void	set_delta_signature (bool val)
	whether signature to base binary delta on the future has to be calculated and stored beside saved files

void	set_delta_mask (const mask &delta_mask)
	whether to derogate to defaut delta file consideration while calculation delta signatures

void	set_delta_sig_min_size (const infinint &val)
	whether to never calculate delta signature for files which size is smaller or equal to the given argument More...

void	set_auto_zeroing_neg_dates (bool val)
	whether to automatically zeroing negative dates read from the filesystem (just warn, don't ask whether to pursue)

void	set_ignored_as_symlink (const std::set< std::string > &list)
	provide a list of full path which if are symlinks will be considered as the inode they point to More...

void	set_modified_data_detection (modified_data_detection val)
	defines when to resave a file's data which inode metadata changed

void	set_iteration_count (const infinint &val)
	key derivation

void	set_kdf_hash (hash_algo algo)
	hash algo used for key derivation

void	set_sig_block_len (delta_sig_block_size val)
	block size to use to build delta signatures

std::shared_ptr< archive >	get_reference () const

const mask &	get_selection () const

const mask &	get_subtree () const

bool	get_allow_over () const

bool	get_warn_over () const

bool	get_info_details () const

bool	get_display_treated () const

bool	get_display_treated_only_dir () const

bool	get_display_skipped () const

bool	get_display_finished () const

const infinint &	get_pause () const

bool	get_empty_dir () const

compression	get_compression () const

U_I	get_compression_level () const

U_I	get_compression_block_size () const

const infinint &	get_slice_size () const

const infinint &	get_first_slice_size () const

const mask &	get_ea_mask () const

const std::string &	get_execute () const

crypto_algo	get_crypto_algo () const

const secu_string &	get_crypto_pass () const

U_32	get_crypto_size () const

const std::vector< std::string > &	get_gnupg_recipients () const

const std::vector< std::string > &	get_gnupg_signatories () const

const mask &	get_compr_mask () const

const infinint &	get_min_compr_size () const

bool	get_nodump () const

const std::string &	get_exclude_by_ea () const

comparison_fields	get_comparison_fields () const

const infinint &	get_hourshift () const

bool	get_empty () const

bool	get_alter_atime () const

bool	get_furtive_read_mode () const

bool	get_same_fs () const

std::deque< std::string >	get_same_fs_include () const

std::deque< std::string >	get_same_fs_exclude () const

bool	get_snapshot () const

bool	get_cache_directory_tagging () const

const infinint &	get_fixed_date () const

const std::string &	get_slice_permission () const

const std::string &	get_slice_user_ownership () const

const std::string &	get_slice_group_ownership () const

const infinint &	get_repeat_count () const

const infinint &	get_repeat_byte () const

bool	get_sequential_marks () const

infinint	get_sparse_file_min_size () const

bool	get_security_check () const

const std::string &	get_user_comment () const

hash_algo	get_hash_algo () const

infinint	get_slice_min_digits () const

const std::string &	get_backup_hook_file_execute () const

const mask &	get_backup_hook_file_mask () const

bool	get_ignore_unknown_inode_type () const

const std::shared_ptr< entrepot > &	get_entrepot () const

const fsa_scope &	get_fsa_scope () const

U_I	get_multi_threaded_crypto () const

U_I	get_multi_threaded_compress () const

bool	get_delta_diff () const

bool	get_delta_signature () const

const mask &	get_delta_mask () const

bool	get_has_delta_mask_been_set () const

const infinint &	get_delta_sig_min_size () const

bool	get_auto_zeroing_neg_dates () const

const std::set< std::string > &	get_ignored_as_symlink () const

modified_data_detection	get_modified_data_detection () const

const infinint &	get_iteration_count () const

hash_algo	get_kdf_hash () const

delta_sig_block_size	get_sig_block_len () const

Private Member Functions
void	nullifyptr () noexcept

void	destroy () noexcept

void	copy_from (const archive_options_create &ref)

void	move_from (archive_options_create &&ref) noexcept

void	destroy_mask (mask *&ptr)

void	clean_mask (mask *&ptr)

void	check_mask (const mask &m)

Private Attributes
std::shared_ptr< archive >	x_ref_arch
	just contains the address of an existing object, no local copy of object is done here

mask *	x_selection
	points to a local copy of mask (must be allocated / releases by the archive_option_create object)

mask *	x_subtree
	points to a local copy of mask (must be allocated / releases by the archive_option_create objects)

bool	x_allow_over

bool	x_warn_over

bool	x_info_details

bool	x_display_treated

bool	x_display_treated_only_dir

bool	x_display_skipped

bool	x_display_finished

infinint	x_pause

bool	x_empty_dir

compression	x_compr_algo

U_I	x_compression_level

U_I	x_compression_block_size

infinint	x_file_size

infinint	x_first_file_size

mask *	x_ea_mask
	points to a local copy of mask (must be allocated / releases by the archive_option_create objects)

std::string	x_execute

crypto_algo	x_crypto

secu_string	x_pass

U_32	x_crypto_size

std::vector< std::string >	x_gnupg_recipients

std::vector< std::string >	x_gnupg_signatories

mask *	x_compr_mask
	points to a local copy of mask (must be allocated / releases by the archive_option_create objects)

infinint	x_min_compr_size

bool	x_nodump

std::string	exclude_by_ea

comparison_fields	x_what_to_check

infinint	x_hourshift

bool	x_empty

bool	x_alter_atime

bool	x_old_alter_atime
	used to backup origina alter_atime value when activating furtive read mode

bool	x_furtive_read

bool	x_same_fs

std::deque< std::string >	x_same_fs_include

std::deque< std::string >	x_same_fs_exclude

bool	x_snapshot

bool	x_cache_directory_tagging

infinint	x_fixed_date

std::string	x_slice_permission

std::string	x_slice_user_ownership

std::string	x_slice_group_ownership

infinint	x_repeat_count

infinint	x_repeat_byte

bool	x_sequential_marks

infinint	x_sparse_file_min_size

bool	x_security_check

std::string	x_user_comment

hash_algo	x_hash

infinint	x_slice_min_digits

mask *	x_backup_hook_file_mask

std::string	x_backup_hook_file_execute

bool	x_ignore_unknown

std::shared_ptr< entrepot >	x_entrepot

fsa_scope	x_scope

U_I	x_multi_threaded_crypto

U_I	x_multi_threaded_compress

bool	x_delta_diff

bool	x_delta_signature

mask *	x_delta_mask

bool	has_delta_mask_been_set

infinint	x_delta_sig_min_size

bool	x_auto_zeroing_neg_dates

std::set< std::string >	x_ignored_as_symlink

modified_data_detection	x_modified_data_detection

infinint	x_iteration_count

hash_algo	x_kdf_hash

delta_sig_block_size	x_sig_block_len

Detailed Description

class holding optional parameters used to create an archive

Definition at line 287 of file archive_options.hpp.

Member Function Documentation

◆ set_alter_atime()

void libdar::archive_options_create::set_alter_atime ( bool alter_atime )

inline

whether to alter atime or ctime in the filesystem when reading files to save

Parameters

[in] alter_atime whether to change atime (true) or ctime (false)

Note: this parameter is used only when furtive_read_mode() is not activated

Definition at line 462 of file archive_options.hpp.

References x_old_alter_atime.

◆ set_compression_block_size()

void libdar::archive_options_create::set_compression_block_size ( U_I compression_block_size )

inline

set the compression block size

Parameters

[in] compression_block_size if set to zero (which is the default value) compression is performed without block in one single stream per file. This is the historical way used by libdar, it gives the best result and the lowest compute overhead, though it cannot be parallelized. At the opposite using compresion per block reduce the compression ratio but allows the block to be compressed/decompressed in parallel and thus leverage multi-core systems. When the block size increase you tend to the same compression ratio as compression ration without block

Definition at line 375 of file archive_options.hpp.

◆ set_crypto_pass()

void libdar::archive_options_create::set_crypto_pass ( const secu_string & pass )

inline

set the pass the password / passphrase to use. Giving an empty string makes the password asked interactively through the dialog argument if encryption has been set.

Definition at line 413 of file archive_options.hpp.

◆ set_delta_diff()

void libdar::archive_options_create::set_delta_diff ( bool val )

inline

whether binary delta has to be computed for differential/incremental backup

Note: this requires delta signature to be present in the archive of reference

Definition at line 558 of file archive_options.hpp.

References libdar::compile_time::librsync().

◆ set_delta_sig_min_size()

void libdar::archive_options_create::set_delta_sig_min_size ( const infinint & val )

inline

whether to never calculate delta signature for files which size is smaller or equal to the given argument

Note: by default a min size of 10 kiB is used

Definition at line 569 of file archive_options.hpp.

◆ set_display_treated()

void libdar::archive_options_create::set_display_treated	(	bool	display_treated,
		bool	only_dir
	)

inline

defines whether to show treated files

Parameters

[in]	display_treated	true to display processed inodes
[in]	only_dir	only display the current directory under process, not its individual files

Definition at line 345 of file archive_options.hpp.

◆ set_exclude_by_ea()

void libdar::archive_options_create::set_exclude_by_ea ( const std::string & ea_name )

inline

defines whether to ignore files having a given EA

Note: if ea_name is set to "" the default ea_name "user.libdar_no_backup" is used.

Definition at line 446 of file archive_options.hpp.

◆ set_execute()

void libdar::archive_options_create::set_execute ( const std::string & execute )

inline

set the command to execute after each slice creation

several macros are available:

%n : the number of the just created slice
%N : the slice number with padded zeros according to slice_min_digits given option
%b : the archive basename
%p : the slices path
%e : the archive extension (usually "dar")
%c : the archive context ("init", "operation" or "last_slice") see dar(1) man page for more details
%%% : substitued by %%

Definition at line 406 of file archive_options.hpp.

◆ set_gnupg_recipients()

void libdar::archive_options_create::set_gnupg_recipients ( const std::vector< std::string > & gnupg_recipients )

inline

set the list of recipients that will be able to read the archive

Note: this is based on GnuPG keyring and assumes the user running libdar has its keyring containing for each recipient a valid public key. If a list of recipient is given the crypto_pass (see above) is not used, but the crypto_algo stays used to encrypt the archive using a randomly generated key which is encrypted using the public keys of the recipients and dropped that way encrypted inside the archive.; if crypto_algo is not set while a list of recipient is given, the crypto algo will default to blowfish; since release 2.7.0 if a given std::string in the list contains an '@' the string is assumed to be an email and search is done in the keyring for that field type, else it is assumed to be a keyid.

Definition at line 427 of file archive_options.hpp.

◆ set_gnupg_signatories()

void libdar::archive_options_create::set_gnupg_signatories ( const std::vector< std::string > & gnupg_signatories )

inline

the private keys matching the email or the keyid of the provided list are used to sign the archive random key

Note: since release 2.7.0 if a given std::string in the list contains an '@' the string is assumed to be an email and search is done in the keyring for that field type, else it is assumed to be a keyid.

Definition at line 433 of file archive_options.hpp.

◆ set_hash_algo()

void libdar::archive_options_create::set_hash_algo ( hash_algo hash )

specify whether to produce a hash file of the slice and which hash algo to use

Note: the libdar::hash_algo data type is defined in hash_fichier.hpp, valid values are for examle libdar::hash_none, libdar::hash_md5, libdar::hash_sha1, libdar::hash_sha512...

◆ set_ignored_as_symlink()

void libdar::archive_options_create::set_ignored_as_symlink ( const std::set< std::string > & list )

inline

provide a list of full path which if are symlinks will be considered as the inode they point to

Note: this is espetially intended for use with symlinks pointing to directories to have dar recursing in such pointed to directory instead of just recording that directory

Definition at line 578 of file archive_options.hpp.

◆ set_info_details()

void libdar::archive_options_create::set_info_details ( bool info_details )

inline

defines whether the user needs detailed output of the operation

Note: in API 5.5.x and before this switch drove the displaying of processing messages and treated files. now it only drives the display of processing messages, use set_display_treated to define whether files under treatement should be display or not

Definition at line 339 of file archive_options.hpp.

◆ set_multi_threaded()

void libdar::archive_options_create::set_multi_threaded ( bool val )

inline

whether libdar is allowed to spawn several threads to possibily work faster on multicore CPU (requires libthreadar)

Deprecated:: this call is deprecated, see set_multi_threaded_*() more specific calls

Note: setting this to true is equivalent to calling set_mutli_threaded_crypto(2)

Definition at line 547 of file archive_options.hpp.

◆ set_same_fs()

void libdar::archive_options_create::set_same_fs ( bool same_fs )

inline

whether to limit the backup to files located on the same filesystem as the directory taken as root of the backup

Note: if using this method, all value set using set_same_fs_include and set_same_fs_exclude so far are forgotten and ignored.

Definition at line 477 of file archive_options.hpp.

◆ set_same_fs_exclude()

void libdar::archive_options_create::set_same_fs_exclude ( const std::string & excluded_path_to_fs )

inline

files on the filesystem pointed to by the given path will not be considered for backup operation

Note: if using this method any previous call to the legacy set_same_fs(bool) invocation is ignored

Definition at line 487 of file archive_options.hpp.

◆ set_same_fs_include()

void libdar::archive_options_create::set_same_fs_include ( const std::string & included_path_to_fs )

inline

files on the filesystem pointed to by the given path will be considered for the backup operation if not excluded by set_same_fs_exclude()

Note: if using this method any previous call to the legacy set_same_fs(bool) invocation is ignored

Definition at line 482 of file archive_options.hpp.

◆ set_slicing()

void libdar::archive_options_create::set_slicing	(	const infinint &	file_size,
		const infinint &	first_file_size = `0`
	)

inline

define the archive slicing

Parameters

[in]	file_size	set the slice size in byte (0 for a single slice whatever its size is)
[in]	first_file_size	set the first file size

Note: if not specified or set to zero, first_file_size is considered equal to file_size

Definition at line 382 of file archive_options.hpp.

◆ set_subtree()

void libdar::archive_options_create::set_subtree ( const mask & subtree )

defines the directories and files to consider

Note: WARNING: this mask will be applied to the absolute path of files being proceeded. We speak here about the root of the filesystem under which the fs_root directory contains the files to backup. This is independent from the fs_root argument of class archive constructor which objective is to reduce the perimeter of the backup. The subtree filters do not compare only to the path inside the fs_root directory but to the full path, including the fs_root directory. In other words, if the subtree mask do not accept anything under fs_root path, the resulting backup will be empty.

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

archive_options.hpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ set_alter_atime()

◆ set_compression_block_size()

◆ set_crypto_pass()

◆ set_delta_diff()

◆ set_delta_sig_min_size()

◆ set_display_treated()

◆ set_exclude_by_ea()

◆ set_execute()

◆ set_gnupg_recipients()

◆ set_gnupg_signatories()

◆ set_hash_algo()

◆ set_ignored_as_symlink()

◆ set_info_details()

◆ set_multi_threaded()

◆ set_same_fs()

◆ set_same_fs_exclude()

◆ set_same_fs_include()

◆ set_slicing()

◆ set_subtree()