File: api_tutorial.html

package info (click to toggle)
dar 2.6.13-2
  • links: PTS
  • area: main
  • in suites: bullseye
  • size: 10,364 kB
  • sloc: cpp: 77,385; sh: 6,192; ansic: 776; makefile: 435; python: 242; csh: 95; perl: 43; sed: 16
file content (3358 lines) | stat: -rw-r--r-- 171,702 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
<!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 6.0.x and later<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 provides a
complete abstraction layer for handling <span style="font-style: italic;">Dar</span><em></em> archives. The general
operations provided are:</p>
      
      
      <ul style="text-align: justify;">
        <li>archive creation, </li>
        <li>file extraction from archive, </li>
        <li>archive listing, </li>
        <li>archive testing, </li>
        <li>archive comparison,</li>
        <li>catalogue isolation,</li>
        <li>archive merging,</li>
        <li>archive reparation<br>
        </li>
        <li>dar_manager database manipulations</li>
        <li>dar_slave steering</li>
        <li>dar_xform operation<br>
        </li>
      </ul>
      
      <div style="text-align: justify;">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> Commercial use is prohibited unless
a contract has been agreed with libdar's author.<br>
      </div>
      <div style="text-align: justify;"> <br>
      </div>
      <div style="text-align: justify;">This tutorial will show you how
to
use the libdar API.&nbsp; Since release 2.0.0 the <span style="font-style: italic;">dar</span> command-line executable also
relies on this API, looking at it's code may provide a good
illustration on the way to use libdar, the file <span style="font-style: italic;">src/dar_suite/dar.cpp</span>
is the primary consumer of the libdar API. <br>
      </div>
      <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> and is referred below as the <span style="font-style: italic;">API reference documentation</span>.<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, for other languages check for the
existing bindings, like for example the <a href="http://darbinding.sourceforge.net/">python bindings</a>.<br>
      </div>
      <span style="font-weight: bold;"><br>
Header files</span><br>
      <br>
Only one include file is required in your program to have access to
libdar:<br>
      <br>
      <div style="margin-left: 40px;"><span style="font-family: monospace;">#include &lt;dar/libdar.hpp&gt;</span><br>
      </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:<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(204, 204, 204);">
      <div style="margin-left: 40px;"><code>using
namespace libdar;</code><br>
      <code> </code><br>
      <code>get_version();</code><br>
      <code> </code></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; text-align: justify;">&nbsp;or,
as shown below, you can
explicitly use the namespace in front of libdar symbols, we will use
this notation in the following: </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>
      </code>
      <div style="margin-left: 40px;"><code>libdar::get_version();</code><br>
      <code> </code></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;">
      <h4>Exceptions<br>
      </h4>
      <div style="text-align: justify;">The library makes use of
exception to report unexpected conditions. These contain the reason and
context the error occurred in and can be caught by your code to display
this information. All exceptions used within libdar inherit from the
pure virtual class <span style="font-weight: bold;">libdar::Egeneric<br>
      </span><br>
Most of the time you will use only one of the following two methods:<br>
      <ul style="font-weight: bold;">
        <li><code>std::string &amp; get_message() const</code><br>
        </li>
        <li><code>std::string &amp; dump_str() const</code></li>
      </ul>
      <span style="font-weight: bold;">get_message() </span>returns a
message string describing the error met<br>
      <span style="font-weight: bold;">dump_str() </span>returns a
text paragraph with additional information about the stack as well as
context the error occurred in.<br>
      <br>
We will only focus on one specific exception type <span style="font-weight: bold;">libdar::Ebug</span> that is used within
libdar when <span style="font-style: italic;">a-situation-that-should-never-occur</span>
is met and is assumed to be a bug in libdar. Using the <span style="font-weight: bold;">get_message()</span> method in that
situation would not provide all necessary details to understand and fix
the bug, so it is advised to always use <span style="font-weight: bold;">dump_str()</span> for that specific type of
exception.<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(204, 204, 204); width: 50%;">
      <div style="margin-left: 40px;"><code>try</code><br>
      <code>{</code><br>
      <code>&nbsp;&nbsp;&nbsp; // calls to libdar</code><br>
      <code>&nbsp;&nbsp; ...</code><br>
      <code>&nbsp;&nbsp;&nbsp; //</code><br>
      <code>}</code><br>
      <code>catch(libdar::Ebug &amp; e)</code><br>
      <code>{</code><br>
      <code>&nbsp;&nbsp;&nbsp; std::string msg = e.dump_str();</code><br>
      <code></code><br>
      <code>&nbsp;&nbsp;&nbsp; // do something with msg like for example:</code><br>
      <code>&nbsp;&nbsp;&nbsp; std::cerr &lt;&lt; msg </code><br>
      <code>}</code><br>
      <code>catch(libdar::Egeneric &amp; e)</code><br>
      <code>{</code><br>
      <code>&nbsp;&nbsp;&nbsp; std::string msg = e.get_message();</code><br>
      <code></code><br>
      <code>&nbsp;&nbsp;&nbsp; // do something with msg like for example</code><br>
      <code>&nbsp;&nbsp;&nbsp; std::cerr &lt;&lt; msg</code><br>
      <code>}</code><br>
      <code> </code></div>
      </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;">
      <h2>&nbsp;1 - First we must initialize libdar <br>
      </h2>
      <div style="text-align: justify;">the libdar initialization is
performed by calling the <span style="font-weight: bold;">libdar::get_version()</span>
function. <br>
      <br>
This function can be called several time though only once is necessary,
but this call has to complete before any other call to libdar. <br>
      </div>
      <div> </div>
      <br>
      <div style="text-align: justify;">In a <span style="font-weight: bold;">multi-thread context </span>libthreadar
initialization is not re-entrant. In other word the first call call to <span style="font-weight: bold;">libdar::get_version()</span> must complete
before any other call to libdar can take place. Once libdar&nbsp; has
been initialized, you can call <span style="font-weight: bold;">libdar::get_version()</span>
concurrently from several threads at the same time.<br>
      </div>
      <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(204, 204, 204); width: 50%;"><code><br>
      </code>
      <div style="margin-left: 40px;"><code><span style="font-family: mon;"><span style="font-weight: bold;"></span></span><span style="font-weight: bold;">libdar::get_version();</span></code><br>
      <code></code></div>
      <code><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>2 - We should prepare the end right now<br>
      </h2>
      <div style="text-align: justify;">Libdar used
some
data-structures (mutex, secured memory, etc.) that need to be released
properly before ending the program. It is important to invoke the
following function before exiting your program if you invoked
get_version() previously.<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="text-align: left; width: 90%; background-color: rgb(204, 204, 204);" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><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="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;"><span style="font-weight: bold; text-decoration: underline;">Note:</span> <span style="font-weight: bold;">closes_and_clean()</span>
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>
      </div>
      <br>
      <br>
All in one, at the highest level, you code should look like the following<br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="text-align: left; width: 90%; background-color: rgb(204, 204, 204);" border="1" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code><span style="font-weight: bold;"><br>
      </span></code>
      <div style="margin-left: 40px;"><code>try</code><br>
      <code>{<br>
&nbsp;&nbsp;&nbsp; <span style="font-weight: bold;">libdar::get_version();</span><br>
      </code><code>&nbsp;&nbsp;&nbsp; // calls to libdar<br>
&nbsp;&nbsp;&nbsp; // thing we will see in next</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...</code><br>
      <code>&nbsp; &nbsp;&nbsp; &nbsp; ...<br>
&nbsp;&nbsp;&nbsp;<span style="font-weight: bold;"> </span><br>
      </code><code>}</code><br>
      <code>catch(<span style="font-weight: bold;">libdar::Ebug &amp; e</span>)</code><br>
      <code>{</code><br>
      <code>&nbsp;&nbsp;&nbsp; std::string msg = <span style="font-weight: bold;">e.dump_str()</span>;</code><br>
      <code> </code><br>
      <code>&nbsp;&nbsp;&nbsp; // do something with msg like for example:</code><br>
      <code>&nbsp;&nbsp;&nbsp; std::cerr &lt;&lt; msg </code><br>
      <code>}</code><br>
      <code>catch(<span style="font-weight: bold;">libdar::Egeneric
&amp; e</span>)</code><br>
      <code>{</code><br>
      <code>&nbsp;&nbsp;&nbsp; std::string msg = <span style="font-weight: bold;">e.get_message()</span>;</code><br>
      <code> </code><br>
      <code>&nbsp;&nbsp;&nbsp; // do something with msg like for example</code><br>
      <code>&nbsp;&nbsp;&nbsp; std::cerr &lt;&lt; msg</code><br>
      <code>}<br>
      <br>
      </code><code><span style="font-weight: bold;">libdar::close_and_clean();</span></code><br>
      </div>
      <code style="font-weight: bold;"><br>
      </code></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;">
      <h2>3 - Intercepting signals</h2>
      <div style="text-align: justify;">libdar by itself does not make
use of any signal (see signal(2) and
kill(2)). However, gpgme library with which libdar may be linked with
in order to
support asymmetrical strong encryption (i.e. encryption using
public/private keys) may trigger the PIPE signal. Your application
shall thus
either ignore it (signal(SIGPIPE, SIG_IGN)) or provide an adhoc handle.
By default the PIPE signal leads the receiving process to terminate.<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>4 - Libdar classes<br>
      </h2>
The main components of libdar are four classes:<span style="font-weight: bold;"></span>
      <ul>
        <li><span style="font-weight: bold;">class libdar::archive</span>
to play with dar archives<br>
          <span style="font-weight: bold;"></span></li>
        <li><span style="font-weight: bold;">class libdar::database </span>to
play with dar_manager databases</li>
        <li><span style="font-weight: bold;">class libdar::libdar_slave</span>
to take the role of dar_slave<br>
        </li>
        <li><span style="font-weight: bold;">class libdar::libdar_xform</span>
to re-slice existing archives like dar_xform does</li>
      </ul>
In the following we will first see <span style="font-weight: bold;">class
libdar::archive</span> which will take most of our effort as other
classes which we will see at the end are very simple to use.<br>
      <br>
      <h2>5 - Multithreaded environment</h2>
      <div style="text-align: justify;">Except some specific cases that
will be mentioned, a given libdar object can only be manipulated by a
single thread. You can however perform several operations concurrently
from different thread, each having its own set of objects. Though, if
one
thread is creating an archive by mean of an first object and at the
same
time another thread by mean of a second object is trying to read the
same archive under construction, things might not work as expected. But this
is obvious considerations we will not dig any further assuming you
know what you are doing.<br>
      </div>
      <h2>6 - Let's create a simple archive</h2>
      <span style="font-weight: bold;"></span>Creating a <span style="font-weight: bold;">libdar::archive</span> object depending on
the constructor used, leads to either:<br>
      <ul>
        <li>the creation of a brand new archive on filesystem, thus
performing a backup (full, incremental, differential, decremental, ...)<br>
        </li>
        <li>the opening an archive existing on filesystem, for further
operation (listing,&nbsp; file restoration,&nbsp; archive testing,
archive difference, ...) <br>
        </li>
        <li>the merging two existing archives into a new one</li>
        <li>the reparation of an archive which catalogue is missing or damaged. The <span style="font-style: italic;">catalogue</span> (which means catalog in French) is the table of content of an archive.<br>
</li>
      </ul>
      <h3>6.1 - Basic archive creation</h3>
