Contents
=========

   I - Introduction
  II - compilation
 III - linking
  IV - API usage
   V - API 2.0 prevision


   I - Introduction
====================

  The API is the APplication Interface. It is composed of a set of functions
present in the libdar library and available to external programs. The features
currently provided correspond the features of the dar program only. There is
actually nothing concerning dar_slave dar_xform or dar_manager functions.
This will maybe come in the future.

Unless you plan to add dar's feature to your software application (in
particular a Graphical User Interface), you are not concerned by Dar's API.

This documentation applies to API version 1.0. Version 2.0 is already planned,
and would add one initial argument to each calls of version 1.0. This argument
would be set by a initial "open" call, to open an archive for reading. A
"close" call would also be added to release memory allocated by the "open"
call. This open/close paradigm, would avoiding to your GUI reading the archive
several times when doing several operations like listing/restoring/isolating
on the same given archive. This would also open the door to thread safe
libdar library. Unfortunately, I discovered the limitations of version 1.0 a
bit late in the release cycle, thus, it will not be included in
dar_suite release 2.0.0, but in 2.1.0 which should follow one or two month
after 2.0.0. see last chapter below. You are welcome to express your comment
and needs as a GUI designer, on the libdar mailing list. The API version 2
is still under design at the time of the writing.

API version 1.
----------------
  
Actually, this API is written in C++. I don't exclude in the future to make a
wrapper to it, in pure ANSI C language. Still remains some problems about the
way to wrap the building of masks in C without loosing the ease of use.
For that reason, in the present documentation, I will help any developer
familiar with C and not C++ by providing a minimum documentation/hint about
C++ specificities that could help understand the way to use this API. The
necessary C++ basis to be able to use the API in C++ are not very difficult
to understand.

The API and libdar are built and installed with the dar package. Refer to the
README and INSTALL files for more information about the installation. In the
following we assume that the library and header files are properly installed
on your system.

  II - Compilation
===================

To access the API, you will need to include the following header file in your
program with the following statement:

        #include <dar/libdar.hpp>

if you have installed dar in a non conventional place, you'll rather need to
use
        #include "libdar.hpp"

and add to CPPFLAGS the following:

        -I<somewhere>/libdar

replacing <somewhere> by the path where has been installed the libdar headers
(if other than /usr/include/dar or /usr/local/include/dar). Also important, 
your compiler must be a C/C++ compiler to understand the class syntax (GNU g++
is the one I use with which you can also compile pure C ANSI code).

If you plane to compile against the libdar32 or libdar64 version (instead of
the infinint based default version), you need to add either -DMODE=32 or
-DMODE=64 to CPPFLAGS. The libdar32 is generated giving --enable-mode=32 to the
configure script in dar's package, and the libdar64 with --enable-mode=64.


 III - linking
===============

Once compiled of course you need to link generated object files (*.o) with
libdar among other library. This can be done as usual with something like:

        -ldar -lz -lbz2

But if as previously seen in II you have not installed dar in standard 
directory (like /usr/lib or /usr/local/lib ...) you need to tell where is 
located the library giving the following argument:

        -L<somwhere> -ldar -lz -lbz2

where <somewhereelse> is the path to libdar.a or libdar.so if available.

Note that if you use the libdar32 or libdar64 variant library, you must first 
compile your program giving -DMODE=32 or -DMODE=64 respectively and replace 
-ldar by one of the following line:

        -ldar32
or
        -ldar64

example of use:
compilation:
        g++ -DMODE=32   -c -o dar_test.o dar_test.cpp
linking:
        g++ dar_test.o -ldar32 -lz -lbz2 -o dar_test

 
  IV - API usage
=================
A - Overview
B - Prerequisite for the C++ version of the API
C - Dynamic memory allocation
D - Libdar user interaction calls
E - Libdar action calls
F - libdar exceptions


A - Overview
----------------

The API is a set of functions. These functions use several special types
in arguments, that will be described in the following. Quite all function
may also throw C++ exceptions, which must be trapped, to extract the nature of
the error. Theses exceptions, are also special types, also described bellow,
with some examples on how to easily "trap" them.


