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

- Main Page
- Modules
- Namespaces
- Classes
- Files

Files | Functions
Tools

a set of tool routine More...

## Files
file | deci.hpp
| manages the decimal representation of infinint
file | tools.hpp
| a set of general purpose routines

## Functions
std::ostream & | libdar::operator<< (std::ostream &ref, const infinint &arg)
| specific << operator to use infinint in std::ostream More...
void | libdar::tools_init ()
| libdar internal use only: it is launched from get_version() and initializes tools internal variables
void | libdar::tools_end ()
| libdar internal use only: it is launched from close_and_clean() and releases tools internal variables
char * | libdar::tools_str2charptr (const std::string &x)
| convert a string to a char * More...
void | libdar::tools_write_string (generic_file &f, const std::string &s)
| write a string to a file with a '\0' at then end More...
void | libdar::tools_read_string (generic_file &f, std::string &s)
| read a string from a file expecting it to terminate by '\0' More...
void | libdar::tools_write_string_all (generic_file &f, const std::string &s)
| write a string to a file, '\0' has no special meaning nor is added at the end More...
void | libdar::tools_read_string_size (generic_file &f, std::string &s, infinint taille)
| read a string if given size from a file '\0' has no special meaning More...
infinint | libdar::tools_get_filesize (const path &p)
| retrieve the size in byte of a file More...
infinint | libdar::tools_get_extended_size (std::string s, U_I base)
| convert the given string to infinint taking care of multiplication suffixes like k, M, T, etc. More...
std::string | libdar::tools_display_integer_in_metric_system (infinint number, const std::string &unit, bool binary)
void | libdar::tools_extract_basename (const char *command_name, std::string &basename)
| extracts the basename of a file (removing path part) More...
std::string::iterator | libdar::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 More...
std::string::iterator | libdar::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 | libdar::tools_split_path_basename (const char *all, path *&chemin, std::string &base, memory_pool *pool=nullptr)
| split a given full path in path part and basename part More...
void | libdar::tools_split_path_basename (const std::string &all, std::string &chemin, std::string &base, memory_pool *pool=nullptr)
| split a given full path in path part and basename part More...
void | libdar::tools_open_pipes (user_interaction &dialog, const std::string &input, const std::string &output, tuyau *&in, tuyau *&out, memory_pool *pool=nullptr)
| open a pair of tuyau objects encapsulating two named pipes. More...
void | libdar::tools_blocking_read (int fd, bool mode)
| set blocking/not blocking mode for reading on a file descriptor More...
std::string | libdar::tools_name_of_uid (const infinint &uid)
| convert uid to name in regards to the current system's configuration More...
std::string | libdar::tools_name_of_gid (const infinint &gid)
| convert gid to name in regards of the current system's configuration More...
std::string | libdar::tools_uword2str (U_16 x)
| convert unsigned word to string More...
std::string | libdar::tools_int2str (S_I x)
| convert integer to string More...
std::string | libdar::tools_uint2str (U_I x)
U_I | libdar::tools_str2int (const std::string &x)
| convert an integer written in decimal notation to the corresponding value More...
S_I | libdar::tools_str2signed_int (const std::string &x)
| convert a signed integer written in decimal notation to the corresponding value More...
bool | libdar::tools_my_atoi (const char *a, U_I &val)
| ascii to integer conversion More...
std::string | libdar::tools_addspacebefore (std::string s, U_I expected_size)
| prepend spaces before the given string More...
std::string | libdar::tools_display_date (const datetime &date)
| convert a date in second to its human readable representation More...
infinint | libdar::tools_convert_date (const std::string &repres)
| convert a human readable date representation in number of second since the system reference date More...
void | libdar::tools_system (user_interaction &dialog, const std::vector< std::string > &argvector)
| wrapper to the "system" system call. More...
void | libdar::tools_system_with_pipe (user_interaction &dialog, const std::string &dar_cmd, const std::vector< std::string > &argvpipe, memory_pool *pool=nullptr)
| wrapper to the "system" system call using anonymous pipe to tranmit arguments to the child process More...
void | libdar::tools_write_vector (generic_file &f, const std::vector< std::string > &x)
| write a list of string to file More...
void | libdar::tools_read_vector (generic_file &f, std::vector< std::string > &x)
| read a list of string from a file More...
std::string | libdar::tools_concat_vector (const std::string &separator, const std::vector< std::string > &x)
| concatenate a vectors of strings in a single string More...
std::vector< std::string > | libdar::operator+ (std::vector< std::string > a, std::vector< std::string > b)
| concatenate two vectors More...
void | libdar::tools_display_features (user_interaction &dialog)
| display the compilation time features of libdar More...
bool | libdar::tools_is_equal_with_hourshift (const infinint &hourshift, const datetime &date1, const datetime &date2)
| test if two dates are equal taking care of a integer hour of difference More...
template<class T >
std::vector< T > | libdar::operator+= (std::vector< T > &a, const std::vector< T > &b)
| template function to add two vectors
const char * | libdar::tools_get_from_env (const char **env, const char *clef)
| isolate the value of a given variable from the environment vector More...
void | libdar::tools_check_basename (user_interaction &dialog, const path &loc, std::string &base, const std::string &extension, memory_pool *pool=nullptr)
| does sanity checks on a slice name, check presence and detect whether the given basename is not rather a filename More...
std::string | libdar::tools_getcwd ()
| get current working directory
std::string | libdar::tools_readlink (const char *root)
| returns the file pointed to by a symbolic link (or transparent if the file is not a symlink). More...
bool | libdar::tools_look_for (const char *argument, S_I argc, char *const argv[])
| test the presence of an argument More...
void | libdar::tools_noexcept_make_date (const std::string &chem, bool symlink, const datetime &last_acc, const datetime &last_mod, const datetime &birth)
| set dates of a given file, no exception thrown More...
void | libdar::tools_make_date (const std::string &chemin, bool symlink, const datetime &access, const datetime &modif, const datetime &birth)
| set dates of a given file, may throw exception More...
bool | libdar::tools_is_case_insensitive_equal (const std::string &a, const std::string &b)
| compare two string in case insensitive manner More...
void | libdar::tools_to_upper (const std::string &r, std::string &uppered)
| convert a string to upper case More...
void | libdar::tools_remove_last_char_if_equal_to (char c, std::string &s)
| remove last character of a string is it equal to a given value More...
void | libdar::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...
std::string | libdar::tools_printf (const char *format,...)
| make printf-like formating to a std::string More...
std::string | libdar::tools_vprintf (const char *format, va_list ap)
| make printf-like formating to a std::string More...
bool | libdar::tools_do_some_files_match_mask_regex (user_interaction &ui, const std::string &c_chemin, const std::string &file_mask)
| test the presence of files corresponding to a given mask in a directory (regex mask) More...
void | libdar::tools_unlink_file_mask_regex (user_interaction &dialog, const std::string &c_chemin, const std::string &file_mask, bool info_details)
| remove files from a given directory More...
void | libdar::tools_avoid_slice_overwriting_regex (user_interaction &dialog, const path &chemin, const std::string &basename, const std::string &extension, bool info_details, bool allow_overwriting, bool warn_overwriting, bool dry_run)
| prevents slice overwriting: check the presence of slice and if necessary ask the user if they can be removed More...
void | libdar::tools_add_elastic_buffer (generic_file &f, U_32 max_size, U_32 modulo, U_32 offset)
| append an elastic buffer of given size to the file More...
bool | libdar::tools_are_on_same_filesystem (const std::string &file1, const std::string &file2)
path | libdar::tools_relative2absolute_path (const path &src, const path &cwd)
| transform a relative path to an absolute one given the current directory value More...
void | libdar::tools_block_all_signals (sigset_t &old_mask)
| block all signals (based on POSIX sigprocmask) More...
void | libdar::tools_set_back_blocked_signals (sigset_t old_mask)
| unblock signals according to given mask More...
U_I | libdar::tools_count_in_string (const std::string &s, const char a)
| counts the number of a given char in a given string More...
datetime | libdar::tools_get_mtime (const std::string &s)
| returns the last modification date of the given file More...
infinint | libdar::tools_get_size (const std::string &s)
| returns the size of the given plain file More...
datetime | libdar::tools_get_ctime (const std::string &s)
| returns the last change date of the given file More...
std::vector< std::string > | libdar::tools_split_in_words (generic_file &f)
| read a file and split its contents into words More...
std::vector< std::string > | libdar::tools_split_in_words (const std::string &arg)
| read a std::string and split its contents into words More...
bool | libdar::tools_find_next_char_out_of_parenthesis (const std::string &data, const char what, U_32 start, U_32 &found)
| look next char in string out of parenthesis More...
std::string | libdar::tools_substitute (const std::string &hook, const std::map< char, std::string > &corres)
| produce the string resulting from the substition of % macro defined in the map More...
std::string | libdar::tools_hook_substitute (const std::string &hook, const std::string &path, const std::string &basename, const std::string &num, const std::string &padded_num, const std::string &ext, const std::string &context)
| produces the string resulting from the substitution of %... macro More...
void | libdar::tools_hook_execute (user_interaction &ui, const std::string &cmd_line)
| execute and retries at user will a given command line More...
void | libdar::tools_hook_substitute_and_execute (user_interaction &ui, const std::string &hook, const std::string &path, const std::string &basename, const std::string &num, const std::string &padded_num, const std::string &ext, const std::string &context)
| subsititue and execute command line More...
std::string | libdar::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 | libdar::tools_output2xml (const std::string &src)
| convert string for xml output More...
U_I | libdar::tools_octal2int (const std::string &perm)
| convert octal string to integer More...
std::string | libdar::tools_int2octal (const U_I &perm)
| convert a number to a string corresponding to its octal representation More...
std::string | libdar::tools_get_permission_string (char type, U_32 perm, bool hard)
| convert a permission number into its string representation (rwxrwxrwx)
void | libdar::tools_set_permission (S_I fd, U_I perm)
| change the permission of the file which descriptor is given More...
U_I | libdar::tools_get_permission (S_I fd)
| obtain the permission of the file which descriptor is given More...
uid_t | libdar::tools_ownership2uid (const std::string &user)
| change ownership of the file which descriptor is given More...
uid_t | libdar::tools_ownership2gid (const std::string &group)
| convert string group name or gid to numeric gid value More...
void | libdar::tools_set_ownership (S_I filedesc, const std::string &slice_user, const std::string &slice_group)
| change ownership of the file which descriptor is given More...
void | libdar::tools_memxor (void *dest, const void *src, U_I n)
| Produces in "dest" the XORed value of "dest" and "src". More...
tlv_list | libdar::tools_string2tlv_list (user_interaction &dialog, const U_16 &type, const std::vector< std::string > &data)
| Produces a list of TLV from a constant type and a list of string. More...
void | libdar::tools_read_from_pipe (user_interaction &dialog, S_I fd, tlv_list &result)
| Extract from anonymous pipe a tlv_list. More...
U_I | libdar::tools_pseudo_random (U_I max)
| Produces a pseudo random number x, where 0 <= x < max. More...
template<class N , class B >
std::vector< B > | libdar::tools_number_base_decomposition_in_big_endian (N number, const B &base)
| Template for the decomposition of any number in any base (decimal, octal, hexa, etc.) More...
std::string | libdar::tools_unsigned_char_to_hexa (unsigned char x)
| convert a unsigned char into its hexa decima representation More...
std::string | libdar::tools_string_to_hexa (const std::string &input)
| convert a string into its hexadecima representation More...
infinint | libdar::tools_file_size_to_crc_size (const infinint &size)
| Defines the CRC size to use for a given filesize. More...
std::string | libdar::tools_get_euid ()
| return a string containing the Effective UID
std::string | libdar::tools_get_egid ()
| return a string containing the Effective UID
std::string | libdar::tools_get_hostname ()
| return a string containing the hostname of the current host
std::string | libdar::tools_get_date_utc ()
| return a string containing the current time (UTC)
std::string | libdar::tools_get_compression_ratio (const infinint &storage_size, const infinint &file_size, bool compressed)
| return the string about compression ratio
std::string | libdar::tools_strerror_r (int errnum)
| wrapper routine to strerror_r
void | libdar::tools_merge_to_vector (std::vector< std::string > &a, const std::vector< std::string > &b)
| add in 'a', element of 'b' not already found in 'a'
std::vector< std::string > | libdar::tools_substract_from_vector (const std::vector< std::string > &a, const std::vector< std::string > &b)
| remove from 'a' elements found in 'b' and return the resulting vector
struct dirent * | libdar::tools_allocate_struct_dirent (const std::string &path_name, U_64 &max_name_length, memory_pool *pool=nullptr)
void | libdar::tools_release_struct_dirent (struct dirent *ptr)
void | libdar::tools_secu_string_show (user_interaction &dialog, const std::string &msg, const secu_string &key)
| display the content of a secu_string, this function is only for trouble shooting!
template<class T >
T | libdar::tools_max (T a, T b)
template<class T >
T | libdar::tools_min (T a, T b)
std::string | libdar::tools_escape_chars_in_string (const std::string &val, const char *to_escape)
| escape with a anti-slash character a set of chars found in the given string
bool | libdar::tools_infinint2U_64 (infinint val, U_64 &res)

