File: api_tutorial.html

package info (click to toggle)
dar 2.8.1-3
links: PTS, VCS
area: main
in suites: forky, sid
size: 12,024 kB
sloc: cpp: 86,219; sh: 6,978; ansic: 895; makefile: 489; python: 242; csh: 115; perl: 43; sed: 16
file content (2594 lines) | stat: -rw-r--r-- 108,250 bytes
parent folder | download | duplicates (4)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <link href="style.css" rel="stylesheet">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
    <title>Libdar API - Tutorial</title>
  </head>
  <body>

    <div class=top>
      <img alt="Dar Documentation" src="dar_s_doc.jpg" style="float:left;">
      <div class=h1>
	<h1>Libdar APplication Interface (API) tutorial</h1>
	(API version 6.x.x)
      </div>
    </div>


    <h2>Presentation</h2>
    <p>
      The Libdar library provides a
      complete abstraction layer for handling
      <i>Dar</i> archives. The general
      operations provided are:
    </p>

    <ul>
      <li>archive creation,</li>
      <li>file extraction from archive,</li>
      <li>archive listing,</li>
      <li>archive testing,</li>
      <li>archive comparison,</li>
      <li>catalogue isolation,</li>
      <li>archive merging,</li>
      <li>archive reparation</li>
      <li>dar_manager database manipulations</li>
      <li>dar_slave steering</li>
      <li>dar_xform operation</li>
    </ul>

    <p>
      Note that <i>Disk ARchive</i> <b>and</b>
      <i>libdar</i>
      have been released under the <b>Gnu
	General Public License (GPL)</b>.
      All code linked to libdar
      (statically or dynamically), <b>must</b>
      also be covered by the GPL or compatible license.
      Commercial use is prohibited unless otherwise
      explicitely agreeded with libdar's author.
    </p>

    <p>
      This tutorial will show you how to
      use the libdar API. Since release 2.0.0 the
      <i>dar</i> command-line executable also
      relies on this API, looking at it's code may provide a good
      illustration on the way to use libdar,
      the file <code>src/dar_suite/dar.cpp</code>
      is the primary consumer of the libdar API.
      However we will see here, step by step how
      you can leverage the API for your own use.
    </p>

    <p>
      In the following sample codes will be provided, they
      are solely illustrative and is not guaranteed to compile.
      Reference documentation for this API
      is contained in the source code as doxygen comment which
      can be extracted and "compiled" in the
      the <code>doc/html</code> directory when compiling dar/libdar.
      This API reference document is also available
      <a href="http://dar.linux.free.fr/doc/html/index.html">online</a>
      and will be referred below as the <i>API reference documentation</i>.
    </p>

    <h2>Let's Start</h2>

    <h3>Conventions</h3>

    <h4>Language</h4>
    <p>
      Dar and libdar are written in
      C++, and so is the libdar fundamental API. Though you can find
      a <b>Python</b> binding in the <code>src/python</code> subdirectory,
      which strongly follows the class hierarchy that will see here with
      C++ sample code. The <a href="python/libdar_test.py">libdar_test.py</a>
      document rawly follows with <i>python</i> code what we will see
      below with C++.
    </p>
    <p>
      Feel free to contribute if you want bindings for other languages.
    </p>

    <h4>Header files</h4>
    <p>
      Only one include file is required in your program to have access to
      libdar:
    </p>
    <code class=block>
      #include &lt;dar/libdar.hpp&gt;
    </code>

    <h4>Libdar namespace</h4>
    <p>
      All libdar symbols are defined within
      the <b>libdar namespace</b>. You
      can either add the <code>using namespace libdar;</code>
      statement at the beginning of your source files...
    </p>
    <code class=block>
      using namespace libdar;

      get_version();
      ...
    </code>
    <p>
      ...or, as shown below, you can
      explicitly use the namespace in front of libdar symbols,
      we will use this notation in the following, which has the
      advantage of avoiding name conflicts and clarify origin of the
      symbols used, but lead to a more heavier code, less easy to
      read:
    </p>
    <code class=block>
      libdar::get_version();
      ...
    </code>

    <h4>Exceptions</h4>
    <p>
      The library makes use of
      exception to report unexpected conditions. These contain the reason and
      context the error occurred in, so you can be catch these in your code
      to display details of the error and its cause. All exceptions used within
      libdar inherit from the pure virtual class <b>libdar::Egeneric</b>
    </p>
    <p>
      Most of the time you will use only one of the following two methods:
    </p>
    <ul>
      <li><code>std::string &amp; get_message() const</code></li>
      <li><code>std::string &amp; dump_str() const</code></li>
    </ul>

    <dl>
      <dt class=void>get_message()</dt><dd>
	returns a message string describing the error met
      </dd>
      <dt class=void>dump_str()</dt><dd>
	returns a text paragraph with additional information about
	the stack as well as context the error occurred in.
      </dd>
    </dl>

    <p>
      Now, messages are for human, you may need to provide different
      behaviors depending on the type of the error libdar has met and
      which triggers such exception. This is can be done by checking the
      type of the exception.
    </p>
    <p>
      We will only focus on most common exception type read the
      <i>API reference documentation</i> for an exhaustive list of the exception
      type used by libdar:
    </p>

    <dl>
      <dt class=void>libdar::Ebug</dt><dd>
	This one is used when <i>a-situation-that-should-never-occur</i>
	is met and can be assumed to be a bug in libdar. Using the
	<code>get_message()</code> method in that
	situation would not provide all necessary details to understand
	and fix the bug, so it is advised to always use <code>dump_str()</code>
	for that specific type of exception and abort further execution regarding
	libdar.
      </dd>
      <dt class=void>libdar::Erange</dt><dd>
	A parameter or a value is out of range, details is provided
	with <code>get_message()</code>
      </dd>
      <dt class=void>libdar::Ememory</dt><dd>
	Libdar lacked of virtual memory to proceed to the requested operation
      </dd>
      <dt class=void>libdar::Einfinint</dt><dd>
	an arythmetic error occurred when using <code>libdar::infinint</code>
	object, which is a internal integer type that can handle arbitrary
	large numbers. Today it is only used if libdar has been compiled
	with <code>--enable-mode=infinint</code> so you are not likely to meet
	it.
      </dd>
      <dt class=void>libdar::Elimitint</dt><dd>
	when <i>infinint</i> are not used, a wrapper class over system
	integers is used to detect integer overflow. In that situation,
	this exception is thrown, enjoying the user to use a <i>infinint</i>
	based flavor of libdar to avoid this error
      </dd>
      <dt class=void>libdar::Ehardware</dt><dd>
	used when the operating system returned an I/O error or hardware
	related error
      </dd>
      <dt class=void>libdar::Esystem</dt><dd>
	When software related error is reported by the system, like lack of
	ownership, permission or non existing file...
      </dd>
      <dt class=void>libdar::Euser_abort</dt><dd>
	This exception is thrown as the consequence of user request to
	abort the process. This may occur when aswnering to a question
	issued by libdar.
      </dd>
      <dt class=void>libda::Ethread_cancel</dt><dd>
	used when a program has called the thread cancellation routine
	of libdar, which drives libdar to stop as soon as possible (immediately
	when the control point is met, or delayed aborting cleanly the operation
	under process depending on the option used to cancel the running libdar
	thread.
      </dd>
    </dl>
    <p>
      Some other exist and are well described in the
      <i>API reference documentation</i>. You can thus wrap the whole
      libdar interaction with a statement like in the following example:
    </p>
    <code class=block>
      &nbsp;try
      &nbsp;{
      &nbsp;    // calls to libdar
      &nbsp;    ...
      &nbsp;    //
      &nbsp;}
      &nbsp;catch(libdar::Ebug &amp; e)
      &nbsp;{
      &nbsp;    std::string msg = e.dump_str();
      &nbsp;
      &nbsp;    // do something with msg like for example:
      &nbsp;    std::cerr &lt;&lt; msg &lt;&lt; std::endl;
      &nbsp;}
      &nbsp;catch(libdar::Euser_abort &amp; e)
      &nbsp;{
      &nbsp;    // some specific treatment for this
      &nbsp;    // type of exception
      &nbsp;    ...
      &nbsp;}
      &nbsp;catch(libdar::Egeneric &amp; e)
      &nbsp;{
      &nbsp;    // a global treatment for all other libdar exceptions
      &nbsp;    std::string msg = e.get_message(); &lt;&lt; std::endl;
      &nbsp;    ...
      &nbsp;}
    </code>



    <h2>First we must initialize libdar</h2>
    <p>
      the libdar initialization is
      performed by calling the <code>libdar::get_version()</code>
      function.
    </p>
    <p>
      This function can be called several time though only once is necessary,
      but this call has to complete before any other call to libdar.
    </p>
    <p>
      In a <b>multi-thread context</b> libthreadar
      initialization is not re-entrant. In other word the first
      call to <code>libdar::get_version()</code> must complete
      before any other call to libdar can take place in another
      thread of the running process. Once libdar has
      been initialized, you can call <code>libdar::get_version()</code>
      concurrently from several threads at the same time without
      problem.
    </p>
    <code class=block>
      libdar::get_version();
    </code>



    <h2>We should prepare the end right now</h2>

    <p>
      Libdar used some
      data-structures (mutex, secured memory, etc.) that need to be released
      properly before ending the process. It is important to invoke the
      <code>close_and_clean()</code> function before exiting your program if you
      had called <code>get_version()</code> previously. After that,
      the only allowed call to libdar is <code>get_version()</code>.
    </p>
    <code class=block>
      libdar::close_and_clean()
    </code>

    <dl>
      <dt class=void>Note:</dt><dd>
	<code>closes_and_clean()</code>
	makes the necessary for memory to be released in the
	proper order.
	<u>
	  Not calling close_and_clean() at the
	  end of your program may result in
	  uncaught exception message from libdar at the end of
	  the execution.
	</u>
	This depends on the compiler, libc and option
	activated in libdar at compilation time.
      </dd>
    </dl>
    <p>
      All in one, at the highest level, you code should look like the following:
    </p>

    <code class=block>

      &nbsp;libdar::get_version();
      &nbsp;try
      &nbsp;{
      &nbsp;    try
      &nbsp;    {
      &nbsp;
      &nbsp;        // calls to libdar
      &nbsp;        // thing we will see in next
      &nbsp;        ...
      &nbsp;        ...
      &nbsp;    }
      &nbsp;    catch(libdar::Ebug & e)
      &nbsp;    {
      &nbsp;        std::string msg = e.dump_str();
      &nbsp;
      &nbsp;        // do something with msg like for example:
      &nbsp;        std::cerr &lt;&lt; msg &lt;&lt; std::endl;
      &nbsp;    }
      &nbsp;    catch(libdar::Egeneric & e)
      &nbsp;    {
      &nbsp;        std::string msg = e.get_message();
      &nbsp;
      &nbsp;        // do something with msg like for example
      &nbsp;        std::cerr &lt;&lt; msg &lt;&lt; std::endl;
      &nbsp;    }
      &nbsp;}
      &nbsp;catch(...)
      &nbsp;{
      &nbsp;    libdar::close_and_clean();
      &nbsp;    throw;
      &nbsp;}
      &nbsp;libdar::close_and_clean();
    </code>



    <h2>Intercepting signals</h2>
    <p>
      libdar by itself does not make 	use of any signal (see signal(2) and
      kill(2)). However, gpgme library with which libdar may be linked with
      in order to support asymmetrical strong encryption (i.e. encryption using
      public/private keys) may trigger the PIPE signal. Your application
      shall thus either ignore it (<code>signal(SIGPIPE, SIG_IGN)</code>)
      or provide an adhoc handle.
      By default the PIPE signal leads the receiving process to terminate.
    </p>



    <h2>Libdar classes</h2>
    <p>
      The main components of libdar are four classes:
    </p>
    <ul>
      <li><b>class libdar::archive</b> to play with dar archives</li>
      <li><b>class libdar::database</b> to play with dar_manager databases</li>
      <li><b>class libdar::libdar_slave</b> to take the role of dar_slave</li>
      <li><b>class libdar::libdar_xform</b> to re-slice existing archives like dar_xform does</li>
    </ul>
    <p>
      In the following we will first see <b>class libdar::archive</b>
      which will take most of our effort as other
      classes which we will see at the end are very trivial.
    </p>



    <h2>Multithreaded environment</h2>
    <p>
      Except when explicitely mentioned,
      a given libdar object can only be manipulated by a
      single thread. You can however perform several operations
      concurrently from different thread, each having its own set
      of libdar objects. Though, if one thread is creating an
      archive by mean of an first object and at the same
      time another thread by mean of a second object is trying to read the
      same archive under construction, things might not work as expected. But this
      is obvious considerations we will not dig any further assuming you
      know what you are doing.
    </p>



    <h2>Let's create a simple archive</h2>
    <p>
      Creating a <code>libdar::archive</code> object depending on
      the constructor used, leads to either:
    </p>
    <ul>
      <li>
	the <b>creation of a brand new archive</b> on filesystem, thus
	performing a backup (full, incremental, differential,
	decremental, ...)
      </li>
      <li>
	the <b>opening an existing archive</b>, for further
	operation (listing, file restoration, archive testing,
	archive difference, ...)
      </li>
      <li>
	<b>merging</b> the content of two existing archives into a new one
      </li>
      <li>
	the <b>reparing</b> of an archive which catalogue is missing
	or damaged. The <i>catalogue</i>
	(which means catalog in French) is the table of content
	of an archive.
      </li>
    </ul>

    <h3>Basic archive creation</h3>
    <p>
      For <b>archive creation</b> the
      constructor format is the following one:
    </p>

    <code class=block>
      &nbsp;archive::archive(const std::shared_ptr&lt;user_interaction&gt; &amp <b>dialog</b>,
      &nbsp;                 const path &amp; <b>fs_root</b>,
      &nbsp;                 const path &amp; <b>sauv_path</b>,
      &nbsp;                 const std::string &amp; <b>filename</b>,
      &nbsp;                 const std::string &amp; <b>extension</b>,
      &nbsp;                 const archive_options_create &amp; <b>options</b>,
      &nbsp;                 statistics * <b>progressive_report</b>);
    </code>
    <p>
      For now we will left beside some parameters, that we will see
      in detail later:
    </p>
    <ul>
      <li>
	<b>dialog</b> can be set to <b>std::nullptr</b> for now, this means
	that all interaction with the user will take place by mean of standard
	input, output and error.
      </li>
      <li>
	<b>fs_root</b> is the directory to take as
	root of the backup. The <b>libdar::path</b>
	class can be setup from a <b>std::string</b>, which
	in turn can be setup from a classical <b>char*</b>
      </li>
      <li>
	<b>sauv_path </b> is the path where to
	write the archive to, here also a <b>std::string</b>
	will do the job
      </li>
      <li>
	<b>filename</b> is the <i>slice name</i> to use for
	the archive we will create.
      </li>
      <li>
	<b>extension</b> is the archive extension
	to use. There is no reason to not use the string
	<b>"dar"</b> here
      </li>
      <li>
	<b>options</b> is a class that carries all
	optional parameters, it contains a
	<i>constructor without argument</i> setting
	all options are set to their default values
      </li>
      <li>
	<b>statistics</b> can
	receive the address of an existing object that another thread can read
	while a first one is doing a backup operation (a first case of libdar
	object that can be used by several threads at the same time). We will see this feature
	later on, but for now let's set this to a <b>null pointer</b> (i.e.: std::nullptr)
      </li>
    </ul>

    <p>
      Once the object has been created (the constructor has returned), the
      archive operation has completed and a new backup has been completely
      written on disk.
    </p>

    <code class=block>
      &nbsp;libdar::archive my_first_backup(nullptr,
      &nbsp;                                "/home/me",
      &nbsp;                                "/tmp",
      &nbsp;                                "first_backup",
      &nbsp;                                "dar",
      &nbsp;                                libdar::archive_options_create(),
      &nbsp;                                std::nullptr);
    </code>

    <p>
      The previous example has create a single sliced archive
      <b>first_backup.1.dar</b> located under
      <b>/tmp</b>. This backup contains the content of
      the directory <b>/home/me</b>
      and its sub-directories, without compression
      and without ciphering. You have guessed: compression,
      slicing, ciphering can be set by playing with
      passing an adhoc <b>archive_option_create</b>
      object to this archive constructor, something we will
      see in details a bit further.
    </p>
    <p>
      Once the object <code>my_first_backup</code>
      has been created there is only little thing we can do
      with it: only archive listing or archive isolation. For archive
      extraction, testing or diffing, we needs creating a new object with a
      "read" constructor.
    <p>
      If we had allocated the archive on the heap (using <code>new</code>),
      we would have just added the <code>delete</code> invocation right
      after the construction of the <code>my_first_backup</code>
      object:
    </p>
    <code class=block>
      &nbsp;libdar::archive* my_first_backup = new libdar::archive(nullptr,
      &nbsp;                                                       "/home/me",
      &nbsp;                                                       "/tmp",
      &nbsp;                                                       "first_backup",
      &nbsp;                                                       "dar",
      &nbsp;                                                        libdar::archive_options_create(),
      &nbsp;                                                        nullptr);
      &nbsp;
      &nbsp;    // we assume std::bad_alloc would be thrown if an allocation
      &nbsp;    // problem had occurred
      &nbsp;
      &nbsp;    // same thing if libdar throws an exception at constructor time,
      &nbsp;    // the object would not be created and would not have to be deleted.
      &nbsp;
      &nbsp;    // So now we can delete the created object:
      &nbsp;
      &nbsp;delete my_first_backup;
    </code>

    <h3>Progressive report</h3>
    <p>
      During the operation we get nothing shown unless an error occurs.
      To provide more visibility on the process we will use an
      <b>libdar::statistics</b>
      object passed as last argument of this constructor. Then we will
      use some interesting method of class <class>libdar::statistics</class>:
    </p>
    <ul>
      <li>std::string <b>get_treated_str()</b></li>
      <li>std::string <b>get_hard_links_str()</b></li>
      <li>std::string <b>get_skipped_str()</b></li>
      <li>std::string <b>get_inode_only_str()</b></li>
      <li>std::string <b>get_ignored_str()</b></li>
      <li>std::string <b>get_tooold_str()</b></li>
      <li>std::string <b>get_errored_str()</b></li>
      <li>std::string <b>get_deleted_str()</b></li>
      <li>std::string <b>get_ea_treated_str()</b></li>
      <li>std::string <b>get_byte_amount_str()</b></li>
      <li>std::string <b>get_fsa_treated_str()</b></li>
    </ul>
    <p>
      If you have a doubt about the meaning and use of a particular counter
      in a particular operation, please refer to <i>API reference documentation</i>
      for class <code>libdar::statistics</code>, the private fields
      corresponding to these counter are explicitly defined there.
    </p>

    <code class=block>
      &nbsp;<b>libdar::statistics <e>stats</e>;</b>
      &nbsp;
      &nbsp;libdar::archive my_first_backup(nullptr,
      &nbsp;                                "/home/me",
      &nbsp;                                "/tmp",
      &nbsp;                                "first_backup",
      &nbsp;                                 "dar",
      &nbsp;                                 libdar::archive_options_create(),
      &nbsp;                                 <e>& stats</e>);
      &nbsp;
      &nbsp;    // in another thread we can see the progression:
      &nbsp;
      &nbsp;std::cout &lt;&lt; <e>stats</e>.get_treated_str()
      &nbsp;          &lt;&lt; " file(s) saved" &lt;&lt; std::endl;
      &nbsp;
      &nbsp;std::cout &lt;&lt; <e>stats</e>.get_errored_str()
      &nbsp;          &lt;&lt; " file(s) failed to backup" &lt;&lt; std::endl;
      &nbsp;
      &nbsp;std::cout &lt;&lt; <e>stats</e>.get_ea_treated_str()
      &nbsp;          &lt;&lt; " Extended Attributes saved" &lt; std::endl;
    </code>

    <h3>Archive creation options</h3>

    <p>
      in the previous example, we
      have created an temporary object of class <b>libdar::archive_options_create</b> and
      passed it on-fly to the archive constructor without modifying it. Thus
      we used the default options for this operations. But <b>a lot</b>
      of options are available, each one can be modified by a specific
      method of this class Follow is a subset of the
      available options. We won't details them all, but you can refer the doxygen
      documentation for <b>class libdar::archive_options_create</b> for additional information.
    </p>
    <ul>
      <li><code>void <b>set_reference</b>(<b>std::shared_ptr&lt;libdar::archive&gt;</b> ref_arch)</code></li>
      <li><code>void <b>set_selection</b>(const <b>libdar::mask</b> &amp; selection)</code></li>
      <li><code>void <b>set_subtree</b>(const <b>libdar::mask</b> &amp; subtree)</code></li>
      <li><code>void <b>set_allow_over</b>(bool allow_over)</code></li>
      <li><code>void <b>set_warn_over</b>(bool warn_over)</code></li>
      <li><code>void <b>set_info_details</b>(bool info_details)</code></li>
      <li><code>void <b>set_display_treated</b>(bool display_treated, bool only_dir)</code></li>
      <li><code>void <b>set_display_skipped</b>(bool display_skipped)</code></li>
      <li><code>void <b>set_display_finished</b>(bool display_finished)</code></li>
      <li><code>void <b>set_pause</b>(const <b>libdar::infinint</b> &amp; pause)</code></li>
      <li><code>void <b>set_empty_dir</b>(bool empty_dir)</code></li>
      <li><code>void <b>set_compression</b>(<b>libdar::compression</b> compr_algo)</code></li>
      <li><code>void <b>set_compression_level</b>(<b>libdar::U_I</b>compression_level)</code></li>
      <li><code>void <b>set_slicing</b>(const <b>libdar::infinint</b> &amp; file_size, const <b>libdar::infinint</b> &amp; first_file_size)</code></li>
      <li><code>void <b>set_ea_mask</b>(const <b>libdar::mask</b> &amp; ea_mask)</code></li>
      <li><code>void <b>set_execute</b>(const std::string &amp; execute)</code></li>
      <li><code>void <b>set_crypto_algo</b>(<b>libdar::crypto_algo</b>crypto)</code></li>
      <li><code>void <b>set_crypto_pass</b>(const <b>libdar::secu_string</b> &amp; pass)</code></li>
      <li><code>void <b>set_compr_mask</b>(const <b>libdar::mask</b> &amp; compr_mask);</code></li>
      <li><code>void <b>set_min_compr_size</b>(const <b>libdar::infinint</b> &amp; min_compr_size)</code></li>
      <li><code>void <b>set_nodump</b>(bool nodump)</code></li>
      <li><code>void <b>set_exclude_by_ea</b>(const std::string &amp; ea_name)</code></li>
      <li><code>void <b>set_what_to_check</b>(<b>libdar::comparison_fields</b> what_to_check)</code></li>
      <li><code>void <b>set_hourshift</b>(const <b>libdar::infinint</b> &amp; hourshift)</code></li>
      <li><code>void <b>set_empty</b>(bool empty)</code></li>
      <li><code>void <b>set_alter_atime</b>(bool alter_atime)</code></li>
      <li><code>void <b>set_furtive_read_mode</b>(bool furtive_read)</code></li>
      <li><code>void <b>set_same_fs</b>(bool same_fs)</code></li>
      <li><code>void <b>set_snapshot</b>(bool snapshot)</code></li>
      <li><code>void <b>set_cache_directory_tagging</b>(bool cache_directory_tagging)</code></li>
      <li><code>void <b>set_fixed_date</b>(const <b>libdar::infinint</b> &amp; fixed_date)</code></li>
      <li><code>void <b>set_slice_permission</b>(const std::string &amp; slice_permission)</code></li>
      <li><code>void <b>set_slice_user_ownership</b>(const std::string &amp; slice_user_ownership)</code></li>
      <li><code>void <b>set_slice_group_ownership</b>(const std::string &amp; slice_group_ownership)</code></li>
      <li><code>void <b>set_retry_on_change</b>(const <b>libdar::infinint</b> &amp; count_max_per_file, const <b>libdar::infinint</b> &amp; global_max_byte_overhead)</code></li>
      <li><code>void <b>set_security_check</b>(bool check)</code></li>
      <li><code>void<b> set_user_comment</b>(const std::string &amp; comment)</code></li>
      <li><code>void <b>set_hash_algo</b>(<b>libdar::hash_algo</b> hash)</code></li>
      <li><code>void <b>set_slice_min_digits</b>(<b>libdar::infinint</b> val)</code></li>
      <li><code>void <b>set_backup_hook</b>(const std::string &amp; execute, const <b>mask</b> &amp; which_files);</code></li>
      <li><code>void <b>set_delta_diff</b>(bool val)</code></li>
      <li><code>void <b>set_delta_signature</b>(bool val)</code></li>
      <li><code>void <b>set_delta_mask</b>(const <b>libdar::mask</b> &amp; delta_mask)</code></li>
    </ul>
    <p>
      First you may have find some new libdar types (=classes) in arguments, we will
      briefly explain how to set them:
    </p>
    <dl>
      <dt class=void>std::shared_ptr&lt;libdar::archive&gt;</dt><dd>
	<p>
	  C++11 shared smart-pointer to an existing libdar::archive object. We will see
	  how to use it next when performing differential backup
	</p>
      </dd>
      <dt class=void>libdar::infinint</dt><dd>
	<p>
	  can be set from a <b>classical unsigned int</b>,
	  unsigned long or other unsigned integer type, so
	  for you this is like another unsigned integer type
	</p>
      </dd>
      <dt class=void>libdar::mask</dt><dd>
	<p>
	  This class is a top of a class hierarchy containing
	  several classes provided with libdar. It allows you
	  to define a filtering mecanism for the feature wher
	  it is used. We will see how to use it in a further
	  paragraph of this tutorial.
	</p>
      </dd>
      <dt class=void>libdar::compression</dt><dd>
	<p>
	  It is an enumeration which values are (among others
	  not listed here):
	</p>
        <ul>
          <li><code>libdar::compression::<b>gzip</b></code></li>
	  <li><code>libdar::compression::<b>bzip2</b></code></li>
	  <li><code>libdar::compression::<b>xz</b></code></li>
          <li><code>libdar::compression::<b>lzo</b></code></li>
        </ul>
	<br/>
      </dd>
      <dt class=void>libdar::U_I</dt><dd>
	<p>
	  A the opposite of the libdar::infinint this is not a class
	  but an alias to the system classical unsigned integer. Depending
	  on the operating system and CPU this might point to <i>unsigned long</i>
	  or <i>unsigned long long</i> or other equivalent type.
	</p>
      </dd>
      <dt class=void>libdar::crypto_algo</dt><dd>
	<p>
	  This is an enumeration with values like:
	</p>
        <ul>
          <li><code>libdar::crypto_algo::<b>scrambling</b></code></li>
	  <li><code>libdar::crypto_algo::<b>blowfish</b></code></li>
	  <li><code>libdar::crypto_algo::<b>aes256</b></code></li>
	  <li><code>libdar::crypto_algo::<b>twofish256</b></code></li>
	  <li><code>libdar::crypto_algo::<b>serpent256</b></code></li>
	  <li><code>libdar::crypto_algo::<b>camellia256</b></code></li>
        </ul>
	<br/>
      </dd>
      <dt class=void>libdar::secu_string</dt><dd>
	<p>
	  This is a class used to securely storing password and sensible
	  cryptographic information. It can be setup from a char* or
	  better, from a filedescriptor. its main constructor is:
	</p>
        <ul>
          <li>secu_string(<b>const char*</b> ptr, U_I <b>size</b>)</li>
        </ul>
	<br/>
      </dd>
      <dt class=void>libdar::comparison_fields</dt><dd>
	<p>
	  This is an enumeration with values like:
	</p>
        <ul>
          <li><code>libdar::comparison_fields::<b>all</b></code></li>
	  <li><code>libdar::comparison_fields::<b>ignore_owner</b></code></li>
	  <li><code>libdar::comparison_fields::<b>mtime</b></code></li>
	  <li><code>libdar::comparison_fields::<b>inode_type</b></code></li>
	</ul>
      </dd>
    </dl>
    <p>
      Follows a variant of the previous backup creation example,
      here we set some options to a given value:
    </p>
    <code class=block>
      &nbsp;libdar::archive_options_create <b>opt</b>;
      &nbsp;
      &nbsp;<b>opt</b>.set_allow_over(false);
      &nbsp;    // forbids slice overwriting
      &nbsp;
      &nbsp;<b>opt</b>.set_display_finished(true);
      &nbsp;    // show a summary after each completed directory
      &nbsp;
      &nbsp;<b>opt</b>.set_slicing(1024000,
      &nbsp;                       2000);
      &nbsp;    // slices of 1000 kiB initial slice of 2000 bytes
      &nbsp;
      &nbsp;<b>opt</b>.set_pause(2);
      &nbsp;    // pause every two slices
      &nbsp;
      &nbsp;<b>opt</b>.set_execute("echo slice %N completed");
      &nbsp;    // command executed after each slice
      &nbsp;
      &nbsp;<b>opt</b>.set_crypto_algo(libdar::crypto_algo::aes256);
      &nbsp;
      &nbsp;    // providing an empty secu_string leads dar
      &nbsp;    // interactively ask the passphrase in a secure manner
      &nbsp;<b>opt</b>.set_crypto_pass(secu_string());
      &nbsp;    // But this previous call is useless as en empty secu_string is the default
      &nbsp;    // though one could have setup a secu_string from a std::string
      &nbsp;    // this way:
      &nbsp;std::string my_pass("hello world!");
      &nbsp;libdar::secu_string my_secupass(my_pass.c_str(), my_pass.size());
      &nbsp;<b>opt</b>.set_crypto_pass(my_secupass);
      &nbsp;
      &nbsp;<b>opt</b>.set_compression(libdar::compression::xz);
      &nbsp;<b>opt</b>.set_compression_level(6);
      &nbsp;<b>opt</b>.set_min_compr_size(10240);
      &nbsp;// not trying compressing file smaller than 10 kiB
      &nbsp;
      &nbsp;    // now we have the <b>opt</b> option object ready
      &nbsp;    // we can proceed to the archive creation using it:
      &nbsp;
      &nbsp;libdar::archive my_first_backup(nullptr,
      &nbsp;                                "/home/me",
      &nbsp;                                "/tmp",
      &nbsp;                                "first_backup",
      &nbsp;                                "dar",
      &nbsp;                                <b>opt</b>,
      &nbsp;                                nullptr);
    </code>
    <p>
      And of course, you can use both <b>libdar::statistics</b>
      and <b>libdar::archive_options_create</b> at
      the same time, when creating a backup
    </p>



    <h2>Creating a differential or incremental backup</h2>
    <p>
      Maybe you have guessed?
      Compared to the previous operation (full backup) doing an differential
      or incremental backup will only ask to open, in read mode, an existing
      archive and pass this object as argument of class
      archive_options_create::set_reference() seen just above.
    </p>
    <p>
      The read-only constructor for class archive is the following:
    </p>
    <code class=block>
      archive::archive(const std::shared_ptr&lt;user_interaction&gt; &amp; <b>dialog</b>,
      const path &amp; <b>chem</b>,
      const std::string &amp; <b>basename</b>,
      const std::string &amp; <b>extension</b>,
      const archive_options_read &amp; <b>options</b>);
    </code>
    <p>
      same as before:
    </p>
    <ul>
      <li>
	<b>dialog</b> can be set to a <b>null pointer</b>, we will see
	further in this tutorial how to play with
	<code>user_interaction</code> class
      </li>
      <li>
	<b>chem</b> is the path leading to the
	archive to read, it can be provided as a <b>std::string</b> or
	even a <b>char*</b>
      </li>
      <li>
	<b>basename</b> is the archive basename to read
      </li>
      <li>
	<b>extension</b> should be <b>"dar"</b> unless you want
	to confuse people
      </li>
      <li>
	<b>options</b> can be set to an empty object for default
	options, we will see this class in more
	details with archive listing
      </li>
    </ul>
    <br/>
    <code class=block>
      &nbsp;    // first we open the previously created archive in read mode:
      &nbsp;
      &nbsp;std::shared_ptr&lt;libdar::archive&gt; <e>ref_archive</e>;
      &nbsp;
      &nbsp;<e>ref_archive</e> = std::make_shared&lt;libdar::archive&gt;(nullptr,
      &nbsp;                                                "/home/me",
      &nbsp;                                                "first_backup",
      &nbsp;                                                "dar",
      &nbsp;                                                archive_create_options_read());
      &nbsp;
      &nbsp;    // for clarity we separated the creation of the
      &nbsp;    // archive object used as archive of reference from
      &nbsp;    // the archive object which creation will perform
      &nbsp;    // differential backup (see below). We could have made
      &nbsp;    // in one step using an anonymous temporary object
      &nbsp;    // (in place of <code>ref_archive</code>)
      &nbsp;    // invoking directly <code>std::make_shared</code>
      &nbsp;    // when calling <code>set_reference()</code> below:
      &nbsp;
      &nbsp;libdar::archive_options_create <b>opt</b>;
      &nbsp;
      &nbsp;<b>opt</b>.set_reference(<e><b>ref_archive</b></e>);
      &nbsp;
      &nbsp;libdar::archive my_second_backup(nullptr,
      &nbsp;                                 "/home/me",
      &nbsp;                                 "/tmp",
      &nbsp;                                 "diff_backup",
      &nbsp;                                 "dar",
      &nbsp;                                 <b>opt</b>,
      &nbsp;                                 nullptr);
    </code>

    <p>
      creating a
      incremental backup is exactly the same, the difference is the nature of
      the archive of reference. We used to describe a differential backup
      one that has a full backup as reference, while an incremental backup
      has another incremental or differential backup as reference (not a full
      backup).
    </p>



    <h2>Archive listing</h2>
    <p>
      Archive listing operation consist of the creation of an archive object
      in read mode as we just did above for <code>ref_archive</code> and
      invoking a method on that newly object to see all or a sub-directory
      content of the archive. Before
      looking at the listing method let's zoom on the class
      <code>libdar::archive_create_options_read</code> which
      we just skip over previously.
    </p>

    <h3>Archive reading options</h3>
    <p>
      The same as the class <code>archive_options_create</code> detailed above, the
      class <code>archive_options_read</code> has a constructor without argument that sets
      the different options to their default value. You can change them one
      by one by mean of specific methods. The most usual ones are:
    </p>

    <ul>
      <li>void <b>set_execute</b>(const std::string &amp; execute)</li>
      <li>void <b>set_info_details</b>(bool info_details)</li>
      <li>void <b>set_sequential_read</b>(bool val)</li>
      <li>void <b>set_slice_min_digits</b>(infinint val)</li>
    </ul>
    <p>
      <code>set_execute()</code> runs a command before reading a new slice of the
      archive. See API reference documentation for details. You will meet
      class <code>archive_options_create</code> in order to test an archive,
      compare an archive with filesystem, isolate an archive and repair an archive.
    </p>

    <h3>Listing methods</h3>
    <p>
      There is several ways to read an given archive contents:
    </p>
    <ol>
      <li>
	<p>
	  making use of a callback function that will be called in turn
	  for <u>each entry of the archive</u> even special entries that
	  flag the end of a directory and the next entry will be located in the parent directory:
	</p>
	<code class=block>
	  &nbsp;void <b>op_listing</b>(libdar::archive_listing_callback <b>callback</b>,
	  &nbsp;                void *<b>context</b>,
	  &nbsp;                const libdar::archive_options_listing &amp; <b>options</b>) const;
	</code>
      </li>
      <li>
	<p>
	  using the same callback but only for the different <u>entries of a given directory</u>,
	  directory that has to exist in the archive of course. It returns false
	  when the end of the directory has been reached:
	</p>
	<code class=block>
	  &nbsp;bool <b>get_children_of</b>(libdar::archive_listing_callback <b>callback</b>,
	  &nbsp;                     void *<b>context</b>,
	  &nbsp;                     const std::string &amp; <b>dir</b>,
	  &nbsp;                     bool <b>fetch_ea</b> = false);
	</code>
      </li>
      <li>
	<p>
	  like previous <u>listing a given directory content</u> but returning
	  a vector of objects <b>libdar::list_entry</b> that provide
	  detailed information about each entry, no callback is used here:
	</p>
	<code class=block>
	  &nbsp;const std::vector&lt;libdar::list_entry&gt; <b>get_children_in_table</b>(const std::string &amp; dir,
	  &nbsp;                          bool <b>fetch_ea</b> = false) const;
	</code>
      </li>
    </ol>
    <p>
      <b>For the two first methods</b>
      you have to define a callback function of the following form:
    </p>
    <code class=block>
      &nbsp;void (*)(const std::string &amp; the_path,
      &nbsp;         const list_entry &amp; entry,
      &nbsp;         void *context);
    </code>
    <p>
      This callback will receive as argument the full path of the object,
      a <b>libdar::list_entry</b> object providing
      much details on it <b>and</b> the "context" value passed as argument
      of <b>archive::op_listing()</b> or <b>archive::get_children_of()</b>
    </p>
    <p>
      In the following example we will use only a few methods of
      class <b>libdar::list_entry</b> that are available to get detail
      of a given entry of an archive, feel free to explore this class's
      documentation for to get all details:
    </p>

    <code class=block>
      &nbsp;    // we first create a read-mode archive object that will be used
      &nbsp;    // in the three following examples,
      &nbsp;
      &nbsp;libdar::archive_options_read opt;
      &nbsp;
      &nbsp;opt.set_info_details(true);
      &nbsp;opt.set_execute("echo 'about to read slice %p/%b.%N.%e with context %c'");
      &nbsp;
      &nbsp;libdar::archive <b>my_backup</b>(nullptr, // this is user_interaction we will see further
      &nbsp;                           "/home/me",
      &nbsp;                           "diff_backup",
      &nbsp;                           "dar",
      &nbsp;                           opt);
    </code>
    <br/>
    <code class=block>
      &nbsp;
      &nbsp;    // we will also illustrate here the use of libdar::archive_options_read
      &nbsp;    // inside the callback function we will define here:
      &nbsp;
      &nbsp;void <b>my_listing_callback</b>(const std::string &amp; the_path,
      &nbsp;                                const libdar::list_entry &amp; entry,
      &nbsp;                                void *context)
      &nbsp;{
      &nbsp;    std::cout &lt;&lt; the_path;
      &nbsp;    if(entry.is_dir())
      &nbsp;        std::cout &lt;&lt; " is a directory";
      &nbsp;    std::cout &lt;&lt; " with permission " &lt;&lt; entry.get_perm();
      &nbsp;    std::cout &lt;&lt; " file located in slices " &lt;&lt; entry.get_slices().display();
      &nbsp;    std::cout &lt;&lt; std::endl;
      &nbsp;        // yep, we do not need context, this
      &nbsp;        // is available if you need it though
      &nbsp;
      &nbsp;    if(entry.is_eod())
      &nbsp;    {
      &nbsp;        // only op_listing() provides such type of object
      &nbsp;        // which occurs when we reached the <b>E</b>nd <b>O</b>f <b>D</b>irectory
      &nbsp;        // next entry will be located in the parent directory.
      &nbsp;        //
      &nbsp;        // Note for op_listing: when reading a directory we recurs in it,
      &nbsp;        // meaning that the next entry this callback will be
      &nbsp;        // invoked for will be located in that directory
      &nbsp;        //
      &nbsp;        // for get_children_of() no recursion or eod object is
      &nbsp;        // performed about directory. The next entry following
      &nbsp;        // a directory is still located in the same parent directory
      &nbsp;        // which when fully read stops the get_children_of() routine
      &nbsp;        // at the difference of op_listing() which parse the whole
      &nbsp;        // directory tree.
      &nbsp;        //
      &nbsp;        // For example, reading a empty directory will provide
      &nbsp;        // that directory info, then an eod object a the next
      &nbsp;        // callback invocation.
      &nbsp;    }
      &nbsp;}
    </code>
    <p>
      These two objects <code>my_backup</code> and <code>my_listing_callback()</code>
      we just defined will be used in the following examples.
    </p>

    <h3>Archive listing using archive::op_listing()</h3>

    <p>
      <u>First possibility:</u> we can pass nullptr as callback function to
      archive::op_listing, all will be displayed in stdout
    </p>
    <code class=block>
      &nbsp;<b>my_backup</b>.op_listing(<b>nullptr</b>, // no callback function
      &nbsp;                        nullptr, // we don't use the context here
      &nbsp;                        archive_options_listing()) // and use default listing options
    </code>
    <p>
      <u>Second possibility:</u> we use the callback defined previously:
    </p>
    <code class=block>
      &nbsp;<b>my_backup</b>.op_listing(<b>my_listing_callback</b>,
      &nbsp;                        nullptr, // we still don't use the context here
      &nbsp;                        archive_options_listing()) // and still the default listing options
    </code>
    <p>
      In complement of both previous variant we can of course set non default listing options
    </p>
    <code class=block>
      &nbsp;libdar::archive_options_listing <b>opt</b>;
      &nbsp;
      &nbsp;<b>opt</b>.set_filter_unsaved(true);
      &nbsp;    // skip entry that have not been saved since the archive of reference
      &nbsp;
      &nbsp;<b>opt</b>.set_slice_location(true);
      &nbsp;    // necessary if we want to have slicing information available in the callback function
      &nbsp;
      &nbsp;opt.set_fetch_ea(false);
      &nbsp;    // this is the default. Set it to true if you
      &nbsp;    // want to use list_entry::get_ea_reset_read()/get_ea_next_read()
      &nbsp;
      &nbsp;<b>my_backup</b>.op_listing(my_listing_callback,
      &nbsp;                      nullptr,     // we still don't care of context here
      &nbsp;                      <b>opt</b>); // and still the default listing options
    </code>

    <h3>Archive listing using archive::get_children_of()</h3>

    <code class=block>
      &nbsp;    // With this method we only list one directory
      &nbsp;
      &nbsp;my_backup.<b>get_children_of</b>(my_listing_callback,
      &nbsp;                                 nullptr,   // we still don't care of context here
      &nbsp;                                 <b>"",</b> // we read the root directory of the archive
      &nbsp;                                 true);     // and ask for EA retrieval, but as we do not
      &nbsp;                                            // use list_entry::get_ea_read_next() in the
      &nbsp;                                            // callback this is just wasting CPU and memory
      &nbsp;
      &nbsp;
      &nbsp;    // or course if you have a sub-directory /home/me/.gnupg/private-keys-v1.d
      &nbsp;    // in your home directory and you want to check how it is saved in the
      &nbsp;    // archive, as we defined the root of the backup as /home/me and as you
      &nbsp;    // always have to pass a relative path (no leading /) you could do that by
      &nbsp;    // calling the following:
      &nbsp;
      &nbsp;my_backup.<b>get_children_of</b>(my_listing_callback,
      &nbsp;                         nullptr,
      &nbsp;                         <b>".gnupg/private-keys-v1.d"</b>);
    </code>

    <h3>Archive listing using archive::get_children_in_table()</h3>

    <code class=block>
      &nbsp;    // still listing a single directory but this time without callback function:
      &nbsp;
      &nbsp;my_backup.<b>init_catalogue</b>();
      &nbsp;    // necessary to fill read the whole catalogue in memory
      &nbsp;    // in particular if archive has been opened in sequential read mode
      &nbsp;
      &nbsp;std::vector&lt;libdar::list_entry&gt; result = my_backup.<b>get_children_in_table</b>(".gnupg/private-keys-v1.d");
      &nbsp;
      &nbsp;    // now reading the std::vector
      &nbsp;
      &nbsp;std::vector&lt;libdar::list_entry&gt;::iterator it = result.begin();
      &nbsp;while(it != result.end())
      &nbsp;{
      &nbsp;    if(it-&gt;is_dir())
      &nbsp;        std::cout &lt;&lt; " is a directory";
      &nbsp;    std::cout &lt;&lt; " with permission " &lt;&lt; it-&gt;get_perm();
      &nbsp;    std::cout &lt;&lt; " located in slices " &lt;&lt; it-&gt;get_slices().display();
      &nbsp;    std::cout &lt;&lt; std::endl;
      &nbsp;}
    </code>



    <h2>Testing an archive</h2>

    <p>
      As seen for listing operation
      we assume a archive object has been create in read mode. Testing the
      coherence of the relative archive files on disk is done by calling the <b>libdar::op_test</b> method:
    </p>
    <code class=block>
      &nbsp;libdar::statistics op_test(const libdar::archive_options_test &amp; options,
      &nbsp;                           libdar::statistics * progressive_report);
    </code>
    <p>
      You may have recognized the
      <code>libdar::statistics</code> type we saw for archive creation. It is present as
      argument and the provided libdar::statistics object can be read during
      the whole testing operation by another thread. But if you just want the
      to know the result, you'd better just use the returned value as it
      makes the operation quicker due to the absence of multithread
      management.
    </p>
    <code class=block>
      &nbsp;    // for the exercise, we will change some default options:
      &nbsp;
      &nbsp;archive_options_test <b>opt</b>;
      &nbsp;<b>opt</b>.set_info_details(true); // to have a verbose output
      &nbsp;
      &nbsp;libdar::statistics <b>stats</b>;
      &nbsp;<b>stats</b> = my_backup.<b>op_test</b>(nullptr,    // still the user_interaction we will see further
      &nbsp;                                        <b>opt</b>; // the non default options set above
      &nbsp;                                        nullptr);   // we will just use the returned value
      &nbsp;
      &nbsp;std::cout &lt;&lt; <b>stats</b>.get_treated_str() &lt;&lt; "file(s) tested" &lt;&lt; std::endl;
      &nbsp;std::cout &lt;&lt; <b>stats</b>.get_errored_str() &lt;&lt; " file(s) with errors" &lt;&lt; std::endl;
      &nbsp;std::cout &lt;&lt; <b>stats</b>.get_ea_treated_str() &lt;&lt; " Extended Attributes tested" &lt;&lt; std::endl;
    </code>



    <h2>Comparing an archive</h2>

    <p>
      As simple as previously, but using the <b>archive::op_diff</b> method:
    </p>
    <code class=block>
      &nbsp;statistics op_diff(const path &amp; fs_root,
      &nbsp;                   const archive_options_diff &amp; options,
      &nbsp;                   statistics * progressive_report);
    </code>
    <br>
    <p>
      Over the type of the option
      field, you see the <b>fs_root</b> argument
      which define which directory of the filesystem to compare the archive to
    </p>

    <code class=block>
      &nbsp;    // for the exercise, we will change some default options:
      &nbsp;
      &nbsp;archive_options_diff <b>opt</b>;
      &nbsp;<b>opt</b>.set_info_details(true);   // to have a verbose output
      &nbsp;
      &nbsp;<b>opt</b>.set_what_to_check(libdar::comparison_fields::ignore_owner);
      &nbsp;    // this option above will consider equal two files which
      &nbsp;    // only change due to user or group ownership difference
      &nbsp;    // by default any difference will be considered a difference
      &nbsp;
      &nbsp;(void)my_backup.<b>op_diff</b>(<b>"/home/me"</b>,
      &nbsp;                               <b>opt</b>; // the non default options set above
      &nbsp;                               nullptr); // not using it for this example
    </code>



    <h2>Isolating an archive</h2>
    <p>
      Still as simple as previously, but
      using the <b>archive::op_isolate </b>method:
    </p>
    <code class=block>
      &nbsp;void op_isolate(const path &amp;sauv_path,
      &nbsp;                const std::string &amp; filename,
      &nbsp;                const std::string &amp; extension,
      &nbsp;                const archive_options_isolate &amp; options);
    </code>

    <p>
      You will find similitude with the archive creation though here this is not a constructor
    </p>
    <ul>
      <li>
	<b>sauv_path </b>is the directory where to create the isolated version of the current archive
      </li>
      <li><b>filename</b> is the archive basename to create</li>
      <li><b>extension</b> should still be "dar" here too</li>
      <li>
	<b>options</b> are options for isolation like slicing, compression,
	encryption similar to the archive_options_create class we saw at
	the beginning of this tutorial
      </li>
    </ul>

    <code class=block>
      &nbsp;    // for the exercise, we will change some default options:
      &nbsp;
      &nbsp;archive_options_isolate <b>opt</b>;
      &nbsp;<b>opt</b>.set_warn_over(false);
      &nbsp;
      &nbsp;    // by default overwriting is allowed by a warning is issued first
      &nbsp;    // here overwriting will take place without warning
      &nbsp;
      &nbsp;<b>opt</b>.set_compression(libdar::compression::gzip);
      &nbsp;<b>opt</b>.set_compression_level(9);
      &nbsp;    // this is the default
      &nbsp;<b>opt</b>.set_min_compr_size(10240);
      &nbsp;    // not trying compressing file smaller than 10 kiB
      &nbsp;
      &nbsp;my_backup.<b>op_isolate</b>("/tmp",
      &nbsp;                     "CAT_diff_backup",
      &nbsp;                     "dar",
      &nbsp;                     <b>opt</b>); // the non default options set above
      &nbsp;
      &nbsp;    // have you noted? There is no libdar statistics field returned nor as argument.
    </code>



    <h2>Restoring files from an archive</h2>

    <p>
      Quite as simple as previously, here we use the <b>archive::op_extract</b>method:
    </p>
    <code class=block>
      &nbsp;statistics op_extract(const path &amp; fs_root,
      &nbsp;                      const archive_options_extract &amp; options,
      &nbsp;                      statistics *progressive_report);
    </code>

    <p>
      <ul>
	<li><b>fs_root</b> is the directory under which to restore the files and directory</li>
	<li><b>options</b> defines how and what to restore</li>
	<li><b>progressive_report</b> has already been seen several time previously</li>
      </ul>
    </p>

    <code class=block>
      &nbsp;    // as we still do not have seen masks, we will restore all files contained in the backup<br>
      &nbsp;    // such mask would be provided to the <br>
      &nbsp;    // archive_options_extract::set_selection() and/or <br>
      &nbsp;    // to the archive_options_extract::set_subtree() methods<br>
      &nbsp;    // to precisely define what files to restore<br>
      &nbsp;
      &nbsp;archive_options_extract <b>opt</b>;
      &nbsp;<b>opt</b>.set_dirty_behavior(false, false); // dirty files are not restored
      &nbsp;
      &nbsp;(void) my_backup.<b>op_extract</b>("/home/me/my_home_copy",
      &nbsp;                                   <b>opt</b>,
      &nbsp;                                   nullptr); // we have seen previously how to use statistics
    </code>


    <h2>Merging archives</h2>
    <p>
      Here we will need two archive objects open in read-mode and we will invoke a
      specific archive constructor passing these two objects as argument,
      once the constructor will have completed the merging operation will be
      done.
    </p>
    <code class=block>
      &nbsp;archive(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog,
      &nbsp;        const path &amp; sauv_path,
      &nbsp;        std::shared_ptr&lt;archive&gt; ref_arch1,
      &nbsp;        const std::string &amp; filename,
      &nbsp;        const std::string &amp; extension,
      &nbsp;        const archive_options_merge &amp; options,
      &nbsp;        statistics * progressive_report);
    </code>
    <p>
      <ul>
	<li><b>dialog</b> is will still be set to null pointer for now</li>
	<li><b>sauv_path</b> is the directory where to create the resulting merging archive</li>
	<li>
	  <b>ref_arch1</b> is the first (and mandatory) archive,
	  the second is optional and may be given to the <b>options</B> argument
	</li>>
	<li><b>filename</b> is the resulting archive basename</li>
	<li><b>extension</b> as always should be set to "dar"</li>
	<li><b>options</b> is a set of optional parameters</li>
	<li>
	  <b>progressive_report</b> is as seen above the ability
	  to have another thread showing progression info during the operation
	</li>
      </ul>
    </p>
    <code class=block>
      &nbsp;    // assuming you have two backups:
      &nbsp;    // the first is /tmp/home_backup.*.dar
      &nbsp;    // the second is /var/tmp/system_backup.*.dar
      &nbsp;    // we will create /tmp/merged.*.dar as result of the merging
      &nbsp;    // of these two backups
      &nbsp;
      &nbsp;    // 1 - first things first: opening the first backup
      &nbsp;
      &nbsp;libdar::archive_options_read <b>opt</b>;
      &nbsp;
      &nbsp;<b>opt</b>.set_info_details(true);
      &nbsp;<b>opt</b>.set_execute("echo 'about to read slice %p/%b.%N.%e with context %c'");
      &nbsp;std::shared_ptr&lt;libdar::archive&gt; <b>home_backup</b>(<b>new</b> libdar::archive(nullptr, // this is user_interaction we'll see further
      &nbsp;                                                                 "/tmp",
      &nbsp;                                                                 "home_backup",
      &nbsp;                                                                 "dar",
      &nbsp;                                                                 <b>opt</b>));
      &nbsp;
      &nbsp;    // 2 - opening the second backup
      &nbsp;
      &nbsp;std::shared_ptr&lt;libdar::archive&gt; <b>system_backup</b>(<b>new</b> libdar::archive(nullptr,
      &nbsp;                                                                   "/var/tmp",
      &nbsp;                                                                   "system_backup",
      &nbsp;                                                                   "dar",
      &nbsp;                                                                   <b>opt</b>);
      &nbsp;
      &nbsp;    // 3 - setting up the options for merging operation
      &nbsp;
      &nbsp;libdar::archive_options_merge <b>opt_merge</b>;
      &nbsp;
      &nbsp;opt_merge.set_auxiliary_ref(<b>system_backup</b>);
      &nbsp;    // while merging the second backup is optional, where from the use of option for it
      &nbsp;opt_merge.set_slicing(1048576, 0); // all slice would have 1 MiB at most
      &nbsp;opt_merge.set_compression(libdar::compression::bzip2);
      &nbsp;opt_merge.set_keep_compressed(true);
      &nbsp;opt_merge.set_user_comment("archive resulting of the merging of home_backup and system_backup");
      &nbsp;opt_merge.set_hash_algo(libdar::hash_algo::sha512); // will generate on-fly hash file for each slice
      &nbsp;
      &nbsp;    // 4 - now performing the merging operation<br>
      &nbsp;
      &nbsp;libdar::archive <b>merged</b>(nullptr, // still the user_interaction we will see further
      &nbsp;                       "/tmp",
      &nbsp;                       <b>home_backup</b>, // first back is mandatory, not part of options
      &nbsp;                       "merged",
      &nbsp;                       "dar",
      &nbsp;                       <b>opt_merge</b>,
      &nbsp;                       nullptr); // progressive_report, we don't use here
    </code>



    <h2>Decremental backup</h2>

    <p>
      Decremental backup is an operation that, from two full backups, an old and a recent
      one, creates a backward differential backup corresponding to the old
      full backup, which difference is based on the new full backup. In other words, instead of
      keeping two full backups, you can keep the latest and replace the
      oldest by its decremental counterpart. This will save you space while
      letting you restore as if you had the old full backup by restoring
      first the recent (full) backup then the decremental backup.
    </p>
    <p>
      Creating a decremental backup is exactly the same as creating a merging
      backup, you need just to set the
      <code>archive_options_merge::set_decremental_mode()</code> before proceeding to the
      merging. To avoid duplication we will just illustrate the last step of
      the previous operation modified for decremental backup:
    </p>

    <code class=block>
      &nbsp;    // creating the two read-only backup as for merging operation
      &nbsp;    // the only difference is that here both backups are mandatory
      &nbsp;std::shared_ptr&lt;libdar::archive&gt; <b>old_full_backup</b>(...); // not detailing this part
      &nbsp;std::shared_ptr&lt;libdar::archive&gt; <b>new_full_backup</b>(...); // not detailing this part
      &nbsp;
      &nbsp;    // setting up the options for a decremental operation
      &nbsp;libdar::archive_options_merge <b>opt_merge</b>;
      &nbsp;
      &nbsp;opt_merge.<b>set_decremental_mode</b>(true);
      &nbsp;opt_merge.set_auxiliary_ref(<b>new_full_backup</b>);
      &nbsp;
      &nbsp;    // now performing the merging operation (here decremental backup)
      &nbsp;
      &nbsp;libdar::archive merged(nullptr, // still the user_interaction we will see further
      &nbsp;                       "/tmp",
      &nbsp;                       <b>old_full_backup</b>,
      &nbsp;                       "decremental_backup",
      &nbsp;                       "dar",
      &nbsp;                       <b>opt_merge</b>,
      &nbsp;                       nullptr); // progressive_report we don't use here
    </code>


    <h2>Archive repairing</h2>
    <p>
      If an archive has been truncated due to lack of disk space and if
      sequential marks (aka tape marks) had not been disable, it is possible
      to rebuild sane archive beside this truncated one.
    </p>
    <p>
      We just need to invoke a <b>specific libdar::archive constructor</b>
      which form follows:
    </p>
    <code class=block>
      &nbsp;archive(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog,
      &nbsp;        const path &amp; chem_src,
      &nbsp;        const std::string &amp; basename_src,
      &nbsp;        const std::string &amp; extension_src,
      &nbsp;        const archive_options_read &amp; options_read,
      &nbsp;        const path &amp; chem_dst,
      &nbsp;        const std::string &amp; basename_dst,
      &nbsp;        const std::string &amp; extension_dst,
      &nbsp;        const archive_options_repair &amp; options_repair);
    </code>
    <p>
      You should now be familiarized with the different types and variable
      uses. As you can note, this constructor takes in charge the work to
      read the damaged archive because if the archive is corrupted a normal
      constructor would fail, so you won't have to do it first. As always,
      this constructor will end only once the operation will have completed,
      that's to say at the end of the reparing.
    </p>

    <code class=block>
      &nbsp;    // assuming the archive /tmp/home_backup.*.dar is damaged
      &nbsp;    // and you want to have repaired archive as /tmp/home_backup_repaired.*.dar
      &nbsp;
      &nbsp;libdar::archive repaired(nullptr, // still the user_interaction we have not yet seen
      &nbsp;                         "/tmp"
      &nbsp;                         "home_backup",
      &nbsp;                         "dar",
      &nbsp;                          <b>archive_options_read()</b>,
      &nbsp;                         "/tmp",
      &nbsp;                         "home_backup_repaired",
      &nbsp;                         "dar",
      &nbsp;                         <b>archive_options_repair()</b>);
      &nbsp;
      &nbsp;    // we have not done fancy things with the two option classes, but we did above
      &nbsp;    // enough time for you get all the necessary information from the API reference
      &nbsp;    // documentation
    </code>


    <h2>Looking at some details</h2>

    <p>
      we have covered the different operations the class <code>libdar::archive</code>
      can be used for, still remains some concepts to view:
    </p>
    <ul>
      <li>user_interaction</li>
      <li>masks</li>
      <li>how to cleanly interrupt an running libdar routine</li>
      <li>how to known which compile-time feature has been activated</li>
    </ul>
    <p>
      Then we will see the three other more simple classes:
    </p>
    <ul>
      <li>class database</li>
      <li>class libdar_slave</li>
      <li>class libdar_xform</li>
    </ul>
    <p>
      This will be the subject of the following chapters, but for now,
      maybe you remember that we had to initialize libdar before use,
      by calling <code>libdar::get_version()</code>?
      This routine also exists with arguments that will provide as
      its name suggests the libdar version:
    </p>
    <code class=block>
      void get_version(U_I &amp; major, U_I &amp; medium, U_I &amp; minor, bool init_libgcrypt = true);
    </code>
    <p>
      It is advised to use this form to fetch the libdar version major,
      medium and minor numbers to be sure the library
      you've dynamically linked with is compatible with the features you will
      be using:
    </p>
    <ul>
      <li>
	The <b>major</b> number must be the same, because no compatibility is
	assured between two libdar versions of different major numbers.
      </li>
      <li>
	While run-time compatibility is assured between <b>medium</b> numbers,
	the medium number must be greater or equal to the one used at
	compilation time to be sure that all the features you want are
	available in the libdar library you dynamically linked with.
      </li>
      <li>
	Changes between <b>minor</b> versions correspond to bug fixes and
	does not to imply any API change, thus no constraints is present
	there (just note the presence of more bugs in lower numbers).
      </li>
    </ul>
    <p>
      <b>If you use libgcrypt beside libdar</b> in your application you should
      initialize libgcrypt and not let it be done by libdar the latest
      argument of this form should be set to false in that case, according to the
      <a href="https://www.gnupg.org/documentation/manuals/gcrypt/Initializing-the-library.html#Initializing-the-library">libgcrypt documentation</a>
      which indicates that <i>libgcrypt</i> should normally (always) be initialized directly
      from the application not from an intermediate library.
    </p>
    <p>
      Follows an example of test that can be performed while initializing libdar:
    </p>
    <code class=block>
      &nbsp;U_I major, medium, minor;
      &nbsp;
      &nbsp;libdar::get_version(major, medium, minor);
      &nbsp;
      &nbsp;if(maj != libdar::LIBDAR_COMPILE_TIME_MAJOR ||
      &nbsp;   med &lt; libdar::LIBDAR_COMPILE_TIME_MEDIUM)
      &nbsp;{
      &nbsp;    std::cout &lt;&lt; "libdar version we link with is too old for this code" &lt;&lt; std::endl;
      &nbsp;        // throw an exception or anything else appropriate to that condition:
      &nbsp;    throw "something";
      &nbsp;}
    </code>
    <br/>

    <h2>Checking compile-time features activation</h2>
    <p>
      Once we have called one of the <code>get_version*</code>
      function it is possible to access the list of features activated at
      compilation time thanks to a set of function located in the
      <code>compile_time</code> nested namespace inside libdar:
    </p>

    <code class=block>
      &nbsp;void my_sample_function()
      &nbsp;{
      &nbsp;    bool ea = libdar::compile_time::ea();
      &nbsp;    bool largefile = libdar::compile_time::largefile();
      &nbsp;    bool nodump = libdar::compile_time::nodump();
      &nbsp;    bool special_alloc = libdar::compile_time::special_alloc();
      &nbsp;    U_I bits = libdar::compile_time::bits();
      &nbsp;        // bits is equal to zero for infinint,
      &nbsp;        // else it is equal to 32 or 64 depending on
      &nbsp;        // the compilation mode used.
      &nbsp;
      &nbsp;    bool thread = libdar::compile_time::thread_safe();
      &nbsp;    bool libz = libdar::compile_time::libz();
      &nbsp;    bool libbz2 = libdar::compile_time::libbz2();
      &nbsp;    bool liblzo = libdar::compile_time::liblzo();
      &nbsp;    bool libxz = libdar::compile_time::libxz();
      &nbsp;    bool libcrypto = libdar::compile_time::libgcrypt();
      &nbsp;    bool furtive_read = libdar::compile_time::furtive_read();
      &nbsp;        // for details see the compile_time namespace in the API reference documentation
      &nbsp;}
    </code>

    <h2>User Interaction</h2>
    <p>
      we have seen <code>std::shared_pointer</code> on class <b>libdar::user_interaction</b>
      previously but did not used this feature.
    </p>

    <h3>Defining your own user_interaction class</h3>
    <p>
      class <b>libdar::user_interaction</b>
      defines the way libdar interact with the user during an operation, like
      an archive creation, restoration, testing and so on. Only four types of
      interaction are used by libdar:
    </p>

    <code class=block>
      void <b>message</b>(const std::string &amp; message);
      void <b>pause</b>(const std::string &amp; message);
      std::string <b>get_string</b>(const std::string &amp; message, bool echo);
      secu_string <b>get_secu_string</b>(const std::string &amp; message, bool echo);
    </code>
    <p>
      By default an inherited class of <code>libdar::user_interaction</code>, called
      <code><b>libdar::shell_interaction</b></code>, is used and implements these
      four type of exchange by mean of text terminal:
    </p>
    <ul>
      <li><b>message()</b> sends the std::string provided by libdar to stdout</li>
      <li><b>pause()</b> does the same and ask for the user to press either return or escape to answer yes or no</li>
      <li><b>get_string()</b> reads a string from stdin</li>
      <li><b>get_secu_string()</b> reads a string into a secu_string object from stdin too<br>
      </li>
    </ul>
    <p>
      For a GUI you will probably not want stdin and stdout to be used.
      Instead of that you have the possibility to implement your own inherited class
      from user_interaction. This one should look like the following:
    </p>

    <code class=block>
      &nbsp;class my_user_interaction: public libdar::user_interaction
      &nbsp;{
      &nbsp;    protected:
      &nbsp;            // display of informational message
      &nbsp;        virtual void <b>inherited_message</b>(const std::string &amp; message) override;
      &nbsp;
      &nbsp;            // display of a question and returns the answer from user as true/false
      &nbsp;        virtual bool <b>inherited_pause</b>(const std::string &amp; message) override;
      &nbsp;
      &nbsp;            // display the message and returns a string from the user,
      &nbsp;            // with or without display what the user typed (echo)
      &nbsp;        virtual std::string <b>inherited_get_string</b>(const std::string &amp; message, bool echo) override;
      &nbsp;
      &nbsp;            // same as the previous be the user provided string is returned as secu_string
      &nbsp;        virtual libdar::secu_string <b>inherited_get_secu_string</b>(const std::string &amp; message, bool echo) override;
      &nbsp;};
    </code>

    <h3>Relying on the pre-defined user_interaction_callback class</h3>

    <p>
      As an alternative to defining
      your own inherited class from <code>libdar::user_interaction</code>,
      libdar provides a class called <code>user_interaction_callback</code>
      which is an implementation of the user interaction, based on callback
      functions.
    </p>
    <p>
      You will need to implement four callback functions:
    </p>
    <code class=block>
      using <b>message_callback</b> = void (*)(const std::string &amp;x, void *context);
      using <b>pause_callback</b> = bool (*)(const std::string &amp;x, void *context);
      using <b>get_string_callback</b> = std::string (*)(const std::string &amp;x, bool echo, void *context);
      using <b>get_secu_string_callback</b> = secu_string (*)(const std::string &amp; x, bool echo, void *context);
    </code>
    <p>
      Then you can create an libdar::user_interaction_callback object using this constructor:
    </p>
    <code class=block>
      &nbsp;user_interaction_callback(<b>message_callback</b> x_message_callback,
      &nbsp;                          <b>pause_callback</b> x_answer_callback,
      &nbsp;                          <b>get_string_callback</b> x_string_callback,
      &nbsp;                          <b>get_secu_string_callback</b> x_secu_string_callback,
      &nbsp;                          void *context_value);
    </code>
    <p>
      Here follows an example of use:
    </p>

    <code class=block>
      &nbsp;void <b>my_message_cb</b>(const std::string &amp; x, void *context)
      &nbsp;{
      &nbsp;    std::cout &lt;&lt; x &lt;&lt; std::endl;
      &nbsp;}
      &nbsp;
      &nbsp;bool void <b>my_pause_cb</b>(const std::string &amp; x, void *context)
      &nbsp;{
      &nbsp;    char a;
      &nbsp;
      &nbsp;    std::cout &lt;&lt; x &lt;&lt; endl;
      &nbsp;    std::cin &gt;&gt; a;
      &nbsp;    return a == 'y';
      &nbsp;}
      &nbsp;
      &nbsp;std::string <b>my_string_cb</b>(const std::string &amp; x, bool echo, void *context)
      &nbsp;{
      &nbsp;    // to be defined
      &nbsp;}
      &nbsp;
      &nbsp;libdar::secu_string <b>my_secu_string_cb</b>(const std::string &amp; x, bool echo, void *context)
      &nbsp;{
      &nbsp;    // to be defined
      &nbsp;}
      &nbsp;
      &nbsp;    // eventually using a context_value that will be passed to the callback of the object
      &nbsp;void *context_value = (void *)(&amp; some_datastructure);
      &nbsp;
      &nbsp;std::shared_ptr&lt;libdar::user_interaction&gt; my_user_interaction(new libdar::user_interaction_callback(<b>my_message_cb</b>,
      &nbsp;                                                                                                    <b>my_pause_cb</b>,
      &nbsp;                                                                                                    <b>my_string_cb</b>,
      &nbsp;                                                                                                    <b>my_secu_string_cb</b>,
      &nbsp;                                                                                                    context_value));
    </code>

    <p>
      You can also find the predefined classes <b>libdar::user_interaction_blind</b>
      which always says no in name of the user displays nothing and provide empty strings,
      as well as <b>libdar::shell_interaction_emulator</b>
      which given a user_interaction object send to it the formatted information
      as if it was a shell_interaction object, leading one to emulate libdar
      default behavior under any type of "terminal".
    </p>
    <dl>
      <dt class=void>IMPORTANT</dt><dd>
	all <code>libdar::user_interaction</code> inherited classes
	provided by libdar are not designed to be manipulated by more
	than one thread at a time. The use of <code>std::shared_ptr</code>
	is only here to let the caller not have to manage
	such object and let libdar release it when no more needed <b>or</b>
	to let the caller reuse the same user_interaction object for a
	subsequent call to libdar which would not be possible if a
	<code>std::unique_ptr</code> was used instead.
      </dd>
    </dl>
    <p>
      Now if you design your own <i>user_interaction inherited class</i>
      and provide them mecanism (mutex, ...) that allow them to be used
      simultaneously by several thread there is no issue to pass a such object as
      argument to different libdar object used by different threads running at the
      same time.
    </p>

    <h2>Masks</h2>

    <p>
      Mask are used to define which <u>string</u>
      will be considered and which will not. Libdar implements masks as
      several classes that all inherit from a virtual class named
      <code>libdar::mask</code> that defines the  way masks are used
      (interface class). This class defines the
      <code>bool mask::is_covered(const std::string &amp; expression) const</code> method
      which libdar uses to determine whether a given string matches or
      not a mask and thus whether the corresponding entry (filename, EA, directory path
      depending on the context), is eligible or not for an operation.
    </p>
    <p>
      Strings applied to masks may correspond to filename only, to full path
      or maybe to other things (like Extended Attributes). That's in the
      context where the mask is used that the string meaning take place,
      thing we will see further.
    </p>
    <p>
      There is several different basic masks classes you can use
      to build fairly complex masks, while it is possible you should
      not need to define you own mask classes, if the need arises,
      please contact libdar developer if you thing an additional class
      should take place beside the following ones:
    </p>

    <div class=table>
      <table>
	<tr>
	  <th>
	    class name
	  </th>
	  <th>
	    behavior
	  </th>
	</tr>
	<tr>
	  <td>
	    class libdar::bool_mask
	  </td>
	  <td>
	    boolean mask, either always true
	    or false (depending on the boolean passed
	    at its constructor), it matches either all
	    or none of the submitted strings
	  </td>
	</tr>
	<tr>
	  <td>
	    class libdar::simple_mask
	  </td>
	  <td>
	    matches strings as done by the shell on the command
	    lines (see "man 7 glob")
	  </td>
	</tr>
	<tr>
	  <td>
	    class libdar::regular_mask
	  </td>
	  <td>
	    matches regular expressions (see "man 7 regex")
	  </td>
	</tr>
	<tr>
	  <td>
	    class libdar::not_mask
	  </td>
	  <td>
	    negation of another mask (the mask given
	    at construction time)
	  </td>
	</tr>
	<tr>
	  <td>
	    class libdar::et_mask
	  </td>
	  <td>makes an *AND* operator between
	    two or more masks
	  </td>
	</tr>
	<tr>
	  <td>
	    class libdar::ou_mask
	  </td>
	  <td>
	    makes the *OR* operator between two or more masks
	  </td>
	</tr>
	<tr>
	  <td>
	    class lbdar::simple_path_mask
	  </td>
	  <td>
	    matches whether the string to evaluate
	    is subdirectory of, or is the directory itself
	    that has been given at construction time.
	  </td>
	</tr>
	<tr>
	  <td>
	    class libdar::same_path_mask
	  </td>
	  <td>
	    matches if the string is exactly the
	    given mask (no wild card expression)
	  </td>
	</tr>
	<tr>
	  <td>
	    class libdar::exclude_dir_mask
	  </td>
	  <td>
	    matches if string is the given
	    string or a sub directory of it
	  </td>
	</tr>
	<tr>
	  <td>class libdar::mask_list
	  </td>
	  <td>
	    matches a list of files defined in a given file
	  </td>
	</tr>
      </table>
    </div>

    <p>
      Let's play with some masks:
    </p>
    <code class=block>
      &nbsp;    // all files will be elected by this mask
      &nbsp;libdar::bool_mask m1(true);
      &nbsp;
      &nbsp;    // all string that match the glob expression "A*~" will match.
      &nbsp;    // the second argument of the constructor tell whether the match is case sensitive so here,
      &nbsp;    // any file beginning by 'A' or by 'a' and ending by '~' will be selected by this mask:
      &nbsp;libdar::simple_mask m2(std::string("A*~"), false);
      &nbsp;
      &nbsp;    // m3 is the negation if m2. This mask will thus match
      &nbsp;    // any string that does not begin by 'A' or 'a' or does not finishing by '~'
      &nbsp;libdar::not_mask m3(m2);
      &nbsp;
      &nbsp;    // this mask matches any string that is a subdirectory of "/home/joe"
      &nbsp;    // and any directory that contains /home/joe, meaning
      &nbsp;    // "/", "/home", "/jome/joe" and any subdirectory are matched.
      &nbsp;    // here, the second argument is also case sensitivity (so
      &nbsp;    // "/HoMe" will not be selected by this mask as we set it to "true".
      &nbsp;libdar::simple_path_mask m4 = simple_path_mask("/home/joe",
      &nbsp;                                               true);
      &nbsp;
      &nbsp;    // now let's do some more complex things:
      &nbsp;    // m5 will now match only strings that are selected by both m2 AND m4
      &nbsp;libdar::et_mask m5;
      &nbsp;m5.add_mask(m2);
      &nbsp;m5.add_mask(m4);
      &nbsp;
      &nbsp;    // we can make more interesting things like this, where m5 will select files
      &nbsp;    // that match m2 AND m4 AND m3. But as <i>m3 is not(m2)</i>, m5 will never
      &nbsp;    // match any file... but the idea here is to see the flexibility of use:
      &nbsp;m5.add_mask(m3);
      &nbsp;
      &nbsp;    // but we could do the same with an "ou_mask" and would get a silly
      &nbsp;    // counterpart of m1 (a mask that matches any files)
      &nbsp;libdar::ou_mask m6;
      &nbsp;m6.add_mask(m2);
      &nbsp;m6.add_mask(m4);
      &nbsp;m6.add_mask(m3);
      &nbsp;
      &nbsp;    // lastly, the NOT, AND and OR operation can be used recursively.
      &nbsp;    // Frankly, it's even possible to have masks referring each other!
      &nbsp;libdar::not_mask m7(m6);
      &nbsp;m6.add_mask(m7);
      &nbsp;   // now that's to you to build something that makes sense...
    </code>
    <p>
      The idea here is not to create object manually, but to link their
      creation to the action and choices the user makes from the user
      interface (Graphical User Interface of your application, for example)
    </p>
    <p>
      Now that you've seen the power of these masks, you should know that in
      libdar masks are used at several places:
    </p>
    <ul>
      <li>
	<p>
	  A first place is to select files against their
	  names (without path information) this the argument of the <b>set_selection()</b>
	  method of <code>libdar::archive_options_*</code> classes.
	  The mask here does not apply to directories.
	</p>
      </li>
      <li>
	<p>
	  A second place is to select files against their
	  path+name and it applies here to all type of files including
	  directories, this is the argument of the <b>set_subtree()</b>
	  method of <code>libdar::archive_options_*</code> classes.
	  So with it, you can prune directories, or in any other way restrict the
	  operation to a particular subdirectory, as well as to a particular
	  plain file for example.
	</p>
	<p>
	  <b>Important note:</b> about this second mask, what
	  your own mask will be compared to by libdar is the <b>absolute path</b> of
	  the file under consideration. If you want to exclude <i>/usr/local/bin</i>
	  from the operation whatever is the <code>fs_root</code>
	  value (which correspond the -R option of dar) using here a
	  <code>libdar::simple_mask("/usr/local/bin")</code>
	  as argument of <code>libdar::archive_options_*::get_subtree()</code>
	  will do the trick.
	</p>
      </li>
    </ul>
    <p>
      An exception is the archive testing operation, which has no
      <code>fs_root</code> argument (because the operation is not
      relative to an existing filesystem), however the
      <code>subtree</code> argument exist to receive a mask for
      comparing the path of file to include or exclude from the
      testing operation. In this case the situation is as if the
      <code>fs_root</code> was set to the value "<b>&lt;ROOT&gt;</b>".
      For example, masks will be compared to <code>"&lt;ROOT&gt;/some/file"</code>
      when performing an archive test operation.
    </p>
    <p>
      Instead of using explicit string "&lt;ROOT&gt;" you can use
      <b>libdar::PSEUDO_ROOT</b> predifined std::string variable
    </p>
    <ul>
      <li>
	A third place concerns
	Extended Attributes (EA), this is the argument of the
	<b>set_ea_mask()</b>method of <code>libdar::archive_options_*</code> classes.
	It is applied to the full EA name in the form
	<i>&lt;domain&gt;.&lt;name&gt;</i> where <i>&lt;domain&gt;</i>
	is any string value like but not limited to the usual "user"
	or "system" domains.
      </li>
      <li>
	A fourth place concerns the file to compress or to avoid
	compressing. This is the argument of the <b>set_compr_mask()</b>
	method of <code>libdar::archive_options_*</code>
	classes. it is works the same as
	<code>set_selection()</code> methods seen above,
	based only to filename without any path
	consideration.
      </li>
      <li>
	A fifth place concerns files that need to be prepared for
	backup, this is the argument of the <b>set_backup_hook()</b>
	methods of <code>libdar::archive_option_create</code>
	class. I has to be used the same as
	<i>set_subtree()</i>. For more about this feature see
	the backup-hook feature in dar man page (-&lt;, -&gt; and -= options).
      </li>
    </ul>



    <h2>Aborting an Operation</h2>

    <p>
      If the POSIX thread support is available,
      <i>libdar</i> will be built in a
      thread-safe manner, giving you the possibility to have several threads using libdar
      at the same time (but on different objects except concerning the
      libdar::statistics which can be shared between threads). You may then
      wish to interrupt a given thread. But
      aborting a thread form the outside (like sending it a KILL signal) will
      most of the time let some memory allocated or even worse can lead to
      dead-lock situation, when the killed thread was inside a critical section
      and had not got the opportunity to release a <u>mutex</u>.
      For that reason, libdar proposes a set
      of calls to abort any processing libdar call which is ran by a given
      thread.
    </p>

    <code class=block>
      &nbsp;    // next is the thread ID in which we want to have lidbar call canceled
      &nbsp;    // here for simplicity we don't describe the way the ID has been obtained
      &nbsp;    // but it could be for example the result of a call to pthread_self() as
      &nbsp;    // defined in &lt;pthread.h&gt; system header file
      &nbsp;pthread_t thread_id = 161720;
      &nbsp;
      &nbsp;    // the most simple call is:
      &nbsp;<b>libdar::cancel_thread(thread_id);</b>
      &nbsp;
      &nbsp;    // this will make any libdar call in this thread be canceled immediately
      &nbsp;
      &nbsp;    // but you can use something a bit more interesting:
      &nbsp;<b>libdar::cancel_thread(thread_id, false);</b>
      &nbsp;
      &nbsp;    // this second argument is true for immediate cancellation and can be ommited in
      &nbsp;    // that case. But using false instead leads to a delayed cancellation,
      &nbsp;    // in which case libdar aborts the operation
      &nbsp;    // but produces something usable, espetially if you were performing a backup.
      &nbsp;
      &nbsp;    // You then get a real usable archive which only contains files saved so far, in place
      &nbsp;    // of having a broken archive which misses a catalogue at the end. Note that this
      &nbsp;    // delayed cancellation needs a bit more time to complete, depending on the
      &nbsp;    // size of the archive under process.
    </code>

    <p>
      As seen above, cancellation can be very simple. What now succeeds when
      you ask for a cancellation? Well, an exception of type <code>Ethread_cancel</code>
      is thrown. All along his path, memory is released and mutex are freed.
      Last, the exception appears to the libdar caller. So, you can catch it
      to define a specific comportment. And if you don't want to use
      exceptions a special returned code is used.
    </p>

    <code class=block>
      &nbsp;try
      &nbsp;{
      &nbsp;    libdar::archive my_arch(...);
      &nbsp;    ...
      &nbsp;}
      &nbsp;catch(libdar::Ethread_cancel &amp; e)
      &nbsp;{
      &nbsp;    ... do something specific when thread has been canceled;<br>
      &nbsp;}
    </code>

    <p>
      Some helper routines are available to
      know the cancellation status for a particular thread or to abort a
      cancellation process if it has not yet been engaged.
    </p>

    <code class=block>
      &nbsp;thread_t tid;
      &nbsp;
      &nbsp;    // how to know if the thread <i>tid</i> is under cancellation process?
      &nbsp;if(<b>libdar::cancel_status(tid)</b>)
      &nbsp;    std::cout &lt;&lt; "thread cancellation is under progress for thread : "
      &nbsp;              &lt;&lt; tid &lt;&lt; std::endl;
      &nbsp;else
      &nbsp;    std::cout &lt;&lt; "no thread cancellation is under progress for thread : "
      &nbsp;              &lt;&lt; std::endl;
      &nbsp;
      &nbsp;    // how to cancel a pending thread cancellation ?
      &nbsp;if(<b>libdar::cancel_clear(tid)</b>)
      &nbsp;    std::cout &lt;&lt; "pending thread cancellation has been reset, thread "
      &nbsp;              &lt;&lt; tid &lt;&lt; " has not been canceled"
      &nbsp;              &lt;&lt; std::endl;
      &nbsp;else
      &nbsp;    std::cout &lt;&lt; "too late, could not avoid thread cancellation for thread "
      &nbsp;              &lt;&lt; tid
      &nbsp;              &lt;&lt; std::endl;
    </code>

    <p>
      Last point, back to the <code>libdar::Ethread_cancel</code>
      exception, this class has two methods you may find useful, when you
      catch it:
    </p>

    <code class=block>
      &nbsp;try
      &nbsp;{
      &nbsp;    ... some libdar calls
      &nbsp;}
      &nbsp;catch(libdar::Ethread_cancel &amp; <b>e</b>)
      &nbsp;{
      &nbsp;    if(e.<b>immediate_cancel</b>())
      &nbsp;        std::cout &lt;&lt; "cancel_thread() has been called with \"true\" as second argument"
      &nbsp;                  &lt;&lt; std::endl;
      &nbsp;    else
      &nbsp;        std::cout &lt;&lt; "cancel_thread() has been called with \"false\" as second argument"
      &nbsp;        &lt;&lt; std::endl;
      &nbsp;
      &nbsp;    U64 flag = e.<b>get_flag()</b>;
      &nbsp;    ... do something with the flag variable...
      &nbsp;}
      &nbsp;
      &nbsp;    // what is this flag stored in this exception?<br>
      &nbsp;    // You must consider that the complete definition of cancel_thread() is the following:
      &nbsp;    // <i>void cancel_thread</i>(pthread_t tid, bool immediate = true, U_64 flag = 0);
      &nbsp;    // thus, any argument given in third is passed to the thrown Ethread_cancel exception,
      &nbsp;    // value which can be retrieved thanks to its get_flag() method. The value given to this
      &nbsp;    // flag is not used by libdar itself, it is a facility for user program to have the possibility
      &nbsp;    // to include additional information about the thread cancellation.
      &nbsp;
      &nbsp;    // supposing the thread cancellation has been invoked by:
      &nbsp;<b>libdar::cancel_thread(thread_id, true, 19);</b>
      &nbsp;    // then the <i>flag</i> variable in the catch() statement above would have received
      &nbsp;    // the value <i>19</i>.
    </code>



    <h2>Dar_manager API</h2>

    <p>
      For more about <i>dar_manager</i>, please read the man page where are described in
      detail its available features.
    </p>

    <p>
      To get dar_manager features you need to use the
      <b>class database</b>. Most of the methods of the <i>database</i>
      class make use options. The same as what has been seen with class <i>archive</i>
      a auxiliary class is used to carry these options.
    </p>

    <h3>Database object construction</h3>
    <p>
      Two constructor are available. The first creates a brand-new but empty database in memory:
    </p>
    <code class=block>
      database(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog);
    </code>
    <p>
      As seen for <code>libdar::archive</code> <b>dialog</b> can be set to a null pointer if the
      default interaction mode (stdin/stdout/stderr) suits your need.
    </p>
    <p>
      The second constructor opens an existing database from filesystem and
      stores its contents into memory ready for further use and actions:
    </p>
    <code class=block>
      &nbsp;database(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog,
      &nbsp;         const std::string &amp; base,
      &nbsp;         const <b>database_open_options</b> &amp; opt);
    </code>
    <p>
      <ul>
        <li><b>dialog</b> can be set to a null pointer or can point to an user_interaction object of your own</li>
        <li><b>base</b> is the path and filename of the database to read</li>
        <li>
	  <b>opt</b> is an object containing a few options. As seen with
	  <code>libdar::archive</code> we can use an default temporary object to use default
	  option
	</li>
      </ul>
      Here follows simple examples of use of class <code>database</code>:
    </p>
    <code class=block>
      &nbsp;std::shared_ptr&lt;libdar::user_interaction&gt; ui_ptr; // points to null
      &nbsp;<b>libdar::database</b> base(ui_ptr);
      &nbsp;    // we have created an empty database (no archive in it) called "base"
      &nbsp;
      &nbsp;libdar::database other(ui_ptr, // we can reuse it as it points to nullptr
      &nbsp;                       "/tmp/existing_base.dmd",
      &nbsp;                       libdar::database_open_options());
      &nbsp;    // we have created a database object called "other" which contains
      &nbsp;    // (in RAM) all information that were contained in the
      &nbsp;    // database file "/tmp/existing_base.dmd"
      &nbsp;
      &nbsp;<b>libdar::database_open_option</b> opt;
      &nbsp;opt.set_partial(true);
      &nbsp;opt.set_warn_order(false);
      &nbsp;<b>libdar::database</b> other2(ui_ptr,
      &nbsp;                               "/tmp/existing_base.dmd",
      &nbsp;                               opt);
      &nbsp;
      &nbsp;    // we have created yet another database object called "other2" which differs
      &nbsp;    // from "other" by the option we used. While "other" is a fully loaded
      &nbsp;    // database, "other2" is a partial database. This notion is explained
      &nbsp;    // below
    </code>
    <br/>
    <ul>
      <li>
	<b>database_open_options::set_partial(bool value)</b>
	leads dar to only load the database header into memory, which is
	quicker than loading the full database. But some operation we will see
	bellow need fully loaded database, the other can work with both
      </li>
      <li>
	<b>database_open_options::set_partial_read_only(bool value)</b>
	in addition to have only the header the archive is open in read-only
	mode which of course forbids any modification to the database but is
	even faster than just a partial read-write database. For just database
	listing this is perfectly adapted.
      </li>
      <li>
	<b>database_open_options::set_warn_order(bool value)</b> avoid
	warning about ordering problem between archive
      </li>
    </ul>
    <p>
      In the following we will indicate whether a database operation can be
      applied to a partially loaded database or not. All operation can be
      applied to a fully loaded databse.
    </p>

    <h3>Database's methods</h3>

    <p>
      A database can be open in <b>read-write</b> mode <b>partially loaded (still read-write)</b> mode
      and last in <b>partially loaded read-only mode</b>. All operations are available
      in the first mode, but some are not in the second and even less in the third mode. We will
      detail which one are available in each mode:
    </p>
    <h4>Available in partially loaded read-only mode</h4>
    <ul>
      <li><b>show_contents()</b> : list the archives used to build the database</li>
      <li>
	<b>get_options()</b> : list the options that will be passed to dar (as
	defined with the set_options() method)
      </li>
      <li>
	<b>get_dar_path()</b> : return the path to dar (or empty string if
	relying on the PATH variable)
      </li>
    </ul>

    <h4>Availabler in partially loaded read-write mode</h4>

    <ul>
      <li><b>all methods seen above</b></li>
      <li>
	<b>dump(...)</b> : it is used to write back the database to a file.
      </li>
      <li>
	<b>change_name()</b> : change the basename of the archive which
	index is given in argument
      </li>
      <li>
	<b>set_path()</b> : change the path to the archive which index is
	given in argument
      </li>
      <li>
	<b>set_options()</b>: change the default options to always pass
	to dar when performing restoration
      </li>
      <li>
	<b>set_dar_path()</b> : specify the path to dar (use empty string
	to rely on the PATH variable)
      </li>
    </ul>

    <h4>Available in fully loaded read-write mode</h4>

    <ul>
      <li>
	<b>all methods seen above</b>
      </li>
      <li>
	<b>add_archive()</b> : add an archive to the database
      </li>
      <li>
	<b>remove_archive()</b> : remove an archive from the
	database
      </li>
      <li>
	<b>set_permutation()</b> : change archive relative order within
	the database
      </li>
      <li>
	<b>show_files()</b> : list the files which are present in the
	given archive
      </li>
      <li>
	<b>show_version()</b> : list the archive where the given file is
	saved
      </li>
      <li>
	<b>show_most_recent_stats()</b> : compute statistics about
	the location of most recent file versions
      </li>
      <li>
	<b>restore()</b> : restore a set of given files given in argument.
      </li>
    </ul>
    <p>
      Well, you might now say that as description this is a bit light for a
      tutorial, yes. In fact these call are really very simple to use, you
      can find a complete description in the API reference documentation.
      This documentation is built if doxygen is available and is put
      under doc/html after calling make in the source
      package. It is also available from
      <a href="http://dar.linux.free.fr/html/">dar's homepage</a>.
    </p>

    <h2>Dar_slave API</h2>

    <p>
      <i>dar_slave</i> role is to read an archive while interacting with
      a dar process through a pair of pipes. Dar asks portion of the
      archive or information about the archive in the first pipe from
      dar to dar_slave. And dar_slave sends the requested information
      into the other pipe toward dar (embedded into an expected format).
    </p>
    <p>
      Since API 6.0.x, dar_slave has an API. It is implemented by the class
      libdar::libdar_slave. You need firs to create an object using the
      following constructor:
    </p>
    <code class=block>
      libdar_slave(std::shared_ptr&lt;user_interaction&gt; &amp; dialog,
      const std::string &amp; folder,
      const std::string &amp; basename,
      const std::string &amp; extension,
      bool input_pipe_is_fd,
      const std::string &amp; input_pipe,
      bool output_pipe_is_fd,
      const std::string &amp; output_pipe,
      const std::string &amp; execute,
      const infinint &amp; min_digits);
    </code>
    <br/>
    <ul>
      <li><b>dialog</b> as seen for other libdar classes can be set to a null pointer for interaction on stdin and stdout</li>
      <li><b>folder</b> is the directory where resides the archive to read</li>
      <li><b>basename</b> is the basename of the archive</li>
      <li><b>extension</b> should always be set to "dar"</li>
      <li>
	<b>input_pipe_is_fd</b> if set to true, the next argument is not the path to a named pipe but a
	number corresponding to a file descriptor open open in read mode
      </li>
      <li><b>input_pipe</b> is the path of a named pipe to read from. It can also be an empty string to use stdin as input pipe</li>
      <li
	><b>out_pipe_is_fd</b> if set to true, the next argument is not the path to a named pipe but a
	number corresponding to a file descriptor open in write mode
      </li>
      <li><b>output_pipe </b>is the path of a named pipe to write from. It can also be an empty string to use stdout as input pipe</li>
    </ul>
    <p>
      Once the object is created, you will need to call the
      <b>libdar_slave::run()</b> method which will end when the
      dar process at the other end will no more need of this slave:
    </p>

    <code class=block>
      &nbsp;libdar::libdar_slave slave(nullptr,
      &nbsp;                           "/tmp",
      &nbsp;                           "first_backup",
      &nbsp;                           "dar",
      &nbsp;                           false,
      &nbsp;                           "/tmp/toslave", // assuming this is an existing named pipe
      &nbsp;                           false,
      &nbsp;                           "/tmp/todar",   // assuming this is also an existing named pipe
      &nbsp;                           "echo 'reading slice %p/%b.%N.%e in context %c'",
      &nbsp;                           0);
      &nbsp;
      &nbsp;<b>slave.run();</b>
      &nbsp;
      &nbsp;    // once run() has returned, you can launch it again for another process
      &nbsp;    // it will continue to provide access to the /tmp/first_backup.*.dar archive
    </code>


    <h2>Dar_xform API</h2>

    <p>
      <i>dar_xform</i>
      creates a copy of a given archive modifying its slicing. it does not
      require decompressing nor deciphering the archive to do so. There is
      different constructor depending whether the archive is read from
      filesystem, from a named pipe of from a provided file descriptor
    </p>

    <h3>Reading from a file</h3>

    <code class=block>
      &nbsp;libdar::libdar_xform(const std::shared_ptr&lt;user_interaction&gt; &amp; ui,
      &nbsp;                     const std::string &amp; chem,
      &nbsp;                     const std::string &amp; basename,
      &nbsp;                     const std::string &amp; extension,
      &nbsp;                     const infinint &amp; min_digits,
      &nbsp;                     const std::string &amp; execute);
    </code>
    <br/>
    <ul>
      <li>
	<b>ui</b> as seen so far it can be set to a null pointer for interaction on stdin and stdout
      </li>
      <li><b>chem</b> is the directory where resides the archive to read</li>
      <li><b>basename</b> is the basename of the archive</li><li><b>extension</b> should always be set to "dar"</li>
      <li>
	<b>min_digits</b> is the minimum number of digits slice number in filename
	have been created with (use zero if you don't know what it is)
      </li>
    </ul>

    <h3>Reading from a named pipe</h3>

    <code class=block>
      &nbsp;libdar_xform(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog,
      &nbsp;             const std::string &amp; pipename);
    </code>
    <br/>
    <ul>
      <li><b>dialog</b> as seen for other libdar classes, it can be set to nullptr</li>
      <li><b>pipename</b> complete path to the named pipe to read the archive from</li>
    </ul>

    <h3>Reading from a file descriptor</h3>

    <code class=block>
      &nbsp;libdar_xform(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog,
      &nbsp;             int filedescriptor);
    </code>
    <br/>
    <ul>
      <li><b>dialog</b> same as above</li>
      <li><b>filedescriptor</b> is an read opened file descriptor to read the archive from</li>
    </ul>

    <h3>Creating a single or multi-sliced archive on filesystem</h3>

    <p>
      Once the <code>libdar::libdar_xform</code> object is created it can copy the
      referred archive to another location in another form thanks to one of
      the two <code>libdar_xform::xform_to</code> methods. There is <u>not link</u> between
      the <b>constructor</b> used and the <b>libdar_xform::xform_to</b> flavor used,
      any combination is possible.
    </p>

    <code class=block>
      &nbsp;void xform_to(const std::string &amp; path,
      &nbsp;              const std::string &amp; basename,
      &nbsp;              const std::string &amp; extension,
      &nbsp;              bool allow_over,
      &nbsp;              bool warn_over,
      &nbsp;              const infinint &amp; pause,
      &nbsp;              const infinint &amp; first_slice_size,
      &nbsp;              const infinint &amp; slice_size,
      &nbsp;              const std::string &amp; slice_perm,
      &nbsp;              const std::string &amp; slice_user,
      &nbsp;              const std::string &amp; slice_group,
      &nbsp;              libdar::hash_algo hash,
      &nbsp;              const libdar::infinint &amp; min_digits,
      &nbsp;              const std::string &amp; execute);
    </code>

    <h3>Creating a single sliced archive toward a filedescriptor</h3>

    <code class=block>
      &nbsp;void xform_to(int filedescriptor,
      &nbsp;              const std::string &amp; execute);
    </code>
    <p>
      Here follows an example of use. We will convert a possibly multi-sliced
      archive to a single slice one, generating a sha512 hash file on-fly.
    </p>

    <code class=block>
      &nbsp;std::shared_ptr&lt;libdar::user_interaction&gt; ui_ptr; // points to null
      &nbsp;libdar::libdar_xform transform(ui_ptr,
      &nbsp;                               "/tmp",
      &nbsp;                               "my_first_archive",
      &nbsp;                               "dar",
      &nbsp;                               0,
      &nbsp;                               "echo 'reading slice %p/%b.%N.%e context is %c'");
      &nbsp;
      &nbsp;transform.xform_to("/tmp",
      &nbsp;                   "my_other_first_archive",
      &nbsp;                   "dar",
      &nbsp;                   false, // no overwriting allowed
      &nbsp;                   true,  // does not matter whether we warn or not as we do not allow overwriting
      &nbsp;                   0,     // no pause between slices
      &nbsp;                   0,     // no specific first slice
      &nbsp;                   0,     // no slicing at all (previous argument is thus not used anyway in that case)
      &nbsp;                   "",    // using default permission for created slices
      &nbsp;                   "",    // using default user ownership for created slices
      &nbsp;                   "",    // using default group ownership for created slices
      &nbsp;                   libdar::hash_algo::sha512, // the hash algo to use (for no hashing use hash_none instead)
      &nbsp;                   0,     // min_digits ... not using this feature here where from we use "0"
      &nbsp;                   "echo 'Slice %p/%b.%N.%e has been written. Context is %c'");
    </code>


    <h2>Compilation &amp; Linking</h2>

    <h3>Compilation</h3>
    <p>
      All the symbols found in the libdar API
      defined from <b>&lt;dar/libdar.h&gt;</b>.
      So you should only need to include this header.
      If the header file is not located in a standard directory,
      in order to compile your code, you may need some extra
      flags to pass to the compiler (like -I/opt/...).
      The <b>pkg-config</b> tool can help here to
      avoid system dependent invocation:
    </p>
    <code class=block>
      <i>&nbsp;shell prompt &gt;</i> <b>cat my_prog.cpp</b>
      &nbsp;
      &nbsp;#include &lt;dar/libdar.h&gt;
      &nbsp;
      &nbsp;main()
      &nbsp;{
      &nbsp;    libdar::get_version(...);
      &nbsp;    ...
      &nbsp;}
      &nbsp;
      <i>&nbsp;shell prompt &gt;</i> <b>gcc <e>`pkg-config --cflags libdar`</e> -c my_prog.cpp</b>
    </code>

    <h3>Linking</h3>

    <p>
      Of course, you need to link your program with libdar. This is done by
      adding <b>-ldar</b> plus other library libdar can rely on like libz,
      libbzip2, liblzo or libgcrypt, depending on the feature activated at
      compilation time. Here too, <b>pkg-config</b> can provide a
      great help to avoid having system dependent invocation:
    </p>

    <code class=block>
      <i>shell prompt &gt;</i> <b>gcc <e>pkg-confg --libs libdar`</e> my_prog.o -o my_prog</b>
    </code>

    <h3>Libdar's different flavors</h3>


    <p>
      The compilation and linking
      steps described above assume you
      have a "<b>full</b>" libdar library.
      but beside the <i>full</i> (alias <i>infinint</i>)
      libdar flavor, libdar also comes in <b>32</B> and <b>64</b> bits
      versions. In these last ones, in place of internally relying on a
      special type (which is a C++ class called<i> infinint</i>)
      to handle arbitrary large integers, <b>libdar32</b> relies on 32 bits integers
      and <b>libdar64</b> relies on 64 bits integers (there are limitations which are
      described in doc/LIMITATIONS). But all these libdar version (infinint,
      32bits, 64bits) have the same interface and must be used the same way,
      except for compilation and linking:
    </p>
    <p>
      These different libdar versions can
      coexist on the same system, they
      share the same include files. But the <b>LIBDAR_MODE</b> macro must be set to
      32 or 64 when compiling or linking with libdar32 or libdar64
      respectively, this macro changes the way the libdar headers
      files are interpreted by the compiler.
      <b>pkg-config --cflags</b> will set the
      correct LIBDAR_MODE, so you should only bother calling it with either
      libdar, libdar32 or libdar64 depending on your need:
      <code>"<b>pkg-confg --cflags libdar<e>64</e></b>"</code> for example.
    </p>

    <code class=block>
      <i>shell prompt &gt;</i> <b>cat my_prog.cpp</b>
      #include &lt;dar/libdar.h&gt;

      main()
      {
      &nbsp; libdar::get_version(...);
      &nbsp; ...
      }

      <i>shell prompt &gt;</i> <b>gcc -c `pkg-config --cflags libdar<e>64</e>` my_prog.cpp</b>
      <i>shell prompt &gt;</i> <b>gcc `pkg-config --libs libdar<e>64</e>` my_prog.o -o my_prog</b>>
    </code>
    <p>
      and replace 64 by 32 to link with libdar32.
    </p>
  </body>
</html>