command-line interface More...

Files
file	command_line.hpp
	contains routing in charge of the command-line and included files parsing

file	config_file.hpp
	specific routines to manages included files's targets

file	crit_action_cmd_line.hpp
	contains routines to convert command-line overwriting criterium to their crit_action counterparts

file	dar.hpp
	main module for dar command-line tool

file	dar_suite.hpp
	contains routine to manage CLI's common initialization and ultimate exception catching

file	getopt_decision.h
	switch routine to define which file to include based on the result of the configure script

file	hide_file.hpp
	contains class of base to split files in words

file	line_tools.hpp
	a set of general command line targeted routines

file	my_getopt_long.h
	may lead to the definition of getopt_long to solve declaration conflicts in <unistd.h> and <getopt.h>

file	no_comment.hpp
	contains class that transparently strips out the comments from configuration file

Classes
struct	ent_params
	entrepot relative parameters More...

struct	line_param
	all parameters retreived from command-line More...

Typedefs
using	cli_callback = S_I()(std::shared_ptr< user_interaction > &dialog, int, char const[], const char **env)

Enumerations
enum	operation { noop , extract , create , diff , test , listing , isolate , merging , version_or_help , repairing }

enum	dirty_behavior { dirtyb_ignore , dirtyb_warn , dirtyb_ok }

Functions
bool	get_args (shared_ptr< user_interaction > &dialog, const char home, const deque< string > &dar_dcf_path, const deque< string > &dar_duc_path, S_I argc, char const argv[], line_param &param)
	main routine to extract parameters from command-line and included files

const char *	get_short_opt ()

std::string	crit_action_canonize_string (const std::string &argument)
	canonizes a criterium description string More...

const libdar::crit_action *	crit_action_create_from_string (libdar::user_interaction &dialog, const std::string &argument, const libdar::infinint &hourshift)
	creates a criterium object as defined by the command line's given string More...

const char *	dar_version ()

void	dar_suite_reset_signal_handler ()

int	dar_suite_global (int argc, char const argv[], const char env, const char getopt_string, char stop_scan, cli_callback call)
	common routine for all dar command-line tools to initialize environment and convert uncaught exceptions to exit status code More...

std::string	dar_suite_command_line_features ()

void	line_tools_slice_ownership (const std::string &cmd, std::string &slice_permission, std::string &slice_user_ownership, std::string &slice_group_ownership)

void	line_tools_repeat_param (const std::string &cmd, infinint &repeat_count, infinint &repeat_byte)

void	line_tools_tlv_list2argv (user_interaction &dialog, tlv_list &list, argc_argv &arg)

S_I	line_tools_reset_getopt ()
	returns the old position of parsing (next argument to parse)

std::string::const_iterator	line_tools_find_first_char_out_of_parenth (const std::string &argument, unsigned char to_find)

std::string::const_iterator	line_tools_find_last_char_out_of_parenth (const std::string &argument, unsigned char to_find)

std::string	line_tools_expand_user_comment (const std::string &user_comment, S_I argc, char *const argv[])

std::deque< std::string >	line_tools_explode_PATH (const char *the_path)
	split a PATH environement variable string into its components (/usr/lib:/lib => /usr/lib /lib)