## Detailed Description

a set of tool routine

these routines are available from libdar for historical reason, but are not part of the API. They are shared and used by dar, dar_slave, dar_xform, and dar_manager command. You should avoid using them in external program as they may be removed or changed without backward compatibility support.

## Function Documentation

std::vector<std::string> libdar::operator+ | ( | std::vector< std::string > | a,
|  | std::vector< std::string > | b
| ) |  |

concatenate two vectors

Parameters

  [in] | a | the first vector
  [in] | b | the second vector

Returns
  a vector containing the elements of a and the element of b

std::ostream& libdar::operator<< | ( | std::ostream & | ref,
|  | const infinint & | arg
| ) |  |

specific << operator to use infinint in std::ostream

including "deci.hpp" let this operator available so you can display infinint with the << std::ostream operator as you can do for standard types.

void libdar::tools_add_elastic_buffer | ( | generic_file & | f,
|  | U_32 | max_size,
|  | U_32 | modulo,
|  | U_32 | offset
| ) |  |

append an elastic buffer of given size to the file

Parameters

  [in,out] | f | file to append elastic buffer to
  [in] | max_size | size of the elastic buffer to add
  [in] | modulo | defines the size to choose (see note)
  [in] | offset | defines the offset to apply (see note)

Note
  the size of the elastic buffer should not exceed max_size but should be chosen in order to reach a size which is zero modulo "modulo" assuming the offset we add the elastic buffer at is "offset". If modulo is zero this the elastic buffer is randomly chosen from 1 to max_size without any concern about being congruent to a given modulo. Example if module is 5 and offset is 2, the elastic buffer possible size can be 3 (2+3 is congruent to 0 modulo 5), 8 (2+8 is congruent to modulo 5), 12, etc. but not exceed max_size+modulo-1
  this is to accomodate the case when encrypted data is followed by clear data at the end of an archive. There is no way to known when we read clear data, but we know the clear data size is very inferior to crypted block size, thus when reading a uncompleted block of data we can be sure we have reached and of file and that the data is clear without any encrypted part because else we would have read an entire block of data.

