Tools

a set of tool routine More...

Files
file	deci.hpp
	manages the decimal representation of infinint
Classes
class	libdar::deci
	decimal class, convert infinint from and to decimal represention More...
Functions
std::ostream &	libdar::operator<< (std::ostream &ref, const infinint &arg)
	specific << operator to use infinint in std::ostream
char *	libdar::tools_str2charptr (std::string x)
	convert a string to a char *
void	libdar::tools_write_string (generic_file &f, const std::string &s)
	write a string to a file with a '\0' at then end
void	libdar::tools_read_string (generic_file &f, std::string &s)
	read a string from a file expecting it to terminate by '\0'
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
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
infinint	libdar::tools_get_filesize (const path &p)
	retrieve the size in byte of a 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.
char *	libdar::tools_extract_basename (const char *command_name)
	extracts the basename of a file (removing path part)
void	libdar::tools_split_path_basename (const char *all, path *&chemin, std::string &base)
	split a given full path in path part and basename part
void	libdar::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
void	libdar::tools_open_pipes (user_interaction &dialog, const std::string &input, const std::string &output, tuyau *&in, tuyau *&out)
	open a pair of tuyau objects encapsulating two named pipes.
void	libdar::tools_blocking_read (int fd, bool mode)
	set blocking/not blocking mode for reading on a file descriptor
std::string	libdar::tools_name_of_uid (U_16 uid)
	convert uid to name in regards to the current system's configuration
std::string	libdar::tools_name_of_gid (U_16 gid)
	convert gid to name in regards of the current system's configuration
std::string	libdar::tools_uword2str (U_16 x)
	convert unsigned word to string
std::string	libdar::tools_int2str (S_I x)
	convert integer to string
U_32	libdar::tools_str2int (const std::string &x)
	convert an integer written in decimal notation to the corresponding value
std::string	libdar::tools_addspacebefore (std::string s, unsigned int expected_size)
	prepend spaces before the given string
std::string	libdar::tools_display_date (infinint date)
	convert a date in second to its human readable representation
infinint	libdar::tools_convert_date (const std::string &repres)
	convert a human readable date representation in number of second since the system reference date
void	libdar::tools_system (user_interaction &dialog, const std::vector< std::string > &argvector)
	wrapper to the "system" system call.
void	libdar::tools_write_vector (generic_file &f, const std::vector< std::string > &x)
	write a list of string to file
void	libdar::tools_read_vector (generic_file &f, std::vector< std::string > &x)
	read a list of string from a file
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
std::vector< std::string >	libdar::operator+ (std::vector< std::string > a, std::vector< std::string > b)
	concatenate two vectors
bool	libdar::tools_is_member (const std::string &val, const std::vector< std::string > &liste)
	test the presence of a value in a list
void	libdar::tools_display_features (user_interaction &dialog, bool ea, bool largefile, bool nodump, bool special_alloc, U_I bits, bool thread_safe, bool libz, bool libbz2, bool libcrypto)
	display the compilation time features of libdar
bool	libdar::is_equal_with_hourshift (const infinint &hourshift, const infinint &date1, const infinint &date2)
	test if two dates are equal taking care of a integer hour of difference
bool	libdar::tools_my_atoi (char *a, U_I &val)
	ascii to integer conversion
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, char *clef)
	isolate the value of a given variable from the environment vector
void	libdar::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
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).
bool	libdar::tools_look_for (const char *argument, S_I argc, char *argv[])
	test the presence of an argument
void	libdar::tools_noexcept_make_date (const std::string &chem, const infinint &last_acc, const infinint &last_mod)
	set dates of a given file, no exception thrown
void	libdar::tools_make_date (const std::string &chemin, infinint access, infinint modif)
	set dates of a given file, may throw exception
bool	libdar::tools_is_case_insensitive_equal (const std::string &a, const std::string &b)
	compare two string in case insensitive manner
void	libdar::tools_to_upper (char *nts)
	convert a string to upper case
void	libdar::tools_to_upper (std::string &r)
	convert a string to upper case
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
void	libdar::tools_read_range (const std::string &s, U_I &min, U_I &max)
	from a string with a range notation (min-max) extract the range values
std::string	libdar::tools_printf (char *format,...)
	make printf-like formating to a std::string
std::string	libdar::tools_vprintf (char *format, va_list ap)
	make printf-like formating to a std::string
bool	libdar::tools_do_some_files_match_mask (user_interaction &ui, const char *c_chemin, const char *file_mask)
	test the presence of files corresponding to a given mask in a directory
void	libdar::tools_unlink_file_mask (user_interaction &dialog, const char *c_chemin, const char *file_mask, bool info_details)
	remove files from a given directory
