1archive_write(3) BSD Library Functions Manual archive_write(3)
2
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
21 #include <archive.h>
22 struct archive *
24 archive_write_new(void);
25 int
27 archive_write_get_bytes_per_block(struct archive *);
28 int
30 archive_write_set_bytes_per_block(struct archive *, int bytes_per_block);
31 int
33 archive_write_set_bytes_in_last_block(struct archive *, int);
34 int
36 archive_write_set_compression_bzip2(struct archive *);
37 int
39 archive_write_set_compression_compress(struct archive *);
40 int
42 archive_write_set_compression_gzip(struct archive *);
43 int
45 archive_write_set_compression_none(struct archive *);
46 int
48 archive_write_set_compression_program(struct archive *,
49 const char * cmd);
50 int
52 archive_write_set_format_cpio(struct archive *);
53 int
55 archive_write_set_format_pax(struct archive *);
56 int
58 archive_write_set_format_pax_restricted(struct archive *);
59 int
61 archive_write_set_format_shar(struct archive *);
62 int
64 archive_write_set_format_shar_binary(struct archive *);
65 int
67 archive_write_set_format_ustar(struct archive *);
68 int
70 archive_write_set_format_options(struct archive *, const char *);
71 int
73 archive_write_set_compressor_options(struct archive *, const char *);
74 int
76 archive_write_set_options(struct archive *, const char *);
77 int
79 archive_write_open(struct archive *, void *client_data,
80 archive_open_callback *, archive_write_callback *,
81 archive_close_callback *);
82 int
84 archive_write_open_fd(struct archive *, int fd);
85 int
87 archive_write_open_FILE(struct archive *, FILE *file);
88 int
90 archive_write_open_filename(struct archive *, const char *filename);
91 int
93 archive_write_open_memory(struct archive *, void *buffer,
94 size_t bufferSize, size_t *outUsed);
95 int
97 archive_write_header(struct archive *, struct archive_entry *);
98 ssize_t
100 archive_write_data(struct archive *, const void *, size_t);
101 int
103 archive_write_finish_entry(struct archive *);
104 int
106 archive_write_close(struct archive *);
107 int
109 archive_write_finish(struct archive *);
110
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 archive_write_new()
120 Allocates and initializes a struct archive object suitable for
121 writing a tar archive.
122 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 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 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 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 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 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 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 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 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 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 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 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 archive_write_open_file()
254 A deprecated synonym for archive_write_open_filename().
255 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 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 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 archive_write_data()
284 Write data corresponding to the header just written. Returns
285 number of bytes written or -1 on error.
286 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 archive_write_close()
294 Complete the archive and invoke the close callback.
295 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
307 Compression support is built-in to libarchive, which uses zlib and bzlib
308 to handle gzip and bzip2 compression, respectively.
309
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 typedef int archive_open_callback(struct archive *, void
316 *client_data)
317 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 typedef ssize_t archive_write_callback(struct archive *,
324 void *client_data, const void *buffer, size_t length)
325 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 typedef int archive_close_callback(struct archive *, void
335 *client_data)
336 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
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 #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 struct mydata {
358 const char *name;
359 int fd;
360 };
361 int
363 myopen(struct archive *a, void *client_data)
364 {
365 struct mydata *mydata = client_data;
366 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 ssize_t
375 mywrite(struct archive *a, void *client_data, const void *buff, size_t n)
376 {
377 struct mydata *mydata = client_data;
378 return (write(mydata->fd, buff, n));
380 }
381 int
383 myclose(struct archive *a, void *client_data)
384 {
385 struct mydata *mydata = client_data;
386 if (mydata->fd > 0)
388 close(mydata->fd);
389 return (0);
390 }
391 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 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 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
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 archive_write_new() returns a pointer to a newly-allocated struct archive
445 object.
446 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
459 tar(1), libarchive(3), tar(5)
460
462 The libarchive library first appeared in FreeBSD 5.3.
463
465 The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
466
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 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.
485BSD May 11, 2008 BSD