For <span style="font-weight: bold;">archive creation</span> the
constructor format is the following one:<br>
      <br style="font-weight: bold;">
      <code><span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
archive::archive(const std::shared_ptr&lt;user_interaction&gt; &amp;
dialog,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const path &amp; fs_root,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const path &amp; sauv_path,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const std::string &amp; filename,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const std::string &amp; extension,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const archive_options_create &amp; options,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
statistics * progressive_report);</span><br>
      <br>
      </code>For now we will left beside several parameters seen
in detail later:<br>
      <ul style="text-align: justify;">
        <li style="text-align: justify;"><span style="font-weight: bold;">dialog</span> can be set to <span style="font-weight: bold;">std::nullptr</span> for now, this means
that all interaction with the user will be done by mean of standard
input, output and error.</li>
        <li style="text-align: justify;"><span style="font-weight: bold;">fs_root</span> is the directory to take as
root of the backup. The <span style="font-weight: bold;">libdar::path</span>
class can be setup from a <span style="font-weight: bold;">std::string</span></li>
        <li style="text-align: justify;"><span style="font-weight: bold;">sauv_path </span>is the path where to
write the archive to, here also a <span style="font-weight: bold;">std::string</span>
will do the job</li>
        <li style="text-align: justify;"><span style="font-weight: bold;">filename</span> is the <span style="font-weight: bold;">slice name</span> of the archive to create</li>
        <li style="text-align: justify;"><span style="font-weight: bold;">extension</span> is the archive extension
to use. There is no reason to not use the string <span style="font-weight: bold;">"dar"</span> here</li>
        <li style="text-align: justify;"><span style="font-weight: bold;">options</span> is a class that carries all
optional parameters, it contains a <span style="font-weight: bold;">constructor
without argument</span> so all options are set to their default that way</li>
        <li style="text-align: justify;"><span style="font-weight: bold;">statistics</span> can
receive the address of an existing object that another thread can read
while a first one is doing a backup operation, we will see this feature
later on, but for now let's set this to a <span style="font-weight: bold;">null pointer</span> (i.e.: std::nullptr)<br>
</li>
      </ul>Once the object has been
created (the constructor has returned), the
archive operation has completed and a new file has been completely
written on disk.<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(204, 204, 204); width: 50%;">
      <div style="margin-left: 40px;"><code>libdar::archive
my_first_backup(nullptr,</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; "/home/me",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; "/tmp",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;
"first_backup",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;
"dar",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; archive_options_create(),</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; nullptr);<br>
      </code></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; text-align: justify;">Thus, the
previous command will create a single sliced archive "<span style="font-weight: bold;">first_backup.1.dar</span>" located under <span style="font-weight: bold;">/tmp</span>. It will contain the content of
the directory <span style="font-weight: bold;">/home/me</span>
and its sub-directories, without compression and without ciphering. You
have guessed compression, slicing, ciphering can be set by playing with
passing an adhoc <span style="font-weight: bold;">archive_option_create</span>
object to this archive constructor, we will see that later.<br>
      <br>
Once the object has been created there is only little thing we can do
with it, like archive listing or archive isolation. But archive
extraction, testing or diffing needs&nbsp; creating a object with a
"read" constructor first.<br>
      <br>
We could also have allocated the archive on the heap, in that case we
would have just added the <span style="font-weight: bold;">delete</span>
operation after the construction has ended:<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(204, 204, 204); width: 50%;">
      <div style="margin-left: 40px;"><code>libdar::archive*
my_first_backup = <span style="font-weight: bold;">new</span>
libdar::archive(nullptr,</code><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; <code>&nbsp;
&nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;
"/home/me",</code><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; <code>&nbsp; &nbsp; &nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; "/tmp",</code><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; <code>&nbsp;
&nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;
"first_backup",</code><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; <code>&nbsp; &nbsp; &nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp; "dar",&nbsp; </code><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;<code>&nbsp;
&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
archive_options_create(),</code><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;<code>&nbsp;
&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
nullptr);<br>
&nbsp; // we assume std::bad_alloc would be thrown if an allocation
problem had occurred<br>
&nbsp; // same thing if libdar throws an exception at constructor time,
the object would<br>
&nbsp; // not be created and would not have to be deleted.<br>
&nbsp; // So now we can delete the created object:<br>
      <br>
      <span style="font-weight: bold;">delete</span> my_first_backup;<br>
      </code></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;">
      <h3>6.2 - Progressive report</h3>
      <div style="text-align: justify;">During the operation we get
nothing shown unless an error occurs. To have more visibility on the
process we will use an <span style="font-weight: bold;">libdar::statistics</span>
object passed as last argument of this constructor. The useful method
of class libdar::statistics are:<br>
      <ul>
        <li>std::string <span style="font-weight: bold;">get_treated_str()</span><br>
        </li>
        <li>std::string <span style="font-weight: bold;">get_hard_links_str()</span>
          <br>
        </li>
        <li>std::string <span style="font-weight: bold;">get_skipped_str()</span><br>
        </li>
        <li>std::string <span style="font-weight: bold;">get_inode_only_str()</span><br>
        </li>
        <li>std::string <span style="font-weight: bold;">get_ignored_str()</span></li>
        <li>std::string <span style="font-weight: bold;">get_tooold_str()</span></li>
        <li>std::string <span style="font-weight: bold;">get_errored_str()
          </span><br>
        </li>
        <li>std::string <span style="font-weight: bold;">get_deleted_str()</span></li>
        <li>std::string <span style="font-weight: bold;">get_ea_treated_str()
          </span><br>
        </li>
        <li>std::string <span style="font-weight: bold;">get_byte_amount_str()</span></li>
        <li>std::string <span style="font-weight: bold;">get_fsa_treated_str()</span><br>
        </li>
      </ul>
If you have a doubt about the meaning and use of a particular counter
in a particular operation, please refer to API reference documentation of
class libdar::statistics, the private fields corresponding to these counter are
explicitly defined there.<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(204, 204, 204); width: 50%;">
      <div style="margin-left: 40px;"><code><span style="font-weight: bold;">libdar::statistics stats;</span><br>
      <br>
libdar::archive my_first_backup(nullptr,</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; "/home/me",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; "/tmp",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;
"first_backup",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;
"dar",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; archive_options_create(),</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; <span style="font-weight: bold;">&amp; stats</span>);<br>
      <br>
std::cout &lt;&lt; <span style="font-weight: bold;">stats.get_treated_str()</span>
&lt;&lt; " file(s) saved" &lt;&lt; std::endl;<br>
std::cout &lt;&lt; <span style="font-weight: bold;">stats.get_errored_str()</span>
&lt;&lt; " file(s) failed to backup" &lt;&lt; std::endl;<br>
std::cout &lt;&lt; <span style="font-weight: bold;">stats.get_ea_treated_str()</span>
&lt;&lt; " Extended Attributes saved" &lt;&lt; std::endl;<br>
      </code></div>
      </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;">
      <h3>6.3 - Archive creation options<br>
      </h3>
      <div style="text-align: justify;">in the previous example, we
have created an object of class <span style="font-weight: bold;">libdar::archive_options_create</span> and
passed it on-fly to the archive constructor without modifying it. Thus
we used the default options for this operations. But <span style="text-decoration: underline; font-weight: bold;">a lot</span>
of options are available, each one can be modified by a specific
method, you will quite never use all of them. Follow is a subset of the
available options. We won't details them all, but you can refer the doxygen
documentation of <span style="font-weight: bold;">class
libdar::archive_options_create</span> for more information.<br>
      </div>
      <ul>
        <li><code>void <span style="font-weight: bold;">set_reference</span>(<span style="font-weight: bold;">std::shared_ptr&lt;archive&gt; ref_arch</span>)</code></li>
        <li><code>void <span style="font-weight: bold;">set_selection</span>(const
          <span style="font-weight: bold;">mask</span> &amp; selection)</code></li>
        <li><code>void <span style="font-weight: bold;">set_subtree</span>(const
          <span style="font-weight: bold;">mask</span> &amp; subtree)</code></li>
        <li><code>void <span style="font-weight: bold;">set_allow_over</span>(bool
allow_over)</code></li>
        <li><code>void <span style="font-weight: bold;">set_warn_over</span>(bool
warn_over) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_info_details</span>(bool
info_details) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_display_treated</span>(bool
display_treated, bool only_dir) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_display_skipped</span>(bool
display_skipped)</code></li>
        <li><code>void <span style="font-weight: bold;">set_display_finished</span>(bool
display_finished) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_pause</span>(const
          <span style="font-weight: bold;">infinint</span> &amp; pause)
          <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_empty_dir</span>(bool
empty_dir)</code></li>
        <li><code>void <span style="font-weight: bold;">set_compression</span>(<span style="font-weight: bold;">compression</span> compr_algo)</code></li>
        <li><code>void <span style="font-weight: bold;">set_compression_level</span>(<span style="font-weight: bold;">U_I </span>compression_level)</code></li>
        <li><code>void <span style="font-weight: bold;">set_slicing</span>(const
          <span style="font-weight: bold;">infinint</span> &amp;
file_size, const <span style="font-weight: bold;">infinint</span>
&amp; first_file_size)</code></li>
        <li><code>void <span style="font-weight: bold;">set_ea_mask</span>(const
          <span style="font-weight: bold;">mask</span> &amp; ea_mask)<br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_execute</span>(const
std::string &amp; execute) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_crypto_algo</span>(<span style="font-weight: bold;">crypto_algo </span>crypto)</code></li>
        <li><code>void <span style="font-weight: bold;">set_crypto_pass</span>(const
          <span style="font-weight: bold;">secu_string</span> &amp;
pass)</code></li>
        <li><code>void <span style="font-weight: bold;">set_compr_mask</span>(const
          <span style="font-weight: bold;">mask</span> &amp;
compr_mask);</code></li>
        <li><code>void <span style="font-weight: bold;">set_min_compr_size</span>(const
          <span style="font-weight: bold;">infinint</span> &amp;
min_compr_size)</code></li>
        <li><code>void <span style="font-weight: bold;">set_nodump</span>(bool
nodump)</code></li>
        <li><code>void <span style="font-weight: bold;">set_exclude_by_ea</span>(const
std::string &amp; ea_name)</code></li>
        <li><code>void <span style="font-weight: bold;">set_what_to_check</span>(<span style="font-weight: bold;">comparison_fields</span> what_to_check)</code></li>
        <li><code>void <span style="font-weight: bold;">set_hourshift</span>(const
          <span style="font-weight: bold;">infinint</span> &amp;
hourshift)</code></li>
        <li><code>void <span style="font-weight: bold;">set_empty</span>(bool
empty) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_alter_atime</span>(bool
alter_atime)</code></li>
        <li><code>void <span style="font-weight: bold;">set_furtive_read_mode</span>(bool
furtive_read)</code></li>
        <li><code>void <span style="font-weight: bold;">set_same_fs</span>(bool
same_fs) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_snapshot</span>(bool
snapshot) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_cache_directory_tagging</span>(bool
cache_directory_tagging) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_fixed_date</span>(const
          <span style="font-weight: bold;">infinint</span> &amp;
fixed_date)</code></li>
        <li><code>void <span style="font-weight: bold;">set_slice_permission</span>(const
std::string &amp; slice_permission)</code></li>
        <li><code>void <span style="font-weight: bold;">set_slice_user_ownership</span>(const
std::string &amp; slice_user_ownership) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_slice_group_ownership</span>(const
std::string &amp; slice_group_ownership)</code></li>
        <li><code>void <span style="font-weight: bold;">set_retry_on_change</span>(const
          <span style="font-weight: bold;">infinint</span> &amp;
count_max_per_file, const <span style="font-weight: bold;">infinint</span>
&amp; global_max_byte_overhead)</code></li>
        <li><code>void <span style="font-weight: bold;">set_security_check</span>(bool
check) <br>
          </code></li>
        <li><code>void<span style="font-weight: bold;"> set_user_comment</span>(const
std::string &amp; comment) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_hash_algo</span>(hash_algo
hash)</code></li>
        <li><code>void <span style="font-weight: bold;">set_slice_min_digits</span>(<span style="font-weight: bold;">infinint</span> val) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_backup_hook</span>(const
std::string &amp; execute, const <span style="font-weight: bold;">mask</span>
&amp; which_files);</code></li>
        <li><code>void <span style="font-weight: bold;">set_delta_diff</span>(bool
val)</code></li>
        <li><code>void <span style="font-weight: bold;">set_delta_signature</span>(bool
val) <br>
          </code></li>
        <li><code>void <span style="font-weight: bold;">set_delta_mask</span>(const
          <span style="font-weight: bold;">mask</span> &amp; delta_mask)</code><br>
        </li>
      </ul>