std::string libdar::tools_addspacebefore | ( | std::string | s,
|  | U_I | expected_size
| ) |  |

prepend spaces before the given string

Parameters

  [in] | s | the string to append spaces to
  [in] | expected_size | the minimum size of the resulting string

Returns
  a string at least as much long as expected_size with prepended leading spaces if necessary

struct dirent* libdar::tools_allocate_struct_dirent | ( | const std::string & | path_name,
|  | U_64 & | max_name_length,
|  | memory_pool * | pool = `nullptr`
| ) |  |

allocate a new dirent structure for use with readdir_r

Parameters

  [in] | path_name | is the path of to the directory (and its underlying filesystem) where the resulting dirent will be used. Depending on fileystem, the size of the dirent structure may vary it is necessary to know the directory where the corresponding files resides
  [in] | pool | whether to allocate the structure on a memory_pool or out of memory_pool
  [out] | max_name_length | is the maximum filename length allocated in the returned structure which succeeds when pool is set to nullptr

Returns
  a pointer to the newly allocated dirent structure

bool libdar::tools_are_on_same_filesystem | ( | const std::string & | file1,
|  | const std::string & | file2
| ) |  |

tells whether two files are on the same mounted filesystem

Parameters

  [in] | file1 | first file
  [in] | file2 | second file

