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
|
<!-- Creator : groff version 1.19.2 -->
<!-- CreationDate: Thu Feb 4 20:36:31 2010 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; }
pre { margin-top: 0; margin-bottom: 0; }
table { margin-top: 0; margin-bottom: 0; }
</style>
<title></title>
</head>
<body>
<hr>
<p valign="top">archive_read(3) FreeBSD Library Functions
Manual archive_read(3)</p>
<p style="margin-top: 1em" valign="top"><b>NAME</b></p>
<p style="margin-left:8%;"><b>archive_read_new</b>,
<b>archive_read_set_filter_options</b>,
<b>archive_read_set_format_options</b>,
<b>archive_read_set_options</b>,
<b>archive_read_support_compression_all</b>,
<b>archive_read_support_compression_bzip2</b>,
<b>archive_read_support_compression_compress</b>,
<b>archive_read_support_compression_gzip</b>,
<b>archive_read_support_compression_lzma</b>,
<b>archive_read_support_compression_none</b>,
<b>archive_read_support_compression_xz</b>,
<b>archive_read_support_compression_program</b>,
<b>archive_read_support_compression_program_signature</b>,
<b>archive_read_support_format_all</b>,
<b>archive_read_support_format_ar</b>,
<b>archive_read_support_format_cpio</b>,
<b>archive_read_support_format_empty</b>,
<b>archive_read_support_format_iso9660</b>,
<b>archive_read_support_format_mtree,
archive_read_support_format_raw,
archive_read_support_format_tar</b>,
<b>archive_read_support_format_zip</b>,
<b>archive_read_open</b>, <b>archive_read_open2</b>,
<b>archive_read_open_fd</b>, <b>archive_read_open_FILE</b>,
<b>archive_read_open_filename</b>,
<b>archive_read_open_memory</b>,
<b>archive_read_next_header</b>,
<b>archive_read_next_header2</b>, <b>archive_read_data</b>,
<b>archive_read_data_block</b>,
<b>archive_read_data_skip</b>,
<b>archive_read_data_into_buffer</b>,
<b>archive_read_data_into_fd</b>,
<b>archive_read_extract</b>, <b>archive_read_extract2</b>,
<b>archive_read_extract_set_progress_callback</b>,
<b>archive_read_close</b>, <b>archive_read_finish</b>
— functions for reading streaming archives</p>
<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p>
<p style="margin-left:8%;"><b>#include
<archive.h></b></p>
<p style="margin-left:8%; margin-top: 1em"><i>struct
archive *</i></p>
<p style="margin-left:14%;"><b>archive_read_new</b>(<i>void</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_compression_all</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_compression_bzip2</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_compression_compress</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_compression_gzip</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_compression_lzma</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_compression_none</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_compression_xz</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p valign="top"><b>archive_read_support_compression_program</b>(<i>struct archive *</i>,
<i>const char *cmd</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p valign="top"><b>archive_read_support_compression_program_signature</b>(<i>struct archive *</i>,
<i>const char *cmd</i>,
<i>const void *signature</i>,
<i>size_t signature_length</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_format_all</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_format_ar</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_format_cpio</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_format_empty</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_format_iso9660</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_format_mtree</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_format_raw</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_format_tar</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_support_format_zip</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_set_filter_options</b>(<i>struct archive *</i>,
<i>const char *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_set_format_options</b>(<i>struct archive *</i>,
<i>const char *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_set_options</b>(<i>struct archive *</i>,
<i>const char *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p valign="top"><b>archive_read_open</b>(<i>struct archive *</i>,
<i>void *client_data</i>,
<i>archive_open_callback *</i>,
<i>archive_read_callback *</i>,
<i>archive_close_callback *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p valign="top"><b>archive_read_open2</b>(<i>struct archive *</i>,
<i>void *client_data</i>,
<i>archive_open_callback *</i>,
<i>archive_read_callback *</i>,
<i>archive_skip_callback *</i>,
<i>archive_close_callback *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_open_FILE</b>(<i>struct archive *</i>,
<i>FILE *file</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_open_fd</b>(<i>struct archive *</i>,
<i>int fd</i>, <i>size_t block_size</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p valign="top"><b>archive_read_open_filename</b>(<i>struct archive *</i>,
<i>const char *filename</i>,
<i>size_t block_size</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_open_memory</b>(<i>struct archive *</i>,
<i>void *buff</i>, <i>size_t size</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_next_header</b>(<i>struct archive *</i>,
<i>struct archive_entry **</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_next_header2</b>(<i>struct archive *</i>,
<i>struct archive_entry *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>ssize_t</i></p>
<p style="margin-left:14%;"><b>archive_read_data</b>(<i>struct archive *</i>,
<i>void *buff</i>, <i>size_t len</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p valign="top"><b>archive_read_data_block</b>(<i>struct archive *</i>,
<i>const void **buff</i>, <i>size_t *len</i>,
<i>off_t *offset</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_data_skip</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_data_into_buffer</b>(<i>struct archive *</i>,
<i>void *</i>, <i>ssize_t len</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_data_into_fd</b>(<i>struct archive *</i>,
<i>int fd</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p valign="top"><b>archive_read_extract</b>(<i>struct archive *</i>,
<i>struct archive_entry *</i>,
<i>int flags</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p valign="top"><b>archive_read_extract2</b>(<i>struct archive *src</i>,
<i>struct archive_entry *</i>,
<i>struct archive *dest</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>void</i></p>
<p valign="top"><b>archive_read_extract_set_progress_callback</b>(<i>struct archive *</i>,
<i>void (*func)(void *)</i>,
<i>void *user_data</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_close</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_finish</b>(<i>struct archive *</i>);</p>
<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p>
<p style="margin-left:8%;">These functions provide a
complete API for reading streaming archives. The general
process is to first create the struct archive object, set
options, initialize the reader, iterate over the archive
headers and associated data, then close the archive and
release all resources. The following summary describes the
functions in approximately the order they would be used:</p>
<p valign="top"><b>archive_read_new</b>()</p>
<p style="margin-left:20%;">Allocates and initializes a
struct archive object suitable for reading from an
archive.</p>
<p valign="top"><b>archive_read_support_compression_bzip2</b>(),
<b>archive_read_support_compression_compress</b>(),
<b>archive_read_support_compression_gzip</b>(),
<b>archive_read_support_compression_lzma</b>(),
<b>archive_read_support_compression_none</b>(),
<b>archive_read_support_compression_xz</b>()</p>
<p style="margin-left:20%;">Enables auto-detection code and
decompression support for the specified compression. Returns
<b>ARCHIVE_OK</b> if the compression is fully supported, or
<b>ARCHIVE_WARN</b> if the compression is supported only
through an external program. Note that decompression using
an external program is usually slower than decompression
through built-in libraries. Note that
‘‘none’’ is always enabled by
default.</p>
<p valign="top"><b>archive_read_support_compression_all</b>()</p>
<p style="margin-left:20%;">Enables all available
decompression filters.</p>
<p valign="top"><b>archive_read_support_compression_program</b>()</p>
<p style="margin-left:20%;">Data is fed through the
specified external program before being dearchived. Note
that this disables automatic detection of the compression
format, so it makes no sense to specify this in conjunction
with any other decompression option.</p>
<p valign="top"><b>archive_read_support_compression_program_signature</b>()</p>
<p style="margin-left:20%;">This feeds data through the
specified external program but only if the initial bytes of
the data match the specified signature value.</p>
<p valign="top"><b>archive_read_support_format_all</b>(),
<b>archive_read_support_format_ar</b>(),
<b>archive_read_support_format_cpio</b>(),
<b>archive_read_support_format_empty</b>(),
<b>archive_read_support_format_iso9660</b>(),
<b>archive_read_support_format_mtree</b>(),
<b>archive_read_support_format_tar</b>(),
<b>archive_read_support_format_zip</b>()</p>
<p style="margin-left:20%;">Enables support---including
auto-detection code---for the specified archive format. For
example, <b>archive_read_support_format_tar</b>() enables
support for a variety of standard tar formats, old-style
tar, ustar, pax interchange format, and many common
variants. For convenience,
<b>archive_read_support_format_all</b>() enables support for
all available formats. Only empty archives are supported by
default.</p>
<p valign="top"><b>archive_read_support_format_raw</b>()</p>
<p style="margin-left:20%;">The
‘‘raw’’ format handler allows
libarchive to be used to read arbitrary data. It treats any
data stream as an archive with a single entry. The pathname
of this entry is ‘‘data’’; all other
entry fields are unset. This is not enabled by
<b>archive_read_support_format_all</b>() in order to avoid
erroneous handling of damaged archives.</p>
<p valign="top"><b>archive_read_set_filter_options</b>(),
<b>archive_read_set_format_options</b>(),
<b>archive_read_set_options</b>()</p>
<p style="margin-left:20%;">Specifies options that will be
passed to currently-registered filters (including
decompression filters) and/or format readers. The argument
is a comma-separated list of individual options. Individual
options have one of the following forms:</p>
<p valign="top"><i>option=value</i></p>
<p style="margin-left:32%;">The option/value pair will be
provided to every module. Modules that do not accept an
option with this name will ignore it.</p>
<p valign="top"><i>option</i></p>
<p style="margin-left:32%; margin-top: 1em">The option will
be provided to every module with a value of
‘‘1’’.</p>
<p valign="top"><i>!option</i></p>
<p style="margin-left:32%;">The option will be provided to
every module with a NULL value.</p>
<p valign="top"><i>module:option=value</i>,
<i>module:option</i>, <i>module:!option</i></p>
<p style="margin-left:32%;">As above, but the corresponding
option and value will be provided only to modules whose name
matches <i>module</i>.</p>
<p style="margin-left:20%;">The return value will be
<b>ARCHIVE_OK</b> if any module accepts the option, or
<b>ARCHIVE_WARN</b> if no module accepted the option, or
<b>ARCHIVE_FATAL</b> if there was a fatal error while
attempting to process the option.</p>
<p style="margin-left:20%; margin-top: 1em">The currently
supported options are:</p>
<p valign="top">Format iso9660 <b><br>
joliet</b></p>
<p style="margin-left:45%; margin-top: 1em">Support Joliet
extensions. Defaults to enabled, use <b>!joliet</b> to
disable.</p>
<p valign="top"><b>archive_read_open</b>()</p>
<p style="margin-left:20%;">The same as
<b>archive_read_open2</b>(), except that the skip callback
is assumed to be NULL.</p>
<p valign="top"><b>archive_read_open2</b>()</p>
<p style="margin-left:20%;">Freeze the settings, open the
archive, and prepare for reading entries. This is the most
generic version of this call, which accepts four callback
functions. Most clients will want to use
<b>archive_read_open_filename</b>(),
<b>archive_read_open_FILE</b>(),
<b>archive_read_open_fd</b>(), or
<b>archive_read_open_memory</b>() instead. The library
invokes the client-provided functions to obtain raw bytes
from the archive.</p>
<p valign="top"><b>archive_read_open_FILE</b>()</p>
<p style="margin-left:20%;">Like
<b>archive_read_open</b>(), except that it accepts a <i>FILE
*</i> pointer. This function should not be used with tape
drives or other devices that require strict I/O
blocking.</p>
<p valign="top"><b>archive_read_open_fd</b>()</p>
<p style="margin-left:20%;">Like
<b>archive_read_open</b>(), except that it accepts a file
descriptor and block size rather than a set of function
pointers. Note that the file descriptor will not be
automatically closed at end-of-archive. This function is
safe for use with tape drives or other blocked devices.</p>
<p valign="top"><b>archive_read_open_file</b>()</p>
<p style="margin-left:20%;">This is a deprecated synonym
for <b>archive_read_open_filename</b>().</p>
<p valign="top"><b>archive_read_open_filename</b>()</p>
<p style="margin-left:20%;">Like
<b>archive_read_open</b>(), except that it accepts a simple
filename and a block size. A NULL filename represents
standard input. This function is safe for use with tape
drives or other blocked devices.</p>
<p valign="top"><b>archive_read_open_memory</b>()</p>
<p style="margin-left:20%;">Like
<b>archive_read_open</b>(), except that it accepts a pointer
and size of a block of memory containing the archive
data.</p>
<p valign="top"><b>archive_read_next_header</b>()</p>
<p style="margin-left:20%;">Read the header for the next
entry and return a pointer to a struct archive_entry. This
is a convenience wrapper around
<b>archive_read_next_header2</b>() that reuses an internal
struct archive_entry object for each request.</p>
<p valign="top"><b>archive_read_next_header2</b>()</p>
<p style="margin-left:20%;">Read the header for the next
entry and populate the provided struct archive_entry.</p>
<p valign="top"><b>archive_read_data</b>()</p>
<p style="margin-left:20%;">Read data associated with the
header just read. Internally, this is a convenience function
that calls <b>archive_read_data_block</b>() and fills any
gaps with nulls so that callers see a single continuous
stream of data.</p>
<p valign="top"><b>archive_read_data_block</b>()</p>
<p style="margin-left:20%;">Return the next available block
of data for this entry. Unlike <b>archive_read_data</b>(),
the <b>archive_read_data_block</b>() function avoids copying
data and allows you to correctly handle sparse files, as
supported by some archive formats. The library guarantees
that offsets will increase and that blocks will not overlap.
Note that the blocks returned from this function can be much
larger than the block size read from disk, due to
compression and internal buffer optimizations.</p>
<p valign="top"><b>archive_read_data_skip</b>()</p>
<p style="margin-left:20%;">A convenience function that
repeatedly calls <b>archive_read_data_block</b>() to skip
all of the data for this archive entry.</p>
<p valign="top"><b>archive_read_data_into_buffer</b>()</p>
<p style="margin-left:20%;">This function is deprecated and
will be removed. Use <b>archive_read_data</b>() instead.</p>
<p valign="top"><b>archive_read_data_into_fd</b>()</p>
<p style="margin-left:20%;">A convenience function that
repeatedly calls <b>archive_read_data_block</b>() to copy
the entire entry to the provided file descriptor.</p>
<p valign="top"><b>archive_read_extract</b>(),
<b>archive_read_extract_set_skip_file</b>()</p>
<p style="margin-left:20%;">A convenience function that
wraps the corresponding archive_write_disk(3) interfaces.
The first call to <b>archive_read_extract</b>() creates a
restore object using archive_write_disk_new(3) and
archive_write_disk_set_standard_lookup(3), then
transparently invokes archive_write_disk_set_options(3),
archive_write_header(3), archive_write_data(3), and
archive_write_finish_entry(3) to create the entry on disk
and copy data into it. The <i>flags</i> argument is passed
unmodified to archive_write_disk_set_options(3).</p>
<p valign="top"><b>archive_read_extract2</b>()</p>
<p style="margin-left:20%;">This is another version of
<b>archive_read_extract</b>() that allows you to provide
your own restore object. In particular, this allows you to
override the standard lookup functions using
archive_write_disk_set_group_lookup(3), and
archive_write_disk_set_user_lookup(3). Note that
<b>archive_read_extract2</b>() does not accept a
<i>flags</i> argument; you should use
<b>archive_write_disk_set_options</b>() to set the restore
options yourself.</p>
<p valign="top"><b>archive_read_extract_set_progress_callback</b>()</p>
<p style="margin-left:20%;">Sets a pointer to a
user-defined callback that can be used for updating progress
displays during extraction. The progress function will be
invoked during the extraction of large regular files. The
progress function will be invoked with the pointer provided
to this call. Generally, the data pointed to should include
a reference to the archive object and the archive_entry
object so that various statistics can be retrieved for the
progress display.</p>
<p valign="top"><b>archive_read_close</b>()</p>
<p style="margin-left:20%;">Complete the archive and invoke
the close callback.</p>
<p valign="top"><b>archive_read_finish</b>()</p>
<p style="margin-left:20%;">Invokes
<b>archive_read_close</b>() if it was not invoked manually,
then release all resources. Note: In libarchive 1.x, this
function was declared to return <i>void</i>, which made it
impossible to detect certain errors when
<b>archive_read_close</b>() was invoked implicitly from this
function. The declaration is corrected beginning with
libarchive 2.0.</p>
<p style="margin-left:8%; margin-top: 1em">Note that the
library determines most of the relevant information about
the archive by inspection. In particular, it automatically
detects gzip(1) or bzip2(1) compression and transparently
performs the appropriate decompression. It also
automatically detects the archive format.</p>
<p style="margin-left:8%; margin-top: 1em">A complete
description of the struct archive and struct archive_entry
objects can be found in the overview manual page for
libarchive(3).</p>
<p style="margin-top: 1em" valign="top"><b>CLIENT
CALLBACKS</b></p>
<p style="margin-left:8%;">The callback functions must
match the following prototypes:</p>
<p style="margin-left:17%; margin-top: 1em"><i>typedef
ssize_t</i></p>
<p valign="top"><b>archive_read_callback</b>(<i>struct archive *</i>,
<i>void *client_data</i>,
<i>const void **buffer</i>)</p>
<p style="margin-left:17%; margin-top: 1em"><i>typedef
int</i></p>
<p valign="top"><b>archive_skip_callback</b>(<i>struct archive *</i>,
<i>void *client_data</i>,
<i>size_t request</i>)</p>
<p style="margin-left:17%; margin-top: 1em"><i>typedef
int</i> <b>archive_open_callback</b>(<i>struct archive
*</i>, <i>void *client_data</i>)</p>
<p style="margin-left:17%; margin-top: 1em"><i>typedef
int</i> <b>archive_close_callback</b>(<i>struct archive
*</i>, <i>void *client_data</i>)</p>
<p style="margin-left:8%; margin-top: 1em">The open
callback is invoked by <b>archive_open</b>(). It should
return <b>ARCHIVE_OK</b> if the underlying file or data
source is successfully opened. If the open fails, it should
call <b>archive_set_error</b>() to register an error code
and message and return <b>ARCHIVE_FATAL</b>.</p>
<p style="margin-left:8%; margin-top: 1em">The read
callback is invoked whenever the library requires raw bytes
from the archive. The read callback should read data into a
buffer, set the const void **buffer argument to point to the
available data, and return a count of the number of bytes
available. The library will invoke the read callback again
only after it has consumed this data. The library imposes no
constraints on the size of the data blocks returned. On
end-of-file, the read callback should return zero. On error,
the read callback should invoke <b>archive_set_error</b>()
to register an error code and message and return -1.</p>
<p style="margin-left:8%; margin-top: 1em">The skip
callback is invoked when the library wants to ignore a block
of data. The return value is the number of bytes actually
skipped, which may differ from the request. If the callback
cannot skip data, it should return zero. If the skip
callback is not provided (the function pointer is NULL ),
the library will invoke the read function instead and simply
discard the result. A skip callback can provide significant
performance gains when reading uncompressed archives from
slow disk drives or other media that can skip quickly.</p>
<p style="margin-left:8%; margin-top: 1em">The close
callback is invoked by archive_close when the archive
processing is complete. The callback should return
<b>ARCHIVE_OK</b> on success. On failure, the callback
should invoke <b>archive_set_error</b>() to register an
error code and message and return <b>ARCHIVE_FATAL.</b></p>
<p style="margin-top: 1em" valign="top"><b>EXAMPLE</b></p>
<p style="margin-left:8%;">The following illustrates basic
usage of the library. In this example, the callback
functions are simply wrappers around the standard open(2),
read(2), and close(2) system calls.</p>
<p style="margin-left:17%; margin-top: 1em">void <br>
list_archive(const char *name) <br>
{ <br>
struct mydata *mydata; <br>
struct archive *a; <br>
struct archive_entry *entry;</p>
<p style="margin-left:17%; margin-top: 1em">mydata =
malloc(sizeof(struct mydata)); <br>
a = archive_read_new(); <br>
mydata->name = name; <br>
archive_read_support_compression_all(a); <br>
archive_read_support_format_all(a); <br>
archive_read_open(a, mydata, myopen, myread, myclose); <br>
while (archive_read_next_header(a, &entry) ==
ARCHIVE_OK) { <br>
printf("%s\n",archive_entry_pathname(entry)); <br>
archive_read_data_skip(a); <br>
} <br>
archive_read_finish(a); <br>
free(mydata); <br>
}</p>
<p style="margin-left:17%; margin-top: 1em">ssize_t <br>
myread(struct archive *a, void *client_data, const void
**buff) <br>
{ <br>
struct mydata *mydata = client_data;</p>
<p style="margin-left:17%; margin-top: 1em">*buff =
mydata->buff; <br>
return (read(mydata->fd, mydata->buff, 10240)); <br>
}</p>
<p style="margin-left:17%; margin-top: 1em">int <br>
myopen(struct archive *a, void *client_data) <br>
{ <br>
struct mydata *mydata = client_data;</p>
<p style="margin-left:17%; margin-top: 1em">mydata->fd =
open(mydata->name, O_RDONLY); <br>
return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
<br>
}</p>
<p style="margin-left:17%; margin-top: 1em">int <br>
myclose(struct archive *a, void *client_data) <br>
{ <br>
struct mydata *mydata = client_data;</p>
<p style="margin-left:17%; margin-top: 1em">if
(mydata->fd > 0) <br>
close(mydata->fd); <br>
return (ARCHIVE_OK); <br>
}</p>
<p style="margin-top: 1em" valign="top"><b>RETURN
VALUES</b></p>
<p style="margin-left:8%;">Most functions return zero on
success, non-zero on error. The possible return codes
include: <b>ARCHIVE_OK</b> (the operation succeeded),
<b>ARCHIVE_WARN</b> (the operation succeeded but a
non-critical error was encountered), <b>ARCHIVE_EOF</b>
(end-of-archive was encountered), <b>ARCHIVE_RETRY</b> (the
operation failed but can be retried), and
<b>ARCHIVE_FATAL</b> (there was a fatal error; the archive
should be closed immediately). Detailed error codes and
textual descriptions are available from the
<b>archive_errno</b>() and <b>archive_error_string</b>()
functions.</p>
<p style="margin-left:8%; margin-top: 1em"><b>archive_read_new</b>()
returns a pointer to a freshly allocated struct archive
object. It returns NULL on error.</p>
<p style="margin-left:8%; margin-top: 1em"><b>archive_read_data</b>()
returns a count of bytes actually read or zero at the end of
the entry. On error, a value of <b>ARCHIVE_FATAL</b>,
<b>ARCHIVE_WARN</b>, or <b>ARCHIVE_RETRY</b> is returned and
an error code and textual description can be retrieved from
the <b>archive_errno</b>() and <b>archive_error_string</b>()
functions.</p>
<p style="margin-left:8%; margin-top: 1em">The library
expects the client callbacks to behave similarly. If there
is an error, you can use <b>archive_set_error</b>() to set
an appropriate error code and description, then return one
of the non-zero values above. (Note that the value
eventually returned to the client may not be the same; many
errors that are not critical at the level of basic I/O can
prevent the archive from being properly read, thus most I/O
errors eventually cause <b>ARCHIVE_FATAL</b> to be
returned.)</p>
<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p>
<p style="margin-left:8%;">tar(1), archive(3),
archive_util(3), tar(5)</p>
<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p>
<p style="margin-left:8%;">The <b>libarchive</b> library
first appeared in FreeBSD 5.3.</p>
<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p>
<p style="margin-left:8%;">The <b>libarchive</b> library
was written by Tim Kientzle
⟨kientzle@acm.org⟩.</p>
<p style="margin-top: 1em" valign="top"><b>BUGS</b></p>
<p style="margin-left:8%;">Many traditional archiver
programs treat empty files as valid empty archives. For
example, many implementations of tar(1) allow you to append
entries to an empty file. Of course, it is impossible to
determine the format of an empty file by inspecting the
contents, so this library treats empty files as having a
special ‘‘empty’’ format.</p>
<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0
April 13, 2009 FreeBSD 8.0</p>
<hr>
</body>
</html>
|
