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
|
.TH archive_write 3 "August 19, 2006" ""
.SH NAME
\fBarchive_write_new\fP,
\fBarchive_write_set_format_cpio\fP,
\fBarchive_write_set_format_pax\fP,
\fBarchive_write_set_format_pax_restricted\fP,
\fBarchive_write_set_format_shar\fP,
\fBarchive_write_set_format_shar_binary\fP,
\fBarchive_write_set_format_ustar\fP,
\fBarchive_write_get_bytes_per_block\fP,
\fBarchive_write_set_bytes_per_block\fP,
\fBarchive_write_set_bytes_in_last_block\fP,
\fBarchive_write_set_compression_bzip2\fP,
\fBarchive_write_set_compression_gzip\fP,
\fBarchive_write_set_compression_none\fP,
\fBarchive_write_set_compression_program\fP,
\fBarchive_write_open\fP,
\fBarchive_write_open_fd\fP,
\fBarchive_write_open_FILE\fP,
\fBarchive_write_open_filename\fP,
\fBarchive_write_open_memory\fP,
\fBarchive_write_header\fP,
\fBarchive_write_data\fP,
\fBarchive_write_finish_entry\fP,
\fBarchive_write_close\fP,
\fBarchive_write_finish\fP
\- functions for creating archives
.SH SYNOPSIS
\fB#include <archive.h>\fP
.br
\fIstruct archive *\fP
.RE
.nh
\fBarchive_write_new\fP
.hy
("void");
\fIint\fP
.RE
.nh
\fBarchive_write_get_bytes_per_block\fP
.hy
("struct archive *");
\fIint\fP
.RE
.nh
\fBarchive_write_set_bytes_per_block\fP
.hy
("struct archive *" "int bytes_per_block");
\fIint\fP
.RE
.nh
\fBarchive_write_set_bytes_in_last_block\fP
.hy
("struct archive *" "int");
\fIint\fP
.RE
.nh
\fBarchive_write_set_compression_bzip2\fP
.hy
("struct archive *");
\fIint\fP
.RE
.nh
\fBarchive_write_set_compression_gzip\fP
.hy
("struct archive *");
\fIint\fP
.RE
.nh
\fBarchive_write_set_compression_none\fP
.hy
("struct archive *");
\fIint\fP
.RE
Fo archive_write_set_compression_program
Fa "struct archive *"
Fa "const char * cmd"
Fc
\fIint\fP
.RE
.nh
\fBarchive_write_set_format_cpio\fP
.hy
("struct archive *");
\fIint\fP
.RE
.nh
\fBarchive_write_set_format_pax\fP
.hy
("struct archive *");
\fIint\fP
.RE
.nh
\fBarchive_write_set_format_pax_restricted\fP
.hy
("struct archive *");
\fIint\fP
.RE
.nh
\fBarchive_write_set_format_shar\fP
.hy
("struct archive *");
\fIint\fP
.RE
.nh
\fBarchive_write_set_format_shar_binary\fP
.hy
("struct archive *");
\fIint\fP
.RE
.nh
\fBarchive_write_set_format_ustar\fP
.hy
("struct archive *");
\fIint\fP
.RE
Fo archive_write_open
Fa "struct archive *"
Fa "void *client_data"
Fa "archive_open_callback *"
Fa "archive_write_callback *"
Fa "archive_close_callback *"
Fc
\fIint\fP
.RE
.nh
\fBarchive_write_open_fd\fP
.hy
("struct archive *" "int fd");
\fIint\fP
.RE
.nh
\fBarchive_write_open_FILE\fP
.hy
("struct archive *" "FILE *file");
\fIint\fP
.RE
.nh
\fBarchive_write_open_filename\fP
.hy
("struct archive *" "const char *filename");
\fIint\fP
.RE
Fo archive_write_open_memory
Fa "struct archive *"
Fa "void *buffer"
Fa "size_t bufferSize"
Fa "size_t *outUsed"
Fc
\fIint\fP
.RE
.nh
\fBarchive_write_header\fP
.hy
("struct archive *" "struct archive_entry *");
\fIssize_t\fP
.RE
.nh
\fBarchive_write_data\fP
.hy
("struct archive *" "const void *" "size_t");
\fIint\fP
.RE
.nh
\fBarchive_write_finish_entry\fP
.hy
("struct archive *");
\fIint\fP
.RE
.nh
\fBarchive_write_close\fP
.hy
("struct archive *");
\fIint\fP
.RE
.nh
\fBarchive_write_finish\fP
.hy
("struct archive *");
.SH DESCRIPTION
These functions provide a complete API for creating streaming
archive files.
The general process is to first create the
Tn struct archive
object, set any desired options, initialize the archive, append entries, then
close the archive and release all resources.
The following summary describes the functions in approximately
the order they are ordinarily used:
.TP
.nh
\fBarchive_write_new\fP
.hy
();
Allocates and initializes a
Tn struct archive
object suitable for writing a tar archive.
.TP
.nh
\fBarchive_write_set_bytes_per_block\fP
.hy
();
Sets the block size used for writing the archive data.
Every call to the write callback function, except possibly the last one, will
use this value for the length.
The third parameter is a boolean that specifies whether or not the final block
written will be padded to the full block size.
If it is zero, the last block will not be padded.
If it is non-zero, padding will be added both before and after compression.
The default is to use a block size of 10240 bytes and to pad the last block.
Note that a block size of zero will suppress internal blocking
and cause writes to be sent directly to the write callback as they occur.
.TP
.nh
\fBarchive_write_get_bytes_per_block\fP
.hy
();
Retrieve the block size to be used for writing.
A value of -1 here indicates that the library should use default values.
A value of zero indicates that internal blocking is suppressed.
.TP
.nh
\fBarchive_write_set_bytes_in_last_block\fP
.hy
();
Sets the block size used for writing the last block.
If this value is zero, the last block will be padded to the same size
as the other blocks.
Otherwise, the final block will be padded to a multiple of this size.
In particular, setting it to 1 will cause the final block to not be padded.
For compressed output, any padding generated by this option
is applied only after the compression.
The uncompressed data is always unpadded.
The default is to pad the last block to the full block size (note that
.nh
\fBarchive_write_open_filename\fP
.hy
();
will set this based on the file type).
Unlike the other
``set''
functions, this function can be called after the archive is opened.
.TP
.nh
\fBarchive_write_get_bytes_in_last_block\fP
.hy
();
Retrieve the currently-set value for last block size.
A value of -1 here indicates that the library should use default values.
.TP
Xo
.nh
\fBarchive_write_set_format_cpio\fP
.hy
(,);
.nh
\fBarchive_write_set_format_pax\fP
.hy
(,);
.nh
\fBarchive_write_set_format_pax_restricted\fP
.hy
(,);
.nh
\fBarchive_write_set_format_shar\fP
.hy
(,);
.nh
\fBarchive_write_set_format_shar_binary\fP
.hy
(,);
.nh
\fBarchive_write_set_format_ustar\fP
.hy
();
Xc
Sets the format that will be used for the archive.
The library can write
POSIX octet-oriented cpio format archives,
POSIX-standard
``pax interchange''
format archives,
traditional
``shar''
archives,
enhanced
``binary''
shar archives that store a variety of file attributes and handle binary files,
and
POSIX-standard
``ustar''
archives.
The pax interchange format is a backwards-compatible tar format that
adds key/value attributes to each entry and supports arbitrary
filenames, linknames, uids, sizes, etc.
``Restricted pax interchange format''
is the library default; this is the same as pax format, but suppresses
the pax extended header for most normal files.
In most cases, this will result in ordinary ustar archives.
.TP
Xo
.nh
\fBarchive_write_set_compression_bzip2\fP
.hy
(,);
.nh
\fBarchive_write_set_compression_gzip\fP
.hy
(,);
.nh
\fBarchive_write_set_compression_none\fP
.hy
();
Xc
The resulting archive will be compressed as specified.
Note that the compressed output is always properly blocked.
.TP
.nh
\fBarchive_write_set_compression_program\fP
.hy
();
The archive will be fed into the specified compression program.
The output of that program is blocked and written to the client
write callbacks.
.TP
.nh
\fBarchive_write_open\fP
.hy
();
Freeze the settings, open the archive, and prepare for writing entries.
This is the most generic form of this function, which accepts
pointers to three callback functions which will be invoked by
the compression layer to write the constructed archive.
.TP
.nh
\fBarchive_write_open_fd\fP
.hy
();
A convenience form of
.nh
\fBarchive_write_open\fP
.hy
();
that accepts a file descriptor.
The
.nh
\fBarchive_write_open_fd\fP
.hy
();
function is safe for use with tape drives or other
block-oriented devices.
.TP
.nh
\fBarchive_write_open_FILE\fP
.hy
();
A convenience form of
.nh
\fBarchive_write_open\fP
.hy
();
that accepts a
\fI"FILE *"\fP
.RE
pointer.
Note that
.nh
\fBarchive_write_open_FILE\fP
.hy
();
is not safe for writing to tape drives or other devices
that require correct blocking.
.TP
.nh
\fBarchive_write_open_file\fP
.hy
();
A deprecated synonym for
.nh
\fBarchive_write_open_filename\fP
.hy
(.);
.TP
.nh
\fBarchive_write_open_filename\fP
.hy
();
A convenience form of
.nh
\fBarchive_write_open\fP
.hy
();
that accepts a filename.
A NULL argument indicates that the output should be written to standard output;
an argument of
``-''
will open a file with that name.
If you have not invoked
.nh
\fBarchive_write_set_bytes_in_last_block\fP
.hy
(,);
then
.nh
\fBarchive_write_open_filename\fP
.hy
();
will adjust the last-block padding depending on the file:
it will enable padding when writing to standard output or
to a character or block device node, it will disable padding otherwise.
You can override this by manually invoking
.nh
\fBarchive_write_set_bytes_in_last_block\fP
.hy
();
before calling
.nh
\fBarchive_write_open\fP
.hy
(.);
The
.nh
\fBarchive_write_open_filename\fP
.hy
();
function is safe for use with tape drives or other
block-oriented devices.
.TP
.nh
\fBarchive_write_open_memory\fP
.hy
();
A convenience form of
.nh
\fBarchive_write_open\fP
.hy
();
that accepts a pointer to a block of memory that will receive
the archive.
The final
\fI"size_t *"\fP
.RE
argument points to a variable that will be updated
after each write to reflect how much of the buffer
is currently in use.
You should be careful to ensure that this variable
remains allocated until after the archive is
closed.
.TP
.nh
\fBarchive_write_header\fP
.hy
();
Build and write a header using the data in the provided
Tn struct archive_entry
structure.
See
\fBarchive_entry\fP(3)
for information on creating and populating
Tn struct archive_entry
objects.
.TP
.nh
\fBarchive_write_data\fP
.hy
();
Write data corresponding to the header just written.
Returns number of bytes written or -1 on error.
.TP
.nh
\fBarchive_write_finish_entry\fP
.hy
();
Close out the entry just written.
In particular, this writes out the final padding required by some formats.
Ordinarily, clients never need to call this, as it
is called automatically by
.nh
\fBarchive_write_next_header\fP
.hy
();
and
.nh
\fBarchive_write_close\fP
.hy
();
as needed.
.TP
.nh
\fBarchive_write_close\fP
.hy
();
Complete the archive and invoke the close callback.
.TP
.nh
\fBarchive_write_finish\fP
.hy
();
Invokes
.nh
\fBarchive_write_close\fP
.hy
();
if it was not invoked manually, then releases all resources.
Note that this function was declared to return
\fIvoid\fP
.RE
in libarchive 1.x, which made it impossible to detect errors when
.nh
\fBarchive_write_close\fP
.hy
();
was invoked implicitly from this function.
This is corrected beginning with libarchive 2.0.
More information about the
\fIstruct\fP archive
object and the overall design of the library can be found in the
\fBlibarchive\fP(3)
overview.
.SH IMPLEMENTATION
Compression support is built-in to libarchive, which uses zlib and bzlib
to handle gzip and bzip2 compression, respectively.
.SH CLIENT CALLBACKS
To use this library, you will need to define and register
callback functions that will be invoked to write data to the
resulting archive.
These functions are registered by calling
.nh
\fBarchive_write_open\fP
.hy
(:);
.IP
\fItypedef int\fP
.RE
.nh
\fBarchive_open_callback\fP
.hy
("struct archive *" "void *client_data");
The open callback is invoked by
.nh
\fBarchive_write_open\fP
.hy
(.);
It should return
\fBARCHIVE_OK\fP
if the underlying file or data source is successfully
opened.
If the open fails, it should call
.nh
\fBarchive_set_error\fP
.hy
();
to register an error code and message and return
\fBARCHIVE_FATAL\fP.
.IP
\fItypedef ssize_t\fP
.RE
Fo archive_write_callback
Fa "struct archive *"
Fa "void *client_data"
Fa "void *buffer"
Fa "size_t length"
Fc
The write callback is invoked whenever the library
needs to write raw bytes to the archive.
For correct blocking, each call to the write callback function
should translate into a single
\fBwrite\fP(2)
system call.
This is especially critical when writing archives to tape drives.
On success, the write callback should return the
number of bytes actually written.
On error, the callback should invoke
.nh
\fBarchive_set_error\fP
.hy
();
to register an error code and message and return -1.
.IP
\fItypedef int\fP
.RE
.nh
\fBarchive_close_callback\fP
.hy
("struct archive *" "void *client_data");
The close callback is invoked by archive_close when
the archive processing is complete.
The callback should return
\fBARCHIVE_OK\fP
on success.
On failure, the callback should invoke
.nh
\fBarchive_set_error\fP
.hy
();
to register an error code and message and
return
\fBARCHIVE_FATAL.\fP
.SH EXAMPLE
The following sketch illustrates basic usage of the library.
In this example,
the callback functions are simply wrappers around the standard
\fBopen\fP(2),
\fBwrite\fP(2),
and
\fBclose\fP(2)
system calls.
.RS
#include <sys/stat.h>
#include <archive.h>
#include <archive_entry.h>
#include <fcntl.h>
#include <stdlib.h>
#include <unistd.h>
struct mydata {
const char *name;
int fd;
};
int
myopen(struct archive *a, void *client_data)
{
struct mydata *mydata = client_data;
mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
if (mydata->fd >= 0)
return (ARCHIVE_OK);
else
return (ARCHIVE_FATAL);
}
ssize_t
mywrite(struct archive *a, void *client_data, void *buff, size_t n)
{
struct mydata *mydata = client_data;
return (write(mydata->fd, buff, n));
}
int
myclose(struct archive *a, void *client_data)
{
struct mydata *mydata = client_data;
if (mydata->fd > 0)
close(mydata->fd);
return (0);
}
void
write_archive(const char *outname, const char **filename)
{
struct mydata *mydata = malloc(sizeof(struct mydata));
struct archive *a;
struct archive_entry *entry;
struct stat st;
char buff[8192];
int len;
int fd;
a = archive_write_new();
mydata->name = outname;
archive_write_set_compression_gzip(a);
archive_write_set_format_ustar(a);
archive_write_open(a, mydata, myopen, mywrite, myclose);
while (*filename) {
stat(*filename, &st);
entry = archive_entry_new();
archive_entry_copy_stat(entry, &st);
archive_entry_set_pathname(entry, *filename);
archive_write_header(a, entry);
fd = open(*filename, O_RDONLY);
len = read(fd, buff, sizeof(buff));
while ( len > 0 ) {
archive_write_data(a, buff, len);
len = read(fd, buff, sizeof(buff));
}
archive_entry_free(entry);
filename++;
}
archive_write_finish(a);
}
int main(int argc, const char **argv)
{
const char *outname;
argv++;
outname = argv++;
write_archive(outname, argv);
return 0;
}
.RE
.SH RETURN VALUES
Most functions return
\fBARCHIVE_OK\fP
(zero) on success, or one of several non-zero
error codes for errors.
Specific error codes include:
\fBARCHIVE_RETRY\fP
for operations that might succeed if retried,
\fBARCHIVE_WARN\fP
for unusual conditions that do not prevent further operations, and
\fBARCHIVE_FATAL\fP
for serious errors that make remaining operations impossible.
The
.nh
\fBarchive_errno\fP
.hy
();
and
.nh
\fBarchive_error_string\fP
.hy
();
functions can be used to retrieve an appropriate error code and a
textual error message.
.nh
\fBarchive_write_new\fP
.hy
();
returns a pointer to a newly-allocated
Tn struct archive
object.
.nh
\fBarchive_write_data\fP
.hy
();
returns a count of the number of bytes actually written.
On error, -1 is returned and the
.nh
\fBarchive_errno\fP
.hy
();
and
.nh
\fBarchive_error_string\fP
.hy
();
functions will return appropriate values.
Note that if the client-provided write callback function
returns a non-zero value, that error will be propagated back to the caller
through whatever API function resulted in that call, which
may include
.nh
\fBarchive_write_header\fP
.hy
(,);
.nh
\fBarchive_write_data\fP
.hy
(,);
.nh
\fBarchive_write_close\fP
.hy
(,);
or
.nh
\fBarchive_write_finish\fP
.hy
(.);
The client callback can call
.nh
\fBarchive_set_error\fP
.hy
();
to provide values that can then be retrieved by
.nh
\fBarchive_errno\fP
.hy
();
and
.nh
\fBarchive_error_string\fP
.hy
(.);
.SH SEE ALSO
\fBtar\fP(1),
\fBlibarchive\fP(3),
\fBtar\fP(5)
.SH HISTORY
The
\fBlibarchive\fP
library first appeared in
FreeBSD 5.3.
.SH AUTHORS
-nosplit
The
\fBlibarchive\fP
library was written by
Tim Kientzle <kientzle@acm.org.>
.SH BUGS
There are many peculiar bugs in historic tar implementations that may cause
certain programs to reject archives written by this library.
For example, several historic implementations calculated header checksums
incorrectly and will thus reject valid archives; GNU tar does not fully support
pax interchange format; some old tar implementations required specific
field terminations.
The default pax interchange format eliminates most of the historic
tar limitations and provides a generic key/value attribute facility
for vendor-defined extensions.
One oversight in POSIX is the failure to provide a standard attribute
for large device numbers.
This library uses
``SCHILY.devminor''
and
``SCHILY.devmajor''
for device numbers that exceed the range supported by the backwards-compatible
ustar header.
These keys are compatible with Joerg Schilling's
\fBstar\fP
archiver.
Other implementations may not recognize these keys and will thus be unable
to correctly restore device nodes with large device numbers from archives
created by this library.
|