Returns
  true if the two file are located under the same mounting point

Note
  if one of the file is not present or if the filesystem information is not possible to be read an exception is throw (Erange)

void libdar::tools_avoid_slice_overwriting_regex | ( | user_interaction & | dialog,
|  | const path & | chemin,
|  | const std::string & | basename,
|  | const std::string & | extension,
|  | bool | info_details,
|  | bool | allow_overwriting,
|  | bool | warn_overwriting,
|  | bool | dry_run
| ) |  |

prevents slice overwriting: check the presence of slice and if necessary ask the user if they can be removed

Parameters

  [in,out] | dialog | for user interaction
  [in] | chemin | where slice is about to be created
  [in] | basename | is the archive basename
  [in] | extension | is the archive filename extension
  [in] | info_details | whether user must be displayed details of the operation
  [in] | allow_overwriting | whether overwriting is allowed by the user
  [in] | warn_overwriting | whether a warning must be issued before overwriting (if allowed)
  [in] | dry_run | do a dry-run exection (no filesystem modification is performed)

Note
  may thow exceptions.

void libdar::tools_block_all_signals | ( | sigset_t & | old_mask | ) |

block all signals (based on POSIX sigprocmask)

Parameters

  [out] | old_mask | is set to the old mask value (for later unmasking signals)

Exceptions

  Erange | is thrown if system call failed for some reason

void libdar::tools_blocking_read | ( | int | fd,
|  | bool | mode
| ) |  |

set blocking/not blocking mode for reading on a file descriptor

Parameters

  [in] | fd | file descriptor to read on
  [in] | mode | set to true for a blocking read and to false for non blocking read

std::string libdar::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

void libdar::tools_check_basename | ( | user_interaction & | dialog,
|  | const path & | loc,
|  | std::string & | base,
|  | const std::string & | extension,
|  | memory_pool * | pool = `nullptr`
| ) |  |

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] | pool | memory pool to use of nullptr for default memory allocation

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

std::string libdar::tools_concat_vector | ( | const std::string & | separator,
|  | const std::vector< std::string > & | x
| ) |  |

concatenate a vectors of strings in a single string

Parameters

  [in] | separator | string to insert between two elements
  [in] | x | the list string

Returns
  the result of the concatenation of the members of the list with separtor between two consecutive members

infinint libdar::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]"

U_I libdar::tools_count_in_string | ( | const std::string & | s,
|  | const char | a
| ) |  |

counts the number of a given char in a given string

Parameters

  [in] | s | string to look inside of
  [in] | a | char to look for

Returns
  the number of char found

std::string libdar::tools_display_date | ( | const datetime & | date | ) |

convert a date in second to its human readable representation

Parameters

  [in] | date | the date in second

Returns
  the human representation corresponding to the argument

void libdar::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

std::string libdar::tools_display_integer_in_metric_system | ( | infinint | number,
|  | const std::string & | unit,
|  | bool | binary
| ) |  |

convert an integer to its decimal representation with the highest unit of metric system

Parameters

  [in] | number | is the integer to convert
  [in] | unit | unit symbol (o for octet, m for meter, etc.) to apply metric system to, this may be nullptr
  [in] | binary | if set to true using the ki, Gi, Mi ... scale instead of the traditional k, G, M, ... prefixes

Returns
  the string representing the number in metric system (ex: "1 ko", "200 Mio", ...)

bool libdar::tools_do_some_files_match_mask_regex | ( | user_interaction & | ui,
|  | const std::string & | c_chemin,
|  | const std::string & | file_mask
| ) |  |

test the presence of files corresponding to a given mask in a directory (regex mask)