B - Prerequisite for the C++ version of the API
-----------------------------------------------

1 - namespaces
2 - introduction to C++ unfamiliar programmers
3 - Macros
4 - C++ classes
5 - standard C++ classes
6 - detailed list of classes brought by the API

1 - namespaces
................

All symbols provided by the C++ version of the API are enclosed in the
libdar namespace. The use of namespace avoids having name collisions between
symbols of the library and those of your program.

To access a symbol like a function you need to have to
either explicitly specify the namespace scope using the following form:

        variable = libdar::my_symbol(...);

or if you are sure that libdar symbol will not conflict with your own symbols,
"open" the namespace to your program, using the following statement required
once at the beginning of each file where you plane to use access libdar
symbols:

        using namespace libdar;

then you can directly access to libdar symbols:
        variable = my_symbol(...);
        variable2 = my_libdar_other_symbol(...);

without the need to explicitly specify the namespace. Note that if you want
to use this second form, what is required is that before all libdar symbol in
a file either in the file itself or in included files, figures the statement:

        #include "libdar.hpp"
        using namespace libdar;


2 - Introduction to C++ unfamiliar programmers
...............................................

In the API functions arguments, over the C++ standard types like "string", you
will find some others that are macro to C standard types, and some other that
are C++ classes. Don't be surprised by the following syntax if you are not
used by C++:

        const path & where

it is equivalent to:

        path where

path is an libdar API type, it can be substituted by a string or a char *
argument. See bellow for libdar classes descriptions.

3 - Macros
............

All the following macro concerns integers.

U_I stands for unsigned integer.
S_I stands for signed integer.

theses two types are used where the needed integer range is a lot bellow
integer limitation seen on many hosts (integer value can be encoded on 10 bits
for example).

Some other macro are also available, like U_32 for unsigned bit integer etc,
but they are not used at the API level, thus it is not recommended to use them
inside your own programs.

4 - C++ classes
................

C++ introduces classes. Classes define a type, from which variable are called
objects. However, this terms, you can use objects like any other variables as
well as classes as any other types. For your information, a C++ class is
defined a bit like a C structure, except the "struct" is replaced by the
"class" reserved word. C++ also bring an automatic typedef definition. In C
you would declare:

        struct toto
        {
          /* definition of the structure */
        };

and you would have the "struct toto" type available, If you would like to use
just toto for type name, you would need a typedef statement like this one:

        typedef struct toto toto;

C++ brings a bit more flexibility, the following declaration:

      class toto
      {
          /* definition of the class */
      };

allow you to use the "toto" symbol as well as the "class toto" syntax, without
any need of a typedef statement. In the following, when referring to a class we
will use the first syntax not mentioning the "class" reserved word.

At the difference with structures, class can own function as part of the
definition. Theses function are called "methods" to differentiate them from
functions outside of any class.

    class toto
    {
    public:
        int get_size();
 
    private:

        ...

    };

The previous class owns the get_size() method. It can be called on an object
of class toto this way:

        
    // declaring an object of class toto:
    toto my_variable;

    int val = my_variable.get_size();


A special type of method called constructors have the same name as the
name of the class they are part of. They are used to initialize an object
of that class.

    class titi
    {
        public:
            titi(int);
            titi(char *);
            titi(char *, long);

            /* a lot of other stuff */
    };

means that "titi" is a class that has three constructors. Thus, you can
initialize an object of class titi using three different ways. Using the
complete syntax you have:

        titi my_object1(19); 	    /* using int as argument */
        titi my_object2("bonjour"); /* using char * as argument */
        titi my_object3("coucou", 2); 
                                    /*using char * and long as arguments */

there is also a more simple notation when using single arguments constructors,
notation that you will see in the following of the documentation:

        titi my_object1 = 19;   /* using int as argument */
        titi my_object2 = "bonjour"; /* using char * as argument */
        titi my_object3("coucou", 2); 
                                         /* this cannot be written simpler */

