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
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 *
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.
void	libdar::tools_extract_basename (const char *command_name, std::string &basename)
	extracts the basename of a file (removing path part)
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
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
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 (const infinint &uid)
	convert uid to name in regards to the current system's configuration
std::string	libdar::tools_name_of_gid (const infinint &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_I	libdar::tools_str2int (const std::string &x)
	convert an integer written in decimal notation to the corresponding value
S_I	libdar::tools_str2signed_int (const std::string &x)
	convert a signed integer written in decimal notation to the corresponding value
bool	libdar::tools_my_atoi (const char *a, U_I &val)
	ascii to integer conversion
std::string	libdar::tools_addspacebefore (std::string s, U_I 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_system_with_pipe (user_interaction &dialog, const std::string &dar_cmd, const std::vector< std::string > &argvpipe)
	wrapper to the "system" system call using anonymous pipe to tranmit arguments to the child process
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 liblzo2, bool libcrypto, bool furtive_read)
	display the compilation time features of libdar
void	libdar::tools_display_features (user_interaction &dialog)
	display the compilation time features of libdar
bool	libdar::tools_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
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
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 *const 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, S_I &min, U_I &max)
	from a string with a range notation (min-max) extract the range values
std::string	libdar::tools_printf (const char *format,...)
	make printf-like formating to a std::string
std::string	libdar::tools_vprintf (const char *format, va_list ap)
	make printf-like formating to a std::string
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)
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
void	libdar::tools_avoid_slice_overwriting_regex (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
infinint	libdar::tools_get_size (const std::string &s)
	returns the size of the given plain file
infinint	libdar::tools_get_ctime (const std::string &s)
	returns the last change 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
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
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
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
void	libdar::tools_hook_execute (user_interaction &ui, const std::string &cmd_line)
	execute and retries at user will a given command line
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
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
std::string	libdar::tools_output2xml (const std::string &src)
	convert string for xml output
U_I	libdar::tools_octal2int (const std::string &perm)
	convert octal string to integer
std::string	libdar::tools_int2octal (const U_I &perm)
	convert a number to a string corresponding to its octal representation
void	libdar::tools_set_permission (S_I fd, U_I perm)
	change the permission of the file which descriptor is given
void	libdar::tools_set_ownership (S_I fd, const std::string &slice_user, const std::string &slice_group)
	change ownership of the file which descriptor is given
void	libdar::tools_memxor (void *dest, const void *src, U_I n)
	Produces in "dest" the XORed value of "dest" and "src".
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.
void	libdar::tools_read_from_pipe (user_interaction &dialog, S_I fd, tlv_list &result)
	Extract from anonymous pipe a tlv_list.
U_I	libdar::tools_pseudo_random (U_I max)
	Produces a pseudo random number x, where 0 <= x < max.
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.).
std::string	libdar::tools_unsigned_char_to_hexa (unsigned char x)
	convert a unsigned char into its hexa decima representation
std::string	libdar::tools_string_to_hexa (const std::string &input)
	convert a string into its hexadecima representation
infinint	libdar::tools_file_size_to_crc_size (const infinint &size)
	Defines the CRC size to use for a given filesize.
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)

---

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
	)

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

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 &	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 (regex)
[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
	)

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	liblzo2,
		bool	libcrypto,
		bool	furtive_read
	)

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]	liblzo2	whether lzo compression is available
[in]	libcrypto	whether strong encryption is available
[in]	furtive_read	whether furtive read access is available

Note:

this routine is deprecated, as it needs a change in its interface upon each new feature addition, use the other tools_display_features() routing, with a single argument (see below).

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

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.

infinint 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:

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

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

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

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

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

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

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

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

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 %% (normal behavior)
• %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) to max - 1. max is never retured, max - 1 can be returned.

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

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

change ownership of the file which descriptor is given

Parameters:

[in]	fd	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 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, 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.

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

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 NULL

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
	)

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

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

(

char *

nts

)

convert a string to upper case

Parameters:

[in,out]

nts

a NULL terminated string to convert

void libdar::tools_to_upper

(

std::string &

r

)

convert a string to upper case

Parameters:

[in,out]

r

to convert

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