void	libdar::tools_avoid_slice_overwriting (user_interaction &dialog, const path &chemin, const std::string &x_file_mask, 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
void	libdar::tools_add_elastic_buffer (generic_file &f, U_32 max_size)
	append an elastic buffer of given size to the file
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
path	libdar::tools_relative2absolute_path (const path &src, const path &cwd)
	transform a relative path to an absolute one given the current directory value
void	libdar::tools_block_all_signals (sigset_t &old_mask)
	block all signals (based on POSIX sigprocmask)
void	libdar::tools_set_back_blocked_signals (sigset_t old_mask)
	unblock signals according to given mask
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
infinint	libdar::tools_get_mtime (const std::string &s)
	returns the last modification date of the given file
std::vector< std::string >	libdar::tools_split_in_words (generic_file &f)
	read a file and split its contents in words

---

Detailed Description

a set of tool routine

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

---

Function Documentation

bool libdar::is_equal_with_hourshift (  const infinint &  hourshift, const infinint &  date1, const infinint &  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

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 )

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

std::string libdar::tools_addspacebefore (  std::string  s, unsigned int  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

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 (  user_interaction &  dialog, const path &  chemin, const std::string &  x_file_mask, 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]  x_file_mask  mask corresponding to slices that will be generated [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

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

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 (  infinint  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, bool  ea, bool  largefile, bool  nodump, bool  special_alloc, U_I  bits, bool  thread_safe, bool  libz, bool  libbz2, bool  libcrypto )

display the compilation time features of libdar Parameters: [in,out]  dialog  for user interaction [in]  ea  whether Extended Attribute support is available [in]  largefile  whether large file support is available [in]  nodump  whether nodump flag support is available [in]  special_alloc  whether special allocation is activated [in]  bits  infinint version used [in]  thread_safe  whether thread safe support is available [in]  libz  whether libz compression is available [in]  libbz2  whether libbz2 compression is available [in]  libcrypto  whether strong encryption is available

bool libdar::tools_do_some_files_match_mask (  user_interaction &  ui, const char *  c_chemin, const char *  file_mask )

test the presence of files corresponding to a given mask in a directory Parameters: [in,out]  ui  for user interaction [in]  c_chemin  directory where file have to looked for [in]  file_mask  glob expression which designates the files to look for Returns: true if some files have found matching the file_mask

char* libdar::tools_extract_basename (  const char *  command_name  )

extracts the basename of a file (removing path part) Parameters: [in]  command_name  is the full path of the file Returns: the basename of the file Exceptions: Ememory  can be thrown if memory allocation failed Note: the returned value has to be release thanks to the "delete []" operator by the caller of this function

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, 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: NULL 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).

infinint 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

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_member (  const std::string &  val, const std::vector< std::string > &  liste )

test the presence of a value in a list Parameters: [in]  val  is the value to look for [in]  liste  is the list to look in Returns: true if val has been found as a member of the list

bool libdar::tools_look_for (  const char *  argument, S_I  argc, char *  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

void libdar::tools_make_date (  const std::string &  chemin, infinint  access, infinint  modif )

set dates of a given file, may throw exception Parameters: [in]  chemin  the path to the file to set [in]  access  last access date to use [in]  modif  last modification date to use

bool libdar::tools_my_atoi (  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

std::string libdar::tools_name_of_gid (  U_16  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 (  U_16  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, const infinint &  last_acc, const infinint &  last_mod )

set dates of a given file, no exception thrown Parameters: [in]  chem  the path to the file to set [in]  last_acc  last access date to use [in]  last_mod  last modification date to use

void libdar::tools_open_pipes (  user_interaction &  dialog, const std::string &  input, const std::string &  output, tuyau *&  in, tuyau *&  out )

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 Note: in and out parameters must be released by the caller thanks to the "delete" operator

std::string libdar::tools_printf (  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 %% (normal behavior) %i (matches infinint *) %S (matches std::string *)

void libdar::tools_read_range (  const std::string &  s, U_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

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 (NULL 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_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

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

read a file and split its contents in 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

void libdar::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 [out]  base  is the resulting basename Note: chemin argument must be release by the call thanks to the "delete" operator.

void libdar::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 [out]  base  is the resulting basename Note: chemin argument must be release by the call thanks to the "delete" operator.

char* libdar::tools_str2charptr (  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 NULL Note: that the allocated memory must be released by the caller thanks to the "delete []" operator

U_32 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

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_to_upper (  std::string &  r  )

convert a string to upper case Parameters: [in,out]  r  to convert

void libdar::tools_to_upper (  char *  nts  )

convert a string to upper case Parameters: [in,out]  nts  a NULL terminated string to convert

void libdar::tools_unlink_file_mask (  user_interaction &  dialog, const char *  c_chemin, const char *  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  glob 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 shell expansion

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

---