First you may have find some strange types in arguments, we will
briefly explain how to set them:<br>
      <ul>
        <li><span style="font-weight: bold;">std::shared_ptr&lt;archive&gt;</span>
C++11 shared smart-pointer to an existing archive object. We will see
how to use it next when performing differential backup<br>
          <span style="font-weight: bold;"></span></li>
        <li><span style="font-weight: bold;">infinint</span> can be set
from a <span style="font-weight: bold;">classical unsigned int</span>,
unsigned long or other unsigned integer type</li>
        <li><span style="font-weight: bold;">mask</span> is a bit more
complex, we will see how to use it in a
specific paragraph of this tutorial</li>
        <li><span style="font-weight: bold;">compression</span> is an
enumeration with values like <br>
        </li>
        <ul>
          <li><code>libdar::compression::<span style="font-weight: bold;">gzip</span></code></li>
          <li><code>libdar::compression::<span style="font-weight: bold;">bzip2</span></code></li>
          <li><code>libdar::compression::<span style="font-weight: bold;">xz</span></code></li>
          <li><code>libdar::compression:<span style="font-weight: bold;">lzo</span></code></li>
        </ul>
        <li><span style="font-weight: bold;">U_I </span>is to be
considered an <span style="font-weight: bold;">unsigned int</span></li>
        <li><span style="font-weight: bold;">crypto_algo</span> is also
an enumeration with values like</li>
        <ul>
          <li><code>libdar::crypto_algo::<span style="font-weight: bold;">scrambling</span></code></li>
          <li><code>libdar::crypto_algo::<span style="font-weight: bold;">blowfish</span></code></li>
          <li><code>libdar::crypto_algo::<span style="font-weight: bold;">aes256</span></code></li>
          <li><code>libdar::crypto_algo::<span style="font-weight: bold;">twofish256</span></code></li>
          <li><code>libdar::crypto_algo::<span style="font-weight: bold;">serpent256</span></code></li>
          <li><code>libdar::crypto_algo::<span style="font-weight: bold;">camellia256</span></code></li>
        </ul>
        <li><span style="font-weight: bold;">secu_string</span> is a
class securely storing password and sensible cryptographic information.
It can be setup from a char* or from a filedescriptor. its main
constructor is:<br>
        </li>
        <ul>
          <li>secu_string(<span style="font-weight: bold;">const char*</span>
ptr, U_I <span style="font-weight: bold;">size</span>)</li>
        </ul>
        <li><span style="font-weight: bold;">comparison_fields</span>
is an enumeration with values like</li>
        <ul>
          <li><code>libdar::comparison_fields::<span style="font-weight: bold;">all</span></code></li>
          <li><code>libdar::comparison_fields::<span style="font-weight: bold;">ignore_owner</span></code></li>
          <li><code>libdar::comparison_fields::<span style="font-weight: bold;">mtime</span></code></li>
          <li><code>libdar::comparison_fields::<span style="font-weight: bold;">inode_type</span></code></li>
        </ul>
      </ul>
      </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); width: 50%;">
      <div style="margin-left: 40px;"><code><span style="font-weight: bold;"></span>libdar::archive_options_create <span style="font-weight: bold;">opt</span>;<br>
      <br>
      <span style="font-weight: bold;">opt</span>.set_allow_over(false);&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// forbids slice overwriting<br>
      <span style="font-weight: bold;">opt</span>.set_display_finished(true);&nbsp;
