1archive_write(3)         BSD Library Functions Manual         archive_write(3)
2

NAME

4     archive_write_new, archive_write_set_format_cpio,
5     archive_write_set_format_pax, archive_write_set_format_pax_restricted,
6     archive_write_set_format_shar, archive_write_set_format_shar_binary,
7     archive_write_set_format_ustar, archive_write_get_bytes_per_block,
8     archive_write_set_bytes_per_block, archive_write_set_bytes_in_last_block,
9     archive_write_set_compression_bzip2,
10     archive_write_set_compression_compress,
11     archive_write_set_compression_gzip, archive_write_set_compression_none,
12     archive_write_set_compression_program,
13     archive_write_set_compressor_options, archive_write_set_format_options,
14     archive_write_set_options, archive_write_open, archive_write_open_fd,
15     archive_write_open_FILE, archive_write_open_filename,
16     archive_write_open_memory, archive_write_header, archive_write_data,
17     archive_write_finish_entry, archive_write_close, archive_write_finish 
18     functions for creating archives
19

SYNOPSIS

21     #include <archive.h>
22
23     struct archive *
24     archive_write_new(void);
25
26     int
27     archive_write_get_bytes_per_block(struct archive *);
28
29     int
30     archive_write_set_bytes_per_block(struct archive *, int bytes_per_block);
31
32     int
33     archive_write_set_bytes_in_last_block(struct archive *, int);
34
35     int
36     archive_write_set_compression_bzip2(struct archive *);
37
38     int
39     archive_write_set_compression_compress(struct archive *);
40
41     int
42     archive_write_set_compression_gzip(struct archive *);
43
44     int
45     archive_write_set_compression_none(struct archive *);
46
47     int
48     archive_write_set_compression_program(struct archive *,
49         const char * cmd);
50
51     int
52     archive_write_set_format_cpio(struct archive *);
53
54     int
55     archive_write_set_format_pax(struct archive *);
56
57     int
58     archive_write_set_format_pax_restricted(struct archive *);
59
60     int
61     archive_write_set_format_shar(struct archive *);
62
63     int
64     archive_write_set_format_shar_binary(struct archive *);
65
66     int
67     archive_write_set_format_ustar(struct archive *);
68
69     int
70     archive_write_set_format_options(struct archive *, const char *);
71
72     int
73     archive_write_set_compressor_options(struct archive *, const char *);
74
75     int
76     archive_write_set_options(struct archive *, const char *);
77
78     int
79     archive_write_open(struct archive *, void *client_data,
80         archive_open_callback *, archive_write_callback *,
81         archive_close_callback *);
82
83     int
84     archive_write_open_fd(struct archive *, int fd);
85
86     int
87     archive_write_open_FILE(struct archive *, FILE *file);
88
89     int
90     archive_write_open_filename(struct archive *, const char *filename);
91
92     int
93     archive_write_open_memory(struct archive *, void *buffer,
94         size_t bufferSize, size_t *outUsed);
95
96     int
97     archive_write_header(struct archive *, struct archive_entry *);
98
99     ssize_t
100     archive_write_data(struct archive *, const void *, size_t);
101
102     int
103     archive_write_finish_entry(struct archive *);
104
105     int
106     archive_write_close(struct archive *);
107
108     int
109     archive_write_finish(struct archive *);
110

DESCRIPTION