Parameters

  [in,out] | ui | for user interaction
  [in] | c_chemin | directory where file have to be looked for
  [in] | file_mask | regex expression which designates the files to look for

Returns
  true if some files have found matching the file_mask

void libdar::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

infinint libdar::tools_file_size_to_crc_size | ( | const infinint & | size | ) |

Defines the CRC size to use for a given filesize.

Parameters

  [in] | size | is the size of the file to protect by CRC

Returns
  crc_size is the size of the crc to use

std::string::iterator libdar::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

std::string::iterator libdar::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

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

bool libdar::tools_find_next_char_out_of_parenthesis | ( | const std::string & | data,
|  | const char | what,
|  | U_32 | start,
|  | U_32 & | found
| ) |  |

look next char in string out of parenthesis

Parameters

  [in] | data | is the string to look into
  [in] | what | is the char to look for
  [in] | start | is the index in string to start from, assuming at given position we are out of parenthesis
  [out] | found | the position of the next char equal to what

Returns
  true if a char equal to 'what' has been found and set the 'found' argument to its position or returns false if no such character has been found out of parenthesis

Note
  the 'found' argument is assigned only if the call returns true, its value is not to be used when false is returned from the call
  second point, the start data should point to a character that is out of any parenthesis, behavior is undefined else.

datetime libdar::tools_get_ctime | ( | const std::string & | s | ) |

returns the last change date of the given file

Parameters

  [in] | s | path of the file to get the last ctime

Returns
  the ctime of the given file

infinint libdar::tools_get_extended_size | ( | std::string | s,
|  | U_I | base
| ) |  |

convert the given string to infinint taking care of multiplication suffixes like k, M, T, etc.

Parameters

  [in] | s | is the string to read
  [in] | base | is the multiplication factor (base = 1000 for SI, base = 1024 for computer science use)

Returns
  the value encoded in the given string

infinint libdar::tools_get_filesize | ( | const path & | p | ) |

retrieve the size in byte of a file

Parameters

  [in] | p | is the path to the file which size is to get

Returns
  the size of the file in byte

const char* libdar::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 find 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).

datetime libdar::tools_get_mtime | ( | const std::string & | s | ) |

returns the last modification date of the given file

Parameters

  [in] | s | path of the file to get the last mtime

Returns
  the mtime of the given file

U_I libdar::tools_get_permission | ( | S_I | fd | ) |

obtain the permission of the file which descriptor is given

Parameters

  [in] | fd | file's descriptor

Returns
  permission of the given file

Note
  in case of error exception may be thrown

infinint libdar::tools_get_size | ( | const std::string & | s | ) |

returns the size of the given plain file

Parameters

  [in] | s | path of the file to get the size

Returns
  the size if the file in byte

void libdar::tools_hook_execute | ( | user_interaction & | ui,
|  | const std::string & | cmd_line
| ) |  |

execute and retries at user will a given command line

Parameters

  [in] | ui | which way to ask the user whether to continue upon command line error
  [in] | cmd_line | the command line to execute

std::string libdar::tools_hook_substitute | ( | const std::string & | hook,
|  | const std::string & | path,
|  | const std::string & | basename,
|  | const std::string & | num,
|  | const std::string & | padded_num,
|  | const std::string & | ext,
|  | const std::string & | context
| ) |  |

produces the string resulting from the substitution of %... macro

Parameters

  [in] | hook | the string in which to substitute
  [in] | path | is by what p will be replaced
  [in] | basename | is by what b will be replaced
  [in] | num | is by what n will be replaced
  [in] | padded_num | is by what N will be replaced
  [in] | ext | is by what e will be replaced
  [in] | context | is by what c will be replaced

Returns
  the substitued resulting string

Note
  it now relies on tools_substitue

void libdar::tools_hook_substitute_and_execute | ( | user_interaction & | ui,
|  | const std::string & | hook,
|  | const std::string & | path,
|  | const std::string & | basename,
|  | const std::string & | num,
|  | const std::string & | padded_num,
|  | const std::string & | ext,
|  | const std::string & | context
| ) |  |

subsititue and execute command line

Parameters

  [in,out] | ui | this is the way to contact the user
  [in] | hook | the string in which to substitute
  [in] | path | is by what p will be replaced
  [in] | basename | is by what b will be replaced
  [in] | num | is by what n will be replaced
  [in] | padded_num | is by what N will be replaced
  [in] | ext | is by what e will be replaced
  [in] | context | is by what c will be replaced

bool libdar::tools_infinint2U_64 | ( | infinint | val,
|  | U_64 & | res
| ) |  |

convert an infinint to U_64 (aka "uint64_t" or yet "unsigned long long")

Note
  : if the infinint is too large to fit in an U_64 it returns false

std::string libdar::tools_int2octal | ( | const U_I & | perm | ) |

convert a number to a string corresponding to its octal representation

Parameters

  perm | is the octal number

Returns
  the corresponding octal string

std::string libdar::tools_int2str | ( | S_I | x | ) |

convert integer to string

Parameters

  [in] | x | the integer to convert

Returns
  the decimal representation of the given integer

