Sar class stands for Segmentation And Reassembly class. More...

#include <sar.hpp>

Inheritance diagram for libdar::sar:

Collaboration diagram for libdar::sar:

Public Member Functions
	sar (const std::shared_ptr< user_interaction > &dialog, const std::string &base_name, const std::string &extension, const std::shared_ptr< entrepot > &where, bool by_the_end, const infinint &x_min_digits, bool sequential_read, bool lax=false, const std::string &execute="")
	this constructor reads data from a set of slices More...

	sar (const std::shared_ptr< user_interaction > &dialog, gf_mode open_mode, const std::string &base_name, const std::string &extension, const infinint &file_size, const infinint &first_file_size, bool x_warn_overwrite, bool x_allow_overwrite, const infinint &pause, const std::shared_ptr< entrepot > &where, const label &internal_name, const label &data_name, bool force_permission, U_I permission, hash_algo x_hash, const infinint &x_min_digits, bool format_07_compatible, const std::string &execute="")
	this constructor creates a new set of slices More...

	sar (const sar &ref)=delete
	the copy constructor

	sar (sar &&ref) noexcept=delete
	move constructor

sar &	operator= (const sar &ref)=delete
	assignment operator

sar &	operator= (sar &&ref) noexcept=delete
	move operator

	~sar ()
	destructor

virtual bool	skippable (skippability direction, const infinint &amount) override
	whether the implementation is able to skip More...

virtual bool	skip (const infinint &pos) override
	skip at the absolute position More...

virtual bool	skip_to_eof () override
	skip to the end of file

virtual bool	skip_relative (S_I x) override
	skip relatively to the current position

virtual bool	truncatable (const infinint &pos) const override
	whether the implementation is able to truncate to the given position

virtual infinint	get_position () const override
	get the current read/write position

const slice_layout &	get_slicing () const

bool	get_total_file_number (infinint &num) const

bool	get_last_file_size (infinint &num) const

void	disable_natural_destruction ()

void	enable_natural_destruction ()

virtual bool	is_an_old_start_end_archive () const override
	returns whether the archive is a old archive (format < 8)

const label &	get_internal_name_used () const

