CMDLINE

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