note also that here we saw variable initialization (declaration + definition of
the value) which is not the same as variable assignment (change of the value
of an already existing value), but classes provided by libdar support both, 
thus you can use for example:

        titi my_object = 19; /* this is an initialization */
        my_object = "new value"; /* this is an assignment */

In all the classes needed by the API, you will quite only need to know how to
build objects, thus just need to use one of the few constructors of each
classes. You will rarely need to use the classes, and in any case you won't
need to know how they are implemented to understand how to use them.

In the following, I will thus just present the classes used in the API, with
description of what it does and what it is used for (for your own information),
and the way to build objects (i.e. to be used as arguments to API functions) of
that type. As I said, you will not need to know all the way to use each class,
but if you want you can still read the libdar code, there is I hope enough
comments to understand it.

Last note about comments in sources: ANSI C has only the /* and */ form to
insert comments, C++ adds the // form. All that follows this on a line is
considered as comments. I will sometimes use this in documentation, and quite
always in the sources, as its use is much lighter than the C ANSI form, but
both are available in C++.

IMPORTANT !
By default in the following (unless specified otherwise), all memory allocation
done by the libdar user, must be released by this user.


5 - standard C++ classes
.........................

There is one class that get often used is the string class. It is a
replacement for the char * type, which has for main advantage to manage any
memory allocation for you. You don't need to worry about memory, and can
concat, strip, or make any operation on them without memory consideration

But you could need for some reasons to convert string from char * and
vice-versa. Converting a char * to a string is easy:

        string toto = "my char * string is here";

will built a string variable named toto which value is "my char * string is
here". The opposite is less straight forward. Thus, I propose in libdar a tool
function that allocates memory for a char * (thus memory will have to be
released by the caller), and fills up the this memory by the corresponding
null terminated string.

        char * libdar_str2charptr(const string &x);

it returns NULL on failure else a newly allocated memory (using new operator
which thus be released by the caller using the delete operator).

        string var1 = "toto"; // var1 is a string variable
        char *var2 = tools_str2charptr(var1); 
                    // var2 is a pointer to a newly allocated
                    // memory filled by the "toto" null terminated string.
        if(var2 != NULL)
                delete var2; // here we release allocated memory.
        else
                // memory allocation problem.


6 - detailed list of classes brought by the API
.................................................
List Summary
- path
- compression
- infinint
- deci
- mask
- bool_mask
- simple_mask
- simple_path_mask
- regular_mask
- not_mask
- et_mask
- ou_mask


- path
the path class describes the path to a file. This class provides to libdar a
simple way to cut or build paths, as well as function to convert from and to
string.

A path argument can be initialized by a string or a char *. Thus you can give
a char * in place of a path argument, or if you prefer to build a path variable
use the following statement:

        char *example = "/toto/bonjour/les/amis";
        path mon_chemin = example;

        libdar_call(..., mon_chemin, ...);
          /* or much more simple, you can use */
      libdar_call(..., "/toto/bonjour/les/amis", ...); 


- compression
this is a C enumeration, that defines the compression algorithm to use.
Possible values are:
        
        none, gzip or bzip2.

        compression algo = none;

- infinint
infinint class is here to be able to use arbitrary length unsigned integers.
This type is used a lot inside libdar.

all standard *unsigned* integer types can be used to build an infinint, either
explicitly
        
        infinint my_int = 19;

or implicitly

        unsigned long toto = 19;
        libdar_call(..., toto, ...); 
                /* toto is in place of an infinint argument */

see the factoriel example program to see the power of infinint in action.

- deci
deci is a class that makes conversions from string to infinint and infinint
from string. It can be built either from a string or from an infinint.

        deci tmp1 = 19; // implicitly built from an infinint
        deci tmp2 = infinint(1024)*infinint(1024); 
                        // explicitly built from an infinint
        deci tmp3 = "1937474998709876875686587474674"; // built from a string

then it disposes of two methods, one to give the decimal string representation
and another to produce a infinint:

        tmp1.human(); // equals the string "19"
        tmp2.human(); // equals the string "1048576"
        tmp3.human(); // equals the string "1937474998709876875686587474674"