virtual const label &	get_data_name () const override
	obtain the data_name of the archive (label associated with the archive's data) More...

const std::shared_ptr< entrepot > &	get_entrepot () const

const infinint &	get_first_slice_header_size () const
	get the first slice header

const infinint &	get_non_first_slice_header_size () const
	get the non first slice header

Public Member Functions inherited from libdar::generic_file
	generic_file (gf_mode m)
	main constructor

	generic_file (const generic_file &ref)
	copy constructor

	generic_file (generic_file &&ref) noexcept
	move constructor

generic_file &	operator= (const generic_file &ref)
	assignment operator

generic_file &	operator= (generic_file &&ref) noexcept
	move operator

	~generic_file () noexcept(false)
	virtual destructor, More...

void	terminate ()
	destructor-like call, except that it is allowed to throw exceptions

bool	operator== (generic_file &ref)

bool	operator!= (generic_file &ref)

gf_mode	get_mode () const
	retreive the openning mode for this object

void	read_ahead (const infinint &amount)

void	ignore_read_ahead (bool mode)

virtual U_I	read (char *a, U_I size) override
	read data from the generic_file inherited from proto_generic_file

virtual void	write (const char *a, U_I size) override
	write data to the generic_file inherited from proto_generic_file

void	write (const std::string &arg)
	write a string to the generic_file More...

S_I	read_back (char &a)
	skip back one char, read on char and skip back one char

S_I	read_forward (char &a)
	read one char

virtual void	truncate (const infinint &pos)
	truncate file at the given offset More...

virtual void	copy_to (generic_file &ref)
	copy all data from current position to the object in argument

virtual void	copy_to (generic_file &ref, const infinint &crc_size, crc *&value)
	copy all data from the current position to the object in argument and computes a CRC value of the transmitted data More...

U_32	copy_to (generic_file &ref, U_32 size)
	small copy (up to 4GB) with CRC calculation

infinint	copy_to (generic_file &ref, infinint size)
	copy the given amount to the object in argument

bool	diff (generic_file &f, const infinint &me_read_ahead, const infinint &you_read_ahead, const infinint &crc_size, crc *&value)
	compares the contents with the object in argument More...

bool	diff (generic_file &f, const infinint &me_read_ahead, const infinint &you_read_ahead, const infinint &crc_size, crc *&value, infinint &err_offset)

void	reset_crc (const infinint &width)
	reset CRC on read or writen data More...

bool	crc_status () const
	to known whether CRC calculation is activated or not

crc *	get_crc ()
	get CRC of the transfered date since last reset More...

void	sync_write ()
	write any pending data

void	flush_read ()
	be ready to read at current position, reseting all pending data for reading, cached and in compression engine for example

Public Member Functions inherited from libdar::proto_generic_file
	proto_generic_file (const proto_generic_file &ref)=default
	copy constructor

	proto_generic_file (proto_generic_file &&ref) noexcept=default
	move constructor

proto_generic_file &	operator= (const proto_generic_file &ref)=default
	assignment operator

proto_generic_file &	operator= (proto_generic_file &&ref) noexcept=default
	move operator

virtual	~proto_generic_file () noexcept(false)
	virtual destructor More...

Public Member Functions inherited from libdar::contextual
	contextual (const contextual &ref)=default

	contextual (contextual &&ref) noexcept=default

contextual &	operator= (const contextual &ref)=default

contextual &	operator= (contextual &&ref) noexcept=default

virtual void	set_info_status (const std::string &s)
	defines the new contextual value More...

virtual std::string	get_info_status () const
	get the current contextual value

Protected Member Functions
virtual void	inherited_read_ahead (const infinint &amount) override
	tells the object that several calls to read() will follow to probably obtain at least the given amount of data More...

virtual U_I	inherited_read (char *a, U_I size) override
	implementation of read() operation More...

virtual void	inherited_write (const char *a, U_I size) override
	implementation of the write() operation More...

virtual void	inherited_truncate (const infinint &pos) override
	truncate file at the give offset More...

virtual void	inherited_sync_write () override
	write down any pending data More...

virtual void	inherited_flush_read () override
	reset internal engine, flush caches in order to read the data at current position More...

virtual void	inherited_terminate () override
	destructor-like call, except that it is allowed to throw exceptions More...

Protected Member Functions inherited from libdar::generic_file
void	set_mode (gf_mode x)

bool	is_terminated () const

Protected Member Functions inherited from libdar::mem_ui
user_interaction &	get_ui () const
	get access to the user_interaction object More...

std::shared_ptr< user_interaction >	get_pointer () const
	get access to the shared_ptr pointing to the user_interaction

	mem_ui (const std::shared_ptr< user_interaction > &dialog)
	constructor More...

	mem_ui (const mem_ui &ref)=default
	the copy constructor More...

	mem_ui (mem_ui &&ref) noexcept=default
	the move constructor

mem_ui &	operator= (const mem_ui &ref)=default
	assignement operator More...

mem_ui &	operator= (mem_ui &&ref) noexcept=default
	move operator

virtual	~mem_ui () noexcept(false)
	destructor More...

Private Member Functions
bool	skip_forward (U_I x)
	skip forward in sar global contents

bool	skip_backward (U_I x)
	skip backward in sar global contents

void	close_file (bool terminal)
	close current openned file, adding (in write mode only) a terminal mark (last slice) or not

void	open_readonly (const std::string &fic, const infinint &num, bool bytheend)

void	open_writeonly (const std::string &fic, const infinint &num, bool bytheend)

void	open_file_init ()
	initialize some of_* fields

void	open_file (infinint num, bool bytheend)
	close current slice and open the slice 'num'

void	set_offset (infinint offset)
	skip to current slice relative offset

void	open_last_file (bool bytheend)
	open the last slice, ask the user, test, until last slice available

bool	is_current_eof_a_normal_end_of_slice () const
	return true if current reading position is at end of slice

infinint	bytes_still_to_read_in_slice () const
	returns the number of bytes expected before the end of slice

header	make_write_header (const infinint &num, char flag)

void	hook_execute (const infinint &num)

Private Attributes
std::shared_ptr< entrepot >	entr
	where are stored slices

std::string	base
	archive base name

std::string	ext
	archive extension

std::string	hook
	command line to execute between slices

slice_layout	slicing
	slice layout

infinint	file_offset
	current reading/writing position in the current slice (relative to the whole slice file, including headers)

hash_algo	hash
	whether to build a hashing when creating slices, and if so, which algorithm to use

infinint	min_digits
	minimum number of digits the slices number is stored with in the filename

bool	natural_destruction
	whether to execute commands between slices on object destruction

infinint	of_current
	number of the open slice

infinint	size_of_current
	size of the current slice (used in reading mode only)

infinint	of_max_seen
	highest slice number seen so far

bool	of_last_file_known
	whether the T terminal slice has been met

infinint	of_last_file_num
	number of the last slice (if met)

infinint	of_last_file_size
	size of the last slice (if met)

label	of_internal_name
	internal name shared in all slice header

label	of_data_name
	internal name linked to data (transparent to dar_xform and used by isolated catalogue as reference)

bool	force_perm
	true if any future slice has its permission to be set explicitely

U_I	perm
	if force_perm is true, value to use for slice permission

fichier_global *	of_fd
	file object currently openned

char	of_flag
	flags of the open file

bool	initial
	do not launch hook command-line during sar initialization

bool	opt_warn_overwrite
	a warning must be issued before overwriting a slice

bool	opt_allow_overwrite
	is slice overwriting allowed

infinint	pause
	do we pause between slices

bool	lax
	whether to try to go further reading problems

infinint	to_read_ahead
	amount of data to read ahead for next slices

bool	seq_read
	whether sequential read has been requested

Additional Inherited Members
Public Types inherited from libdar::generic_file
enum	skippability { skip_backward , skip_forward }

Detailed Description

Sar class stands for Segmentation And Reassembly class.

sar is used as a normal file but given some parameters at construction time the object will split the data in several files of given size (aka slices) sar uses a header to identify slices in a given set and tie slices of different sets At reading time sar transparently read data from the different slices.

Definition at line 54 of file sar.hpp.

Constructor & Destructor Documentation

◆ sar() [1/2]

libdar::sar::sar	(	const std::shared_ptr< user_interaction > &	dialog,
		const std::string &	base_name,
		const std::string &	extension,
		const std::shared_ptr< entrepot > &	where,
		bool	by_the_end,
		const infinint &	x_min_digits,
		bool	sequential_read,
		bool	lax = `false`,
		const std::string &	execute = `""`
	)

this constructor reads data from a set of slices

Parameters

[in]	dialog	is for user interation (such a requesting a slice and pausing between slices)
[in]	base_name	is the basename of all slices of the set (it will be added the ".<slice numer>.extension" to form a filename
[in]	extension	is the extension of slice's filenames
[in]	where	defines where to store or where are stored slices
[in]	by_the_end	if true dar will try to open the slice set starting from the last slice else it will try starting from the first
[in]	x_min_digits	is the minimum number of digits the slices number is stored with in the filename
[in]	sequential_read	to be set to true for sequential reading
[in]	lax	if set to true will try workaround problems that would otherwise lead the operation to fail
[in]	execute	is the command to execute before trying to open each slice for reading

Note: if by_the_end is set to true, the last slice must have extended slice header that contain informations about the first slice size (used starting archive format "08"), Else, the slice size is not possible to open as the offset of the data cannot be determined. If slice header is too old the sar class will fallback openning the first slice and directly get the first slice.

◆ sar() [2/2]

libdar::sar::sar	(	const std::shared_ptr< user_interaction > &	dialog,
		gf_mode	open_mode,
		const std::string &	base_name,
		const std::string &	extension,
		const infinint &	file_size,
		const infinint &	first_file_size,
		bool	x_warn_overwrite,
		bool	x_allow_overwrite,
		const infinint &	pause,
		const std::shared_ptr< entrepot > &	where,
		const label &	internal_name,
		const label &	data_name,
		bool	force_permission,
		U_I	permission,
		hash_algo	x_hash,
		const infinint &	x_min_digits,
		bool	format_07_compatible,
		const std::string &	execute = `""`
	)

this constructor creates a new set of slices

Parameters

[in,out]	dialog	is used for user interaction
[in]	open_mode	read_write or write_only is accepted only
[in]	base_name	is the slice set base name
[in]	extension	is the slices extension
[in]	file_size	is the size of slices (in byte)
[in]	first_file_size	is the size of the first slice (in byte) or set it to zero if it has to be equal to other slice's size
[in]	x_warn_overwrite	if set to true, a warning will be issued before overwriting a slice
[in]	x_allow_overwrite	if set to false, no slice overwritting will be allowed
[in]	pause	if set to zero no pause will be done between slice creation. If set to 1 a pause between each slice will be done. If set to N a pause each N slice will be done. Pauses must be acknoledged by user for the process to continue
[in]	where	defines where to store the slices
[in]	internal_name	is a tag common to all slice of the archive
[in]	data_name	is a tag that has to be associated with the data.
[in]	force_permission	if true slice permission will be forced to the value given in the next argument
[in]	permission	value to use to set permission of slices
[in]	x_hash	defines whether a hash file has to be generated for each slice, and wich hash algorithm to use
[in]	x_min_digits	is the minimum number of digits the slices number is stored with in the filename
[in]	format_07_compatible	when set to true, creates a slice header in the archive format of version 7 instead of the highest version known
[in]	execute	is the command to execute after each slice creation (once it is completed)

Note: data_name should be equal to internal_name except when reslicing an archive as dar_xform does in which case internal_name is randomly, and data_name is kept from the source archive

Member Function Documentation

◆ get_data_name()

virtual const label& libdar::sar::get_data_name ( ) const

inlineoverridevirtual

obtain the data_name of the archive (label associated with the archive's data)

Note: label are conserved with dar_xform and archive isolation, but are not with archive merging or archive creation (full or differential backup)

Implements libdar::contextual.

Definition at line 175 of file sar.hpp.

References of_data_name.

◆ inherited_flush_read()

virtual void libdar::sar::inherited_flush_read ( )

inlineoverrideprotectedvirtual

reset internal engine, flush caches in order to read the data at current position

Note: when the object relies on external object or system object to fetch the data from for reading, when a call to (inherited_)flush_read() occurs, the current object must not assume that any previously read data is still valid if it has internal buffers or the like and it should flush them asap. This call must not propagate the flush_read to any other gneric_file object it could rely on

Implements libdar::generic_file.

Definition at line 191 of file sar.hpp.

◆ inherited_read()

virtual U_I libdar::sar::inherited_read	(	char *	a,
		U_I	size
	)

overrideprotectedvirtual

implementation of read() operation

Parameters

[in,out]	a	where to put the data to read
[in]	size	says how much data to read

Returns: the exact amount of data read and put into 'a'

Note: read as much byte as requested, up to end of file stays blocked if not enough data is available and EOF not yet met. May return less data than requested only if EOF as been reached. in other worlds, EOF is reached when returned data is stricly less than the requested data Any problem shall be reported by throwing an exception.

Implements libdar::generic_file.

◆ inherited_read_ahead()

virtual void libdar::sar::inherited_read_ahead ( const infinint & amount )

overrideprotectedvirtual

tells the object that several calls to read() will follow to probably obtain at least the given amount of data

Parameters

[in] amount is the maximum expected amount of data that is known to be read

Note: this call may be implemented as a do-nothing call, its presence is only to allow optimization when possible, like in multi-threaded environment

Implements libdar::generic_file.

◆ inherited_sync_write()

virtual void libdar::sar::inherited_sync_write ( )

inlineoverrideprotectedvirtual

write down any pending data

Note: called after sanity checks from generic_file::sync_write() this method's role is to write down any data pending for writing in the current object it has not to be propagated to other gneric_file object this object could rely on

Implements libdar::generic_file.

Definition at line 190 of file sar.hpp.

◆ inherited_terminate()

virtual void libdar::sar::inherited_terminate ( )

overrideprotectedvirtual

destructor-like call, except that it is allowed to throw exceptions

Note: this method must never be called directly but using terminate() instead, generic_file class manages it to never be called more than once

Implements libdar::generic_file.

◆ inherited_truncate()

virtual void libdar::sar::inherited_truncate ( const infinint & pos )

overrideprotectedvirtual

truncate file at the give offset

Note: if pos is greater than the current file size, this call may do nothing (not even enlarging the file); this call should always fail on a read-only generic_file; implementation must throw exception if truncate is not possible for other reason than read/write access mode

Implements libdar::generic_file.

◆ inherited_write()

virtual void libdar::sar::inherited_write	(	const char *	a,
		U_I	size
	)

overrideprotectedvirtual

implementation of the write() operation

Parameters

[in]	a	what data to write
[in]	size	amount of data to write

Note: must either write all data or report an error by throwing an exception

Implements libdar::generic_file.

◆ open_readonly()

void libdar::sar::open_readonly	(	const std::string &	fic,
		const infinint &	num,
		bool	bytheend
	)

private

Parameters

fic	open file of name "fic" for read only
num	"num" is the slice number
bytheend	whether to position the read cursor at the beginning or the end of the file

◆ open_writeonly()

void libdar::sar::open_writeonly	(	const std::string &	fic,
		const infinint &	num,
		bool	bytheend
	)

private

Parameters

fic	open file of name "filename" for write only
num	"num" is the slice number
bytheend	whether to overwrite or to append data to be written to the file

◆ skip()

virtual bool libdar::sar::skip ( const infinint & pos )

overridevirtual

skip at the absolute position

Parameters

[in] pos the offset in byte where next read/write operation must start

Returns: true if operation was successfull and false if the requested position is not valid (after end of file)

Note: if requested position is not valid the reading/writing cursor must be set to the closest valid position

Implements libdar::generic_file.

◆ skippable()

virtual bool libdar::sar::skippable	(	skippability	direction,
		const infinint &	amount
	)

overridevirtual

whether the implementation is able to skip

Note: the capability to skip does not mean that skip_relative() or skip() will succeed, but rather that the inherited class implementation does not by construction forbid the requested skip (like inherited class providing a generic_file interface of an anonymous pipe for example)

Implements libdar::generic_file.

The documentation for this class was generated from the following file:

sar.hpp

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ sar() [1/2]

◆ sar() [2/2]

Member Function Documentation

◆ get_data_name()

◆ inherited_flush_read()

◆ inherited_read()

◆ inherited_read_ahead()

◆ inherited_sync_write()

◆ inherited_terminate()

◆ inherited_truncate()

◆ inherited_write()

◆ open_readonly()

◆ open_writeonly()

◆ skip()

◆ skippable()