// show a summary after each completed directory<br>
      <span style="font-weight: bold;">opt</span>.set_slicing(1024000,
2000);&nbsp; // slices of 1000 kiB initial slice of 2000 bytes<br>
      <span style="font-weight: bold;">opt</span>.set_pause(2);&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// pause every two slices<br>
      <span style="font-weight: bold;">opt</span>.set_execute("echo
slice %N completed"); // command executed after each slice<br>
      <span style="font-weight: bold;">opt</span>.set_crypto_algo(libdar::crypto_algo::aes256);<br>
      <br>
      </code><code>&nbsp;// providing an empty secu_string leads dar
interactively ask the passphrase in a secure manner</code><br>
      <code><span style="font-weight: bold;">opt</span>.set_crypto_pass(secu_string());
      <br>
&nbsp;// this previous call is useless as en empty secu_string is the
default<br>
&nbsp;// though one could have setup a secu_string from a std::string
this way:<br>
std::string my_pass("hello world!");<br>
libdar::secu_string my_secupass(my_pass.c_str(), my_pass.size());<br>
      <span style="font-weight: bold;">opt</span>.set_crypto_pass(my_secupass);<br>
      <br>
      <span style="font-weight: bold;">opt</span>.set_compression(libdar::compression::xz);<br>
      <span style="font-weight: bold;">opt</span>.set_compression_level(9);&nbsp;&nbsp;
// this is the default<br>
      <span style="font-weight: bold;">opt</span>.set_min_compr_size(10240);&nbsp;
// not trying compressing file smaller than 10 kiB<br>
      <span style="font-weight: bold;"></span></code><code><br>
libdar::archive my_first_backup(nullptr,</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; "/home/me",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; "/tmp",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;
"first_backup",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;
"dar",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; <span style="font-weight: bold;">opt</span>,</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; nullptr);<br>
      </code></div>
      </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;"> Of course, you can use both <span style="font-weight: bold;">libdar::statistics</span> and <span style="font-weight: bold;">libdar::archive_options_create</span> at
the same time.<br>
      <br>
      <h2>7 - Creating a differential or incremental backup</h2>
      <div style="text-align: justify;">Maybe you have guessed?
Compared to the previous operation (full backup) doing an differential
or incremental backup will only ask to open in read-mode an existing
archive and pass this object as argument of class
archive_options_create::set_reference() seen just above.<br>
      <br>
The read-only constructor for class archive is the following:<br>
      <code><br>
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp; archive(const
std::shared_ptr&lt;user_interaction&gt; &amp; dialog,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const path &amp; chem,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const std::string &amp; basename,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const std::string &amp; extension,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const archive_options_read &amp; options);</span></code><br>
      <br>
same as before:<br>
      <ul>
        <li><span style="font-weight: bold;">dialog</span> can be set
to a <span style="font-weight: bold;">null pointer</span>, we will see
later on how to play with user_interaction class</li>
        <li><span style="font-weight: bold;">chem</span> is the path
leading to the archive to read, it can be provided as a <span style="font-weight: bold;">std::string</span></li>
        <li><span style="font-weight: bold;">basename</span> is the
archive basename to read</li>
        <li><span style="font-weight: bold;">extension</span> should be
          <span style="font-weight: bold;">"dar"</span> unless you want
to confuse people</li>
        <li><span style="font-weight: bold;">options</span> can be set
to an empty object for default options, we will see this class in more
details with archive listing</li>
      </ul>
      </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(204, 204, 204); width: 50%;">
      <div style="margin-left: 40px;"><code><span style="font-weight: bold;"></span>&nbsp; // first we open the
previously created archive in read mode:<br>
      <br>
std::shared_ptr&lt;libdar::archive&gt; <span style="font-weight: bold;">ref_archive</span>(<span style="font-weight: bold;">new</span> libdar::archive(nullptr,<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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"/home/me",<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;
"first_backup",<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;
"dar",<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; archive_create_options_read()));<br>
      <br>
&nbsp; // here we dynamically allocated the object to be able to setup<br>
&nbsp; // a shared_ptr in order to passed it to <br>
&nbsp; // the archive_options_create::set_reference() method:<br>
      <br>
      </code><code>libdar::archive_options_create <span style="font-weight: bold;">opt</span>;</code><code><br>
      <span style="font-weight: bold;">opt</span>.set_reference(<span style="font-weight: bold;">ref_archive</span>);</code><code><br>
      <span style="font-weight: bold;"></span></code><code><br>
libdar::archive my_second_backup(nullptr,</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; "/home/me",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp; "/tmp",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;
"diff_backup",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;
"dar",</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; <span style="font-weight: bold;">opt</span>,</code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; nullptr);<br>
      </code></div>
      </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;">creating a
incremental backup is exactly the same, the difference is the nature of
the archive of reference. We used to describe a differential backup
one that has a full backup as reference, while an incremental backup
has another incremental or differential backup as reference (not a full
backup).<br>
      <br>
      <h2>8 - Archive listing</h2>
Archive listing operation consist of the creation of an archive object
in read-mode as we just did above and invoking a method on that newly
object to see all or a sub-directory content of the archive. Before
looking at the listing method let's zoom on the class
libdar::archive_create_options_read we just skip over previously.<br>
      <br>
      <h3>8.1 - Archive reading options</h3>
&nbsp;The same as the class archive_options_create detailed above, the
class archive_options_read has a constructor without argument that sets
the different options to their default value. You can change them one
by one by mean of specific methods. The most usual ones are:<br>
      <ul>
        <li>void <span style="font-weight: bold;">set_execute</span>(const
std::string &amp; execute)</li>
        <li>void <span style="font-weight: bold;">set_info_details</span>(bool
info_details)</li>
        <li>void <span style="font-weight: bold;">set_sequential_read</span>(bool
val)</li>
        <li>void <span style="font-weight: bold;">set_slice_min_digits</span>(infinint
val)</li>
      </ul>
set_execute() has runs a command before reading a new slice of the
archive. See API reference documentation for details. You will meet
that class in order to test an archive, compare an archive with
filesystem, isolate an archive and repair an archive.<br>
      <br>
      <h3>8.2 - Listing methods</h3>
There is several way to read an given archive contents:<br>
      <ul>
        <li><code>void <span style="font-weight: bold;">op_listing</span>(archive_listing_callback
          <span style="font-weight: bold;">callback</span>,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
void *<span style="font-weight: bold;">context</span>,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const archive_options_listing &amp; <span style="font-weight: bold;">options</span>)
const;</code></li>
        <li><code>bool <span style="font-weight: bold;">get_children_of</span>(archive_listing_callback
          <span style="font-weight: bold;">callback</span>,<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;
void *<span style="font-weight: bold;">context</span>,<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;
const std::string &amp; <span style="font-weight: bold;">dir</span>,<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;
bool <span style="font-weight: bold;">fetch_ea</span> = false);</code></li>
        <li><code>const std::vector&lt;list_entry&gt; <span style="font-weight: bold;">get_children_in_table</span>(const
std::string &amp; dir, bool <span style="font-weight: bold;">fetch_ea</span>
= false) const</code></li>
      </ul>
      <span style="font-weight: bold;">archive::op_listing() </span>makes
use of a callback function that will be called in turn for <span style="text-decoration: underline;">each entry
of the archive</span> even special entries that flag the end of a directory and the next entry will be located in the parent directory.<br>
      <span style="font-weight: bold;">archive::get_children_of() </span>use
the same callback but only for the different <span style="text-decoration: underline;">entries of a given
directory</span>, that has to exist in the archive of course. It returns false
      when the end of the directory has been reached.<br>
      <span style="font-weight: bold;">archive::get_children_in_table()</span>
is like the previous <span style="text-decoration: underline;">listing a given directory</span> but returns a vector of objects <span style="font-weight: bold;">libdar::list_entry</span> that provide
detailed information about each entry, no callback is used here.<br>
      <br>
      <span style="font-weight: bold;">For the two first methods</span>
you have to define a callback function of the following form<br>
      <br>
      <div style="margin-left: 40px;"><code><span style="font-weight: bold;">void (*)(const std::string &amp; the_path,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const list_entry &amp; entry,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
void *context);</span></code><br>
      </div>
      <br>
This callback will receive as argument the full path of the object, a <span style="font-weight: bold;">libdar::list_entry</span> object providing
much details on it <span style="font-weight: bold;">and</span> the "context" value passed as argument of <span style="font-weight: bold;">archive::op_listing()</span> or <span style="font-weight: bold;">archive::get_children_of()<br>
      <span style="font-weight: bold;"><br>
      </span></span>Last point to see before going forward with an
example is this <span style="font-weight: bold;">libdar::list_entry </span>class,
we
will use here only a few of the rich set of fields/methods this class provides in the following examples:<br>
      <span style="font-weight: bold;"></span><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(204, 204, 204); width: 50%;">
      <div style="margin-left: 40px;">&nbsp; <code><span style="font-weight: bold;"></span></code><code> // we first create a
read-mode archive object that will be used in the three following
examples<br>
&nbsp;// we will also illustrate the use of libdar::archive_options_read<br>
      <br>
libdar::archive_options_read opt;<br>
      <br>
opt.set_info_details(true);<br>
opt.set_execute("echo 'about to read slice %p/%b.%N.%e with context
%c'");<br>
      <br>
libdar::archive <span style="font-weight: bold;">my_backup</span>(nullptr,&nbsp;&nbsp;
// this is user_interaction we will see further<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;
</code><code>"/home/me",<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;
"diff_backup",<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;
"dar",<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
opt); <br>
      </code><code><br>
      <br>
&nbsp; // we will also need a backup function for the two first methods<br>
&nbsp; // let's define it:<br>
      <br>
void <span style="font-weight: bold;">my_listing_callback</span>(const
std::string &amp; the_path,<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;
const libdar::list_entry &amp; entry,<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;
void *context)<br>
{<br>
&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; the_path;<br>
&nbsp;&nbsp;&nbsp; if(entry.is_dir())<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; " is a
directory";<br>
&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; " with permission " &lt;&lt;
entry.get_perm();<br>
&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; " located in slices " &lt;&lt;
entry.get_slices().display();<br>
&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; std::endl;<br>
&nbsp;&nbsp;&nbsp;&nbsp; // yep, we do not need context, this<br>
&nbsp;&nbsp;&nbsp;&nbsp; // is available if you need it though<br>
      <br>
&nbsp;&nbsp;&nbsp; if(entry.is_eod())<br>
&nbsp;&nbsp;&nbsp; {<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // only op_listing() provides such type of object<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // which occurs when we reached the <span style="font-weight: bold;">E</span>nd <span style="font-weight: bold;">O</span>f <span style="font-weight: bold;">D</span>irectory<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // next entry will be located in the parent directory.<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // Note for op_listing: when reading a directory we recurs in it,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // meaning that the next entry this callback will be <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // invoked for will be located in that directory<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //<br>
&nbsp; &nbsp; &nbsp;&nbsp; // for get_children_of() no recursion or eod object is<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // performed about directory. The next entry following<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // a directory is still located in the same parent directory<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // which when fully read stops the get_children_of() routine<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // at the difference of op_listing() which parse the whole<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // directory tree.<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // For example, reading a empty directory will provide<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // that directory info, then an eod object a the next<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // callback invocation.<br>
&nbsp;&nbsp;&nbsp; }<br>
}<br>
      </code></div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<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;">
      <h3>8.3 - archive listing using archive::op_listing()</h3>
      </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(204, 204, 204); width: 50%;">
      <div style="margin-left: 40px;"><code>&nbsp; // first
possibility: we can pass nullptr as callback function to
archive::op_listing, all will be displayed in stdout<br>
      <br>
      <span style="font-weight: bold;">my_backup</span>.op_listing(<span style="font-weight: bold;">nullptr</span>, // no callback function<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; nullptr, // we don't
care of context here<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
archive_options_listing()) // and use default listing options<br>
      <br>
      <br>
      </code><code> </code></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(204, 204, 204); width: 50%;">
      <div style="margin-left: 40px;"><code>&nbsp; // second
possibility: we use the callback defined above<br>
      <br>
      <span style="font-weight: bold;">my_backup</span>.op_listing(<span style="font-weight: bold;">my_listing_callback</span>,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; nullptr, // we still
don't care of context here<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
archive_options_listing()) // and still the default listing options<br>
      <br>
      </code><code> </code></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(204, 204, 204); width: 50%;">
      <div style="margin-left: 40px;"><code>&nbsp; // in complement of
both previous variant we can of course set non default listing options<br>
      <br>
libdar::archive_options_listing <span style="font-weight: bold;">opt</span>;<br>
      <br>
      <span style="font-weight: bold;">opt</span>.set_filter_unsaved(true);
// skip entry that have not been saved since the archive of reference<br>
      <span style="font-weight: bold;">opt</span>.set_slice_location(true);
// necessary if we want to have slicing information available in the
callback function<br>
opt.set_fetch_ea(false);&nbsp; // this is the default. Set it to true
if you want to use list_entry::get_ea_reset_read()/get_ea_next_read()<br>
      <br>
      <span style="font-weight: bold;">my_backup</span>.op_listing(my_listing_callback,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; nullptr, // we still
don't care of context here<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span style="font-weight: bold;">opt</span>) // and still the default listing
options<br>
      <br>
      </code><code> </code></div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<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;">
      <h3>8.4 - archive listing using archive::get_children_of()</h3>
      </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(204, 204, 204); width: 50%;">
      <div style="margin-left: 40px;"><code>&nbsp; // With this method
we only list one directory<br>
      <br>
my_backup.<span style="font-weight: bold;">get_children_of</span>(my_listing_callback,<br>
&nbsp; &nbsp; &nbsp;&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; nullptr,&nbsp; // we
still don't care of context here<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span style="font-weight: bold;">"",</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// we read the root directory of the archive<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
true); &nbsp;&nbsp; // and ask for EA retrieval, but as we do not<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;
// use list_entry::get_ea_read_next() 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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// callback this is just wasting CPU and memory<br>
      <br>
or course if you have a sub-directory /home/me/.gnupg/private-keys-v1.d
in your home directory and you want to check how it is saved in the
archive, as we defined the root of the backup as /home/me and as you
always have to pass a relative path (no leading /) you could do that by
calling the following:<br>
      <br>
      </code><code>my_backup.<span style="font-weight: bold;">get_children_of</span>(my_listing_callback,<br>
&nbsp; &nbsp; &nbsp;&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; nullptr,<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span style="font-weight: bold;">"</span></code><code><span style="font-weight: bold;">.gnupg/private-keys-v1.d"</span>);</code><code>&nbsp;&nbsp;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </code><code><br>
      <br>
      </code><code> </code></div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<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;">
      <h3>8.5 - archive listing using archive::get_children_in_table()</h3>
      </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(204, 204, 204); width: 50%;">
      <div style="margin-left: 40px;"><code></code><code> // still
listing a single directory but this time without callback function:<br>
      <br>
my_backup.<span style="font-weight: bold;">init_catalogue</span>(); //
necessary to fill read the whole catalogue in memory<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 particular if archive has been opened in sequential read mode<br>
      <br>
std::vector&lt;libdar::list_entry&gt; result = my_backup.<span style="font-weight: bold;">get_children_in_table</span>(</code><code>"</code><code>.gnupg/private-keys-v1.d");<br>
      <br>
// now reading the std::vector<br>
      <br>
std::vector&lt;libdar::list_entry&gt;::iterator it = result.begin();<br>
while(it != result.end())<br>
{<br>
      </code><code>&nbsp;&nbsp; if(it-&gt;is_dir())<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; " is a
directory";<br>
&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; " with permission " &lt;&lt;
it-&gt;get_perm();<br>
&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; " located in slices " &lt;&lt;
it-&gt;get_slices().display();<br>
&nbsp;&nbsp;&nbsp; std::cout &lt;&lt; std::endl;</code><code><br>
}<br>
      </code><code><br>
      </code><code> </code></div>
      </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> <span style="font-weight: bold;"></span>
      <h2>9 - Testing an archive<br>
      </h2>
      <div style="text-align: justify;">As seen for listing operation
we assume a archive object has been create in read mode. Testing the
coherence of the relative archive files on disk is done by calling the <span style="font-weight: bold;">libdar::op_test</span> method:<br>
      </div>
      <br>
      <code style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
statistics op_test(const archive_options_test &amp; 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;
statistics * progressive_report);</code><br>
      <br>
      <div style="text-align: justify;">You may recognize the
libdar::statistics type we saw for archive creation. It is present as
argument and the provided libdar::statistics object can be read during
the whole testing operation by another thread. But if you just want the
to know the result, you'd better just use the returned value as it
makes the operation quicker due to the absence of multithread
management.<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<code></code><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); width: 50%;"><code><br>
      </code>
      <div style="margin-left: 40px;"><code>&nbsp;&nbsp; // for the
exercise, we will change some default options:<br>
      <br>
      </code><code>archive_options_test <span style="font-weight: bold;">opt</span>;</code><br>
      <code><span style="font-weight: bold;">opt</span>.set_info_details(true);
// to have a verbose output</code><br>
      <code></code><br>
      <code>libdar::statistics <span style="font-weight: bold;">stats</span>;</code><br>
      <code><span style="font-weight: bold;">stats</span> = my_backup.<span class="el">op_test</span>(<span class="el"></span>nullptr,&nbsp;&nbsp;
// still the user_interaction we will see further</code><br>
      <code>&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;
<span style="font-weight: bold;">opt</span>; &nbsp; &nbsp; &nbsp;
// the non default options set above</code><code></code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
nullptr);&nbsp; // we will just use the returned value</code><br>
      <code></code><br>
      <code></code><code>std::cout &lt;&lt; <span style="font-weight: bold;">stats</span>.get_treated_str() &lt;&lt; "
file(s) tested" &lt;&lt; std::endl;</code><br>
      <code>std::cout &lt;&lt; <span style="font-weight: bold;">stats</span>.get_errored_str()
&lt;&lt; " file(s) with errors" &lt;&lt; std::endl;</code><br>
      <code>std::cout &lt;&lt; <span style="font-weight: bold;">stats</span>.get_ea_treated_str()
&lt;&lt; " Extended Attributes tested" &lt;&lt; std::endl;</code><code></code><br>
      </div>
      <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;"> <span style="font-weight: bold;"></span> <span style="font-weight: bold;"></span>
      <h2>10 - Comparing an archive<br>
      </h2>
      <div style="text-align: justify;">As simple as previously, but
using the <span style="font-weight: bold;">archive::op_diff </span>method:<br>
      </div>
      <br>
      <code style="font-weight: bold;">&nbsp; &nbsp; &nbsp; &nbsp;
statistics op_diff(const path &amp; fs_root,<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;
const archive_options_diff &amp; 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;
statistics * progressive_report);</code><br>
      <code style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
      </code><br>
      <br>
      <div style="text-align: justify;">Over the type of the option
field, you see the <span style="font-weight: bold;">fs_root </span>argument
which define which directory of the filesystem to compare the archive to<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<code></code><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); width: 50%;"><code><br>
      </code>
      <div style="margin-left: 40px;"><code>&nbsp;&nbsp; // for the
exercise, we will change some default options:<br>
      <br>
      </code><code>archive_options_diff <span style="font-weight: bold;">opt</span>;</code><br>
      <code> <span style="font-weight: bold;">opt</span>.set_info_details(true);
// to have a verbose output<br>
      <span style="font-weight: bold;">opt</span>.set_what_to_check(libdar::comparison_fields::ignore_owner);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // this option above will consider equal
two files which<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // only change due to user or group
ownership difference<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // by default any difference will be
considered a difference<br>
      </code> <code></code><code></code><br>
      <span style="font-weight: bold;"></span><code><span style="font-weight: bold;"></span><span style="font-family: mon; font-weight: bold;">(void)</span><span style="font-weight: bold;"> </span>my_backup.<span class="el">op_diff</span>(<span class="el"></span><span style="font-weight: bold;">"/home/me"</span>,</code><br>
      <code>&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;
<span style="font-weight: bold;">opt</span>; &nbsp; &nbsp; &nbsp;
// the non default options set above</code><code></code><br>
      <code>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
nullptr);&nbsp; // not using it for this example</code><br>
      <code></code><code></code><code></code><br>
      </div>
      <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;"> <span style="font-weight: bold;"></span> <span style="font-weight: bold;"></span>
      <h2>11 - Isolating an archive<br>
      </h2>
      <div style="text-align: justify;">As simple as previously, but
using the <span style="font-weight: bold;">archive::op_isolate </span>method:<br>
      </div>
      <code style="font-weight: bold;"><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void op_isolate(const path
&amp;sauv_path,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const std::string &amp; extension,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const archive_options_isolate &amp; options);<br>
      </code><code style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
      </code><br>
      <div style="text-align: justify;">You will find similitude with
the archive creation though here this is not a constructor<br>
      <br>
      <span style="font-weight: bold;">sauv_path </span>is the
directory where to create the isolated version of the current archive<br>
      <span style="font-weight: bold;">filename</span> is the archive
basename to create<br>
      <span style="font-weight: bold;">extension</span> should still be
"dar" here too<br>
      <span style="font-weight: bold;">options</span> are options for
isolation like slicing, compression, encryption similar to the
archive_options_create class we saw at the beginning of this tutorial<br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<code></code><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); width: 50%;"><code></code>
      <div style="margin-left: 40px;"><code>&nbsp;&nbsp; // for the