bool libdar::tools_is_case_insensitive_equal | ( | const std::string & | a,
|  | const std::string & | b
| ) |  |

compare two string in case insensitive manner

Parameters

  [in] | a | first string to compare
  [in] | b | second string to compare

Returns
  whether the two string given in argument are equal in case insensitive comparison

bool libdar::tools_is_equal_with_hourshift | ( | const infinint & | hourshift,
|  | const datetime & | date1,
|  | const datetime & | date2
| ) |  |

test if two dates are equal taking care of a integer hour of difference

Parameters

  [in] | hourshift | is the number of integer hour more or less two date can be considered equal
  [in] | date1 | first date to compare
  [in] | date2 | second date to compare to

Returns
  whether dates are equal or not

bool libdar::tools_look_for | ( | const char * | argument,
|  | S_I | argc,
|  | char *const | argv[]
| ) |  |

test the presence of an argument

Parameters

  [in] | argument | is the command line argument to look for
  [in] | argc | is the number of argument on the command line
  [in] | argv | is the list of argument on the command line

Returns
  true if the argument is present in the list

Note
  THIS ROUTINE IS DEPRECATED AND WILL BE REMOVED IN A FUTURE VERSION OF LIBDAR

void libdar::tools_make_date | ( | const std::string & | chemin,
|  | bool | symlink,
|  | const datetime & | access,
|  | const datetime & | modif,
|  | const datetime & | birth
| ) |  |

set dates of a given file, may throw exception

Parameters

  [in] | chemin | the path to the file to set
  [in] | symlink | true if the file is a symlink
  [in] | access | last access date to use
  [in] | modif | last modification date to use
  [in] | birth | time of creation of the file

Note
  if birth time is not known, it should be set to the value of modif for efficiency

void libdar::tools_memxor | ( | void * | dest,
|  | const void * | src,
|  | U_I | n
| ) |  |

Produces in "dest" the XORed value of "dest" and "src".

Parameters

  [in,out] | dest | is the area where to write down the result
  [in] | src | points to vector or array of values to convert
  [in] | n | is the number of byte to convert from src to dest

Note
  dest must be a valid pointer to an allocated memory area of at least n bytes

bool libdar::tools_my_atoi | ( | const char * | a,
|  | U_I & | val
| ) |  |

ascii to integer conversion

Parameters

  [in] | a | is the ascii string to convert
  [out] | val | is the resulting value

Returns
  true if the conversion could be done false if the given string does not correspond to the decimal representation of an unsigned integer

Note
  this call is now a warapper around tools_str2int

std::string libdar::tools_name_of_gid | ( | const infinint & | gid | ) |

convert gid to name in regards of the current system's configuration

Parameters

  [in] | gid | the Group ID number

Returns
  the name of the corresponding group or the gid if none corresponds

std::string libdar::tools_name_of_uid | ( | const infinint & | uid | ) |

convert uid to name in regards to the current system's configuration

Parameters

  [in] | uid | the User ID number

Returns
  the name of the corresponding user or the uid if none corresponds

void libdar::tools_noexcept_make_date | ( | const std::string & | chem,
|  | bool | symlink,
|  | const datetime & | last_acc,
|  | const datetime & | last_mod,
|  | const datetime & | birth
| ) |  |

set dates of a given file, no exception thrown

Parameters

  [in] | chem | the path to the file to set
  [in] | symlink | true if the file is a symlink
  [in] | last_acc | last access date to use
  [in] | last_mod | last modification date to use
  [in] | birth | creation date of the file, if not known, use the value of last_mod for efficiency

template<class N , class B >

std::vector<B> libdar::tools_number_base_decomposition_in_big_endian | ( | N | number,
|  | const B & | base
| ) |  |

Template for the decomposition of any number in any base (decimal, octal, hexa, etc.)

Parameters

  [in] | number | is the number to decompose
  [in] | base | is the base to decompose the number into

Returns
  a vector of 'digit' int the specified base, the first beeing the less significative

Note
  this template does not take care of the possibily existing optimized euclide division to speed up the operation like what exists for infinint. A specific overriden fonction for this type would be better.
  , the name "big_endian" is erroneous, it gives a little endian vector

Definition at line 783 of file tools.hpp.

U_I libdar::tools_octal2int | ( | const std::string & | perm | ) |

convert octal string to integer

Parameters

  perm | is a string representing a number in octal (string must have a leading zero)

Returns
  the corresponding value as an integer

void libdar::tools_open_pipes | ( | user_interaction & | dialog,
|  | const std::string & | input,
|  | const std::string & | output,
|  | tuyau *& | in,
|  | tuyau *& | out,
|  | memory_pool * | pool = `nullptr`
| ) |  |

open a pair of tuyau objects encapsulating two named pipes.

Parameters

  [in,out] | dialog | for user interaction
  [in] | input | path to the input named pipe
  [in] | output | path to the output named pipe
  [out] | in | resulting tuyau object for input
  [out] | out | resulting tuyau object for output
  [in] | pool | memory pool to use for allocation or nullptr for default memory allocation

Note
  in and out parameters must be released by the caller thanks to the "delete" operator