while
        
        tmp1.computer(); // is an infinint which value is 19;
        tmp2.computer(); // is an infinint which value is 1048576
        tmp3.computer(); // is an infinint which value is 1937474998709876875686587474674

if you want to display the statistics returned by some API functions
(see bellow), you can use the following statement to convert them to string:

assuming that "st" is a "struct statistics" variable, which saved field is of
type infinint, you could get the following:

        string result = deci(st.saved).human();

the string in turn can be converted in char * thanks to the libdar_str2charptr
function as seen above.

- mask
last be not least, the mask class. The use of this class is to check if a
character strings matches a wild card expression. The mask class by itself is
not usable, but rather is a type *over* the following classes, that all
inherit (and thus can be used in place) of the pure virtual class "mask".
Theses descendant classes are used to build the -I -X -Z -Y -P and [list of
path] arguments used on dar command line, but they can do much more, things
the command-line limitations avoids.

- bool_mask
this mask type is initialized by a boolean ("true" or "false") and is always
"true" or "false" whatever is the string it is check against. This are used
for example to save all files, or exclude no file, which is the default with
dar command line program. you can build a bool_mask variable this way:

        bool_mask my_mask1 = true;
        bool_mask my_mask2 = false; 

- simple_mask
this mask type receive a wild card exception (string or char *) which
is expended and compared using the fnmatch C library call, this is this
function the shells use to expand filename on the command-line (using the
* and ? wild cards in particular).

this mask is initialized by a string or a char * expression:

        simple_mask my_mask3 = "/home/*/.mozilla/Cache";


- simple_path_mask
this mask type receive a string or char *, which represent a path. The mask
matches any string that correspond to a subdirectory or directory leading
to that path. Let's take an example:

        simple_path_mask my_mask4 = "/dev/pts"

will match any subdirectory of /dev/pts (like /dev/pts/1) as well as /dev/pts
and /dev and / . this mask is used by dar command line for each member of the
[list of path].

- regular_mask
this mask receive a string or char *, which represent a regular expression to
be expended (see regexp standard library call). This mask is used internally
in libdar and has not much application in the API, but it exists and thus is
available.

        regular_mask my_mask5 = "/tmp/toto\\.[1-9][0-9]*\\.dar";

- not_mask
this is mask is the negation of the mask received in argument. Thus it does
not match all its argument does. When I said that it receive a mask in
argument I means any mask type seen before and seen below that inherit from
the "mask" virtual class. A not_mask can even take as argument another
not_mask, which however is not very useful. :-)

        simple_mask arg1 = "*.*.dar";
        no_mask my_mask6 = arg1;

here we have my_mask6 which is the negation of arg1. Thus my_mask6 will
match any string that is not of the type "*.*.dar" as would the shell
do against existing files.

- et_mask
this mask permits to make a logical AND ("et" means "and" in French) between
several other masks, whatever they are. The use is a bit different as
previously. First you need to build the object, with the only available
constructor which has no argument. Using one of the following statement
is possible:

        et_mask my_mask7;
or
        et_mask my_mask7 = et_mask();

then you need to add other masks thanks to the "add_mask" method which takes
a mask as argument:

        bool_mask my_mask8 = true;
        simple_mask my_mask9 = "*toto*";

        my_mask7.add_mask(my_mask8);
        my_mask7.add_mask(my_mask9);
        my_mask7.add_mask(regular_mask("[a-z]*"));

note that in the last "add_mask", we did not used a named variable to feed
the add_mask method, but rather build the object on the fly. This is a
common feature available also for constructors of other classes. In the
previous example, the mask my_mask7 would match any string that matches
each of the three mask added, thus any string that is only composed of
lowercase letters (regular_mask("[a-z]*")), *AND* that contains the string
"toto" (my_mask9). my_mask8 has no effect in the AND comparison as it
always succeeds (true).

- ou_mask
the ou_mask makes a logical OR ("ou" means "or" in French) between
several other masks. The syntax is similar to the syntax used
for the et_mask class (see above).

If you want to see masks in action, you can have a look at dar's file named
command_line.cpp


C - Dynamic memory allocation
-------------------------------