exercise, we will change some default options:<br>
      <br>
      </code><code>archive_options_isolate <span style="font-weight: bold;">opt</span>;</code><br>
      <code> <span style="font-weight: bold;">opt</span>.set_warn_over(false);&nbsp;
      <br>
&nbsp;&nbsp; // by default overwriting is allowed by a warning is
issued first<br>
&nbsp;&nbsp; // here overwriting will take place without warning<br>
      </code><code><br>
      <span style="font-weight: bold;">opt</span>.set_compression(libdar::compression::gzip);<br>
      <span style="font-weight: bold;">opt</span>.set_compression_level(9);&nbsp;&nbsp;
// this is the default<br>
      <span style="font-weight: bold;">opt</span>.set_min_compr_size(10240);&nbsp;
// not trying compressing file smaller than 10 kiB</code><br>
      <code></code><code></code><br>
      <span style="font-weight: bold;"></span><code><span style="font-weight: bold;"></span><span style="font-family: mon; font-weight: bold;"></span><span style="font-weight: bold;"></span>my_backup.<span class="el">op_isolate</span>(<span class="el"></span>"/tmp"<span style="font-weight: bold;">,</span><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"CAT_diff_backup",<br>
&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "dar",<br>
      </code><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
      <span style="font-weight: bold;">opt</span>); // the non default
options set above</code><code></code><br>
&nbsp; <code></code><span style="font-family: monospace;"><br>
&nbsp;&nbsp; // have you noted? There is no libdar statistics field
returned nor as argument.</span><code></code><br>
      </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;"> <span style="font-weight: bold;"></span> <span style="font-weight: bold;"></span>
      <h2>12 - Restoring files from an archive<br>
      </h2>
      <div style="text-align: justify;">Quite as simple as previously, here we use the <span style="font-weight: bold;">archive::op_extract </span>method:<br>
      </div>
      <code style="font-weight: bold;"><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; statistics op_extract(const path &amp;fs_root,<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;
const archive_options_extract &amp; 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;&nbsp;&nbsp;
statistics *progressive_report);<br>
<br>
<br>
      </code><code style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
      </code><br>
      <div style="text-align: justify;"><span style="font-weight: bold;">fs_root</span> is the directory under which to restore the files and directory<br>
<span style="font-weight: bold;">options</span> defines how and what to restore<br>
<span style="font-weight: bold;">progressive_report</span> has already been seen several time previously<br>
      </div>
      </td></tr></tbody>
</table>
<code></code><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); width: 50%;"><code></code>
      <div style="margin-left: 40px;"><code>&nbsp;&nbsp; // as we still do not have seen masks, we will restore all files contained in the backup<br>
&nbsp;&nbsp; // such mask would be provided to the <br>
&nbsp;&nbsp; // archive_options_extract::set_selection() and/or <br>
&nbsp;&nbsp; // to the archive_options_extract::set_subtree() methods<br>
&nbsp;&nbsp; // to precisely define what files to restore<br>
      <br>
archive_options_extract <span style="font-weight: bold;">opt</span>;<br>
      <br>
      <span style="font-weight: bold;">opt</span>.set_dirty_behavior(false, false); // dirty files are not restored<br>
      <br>
(void) my_backup.<span style="font-weight: bold;">op_extract</span>("/home/me/my_home_copy",<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;
<span style="font-weight: bold;">opt</span>,<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;
nullptr); // we have seen previously how to use statistics<br>
&nbsp; </code><span style="font-family: monospace;"></span><code></code><br>
      </div>
      </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> <span style="font-weight: bold;"></span>
      <h2>13 - Merging archives<br>
      </h2>
      <div style="text-align: justify;">Here
we will need two archive objects open in read-mode and we will invoke a
specific archive constructor passing these two objects as argument,
once the constructor will have completed the merging operation will be
done:<br>
      </div>
      <code style="font-weight: bold;"><br><br>
&nbsp; &nbsp; &nbsp; &nbsp; archive(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const path &amp; sauv_path,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
std::shared_ptr&lt;archive&gt; ref_arch1,<br>
&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; const std::string &amp; extension,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const archive_options_merge &amp; options,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; statistics * progressive_report);<br>
      </code><code style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
      </code><br>
      <div style="text-align: justify;"><span style="font-weight: bold;">dialog</span> is will still be set to null pointer for now<br>
      <span style="font-weight: bold;">sauv_path</span> is the directory where to create the resulting merging archive<br>
      <span style="font-weight: bold;">ref_arch1</span> is the first (and mandatory) archive, the second is optional and may be given to the <span style="font-weight: bold;">options</span> argument<br>
      <span style="font-weight: bold;">filename</span> is the resulting archive basename<br>
      <span style="font-weight: bold;">extension</span> as always should be set to "dar"<br>
      <span style="font-weight: bold;">options</span> is a set of optional parameters<br>
      <span style="font-weight: bold;">progressive_report </span>is as seen above the ability to have another thread  showing progression info during the operation<br>
</div>
      </td></tr></tbody>
</table>

<code></code><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); width: 50%;"><code></code>
      <div style="margin-left: 40px;"><code>&nbsp; // assuming you have two backups: <br>
&nbsp; // the first is /tmp/home_backup.*.dar<br>
&nbsp; // the second is /var/tmp/system_backup.*.dar<br>
&nbsp; // we will create /tmp/merged.*.dar as result of the merging<br>
&nbsp; // of these two backups<br>
      <br>
&nbsp; // 1 - first things first: opening the first backup<br>
      <br>