std::string	line_tools_get_full_path_from_PATH (const std::deque< std::string > &the_path, const char *filename)
	return the full path of the given filename (eventually unchanged of pointing to the first file of that name present in the_path directories

void	line_tools_split_at_first_space (const char *field, std::string &before_space, std::string &after_space)
	return split at the first space met the string given as first argument, and provide the two splitted string as second and third argument

void	line_tools_get_min_digits (std::string arg, infinint &num, infinint &ref_num, infinint &aux_num)

void	line_tools_look_for (const std::deque< char > &arguments, S_I argc, char const argv[], const char getopt_string, char stop_scan, std::deque< char > &presence)
	test the presence of a set of argument on the command line More...

void	line_tools_look_for_Q (S_I argc, char const argv[], const char getopt_string, char stop_scan, bool &Q_is_present)
	test the presence of -Q and -j options on the command line More...

template<class T >
void	line_tools_split (const std::string &val, char sep, T &split)
	split a line in words given the separator character (sep)

std::set< std::string >	line_tools_deque_to_set (const std::deque< std::string > &list)

void	line_tools_4_4_build_compatible_overwriting_policy (bool allow_over, bool detruire, bool more_recent, const libdar::infinint &hourshift, bool ea_erase, const libdar::crit_action *&overwrite)

void	line_tools_crypto_split_algo_pass (const secu_string &all, crypto_algo &algo, secu_string &pass, bool &no_cipher_given, std::vector< std::string > &recipients)

void	line_tools_display_signatories (user_interaction &ui, const std::list< signator > &gnupg_signed)
	display information about the signatories

void	line_tools_read_from_pipe (std::shared_ptr< user_interaction > &dialog, S_I fd, tlv_list &result)
	Extract from anonymous pipe a tlv_list. More...

void	line_tools_extract_basename (const char *command_name, std::string &basename)
	extracts the basename of a file (removing path part) More...

std::string::iterator	line_tools_find_first_char_of (std::string &s, unsigned char v)
	give a pointer to the last character of the given value in the given string More...

void	line_tools_split_path_basename (const char all, path &chemin, std::string &base)
	split a given full path in path part and basename part More...

void	line_tools_split_path_basename (const std::string &all, std::string &chemin, std::string &base)
	split a given full path in path part and basename part More...

bool	line_tools_split_entrepot_path (const std::string &all, std::string &proto, std::string &login, secu_string &password, std::string &hostname, std::string &port, std::string &path_basename)
	split a given full remote repository path in parts More...

S_I	line_tools_str2signed_int (const std::string &x)
	convert a signed integer written in decimal notation to the corresponding value More...

infinint	line_tools_convert_date (const std::string &repres)
	convert a human readable date representation in number of second since the system reference date More...

void	line_tools_display_features (user_interaction &dialog)
	display the compilation time features of libdar More...

const char *	line_tools_get_from_env (const char *env, const char clef)
	isolate the value of a given variable from the environment vector More...

void	line_tools_check_basename (user_interaction &dialog, const path &loc, std::string &base, const std::string &extension, bool create)
	does sanity checks on a slice name, check presence and detect whether the given basename is not rather a filename More...

void	line_tools_check_min_digits (user_interaction &dialog, const path &loc, const std::string &base, const std::string &extension, infinint &num_digits)
	if a slice number 1 is met with the provided basename, set the num_digits accordingly More...

void	line_tools_read_range (const std::string &s, S_I &min, U_I &max)
	from a string with a range notation (min-max) extract the range values More...

template<class T >
void	line_tools_split_in_words (generic_file &f, T &mots)
	read a file and split its contents into words More...

template<class T >
void	line_tools_split_in_words (const std::string &arg, T &mots)
	read a std::string and split its contents into words More...

std::string	line_tools_build_regex_for_exclude_mask (const std::string &prefix, const std::string &relative_part)
	builds a regex from root directory and user provided regex to be applied to the relative path More...

std::string	line_tools_get_euid ()
	return a string containing the Effective UID

std::string	line_tools_get_egid ()
	return a string containing the Effective UID

std::string	line_tools_get_hostname ()
	return a string containing the hostname of the current host

std::string	line_tools_get_date_utc ()
	return a string containing the current time (UTC)

void	line_tools_merge_to_deque (std::deque< std::string > &a, const std::deque< std::string > &b)
	add in 'a', element of 'b' not already found in 'a'

std::deque< std::string >	line_tools_substract_from_deque (const std::deque< std::string > &a, const std::deque< std::string > &b)
	remove from 'a' elements found in 'b' and return the resulting deque

delta_sig_block_size::fs_function_t	line_tools_string_to_sig_block_size_function (const std::string &funname)
	converts string name to function More...

void	line_tools_split_compression_algo (const char *arg, U_I base, compression &algo, U_I &level, U_I &block_size)

Variables
constexpr U_I	LINE_TOOLS_SI_SUFFIX = 1000

constexpr U_I	LINE_TOOLS_BIN_SUFFIX = 1024

Detailed Description

command-line interface

this module contains all the command-line specific routines, classes and datastructures. The intention of documenting that part is for illustration and example of libdar usage.

Function Documentation

◆ crit_action_canonize_string()

std::string crit_action_canonize_string ( const std::string & argument )

canonizes a criterium description string

Parameters

[in] argument is a not canonized criterium description string

Returns: a canonized description string

Note: criterium description strings when not canonized may include spaces tabs and carriage return for readability. Canonizing a criterium description string is to remove all these non significant characters.

◆ crit_action_create_from_string()

const libdar::crit_action* crit_action_create_from_string	(	libdar::user_interaction &	dialog,
		const std::string &	argument,
		const libdar::infinint &	hourshift
	)

creates a criterium object as defined by the command line's given string

Parameters

[in]	dialog	for user interaction
[in]	argument	is a canonized criterium argument
[in]	hourshift	the hourshift used to compare dates "more recent than"

Returns: a criterium object

Note: this function is recursive, it may throw Erange exception in case of syntaxical error; second point, the returned object is dynamically allocated, this is the duty of the caller to release its memory calling the delete operator.

◆ dar_suite_global()

int dar_suite_global	(	int	argc,
		char *const	argv[],
		const char **	env,
		const char *	getopt_string,
		char	stop_scan,
		cli_callback	call
	)

common routine for all dar command-line tools to initialize environment and convert uncaught exceptions to exit status code

Parameters

[in]	argc	is the number of argument on the command line
[in]	argv	is the list of arguments on the command line
[in]	env	is the environment variables table obtained from main()
[in]	getopt_string	is the parsing string to pass to getopt
[in]	stop_scan	while looking early for -j and -Q option will ignore all that follows stop_scan option if met
[in]	call	is a callback function to run once user interaction is initialized and to catch from the exceptions

Returns: the application exist status to use

◆ line_tools_build_regex_for_exclude_mask()

std::string line_tools_build_regex_for_exclude_mask	(	const std::string &	prefix,
		const std::string &	relative_part
	)

builds a regex from root directory and user provided regex to be applied to the relative path

Parameters

[in]	prefix	is the root portion of the path
[in]	relative_part	is the user provided regex to be applied to the relative path

Returns: the corresponding regex to be applied to full absolute path

◆ line_tools_check_basename()

void line_tools_check_basename	(	user_interaction &	dialog,
		const path &	loc,
		std::string &	base,
		const std::string &	extension,
		bool	create
	)

does sanity checks on a slice name, check presence and detect whether the given basename is not rather a filename

Parameters

[in,out]	dialog	for user interaction
[in]	loc	the path where resides the slice
[in,out]	base	the basename of the slice
[in]	extension	the extension of dar's slices
[in]	create	whether this is a new archive that is about to be created by this name

Note: if user accepted the change of slice name proposed by libdar through dialog the base argument is changed

◆ line_tools_check_min_digits()

void line_tools_check_min_digits	(	user_interaction &	dialog,
		const path &	loc,
		const std::string &	base,
		const std::string &	extension,
		infinint &	num_digits
	)

if a slice number 1 is met with the provided basename, set the num_digits accordingly

Parameters

[in,out]	dialog	for user interaction
[in]	loc	the path where are expected the slices to be present
[in]	base	the basename of the archive
[in]	extension	the extension of dar's slices
[in,out]	num_digits	the min width of slice number (0 padded numbers)

◆ line_tools_convert_date()

infinint line_tools_convert_date ( const std::string & repres )

convert a human readable date representation in number of second since the system reference date

Parameters

[in] repres the date's human representation

Returns: the corresponding number of seconds (computer time)

Note: the string expected format is "[[[year/]month/]day-]hour:minute[:second]"

◆ line_tools_crypto_split_algo_pass()

void line_tools_crypto_split_algo_pass	(	const secu_string &	all,
		crypto_algo &	algo,
		secu_string &	pass,
		bool &	no_cipher_given,
		std::vector< std::string > &	recipients
	)

split the argument to -K, -J and -$ in their different parts

Parameters

[in]	all	is what the user provided on command-line
[out]	algo	is the symmetrical algorithm to use
[out]	pass	is either the passphrase
[out]	no_cipher_given	is true if the use did not specified the cipher (which defaults to blowfish)
[out]	recipients	emails recipients to use (empty list if gnupg has not to be used)

◆ line_tools_display_features()

void line_tools_display_features ( user_interaction & dialog )

display the compilation time features of libdar

Parameters

[in,out] dialog for user interaction

Note: this call uses the compile_time:: routines, and will not change its interface upon new feature addition

◆ line_tools_extract_basename()

void line_tools_extract_basename	(	const char *	command_name,
		std::string &	basename
	)

extracts the basename of a file (removing path part)

Parameters

[in]	command_name	is the full path of the file
[out]	basename	the basename of the file

Exceptions

Ememory can be thrown if memory allocation failed

◆ line_tools_find_first_char_of()

std::string::iterator line_tools_find_first_char_of	(	std::string &	s,
		unsigned char	v
	)

give a pointer to the last character of the given value in the given string

Parameters

[in]	s	is the given string
[in]	v	is the given char value

Returns: a interator on s, pointing on the first char of s equal to v or a pointing to s.end() if no such char could be found is "s"

Note: the arguments are not modified neither the data they are pointing to. However the const statement has not been used to be able to return a iterator on the string (and not a const_interator). There is probably other ways to do that (using const_cast) for example

◆ line_tools_get_from_env()

const char* line_tools_get_from_env	(	const char **	env,
		const char *	clef
	)

isolate the value of a given variable from the environment vector

Parameters

[in]	env	the environment vector as retreived from the third argument of the main() function
[in]	clef	the key or variable name too look for

Returns: nullptr if the key could not be found or a pointer to the env data giving the value of the requested key

Note: the returned value must not be released by any mean as it is just a pointer to an system allocated memory (the env vector).

◆ line_tools_look_for()

void line_tools_look_for	(	const std::deque< char > &	arguments,
		S_I	argc,
		char *const	argv[],
		const char *	getopt_string,
		char	stop_scan,
		std::deque< char > &	presence
	)

test the presence of a set of argument on the command line

Parameters

[in]	arguments	is the list of options to look for
[in]	argc	is the number of argument on the command line
[in]	argv	is the list of arguments on the command line
[in]	getopt_string	is the parsing string to pass to getopt
[in]	stop_scan	if this (char) option is met, stop scanning for wanted options
[out]	presence	is a subset of arguments containing the option found on command-line

◆ line_tools_look_for_Q()

void line_tools_look_for_Q	(	S_I	argc,
		char *const	argv[],
		const char *	getopt_string,
		char	stop_scan,
		bool &	Q_is_present
	)

test the presence of -Q and -j options on the command line

Parameters

[in]	argc	is the number of argument on the command line
[in]	argv	is the list of arguments on the command line
[in]	getopt_string	is the parsing string to pass to getopt
[in]	stop_scan	if this (char) option is met, stop scanning for -j and -Q options
[out]	Q_is_present	is set to true if -Q option or its equivalent long option has been found on command-line

◆ line_tools_read_from_pipe()

void line_tools_read_from_pipe	(	std::shared_ptr< user_interaction > &	dialog,
		S_I	fd,
		tlv_list &	result
	)

Extract from anonymous pipe a tlv_list.

Parameters

[in,out]	dialog	for user interaction
[in]	fd	the filedescriptor for the anonymous pipe's read extremity
[out]	result	the resulting tlv_list

◆ line_tools_read_range()

void line_tools_read_range	(	const std::string &	s,
		S_I &	min,
		U_I &	max
	)

from a string with a range notation (min-max) extract the range values

Parameters

[in]	s	the string to parse
[out]	min	the minimum value of the range
[out]	max	the maximum value of the range

Exceptions

Erange is thrown is the string to parse is incorrect

Note: : either a single number (positive or negative) is returned in min (max is set to min if min is positive or to zero if min is negative) or a range of positive numbers.

◆ line_tools_split_compression_algo()

void line_tools_split_compression_algo	(	const char *	arg,
		U_I	base,
		compression &	algo,
		U_I &	level,
		U_I &	block_size
	)

Parameters

arg	input string to analyse
base	base value for number suffix
algo	returned compression algorithm
level	returned compression level
block_size	returned compression block size

◆ line_tools_split_entrepot_path()

bool line_tools_split_entrepot_path	(	const std::string &	all,
		std::string &	proto,
		std::string &	login,
		secu_string &	password,
		std::string &	hostname,
		std::string &	port,
		std::string &	path_basename
	)

split a given full remote repository path in parts

Parameters

[in]	all	is the argument to split in parts
[out]	proto	is the protocol field
[out]	login	is the login field (empty string is returned if not provided)
[out]	password	is the password field (empty string if not provided)
[out]	hostname	is the hostname field
[out]	port	is the port field (empty string if not provided)
[out]	path_basename	is the path+basename remaing field

Returns: false if the all argument does not follow the remote repository syntax

◆ line_tools_split_in_words() [1/2]

template<class T >

void line_tools_split_in_words	(	const std::string &	arg,
		T &	mots
	)

read a std::string and split its contents into words

Parameters

[in,out]	arg	is the string to read
[out]	mots	a std container to receive the split result

Returns: the list of words found in this order in the file

Note: The different quotes are taken into account

Definition at line 414 of file line_tools.hpp.

References line_tools_split_in_words(), libdar::memory_file::skip(), and libdar::generic_file::write().

◆ line_tools_split_in_words() [2/2]

template<class T >

void line_tools_split_in_words	(	generic_file &	f,
		T &	mots
	)

read a file and split its contents into words

Parameters

[in,out]	f	is the file to read
[out]	mots	std container to receive the split result

Returns: the list of words found in this order in the file

Note: The different quotes are taken into account

Definition at line 311 of file line_tools.hpp.

References libdar::dar_gettext(), libdar::generic_file::read(), and libdar::tools_printf().

Referenced by line_tools_split_in_words().

◆ line_tools_split_path_basename() [1/2]

void line_tools_split_path_basename	(	const char *	all,
		path *&	chemin,
		std::string &	base
	)

split a given full path in path part and basename part

Parameters

[in]	all	is the path to split
[out]	chemin	is the resulting path part, it points to a newly allocated path object
[out]	base	is the resulting basename

Note: chemin argument must be release by the caller thanks to the "delete" operator.

◆ line_tools_split_path_basename() [2/2]

void line_tools_split_path_basename	(	const std::string &	all,
		std::string &	chemin,
		std::string &	base
	)

split a given full path in path part and basename part

Parameters

[in]	all	is the path to split
[out]	chemin	is the resulting path part, it points to a newly allocated path object
[out]	base	is the resulting basename

Note: chemin argument must be release by the caller thanks to the "delete" operator.

◆ line_tools_str2signed_int()

S_I line_tools_str2signed_int ( const std::string & x )

convert a signed integer written in decimal notation to the corresponding value

Parameters

[in] x the decimal representation of the integer

Returns: the value corresponding to the decimal representation given

◆ line_tools_string_to_sig_block_size_function()

delta_sig_block_size::fs_function_t line_tools_string_to_sig_block_size_function ( const std::string & funname )

converts string name to function

Note: throws Erange in case of error

Files

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Function Documentation

◆ crit_action_canonize_string()

◆ crit_action_create_from_string()

◆ dar_suite_global()

◆ line_tools_build_regex_for_exclude_mask()

◆ line_tools_check_basename()

◆ line_tools_check_min_digits()

◆ line_tools_convert_date()

◆ line_tools_crypto_split_algo_pass()

◆ line_tools_display_features()

◆ line_tools_extract_basename()

◆ line_tools_find_first_char_of()

◆ line_tools_get_from_env()

◆ line_tools_look_for()

◆ line_tools_look_for_Q()

◆ line_tools_read_from_pipe()

◆ line_tools_read_range()

◆ line_tools_split_compression_algo()

◆ line_tools_split_entrepot_path()

◆ line_tools_split_in_words() [1/2]

◆ line_tools_split_in_words() [2/2]

◆ line_tools_split_path_basename() [1/2]

◆ line_tools_split_path_basename() [2/2]

◆ line_tools_str2signed_int()

◆ line_tools_string_to_sig_block_size_function()