For some reasons, you may want to dynamically allocate memory for a given
variable. In pure C you have the malloc()/free() calls that let you do that.
But they cannot apply to objects. Thus for theses there is the new/delete
operators that have been added with C++. They can be used for any variable even
non object like "int". The important thing here is if you allocate memory
with malloc() you *must* release it with free(). And if you allocate memory
with "new" it must be released using "delete".

"new" and "delete" have their own syntax:

        int *ptr = new int;

is the equivalent to

        int *ptr = (int *)malloc(sizeof(int));


and
        delete ptr;

is the equivalent to
        
        free(ptr);

as with malloc(), if memory could not be allocated with "new" (because of a
lack of free memory), the NULL value is returned.
        
if you want to allocate a table, you have to use the following syntax:

        char *ptr = new char[10];

which is equivalent to

        char *ptr = (char *)malloc(10*sizeof(char));

now, using classes, the syntax is the same:

        bool_mask *my_ptr = new bool_mask(true);

which cannot be done by malloc().

        et_mask *my_other_ptr = new et_mask();

then you have the following syntax to access methods:

        my_other_ptr->add_mask(simple_path_mask("/dev/pts"));

or if you prefer more complicated things:
        
        (*my_other_ptr).add_mask(simple_path_mask("/dev/pts"));

which syntax you should already have met when dynamically allocating
structures.

Note that if you give a dynamically allocated mask as argument to et_mask or
ou_mask, you must release its memory after use :


        simple_path_mask *ptr = new simple_path_mask("/dev/pts");
        et_mask toto;

        if(ptr != NULL)
        {
                toto.add(*ptr);
                delete ptr;   // the user releases the allocated memory
        }
        else // dynamic allocation failed
           return -5 // or other mean to report an error
        
        my_libdar_call(..., ..., toto, ...);


D - Libdar user interaction calls
------------------------------------
- Dar's Version
- User interaction
- Getting compile time feature status

- Dar's Version
.................

The first and mandatory call to do is to check against library version with

        void get_version(U_I & major, U_I & minor)

One could use the following code:
 
        U_I maj, min;
        et_version(maj, min);
        if(maj != LIBDAR_COMPILE_TIME_MAJOR)
                // abort the program, we are not using the correct library
        else
                // that's OK. we use a compatible libdar version
  
The get_version() call set the value to two numbers. Major and Minor.
Two libraries with different major version have non ascendant difference in the
specification of the API. Thus a client application must check that
the major version is EXACTLY the same number as the version it has been built
for, which can be easily done using the LIBDAR_COMPILE_TIME_VERSION macro
defined in the libdar's headers.


          -------------------------------------------------
          |                                               |
          |             !!! WARNING !!!                   |
          |                                               |
          |   NO ASCENDING OR DESCENDING COMPATIBILITY    |
          |              MUST BE ASSUMED                  |
          |     BETWEEN TWO DIFFERENT MAJOR VERSIONS      |
          |                   OF                          |
          |               LIBDAR API !                    |
          |                                               |
          -------------------------------------------------


Thus, a wrong major version, could make a program calling a libdar function
with a wrong number of argument, or a wrong argument type leading to a stack
corruption or a memory fault, for example. The minor version instead, is here
to trace the libdar version a given application is linked with. Two libdar
version with same major number but different minor version can be used the
same. This does not say that libdar maintainer will not do all the necessary
to not lead the API change with as much as possible ascending compatibility,
in which case major number of the library would not change. But, it is not
possible to assume that ascending compatibility will be possible nor a good
choice face to new needs that are even not yet defined.

- User interaction
....................

The following function are also important and mandatory, they define how you
want the libdar library to interact with the user. There is two main
interactions:

- the warning to the user.
- the question to the user.

suppose the libdar user (i.e.: the programmer) defines the following call:

        void my_warning_callback(const string & x);

it would have to say libdar to use it as warning callback this way:

        set_warning_callback(&my_warning_callback);

this way, each time the libdar needs to communicate a warning to the user
it would rely on the "my_warning_callback" to display the warning given in
argument.