112     These functions provide a complete API for creating streaming archive
113     files.  The general process is to first create the struct archive object,
114     set any desired options, initialize the archive, append entries, then
115     close the archive and release all resources.  The following summary
116     describes the functions in approximately the order they are ordinarily
117     used:
118
119     archive_write_new()
120             Allocates and initializes a struct archive object suitable for
121             writing a tar archive.
122
123     archive_write_set_bytes_per_block()
124             Sets the block size used for writing the archive data.  Every
125             call to the write callback function, except possibly the last
126             one, will use this value for the length.  The third parameter is
127             a boolean that specifies whether or not the final block written
128             will be padded to the full block size.  If it is zero, the last
129             block will not be padded.  If it is non-zero, padding will be
130             added both before and after compression.  The default is to use a
131             block size of 10240 bytes and to pad the last block.  Note that a
132             block size of zero will suppress internal blocking and cause
133             writes to be sent directly to the write callback as they occur.
134
135     archive_write_get_bytes_per_block()
136             Retrieve the block size to be used for writing.  A value of -1
137             here indicates that the library should use default values.  A
138             value of zero indicates that internal blocking is suppressed.
139
140     archive_write_set_bytes_in_last_block()
141             Sets the block size used for writing the last block.  If this
142             value is zero, the last block will be padded to the same size as
143             the other blocks.  Otherwise, the final block will be padded to a
144             multiple of this size.  In particular, setting it to 1 will cause
145             the final block to not be padded.  For compressed output, any
146             padding generated by this option is applied only after the com‐
147             pression.  The uncompressed data is always unpadded.  The default
148             is to pad the last block to the full block size (note that
149             archive_write_open_filename() will set this based on the file
150             type).  Unlike the other “set” functions, this function can be
151             called after the archive is opened.
152
153     archive_write_get_bytes_in_last_block()
154             Retrieve the currently-set value for last block size.  A value of
155             -1 here indicates that the library should use default values.
156
157     archive_write_set_format_cpio(), archive_write_set_format_pax(),
158             archive_write_set_format_pax_restricted(),
159             archive_write_set_format_shar(),
160             archive_write_set_format_shar_binary(),
161             archive_write_set_format_ustar()
162             Sets the format that will be used for the archive.  The library
163             can write POSIX octet-oriented cpio format archives, POSIX-stan‐
164             dard “pax interchange” format archives, traditional “shar” ar‐
165             chives, enhanced “binary” shar archives that store a variety of
166             file attributes and handle binary files, and POSIX-standard
167             “ustar” archives.  The pax interchange format is a backwards-com‐
168             patible tar format that adds key/value attributes to each entry
169             and supports arbitrary filenames, linknames, uids, sizes, etc.
170             “Restricted pax interchange format” is the library default; this
171             is the same as pax format, but suppresses the pax extended header
172             for most normal files.  In most cases, this will result in ordi‐
173             nary ustar archives.
174
175     archive_write_set_compression_bzip2(),
176             archive_write_set_compression_compress(),
177             archive_write_set_compression_gzip(),
178             archive_write_set_compression_none()
179             The resulting archive will be compressed as specified.  Note that
180             the compressed output is always properly blocked.
181
182     archive_write_set_compression_program()
183             The archive will be fed into the specified compression program.
184             The output of that program is blocked and written to the client
185             write callbacks.
186
187     archive_write_set_compressor_options(),
188             archive_write_set_format_options(), archive_write_set_options()
189             Specifies options that will be passed to the currently-enabled
190             compressor and/or format writer.  The argument is a comma-sepa‐
191             rated list of individual options.  Individual options have one of
192             the following forms:
193             option=value
194                     The option/value pair will be provided to every module.
195                     Modules that do not accept an option with this name will
196                     ignore it.
197             option  The option will be provided to every module with a value
198                     of “1”.
199             !option
200                     The option will be provided to every module with a NULL
201                     value.
202             module:option=value, module:option, module:!option
203                     As above, but the corresponding option and value will be
204                     provided only to modules whose name matches module.
205             The return value will be ARCHIVE_OK if any module accepts the
206             option, or ARCHIVE_WARN if no module accepted the option, or
207             ARCHIVE_FATAL if there was a fatal error while attempting to
208             process the option.
209
210             The currently supported options are:
211             Compressor gzip
212                     compression-level
213                             The value is interpreted as a decimal integer
214                             specifying the gzip compression level.
215             Compressor xz
216                     compression-level
217                             The value is interpreted as a decimal integer
218                             specifying the compression level.
219             Format mtree
220                     cksum, device, flags, gid, gname, indent, link, md5,
221                             mode, nlink, rmd160, sha1, sha256, sha384,
222                             sha512, size, time, uid, uname
223                             Enable a particular keyword in the mtree output.
224                             Prefix with an exclamation mark to disable the
225                             corresponding keyword.  The default is equivalent
226                             to “device, flags, gid, gname, link, mode, nlink,
227                             size, time, type, uid, uname”.
228                     all     Enables all of the above keywords.
229                     use-set
230                             Enables generation of /set lines that specify
231                             default values for the following files and/or
232                             directories.
233                     indent  XXX needs explanation XXX
234
235     archive_write_open()
236             Freeze the settings, open the archive, and prepare for writing
237             entries.  This is the most generic form of this function, which
238             accepts pointers to three callback functions which will be
239             invoked by the compression layer to write the constructed ar‐
240             chive.
241
242     archive_write_open_fd()
243             A convenience form of archive_write_open() that accepts a file
244             descriptor.  The archive_write_open_fd() function is safe for use
245             with tape drives or other block-oriented devices.
246
247     archive_write_open_FILE()
248             A convenience form of archive_write_open() that accepts a FILE *
249             pointer.  Note that archive_write_open_FILE() is not safe for
250             writing to tape drives or other devices that require correct
251             blocking.
252
253     archive_write_open_file()
254             A deprecated synonym for archive_write_open_filename().
255
256     archive_write_open_filename()
257             A convenience form of archive_write_open() that accepts a file‐
258             name.  A NULL argument indicates that the output should be writ‐
259             ten to standard output; an argument of “-” will open a file with
260             that name.  If you have not invoked
261             archive_write_set_bytes_in_last_block(), then
262             archive_write_open_filename() will adjust the last-block padding
263             depending on the file: it will enable padding when writing to
264             standard output or to a character or block device node, it will
265             disable padding otherwise.  You can override this by manually
266             invoking archive_write_set_bytes_in_last_block() before calling
267             archive_write_open().  The archive_write_open_filename() function
268             is safe for use with tape drives or other block-oriented devices.
269
270     archive_write_open_memory()
271             A convenience form of archive_write_open() that accepts a pointer
272             to a block of memory that will receive the archive.  The final
273             size_t * argument points to a variable that will be updated after
274             each write to reflect how much of the buffer is currently in use.
275             You should be careful to ensure that this variable remains allo‐
276             cated until after the archive is closed.
277
278     archive_write_header()
279             Build and write a header using the data in the provided struct
280             archive_entry structure.  See archive_entry(3) for information on
281             creating and populating struct archive_entry objects.
282
283     archive_write_data()
284             Write data corresponding to the header just written.  Returns
285             number of bytes written or -1 on error.
286
287     archive_write_finish_entry()
288             Close out the entry just written.  In particular, this writes out
289             the final padding required by some formats.  Ordinarily, clients
290             never need to call this, as it is called automatically by
291             archive_write_next_header() and archive_write_close() as needed.
292
293     archive_write_close()
294             Complete the archive and invoke the close callback.
295
296     archive_write_finish()
297             Invokes archive_write_close() if it was not invoked manually,
298             then releases all resources.  Note that this function was
299             declared to return void in libarchive 1.x, which made it impossi‐
300             ble to detect errors when archive_write_close() was invoked
301             implicitly from this function.  This is corrected beginning with
302             libarchive 2.0.
303     More information about the struct archive object and the overall design
304     of the library can be found in the libarchive(3) overview.
305

