Loading...
Searching...
No Matches
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
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
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
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
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
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.
void | line_tools_extract_basename (const char *command_name, std::string &basename)
| extracts the basename of a file (removing path part)
std::string::iterator | line_tools_find_first_char_of (std::string &s, unsigned char v)
| give a pointer to the first character of the given value in the given string
std::string::iterator | line_tools_find_last_char_of (std::string &s, unsigned char v)
| give a pointer to the last character of the given value in the given string
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
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
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
S_I | line_tools_str2signed_int (const std::string &x)
| convert a signed integer written in decimal notation to the corresponding value
infinint | line_tools_convert_date (const std::string &repres)
| convert a human readable date representation in number of second since the system reference date
void | line_tools_display_features (user_interaction &dialog)
| display the compilation time features of libdar
const char * | line_tools_get_from_env (const char **env, const char *clef)
| isolate the value of a given variable from the environment vector
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
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
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
template<class T>
void | line_tools_split_in_words (generic_file &f, T &mots)
| read a file and split its contents into words
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
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
void | line_tools_split_compression_algo (const char *arg, U_I base, compression &algo, U_I &level, U_I &block_size)
void | line_tools_split_mask_list_from_eols (const std::string &arg, std::string &filename, std::deque< std::string > &eols)
| convert –include-from-file / –exclude-from-file argument to its different components
std::string | line_tools_replace_escape_sequences (const std::string &arg)
| replace escape sequences by their real byte value

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

## Typedef Documentation

## cli_callback

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

Definition at line 73 of file dar_suite.hpp.

## Enumeration Type Documentation

## dirty_behavior

enum dirty_behavior

Definition at line 45 of file command_line.hpp.

## operation

enum operation

Definition at line 41 of file command_line.hpp.

## Function Documentation

## crit_action_canonize_string()

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

extern

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 )

extern

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 )

extern

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_check_basename()

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

extern

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

extern

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 )

extern

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

extern

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 )

extern

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 )

extern

give a pointer to the first 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_find_last_char_of()

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

extern

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

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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

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)

Definition at line 135 of file line_tools.hpp.

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

extern

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 )

extern

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] | arg | is the string to read
  [out] | mots | a std container to receive the split result

Note
  The different quotes are taken into account

Definition at line 421 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

Note
  The different quotes are taken into account

Definition at line 319 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 )

extern

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 )

extern

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

extern

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

extern

converts string name to function

Note
  throws Erange in case of error

## Variable Documentation

## LINE_TOOLS_BIN_SUFFIX

U_I LINE_TOOLS_BIN_SUFFIX = 1024

constexpr

Definition at line 45 of file line_tools.hpp.

## LINE_TOOLS_SI_SUFFIX

U_I LINE_TOOLS_SI_SUFFIX = 1000

constexpr

Definition at line 44 of file line_tools.hpp.