-
Notifications
You must be signed in to change notification settings - Fork 24
Expand file tree
/
Copy pathapi_tutorial.html
More file actions
2594 lines (2429 loc) · 106 KB
/
api_tutorial.html
File metadata and controls
2594 lines (2429 loc) · 106 KB
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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link href="style.css" rel="stylesheet">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
<title>Libdar API - Tutorial</title>
</head>
<body>
<div class=top>
<img alt="Dar Documentation" src="dar_s_doc.jpg" style="float:left;">
<div class=h1>
<h1>Libdar APplication Interface (API) tutorial</h1>
(API version 6.x.x)
</div>
</div>
<h2>Presentation</h2>
<p>
The Libdar library provides a
complete abstraction layer for handling
<i>Dar</i> archives. The general
operations provided are:
</p>
<ul>
<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</li>
<li>dar_manager database manipulations</li>
<li>dar_slave steering</li>
<li>dar_xform operation</li>
</ul>
<p>
Note that <i>Disk ARchive</i> <b>and</b>
<i>libdar</i>
have been released under the <b>Gnu
General Public License (GPL)</b>.
All code linked to libdar
(statically or dynamically), <b>must</b>
also be covered by the GPL or compatible license.
Commercial use is prohibited unless otherwise
explicitely agreeded with libdar's author.
</p>
<p>
This tutorial will show you how to
use the libdar API. Since release 2.0.0 the
<i>dar</i> 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 <code>src/dar_suite/dar.cpp</code>
is the primary consumer of the libdar API.
However we will see here, step by step how
you can leverage the API for your own use.
</p>
<p>
In the following sample codes will be provided, they
are solely illustrative and is not guaranteed to compile.
Reference documentation for this API
is contained in the source code as doxygen comment which
can be extracted and "compiled" in the
the <code>doc/html</code> directory when compiling dar/libdar.
This API reference document is also available
<a href="http://dar.linux.free.fr/doc/html/index.html">online</a>
and will be referred below as the <i>API reference documentation</i>.
</p>
<h2>Let's Start</h2>
<h3>Conventions</h3>
<h4>Language</h4>
<p>
Dar and libdar are written in
C++, and so is the libdar fundamental API. Though you can find
a <b>Python</b> binding in the <code>src/python</code> subdirectory,
which strongly follows the class hierarchy that will see here with
C++ sample code. The <a href="python/libdar_test.py">libdar_test.py</a>
document rawly follows with <i>python</i> code what we will see
below with C++.
</p>
<p>
Feel free to contribute if you want bindings for other languages.
</p>
<h4>Header files</h4>
<p>
Only one include file is required in your program to have access to
libdar:
</p>
<code class=block>
#include <dar/libdar.hpp>
</code>
<h4>Libdar namespace</h4>
<p>
All libdar symbols are defined within
the <b>libdar namespace</b>. You
can either add the <code>using namespace libdar;</code>
statement at the beginning of your source files...
</p>
<code class=block>
using namespace libdar;
get_version();
...
</code>
<p>
...or, as shown below, you can
explicitly use the namespace in front of libdar symbols,
we will use this notation in the following, which has the
advantage of avoiding name conflicts and clarify origin of the
symbols used, but lead to a more heavier code, less easy to
read:
</p>
<code class=block>
libdar::get_version();
...
</code>
<h4>Exceptions</h4>
<p>
The library makes use of
exception to report unexpected conditions. These contain the reason and
context the error occurred in, so you can be catch these in your code
to display details of the error and its cause. All exceptions used within
libdar inherit from the pure virtual class <b>libdar::Egeneric</b>
</p>
<p>
Most of the time you will use only one of the following two methods:
</p>
<ul>
<li><code>std::string & get_message() const</code></li>
<li><code>std::string & dump_str() const</code></li>
</ul>
<dl>
<dt class=void>get_message()</dt><dd>
returns a message string describing the error met
</dd>
<dt class=void>dump_str()</dt><dd>
returns a text paragraph with additional information about
the stack as well as context the error occurred in.
</dd>
</dl>
<p>
Now, messages are for human, you may need to provide different
behaviors depending on the type of the error libdar has met and
which triggers such exception. This is can be done by checking the
type of the exception.
</p>
<p>
We will only focus on most common exception type read the
<i>API reference documentation</i> for an exhaustive list of the exception
type used by libdar:
</p>
<dl>
<dt class=void>libdar::Ebug</dt><dd>
This one is used when <i>a-situation-that-should-never-occur</i>
is met and can be assumed to be a bug in libdar. Using the
<code>get_message()</code> method in that
situation would not provide all necessary details to understand
and fix the bug, so it is advised to always use <code>dump_str()</code>
for that specific type of exception and abort further execution regarding
libdar.
</dd>
<dt class=void>libdar::Erange</dt><dd>
A parameter or a value is out of range, details is provided
with <code>get_message()</code>
</dd>
<dt class=void>libdar::Ememory</dt><dd>
Libdar lacked of virtual memory to proceed to the requested operation
</dd>
<dt class=void>libdar::Einfinint</dt><dd>
an arythmetic error occurred when using <code>libdar::infinint</code>
object, which is a internal integer type that can handle arbitrary
large numbers. Today it is only used if libdar has been compiled
with <code>--enable-mode=infinint</code> so you are not likely to meet
it.
</dd>
<dt class=void>libdar::Elimitint</dt><dd>
when <i>infinint</i> are not used, a wrapper class over system
integers is used to detect integer overflow. In that situation,
this exception is thrown, enjoying the user to use a <i>infinint</i>
based flavor of libdar to avoid this error
</dd>
<dt class=void>libdar::Ehardware</dt><dd>
used when the operating system returned an I/O error or hardware
related error
</dd>
<dt class=void>libdar::Esystem</dt><dd>
When software related error is reported by the system, like lack of
ownership, permission or non existing file...
</dd>
<dt class=void>libdar::Euser_abort</dt><dd>
This exception is thrown as the consequence of user request to
abort the process. This may occur when aswnering to a question
issued by libdar.
</dd>
<dt class=void>libda::Ethread_cancel</dt><dd>
used when a program has called the thread cancellation routine
of libdar, which drives libdar to stop as soon as possible (immediately
when the control point is met, or delayed aborting cleanly the operation
under process depending on the option used to cancel the running libdar
thread.
</dd>
</dl>
<p>
Some other exist and are well described in the
<i>API reference documentation</i>. You can thus wrap the whole
libdar interaction with a statement like in the following example:
</p>
<code class=block>
try
{
// calls to libdar
...
//
}
catch(libdar::Ebug & e)
{
std::string msg = e.dump_str();
// do something with msg like for example:
std::cerr << msg << std::endl;
}
catch(libdar::Euser_abort & e)
{
// some specific treatment for this
// type of exception
...
}
catch(libdar::Egeneric & e)
{
// a global treatment for all other libdar exceptions
std::string msg = e.get_message(); << std::endl;
...
}
</code>
<h2>First we must initialize libdar</h2>
<p>
the libdar initialization is
performed by calling the <code>libdar::get_version()</code>
function.
</p>
<p>
This function can be called several time though only once is necessary,
but this call has to complete before any other call to libdar.
</p>
<p>
In a <b>multi-thread context</b> libthreadar
initialization is not re-entrant. In other word the first
call to <code>libdar::get_version()</code> must complete
before any other call to libdar can take place in another
thread of the running process. Once libdar has
been initialized, you can call <code>libdar::get_version()</code>
concurrently from several threads at the same time without
problem.
</p>
<code class=block>
libdar::get_version();
</code>
<h2>We should prepare the end right now</h2>
<p>
Libdar used some
data-structures (mutex, secured memory, etc.) that need to be released
properly before ending the process. It is important to invoke the
<code>close_and_clean()</code> function before exiting your program if you
had called <code>get_version()</code> previously. After that,
the only allowed call to libdar is <code>get_version()</code>.
</p>
<code class=block>
libdar::close_and_clean()
</code>
<dl>
<dt class=void>Note:</dt><dd>
<code>closes_and_clean()</code>
makes the necessary for memory to be released in the
proper order.
<u>
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.
</u>
This depends on the compiler, libc and option
activated in libdar at compilation time.
</dd>
</dl>
<p>
All in one, at the highest level, you code should look like the following:
</p>
<code class=block>
libdar::get_version();
try
{
try
{
// calls to libdar
// thing we will see in next
...
...
}
catch(libdar::Ebug & e)
{
std::string msg = e.dump_str();
// do something with msg like for example:
std::cerr << msg << std::endl;
}
catch(libdar::Egeneric & e)
{
std::string msg = e.get_message();
// do something with msg like for example
std::cerr << msg << std::endl;
}
}
catch(...)
{
libdar::close_and_clean();
throw;
}
libdar::close_and_clean();
</code>
<h2>Intercepting signals</h2>
<p>
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 (<code>signal(SIGPIPE, SIG_IGN)</code>)
or provide an adhoc handle.
By default the PIPE signal leads the receiving process to terminate.
</p>
<h2>Libdar classes</h2>
<p>
The main components of libdar are four classes:
</p>
<ul>
<li><b>class libdar::archive</b> to play with dar archives</li>
<li><b>class libdar::database</b> to play with dar_manager databases</li>
<li><b>class libdar::libdar_slave</b> to take the role of dar_slave</li>
<li><b>class libdar::libdar_xform</b> to re-slice existing archives like dar_xform does</li>
</ul>
<p>
In the following we will first see <b>class libdar::archive</b>
which will take most of our effort as other
classes which we will see at the end are very trivial.
</p>
<h2>Multithreaded environment</h2>
<p>
Except when explicitely 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 libdar 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.
</p>
<h2>Let's create a simple archive</h2>
<p>
Creating a <code>libdar::archive</code> object depending on
the constructor used, leads to either:
</p>
<ul>
<li>
the <b>creation of a brand new archive</b> on filesystem, thus
performing a backup (full, incremental, differential,
decremental, ...)
</li>
<li>
the <b>opening an existing archive</b>, for further
operation (listing, file restoration, archive testing,
archive difference, ...)
</li>
<li>
<b>merging</b> the content of two existing archives into a new one
</li>
<li>
the <b>reparing</b> of an archive which catalogue is missing
or damaged. The <i>catalogue</i>
(which means catalog in French) is the table of content
of an archive.
</li>
</ul>
<h3>Basic archive creation</h3>
<p>
For <b>archive creation</b> the
constructor format is the following one:
</p>
<code class=block>
archive::archive(const std::shared_ptr<user_interaction> & <b>dialog</b>,
const path & <b>fs_root</b>,
const path & <b>sauv_path</b>,
const std::string & <b>filename</b>,
const std::string & <b>extension</b>,
const archive_options_create & <b>options</b>,
statistics * <b>progressive_report</b>);
</code>
<p>
For now we will left beside some parameters, that we will see
in detail later:
</p>
<ul>
<li>
<b>dialog</b> can be set to <b>std::nullptr</b> for now, this means
that all interaction with the user will take place by mean of standard
input, output and error.
</li>
<li>
<b>fs_root</b> is the directory to take as
root of the backup. The <b>libdar::path</b>
class can be setup from a <b>std::string</b>, which
in turn can be setup from a classical <b>char*</b>
</li>
<li>
<b>sauv_path </b> is the path where to
write the archive to, here also a <b>std::string</b>
will do the job
</li>
<li>
<b>filename</b> is the <i>slice name</i> to use for
the archive we will create.
</li>
<li>
<b>extension</b> is the archive extension
to use. There is no reason to not use the string
<b>"dar"</b> here
</li>
<li>
<b>options</b> is a class that carries all
optional parameters, it contains a
<i>constructor without argument</i> setting
all options are set to their default values
</li>
<li>
<b>statistics</b> can
receive the address of an existing object that another thread can read
while a first one is doing a backup operation (a first case of libdar
object that can be used by several threads at the same time). We will see this feature
later on, but for now let's set this to a <b>null pointer</b> (i.e.: std::nullptr)
</li>
</ul>
<p>
Once the object has been created (the constructor has returned), the
archive operation has completed and a new backup has been completely
written on disk.
</p>
<code class=block>
libdar::archive my_first_backup(nullptr,
"/home/me",
"/tmp",
"first_backup",
"dar",
libdar::archive_options_create(),
std::nullptr);
</code>
<p>
The previous example has create a single sliced archive
<b>first_backup.1.dar</b> located under
<b>/tmp</b>. This backup contains the content of
the directory <b>/home/me</b>
and its sub-directories, without compression
and without ciphering. You have guessed: compression,
slicing, ciphering can be set by playing with
passing an adhoc <b>archive_option_create</b>
object to this archive constructor, something we will
see in details a bit further.
</p>
<p>
Once the object <code>my_first_backup</code>
has been created there is only little thing we can do
with it: only archive listing or archive isolation. For archive
extraction, testing or diffing, we needs creating a new object with a
"read" constructor.
<p>
If we had allocated the archive on the heap (using <code>new</code>),
we would have just added the <code>delete</code> invocation right
after the construction of the <code>my_first_backup</code>
object:
</p>
<code class=block>
libdar::archive* my_first_backup = new libdar::archive(nullptr,
"/home/me",
"/tmp",
"first_backup",
"dar",
libdar::archive_options_create(),
nullptr);
// we assume std::bad_alloc would be thrown if an allocation
// problem had occurred
// same thing if libdar throws an exception at constructor time,
// the object would not be created and would not have to be deleted.
// So now we can delete the created object:
delete my_first_backup;
</code>
<h3>Progressive report</h3>
<p>
During the operation we get nothing shown unless an error occurs.
To provide more visibility on the process we will use an
<b>libdar::statistics</b>
object passed as last argument of this constructor. Then we will
use some interesting method of class <class>libdar::statistics</class>:
</p>
<ul>
<li>std::string <b>get_treated_str()</b></li>
<li>std::string <b>get_hard_links_str()</b></li>
<li>std::string <b>get_skipped_str()</b></li>
<li>std::string <b>get_inode_only_str()</b></li>
<li>std::string <b>get_ignored_str()</b></li>
<li>std::string <b>get_tooold_str()</b></li>
<li>std::string <b>get_errored_str()</b></li>
<li>std::string <b>get_deleted_str()</b></li>
<li>std::string <b>get_ea_treated_str()</b></li>
<li>std::string <b>get_byte_amount_str()</b></li>
<li>std::string <b>get_fsa_treated_str()</b></li>
</ul>
<p>
If you have a doubt about the meaning and use of a particular counter
in a particular operation, please refer to <i>API reference documentation</i>
for class <code>libdar::statistics</code>, the private fields
corresponding to these counter are explicitly defined there.
</p>
<code class=block>
<b>libdar::statistics <e>stats</e>;</b>
libdar::archive my_first_backup(nullptr,
"/home/me",
"/tmp",
"first_backup",
"dar",
libdar::archive_options_create(),
<e>& stats</e>);
// in another thread we can see the progression:
std::cout << <e>stats</e>.get_treated_str()
<< " file(s) saved" << std::endl;
std::cout << <e>stats</e>.get_errored_str()
<< " file(s) failed to backup" << std::endl;
std::cout << <e>stats</e>.get_ea_treated_str()
<< " Extended Attributes saved" < std::endl;
</code>
<h3>Archive creation options</h3>
<p>
in the previous example, we
have created an temporary object of class <b>libdar::archive_options_create</b> and
passed it on-fly to the archive constructor without modifying it. Thus
we used the default options for this operations. But <b>a lot</b>
of options are available, each one can be modified by a specific
method of this class Follow is a subset of the
available options. We won't details them all, but you can refer the doxygen
documentation for <b>class libdar::archive_options_create</b> for additional information.
</p>
<ul>
<li><code>void <b>set_reference</b>(<b>std::shared_ptr<libdar::archive></b> ref_arch)</code></li>
<li><code>void <b>set_selection</b>(const <b>libdar::mask</b> & selection)</code></li>
<li><code>void <b>set_subtree</b>(const <b>libdar::mask</b> & subtree)</code></li>
<li><code>void <b>set_allow_over</b>(bool allow_over)</code></li>
<li><code>void <b>set_warn_over</b>(bool warn_over)</code></li>
<li><code>void <b>set_info_details</b>(bool info_details)</code></li>
<li><code>void <b>set_display_treated</b>(bool display_treated, bool only_dir)</code></li>
<li><code>void <b>set_display_skipped</b>(bool display_skipped)</code></li>
<li><code>void <b>set_display_finished</b>(bool display_finished)</code></li>
<li><code>void <b>set_pause</b>(const <b>libdar::infinint</b> & pause)</code></li>
<li><code>void <b>set_empty_dir</b>(bool empty_dir)</code></li>
<li><code>void <b>set_compression</b>(<b>libdar::compression</b> compr_algo)</code></li>
<li><code>void <b>set_compression_level</b>(<b>libdar::U_I</b>compression_level)</code></li>
<li><code>void <b>set_slicing</b>(const <b>libdar::infinint</b> & file_size, const <b>libdar::infinint</b> & first_file_size)</code></li>
<li><code>void <b>set_ea_mask</b>(const <b>libdar::mask</b> & ea_mask)</code></li>
<li><code>void <b>set_execute</b>(const std::string & execute)</code></li>
<li><code>void <b>set_crypto_algo</b>(<b>libdar::crypto_algo</b>crypto)</code></li>
<li><code>void <b>set_crypto_pass</b>(const <b>libdar::secu_string</b> & pass)</code></li>
<li><code>void <b>set_compr_mask</b>(const <b>libdar::mask</b> & compr_mask);</code></li>
<li><code>void <b>set_min_compr_size</b>(const <b>libdar::infinint</b> & min_compr_size)</code></li>
<li><code>void <b>set_nodump</b>(bool nodump)</code></li>
<li><code>void <b>set_exclude_by_ea</b>(const std::string & ea_name)</code></li>
<li><code>void <b>set_what_to_check</b>(<b>libdar::comparison_fields</b> what_to_check)</code></li>
<li><code>void <b>set_hourshift</b>(const <b>libdar::infinint</b> & hourshift)</code></li>
<li><code>void <b>set_empty</b>(bool empty)</code></li>
<li><code>void <b>set_alter_atime</b>(bool alter_atime)</code></li>
<li><code>void <b>set_furtive_read_mode</b>(bool furtive_read)</code></li>
<li><code>void <b>set_same_fs</b>(bool same_fs)</code></li>
<li><code>void <b>set_snapshot</b>(bool snapshot)</code></li>
<li><code>void <b>set_cache_directory_tagging</b>(bool cache_directory_tagging)</code></li>
<li><code>void <b>set_fixed_date</b>(const <b>libdar::infinint</b> & fixed_date)</code></li>
<li><code>void <b>set_slice_permission</b>(const std::string & slice_permission)</code></li>
<li><code>void <b>set_slice_user_ownership</b>(const std::string & slice_user_ownership)</code></li>
<li><code>void <b>set_slice_group_ownership</b>(const std::string & slice_group_ownership)</code></li>
<li><code>void <b>set_retry_on_change</b>(const <b>libdar::infinint</b> & count_max_per_file, const <b>libdar::infinint</b> & global_max_byte_overhead)</code></li>
<li><code>void <b>set_security_check</b>(bool check)</code></li>
<li><code>void<b> set_user_comment</b>(const std::string & comment)</code></li>
<li><code>void <b>set_hash_algo</b>(<b>libdar::hash_algo</b> hash)</code></li>
<li><code>void <b>set_slice_min_digits</b>(<b>libdar::infinint</b> val)</code></li>
<li><code>void <b>set_backup_hook</b>(const std::string & execute, const <b>mask</b> & which_files);</code></li>
<li><code>void <b>set_delta_diff</b>(bool val)</code></li>
<li><code>void <b>set_delta_signature</b>(bool val)</code></li>
<li><code>void <b>set_delta_mask</b>(const <b>libdar::mask</b> & delta_mask)</code></li>
</ul>
<p>
First you may have find some new libdar types (=classes) in arguments, we will
briefly explain how to set them:
</p>
<dl>
<dt class=void>std::shared_ptr<libdar::archive></dt><dd>
<p>
C++11 shared smart-pointer to an existing libdar::archive object. We will see
how to use it next when performing differential backup
</p>
</dd>
<dt class=void>libdar::infinint</dt><dd>
<p>
can be set from a <b>classical unsigned int</b>,
unsigned long or other unsigned integer type, so
for you this is like another unsigned integer type
</p>
</dd>
<dt class=void>libdar::mask</dt><dd>
<p>
This class is a top of a class hierarchy containing
several classes provided with libdar. It allows you
to define a filtering mecanism for the feature wher
it is used. We will see how to use it in a further
paragraph of this tutorial.
</p>
</dd>
<dt class=void>libdar::compression</dt><dd>
<p>
It is an enumeration which values are (among others
not listed here):
</p>
<ul>
<li><code>libdar::compression::<b>gzip</b></code></li>
<li><code>libdar::compression::<b>bzip2</b></code></li>
<li><code>libdar::compression::<b>xz</b></code></li>
<li><code>libdar::compression::<b>lzo</b></code></li>
</ul>
<br/>
</dd>
<dt class=void>libdar::U_I</dt><dd>
<p>
A the opposite of the libdar::infinint this is not a class
but an alias to the system classical unsigned integer. Depending
on the operating system and CPU this might point to <i>unsigned long</i>
or <i>unsigned long long</i> or other equivalent type.
</p>
</dd>
<dt class=void>libdar::crypto_algo</dt><dd>
<p>
This is an enumeration with values like:
</p>
<ul>
<li><code>libdar::crypto_algo::<b>scrambling</b></code></li>
<li><code>libdar::crypto_algo::<b>blowfish</b></code></li>
<li><code>libdar::crypto_algo::<b>aes256</b></code></li>
<li><code>libdar::crypto_algo::<b>twofish256</b></code></li>
<li><code>libdar::crypto_algo::<b>serpent256</b></code></li>
<li><code>libdar::crypto_algo::<b>camellia256</b></code></li>
</ul>
<br/>
</dd>
<dt class=void>libdar::secu_string</dt><dd>
<p>
This is a class used to securely storing password and sensible
cryptographic information. It can be setup from a char* or
better, from a filedescriptor. its main constructor is:
</p>
<ul>
<li>secu_string(<b>const char*</b> ptr, U_I <b>size</b>)</li>
</ul>
<br/>
</dd>
<dt class=void>libdar::comparison_fields</dt><dd>
<p>
This is an enumeration with values like:
</p>
<ul>
<li><code>libdar::comparison_fields::<b>all</b></code></li>
<li><code>libdar::comparison_fields::<b>ignore_owner</b></code></li>
<li><code>libdar::comparison_fields::<b>mtime</b></code></li>
<li><code>libdar::comparison_fields::<b>inode_type</b></code></li>
</ul>
</dd>
</dl>
<p>
Follows a variant of the previous backup creation example,
here we set some options to a given value:
</p>
<code class=block>
libdar::archive_options_create <b>opt</b>;
<b>opt</b>.set_allow_over(false);
// forbids slice overwriting
<b>opt</b>.set_display_finished(true);
// show a summary after each completed directory
<b>opt</b>.set_slicing(1024000,
2000);
// slices of 1000 kiB initial slice of 2000 bytes
<b>opt</b>.set_pause(2);
// pause every two slices
<b>opt</b>.set_execute("echo slice %N completed");
// command executed after each slice
<b>opt</b>.set_crypto_algo(libdar::crypto_algo::aes256);
// providing an empty secu_string leads dar
// interactively ask the passphrase in a secure manner
<b>opt</b>.set_crypto_pass(secu_string());
// But this previous call is useless as en empty secu_string is the default
// though one could have setup a secu_string from a std::string
// this way:
std::string my_pass("hello world!");
libdar::secu_string my_secupass(my_pass.c_str(), my_pass.size());
<b>opt</b>.set_crypto_pass(my_secupass);
<b>opt</b>.set_compression(libdar::compression::xz);
<b>opt</b>.set_compression_level(6);
<b>opt</b>.set_min_compr_size(10240);
// not trying compressing file smaller than 10 kiB
// now we have the <b>opt</b> option object ready
// we can proceed to the archive creation using it:
libdar::archive my_first_backup(nullptr,
"/home/me",
"/tmp",
"first_backup",
"dar",
<b>opt</b>,
nullptr);
</code>
<p>
And of course, you can use both <b>libdar::statistics</b>
and <b>libdar::archive_options_create</b> at
the same time, when creating a backup
</p>
<h2>Creating a differential or incremental backup</h2>
<p>
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.
</p>
<p>
The read-only constructor for class archive is the following:
</p>
<code class=block>
archive::archive(const std::shared_ptr<user_interaction> & <b>dialog</b>,
const path & <b>chem</b>,
const std::string & <b>basename</b>,
const std::string & <b>extension</b>,
const archive_options_read & <b>options</b>);
</code>
<p>
same as before:
</p>
<ul>
<li>
<b>dialog</b> can be set to a <b>null pointer</b>, we will see
further in this tutorial how to play with
<code>user_interaction</code> class
</li>
<li>
<b>chem</b> is the path leading to the
archive to read, it can be provided as a <b>std::string</b> or
even a <b>char*</b>
</li>
<li>
<b>basename</b> is the archive basename to read
</li>
<li>
<b>extension</b> should be <b>"dar"</b> unless you want
to confuse people
</li>
<li>
<b>options</b> can be set to an empty object for default
options, we will see this class in more
details with archive listing
</li>
</ul>
<br/>
<code class=block>
// first we open the previously created archive in read mode:
std::shared_ptr<libdar::archive> <e>ref_archive</e>;
<e>ref_archive</e> = std::make_shared<libdar::archive>(nullptr,
"/home/me",
"first_backup",
"dar",
archive_create_options_read());
// for clarity we separated the creation of the
// archive object used as archive of reference from
// the archive object which creation will perform
// differential backup (see below). We could have made
// in one step using an anonymous temporary object
// (in place of <code>ref_archive</code>)
// invoking directly <code>std::make_shared</code>
// when calling <code>set_reference()</code> below:
libdar::archive_options_create <b>opt</b>;
<b>opt</b>.set_reference(<e><b>ref_archive</b></e>);
libdar::archive my_second_backup(nullptr,
"/home/me",
"/tmp",
"diff_backup",
"dar",
<b>opt</b>,
nullptr);
</code>
<p>
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).
</p>
<h2>Archive listing</h2>
<p>
Archive listing operation consist of the creation of an archive object
in read mode as we just did above for <code>ref_archive</code> 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
<code>libdar::archive_create_options_read</code> which
we just skip over previously.
</p>
<h3>Archive reading options</h3>
<p>
The same as the class <code>archive_options_create</code> detailed above, the
class <code>archive_options_read</code> 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:
</p>
<ul>
<li>void <b>set_execute</b>(const std::string & execute)</li>
<li>void <b>set_info_details</b>(bool info_details)</li>
<li>void <b>set_sequential_read</b>(bool val)</li>
<li>void <b>set_slice_min_digits</b>(infinint val)</li>
</ul>
<p>
<code>set_execute()</code> runs a command before reading a new slice of the
archive. See API reference documentation for details. You will meet
class <code>archive_options_create</code> in order to test an archive,
compare an archive with filesystem, isolate an archive and repair an archive.
</p>
<h3>Listing methods</h3>
<p>
There is several ways to read an given archive contents:
</p>
<ol>
<li>
<p>
making use of a callback function that will be called in turn
for <u>each entry of the archive</u> even special entries that
flag the end of a directory and the next entry will be located in the parent directory:
</p>
<code class=block>
void <b>op_listing</b>(libdar::archive_listing_callback <b>callback</b>,
void *<b>context</b>,
const libdar::archive_options_listing & <b>options</b>) const;
</code>
</li>
<li>
<p>
using the same callback but only for the different <u>entries of a given directory</u>,
directory that has to exist in the archive of course. It returns false
when the end of the directory has been reached:
</p>
<code class=block>
bool <b>get_children_of</b>(libdar::archive_listing_callback <b>callback</b>,
void *<b>context</b>,
const std::string & <b>dir</b>,
bool <b>fetch_ea</b> = false);
</code>
</li>
<li>
<p>
like previous <u>listing a given directory content</u> but returning
a vector of objects <b>libdar::list_entry</b> that provide
detailed information about each entry, no callback is used here:
</p>
<code class=block>
const std::vector<libdar::list_entry> <b>get_children_in_table</b>(const std::string & dir,
bool <b>fetch_ea</b> = false) const;
</code>
</li>
</ol>
<p>
<b>For the two first methods</b>
you have to define a callback function of the following form:
</p>
<code class=block>
void (*)(const std::string & the_path,
const list_entry & entry,
void *context);
</code>
<p>
This callback will receive as argument the full path of the object,
a <b>libdar::list_entry</b> object providing
much details on it <b>and</b> the "context" value passed as argument
of <b>archive::op_listing()</b> or <b>archive::get_children_of()</b>
</p>
<p>
In the following example we will use only a few methods of
class <b>libdar::list_entry</b> that are available to get detail
of a given entry of an archive, feel free to explore this class's
documentation for to get all details:
</p>
<code class=block>
// we first create a read-mode archive object that will be used
// in the three following examples,
libdar::archive_options_read opt;
opt.set_info_details(true);
opt.set_execute("echo 'about to read slice %p/%b.%N.%e with context %c'");
libdar::archive <b>my_backup</b>(nullptr, // this is user_interaction we will see further
"/home/me",
"diff_backup",
"dar",
opt);
</code>
<br/>
<code class=block>