IMPLEMENTATION

307     Compression support is built-in to libarchive, which uses zlib and bzlib
308     to handle gzip and bzip2 compression, respectively.
309

CLIENT CALLBACKS

311     To use this library, you will need to define and register callback func‐
312     tions that will be invoked to write data to the resulting archive.  These
313     functions are registered by calling archive_write_open():
314
315           typedef int archive_open_callback(struct archive *, void
316           *client_data)
317
318     The open callback is invoked by archive_write_open().  It should return
319     ARCHIVE_OK if the underlying file or data source is successfully opened.
320     If the open fails, it should call archive_set_error() to register an
321     error code and message and return ARCHIVE_FATAL.
322
323           typedef ssize_t archive_write_callback(struct archive *,
324           void *client_data, const void *buffer, size_t length)
325
326     The write callback is invoked whenever the library needs to write raw
327     bytes to the archive.  For correct blocking, each call to the write call‐
328     back function should translate into a single write(2) system call.  This
329     is especially critical when writing archives to tape drives.  On success,
330     the write callback should return the number of bytes actually written.
331     On error, the callback should invoke archive_set_error() to register an
332     error code and message and return -1.
333
334           typedef int archive_close_callback(struct archive *, void
335           *client_data)
336
337     The close callback is invoked by archive_close when the archive process‐
338     ing is complete.  The callback should return ARCHIVE_OK on success.  On
339     failure, the callback should invoke archive_set_error() to register an
340     error code and message and return ARCHIVE_FATAL.
341

EXAMPLE

