[Dar-libdar_api] API 3.x.x versus API 4.x.x about file filtering

[Denis C. <dar...@fr...>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hello,

I have noted a side effect for the addition of a new mask class in
libdar: the class "mask_list". This mask class takes a list of file to
match, from a given file, this list may contain relative path as well as
absolute paths (which is new to libdar).

To be able to compare absolute paths, the dar's root directory in which
takes place all the file operations when saving, extracting and
comparing, directory which is passed under the "fs_root" argument of the
corresponding methods of class archive, well, this root has to be
expanded to an absolute path when a relative path is given:

Assuming the current directory is /var/tmp and your program calls libdar
giving A/test as value to the "fs_root" argument (-R option for dar),
this argument will be expanded to /var/tmp/A/test inside libdar.

The side effect is that when scanning the directory tree the strings
passed to the mask for matching are no more of the type A/test/some/file
as it was in the API 3.x.x but /var/tmp/A/test/some/file.

The consequence is that when building the masks before calling libdar
for a call that uses the "subtree" argument you must consider this root
expansion to an absolute path. For example, the user gives:
~   fs_root = A/test  ([-R A/test] with dar)
~   current directory is /var/tmp
~   the user asked for excluding A/test/B subdirectory ([-P "B/toto"]
with dar).
~   then you must build mask that exclude "/var/tmp/A/test/B/toto"
instead of "A/test/B/toto". Note that you can still pass to libdar
relative paths as value for fs_root, it will be expanded by the value
returned by the getcwd() system call.

Last point concerns the op_listing() operation. This method does not
have a "fs_root" argument because no operation is done in the filesystem
(just listing the archive contents), however this methods *has* a
"subtree" argument, allowing one to prune some directories from the
listing. Masks must thus be done considering that a virtual "fs_root"
argument has been given the "<ROOT>" value. In consequence, masks will
be applied strings like "<ROOT>/some/files". This is not new, release
3.x.x had the same "feature", that no one seems to have noticed, since
graphical applications usually do not use the op_listing() method, but
prefer the get_children_of() method.

I have updated the api_tutorial with a similar note, and a sparse not in
the comments used for Doxygen.

Cheers,
Denis.

P.S.: nothing is changed for the selection arguments (-I, -X options for
dar) nor for the compression mask (-Y -Z options for dar).
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFDBkUnpC5CI8gYGlIRAsJqAKCGdGrhWV3A/90neJASDm61eXfr6QCgjB7d
+/GdzKxCxapLDftLyv7uqmo=
=RgO1
-----END PGP SIGNATURE-----