From 76b1b8762db24d341e651e93a27ca708023c53c6 Mon Sep 17 00:00:00 2001 From: Denis Corbin Date: Fri, 12 Jul 2024 20:09:35 +0200 Subject: [PATCH 1/2] updating documentation and usage of class mask_list --- src/libdar/mask_list.hpp | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/libdar/mask_list.hpp b/src/libdar/mask_list.hpp index e3986c94..ddfc6e27 100644 --- a/src/libdar/mask_list.hpp +++ b/src/libdar/mask_list.hpp @@ -60,6 +60,16 @@ namespace libdar /// prefix should be either absolute, or path::FAKE_ROOT (if the operation /// does not involve an fs_root - testing, listing, merging operations for example) /// \param[in] include whether the mask_list is used for file inclusion or file exclusion + /// \note: WARNING: if "include is set to false, the mask must be negated by a not_mask(), + /// this is not performed here. Here the include/exclude only parameter changes the filter + /// internal "formula", but for historical reasons and by homogeneity with path base filtering + /// the mask negation is done outside the mask construction. In other words, the caller should + /// create the mask with the following statement either: + /// - not_mask(mask_list(, , , false)) + /// or + /// - mask_list(, , , true)) + /// and pass the resulting (eventually logically anded or ored with other masks to + /// libdar set_subtree() method of an archive_option_* class. mask_list(const std::string & filename_list_st, bool case_sensit, const path & prefix, bool include); mask_list(const mask_list & ref) = default; mask_list(mask_list && ref) = default; From aff8b467af895731cfb9938559e379c7ab618622 Mon Sep 17 00:00:00 2001 From: Denis Corbin Date: Sat, 13 Jul 2024 09:32:46 +0200 Subject: [PATCH 2/2] updating archive class method documentation --- src/libdar/archive.hpp | 77 +++++++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 35 deletions(-) diff --git a/src/libdar/archive.hpp b/src/libdar/archive.hpp index 9a12fecf..997b876b 100644 --- a/src/libdar/archive.hpp +++ b/src/libdar/archive.hpp @@ -90,16 +90,16 @@ namespace libdar /// \param[in] options optional parameters to use for the operation /// \param[out] progressive_report statistics about the operation, considering the treated files (nullptr can be given if you don't want to use this feature) /// \note the statistics fields used are: - /// - .treated: the total number of files seen - /// - .hard_link: the number of hard linked inodes - /// - .tooold: the number of files that changed at the time they were saved and that could not be resaved (due to repeat limit or byte limit) - /// - .skipped: number of files not changed (differential backup) - /// - .errored: number of files concerned by filesystem error - /// - .ignored: number of files excluded by filters - /// - .deleted: number of files recorded as deleted - /// - .ea_treated: number of entry having some EA - /// - .byte_amount : number of wasted bytes due to repeat on change feature - /// . + /// - treated: the total number of files seen + /// - hard_link: the number of hard linked inodes + /// - tooold: the number of files that changed at the time they were saved and that could not be resaved (due to repeat limit or byte limit) + /// - skipped: number of files not changed (differential backup) + /// - errored: number of files concerned by filesystem error + /// - ignored: number of files excluded by filters + /// - deleted: number of files recorded as deleted + /// - ea_treated: number of entry having some EA + /// - byte_amount : number of wasted bytes due to repeat on change feature + archive(const std::shared_ptr & dialog, const path & fs_root, const path & sauv_path, @@ -118,12 +118,11 @@ namespace libdar /// \param[in] options optional parameters to be used for the operation /// \param[out] progressive_report statistics about the operation, considering the treated files (nullptr can be given if you don't want to use this feature) /// \note the statistics fields used are: - /// - .treated: the total number of files seen - /// - .hard_link: the number of hard linked inodes - /// - .ignored: number of files excluded by filters - /// - .deleted: number of files recorded as deleted - /// - .ea_treated: number of entry with EA - /// . + /// - treated: the total number of files seen + /// - hard_link: the number of hard linked inodes + /// - ignored: number of files excluded by filters + /// - deleted: number of files recorded as deleted + /// - ea_treated: number of entry with EA archive(const std::shared_ptr & dialog, const path & sauv_path, @@ -144,6 +143,16 @@ namespace libdar /// \param[in] basename_dst the slices basename of the repaired archive /// \param[in] extension_dst the slices extension of the repaired archive /// \param[in] options_repair the set of option to use to write the repaired archive + /// \note the statistics fieds used are the same as the ones used for archive creation, + /// though no entry should be ignored as no file or path filtering exists for this + /// operation, and no skipped or tooold should increase as no comparison is performed to an existing + /// filesystem: + /// - treated: the total number of files seen + /// - hard_link: the number of hard linked inodes + /// - errored: number of files concerned by filesystem error + /// - deleted: number of files recorded as deleted + /// - ea_treated: number of entry having some EA + /// - byte_amount : number of wasted bytes due to repeat on change feature archive(const std::shared_ptr & dialog, const path & chem_src, @@ -182,15 +191,15 @@ namespace libdar /// this should speed up the operation by a little amount. /// \return the statistics about the operation, considering the treated files /// \note the statistics fields used are: - /// - .treated: the total number of files restored - /// - .skipped: number of files not saved in the archive - /// - .tooold: number of file not restored due to overwriting policy decision - /// - .errored: number of files concerned by filesystem error - /// - .ignored: number of files excluded by filters - /// - .deleted: number of files deleted - /// - .hard_links: number of hard link restored - /// - .ea_treated: number of entry having some EA - /// . + /// - treated: the total number of files restored + /// - skipped: number of files not saved in the archive + /// - tooold: number of file not restored due to overwriting policy decision + /// - errored: number of files concerned by filesystem error + /// - ignored: number of files excluded by filters + /// - deleted: number of files deleted + /// - hard_links: number of hard link restored + /// - ea_treated: number of entry having some EA + statistics op_extract(const path &fs_root, const archive_options_extract & options, statistics *progressive_report); @@ -211,8 +220,8 @@ namespace libdar /// \param[in] options list of optional parameters to use for the operation /// \note if callback is nullptr (or NULL), the output is done using user_interaction provided with archive constructor /// \note alternative way to get archive contents: - /// . archive::get_children_of() method - /// . archive::init_catalogue()+get_children_in_table() + /// - archive::get_children_of() method + /// - archive::init_catalogue()+get_children_in_table() void op_listing(archive_listing_callback callback, void *context, const archive_options_listing & options) const; @@ -227,10 +236,9 @@ namespace libdar /// this should speed up the operation by a little amount. /// \return the statistics about the operation, considering the treated files /// \note the statistics fields used are: - /// - .treated: the total number of files seen - /// - .errored: number of files that do not match or could not be read - /// - .ignored: number of files excluded by filters - /// . + /// - treated: the total number of files seen + /// - errored: number of files that do not match or could not be read + /// - ignored: number of files excluded by filters statistics op_diff(const path & fs_root, const archive_options_diff & options, statistics * progressive_report); @@ -252,10 +260,9 @@ namespace libdar /// this way only you can be sure your archive is properly tested. /// \return the statistics about the operation, considering the treated files /// \note the statistics fields used are: - /// - .treated: the total number of files seen - /// - .skipped: number of file older than the one on filesystem - /// - .errored: number of files with error - /// . + /// - treated: the total number of files seen + /// - skipped: number of file older than the one on filesystem + /// - errored: number of files with error statistics op_test(const archive_options_test & options, statistics * progressive_report);