std::string libdar::tools_output2xml | ( | const std::string & | src | ) |

convert string for xml output

Note
  any < > & quote and double quote are replaced by adequate sequence for unicode
  second point, nothing is done here to replace system native strings to unicode

uid_t libdar::tools_ownership2gid | ( | const std::string & | group | ) |

convert string group name or gid to numeric gid value

Parameters

  [in] | group | string username

Returns
  uid value

uid_t libdar::tools_ownership2uid | ( | const std::string & | user | ) |

change ownership of the file which descriptor is given

convert string user name or uid to numeric uid value

Parameters

  [in] | user | string username

Returns
  uid value

std::string libdar::tools_printf | ( | const char * | format,
|  |  | ...
| ) |  |

make printf-like formating to a std::string

Parameters

  [in] | format | the format string
  [in] | ... | list of argument to use against the format string

Returns
  the resulting string

Note
  the supported masks for the format are:
  - %s %c %d %% (usual behavior)
  - %x display an integer under hexadecimal notation
  - %i (matches infinint *)
  - %S (matches std::string *)

U_I libdar::tools_pseudo_random | ( | U_I | max | ) |

Produces a pseudo random number x, where 0 <= x < max.

Parameters

  [in] | max | defines the range of the random number to return

Returns
  the returned value ranges from 0 (zero) up to max (= including max)

