File: api_tutorial.html

package info (click to toggle)
dar 2.4.5.debian.1-1
links: PTS
area: main
in suites: wheezy
size: 10,608 kB
sloc: cpp: 50,637; sh: 12,281; ansic: 836; xml: 694; makefile: 369; csh: 104; perl: 43; sed: 16
file content (3117 lines) | stat: -rw-r--r-- 139,067 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>Libdar API - Tutorial</title>











  <meta content="Denis Corbin" name="author">
  <meta content="Tutorial for using libdar library" name="description"></head><body style="background-color: rgb(221, 221, 221); color: rgb(0, 0, 170);" alink="#ff0000" link="#0000ff" vlink="#000055">
<center>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; width: 161px;"><a href="index.html"><img style="border: 0px solid ; width: 160px; height: 120px;" alt="Dar Documentation" src="dar_s_doc.jpg"></a><br>
      </td>
      <td style="vertical-align: top;">
      <h1 style="text-align: center;"> LIBDAR <br>
      </h1>
      <h1 style="text-align: center;">APPLICATION INTERFACE <br>
      </h1>
      <h1 style="text-align: center;">TUTORIAL</h1>
      <div style="text-align: center;"> for API version 5.x.x<br>
      </div>
      <h1 style="text-align: center;"> </h1>
      </td>
    </tr>
  </tbody>
</table>
<div style="text-align: center;"><br>
</div>
<hr style="width: 100%; height: 2px;"><br>
<table style="width: 90%; margin-right: auto; margin-left: auto; text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h2>Presentation</h2>
      <p style="text-align: justify;">The Libdar library has been built
from source code originally
located directly in the <em><strong>dar</strong></em> command line
application. Libdar provides a complete abstraction layer for handling Disk
ARchive (<em>dar</em>)'s archives. The general operations provided are:</p>
      <div style="text-align: justify;"></div>
      <div></div>
      <ul style="text-align: justify;">
        <li>archive creation, </li>
        <li>file extraction, </li>
        <li>archive listing, </li>
        <li>archive testing, </li>
        <li>archive comparison,</li>
        <li>catalogue isolation</li>
        <li>archive merging</li>
        <li>dar_manager database manipulations<br>
        </li>
      </ul>
      <div style="text-align: justify;"></div>
Note that <span style="font-style: italic;">Disk ARchive</span> <em>and</em>
libdar
have been released under the <span style="font-style: italic;">Gnu
General Public License </span>(GPL). All code linked to libdar
(statically or dynamically), <span style="font-weight: bold;"> must
also be covered by the GPL.</span><br>
      <div style="text-align: justify;"> <br>
      </div>
This tutorial will show you how to
use the libdar API. As <span style="font-style: italic;">dar</span> since its release 2.0.0 also uses this API, looking at it's code may also provide a good
illustration. The file <span style="font-style: italic;">src/dar_suite/dar.cpp</span>
is the primary consumer of the libdar API. <br>
      <div style="text-align: justify;"> <br>
The sample codes provided here is
solely illustrative and is not guaranteed to compile. More detailed API
documentation is contained in the source code and can be compiled to
the doc/html directory using Doxygen, which is also provided <a href="http://dar.linux.free.fr/doc/html/index.html">online</a>.<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<hr style="width: 100%; height: 2px;"><br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h2>Let's Start</h2>
      <h3>Conventions</h3>
      <h4>Language</h4>
      <div style="text-align: justify;">Dar and libdar are written in
C++, and so is the libdar API. While
written in C++, libdar is easily usable by both C and C++ code.
Access from other languages can be provided by specific bindings. I
would only say that you are welcome to provide the necessary bindings
yourself. :-) </div>
      <h4>Libdar namespace</h4>
All libdar symbols are defined under
the <span style="font-style: italic; font-weight: bold;">libdar </span><span style="font-weight: bold;">namespace</span>. You
can either add the <span style="font-style: italic;">using namespace
libdar;</span> line at the beginning of your source files: </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code>using
namespace libdar;<br>
      </code><br>
      <code>get_version(....);<br>
      </code></td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: justify;">&nbsp;or,
as shown below, you can
explicitly use the namespace in front of libdar objects : </td>
    </tr>
  </tbody>
</table>
<br>
<code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code><br>
libdar::get_version(....);<br>
      </code></td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h4>Exceptions or no Exceptions</h4>
      <div style="text-align: justify;">The library can be used with or
without <span style="font-style: italic;">exceptions.</span> For each example we will see a sample code for both ways. To the left is with exceptions, to the right without:<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code><br>
example
code <span style="font-weight: bold;">using exceptions</span><br>
      <br>
      </code> </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code><br>
example
code <span style="font-weight: bold;">not using</span> exceptions</code><br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: justify;">All
exceptions used by <span style="font-style: italic;">libdar</span>
inherit from the pure virtual <span style="font-style: italic;"><span style="font-weight: bold;">class Egeneric</span>.</span> The only
method you will need to know about for any exception is the <span style="font-style: italic; font-weight: bold;">get_message()</span>
call, which returns a message string describing the message (in human
language). The type of the error is defined by the class of the
exception. The possible exception types follow: </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; width: 200px;"><code>class
libdar::Egeneric<br>
      </code></td>
      <td style="vertical-align: top;"> the parent class of all
exceptions (a pure virtual class)<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Ememory<br>
      </code></td>
      <td style="vertical-align: top;">memory has been exhausted<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Ebug<br>
      </code></td>
      <td style="vertical-align: top;">signals a bug, which is
triggered when reaching some code that should never be executed<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Einfinint<br>
      </code></td>
      <td style="vertical-align: top;">arithmetic error detected when
operating on infinint<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Elimitint<br>
      </code></td>
      <td style="vertical-align: top;">a limitint overflow is detected,
indicating the maximum value of the limitint has been exceeded<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Erange<br>
      </code></td>
      <td style="vertical-align: top;">signals a range error<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Edeci<br>
      </code></td>
      <td style="vertical-align: top;">signals conversion problem
between infinint and string (decimal representation)<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Efeature<br>
      </code></td>
      <td style="vertical-align: top;">a requested feature is not (yet)
implemented<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Ehardware<br>
      </code></td>
      <td style="vertical-align: top;">hardware problem is found <br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Euser_abort<br>
      </code></td>
      <td style="vertical-align: top;">signals that the user has
aborted the operation <br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class
libdar::Ethread_cancel</code></td>
      <td style="vertical-align: top;">A program has requested the
termination of the current thread while libdar was running<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Edata<br>
      </code></td>
      <td style="vertical-align: top;">an error concerning the treated
data has been encountered<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Escript<br>
      </code></td>
      <td style="vertical-align: top;">the script executed between
slices returned an error code<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Elibcall<br>
      </code></td>
      <td style="vertical-align: top;">signals an error in the
arguments given to a libdar call of the API<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code>class libdar::Ecompilation<br>
      </code></td>
      <td style="vertical-align: top;">a requested feature has not been
activated at compilation time<br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<br>
<hr style="width: 100%; height: 2px;"><br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h2>&nbsp;1 - First we *must* initialize libdar by checking the libdar version</h2>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code>&nbsp;&nbsp;
      <br>
&nbsp;&nbsp;&nbsp; // we'll want to display some messages<br>
#include &lt;io.h&gt;<br>
      <br>
&nbsp;&nbsp;&nbsp; // we include this header to access lidbar API<br>
#include &lt;dar/libdar.h&gt;<br>
      <br>