343     The following sketch illustrates basic usage of the library.  In this
344     example, the callback functions are simply wrappers around the standard
345     open(2), write(2), and close(2) system calls.
346
347           #ifdef __linux__
348           #define _FILE_OFFSET_BITS 64
349           #endif
350           #include <sys/stat.h>
351           #include <archive.h>
352           #include <archive_entry.h>
353           #include <fcntl.h>
354           #include <stdlib.h>
355           #include <unistd.h>
356
357           struct mydata {
358                   const char *name;
359                   int fd;
360           };
361
362           int
363           myopen(struct archive *a, void *client_data)
364           {
365             struct mydata *mydata = client_data;
366
367             mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
368             if (mydata->fd >= 0)
369               return (ARCHIVE_OK);
370             else
371               return (ARCHIVE_FATAL);
372           }
373
374           ssize_t
375           mywrite(struct archive *a, void *client_data, const void *buff, size_t n)
376           {
377             struct mydata *mydata = client_data;
378
379             return (write(mydata->fd, buff, n));
380           }
381
382           int
383           myclose(struct archive *a, void *client_data)
384           {
385             struct mydata *mydata = client_data;
386
387             if (mydata->fd > 0)
388               close(mydata->fd);
389             return (0);
390           }
391
392           void
393           write_archive(const char *outname, const char **filename)
394           {
395             struct mydata *mydata = malloc(sizeof(struct mydata));
396             struct archive *a;
397             struct archive_entry *entry;
398             struct stat st;
399             char buff[8192];
400             int len;
401             int fd;
402
403             a = archive_write_new();
404             mydata->name = outname;
405             archive_write_set_compression_gzip(a);
406             archive_write_set_format_ustar(a);
407             archive_write_open(a, mydata, myopen, mywrite, myclose);
408             while (*filename) {
409               stat(*filename, &st);
410               entry = archive_entry_new();
411               archive_entry_copy_stat(entry, &st);
412               archive_entry_set_pathname(entry, *filename);
413               archive_write_header(a, entry);
414               fd = open(*filename, O_RDONLY);
415               len = read(fd, buff, sizeof(buff));
416               while ( len > 0 ) {
417                   archive_write_data(a, buff, len);
418                   len = read(fd, buff, sizeof(buff));
419               }
420               archive_entry_free(entry);
421               filename++;
422             }
423             archive_write_finish(a);
424           }
425
426           int main(int argc, const char **argv)
427           {
428                   const char *outname;
429                   argv++;
430                   outname = argv++;
431                   write_archive(outname, argv);
432                   return 0;
433           }
434

RETURN VALUES

436     Most functions return ARCHIVE_OK (zero) on success, or one of several
437     non-zero error codes for errors.  Specific error codes include:
438     ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN
439     for unusual conditions that do not prevent further operations, and
440     ARCHIVE_FATAL for serious errors that make remaining operations impossi‐
441     ble.  The archive_errno() and archive_error_string() functions can be
442     used to retrieve an appropriate error code and a textual error message.
443
444     archive_write_new() returns a pointer to a newly-allocated struct archive
445     object.
446
447     archive_write_data() returns a count of the number of bytes actually
448     written.  On error, -1 is returned and the archive_errno() and
449     archive_error_string() functions will return appropriate values.  Note
450     that if the client-provided write callback function returns a non-zero
451     value, that error will be propagated back to the caller through whatever
452     API function resulted in that call, which may include
453     archive_write_header(), archive_write_data(), archive_write_close(), or
454     archive_write_finish().  The client callback can call archive_set_error()
455     to provide values that can then be retrieved by archive_errno() and
456     archive_error_string().
457

SEE ALSO

459     tar(1), libarchive(3), tar(5)
460

HISTORY

462     The libarchive library first appeared in FreeBSD 5.3.
463

AUTHORS

465     The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
466

BUGS

468     There are many peculiar bugs in historic tar implementations that may
469     cause certain programs to reject archives written by this library.  For
470     example, several historic implementations calculated header checksums
471     incorrectly and will thus reject valid archives; GNU tar does not fully
472     support pax interchange format; some old tar implementations required
473     specific field terminations.
474
475     The default pax interchange format eliminates most of the historic tar
476     limitations and provides a generic key/value attribute facility for ven‐
477     dor-defined extensions.  One oversight in POSIX is the failure to provide
478     a standard attribute for large device numbers.  This library uses
479     “SCHILY.devminor” and “SCHILY.devmajor” for device numbers that exceed
480     the range supported by the backwards-compatible ustar header.  These keys
481     are compatible with Joerg Schilling's star archiver.  Other implementa‐
482     tions may not recognize these keys and will thus be unable to correctly
483     restore device nodes with large device numbers from archives created by
484     this library.
485
486BSD                              May 11, 2008                              BSD
Impressum