same thing with the question to the user, at the difference that the
callback function must return a boolean. As previously let's take an example,
the libdar user (i.e.: the programmer) defines the following callback:

        bool my_question_callback(const string & x);

it would have to say libdar to use it as question callback this way:

        set_answer_callback(&my_question_callback);

this way, each time the libdar needs an answer from the user it would
call "my_question_callback" giving in argument the text of the question,
and getting the returned value as the answer of the user.

one of each callback function must be defined before being able to use the
following action functions.

You can have a look at the shell_interaction.hpp/cpp module of dar command
line sources, that defines dar command-line's callback functions.

- Getting compile time feature status
.........................................

you can retrieve state of compilation time feature thanks to the following
call:

        void get_compile_time_feature(bool & ea, bool & largefile, bool & nodump);

for those not familiar with C++ the & in the argument line means that the
argument to give is a variable that will be modified by the call. In pure C
one would use a "bool * ea" statement in the declaration, and the user
would have to give the address of the variable "...feature(&my_ea_var,...".
here things are simpler :

        bool ea, largefile, nodump;

        get_compile_time_features(ea, largefile, nodump);
        
        if(ea)
                //  display EA support activated at compile time
        else
                // do other thing

        // an so on.


E - Libdar action calls
-------------------------

Dar command-line is able to perform 6 different operations:
- create an archive
- extract data from an archive
- list archive contents
- test an archive integrity
- compare an archive with a filesystem
- isolate a catalogue of an archive

for each action is defined a function in the API, which we will
revue, detailing and explaining its arguments,
and giving the command-line option that correspond to each argument.

- CREATION
.............

the function's name is op_create
and receive the following arguments in this order:

        const path &fs_root,
this is the path for the subdirectory to save (-R option)

        const path &sauv_path,
this is the path to where archive slices will be created

        const path *ref_path,
this is the path of the archive of reference. If this
pointer is set to NULL, then it is assumed that no reference
is given and that a full backup must be performed. (-A option)

        const mask &selection,
this is the mask of the files to save. (-I and -X options).
this mask is applied only to filename (not including path)
and does not concerns directories' names. If you want
to include any files you could give "bool_mask(true)" as value,
but you could also build something much more complex than
-I/-X paradigm using any combination of et_mask ou_mask,
not_mask, etc.

        const mask &subtree,
this mask applied to any file including path part.
(-P option and [list of path]). As above, if you want
to include all files, you can use "bool_mask(true)" as argument,
but could also give something more complex than the
-P/[list of path] paradigm.

        const string &filename,
this is the basename of the archive (With sauv_path
--- see above --- it makes the argument given to -c option).

        const string & extension,
this is the extension to the archive. It is left as parametrable,
but is is strongly recommended to always use "dar" as argument.

        const string *ref_filename,
this is the basename of the archive of reference. If ref_path
is not NULL, then ref_filename must also not be NULL and if
ref_path is NULL, ref_filename must also be NULL (the
combination of theses two arguments makes the -A option).

        bool allow_over,
if set to true, overwriting slice is allowed, but a confirmation
is asked to the user first. If set to true, no overwriting is
allowed. (-n option = false).

        bool warn_over,
this option is only useful if overwriting is allowed. if set to
false it then avoids any complain before overwriting.
(-w option = false).

        bool info_details,
if set to true, display more information about what is done.
(-v options).
                
        bool pause,
if set to true, libdar pauses before writing a new slice. it also
pauses before the first slice, if the slices of the archive of
reference (if applicable), share the same path as the archive to be
created (-p option).

        bool empty_dir,
if set to true, any directory that get ignored by the subtree mask
is replaced by an empty directory (-D option).

        compression algo,
this is the compression algorithm to use:
none, gzip (-z option), bzip2 (-y option) are the only possible
values.

        U_I compression_level,
this is the compression level. Possible values are integers from
0 to 9.
        
        const infinint & file_size,
if set to zero, the archive will be generated in one slice. Else
if a strictly positive value is given, the archive will have slices
of that value in byte. Be aware that the slice header takes around
20 bytes, thus a value below 20 bytes will generate an error (-s option).

        const infinint & first_file_size,