&nbsp;&nbsp;&nbsp; // all sample code shown will be inside this<br>
&nbsp;&nbsp;&nbsp; // function for simplicity's sake<br>
void my_sample_function()<br>
{<br>
&nbsp;&nbsp; try<br>
&nbsp;&nbsp; {<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; libdar::U_I maj, med, min;<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // first we <span style="font-weight: bold;">MUST </span>call
get_version()<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; libdar::<span style="font-weight: bold;">get_version</span>(maj,
med, min); <br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if(maj !=
libdar::LIBDAR_COMPILE_TIME_MAJOR ||<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; med &lt;
libdar::LIBDAR_COMPILE_TIME_MEDIUM)<br>
&nbsp; &nbsp; &nbsp; &nbsp; throw libdar::Erange("initialization", <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "we are linking against a
wrong libdar"); <br>
&nbsp;&nbsp; }</code><br>
      <code>&nbsp;&nbsp; catch(libdar::Egeneric &amp; e)<br>
&nbsp;&nbsp; {<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; e.get_message()
&lt;&lt;
std::endl;<br>
&nbsp;&nbsp; }<br>
}<br>
      <br>
&nbsp;&nbsp; <br>
      </code> </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code><code>&nbsp;&nbsp;
      <br>
&nbsp;&nbsp;&nbsp; // we'll want to display some messages<br>
#include &lt;io.h&gt;<br>
      <br>
&nbsp;&nbsp;&nbsp; // we include this header to access lidbar API<br>
#include &lt;dar/libdar.h&gt;<br>
      <br>
&nbsp;&nbsp;&nbsp; // all sample code shown will be inside this<br>
&nbsp;&nbsp;&nbsp; // function for simplicity's sake<br>
void my_sample_function()<br>
{<br>
      <br>
&nbsp;&nbsp; </code><code> libdar::U_I maj, med, min;<br>
&nbsp;&nbsp; libdar::U_16 excode;<br>
&nbsp;&nbsp; std::string msg;<br>
      </code><code><br>
&nbsp;&nbsp;&nbsp; // first we <span style="font-weight: bold;">MUST </span>call
get_version()<br>
      <br>
&nbsp;&nbsp; libdar::<span style="font-weight: bold;">get_version_noexcept</span>(maj,
med, min, <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
excode, msg);<br>
      <br>
&nbsp;&nbsp; if(excode != LIBDAR_NOEXCEPT)<br>
&nbsp;&nbsp; { <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; msg &lt;&lt; endl;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return;<br>
&nbsp;&nbsp; }<br>
&nbsp; <br>
&nbsp;&nbsp; if(maj != LIBDAR_COMPILE_TIME_MAJOR ||<br>
&nbsp; &nbsp; &nbsp; </code><code>med &lt;
libdar::LIBDAR_COMPILE_TIME_MEDIUM</code><code>)<br>
&nbsp;&nbsp; {<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; </code><code>"we are
linking against wrong libdar"</code><code> &lt;&lt; std::endl;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return;<br>
&nbsp;&nbsp;&nbsp; }<br>
      </code> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">The get_version() function must
be called for
several reasons :<br>
      <ul>
        <li>
          <div style="text-align: justify;">you must check that the
library
you've dynamically linked with is compatible with the features you will
be using. The major number must be the same, for no compatibility is
assured between two libdar versions of different major numbers. While
run-time compatibility is assured between medium 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. Changes between minor versions
correspond to bug fixes and is not to imply any API change, thus no
constraints are present there (except the presence of more bugs in lower numbers).<br>
          </div>
        </li>
        <li style="text-align: justify;">the
get_version() call, as
well as
returning version information, does important initialization tasks for
libdar. If not called first, the libdar library will not initialized
properly and its behavior will be unpredictable. Note that you may call
get_version() several time if you wish, the secon time only the version
information are returned, the libdar library is not reset or the like.<br>
</li>
	<li style="text-align: justify;">Last, if strong encryption support is activated at compilation time, libdar will by default
performs libgcrypt initialization when get_version() is called if libgcrypt is
not already initialized. You can avoid having dar initializing libgcrypt by calling get_version()
with an additional argument set to "false" :</li></ul>
      <div style="text-align: left; margin-left: 120px;"><span style="font-family: Courier;">ger_version(maj, med, min, </span><span style="font-weight: bold; font-family: Courier;">false</span><span style="font-family: Courier;">)</span><br>
      </div>

      <ul style="text-align: justify;">
        <li>Note
that in multi-thread environment with strong encryption activated in
libdar at compilation time, libgcrypt requires to be initialized from
the application, thus you *must* avoid having libdar initializing
libgcrypt by using the get_version() described just above and proceed
from the application to the initialization of libgcrypt before calling
get_version(). For more details see libgcrypt documentation.</li></ul>
      <ul>

      
      </ul>

      <br>
      <h2>1 bis - We must prepare the end right now!<br>
      </h2>
<br>
      <div style="text-align: justify;">As we saw, libdar used
some
datastructures (mutex, secured memory, etc.) that need to be released
properly before ending the program. It is mandatory to invoke the
following function before exiting your program if you invoked
get_version() previously. It is a good idea to implement this right now
not to forget later:<br>
      
      </div>
      
      
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="text-align: left; width: 90%; background-color: rgb(153, 255, 255);" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><code><span style="font-weight: bold;"><br>
      </span></code>
      <div style="margin-left: 40px;"><code style="font-weight: bold;">libdar::close_and_clean()</code><span style="font-weight: bold;"></span><br>
      <span style="font-weight: bold;"></span></div>
      <code style="font-weight: bold;"><br>
      </code></td>
    </tr>
  </tbody>
</table>
<br>
<table style="text-align: left; width: 90%;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      
      <div style="text-align: justify;">In particular, closes_and_clean()
makes the necessary for memory to be released in the proper order. <span style="text-decoration: underline;">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</span>. This depends on the compiler, libc and option activated in libdar at compilation time.<br>
      <br>
<br>


      </div>

      <h2>2 - Let's see the available features</h2>

once we have called one of the <span style="font-style: italic;">get_version*</span>
function it is possible to access the list of features activated at compilation
time:</td>
    </tr>
  </tbody>
</table>
<br>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code><br>
      <br>
void my_sample_function()<br>
{<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // let's continue in the
same function<br>
      <br>
</code>
      <div style="margin-left: 40px;"><code>bool ea = libdar::compile_time::ea();<br>
bool largefile = libdar::compile_time::largefile();<br>
bool nodump = libdar::compile_time::nodump();<br>
bool special_alloc = libdar::compile_time::special_alloc();<br>
U_I bits = libdar::compile_time::bits();<br>
// bits is equal to zero for infinint,<br>
// else it is equal to 32 or 64 depending on<br>
// the compilation mode used.<br>
      <br>
bool thread = libdar::compile_time::thread_safe();<br>
bool libz = libdar::compile_time::libz();<br>
bool libbz2 = libdar::compile_time::libbz2();<br>
bool liblzo = libdar::compile_time::liblzo();<br>
bool libcrypto = libdar::compile_time::libgcrypt();<br>
bool furtive_read = libdar::compile_time::furtive_read</code>();<br>
      </div>
      <code>
      </code><br>
}<br>
      <br>
      </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code>
      <code><br>
      <br>
&nbsp;// here there is no difference because no exceptions<br>
&nbsp;// are thrown by the get_compile_time_feature() <br>
&nbsp;// function<br>
      </code> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">You can do what you want with
the
resulting values. It's possible to display the available libdar
features or to terminate if you don't find a desired feature. However,
verifying that features are available is not strictly necessary because
libdar will tell you if an operation you call requires a feature that
has not been activated at compilation time, by throwing an Ecompile
exception (or returning
the <span style="font-style: italic;">LIBDAR_ECOMPILATION</span> error
code if you are not using exceptions).<br>
      </div>
      <br>
      <br>
      <h2>3 -User interaction</h2>
      <div style="text-align: justify;">
      <h3>The generic <span style="font-style: italic;">user_interaction</span>
class</h3>
To be able to report messages to the user and prompt for feedback a
special class called<span style="font-style: italic;"> <span style="font-weight: bold;">user_interaction </span></span>has been
introduced. Simply put, <span style="font-style: italic;">user_interaction</span>
is a virtual class which you can derive to provide user interaction (a
GUI's graphical interaction, for example). There are four methods whose
prototypes you must override:<br>
      </div>
      <br style="font-style: italic; font-weight: bold;">
      <span style="font-style: italic; font-weight: bold;">void&nbsp;</span><span style="font-style: italic; font-weight: bold;" class="el">pause</span><span style="font-style: italic; font-weight: bold;"> (const std::string
&amp;message);</span><br>
      <div style="margin-left: 40px; text-align: justify;">this method
is
called by libdar when the library needs a yes or no ("continue" or
"kill")
answer to a question, which is provided by the string <em>message</em>.
The question posed by <em>pause()</em> must be answered by returning
normally (= "true") or throwing a <em><strong>Euser_abort</strong></em>
exception if the user refused the proposition<span style="font-weight: bold;"><span style="font-weight: bold;">. </span></span>Don't
worry about throwing an exception in your code; it will be trapped by
libdar if you don't want to manage exceptions, and are using libdar in
the "no exception" method. But if you really don't want to throw
exception from your code see next:<br>
      <span style="font-weight: bold;"><span style="font-weight: bold;"><br>
      <br>
      </span></span></div>
      <span style="font-weight: bold;"><span style="font-style: italic; font-weight: bold;">bool </span><span style="font-style: italic; font-weight: bold;" class="el">pause</span><span style="font-style: italic; font-weight: bold;">2(const std::string
&amp;message);</span></span><span style="font-weight: bold;"><br>
      </span>
      <div style="margin-left: 40px;">This is an alternative method to<span style="font-style: italic;"> pause()</span> as seen above. In place of
defining a <span style="font-style: italic;">pause()</span> method in
your inherited class, you can redefine the <span style="font-style: italic;">pause2()</span> method. The only
difference with <span style="font-style: italic;">pause()</span> is
that the user answer to the question is returned by a boolean value,
your code does no more have to throw a <span style="font-style: italic;">Euser_abort</span> exception to say "no".
Note that <span style="font-weight: bold;">you must not redefine both
pause() and pause2(). </span><span style="text-decoration: underline;"><br>
      </span></div>
      <span style="font-weight: bold;"><br>
      </span><span style="font-style: italic; font-weight: bold;">void </span><span style="font-style: italic; font-weight: bold;" class="el">inherited_warning</span><span style="font-style: italic; font-weight: bold;"> (const std::string
&amp;message);</span><br>
      <div style="margin-left: 40px; text-align: justify;">libdar calls
this <span style="font-weight: bold;">protected</span> method (through
the
public method named <span style="font-style: italic;">warning()</span>)
to display an informational message to the user. It is not
always a warning as the name suggests, but sometimes just normal
information. In API 3.0.x this method did not exist,&nbsp; but the
public warning() method itself was pure virtual and thus needed to be
overwritten. Today, the <span style="font-style: italic;">warning()</span>
method is no more pure virtual nor it is even virtual, so the user
defined implementation of message display has to be done in the <span style="font-style: italic;">inherited_warning()</span> method.<br>
      </div>
      <br>
      <span style="font-style: italic; font-weight: bold;">std::string&nbsp;</span><span style="font-style: italic; font-weight: bold;" class="el">get_string</span><span style="font-style: italic; font-weight: bold;"> (const std::string
&amp;message, bool echo);</span><br>
      <div style="margin-left: 40px; text-align: justify;">This call is
used
to get an arbitrary answer from the user. This is mainly used to get a
password from the user (when no password has been supplied for an
encrypted archive), the <span style="font-style: italic;">echo </span>argument
indicates if the user response should be displayed back on the screen
(again, very useful for handling password input). If <span style="font-style: italic;">echo</span> is set to "false" the
implementation of <span style="font-style: italic;">get_string() </span>should
hide the characters typed by the user.<br>
      </div>
      <br style="font-style: italic; font-weight: bold;">
      <span style="font-style: italic; font-weight: bold;">&nbsp;</span><span style="font-style: italic; font-weight: bold;" class="el">user_interaction</span><span style="font-style: italic; font-weight: bold;"> *&nbsp;</span><span style="font-style: italic; font-weight: bold;" class="el">clone</span><span style="font-style: italic; font-weight: bold;">
() const;</span><br>
      <div style="margin-left: 40px;">
A deep copy
operation must be implemented here. This is because libdar stores the
reference to the <span style="font-style: italic;">user_interaction</span>
class as a pointer but may want to keep a complete internal copy at
some point. A simple implementation of this method should be something
like this (even if you don't want to use exceptions): </div>
</td>
    </tr>
  </tbody>
</table>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code><br>
      </code><code>user_interaction
*my_own_class::clone() const<br>
{<br>
&nbsp;&nbsp;&nbsp; my_own_class *ret = new my_own_class(*this);<br>
&nbsp;&nbsp;&nbsp; if(ret == NULL)<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; throw
Ememory("user_interaction_callback::clone");<br>
&nbsp;&nbsp;&nbsp; else<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; return ret;<br>
}<br>
      </code><br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h3>The callback interaction class</h3>
      <div style="text-align: justify;">An inherited class from<span style="font-style: italic;"> user_interaction</span> called <span style="font-weight: bold; font-style: italic;">user_interaction_callback</span>
provides an implementation of the user interaction based on callback
functions. This allows you to replace the three interactions methods
(pause, warning and get_string) by three normal functions of your
choice, which must be given to the <span style="font-style: italic;">user_interaction_callback</span>'s
constructor. The <span style="font-style: italic;">clone()</span>
method is implemented internally, leaving only the three callback
functions to be implemented. Look at <span style="font-style: italic;">
dar</span>'s command line code for a practical example. <span style="font-style: italic;">dar</span>'s user interaction code is
implemented using an instance of <span style="font-style: italic;">user_interaction_callback</span>
and three static functions in the module<span style="font-style: italic;"> dar_suite/shell_interaction.cpp</span> <br>
      </div>
      <br>
Pay attention to the <span style="font-style: italic;">contextual</span>
value present in the arguments of these callback functions : </td>
    </tr>
  </tbody>
</table>
<br>
<div style="text-align: justify;"><code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code>&nbsp;
      </code><code><br>
&nbsp; // our own callback functions. <br>
&nbsp; // for the illustration of what these 'context' arguments<br>
&nbsp; // can be used for we will imagine the situation where<br>
&nbsp; // multiple windows or multiple threads may each one use <br>
&nbsp; // libdar, but all share the same callback functions.<br>
&nbsp;<br>
typedef class t_window_type t_win;<br>
      <br>
&nbsp; // this is an arbitrary type that here we will say<br>
&nbsp; // points to a graphical window object wrapped in a C++<br>
&nbsp; // class. <br>
&nbsp; // Note that the method show() wait_for_click() and so on<br>
&nbsp; // attributed to the t_win class are absolutely<br>
&nbsp; // imaginary. Any link to an existing class is a pure <br>
&nbsp; // coincidence...<br>
      <br>
void warning_callback(const std::string &amp;x, void *context)<br>
{<br>
&nbsp;&nbsp;&nbsp; (t_win *)(context)-&gt;show(x);<br>
}<br>
&nbsp;<br>
bool answer_callback(const std::string &amp;x, void *context)<br>
{<br>
&nbsp;&nbsp;&nbsp; click_type ret;<br>
      <br>
&nbsp; &nbsp; </code><code>(t_win *)(context)-&gt;show(x);<br>
&nbsp;&nbsp;&nbsp; ret = (t_win *)(context)-&gt;wait_for_click();<br>
      <br>
&nbsp;&nbsp;&nbsp; return ret == click_OK;<br>
      </code><code>}<br>
      <br>
std::string string_callback(const std::string &amp;x, bool echo, void
*context)<br>
{<br>
&nbsp;&nbsp;&nbsp; (t_win *)(context)-&gt;show(x);<br>
&nbsp;&nbsp;&nbsp; if(!echo)<br>
&nbsp;&nbsp; &nbsp;&nbsp; (t_win *)(context)-&gt;set_hide_typed_char();<br>
&nbsp;&nbsp;&nbsp; (t_win *)(context)-&gt;wait_for_click();<br>
&nbsp;&nbsp;&nbsp; return (t_win *)(context)-&gt;read_text();<br>
}<br>
      <br>
---------8&lt;-------8&lt;-------8&lt;-------<br>
      <br>
&nbsp; // So now each window can have its user_interaction object based
on the same<br>
&nbsp; // user_interaction_callback object pointing to the same
functions.<br>
&nbsp; // user_interaction_callback objects can be shared among
different window objects<br>
      <br>
libdar::user_interaction_callback dialog = <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
libdar::user_interaction_callback(&amp;warning_callback,
&amp;answer_callback, &amp;string_callback,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
(void *)get_current_windows_id());<br>
      <br>
&nbsp; // just the "context" argument changes, and will be passed as is
from the constructor to the callback<br>
&nbsp; // functions<br>
      </code><br>
      </td>
    </tr>
  </tbody>
</table>
<br>
</div>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h2>4 - Masks</h2>
      <div style="text-align: justify;">Mask are used to define which
files
will be considered and which will not. Libdar implements masks as
several classes that all inherit from a virtual class that defines the
way masks are used. This root class is the <span style="font-weight: bold; font-style: italic;">class mask</span> and
provides the <span style="font-style: italic;">is_covered()</span>
method which libdar uses to determine which files are considered. There
are many different basic masks classes you can use to build fairly
complex masks: </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; width: 200px;">class libdar::mask<br>
      </td>
      <td style="vertical-align: top;">the generic class, parent of all
masks (a pure virtual class)<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">class libdar::bool_mask<br>
      </td>
      <td style="vertical-align: top;">boolean mask, either always true
or false, it matches either all files or no files at all<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">class libdar::simple_mask<br>
      </td>
      <td style="vertical-align: top;">matches as done by the shell on
the command
lines (see "man 7 glob")<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">class libdar::regular_mask<br>
      </td>
      <td style="vertical-align: top;">matches regular expressions (see
"man 7 regex")<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">class libdar::not_mask<br>
      </td>
      <td style="vertical-align: top;">negation of another mask<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">class libdar::et_mask<br>
      </td>
      <td style="vertical-align: top;">makes an *AND* operator between
two or more masks<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">class libdar::ou_mask<br>
      </td>
      <td style="vertical-align: top;">makes the *OR* operator
between&nbsp; two or more masks <br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">class lbdar::simple_path_mask<br>
      </td>
      <td style="vertical-align: top;">
      <p>string matches if it is subdirectory of mask or is a directory
that contains the specified path itself<br>
      </p>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">class libdar::same_path_mask<br>
      </td>
      <td style="vertical-align: top;">matches if the string is exactly
the
given mask (no wild card expression)<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; width: 210px;">class
libdar::exclude_dir_mask<br>
      </td>
      <td style="vertical-align: top;">matches if string is the given
string or a sub directory of it<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">class libdar::mask_list<br>
      </td>
      <td style="vertical-align: top;">matches a list of files defined
in a given file<br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">Let's play with some masks : </td>
    </tr>
  </tbody>
</table>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code><br>
      </code><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // all files will be
elected by this mask</code><br>
      <code>&nbsp; libdar::bool_mask m1 = true;&nbsp;&nbsp;&nbsp; <br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // all file that match the glob
expession "A*~" will match. <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // the second argument of the
constructor tell if the match is case sensitive so here <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // any file beginning by 'A' or by 'a'
and ending by '~' will be selected by this mask<br>
&nbsp; libdar::simple_mask m2 = libdar::simple_mask(std::string("A*~"),
false);<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // m3 is the negation if m2. This mask
will thus match<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // any file that does not begin by 'A'
or 'a' and also finish by '~'<br>
&nbsp; libdar::not_mask m3 = m2;<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // this mask matches any file that is a
subdirectory of "/home/joe"<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // and any directory that contains
/home/joe, meaning<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // "/", "/home", "/jome/joe" and any
subdirectory are matched.<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // here, the second argument is also
case sensitivity (so<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp; "/HoMe" will not be selected by
this mask.<br>
&nbsp; libdar::simple_path_mask m4 = simple_path_mask("/home/joe",
true);<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // now let's do some more complex things:<br>
      </code><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // m5 will now match
only files that are selected by both m2 AND m4</code><br>
      <code>&nbsp; libdar::et_mask m5;<br>
&nbsp; m5.add_mask(m2);<br>
&nbsp; m5.add_mask(m4);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // we can make more silly things like
this, where m5 will select files<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // that match m2 AND m4 AND m3. But <span style="font-style: italic;">m3 =
not m2</span> so now m5 will never<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // match any file...<br>
&nbsp; m5.add_mask(m3);<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // but we could do the same with an
"ou_mask" and would get a silly<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // counterpart of m1 (a mask that
matches any files)<br>
&nbsp; libdar::ou_mask m6;<br>
&nbsp; m6.add_mask(m2);<br>
&nbsp; m6.add_mask(m4);<br>
&nbsp; m6.add_mask(m3);<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // lastly, the NOT, AND and OR operation
can be used recursively.<br>
      </code><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // Frankly, it's
possible to have masks reference each other!</code><br>
      <code>&nbsp; libdar::not_mask m7 = m6;<br>
&nbsp; m6.add_mask(m7);<br>
      <br>
      </code></td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">Now that you've seen the power
of these masks, you should know that in
libdar there are three masks that are required: <br>
      <ul style="text-align: justify;">
        <li>The first mask is used against
the
names of all files except directories. It is applied solely to the
names themselves (not the file path). This mask may be any combination
of the masks seen previously; it will only be applied to socket, named
pipes, symbolic links, char or block devices, plain files, but again
not to directories. This way you can filter by file type for save,
restore, list, compare, compress, and other library operations.</li>
        <li>The second mask is applied to
any
file including directories, including the path part of the filename. 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. <span style="font-weight: bold;">Important note</span>
about this second mask: what your own mask will be compared to by
libdar is the filesystem root (as defined under the argument "fs_root"
of the same call you will give your own mask to) plus the current file
being&nbsp; proceeded:</li>
      </ul>
      <div style="text-align: justify;"> </div>
      <div style="margin-left: 80px; text-align: justify;">Assuming you
choose for example <span style="font-style: italic;">tmp/A</span> as
argument to <span style="font-style: italic;">fs_root</span> (which
argument is present
when creating an archive, for example), your mask will be used against
strings like "<span style="font-style: italic;">tmp/A/some/file</span>"
. This is true up to libdar version 3.0.x (alias release 2.2.x).
Instead, since libdar 4.0.0 the <span style="font-style: italic;">fs_root</span>
argument is expended to an absolute path, so if in the previous
example, your current directory was <span style="font-style: italic;">/var</span>
your masks will be used against strings like "<span style="font-style: italic;">/var/tmp/A/some/file</span>". Of course
there is no difference between these two libdar revisions when the <span style="font-style: italic;">fs_root</span> argument is an absolute
path <span style="font-style: italic;">[this change was necessary to support masks based on a list of files]</span><br>
      <br>
An exception is the test operation, which has no <span style="font-style: italic;">fs_root</span> argument (because the
operation is not relative to an existing filesystem), however the <span style="font-style: italic;">subtree</span> argument exist to receive a
mask for comparing the path of file to include or exclude from the test
operation. In this case the situation is as if the <span style="font-style: italic;">fs_root</span> was set to the value "<span style="font-style: italic;">&lt;ROOT&gt;</span>". For example, masks
will be compared to <span style="font-style: italic;">&lt;ROOT&gt;/some/file</span>
when performing an archive test operation.<br>
</div>
      <div style="margin-left: 80px; text-align: justify;">
      </div>


      <ul>
        <li>The third mask --- which is not always needed --- concerns
Extended Attributes (EA). It is applied to the full EA name in the form
&lt;domain&gt;.&lt;name&gt; where &lt;domain&gt; is any string value
like but not limited to the usual "user" or "system" domains.<br>
        </li>
      </ul>


      <h2><br>
</h2>
      <h2>5 - Let's create a simple archive</h2>

Now that we have seen masks and exceptions let's start the real thing:<br>
      <br>
All the operations on archives are handled by the archive class which
is defined in libdar/archive.hpp. Each operation requires some
mandatory parameters and some optional parameters. Optional parameters
are gathered in a archive_option auxilliary class, which default
constructor set them to default values. We will see a bit further how
to set these options, but for now let's keep the things simple:<br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;">
      <p><code>&nbsp; // creating an archive is simple; it is just<br>
&nbsp; // a matter of calling the "create" constructor<br>
&nbsp; // of the archive class. It may be used for full or<br>
&nbsp; // differential archives. We'll see an example of<br>
&nbsp; // of differential archives later.<br>
      <br>
&nbsp; // note that while this example uses a pointer to store<br>
&nbsp; // my_arch, it is perhaps better practice to use a plain<br>
&nbsp; // stack object. In your code, use an object instead of<br>
&nbsp; // a pointer to an object under normal circumstances.<br>
      <br>
libdar::user_interaction_callback dialog =
libdar::user_interaction_callback(ptr1, ptr2, ptr3);<br>
&nbsp; // where ptr1, ptr2 and ptr3 are three callback<br>
&nbsp; // functions.<br>
libdar::statistics ret;<br>
&nbsp; // we will see this structure a bit further<br>
      <br>
libdar::archive *my_arch = <br>
&nbsp; &nbsp;&nbsp; new <span style="font-weight: bold;">libdar::archive</span>(dialog,
      <br>
&nbsp;&nbsp;&nbsp; &nbsp;"/home",&nbsp; // saving all under this "root"<br>
&nbsp;&nbsp;&nbsp; &nbsp;"/tmp",&nbsp;&nbsp; // where the slices will go<br>
&nbsp;&nbsp;&nbsp;&nbsp; "my_archive", // the basename of the slices<br>
&nbsp;&nbsp;&nbsp;&nbsp; "dar",&nbsp; // the extension used for slices<br>
&nbsp;&nbsp;&nbsp;&nbsp; archive_options_create(), // default options<br>
&nbsp;&nbsp;&nbsp;&nbsp; &amp;ret); // this value is
returned by libdar<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //
if you don't want to have statistics of the<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //
operation you can set this parameter to NULL<br>
      </code> </p>

      </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code><code>&nbsp;&nbsp;
// creating an archive is simple; it is just<br>
&nbsp; // a matter of calling the "create" constructor<br>
&nbsp; // of the archive class. It may be used for full or<br>
&nbsp; // differential archives. We'll see an example of<br>
&nbsp; // of differential archives later.<br>
      <br>
&nbsp; // note that while this example uses a pointer to store<br>
&nbsp; // my_arch, it is perhaps better practice to use a plain<br>
&nbsp; // stack object. In your code, use an object instead of<br>
&nbsp; // a pointer to an object under normal circumstances.<br>
      </code><code><br>
libdar::user_interaction_callback dialog =
libdar::user_interaction_callback(ptr1, ptr2, ptr3);<br>
&nbsp; // where ptr1, ptr2 and ptr3 are three callback<br>
&nbsp; // functions.<br>
libdar::statistics ret;<br>
&nbsp; </code><code>// we will see this structure a bit further<br>
      <br>
      </code><code>U_16 exception, <br>
std::string except_msg;</code><br>
      <br>
      <code><span class="el">libdar::archive *my_arch
=&nbsp;&nbsp;&nbsp;&nbsp; <br>
&nbsp;&nbsp;&nbsp;&nbsp; <span style="font-weight: bold;">libdar::create_archive_noexcept</span>(dialog,</span></code><span class="el"><code>&nbsp; <br>
&nbsp;&nbsp;&nbsp;&nbsp; "/home",&nbsp; // saving all under this "root"<br>
&nbsp;&nbsp;&nbsp; &nbsp;"/tmp",&nbsp;&nbsp; // where the slices will go<br>
&nbsp;&nbsp;&nbsp;&nbsp; "my_archive",&nbsp; <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //
the basename of the slices <br>
&nbsp;&nbsp;&nbsp; &nbsp;"dar", // dar's slice extensions<br>
&nbsp;&nbsp;&nbsp;&nbsp; archive_options_create(), // default options</code></span><span class="el"><code></code><br>
      </span><span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp;
&amp;ret,&nbsp; // this value is returned by
libdar<br>
      </code></span><span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// if you don't want to have statistics of the<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //
operation you can set this parameter to NULL</code><br>
      </span><span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp; exception,
// this gives the status of the call<br>
&nbsp;&nbsp;&nbsp;&nbsp; except_msg); // and in case of error the cause.<br>
      <br>
if(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt; std::endl;<br>
      <br>
      </code></span> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">When creating an archive, the
created
archive object can be used only as reference for an isolation or for
a differential backups. You cannot use it for restoration, listing, or
comparison, because the underlying file descriptors are opened in
write only mode. An implementation which uses file descriptors in
read-write access is not possible and is not a good idea anyway. Why?
Because, for example, if you want to test the newly created archive,
using the newly created object would make the test rely on information
stored in virtual memory (the archive contents, the data location of a
file, etc.), not on the file archive itself. If some corruption
occurred
in the file you would not notice it.<br>
      </div>
      <br>
      <div style="text-align: justify;">So to totally complete the
archive creation we must destroy the archive
object we have just created, which will also close any file descriptors
used by the object : </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code><br>
&nbsp;&nbsp;&nbsp;&nbsp; delete my_arch;<br>
      <br>
      </code> </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code><br>
libdar::close_archive_noexcept(my_arch, exception,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; except_msg);<br>
      <br>
      </code><span class="el"><code>if(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt;
std::endl;<br>
      <br>
      </code></span> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="text-align: left; width: 90%;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h3>Optional Arguments:</h3>
      <br>
      <div style="text-align: justify;">Back on the optional arguments.
The archive constructor used above to
create an archive uses an argument of type "archive_option_create". In
the above example, we called the constructor of this class directly
withing the argument list of the constructor. Thsi has for effect to
built
a anonymous temporary object of this class. Such a "just borned" object
has
all the necessary options set to the default values inside it (like
default masks for example) to
correspond to the default options. If you want to use non default
options like compression, slicing, encryption , file filtering and so
on, you must
change the options to your need thanks to the appropriate method
provided by the archive_options_create class. Assuming we want to make
a
compressed an sliced archive we would use the following code:<br>

      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
<tbody><tr><td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;">

      <p><code>&nbsp; <br>
&nbsp;// we define an options object to be able to use <br>
&nbsp;&nbsp; // non default options:<br>
libdar::archive_options_create options;<br>
      </code></p>
      <p><code>&nbsp; // so now we can modify only the option we wish to<br>
options.set_slicing(1024); // 1024 bytes, well that's small<br>
options.set_compression(bzip2); // default is no compression<br>
options.set_compression_level(6); // default is 9<br>
      </code></p>

<p><code>
libdar::statistics ret;<br>
&nbsp; // we will see this structure a bit further<br>
      <br>
libdar::archive *my_arch = <br>
&nbsp; &nbsp;&nbsp; new <span style="font-weight: bold;">libdar::archive</span>(dialog,
      <br>
&nbsp;&nbsp;&nbsp; &nbsp;"/home",&nbsp; // saving all under this "root"<br>
&nbsp;&nbsp;&nbsp; &nbsp;"/tmp",&nbsp;&nbsp; // where the slices will go<br>
&nbsp;&nbsp;&nbsp;&nbsp; "my_archive", // the basename of the slices<br>
&nbsp;&nbsp;&nbsp;&nbsp; "dar",&nbsp; // the extension used for slices<br>
&nbsp;&nbsp;&nbsp;&nbsp; options, // the object we modified above<br>
&nbsp;&nbsp;&nbsp;&nbsp; &amp;ret); // this value is
returned by libdar<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //
if you don't want to have statistics of the<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //
operation you can set this parameter to NULL<br>
      </code> </p>

      </td><td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code><code></code>
      <p><code>&nbsp;&nbsp; // we define an options object to be able to use <br>
&nbsp;&nbsp; // non default options:<br>
libdar::archive_options_create options;<br>
</code></p>


      <p><code>&nbsp; // so now we can modify only the option we wish to<br>
options.set_slicing(1024); </code><code>// 1024 bytes, well that's small</code><br>
      <code>
options.set_compression(bzip2);&nbsp; // default is no compression<br>
options.set_compression_level(6); // default is 9<br>
      </code></p>
      <code>libdar::statistics ret;<br>
&nbsp; </code><code>// we will see this structure a bit further<br>
      <br>
      </code><code>U_16 exception, <br>
std::string except_msg;</code><br>
      <br>
      <code><span class="el">libdar::archive *my_arch
=&nbsp;&nbsp;&nbsp;&nbsp; <br>
&nbsp;&nbsp;&nbsp;&nbsp; <span style="font-weight: bold;">libdar::create_archive_noexcept</span>(dialog,</span></code><span class="el"><code>&nbsp; <br>
&nbsp;&nbsp;&nbsp;&nbsp; "/home",&nbsp; // saving all under this "root"<br>
&nbsp;&nbsp;&nbsp; &nbsp;"/tmp",&nbsp;&nbsp; // where the slices will go<br>
&nbsp;&nbsp;&nbsp;&nbsp; "my_archive", //
the basename of the slices <br>
&nbsp;&nbsp;&nbsp; &nbsp;"dar", // dar's slice extensions<br>
&nbsp;&nbsp;&nbsp;&nbsp; options, // the object we modified above</code></span><span class="el"><code></code><br>
      </span><span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp;
&amp;ret,&nbsp; // this value is returned by
libdar<br>
      </code></span><span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// if you don't want to have statistics of the<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //
operation you can set this parameter to NULL</code><br>
      </span><span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp; exception,
// this gives the status of the call<br>
&nbsp;&nbsp;&nbsp;&nbsp; except_msg); // and in case of error the cause.<br>
      <br>
if(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt; std::endl;<br>
      <br>
      </code></span> </td></tr></tbody>
</table>
<br>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">

      <span style="font-weight: bold;"></span>
      <p style="text-align: justify;">In
the same way, each other
operation (diff, testing, extraction, merging, ...) has a specific
class that gathers the options parameters. These classes are defined
in the file libdar/archive_options.hpp you are welcome to refer to for
a complete up to date list of available options. The advantage of this
class is to not break ascendant compatibility of the API when new
features get added, while it also improve readability of your code.
This way, the major current number '5' of the API should stay for a
longer time than previous numbers, as for thoses each new feature
implementation broke the ascendant compatibility by adding an new
argument to an API call.<br>
      </p>
      <span style="font-weight: bold;"></span>
      <h2>6 - Testing the archive we have created</h2>

      <br>
So, as explained previously, we must create a new archive object but
this time with the "read" constructor: </td>
    </tr>
  </tbody>
</table>
<code><br>
</code>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code><br>
my_arch = new </code><code>libdar::archive(dialog,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
      <br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; "/tmp",&nbsp; // where is the
archive <br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; "my_archive", // slice name<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; "dar",&nbsp;&nbsp; // dar's
archive extensions<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; archive_options_read()); // default options<br>
      </code> </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code><br>
my_arch = </code><code>libdar::open_archive_noexcept(</code><code>dialog,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
      <br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; "/tmp",&nbsp; // where is the
archive <br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; "my_archive", // slice name<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; "dar",&nbsp;&nbsp; // dar's
archive extensions<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; archive_options_read(), // default options<br>
      </code><span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
exception,// this gives the status of the call<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; except_msg); // and in case of
error the <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// cause of the error<br>
      <br>
i</code></span><span class="el"><span class="el"><code>f(exception !=
LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt;
std::endl;</code></span><br>
      </span><span class="el"><code><br>
      </code></span> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><br>
Now that we have opened the archive we can perform any operation on it.
Let's thus start by testing the archive coherence: </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code><br>
&nbsp;&nbsp; // for the exercice, we will change the default options:<br>
archive_options_test options;<br>
      <br>
options.clear(); // this set back all options to default<br>
&nbsp;// here this is not required as the object has just bee<br>
&nbsp;// created, however it is used here for illustration that<br>
&nbsp;// you can recycle an archive_option_* object.<br>
options.set_info_details(true); // to have a verbose output<br>
<br>
ret = my_arch-&gt;<span class="el">op_test</span>(<span class="el"></span>dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; options; // the non default options set above</code><code><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
NULL);&nbsp; // we don't want a progressive report</code><code></code><br>
      <br>
      </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code><br>
&nbsp;&nbsp; // for the exercice, we will change the default options:<br>
archive_options_test options;<br>
<br>
options.clear(); // this set back all options to default<br>
&nbsp;// here this is not required as the object has just bee<br>
&nbsp;// created, however it is used here for illustration that<br>
&nbsp;// you can recycle an archive_option_* object.<br>
options.set_info_details(true); // to have a verbose output</code><br>
      <code><br>
      <span class="el">ret = libdar::op_test_noexcept(</span></code><span class="el"><code><span class="el"></span>dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
my_arch,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // the archive
to test<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </code></span><span class="el"><code>options, // the non default options set above<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; NULL,&nbsp; // we don't want a
progressive report<br>
      </code> </span> <span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
exception,// this gives the status of the call<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; except_msg); // and in case of
error the <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// cause of the error<br>
      <br>
      </code></span><span class="el"><span class="el"><code>i</code></span><span class="el"><span class="el"><code>f(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt;
std::endl;<br>
      <br>
      </code></span></span></span> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">We have tested the archive, but
have
not yet seen the libdar::statistics variable. It can be used when
creating an archive as well as when testing it.&nbsp; This object
reports the number of files treated, as well as the number files with
errors and the type of error. You can have a look at the API reference
guide concerning the archive class methods, for more information about
the uses of these different fields. Here is
an example, which relies on the <span style="font-style: italic;"><span style="font-weight: bold;">class deci</span> </span>to display the
value of an infinint variable:<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);">&nbsp;&nbsp;
      <code>&nbsp;&nbsp; <br>
&nbsp;&nbsp;&nbsp;&nbsp; // we need the <span style="font-style: italic;">class deci</span> to display the value of
an infinint:<br>
      </code><code></code><code>#include "deci.hpp"<br>
      <br>
&nbsp;std::cout &lt;&lt; std::string("Number of file treated :")
&lt;&lt; libdar::deci(ret.treated).human() &lt;&lt; std::endl;<br>
      <br>
&nbsp; &nbsp; // or much simpler (but totally equivalent):<br>
&nbsp;std::cout &lt;&lt; std::string("Number of file treated :")
libdar::&lt;&lt; ret.treated &lt;&lt; std::endl;<br>
      </code><br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">Note that the use of the <span style="font-style: italic;">class
deci
      </span>may throw exceptions (in case of lack of memory, for example), and
there is actually no wrapper available to trap the exceptions that may
be thrown by the class<span style="font-style: italic;"> deci</span>.
So you have to protect the code using a<span style="font-style: italic;">
      <span style="font-weight: bold;">try {} catch {}</span></span>&nbsp;
statement.<br>
      <br>
You may have noticed that we used NULL as argument for
"progressive_report". This argument must either receive NULL as
argument or the address of a real allocated statistics object. This
object will be updated by the libdar call and if multi-threaded support is
enabled it will let a concurrent thread able to reading its value to display the
current number of file treated, for example. Note that there is a little
overhead passing a variable to progressive_report, due to the mutex
that need be used to avoid one reading data while it is updated by
another thread. Follows a example of use of this <span style="font-style: italic;">progressive report</span> feature:<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code>&nbsp;
&nbsp; &nbsp; <br>
&nbsp; &nbsp; &nbsp;&nbsp;&nbsp; // we need a variable that will be
visible by two threads: <br>
&nbsp;&nbsp;&nbsp; </code><code>libdar::statistics report;<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // and we need store the
libdar call returned value<br>
&nbsp;&nbsp;&nbsp; libdar::statistics final_result;<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // we spawn a first task
with a libdar call passing &amp;report as argument to
"progressive_report"<br>
&nbsp;&nbsp;&nbsp; final_result =
some_call_to_be_defined_to_call_op_test_in_another_tread(...,
&amp;report);<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // doing a endless loop
(assuming the current thread will be signaled or interrupted once the<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // previously libdar call running in another thread
will end)<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp; while(true)<br>
&nbsp;&nbsp;&nbsp;&nbsp; {<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sleep(1); // updating
the display each second<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
some_function_to_update_the_display_with(report);<br>
&nbsp;&nbsp;&nbsp;&nbsp; }<br>
      </code><br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h2><br>
      </h2>
      <h2>7 - listing archive contents</h2>
      <br>
The simple way:<br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code><br>
my_arch-&gt;<span class="el">op_listing</span>(<span class="el"></span>dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; archive_option_listing()); // default options<br>
      </code><br>
      </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code>&nbsp;
      <br>
li<span class="el">bdar::op_test_listing(</span></code><span class="el"><code><span class="el"></span>dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; archive_options_listing(), // default options</code></span><span class="el"><code></code></span><br>
      <span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
exception,// this gives the status of the call<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; except_msg); // and in case of
error the <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// cause of the error<br>
      <br>
      </code></span><span class="el"><span class="el"><code>i</code></span><span class="el"><span class="el"><code>f(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt;
endl;<br>
      <br>
      </code></span></span></span> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">By default the library will
complete
the listing by calling the<span style="font-style: italic;"> warning()</span>
method of the <span style="font-style: italic;">dialog</span> object
one time for each file listed. The warning text will consist of a
string for each file with the relevant information in columns that
would need to be parsed if individual information was desired. This may
not be appropriate for you and as such there is another way to get
listing information. This requires a simple reimplementation of the <em>user_interaction</em>
object.<br>
      </div>
      <br>
      <div style="text-align: justify;">The <span style="font-style: italic;">user_interaction</span> class
has a<span style="font-style: italic;"> </span><span style="font-weight: bold; font-style: italic;">listing()</span> method
which provides separate arguments for each piece of information that
can be displayed:<br>
      </div>
      <ul>
        <li>filename, </li>
        <li>permission, </li>
        <li>user, </li>
        <li>group, </li>
        <li>file size,</li>
        <li>last modification date,</li>
        <li>if the file is a directory</li>
        <li>if the file has children or is an empty dir</li>
        <li>file type</li>
        <li>flag about saved data / saved EA / compression used</li>
      </ul>
      <p><br>
      </p>
      <div style="text-align: justify;"><strong>Technical note:</strong>
      <em>You may notice that file
type is
not explicitly given as a parameter in the listing method. File type is
available as the first byte of the permissions string. This is standard
POSIX stuff except for an extension: </em>"h"<em> for files hard
linked several times (it has been removed after release 2.3.0 / API 4.0.0). See </em><strong>man 2 stat</strong> <em>
for
more information about POSIX permissions. Note however that the last
arguments of this call, let you easily know whether a file is a
directory or not and whether it
is empty or not.</em></div>
      <div style="text-align: justify;">In the <span style="font-style: italic;">user_interaction</span> class
(a virtual class), the <span style="font-style: italic;">listing()</span>
method is not a pure virtual method, so you are not obliged to
overwrite it, but it has just an empty implementation so it does
nothing.
You understand now that, by default, this method is not used. To
activate it, you must call&nbsp;<span style="font-style: italic;">
set_use_listing(true) </span>protected method and of course you will
have to overwrite the <span style="font-style: italic;">listing()</span>
method to have a less silly behavior: </div>
      </td>
    </tr>
  </tbody>
</table>
<div style="text-align: justify;">
</div>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code>&nbsp;&nbsp;&nbsp;
// here follows the definition of our own implementation of<br>
&nbsp;&nbsp;&nbsp; // of a user_interaction class <br>
      <br>
class my_user_interaction : public user_interaction<br>
{<br>
public :<br>
&nbsp; &nbsp;&nbsp; // the inherited pure virtual methods we must define<br>
&nbsp; &nbsp;&nbsp; // as seen at the beginning of this tutorial:<br>
&nbsp; &nbsp;&nbsp; &nbsp; void pause(const std::string &amp; message);<br>
      </code><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void
warning(const std::string &amp; message);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; std::string get_string(const
std::string &amp; message, bool echo);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; user_interaction *clone() const;<br>
      <br>
&nbsp;&nbsp;&nbsp; // we can overwrite this method to have splitted
fields for listing:<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void listing(const
std::string &amp; flag,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; const std::string
&amp; perm,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; const
std::string &amp; uid,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; const
std::string &amp; gid,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; &nbsp; &nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp;
size,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; const
std::string &amp; date,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; &nbsp; &nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp;
filename,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; bool
is_dir,<br>
&nbsp;&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; bool
has_children);<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp; // but it will not get used by libdar unless
we call the protected method set_use_listing()<br>
&nbsp;&nbsp;&nbsp;&nbsp; // for example this can be done in the class
constructor :<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp; my_user_interaction() { <span style="font-weight: bold;">set_use_listing(true);</span> };<br>
};<br>
      <br>
      </code> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">Now assuming we have
implemented the <span style="font-style: italic;">listing()</span>
method in&nbsp; <span style="font-style: italic;">my_user_interaction</span>
class, calling <span style="font-style: italic;">op_listing()</span>
exactly as we did
before, only replacing the <span style="font-style: italic;">dialog</span>
object by one of the <span style="font-style: italic;">my_user_interaction</span>
class. Then this <span style="font-style: italic;">listing()</span>
method will be called for each file to be listed, in place of the <span style="font-style: italic;">warning()</span> method.<br>
      </div>
      <br>
      <div style="text-align: justify;">As seen at the beginning of
this
tutorial, there is a child class of <span style="font-style: italic;">user_interaction</span>
based on callback functions which is called <span style="font-style: italic;">user_interaction_callback</span>. The <span style="font-style: italic;">listing()</span> method must also be
activated here. This is done automatically when you give a callback
function to the object, thanks to the <span style="font-weight: bold; font-style: italic;">set_listing_callback()</span>
method : </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code>&nbsp;
      </code><code><br>
&nbsp; // our mandatory callback functions:<br>
      <br>
void warning_callback(const std::string &amp;x, void *context)<br>
{<br>
&nbsp;&nbsp;&nbsp; ....<br>
}<br>
&nbsp;<br>
bool answer_callback(const std::string &amp;x, void *context)<br>
{<br>
&nbsp; &nbsp; ....<br>
}<br>
      <br>
std::string string_callback(const std::string &amp;x, bool echo, void
*context)<br>
{<br>
&nbsp;&nbsp;&nbsp; ....<br>
}<br>
      <br>
&nbsp; // let's build a user_interaction_callback object:<br>
      <br>
libdar::user_interaction_callback dialog = <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
libdar::user_interaction_callback(&amp;warning_callback,
&amp;answer_callback, &amp;string_callback, NULL);<br>
      <br>
&nbsp;&nbsp; // at this point our dialog object is perfectly
operational for listing<br>
&nbsp;&nbsp; // but libdar will call the warning_callback function to
list the archive<br>
&nbsp;&nbsp; // contents<br>
      <br>
&nbsp;&nbsp; // a new callback function for listing :<br>
      <br>
void listing_callback(const std::string &amp; flag,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; perm,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; uid,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; gid,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; size,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; date,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; filename,<br>
&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp; bool is_dir,<br>
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; bool has_children,<br>
&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; void *context)<br>
{<br>
&nbsp;&nbsp;&nbsp; ....<br>
}<br>
      <br>
      <span style="font-weight: bold;">dialog.set_listing_callback(&amp;listing_callback);</span><br>
      <br>
&nbsp;&nbsp; // now libdar will call the listing_callback function when
we <br>
&nbsp;&nbsp; // use this <span style="font-style: italic;">dialog </span>object
for listing the archive contents.<br>
      </code><br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">
      </div>
      <div style="text-align: justify;">Last point about listing, if
you examin the definition of the archive_option_listing class in file
libdar/archive_options.hpp, you will notice the the&nbsp;
set_list_mode() method. It may receive either <span style="font-weight: bold; font-style: italic;">normal,</span> <span style="font-style: italic; font-weight: bold;">tree</span> or <span style="font-style: italic; font-weight: bold;">xml</span> <span style="font-style: italic;">(normal</span> being the default).<br>
      </div>
      <ul style="text-align: justify;">
        <li><span style="font-style: italic;">normal</span>, produces (if the <span style="font-style: italic;">listing()</span>
method of the given
user_interaction object is not overwritten) a listing like tar would
do. <br>
        </li>
        <li><span style="font-style: italic;"></span><span style="font-style: italic;">tree </span>produces a tree like directory listing (this was the original listing format in dar version 1.0.0)<span style="font-style: italic; font-weight: bold;"><br>
          </span></li>
        <li><span style="font-style: italic;">xml</span>, produces a XML output as described in doc/dar-catalog-1.0.dtd</li>
      </ul>
      <div style="text-align: justify;">Note that for these two last formats (tree and xml) the <span style="font-style: italic;">listing()</span> is never used, so even if
you provide a object which listing() method is overwritten, the <span style="font-style: italic;">archive::op_listing()</span> method will
still use the <span style="font-style: italic;">warning()</span>
method of this <span style="font-style: italic;">user_interaction</span>
object to report the archive contents.

      <br>

      </div>
<h2>7 bis - Dynamic archive contents listing</h2>
      <div style="text-align: justify;">Well, in the previous chapter,
we saw
how to list the archive contents. You can imagine that when you have a
huge archive this op_listing() call may take a long time to complete and produces a
long output. If your application uses some graphical components and you
want to have a more interesting way for listing the archive contents,
you would maybe like to have just the first level of the directory tree
and let the user open the subdirectories and list their contents when needed,
having a sort of iterative archive listing. This would avoid having to
wait for the long listing to complete as well as it would avoid having
to allocate memory for all this graphical components representing each
directories and files, entries that will most of the time would not be
read by the user.<br>
      </div>
      <br>
First step, we need to use the listing() method of the
user_interaction() as seen above. <br>
Second step, we have to call the get_children_of() method of a given
archive class, instead of the op_listing() method.<br>
      <div style="text-align: justify;">In the following example, we
will use
the <span style="font-style: italic;">user_interaction_callback</span>
class, but you can use your own inherited class from <span style="font-style: italic;">user_interaction</span>, and its <span style="font-style: italic;">listing()</span> class.<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code>&nbsp;
      </code><code><br>
&nbsp; // our mandatory callback functions:<br>
      <br>
void warning_callback(const std::string &amp;x, void *context)<br>
{<br>
&nbsp;&nbsp;&nbsp; ....<br>
}<br>
&nbsp;<br>
bool answer_callback(const std::string &amp;x, void *context)<br>
{<br>
&nbsp; &nbsp; ....<br>
}<br>
      <br>
std::string string_callback(const std::string &amp;x, bool echo, void
*context)<br>
{<br>
&nbsp;&nbsp;&nbsp; ....<br>
}<br>
      <br>
&nbsp; // Now the callback function implementing the listing() method
of class user_interaction<br>
      <br>
      </code><code>void listing_callback(const std::string &amp; flag,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; perm,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; uid,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; gid,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; size,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; date,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; const std::string &amp; filename,<br>
&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp; bool is_dir,<br>
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; bool has_children,<br>
&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; void *context)<br>
{<br>
&nbsp;&nbsp;&nbsp; ....<br>
} <br>
      <br>
&nbsp; // Now that our callback functions are ready, let's create a
user_interaction callback object named "dialog"<br>
      </code><code><br>
libdar::user_interaction_callback dialog = <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
libdar::user_interaction_callback(&amp;warning_callback,
&amp;answer_callback, &amp;string_callback, NULL);<br>
      <br>
&nbsp; // now we must assign the listing_callback() function to
"dialog".<br>
      <span style="font-weight: bold;">dialog.set_listing_callback(&amp;listing_callback);</span><br>
      <br>
&nbsp;
// Let's open an archive:<br>
archive some_archive = archive(dialog, "/some/dir", "basename", "dar", archive_option_read()); <br>
&nbsp; // we are reading a new archive,
but we could have created one instead...<br>
      <br>
      </code><code>&nbsp; // now, instead of calling op_listing()
method of some_archive giving our dialog object as argument, we can
rather call:<br>
      <span style="font-weight: bold;">some_archive.get_children_of(dialog,
"");</span><br>
&nbsp; // the second argument is the directory of which we want to know
the subdirectories and subfiles. Here "" means the <br>
&nbsp; // root of the archive (we cannot use absolute path here).<br>
&nbsp; // get_chidren_of() method will call listing()'s dialog method
(here our listing_callback() function through the<br>
&nbsp; // user_interaction_callback implementation) for each entry of
the root directory.<br>
      <br>
&nbsp; // let suppose that thanks to listing_callback() during the
previous call to get_chidren_of() we know that the entry <br>
&nbsp; // "var" exists (filename == var) and is a directory (is_dir ==
true) and has some children (has_children == true),<br>
&nbsp; // suppose the user want to know what is inside this directory,
we would then only have to call:<br>
      <br>
      <span style="font-weight: bold;">some_archive.get_children_of(dialog,
"var");</span><br>
&nbsp; // assuming through listing_callback we know that a subdirectory
tmp exist and is not empty, assuming that the user<br>
&nbsp; // want to know what is in it:<br>
      <br>
s<span style="font-weight: bold;">ome_archive.get_children_of(dialog,
"var/tmp");</span><br>
&nbsp; // and so on.<br>
      </code> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h2><br>
      </h2>
      <h2>8 - comparing with filesystem</h2>
We can compare file in an archive with the filesystem by calling the<span style="font-weight: bold; font-style: italic;"> op_diff</span> method
of the <span style="font-style: italic;">class archive</span>. </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code><br>
&nbsp;&nbsp;&nbsp;&nbsp; ret = my_arch-&gt;op_diff(dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"/home", // what directory to take<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// as root we shall<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// compare the archive<br>
&nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// contents to<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
archive_options_diff(), // default options</code><code><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
NULL);&nbsp;&nbsp; // we don't use progessive report<br>
      </code> <code> <br>
      <br>
      <br>
      <br>
      </code> </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
      <br>
&nbsp; ret = </code><code>libdar::op_diff_noexcept(dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
my_arch, // the archive to use<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"/home", // what directory to take<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// as root we shall<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// compare the archive<br>
&nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// contents to<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </code><code>archive_options_diff(), // default options<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
NULL,&nbsp;&nbsp;&nbsp; // we don't use progressive report<br>
      </code> <code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp; files</code><span class="el"><code>exception, // this
gives the<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; &nbsp; // status of the call<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
except_msg); // and in case of<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; &nbsp; // error the cause of the<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //
error<br>
      <br>
      </code></span><span class="el"><span class="el"><code>i</code></span><span class="el"><span class="el"><code>f(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt;
std::endl;<br>
      <br>
      </code></span></span></span><span class="el"><code></code></span>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">Simple, no?<br>
      <br>
Just a note about the <span style="font-style: italic;">set_what_to_check() </span>method<span style="font-style: italic;"> </span>argument of the archive_options_diff class.
It may take several values:<br>
      <ul>
        <li>cf_inode_type (default value): a file is considered as changed if its
inode type
has changed (directory/plain file/symbolic link/ ...)</li>
        <li>cf_mtime : permission change is ignored, as well as
ownership
change</li>
        <li>cf_ignore_owner : ownership change is ignored</li>
        <li>cf_all : all fields denoting a content's file change
triggers a
file changed status (ownership, permission, dates, inode type).<br>
</li>
      </ul>
      <br style="font-style: italic;">
      <h2>9 - restoring files</h2>
Restoration of files is done by calling the&nbsp;<span style="font-style: italic;"> </span><span style="font-weight: bold; font-style: italic;">op_extract</span>
method of <em>class archive</em>. </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code><br>
ret = my_arch-&gt;<span class="el">op_extract</span>(<span class="el"></span>dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"/tmp",&nbsp;&nbsp; // where to restore files to<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; archive_options_extract(), // default options</code><code><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
NULL);// no progressive report used<br>
      </code> </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code>&nbsp;
      <br>
      <span class="el">ret = libdar::op_extract_noexcept(</span></code><span class="el"><code><span class="el"></span>dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
my_arch,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // the archive
to test<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </code></span><span class="el"><code>"/tmp",&nbsp;&nbsp;
// where to restore files to<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; </code></span><code> archive_options_extract(), // default options</code><span class="el"><code></code><br>
      </span><span class="el"><code></code></span><span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
exception,// this gives the status of the call<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; except_msg); // and in case of
error the <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// cause of the error<br>
      <br>
      </code></span><span class="el"><span class="el"><code>i</code></span><span class="el"><span class="el"><code>f(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt;
std::endl;<br>
      <br>
      </code></span></span></span> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="text-align: left; width: 90%; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="text-align: justify; vertical-align: top;">Here as we used default options, we restore all the files stored in the
archive in the directory /tmp (we also restore there the directory
structure stored in the archive), but we could also make a flat
restoration (ignore directory structure), as well as restore only some
of the files. By default too, dar asks user confirmation before
overwriting a file. You can change these options and many others using
the methods the class archive_options_extract. We will here restore all
that is under usr/lib and only files which filename ends with ".a", we
want libdar to skip file that would lead to overwriting an existing
file and also have libdar display files that have been skipped from the
restoration.</td>
    </tr>
  </tbody>
</table>
<br>





<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
<tbody><tr><td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code>archive_options_extract options;<br>
      <br>
options.set_selection(simple_mask("*.a", true));<br>
options.set_subtree(simple_path_mask("usr/lib", true));<br>
options.set_allow_over(false);<br>
options.set_display_skipped(true);<br>
<br>
ret = my_arch-&gt;<span class="el">op_extract</span>(<span class="el"></span>dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"/tmp",&nbsp;&nbsp; // where to restore files to<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; options, // non default options set just above</code><code><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
NULL);// no progressive report used<br>
      </code> </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code><code>archive_options_extract options;<br>
<br>
options.set_selection(simple_mask("*.a", true));<br>
options.set_subtree(simple_path_mask("usr/lib", true));<br>
options.set_allow_over(false);<br>
options.set_display_skipped(true);<br>
      <br>
      </code><code>
      <span class="el">ret = libdar::op_extract_noexcept(</span></code><span class="el"><code><span class="el"></span>dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
my_arch,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // the archive
to test<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </code></span><span class="el"><code>"/tmp",&nbsp;&nbsp;
// where to restore files to<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; </code></span><code>options, // non default options set just above<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; NULL,</code><code>&nbsp;&nbsp;&nbsp; // no progressive report used</code><span class="el"><br>
      </span><span class="el"><code></code></span><span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
exception,// this gives the status of the call<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; except_msg); // and in case of
error the <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// cause of the error<br>
      </code></span></td></tr></tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">last point about optional parameter concerns the <span style="font-style: italic;">set</span>_<span style="font-style: italic;">what_to_check</span> method. It serves two roles here: <br>
      <ol style="text-align: justify;">
        <li>Which field are to be ignored when looking whether a file is
more
recent than the one in the filesystem (if this feature is enabled)<br>
        </li>
        <li>Which field to avoid restoring (for example, when not having root
privileges, avoid restoring ownership may be interesting instead of
having a plethora of failure to restore ownership messages).<br>
        </li>
      </ol>
      <h2><br>
</h2>
      <h2>10 - Isolating the Catalogue</h2>

      <div style="text-align: justify;">OK, I know, <span style="font-style: italic;">catalogue </span>is not an English word
(one would rather write <span style="font-style: italic;">catalog</span>),
but that's the name of the C++ class used in libdar, so we will keep
using it here. Note that you don't have to directly access this
class (if you really don't like French).<br>
      </div>
      <br>
      <div style="text-align: justify;">Isolating the catalogue creates
a new
archive that only contains the list of files and their attributes
(ownership, dates, size, etc.), but no data and no EA are stored in it.
It is very similar to the same archive one gets if one makes a
differential backup of a filesystem that has not changed since the
creation of a reference archive. The usage is very similar to the
archive creation, but it uses a different constructor that has less
arguments:<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code>archive_options_isolate options;<br>
      <br>
&nbsp; // we just want to have a compressed isolated catalogue<br>
options.set_compression(gzip);<br>
<br>
libdar::archive *my_cat = new libdar::archive(dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"/tmp",&nbsp; // where the extracted <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp; // catalogue is saved<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
my_arch, // the archive of reference<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// is the one we have been<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// playing with previously<br>
&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"my_catalogue", // slice name<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"dar",&nbsp;&nbsp; // file extension<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
options) // non default options set above<br>
&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; <br>
      </code><br>
      </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code><code>archive_options_isolate options;<br>
<br>
&nbsp; // we just want to have a compressed isolated catalogue<br>
options.set_compression(gzip);<br>
      </code><code>&nbsp;&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <br>
      <span class="el">libdar::archive *my_cat = <br>
&nbsp;&nbsp;&nbsp; libdar::op_isolate_noexcept(dialog,<br>
      </span></code><span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp; "/tmp", &nbsp; // where is saved the <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp; // extracted catalogue<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
my_arch, // the archive of reference<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// is the one we have been<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// playing with previously<br>
&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"my_catalogue", // slice name<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"dar",&nbsp;&nbsp; // file extension<br>
&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; options, // non default options set above</code><br>
      </span><span class="el"><code></code></span><span class="el"><code>&nbsp;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
exception,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // this gives
the status <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // of the call<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
except_msg); <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // and in
case of error the <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp; &nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // cause of the error<br>
      <br>
      </code></span><span class="el"><span class="el"><code>i</code></span><span class="el"><span class="el"><code>f(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt;
std::endl;<br>
      <br>
      </code></span></span></span> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">


      <div style="text-align: justify;">Now we have two archive
objects. <span style="font-style: italic;">my_arch</span> is a
read-only object
created by the "read" constructor. You can do any operations with it,
like file restoration, file comparison, archive testing, as we have
done in the previous sections. The second archive object is <span style="font-style: italic;">my_cat</span> which is a write only
object. It can only be used as a reference for another backup (a
differential backup) or as a reference for a subsequent catalogue
isolation (which would just clone the already isolated catalogue object
here). <br>
      <br>
Note that once closed (object destruction) you can re-open the isolated
catalogue and use it as a read-only object (you can then test its
integrity as seen previously).<br>
      <br>
So for now we will just destroy
the extracted catalogue object, so that all its file descriptors are
closed: </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<div style="text-align: justify;">
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code><br>
delete my_cat; &nbsp;&nbsp; <br>
      </code><br>
      </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code><code><br>
close_archive_noexcept (my_cat, exception,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; except_msg);<br>
      <br>
      </code><span class="el"><code>if(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt;
std::endl;</code></span><code> <br>
      <span class="el"></span></code><span class="el"><span class="el"><span class="el"><code><br>
      </code></span></span></span> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">and we keep the <span style="font-style: italic;">my_arch</span>
object for our last operation:<br>
      <h2>11 - creating a differential backup</h2>
      <div style="text-align: justify;">This operation is the same as
the
first one we did (archive creation). We will just provide the archive of reference as an optional parameter. If we had
not destroyed <span style="font-style: italic;">my_cat </span>above,
we could have used it in place of <span style="font-style: italic;">my_arch</span>
for exactly the same result.<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
</div>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code>archive_options_create options;<br>
      <br>
&nbsp;&nbsp; // we provide here the reference to an <br>
&nbsp;&nbsp; // existing archive object, this implies that<br>
&nbsp;&nbsp; // the archive will be a differential backup<br>
options.set_reference(my_arch);<br>
      <br>
&nbsp;&nbsp; // as we are now used to options, we will set a more<br>
&nbsp;&nbsp; // complex set of other options:<br>
options.set_selection(not_mask(simple_mask("*~")));<br>
options.set_empty_dir(true);<br>
options.set_compression(bzip2);<br>
options.set_compr_mask(not_mask(simple_mask("*.bz2")));<br>
options.set_cache_directory_tagging(true);<br>
options.set_slice_permission("0600");<br>
options.set_slice_user_ownership("root");<br>
options.set_slice_group_ownership("bin");<br>
options.set_crypto_algo(crypto_blowfish);<br>
&nbsp; // if not specified with set_crypto_pass() the password<br>
&nbsp; // will be asked interactively to the user<br>
options.set_slicing(100000000, 20480);<br>
&nbsp;
      <br>
libdar::archive *my_other_arch = <br>
&nbsp; &nbsp;&nbsp; new libdar::archive(dialog, <br>
&nbsp;&nbsp;&nbsp; &nbsp;"/home",&nbsp; // saving all under this "root"<br>
&nbsp;&nbsp;&nbsp; &nbsp;"/tmp",&nbsp;&nbsp; // where the slices will go<br>
&nbsp;&nbsp;&nbsp; &nbsp;"my_archive", //
the basename of the slices <br>
&nbsp;&nbsp;&nbsp; &nbsp;"dar", // dar's slice extensions<br>
&nbsp;&nbsp;&nbsp;&nbsp; options, // the optional parameter as defined above</code><code></code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp; NULL); // no progressive report</code><br>
      </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code>archive_options_create options;<br>
<br>
&nbsp;&nbsp; // we provide here the reference to an <br>
&nbsp;&nbsp; // existing archive object, this implies that<br>
&nbsp;&nbsp; // the archive will be a differential backup<br>
options.set_reference(my_arch);<br>
<br>
&nbsp;&nbsp; // as we are now used to options, we will set a more<br>
&nbsp;&nbsp; // complex set of other options:<br>
options.set_selection(not_mask(simple_mask("*~")));<br>
options.set_empty_dir(true);<br>
options.set_compression(bzip2);<br>
options.set_compr_mask(not_mask(simple_mask("*.bz2")));<br>
options.set_cache_directory_tagging(true);<br>
options.set_slice_permission("0600");<br>
options.set_slice_user_ownership("root");<br>
options.set_slice_group_ownership("bin");<br>
options.set_crypto_algo(crypto_blowfish);<br>
&nbsp; // if not specified with set_crypto_pass() the password<br>
&nbsp; // will be asked interactively to the user<br>
options.set_slicing(100000000, 20480);</code><code><br>
      <br>
      </code><code></code>
      <code><span class="el">libdar::archive *my_other_arch
=&nbsp;&nbsp;&nbsp;&nbsp; <br>
&nbsp;&nbsp;&nbsp;&nbsp; libdar::create_archive_noexcept(dialog,</span></code><span class="el"><code>&nbsp; <br>
&nbsp;&nbsp;&nbsp;&nbsp; "/home",&nbsp; // saving all under this "root"<br>
&nbsp;&nbsp;&nbsp; &nbsp;"/tmp",&nbsp;&nbsp; // where the slices will go<br>
      </code></span><span class="el"><code><span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp; my_arch,&nbsp; //
differential backup </span></code></span><span class="el"><code><br>
&nbsp;&nbsp;&nbsp; &nbsp;"my_archive", //
the basename of the slices <br>
&nbsp;&nbsp;&nbsp; &nbsp;"dar", // dar's slice extensions<br>
&nbsp;&nbsp;&nbsp;&nbsp; </code></span><code>options, // the optional parameter as defined above</code><span class="el"><code><br></code></span><span class="el"></span><span class="el"><code>&nbsp;&nbsp;&nbsp;&nbsp; exception,
// thisgives the status of the call<br>
&nbsp;&nbsp;&nbsp;&nbsp; except_msg); // and in case of error the cause.<br>
      <br>
if(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt;
std::endl;<br>
      <br>
      </code></span> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">As previously, my_other_arch is
a write only object that we won't need
anymore. So we destroy it: </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code><br>
&nbsp;&nbsp;&nbsp;&nbsp; delete my_other_arch;<br>
      <br>
      </code> </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code><br>
libdar::close_archive_noexcept(my_other_arch,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; exception,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; except_msg);<br>
      <br>
      </code><span class="el"><code>if(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt;
std::endl;<br>
      <br>
      </code></span> </td>
    </tr>
  </tbody>
</table>
<br>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: justify;">We are
at the end of this first part of the tutorial, where we have
seen the general way to manipulate dar archives like dar command-line
does. But we still have an object we need
to destroy to cleanly release the memory used:<br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code><br>
&nbsp;&nbsp;&nbsp;&nbsp; delete my_arch;<br>
      <br>
      </code> </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code><br>
libdar::close_archive_noexcept(my_arch, exception,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; except_msg);<br>
      <br>
      </code><span class="el"><code>if(exception != LIBDAR_NOEXCEPT)<br>
&nbsp; std::cout &lt;&lt; "an error occurred: " &lt;&lt; except_msg <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;&lt;
std::endl;<br>
      <br>
      </code></span> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">For more detailed information
about the API you can build the API
documentation from the source code using Doxygen or get it online from <a href="http://dar.linux.free.fr/doc/man/index.html">dar home page</a> or <a href="http://dar.sourceforge.net/doc/man/index.html">mirror site</a>.<br>
      <br>
      <br>
      <h2>12 - Compilation &amp; Linking<br>
      </h2>
      <h3>Compilation</h3>
All the symbols found in the libdar API are defined via <span style="font-style: italic; font-weight: bold;">&lt;dar/libdar.h&gt;</span>
so you should only need to include this header.<br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><br>
      <code></code>&gt; cat my_prog.cpp<span style="font-weight: bold;"><br>
#include &lt;dar/libdar.h&gt;</span><br>
      <br>
main()<br>
{<br>
&nbsp;&nbsp; libdar::get_version(...);<br>
&nbsp;&nbsp; ...<br>
}<br>
&gt; gcc -c my_prog.cpp<br>
      <br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h3><br>
      </h3>
      <h3>Linking</h3>
      <br>
Of course, you need to link your program with libdar. This is done by
adding <span style="font-style: italic; font-weight: bold;">-ldar</span>
plus other library libdar can be built to use like libz, libbzip2, liblzo or libgcrypt :<code></code><code></code> <code>&nbsp; </code> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code></code><code></code><span style="font-weight: bold;"></span><br>
&gt; gcc <span style="font-weight: bold;">-ldar</span> -lz -lbzip2 -llzo -lgcrypt my_prog.o -o
my_prog<br>
      <br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h3>Libdar's different flavors</h3>
      <br>
      <div style="text-align: justify;">Well, all the compilation and
linking
steps described above assume you
have a "<span style="font-style: italic;">full</span>" libdar library.
Beside the <span style="font-style: italic;">full</span> (alias <span style="font-style: italic;">infinint</span>) libdar flavor, libdar
also comes in 32 and 64 bits
versions. In these last ones, in place of internally relying on a
special type (which
is a C++ class called<span style="font-style: italic;"> infinint</span>)
to
handle arbitrary large integers, libdar32 relies on 32 bits integers
and
libdar64 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.<br>
      </div>
      <br>
      <div style="text-align: justify;">These different libdar
versions can
coexist on the same system, they
share the same include files. But the MODE macro must be set to 32
or 64 when compiling for linking with libdar32 or libdar64
respectively. The MODE macro defines the way the "<span style="font-style: italic;">class infinint" </span>type is
implemented in libdar, and thus changes the way the libdar headers
files are interpreted by the compiler. </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code></code>&gt;
cat my_prog.cpp<span style="font-weight: bold;"><br>
      </span>#include &lt;dar/libdar.h&gt;<br>
      <br>
main()<br>
{<br>
&nbsp;&nbsp; libdar::get_version(...);<br>
&nbsp;&nbsp; ...<br>
}<br>
&gt; gcc -c <span style="font-weight: bold;">-DMODE=32</span>
my_prog.cpp<br>
      <br>
      <code></code><code></code><span style="font-weight: bold;"></span><br>
&gt; gcc <span style="font-weight: bold;">-ldar32</span> my_prog.o -o
my_prog<br>
      <br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; margin-right: auto; margin-left: auto; text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">and replace 32 by 64 to link
with libdar64. <br>
      <br>
      <div style="text-align: justify;">Note that libdar*.pc files are
installed in the <span style="font-style: italic;">$(PREFIX)/lib/pkgconfig</span>
file that should simplify (depending on the point of view) all these
operations.
For example, if you have all different flavors of libdar installed, the
      <span style="font-style: italic;">$(PREFIX)/lib/pkgconfig</span>
dir will contain (among other files) the three
following ones:<br>
      </div>
      <ul>
        <li>libdar.pc</li>
        <li>libdar32.pc</li>
        <li>libdar64.pc</li>
      </ul>
      <div style="text-align: justify;">Thus, if you want to build your
application with libdar32 for example, you will have to call (assuming
you have <span style="font-style: italic;">pkg-config</span> installed)<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code></code>&gt;
gcc <span style="font-weight: bold;">`pkg-config --cflags libdar32`</span>
-c
my_prog.cpp<br>
      <br>
      <code></code><code></code><span style="font-weight: bold;"></span><br>
&gt; gcc <span style="font-weight: bold;">`pkg-config --libs libdar32`</span>
my_prog.o -o
my_prog<br>
      <br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><br>
      <br>
      <br>
      <h2>13 - Aborting an Operation</h2>
      <div style="text-align: justify;">If the POSIX thread support is
available,<span style="font-style: italic;"> libdar</span> will be
built in a
thread-safe manner, thus you may have several thread using libdar calls
at the same time. 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 in a critical section and had not
got&nbsp; the opportunity to release a <span style="font-style: italic;">mutex</span>.
For that reason, libdar proposes a set
of calls to abort any processing libdar call which is ran by a given
thread. <br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code></code>&nbsp;&nbsp;
      <span style="font-style: italic;"></span>&nbsp; // next is the
thread ID in which we want to have
lidbar call canceled<br>
&nbsp;&nbsp;&nbsp; // here for simplicity we don't describe the way the
ID has been obtained<br>
pthread_t thread_id = 161720;<br>
&nbsp;&nbsp; <br>
&nbsp;&nbsp;&nbsp; // the most simple call is :<br>
libdar::cancel_thread(thread_id);<br>
&nbsp;&nbsp; // this will make any libdar call in this thread be
canceled immediately<br>
      <br>
&nbsp;&nbsp; // but you can use something a bit more interesting:<br>
libdar::cancel_thread(thread_id, false);<br>
&nbsp;&nbsp; // this second argument is true for immediate cancellation,<br>
&nbsp;&nbsp; // of false for a delayed cancellation, in which case
libdar
aborts the operation<br>
&nbsp;&nbsp; // but produces something usable, for example, if you were
backing up something<br>
&nbsp;&nbsp; // you get a real usable archive which only contains
files saved so far, in place<br>
&nbsp;&nbsp; // of having a broken archive which miss a catalogue at
the end. Note that this<br>
&nbsp;&nbsp; // delayed
cancellation needs a bit more time&nbsp; to complete, depending on the<br>
&nbsp;&nbsp; // size of the archive
under process.<br>
      <br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">As seen above, cancellation can
be
very simple. What now succeeds when
you ask for a cancellation this way? Well, an exception of type <span style="font-weight: bold; font-style: italic;">Ethread_cancel</span>
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.<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(153, 255, 255); width: 50%;"><code>try<br>
{<br>
&nbsp; &nbsp; </code><code>libdar::archive *my_arch =<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; new
libdar::archive(...);<br>
&nbsp;&nbsp;&nbsp; ...<br>
}<br>
catch(libdar::Ethread_cancel &amp; e)<br>
{<br>
&nbsp;&nbsp;&nbsp; ... do something when thread has been canceled;<br>
}<br>
      <br>
      </code><code> </code><br>
      </td>
      <td style="vertical-align: top; background-color: rgb(153, 255, 153); width: 50px;"><code></code><code><br>
      </code><code>U_16 ex;<br>
std::string msg;<br>
      <span class="el"></span></code><span class="el"><span class="el"><span class="el"><code>archive *my_arch =<br>
&nbsp;&nbsp; libdar::open_archive_noexcept(...,ex,msg);<br>
      <br>
switch(ex)<br>
{<br>
case ...<br>
&nbsp; .... <br>
&nbsp; break;<br>
case LIBDAR_THREAD_CANCEL:<br>
&nbsp; ... do something when thread has been canceled<br>
&nbsp; break;<br>
case ...<br>
}<br>
      <br>
      </code></span></span></span> </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">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.<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);">&nbsp;pthread_t
tid;<br>
&nbsp;&nbsp; <br>
&nbsp;&nbsp; // how to know if the thread <span style="font-style: italic;">tid</span> is under cancellation process ?<br>
if(<span style="font-weight: bold;">libdar::cancel_status</span>(tid))<br>
&nbsp;&nbsp;&nbsp;&nbsp; cout &lt;&lt; "thread cancellation is under
progress for thread : " &lt;&lt; tid &lt;&lt; endl;<br>
else<br>
&nbsp;&nbsp;&nbsp;&nbsp; cout &lt;&lt; "no thread cancellation is under
progress for thread : " &lt;&lt; endl;<br>
      <br>
&nbsp;&nbsp; // how to cancel a pending thread cancellation ?<br>
if(<span style="font-weight: bold;">libdar::cancel_clear</span>(tid))<br>
&nbsp;&nbsp;&nbsp; cout &lt;&lt; "pending thread cancellation has been
reset, thread " &lt;&lt; tid &lt;&lt; " has not been canceled" &lt;&lt;
endl;<br>
else<br>
&nbsp;&nbsp; cout &lt;&lt; "too late, could not avoid thread
cancellation for thread "&lt;&lt; tid &lt;&lt; endl;<br>
      <br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">Last point, back to the<span style="font-weight: bold; font-style: italic;"> Ethread_cancel</span>
exception, this class has two methods you may find useful, when you
catch it: </td>
    </tr>
  </tbody>
</table>
<br>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code></code>try<br>
{<br>
&nbsp;&nbsp; ... some libdar calls<br>
}<br>
catch(libdar::Ethread_cancel &amp; e)<br>
{<br>
&nbsp;&nbsp; if(e.<span style="font-weight: bold;">immediate_cancel</span>())<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cout &lt;&lt; "cancel_thread() has
been called with "true" as second argument" &lt;&lt; endl;<br>
&nbsp;&nbsp; else<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cout &lt;&lt; "cancel_thread() has been
called with "false" as second argument" &lt;&lt; endl;<br>
      <br>
&nbsp;&nbsp; U64 flag = e.<span style="font-weight: bold;">get_flag</span>();<br>
&nbsp;&nbsp;&nbsp; ... do something with the flag variable...<br>
}<br>
      <br>
&nbsp;&nbsp;&nbsp; // what is this flag stored in this exception ?<br>
&nbsp;&nbsp;&nbsp; // You must consider that the complete definition of
cancel_thread() is the following:<br>
&nbsp; &nbsp; // <span style="font-style: italic;">void
cancel_thread(pthread_t tid, bool immediate = true, U_64 flag = 0);<br>
&nbsp;&nbsp;&nbsp; </span>// thus, any argument given in third is
passed to the thrown Ethread_cancel exception, <br>
&nbsp;&nbsp;&nbsp; // value which can be retrieved thanks to its
get_flag() method. The value given to this<br>
&nbsp; &nbsp; // flag is not used by libdar itself, it is a facility
for user program to have the possibility <br>
&nbsp;&nbsp;&nbsp; // to include additional information about the
thread cancellation.<br>
      <br>
&nbsp;&nbsp;&nbsp; // supposing the thread cancellation has been
invoked by :<br>
libdar::cancel_thread(thread_id, true, 19);<br>
&nbsp;&nbsp; // then the<span style="font-style: italic;"> flag</span>
variable in the catch() statement above would have received<br>
      <div style="text-align: justify;">&nbsp;&nbsp; // the value <span style="font-style: italic;">19</span>.<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<div style="text-align: justify;"><br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">
      </div>
      <p style="text-align: justify;"><span style="font-weight: bold; text-decoration: underline;">A last and important point about multi-threaded environment: </span>An
object like any other variable cannot be modified or read (with the use
of its methods) without precaution from several threads at the same
time. Care must be taken to avoid this situation, and the use of Posix
mutex is recommanded in your program if you plan to let an archive
object be accessed by more than one thread. See the <a href="http://dar.sourceforge.net/doc/FAQ.html#threadsafe">FAQ</a> for more about this point.<br>
      </p>
      <br>
      <br>
      <br>
      <h2 style="text-align: justify;">14 - Dar_manager API</h2>

      <br>
      <div style="text-align: justify;">For more about <span style="font-style: italic;">dar_manager</span>, please read the&nbsp;<span style="font-style: italic;"></span>man page where are described in
detail the available features. Note that for <span style="font-style: italic;">dar_manager</span> there is not
a "<span style="font-style: italic;">without exception</span>" flavor,
your
program
must be able to handle exceptions, which by the way are the same as the
ones described above.<br>
      </div>
      <br>
      <div style="text-align: justify;">To get dar_manager features you
need to use the <span style="font-weight: bold; font-style: italic;">class
database</span>
which is defined in the <span style="font-style: italic;">libdar/database.hpp</span>
header file so you first need to include that file. Most of the methods of the <span style="font-style: italic;">database</span> class do use options. For the same reason as previously seen for <span style="font-style: italic;">archive</span> manipulation, these options are passed thanks to a container class. These container classes for options used by the <span style="font-style: italic;">database</span> class are defined in the<span style="font-style: italic;"> libdar/database_options.hpp</span> file. Let's see the
different method of the class <span style="font-style: italic;">database</span>
:<br>
      </div>
      <br>
      <h3>Database object construction</h3>
Two constructor are available: </td>
    </tr>
  </tbody>
</table>
<br>
</div>
<code></code><code></code>
<table style="width: 90%; height: 51px; text-align: left; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code>#include
&lt;dar/database.hpp&gt;<br>
      </code><code><span style="font-weight: bold;"></span><br>
void my_sample_function(user_interaction &amp; dialog)<br>
{<br>
&nbsp; &nbsp; database base; &nbsp; // we have created an empty
database (no archive in it) called "base"<br>
      <br>
&nbsp; &nbsp; database other&nbsp; = database(dialog,
"/tmp/existing_base.dmd", database_open_options());<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// we have created a database object called "other" which contains <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// (in RAM) all information that were contained in the <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// database file "/tmp/existing_base.dmd"<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// I will explain below the last argument<br>
      <br>
&nbsp;&nbsp;&nbsp; database_open_option opt;<br>
&nbsp;&nbsp;&nbsp; opt.set_partial(true);<br>
&nbsp;&nbsp;&nbsp; database other2 = database(dialog, "/tmp/existing_base.dmd", opt);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// we have created a database object called "other2" which differs<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// from "other" in the option we used. While "other" is a fully loaded <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// database, "other2" is a partial database. This notion is explained <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// below<br>
}</code> <br>
      <br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <div style="text-align: justify;">So far, this is not much
complicated.
You can build an empty database
from nothing, or load a database to memory from a file using the second
constructor. As you can see over the filename to give in this later
constructor, we need a <span style="font-style: italic;">user_interaction</span>
object to be able to inform the
user of any problem that could be met, and an object of class
database_open_options. This last object contains options to use for
this call (options are set to their default unless modified
explicitely). Currently, the only available option is the "partial"
option which is a boolean argument:<br>
      <br>
In all the available methods for class database, some require to load
the whole database in the memory while some other only require
the database header. Loading just the database header is much faster
than loading the whole database, of course, and as you guess it requires
much less memory. While you can perform any operation with a full
loaded database, only a subset of available method will be available
with a partially loaded database.&nbsp; If you try a method that
requires a completely loaded database, you will get an exception if the
object you use has been loaded with "true" as last argument (called
"partial") of the constructor, and of course an empty database (built
with the first
constructor) is a completely loaded database, so you don't have
restriction in using a new database object. <br>
      <br>
But now let's see the
available method for that class:<br>
      </div>
      <br>
      <h3>Database's methods <br>
      </h3>
First we will see methods that work with both partially and completely
loaded databases:<br>
      <ul>
        <li>dump(...) : it is used to write back the database to a
file. <br>
        </li>
        <li>change_name() : change the basename of the archive which
index is
given in argument</li>
        <li>set_path() : change the path to the archive which index is
given
in argument</li>
        <li>set_options() : change the default options to always pass
to dar
when performing restoration</li>
        <li>set_dar_path() : specify the path to dar (use empty string
to
rely on the PATH variable)</li>
        <li>show_contents() : list the archives used to build the
database</li>
        <li>get_options() : list the options that will be passed to dar
(as
defined with the set_options() method)</li>
        <li>get_dar_path() : return the path to dar (or empty string if
relying on the PATH variable)</li>
      </ul>
      <br>
Now let's see the database methods that only work with completely
loaded databases:<br>
      <ul>
        <li>add_archive() : add an archive to the database</li>
        <li>remove_archive() : remove an archive from the database</li>
        <li>set_permutation() : change archive relative order within
the
database</li>
        <li>show_files() : list the files which are present in the
given
archive<br>
        </li>
        <li>show_version() : list the archive where the given file is
saved</li>
        <li>show_most_recent_stats() :&nbsp; compute statistics about
the
location of most recent file versions</li>
        <li>restore() : restore a set of given files given in argument.</li>
      </ul>
      <div style="text-align: justify;">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 reference documentation of the
API. 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>. </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<hr style="width: 100%; height: 2px;"><br>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <h2>Thanks</h2>
      <br>
      <div style="text-align: justify;">I would like to thank Wesley
Leggette and Johnathan Burchill for having
given their feedback and
having done grammar corrections to this document. Out of this document,
I would also like to thanks them a second time for their work around
dar and libdar (Johnathan is the author of kdar, the KDE front-end for
dar).<br>
      </div>

      <br>
Regards,<br>
Denis Corbin.<br>
      </td>
    </tr>
  </tbody>
</table>
<br>
</center>


</body></html>