</code><code>
libdar::archive_options_read <span style="font-weight: bold;">opt</span>;<br>
      <br>
      <span style="font-weight: bold;">opt</span>.set_info_details(true);<br>
      <span style="font-weight: bold;">opt</span>.set_execute("echo 'about to read slice %p/%b.%N.%e with context
%c'");<br>
      <br>std::shared_ptr&lt;libdar::archive&gt; <span style="font-weight: bold;"><span style="font-family: monospace;">home_backup</span></span>(<span style="font-weight: bold;">new</span> libdar::archive(nullptr,&nbsp;&nbsp;
// this is user_interaction we will see further<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;
</code><code>"/tmp",<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;
"home_backup",<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;
"dar",<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;
<span style="font-weight: bold;">opt</span>)); </code><code><br>
      <br>
&nbsp; // 2 - opening the second backup<br>
      <br>
std::shared_ptr&lt;libdar::archive&gt; <span style="font-weight: bold;">system_backup</span>(<span style="font-weight: bold;">new</span> libdar::archive(nullptr,<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;
"/var/tmp",<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;
"system_backup",<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;&nbsp;
"dar",<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;
<span style="font-weight: bold;">opt</span>);<br>
      <br>
&nbsp; // 3 - setting up the options for merging<br>
      <br>
libdar::archive_options_merge <span style="font-weight: bold;">opt_merge</span>;<br>
      <br>
opt_merge.set_auxiliary_ref(<span style="font-weight: bold;">system_backup</span>);<br>
opt_merge.set_slicing(1048576, 0); // all slice would have 1 MiB at most<br>
opt_merge.set_compression(libdar::compression::bzip2);<br>
opt_merge.set_keep_compressed(true);<br>
opt_merge.set_user_comment("archive resulting of the merging of home_backup and system_backup");<br>
opt_merge.set_hash_algo(libdar::hash_algo::sha512); // will generate on-fly hash file for each slice<br>
      <br>
&nbsp; // 4 - now performing the merging operation<br>
      <br>
libdar::archive <span style="font-weight: bold;">merged</span>(nullptr,&nbsp; // still the user_interaction we will see further<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"/tmp",<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<span style="font-weight: bold;">home_backup</span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"merged",<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"dar",<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<span style="font-weight: bold;">opt_merge</span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
nullptr);&nbsp; // progressive_report we don't use here<br>
      <br>
      </code><code></code><br>
      </div>
      </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> <span style="font-weight: bold;"></span>
      <h2>14 - Decremental backup<br>
      </h2>
      <div style="text-align: justify;">Decremental
backup is an operation that from two full backups an old and a recent
one creates a backward differential backup corresponding to the old
full backup based on the new full backup. In other words, instead of
keeping two full backups, you can keep the latest and replace the
oldest by its decremental counterpart. This will save you space while
letting you restore as if you had the old full backup by restoring
first the recent backup then the decremental backup.<br>
      <br>
Creating a decremental backup is exactly the same as creating a merging
backup, you need just to set the
archive_options_merge::set_decremental_mode() before proceeding to the
merging. To avoid duplication we will just illustrate the last step of
the previous operation modified for decremental backup:<br>
</div></td></tr></tbody>
</table>


<code></code><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); width: 50%;"><code></code>
      <div style="margin-left: 40px;"><code>&nbsp; // </code><code></code><code>[...]<br>
      <br>
libdar::archive_options_merge <span style="font-weight: bold;">opt_merge</span>;<br>
      <br>
&nbsp; // [...]<br><span style="font-weight: bold;">
opt_merge.set_decremental_mode(true);</span><br>
      <br>
&nbsp; // 4 - now performing the merging operation (here decremental backup)<br>
      <br>
libdar::archive merged(nullptr,&nbsp; // still the user_interaction we will see further<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"/tmp",<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
home_backup,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"merged",<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"dar",<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<span style="font-weight: bold;">opt_merge</span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
nullptr);&nbsp; // progressive_report we don't use here<br>
      <br>
      </code></div>
      </td>
    </tr>
  </tbody>
</table>


<br>


<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> <span style="font-weight: bold;"></span>
      <h2>15 - Archive repairing<br>
      </h2>
      <div style="text-align: justify;">If
an archive has been truncated due to lack of disk space and if
sequential marks (aka tape marks) had not been disable, it is possible
to rebuild sane archive beside this truncated one.<br>
      <br>
We just need to invoke a <span style="font-weight: bold;">specific libdar::archive constructor</span> which form follows:<br>
      <br>
      <code style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; archive(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const path &amp; chem_src,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; basename_src,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const std::string &amp; extension_src,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const archive_options_read &amp; options_read,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const path &amp; chem_dst,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; basename_dst,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const std::string &amp; extension_dst,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const archive_options_repair &amp; options_repair);</code><br>
      <br>
You should now be familiarized with the different types and variable
uses. As you can note, this constructor takes in charge the work to
read the damaged archive, so you won't have to do it first. As always,
this constructor will end only once the operation will have completed.<br>
      <br>
</div></td></tr></tbody>
</table>



<code></code><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); width: 50%;"><code></code>
      <div style="margin-left: 40px;"><code>&nbsp; // </code><code>assuming the archive /tmp/home_backup.*.dar is damaged <br>
&nbsp; // and you want to have repaired archive as /tmp/home_backup_repaired.*.dar<br>
      <br>
libdar::archive repaired(nullptr,&nbsp;&nbsp; // still the user_interaction we have not yet seen<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;
"/tmp"<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;
"home_backup",<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;
"dar",<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;
<span style="font-weight: bold;">archive_options_read()</span>,<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;
"/tmp",<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;
"home_backup_repaired",<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;
"dar",<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;
<span style="font-weight: bold;">archive_options_repair()</span>);<br>
      <br>
&nbsp; // we have not done fancy things with the two option classes, but we did above<br>
&nbsp; // enough time for you get all the necessary information from the API reference <br>
&nbsp; // documentation<br>
<br>
      </code></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>16 - Looking at some details<br>
      </h2>
we have covered the different operations the class libdar::archive can be used for, still remains some concepts to details:<br>
      <ul>
        <li>user_interaction</li>
        <li>masks</li>
        <li>how to cleanly interrupt an running libdar routine</li>
        <li>how to known which compile-time feature has been activated<br>
        </li>
      </ul>
Then we will see the three other more simple classes :<br>
      <ul>
        <li>class database</li>
        <li>class libdar_slave</li>
        <li>class libdar_xform</li>
      </ul>
For now, maybe you remember that we had to initialize libdar before use, by calling <span style="font-weight: bold;">libdar::get_version()? </span>This routine also exists with arguments that will provide as its name suggests the libdar version:<br>
      <br>
      <div style="margin-left: 40px;"><code><span style="font-weight: bold;">void get_version(U_I &amp; major, U_I &amp; medium, U_I &amp; minor, bool init_libgcrypt = true);</span></code><br>
      </div>
      <br>
It is advised to use this form to fetch the libdar version major, medium and minor numbers for the following reasons:<br>
      <br>
you should 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 is present there (just note the presence of more bugs in
lower numbers).<br>
      <br>
If you use libgcrypt beside libdar in your application you should
initialize libgcrypt and not let it be done by libdar the latest
argument of this form should be set to false in that case. Note
that <a href="https://www.gnupg.org/documentation/manuals/gcrypt/Initializing-the-library.html#Initializing-the-library">libgcrypt
documentation</a> indicates that libgcrypt must be initialized directly
from
the application not from an intermediate library.<br>
      <br>
Follows an example of test that can be performed while initializing libdar:<ul style="text-align: justify;">
        
      </ul>
      <ul>
      </ul>
      
      
      </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); width: 50%;"><code>U_I major, medium, minor;<br>
      <br>
libdar::get_version(major, medium, minor);<br>
<br>
      </code><code> if(maj !=
libdar::LIBDAR_COMPILE_TIME_MAJOR ||<br>&nbsp;&nbsp; med &lt;
libdar::LIBDAR_COMPILE_TIME_MEDIUM)<br>
{<br>
&nbsp; &nbsp; std::cout &lt;&lt; "libdar version we link with is too old for this code" &lt;&lt; std::endl;<br>
&nbsp;&nbsp;&nbsp; // throw an exception or anything else appropriate to that condition<br>
}<br>
      <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;">
      
      <h2>17 - checking compile-time features activation<br>
      </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 thanks to a set of function located in the compile_time nested namespace inside libdar:<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(204, 204, 204); width: 50%;"><code><br>
      <br>
void my_sample_function()<br>
{<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <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 libxz = libdar::compile_time::libxz();<br>
bool libcrypto = libdar::compile_time::libgcrypt();<br>
bool furtive_read = libdar::compile_time::furtive_read</code>();<br>
      <br>
      <span style="font-family: monospace;">/ // for details see the compile_time namespace in the API reference documentation</span><span style="font-family: monospace;"></span><br>
      </div>
      <code> </code><br>
}<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;">
      
      
      
      <h2>18 - User Interaction</h2>
we have seen std::shared_pointer on class <span style="font-weight: bold;">libdar::user_interaction</span> previously but did not used this feature.<br>
      <br>
      <h3>18.1 - Defining your own user_interaction class</h3>
      <div style="text-align: justify;">
class <span style="font-weight: bold;">libdar::user_interaction</span>
defines the way libdar interact with the user during an operation, like
an archive creation, restoration, testing and so on. Only four types of
interaction are used by libdar:<br>
      </div>

      <br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void message(const std::string &amp; message);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void pause(const std::string &amp; message);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; std::string get_string(const std::string &amp; message, bool echo);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; secu_string get_secu_string(const std::string &amp; message, bool echo);</code><br>
      <br>
      <div style="text-align: justify;">
By default an inherited class of libdar::user_interaction called
      <span style="font-weight: bold;">libdar::shell_interaction</span> is used and implements these four type of exchange by
mean of text terminal:<br>

      </div>
<ul>
        <li><span style="font-weight: bold;">message()</span> sends the std::string provided by libdar to stdout</li>
        <li><span style="font-weight: bold;">pause()</span> does the same and ask for the user to press either return or escape to answer yes or no</li>
        <li><span style="font-weight: bold;">get_string()</span> reads a string from stdin</li>
        <li><span style="font-weight: bold;">get_secu_string()</span> reads a string into a secu_string object from stdin too<br>
        </li>
      </ul>
      <div style="text-align: justify;">