defines the size in byte of the first slice. If set to zero, it is
assumed that the first slice has the same size of the following. Note
that if file_size = 0 first_file_size must also be equal to zero
(-S option).

        bool root_ea,
set to true, if you want to save root or system Extended Attributes.
Libdar must be compiled with Extended Attribute support activated.
(see -U option).

        bool user_ea,
set to true if you want to save user Extended Attributes. Libdar must
be compiled with Extended Attribute support activated. (see -u option).

        const string & input_pipe,
if the archive reference basename is "-" which means read the reference
archive using standard input/output (see dar_slave), specifying a string
other than "" (empty string), tells dar to read the given filename (named
pipe), in place of reading from stdin.

        const string & output_pipe,
if the archive reference basename is "-" which means read the reference
archive using standard input/output (see dar_slave), specifying a string
other than "" (empty string), tells dar to write order to dar_slave using
the given filename (named pipe), in place of writing them to stdout.

        const string & execute,
if a non empty string is given, dar will execute the given command after
each new slice created. This uses the % substitution as described in man
pages

        const string & execute_ref,
if a non empty string is given, dar will execute the given command before
requesting a new slice for the archive or reference, using % substitution
as described in man pages.

        const string & pass,
if a non empty string is given in argument, scramble the generated archive
with the given string (-K option).

        const string & pass_ref,
if a non empty string is given in argument, unscramble the archive of
reference with the given string (-J option).

        const mask &compr_mask,
the given mask only apply to filenames, and determines which files
must be compressed (-Z and -Y options).

        const infinint & min_compr_size,
this determines a minimal size (in bytes) for a file to be elected to
compression. file smaller will never be compressed (-m option).

        bool nodump,
if set to true, do not save files which have the ext2/3 nodump flag set.
This option is available if activated at compilation time. (--nodump option)

        bool ignore_owner,
if set, do not compare ownership of files between filesystem to be saved
and archive of reference (-O option).

        const infinint & hourshift,
if set to a positive value assumes two dates are identical if they differ
by an integer number of hour, which number is less or equal than hourshift
(-H option). this is used when comparing files for a differential backup.

this function returns a statistics C structure which interesting fields are:
        
        statistics st = op_create(...);

        st.treated              is the number inode saved
        st.hard_links   is the number of hard link recorded
        st.skipped              is the number of file not saved (no file change)
        st.errored              is the number of file failed to save (filesystem error)
        st.ignored              is the number of file excluded by any filter.
        st.deleted              is the number of file recored as deleted since reference backup
        st.ea_treated   is the number of file that get their EA saved.


- Extraction
...............
///////
// check the libdar.hpp file for up to date headers
// some minor changes may occur along the software cycle after documentation
// which is done as early as possible.
///////

extern statistics op_extract(const path &fs_root,
                             const path &sauv_path,
                             const mask &selection,
                             const mask &subtree,
                             const string &filename,
                             const string & extension,
                             bool allow_over,
                             bool warn_over,
                             bool info_details,
                             bool detruire,
                             bool only_more_recent,
                             bool restore_ea_root,
                             bool restore_ea_user,
                             const string &input_pipe,
                             const string &output_pipe,
                             const string & execute,
                             const string & pass,
                             bool flat,
                             bool ignore_owner,
                             const infinint & hourshift);

extern statistics op_diff(const path & fs_root,
                          const path &sauv_path,
                          const mask &selection,
                          const mask &subtree,
                          const string &filename,
                          const string & extension,
                          bool info_details,
                          bool check_ea_root,
                          bool check_ea_user,
                          const string &input_pipe,
                          const string &output_pipe,
                          const string & execute,
                          const string & pass,
                          bool ignore_owner);

extern void op_listing(const path &sauv_path,
                       const string & filename,
                       const string & extension,
                       bool info_details,
                       bool tar_format,
                       const string &input_pipe,
                       const string &output_pipe,
                       const string & execute,
                       const string & pass,
                       const mask &selection);

extern statistics op_test(const path &sauv_path,
                          const mask &selection,
                          const mask &subtree,
                          const string & filename,
                          const string & extension,
                          bool info_details,
                          const string &input_pipe,
                          const string &output_pipe,
                          const string & execute,
                          const string & pass);

