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

Files | Classes | Typedefs | Enumerations | Functions | Variables
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)
| does sanity checks on a slice name, check presence and detect whether the given basename is not rather a filename 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...

## 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
| ) |  |

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

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

## ◆ 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_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 398 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 295 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