For a GUI you will probably not want stdin and stdout to be used. For
that you have the possibility to implement your own inherited class
from user_interaction. It should look like the following:<br>
      </div>

      <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);"><code></code><code>class my_user_interaction: public libdar::user_interaction<br>
{<br>
protected:<br>
&nbsp;&nbsp; &nbsp;&nbsp; // display of informational message<br>
&nbsp;&nbsp; virtual void inherited_message(const std::string &amp; message) override;<br>
      <br>
&nbsp; &nbsp; &nbsp; // display of a question and returns the answer from user as true/false <br>
&nbsp;&nbsp; virtual bool inherited_pause(const std::string &amp; message) override;<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // display the message and returns a
string from the user, with or without display what the user typed (echo)<br>
&nbsp;&nbsp; virtual std::string inherited_get_string(const std::string &amp; message, bool echo) override; <br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // same as the previous be the user provided string is returned as secu_string <br>
&nbsp;&nbsp; virtual secu_string inherited_get_secu_string(const std::string &amp; message, bool echo) override;<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>18.2 - Relying on the pre-defined user_interaction_callback class<br>
      </h3>
      <div style="text-align: justify;">As an alternative to defining
your own inherited class from <span style="font-style: italic;">libdar::user_interaction</span>,
libdar provides a class called <span style="font-weight: bold; font-style: italic;">user_interaction_callback</span>
which is an implementation of the user interaction, based on callback
functions.<br>
      <br>
You will need to implement four callback functions:<br>
      <br>
      <code style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; using message_callback = void (*)(const std::string &amp;x, void *context);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; using pause_callback = bool (*)(const std::string &amp;x, void *context);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; using get_string_callback =
std::string (*)(const std::string &amp;x, bool echo, void *context);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; using
get_secu_string_callback = secu_string (*)(const std::string &amp;x,
bool echo, void *context);</code><br>
      <br>
Then you can create an libdar::user_interaction_callback object using this constructor:<br>
      <br>
      <code style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; user_interaction_callback(message_callback x_message_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;
pause_callback x_answer_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;
get_string_callback x_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;
get_secu_string_callback x_secu_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;
void *context_value);</code><br>
      <br>
Here follows an example of use:<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><code>void my_message_cb(const std::string &amp; x, void *context)<br>
{<br>
&nbsp;&nbsp;&nbsp; cout &lt;&lt; x &lt;&lt; endl;<br>
}<br>
      <br>
bool void my_pause_cb(const std::string &amp; x, void *context)<br>
{<br>
&nbsp;&nbsp; char a;<br>
      <br>
&nbsp;&nbsp; cout &lt;&lt; x &lt;&lt; endl;<br>
&nbsp;&nbsp; cin &gt;&gt; a;<br>
&nbsp;&nbsp; return a == 'y';<br>
}<br>
      <br>
std::string my_string_cb(const std::string &amp; x, bool echo, void *context)<br>
{<br>
&nbsp; // to be defined<br>
}<br>
      <br>
libdar::secu_string my_secu_string_cb(const std::string &amp; x, bool echo, void *context)<br>
{<br>
&nbsp; // to be defined<br>
}<br>
      <br>
&nbsp;&nbsp; // eventually using a context_value that will be passed to the callback of the object<br>
void *context_value = (void *)(&amp; some_datastructure);<br>
      <br>
std::shared_ptr&lt;libdar::user_interaction&gt; my_user_interaction(new libdar::user_interaction_callback(my_message_cb,<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;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
my_pause_cb,<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;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
my_string_cb,<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;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
my_secu_string_cb,<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;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
context_value));</code><br>
</td>
    </tr>
  </tbody>
</table>

<code></code><code></code><code></code><code></code><code></code><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;">
      You will also find predefined classes like <span style="font-weight: bold;">libdar::user_interaction_blind</span> which always says no in name of the user displays nothing and provide empty strings, as well as <span style="font-weight: bold;">libdar::shell_interaction_emulator</span>
which given a user_interaction object send to it formatted information
as if it was a shell_interaction object, leading one to emulate libdar
default behavior under any time of "terminal".<br>
      <br>
      <div style="text-align: justify;"><span style="font-weight: bold;"><span style="text-decoration: underline;">IMPORTANT:</span> </span>all
libdar::user_interaction inherited classes provided by libdar are not
designed to be manipulated by more than one thread at a time. The use
of std::shared_ptr is only here to let the caller not have to manage
such object and let libdar release it when no more needed <span style="font-weight: bold;">or</span>
to let the caller to reuse the same user_interaction object for a
subsequent call to libdar which would not be possible if a
std::unique_ptr was used.<br>
      <br>
Now if you design your own user_interaction inherited class and provide
them mecanism (mutex, ...) that allow them to be used simultaneously by
several thread there is no issue to give pass such one object as
argument to different libdar object used by different threads.<br>
      </div>
<span style="font-weight: bold;">
      <br>
      </span><br>
      <h2>19 - Masks<br>
      </h2>

      <div style="text-align: justify;">Mask are used to define which <span style="text-decoration: underline;">string</span>
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; font-weight: bold;">mask::is_covered(const std::string &amp; expression)</span><span style="font-weight: bold;"> </span>method
which libdar uses to determine which string are considered for an operation which are not.<br>
      <br>
Strings applied to masks may correspond to filename only, to full path
or maybe to other things. That's in the context where the mask is used
that the string meaning take place.<br>
      <br>
&nbsp;There is several different basic masks classes you can use
to build fairly
complex masks, while it is possible you should not need to define you
own mask classes, if the need arises, please contact libdar developer
if you thing an additional class should take place beside the following
ones:<br>
      </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;">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>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 string that match the glob
expression "A*~" will match. <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // the second argument of the
constructor tell whether 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(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 string that does not begin by 'A'
or 'a' or finishing by '~'<br>
&nbsp; libdar::not_mask m3(m2);<br>
      <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // this mask matches any string 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 as we set it to "true".<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 strings 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 interesting 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 referring each other!</code><br>
      <code>&nbsp; libdar::not_mask m7(m6);<br>
&nbsp; m6.add_mask(m7);<br>
      <br>
      <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;">The idea here is not to create
object manually, but to link their
creation to the action and choices the user makes from the user
interface (Graphical User Interface of your application, for example)<br>
      <br>
Now that you've seen the power
of these masks, you should know that in
libdar masks are used at several places:<br>
      <ul style="text-align: justify;">
        <li>A first place is to select files against
their
names (without path information) this the argument of the <span style="font-weight: bold;">set_selection()</span> method of <span style="font-style: italic;">libdar::archive_options_*</span> classes.
The mask here does not apply to directories.<br>
        </li>
        <li>A second place is to select files against their
path+name and it applies here to all type of files including
directories, this is the argument of the <span style="font-weight: bold;">set_subtree()</span> method of <span style="font-style: italic;">libdar::archive_options_*</span> classes.
So
with it, you can prune directories, or in any other way restrict the
operation to a particular subdirectory, as well as to a particular
plain file for example. <span style="font-weight: bold;">Important note</span>
about this second mask: what your own mask will be compared to by
libdar is the <span style="font-weight: bold;">absolute path</span> of
the file under consideration. If you want to exclude /usr/local/bin
from the operation whatever is the <span style="font-style: italic;">fs_root</span>
value (which correspond the -R option of dar) using here a <span style="font-style: italic;">libdar::simple_mask("/usr/local/bin")</span>
as argument of <span style="font-style: italic;">libdar::archive_options_*::get_subtree()</span>
will do the trick.<br>
        </li>
      </ul>
      <div style="text-align: justify;"> </div>
      <div style="margin-left: 80px; text-align: justify;"><span style="font-style: italic;"></span>An exception is the archive testing
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
testing
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>
      <br>
instead of using explicit string "&lt;ROOT&gt;" you can use <span style="font-weight: bold;">libdar::PSEUDO_ROOT</span> const std::string variable<br>
      </div>
      <div style="margin-left: 80px; text-align: justify;"> </div>
      <ul>
        <li>A third place concerns
Extended Attributes (EA), this is the argument of the <span style="font-weight: bold;">set_ea_mask() </span>method of
archive_options classes. 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.</li>
        <li>A fourth place concerns the file to compress or to avoid
compressing. This is the argument of the <span style="font-weight: bold;">set_compr_mask()</span>
method of <span style="font-style: italic;">libdar::archive_options_*</span>
classes. it is works the same as
set_selection() seen above, based only to filename without any path
consideration.</li>
        <li>A fifth place concerns files that have need be prepared for
backup, this is the argument of the <span style="font-weight: bold;">set_backup_hook()
          </span>method
of <span style="font-style: italic;">libdar::archive_option_create</span>
class. I has to be used the same as
set_subtree(). For more about this feature see the backup-hook feature
in dar man page (-&lt;, -&gt; and -= options).<br>
        </li>
      </ul>
      </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>
      <h2>20 - 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 (but on different objects except concerning the
libdar::statistics which can be shared between threads). You may then
wish to interrupt a given thread. But
aborting a thread form the outside (like sending it a KILL signal) will
most of the time let some memory allocated or even worse can lead to
dead-lock
situation, when the killed thread was inside a critical section and had
not
got the opportunity to release a <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; font-family: monospace;" border="1" cellpadding="2" cellspacing="2">

  <tbody>
    <tr>
      <td style="vertical-align: top; background-color: rgb(204, 204, 204);"><code></code>&nbsp;&nbsp;
// next is the
thread ID in which we want to have
lidbar call canceled<br>
&nbsp;&nbsp; // here for simplicity we don't describe the way the
ID has been obtained<br>
&nbsp;&nbsp; // but it could be for example the result of a call to pthread_self() as<br>
&nbsp;&nbsp; // defined in &lt;pthread.h&gt; system header file<br>
pthread_t thread_id = 161720;<br>
&nbsp;&nbsp; <br>
&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 misses a catalogue at
the end. Note that this<br>
&nbsp;&nbsp; // delayed
cancellation needs a bit more time 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(204, 204, 204); width: 50%;"><code>try<br>
{<br>
&nbsp; &nbsp; </code><code>libdar::archive my_arch(...);<br>
&nbsp;&nbsp;&nbsp; ...<br>
}<br>
catch(libdar::Ethread_cancel &amp; e)<br>
{<br>
&nbsp;&nbsp;&nbsp; ... do something specific when thread has been canceled;<br>
}<br>
      <br>
      </code><code> </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;">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);"><span style="font-family: monospace;">&nbsp;pthread_t
tid;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp; </span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp; // how to know
if the thread </span><span style="font-style: italic; font-family: monospace;">tid</span><span style="font-family: monospace;"> is under cancellation process?</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">if(</span><span style="font-weight: bold; font-family: monospace;">libdar::cancel_status</span><span style="font-family: monospace;">(tid))</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;
cout &lt;&lt; "thread cancellation is under
progress for thread : " &lt;&lt; tid &lt;&lt; endl;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">else</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;
cout &lt;&lt; "no thread cancellation is under
progress for thread : " &lt;&lt; endl;</span><br style="font-family: monospace;">
      <br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp; // how to
cancel a pending thread cancellation ?</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">if(</span><span style="font-weight: bold; font-family: monospace;">libdar::cancel_clear</span><span style="font-family: monospace;">(tid))</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&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;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">else</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp; cout &lt;&lt;
"too late, could not avoid thread
cancellation for thread "&lt;&lt; tid &lt;&lt; endl;</span><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; font-family: monospace;" 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>

<code></code><code></code><br>
<hr style="width: 100%; height: 2px;"><br>
<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>
      
      
      <h2 style="text-align: justify;">21 - 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; font-weight: bold;">libdar/database.hpp</span>
header file so <span style="text-decoration: underline;">you first
need to include that file</span>. 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. The first creates a brand-new but empty database in memory<br>
      <br>
      <div style="margin-left: 40px;"><code>database(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog);</code><br>
      </div>
      <br>
As seen for libdar::archive dialog can be set to a null pointer if the
default interaction mode (stdin/stdout/stderr) suits your need.<br>
The second constructor opens an existing database from filesystem and stores its contents into memory ready for further use.<br>
      <br>
      <div style="margin-left: 40px;"><code>database(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; base,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
const database_open_options &amp; opt);</code><br>
      </div>
      <br>
      <ul>
        <li>dialog here to can be set to a null pointer or can point to an user_interaction object of your own</li>
        <li>base is the path and filename of the database to read</li>
        <li>opt is an object containing a few options. As seen with
libdar::archive we can use an default temporary object to use default
option</li>
      </ul>
 </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></code><code>&nbsp; &nbsp; database base; &nbsp; <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // we have created an empty
database (no archive in it) called "base"<br>
      <br>
&nbsp; &nbsp; database other&nbsp; = database(nullptr,<br>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; "/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;&nbsp;&nbsp;&nbsp;
database_open_options());<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// we have created a database object called "other" which contains <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// (in RAM) all information that were contained in the <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// database file "/tmp/existing_base.dmd"<br>
&nbsp;&nbsp;&nbsp;&nbsp; <br>
      <br>
&nbsp;&nbsp;&nbsp; database_open_option opt;<br>
&nbsp;&nbsp;&nbsp; opt.set_partial(true);<br>
&nbsp;&nbsp;&nbsp; opt.set_warn_order(false);<br>
&nbsp;&nbsp;&nbsp; database other2 = database(nullptr,
      <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;
"/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;&nbsp;&nbsp;&nbsp;
opt);<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// we have created yet another database object called "other2" which differs<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// from "other" by the option we used. While "other" is a fully loaded <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// database, "other2" is a partial database. This notion is explained <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
// below</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;">
      <ul>
        <li><span style="font-weight: bold;">database_open_options::set_partial(bool value)</span>
leads dar to only load the database header into memory, which is
quicker than loading the full database. But some operation we will see
bellow need fully loaded database,&nbsp; the other can work with both</li>
        <li><span style="font-weight: bold;">database_open_options::set_partial_read_only(bool value)</span>
in addition to have only the header the archive is open in read-only
mode which of course forbids any modification to the database but is
even faster than just a partial read-write database. For just database
listing this is perfectly adapted.</li>
        <li><span style="font-weight: bold;">database_open_options::set_warn_order(bool value)</span> avoid warning about ordering problem between archive<br>
        </li>
      </ul>
In the following we will indicate whether a database operation can be
applied to a partially loaded database or not. All operation can be
applied to a fully loaded databse.<br>
      </div>
      <br>
      <h3>Database's methods <br>
</h3>First we will see methods that can work with a <span style="font-weight: bold;">partial and read-only</span> database<br>
      <ul>
<li><span style="font-weight: bold;">show_contents()</span> : list the archives used to build the
database</li><li><span style="font-weight: bold;">get_options()</span> : list the options that will be passed to dar
(as
defined with the set_options() method)</li><li><span style="font-weight: bold;">get_dar_path()</span> : return the path to dar (or empty string if
relying on the PATH variable)</li>
      </ul>

Second we will see methods that can work with&nbsp; <span style="font-weight: bold;">partially</span> loaded databases:<br>
      <ul><li><span style="font-weight: bold;">all methods seen above</span><br>
          <span style="font-weight: bold;"></span></li>
        <li><span style="font-weight: bold;">dump(...)</span> : it is used to write back the database to a
file. <br>
        </li>
<li><span style="font-weight: bold;">change_name()</span> : change the basename of the archive which
index is
given in argument</li><li><span style="font-weight: bold;">set_path()</span> : change the path to the archive which index is
given
in argument</li><li><span style="font-weight: bold;">set_options() </span>: change the default options to always pass
to dar
when performing restoration</li><li><span style="font-weight: bold;">set_dar_path()</span> : specify the path to dar (use empty string
to
rely on the PATH variable)</li></ul>last, let's see the database methods that can work with completely
loaded databases:<br>
      <ul><li><span style="font-weight: bold;">all methods seen above</span><br>
          <span style="font-weight: bold;"></span></li>
        <li><span style="font-weight: bold;">add_archive()</span> : add an archive to the database</li>
<li><span style="font-weight: bold;">remove_archive()</span> : remove an archive from the database</li><li><span style="font-weight: bold;">set_permutation()</span> : change archive relative order within
the
database</li><li><span style="font-weight: bold;">show_files()</span> : list the files which are present in the
given
archive<br>
        </li><li><span style="font-weight: bold;">show_version()</span> : list the archive where the given file is
saved</li><li><span style="font-weight: bold;">show_most_recent_stats()</span> :&nbsp; compute statistics about
the
location of most recent file versions</li><li><span style="font-weight: bold;">restore()</span> : 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 API reference documentation.
This documentation is built if doxygen is available and is put
under doc/html after calling make in the source
package. It is also available from <a href="http://dar.linux.free.fr/html/">dar's
homepage</a>. </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>22 - dar_slave API<br>
      </h2>dar_slave
role is to read an archive while interacting with a dar process through
a pair of pipes. Dar asks portion of the archive or information about
the archive in the first pipe from dar to dar_slave. And dar_slave
sends the requested information into the other pipe toward dar.<br>
      <br>
Since API 6.0.x, dar_slave has an API. It is implemented by the class
libdar::libdar_slave. You need firs to create an object using the
following constructor:<br>
      <br>
      <div style="margin-left: 40px;"><code></code><code><span style="font-weight: bold;"> libdar_slave(std::shared_ptr&lt;user_interaction&gt; &amp; dialog,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; folder,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; basename,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; extension,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; bool input_pipe_is_fd,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; input_pipe,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; bool output_pipe_is_fd,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; output_pipe,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; execute,</span><br style="font-weight: bold;">
      <span style="font-weight: bold;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const infinint &amp; min_digits);</span><br>
      </code></div>
      <br>
      <ul>
        <li><span style="font-weight: bold;">dialog</span> as seen for other libdar classes can be set to a null pointer for interaction on stdin and stdout</li>
        <li><span style="font-weight: bold;">folder</span> is the directory where resides the archive to read</li>
        <li><span style="font-weight: bold;">basename</span> is the basename of the archive</li>
        <li><span style="font-weight: bold;">extension</span> should always be set to "dar"</li>
        <li><span style="font-weight: bold;">input_pipe_is_fd</span> if
set to true, the next argument is not the path to a named pipe but a
number corresponding to a file descriptor open open in read mode<br>
        </li>
        <li><span style="font-weight: bold;">input_pipe</span> is the path of a named pipe to read from. It can also be an empty string to use stdin as input pipe</li>
        <li><span style="font-weight: bold;">out_pipe_is_fd</span> if
set to true, the next argument is not the path to a named pipe but a
number corresponding to a file descriptor open in write mode<br>
        </li>
        <li><span style="font-weight: bold;">output_pipe </span>is the path of a named pipe to write from. It can also be an empty string to use stdout as input pipe</li>
      </ul>
Once the object is created, you will need to call the <span style="font-weight: bold;">libdar_slave::run()</span> method which will end when the dar process at the other end will no more need of this slave<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);"><code></code><code>libdar::libdar_slave slave(nullptr,<br>
&nbsp;&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"/tmp",<br>
&nbsp;&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"first_backup",<br>
&nbsp;&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"dar",<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;
false,<br>
&nbsp;&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"/tmp/toslave", // assuming this is an existing named pipe<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;
false,<br>
&nbsp;&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"/tmp/todar",&nbsp;&nbsp; // assuming this is also an existing named
pipe<br>
&nbsp;&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"echo 'reading slice %p/%b.%N.%e in context %c'",<br>
&nbsp;&nbsp; &nbsp; &nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
0);<br>
      <br>
slave.run();<br>
&nbsp; <br>
&nbsp; // once run() has returned, you can launch it again for another process or the same<br>
&nbsp; // one as previously has access to the /tmp/first_backup.*.dar archive<br>
</code>
      </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>23 - dar_xform API<br>
      </h2>dar_xform
creates a copy of a given archive modifying its slicing. it does not
require decompressing nor deciphering the archive to do so. There is
different constructor depending whether the archive is read from
filesystem, from a named pipe of from a provided file descriptor<br>
      <br>
      <span style="font-weight: bold;">Reading from a file</span><br>
      <br>
      <div style="margin-left: 40px;"><code></code><code>libdar_xform(const std::shared_ptr&lt;user_interaction&gt; &amp; ui,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; chem,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; basename,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; extension,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const infinint &amp; min_digits,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; execute);</code><br>
</div>
      
      <ul><li><span style="font-weight: bold;">ui</span> as seen for other libdar classes can be set to a null pointer for interaction on stdin and stdout</li><li><span style="font-weight: bold;">chem</span> is the directory where resides the archive to read</li><li><span style="font-weight: bold;">basename</span> is the basename of the archive</li><li><span style="font-weight: bold;">extension</span> should always be set to "dar"</li><li><span style="font-weight: bold;">min_digits</span> is the minimum number of digits slice number in filename have been created with (use zero if you don't know what it is)<br>
</li></ul><span style="font-weight: bold;">Reading from a named pipe</span><br>
      <br>
      <div style="margin-left: 40px;"><code>libdar_xform(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; pipename);</code><br>
      </div>
      <ul>
        <li><span style="font-weight: bold;">dialog</span> as seen for other libdar classes, it can be set to nullptr</li>
        <li><span style="font-weight: bold;">pipename</span> complete path to the named pipe to read the archive from</li>
      </ul>
      <span style="font-weight: bold;">Reading from a file descriptor</span><br>
      <br>
      <div style="margin-left: 40px;"><code>libdar_xform(const std::shared_ptr&lt;user_interaction&gt; &amp; dialog,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; int filedescriptor);</code><br>
      </div>
      <ul>
        <li><span style="font-weight: bold;">dialog</span> same as above</li>
        <li><span style="font-weight: bold;">filedescriptor</span> is an read opened file descriptor to read the archive from<br>
        </li>
      </ul>
Once the libdar::libdar_xform object is created it can copy the
referred archive to another location in another form thanks to one of
the two <span style="font-weight: bold;">libdar_xform::xform_to</span> methods. There is not link between the <span style="font-weight: bold;">constructor</span> used and the <span style="font-weight: bold;">libdar_xform::xform_to</span> flavor used, any combination is possible.<br>
      <br>
      <span style="font-weight: bold;">Creating a single or multi-sliced archive on filesystem<br>
      <br>
      </span>
      <div style="margin-left: 40px;"><code>void xform_to(const std::string &amp; path,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; basename,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; extension,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; bool allow_over,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; bool warn_over,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const infinint &amp; pause,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const infinint &amp; first_slice_size,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const infinint &amp; slice_size,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; slice_perm,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; slice_user,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; slice_group,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; hash_algo hash,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const infinint &amp; min_digits,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; execute);</code><br>
      </div>
      <br>
      <span style="font-weight: bold;">Creating a single sliced archive toward a filedescriptor</span><br>
      <br>
      <div style="margin-left: 40px;"><code>void xform_to(int filedescriptor,</code><br>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const std::string &amp; execute);</code><br>
      </div>
      <br>
Here follows an example of use. We will convert a possibly multi-sliced
archive to a single slice one generating a sha512 hash file on-fly<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);"><code></code><code>libdar::libdar_xform transform(nullptr,<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;
"/tmp",<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;
"my_first_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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"dar",<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;
0,<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;
"echo 'reading slice %p/%b.%N.%e context is %c'");<br>
      <br>