extern void op_isolate(const path &sauv_path,
                       const path *ref_path,
                       const string & filename,
                       const string & extension,
                       const string *ref_filename,
                       bool allow_over,
                       bool warn_over,
                       bool info_details,
                       bool pause,
                       compression algo,
                       U_I compression_level,
                       const infinint &file_size,
                       const infinint &first_file_size,
                       const string &input_pipe,
                       const string &output_pipe,
                       const string & execute,
                       const string & execute_ref,
                       const string & pass,
                       const string & pass_ref);

F - libdar exceptions
------------------------

1 - exceptions types

        historically, all the dar code used exception to signal an unexpected
condition, this is the pure C++ way to replace error code as returned value.
This is much more powerful, but need a bit of practice. As all of libdar code
was part of dar, libdar also uses C++ exceptions.

First you will need to include "erreurs.hpp" header file. It defines the
exceptions hierarchy used by dar.

all exceptions type are inherited from the Egeneric pure virtual class. You
will rarely need to use it directly. It is like a template for other exceptions
in the way it defines for all the same way to interact with them. In 
particular, all the inherited exceptions types, use the

        string get_message();

method, which returns a string explaining the nature of the error. The 
inherited exceptions type are:
        
        Ememory : when virtual memory has been exhausted
        Ebug : when dar detected a condition that should never happen,
                  and which is mostly probably an internal bug
        Einfinint : arithmetic operation on infinint
        Elimitint : overflow in 32 or 64 bits integer when used in place if
                   infinint (--enable-mode=32 or 64 option passed to configure)
        Erange : an argument has been out of range (sometimes more general)
        Edeci : error while computing decimal representation of an infinint
        Efeature : a used feature is not yet implemented (was used in the
                    first releases, but not used anymore actually).
        Ehardware : hardware error (I/O error or the like)
        Euser_abort : user pressed escape after user interaction
        Edata   :  some file could not be restored/saved/tested/compared, etc.
        Escript : error in user script
        Elibcall : incorrect argument given to API call

        
2 - example of statement around
 
        an exception is thrown (or raised) by the program. It then breaks all
        current look, all current call to function, until it is caught.

        to catch an exception that could be thrown from a piece of code C++
        defines the following statement:

        try
        {
                some piece of code
        }
        catch(exception_type & object)
        {
               some code to manage the error
        }

        in a first time you thus could enclose each call to libdar this way:

        try
        {
             libdar::...
        }
        catch(Egeneric & e)
        {
            user_interaction_warning(e.get_message());
        }


3 - what could be the Pure C API
        
        but I admit, exception should not pass the API. Thus in version 2.0
        of the API, I will add the necessary statement for the API to catch
        any exception and convert them to error code identical to exit status
        code of the dar suite program (see man page). An specific API call
        would be present to let the API caller have more information about
        the last error, a bit like what is done with errno.


   V - API 2.0 prevision
==========================

the version 2.0 will bring the open/close paradigm.

two new calls will appear:

        <datastructure> *open_archive(const path &sauv_path,
                                      const path *ref_path,
                                      <open_mode> mode);

        void close_archive(<datastructure> *);

where <datastructure> is not defined actually (will contain catalogue and sar
informations at least). <open_mode> will be a enum defining if the open is
for reading or writing.

all existing calls of version 1.0 will receive an additional argument of type
<datastructure> * in first position, and other argument referring to archive
name/path will disappear.

it will then be possible to open an archive for listing then extract several
time without the big overhead of having to extract each time the archive and
ask the user for first and last slices.

Tree listing. I got feedback about another need, which is the possibility to
read the list of files in the given archive level by level (read the tree
in width rather than in deep). This would not require you to build all
Graphical Components each corresponding to a file, unless the user open
the directory tree. Thus I must find a simple way and a simple API interface
to provide this on demand directory listing. If you have some wishes you
are welcome to use the libdar mailing list:

        http://lists.sourceforge.net/lists/listinfo/dar-libdar_api