void libdar::tools_read_from_pipe | ( | 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

void libdar::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.

void libdar::tools_read_string | ( | generic_file & | f,
|  | std::string & | s
| ) |  |

read a string from a file expecting it to terminate by '\0'

Parameters

  f | the file to read from
  s | the string to put the data to (except the ending '\0')

void libdar::tools_read_string_size | ( | generic_file & | f,
|  | std::string & | s,
|  | infinint | taille
| ) |  |

read a string if given size from a file '\0' has no special meaning

Parameters

  [in] | f | is the file to read from
  [in] | s | is the string to put read data in
  [in] | taille | is the size in byte to read

void libdar::tools_read_vector | ( | generic_file & | f,
|  | std::vector< std::string > & | x
| ) |  |

read a list of string from a file

Parameters

  [in] | f | the file to read from
  [out] | x | the list to fill from file

std::string libdar::tools_readlink | ( | const char * | root | ) |

returns the file pointed to by a symbolic link (or transparent if the file is not a symlink).

Parameters

  root | the path to the file to read

Returns
  the file pointed to by the symlink or the value given in argument if it is not a symlink

Note
  an exception can occur if lack of memory or invalid argument given (nullptr or empty string), system call error...

path libdar::tools_relative2absolute_path | ( | const path & | src,
|  | const path & | cwd
| ) |  |

transform a relative path to an absolute one given the current directory value

Parameters

  [in] | src | the relative path to transform
  [in] | cwd | the value to take for the current directory

Returns
  the corresponding absolute path

void libdar::tools_release_struct_dirent | ( | struct dirent * | ptr | ) |

release a dirent structure as allocated by tools_allocate_struct_dirent

Parameters

  [in] | ptr | is the address of the structure to release

void libdar::tools_remove_last_char_if_equal_to | ( | char | c,
|  | std::string & | s
| ) |  |

remove last character of a string is it equal to a given value

Parameters

  [in] | c | the given value to compare the last char with
  [in,out] | s | the string to modify

void libdar::tools_set_back_blocked_signals | ( | sigset_t | old_mask | ) |

unblock signals according to given mask

Parameters

  [in] | old_mask | value to set to blocked signal mask

Exceptions

  Erange | is thrown if system call failed for some reason

void libdar::tools_set_ownership | ( | S_I | filedesc,
|  | const std::string & | slice_user,
|  | const std::string & | slice_group
| ) |  |

change ownership of the file which descriptor is given

Parameters

  [in] | filedesc | file's descriptor
  [in] | slice_user | the user to set the file to. For empty string, no attempts to change the user ownership is done
  [in] | slice_group | the group to set the file to. For empty string, no attempts to change the group ownership is done

Note
  this call may throw Erange exception upon system error

void libdar::tools_set_permission | ( | S_I | fd,
|  | U_I | perm
| ) |  |

change the permission of the file which descriptor is given

Parameters

  [in] | fd | file's descriptor
  [in] | perm | file permission to set the file to

std::vector<std::string> libdar::tools_split_in_words | ( | generic_file & | f | ) |

read a file and split its contents into words

Parameters

  [in,out] | f | is the file to read

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

Note
  The different quotes are taken into account

std::vector<std::string> libdar::tools_split_in_words | ( | const std::string & | arg | ) |

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

Parameters

  [in,out] | arg | is the string to read

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

Note
  The different quotes are taken into account

void libdar::tools_split_path_basename | ( | const char * | all,
|  | path *& | chemin,
|  | std::string & | base,
|  | memory_pool * | pool = `nullptr`
| ) |  |

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
  [in] | pool | memory pool to use for allocation or nullptr for default memory allocation

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

void libdar::tools_split_path_basename | ( | const std::string & | all,
|  | std::string & | chemin,
|  | std::string & | base,
|  | memory_pool * | pool = `nullptr`
| ) |  |

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
  [in] | pool | memory pool to use for allocation or nullptr for default memory allocation

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

char* libdar::tools_str2charptr | ( | const std::string & | x | ) |

convert a string to a char *

Parameters

  [in] | x | is the string to convert

Returns
  the address of newly allocated memory containing the equivalent string as the argument

Exceptions

  Ememory | is thrown if the memory allocation failed, this call never return nullptr

Note
  Do not use this function, use std::string::c_str(). The allocated memory must be released by the caller thanks to the "delete []" operator

U_I libdar::tools_str2int | ( | const std::string & | x | ) |

convert an 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

S_I libdar::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

tlv_list libdar::tools_string2tlv_list | ( | user_interaction & | dialog,
|  | const U_16 & | type,
|  | const std::vector< std::string > & | data
| ) |  |

Produces a list of TLV from a constant type and a list of string.

Parameters

  [in,out] | dialog | for user interaction
  [in] | type | is the type each TLV will have
  [in] | data | is the list of string to convert into a list of TLV

Returns
  a tlv_list object. Each TLV in the list correspond to a string in the given list

std::string libdar::tools_string_to_hexa | ( | const std::string & | input | ) |

convert a string into its hexadecima representation

Parameters

  [in] | input | input string to convert

Returns
  a string containing an hexadecimal number corresponding to the bytes of the input string

std::string libdar::tools_substitute | ( | const std::string & | hook,
|  | const std::map< char, std::string > & | corres
| ) |  |

produce the string resulting from the substition of % macro defined in the map

Parameters

  [in] | hook | is the user's expression in which to proceed to substitution
  [in] | corres | is a map telling which char following a % sign to replace by which string

Returns
  the resulting string of the substitution

void libdar::tools_system | ( | user_interaction & | dialog,
|  | const std::vector< std::string > & | argvector
| ) |  |

wrapper to the "system" system call.

Parameters

  [in,out] | dialog | for user interaction
  [in] | argvector | the equivalent to the argv[] vector

void libdar::tools_system_with_pipe | ( | user_interaction & | dialog,
|  | const std::string & | dar_cmd,
|  | const std::vector< std::string > & | argvpipe,
|  | memory_pool * | pool = `nullptr`
| ) |  |

wrapper to the "system" system call using anonymous pipe to tranmit arguments to the child process

Parameters

  [in,out] | dialog | for user interaction
  [in] | dar_cmd | the path to the executable to run
  [in] | argvpipe | the list of arguments to pass through anonymous pipe
  [in] | pool | memory pool to use or nullptr for default memory allocation

Note
  the command to execute must understand the –pipe-fd option that gives the filedescriptor to read from the command-line options

void libdar::tools_to_upper | ( | const std::string & | r,
|  | std::string & | uppered
| ) |  |

convert a string to upper case

Parameters

  [in] | r | the string to convert
  [out] | uppered | resulting upper cased string

Note
  in case of invalid wide char met in source string, the upper case convertion is done in ASCII mode (byte by byte)

void libdar::tools_unlink_file_mask_regex | ( | user_interaction & | dialog,
|  | const std::string & | c_chemin,
|  | const std::string & | file_mask,
|  | bool | info_details
| ) |  |

remove files from a given directory

Parameters

  [in,out] | dialog | for user interaction
  [in] | c_chemin | directory where files have to be removed
  [in] | file_mask | regex expression which designates the files to remove
  [in] | info_details | whether user must be displayed details of the operation

Note
  This is equivalent to the 'rm' command with regex expression in place of glob one

std::string libdar::tools_unsigned_char_to_hexa | ( | unsigned char | x | ) |

convert a unsigned char into its hexa decima representation

Parameters

  [in] | x | is the byte to convert

Returns
  the string representing the value of x written in hexadecimal

std::string libdar::tools_uword2str | ( | U_16 | x | ) |

convert unsigned word to string

Parameters

  [in] | x | the unsigned word to convert

Returns
  the decimal representation of the given integer

std::string libdar::tools_vprintf | ( | const char * | format,
|  | va_list | ap
| ) |  |

make printf-like formating to a std::string

Parameters

  [in] | format | the format string
  [in] | ap | list of argument to use against the format string

Returns
  the resulting string

Note
  the supported masks for the format are:
  - %s %c %d %% (normal behavior)
  - %i (matches infinint *)
  - %S (matches std::string *)

void libdar::tools_write_string | ( | generic_file & | f,
|  | const std::string & | s
| ) |  |

write a string to a file with a '\0' at then end

Parameters

  [in] | f | the file to write to
  [in] | s | the string to write to file

void libdar::tools_write_string_all | ( | generic_file & | f,
|  | const std::string & | s
| ) |  |

write a string to a file, '\0' has no special meaning nor is added at the end

Parameters

  [in] | f | the file to write to
  [in] | s | the string to write to file

void libdar::tools_write_vector | ( | generic_file & | f,
|  | const std::vector< std::string > & | x
| ) |  |

write a list of string to file

Parameters

  [in] | f | the file to write to
  [in] | x | the list of string to write