transform.xform_to("/tmp",<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"my_other_first_archive",<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "dar",<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
false,&nbsp;&nbsp;&nbsp;&nbsp; // no overwriting allowed<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
true,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // does not matter whether we warn
or not as we do not allow overwriting<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
0,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // no pause between
slices<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
0,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // no specific first
slice<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
0,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // no slicing at all
(previous argument is thus not used anyway)<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; // using default
permission for created slices<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; // using default user
ownership for created slices<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; // using default group
ownership for created slices<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
libdar::hash_algo::sha512, // the hash algo to use (for no hashing use
hash_none instead)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
0,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // min_digits ...
not using this feature here<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"echo 'Slice %p/%b.%N.%e has been written. Context is %c'");<br>
<br>
</code>
      </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;"><br>
      
      <h2>24 - Compilation &amp; Linking<br>
      </h2>

      <h3>Compilation</h3>
      <div style="text-align: justify;">All the symbols found in the
libdar API except the one relative to dar_manager (see below) are
defined from <span style="font-style: italic; font-weight: bold;">&lt;dar/libdar.h&gt;</span>.
So
you should only need to include this header. If the header file is not
located in a standard directory, in order to compile your code, you may
need some extra
flags to pass to the compiler (like -I/opt/...). The <span style="font-weight: bold;">pkg-config</span> tool can help here to
avoid system dependent
invocation:<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);"><br>
      <code></code><span style="font-family: monospace;">&gt; cat
my_prog.cpp</span><br style="font-family: monospace;">
      <br style="font-family: monospace;">
      <span style="font-weight: bold; font-family: monospace;">
#include &lt;dar/libdar.h&gt;</span><br style="font-family: monospace;">
      <br style="font-family: monospace;">
      <span style="font-family: monospace;">main()</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">{</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;
libdar::get_version(...);</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp; ...</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">}</span><br style="font-family: monospace;">
      <br style="font-family: monospace;">
      <span style="font-family: monospace;">&gt; <span style="font-weight: bold;">gcc `pkg-config --cflags libdar` -c
my_prog.cpp</span></span><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 rely on like libz, libbzip2, liblzo or
libgcrypt, depending on the feature activated at compilation time. Here
too, <span style="font-weight: bold;">pkg-config</span> can provide a
great help to avoid having system
dependent invocation:<code> </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;">pkg-confg --libs libdar`</span>
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 LIBDAR_MODE macro must be set to
32
or 64 when compiling or linking with libdar32 or libdar64
respectively. The LIBDAR_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. <span style="font-weight: bold;">pkg-config
--cflags</span> will set the
correct LIBDAR_MODE, so you should only bother calling it with either
libdar, libdar32 or libdar64 depending on your need : "<span style="font-weight: bold;">pkg-confg
--cflags libdar64</span>" for example.<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>&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;">`pkg-config --cflags
libdar32`</span>
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>
<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>
      </td>
    </tr>
  </tbody>
</table>
<br>
<br>
</center>

<br>
</body></html>