1 .\" Copyright (c) 2003-2007 Tim Kientzle
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" $FreeBSD: head/lib/libarchive/archive_write.3 201110 2009-12-28 03:31:29Z kientzle $
31 .Nm archive_write_new ,
32 .Nm archive_write_set_format_cpio ,
33 .Nm archive_write_set_format_pax ,
34 .Nm archive_write_set_format_pax_restricted ,
35 .Nm archive_write_set_format_shar ,
36 .Nm archive_write_set_format_shar_binary ,
37 .Nm archive_write_set_format_ustar ,
38 .Nm archive_write_get_bytes_per_block ,
39 .Nm archive_write_set_bytes_per_block ,
40 .Nm archive_write_set_bytes_in_last_block ,
41 .Nm archive_write_set_compression_bzip2 ,
42 .Nm archive_write_set_compression_compress ,
43 .Nm archive_write_set_compression_gzip ,
44 .Nm archive_write_set_compression_none ,
45 .Nm archive_write_set_compression_program ,
46 .Nm archive_write_set_compressor_options ,
47 .Nm archive_write_set_format_options ,
48 .Nm archive_write_set_options ,
49 .Nm archive_write_open ,
50 .Nm archive_write_open_fd ,
51 .Nm archive_write_open_FILE ,
52 .Nm archive_write_open_filename ,
53 .Nm archive_write_open_memory ,
54 .Nm archive_write_header ,
55 .Nm archive_write_data ,
56 .Nm archive_write_finish_entry ,
57 .Nm archive_write_close ,
58 .Nm archive_write_finish
59 .Nd functions for creating archives
63 .Fn archive_write_new "void"
65 .Fn archive_write_get_bytes_per_block "struct archive *"
67 .Fn archive_write_set_bytes_per_block "struct archive *" "int bytes_per_block"
69 .Fn archive_write_set_bytes_in_last_block "struct archive *" "int"
71 .Fn archive_write_set_compression_bzip2 "struct archive *"
73 .Fn archive_write_set_compression_compress "struct archive *"
75 .Fn archive_write_set_compression_gzip "struct archive *"
77 .Fn archive_write_set_compression_none "struct archive *"
79 .Fn archive_write_set_compression_program "struct archive *" "const char * cmd"
81 .Fn archive_write_set_format_cpio "struct archive *"
83 .Fn archive_write_set_format_pax "struct archive *"
85 .Fn archive_write_set_format_pax_restricted "struct archive *"
87 .Fn archive_write_set_format_shar "struct archive *"
89 .Fn archive_write_set_format_shar_binary "struct archive *"
91 .Fn archive_write_set_format_ustar "struct archive *"
93 .Fn archive_write_set_format_options "struct archive *" "const char *"
95 .Fn archive_write_set_compressor_options "struct archive *" "const char *"
97 .Fn archive_write_set_options "struct archive *" "const char *"
99 .Fo archive_write_open
100 .Fa "struct archive *"
101 .Fa "void *client_data"
102 .Fa "archive_open_callback *"
103 .Fa "archive_write_callback *"
104 .Fa "archive_close_callback *"
107 .Fn archive_write_open_fd "struct archive *" "int fd"
109 .Fn archive_write_open_FILE "struct archive *" "FILE *file"
111 .Fn archive_write_open_filename "struct archive *" "const char *filename"
113 .Fo archive_write_open_memory
114 .Fa "struct archive *"
116 .Fa "size_t bufferSize"
117 .Fa "size_t *outUsed"
120 .Fn archive_write_header "struct archive *" "struct archive_entry *"
122 .Fn archive_write_data "struct archive *" "const void *" "size_t"
124 .Fn archive_write_finish_entry "struct archive *"
126 .Fn archive_write_close "struct archive *"
128 .Fn archive_write_finish "struct archive *"
130 These functions provide a complete API for creating streaming
132 The general process is to first create the
134 object, set any desired options, initialize the archive, append entries, then
135 close the archive and release all resources.
136 The following summary describes the functions in approximately
137 the order they are ordinarily used:
138 .Bl -tag -width indent
139 .It Fn archive_write_new
140 Allocates and initializes a
142 object suitable for writing a tar archive.
143 .It Fn archive_write_set_bytes_per_block
144 Sets the block size used for writing the archive data.
145 Every call to the write callback function, except possibly the last one, will
146 use this value for the length.
147 The third parameter is a boolean that specifies whether or not the final block
148 written will be padded to the full block size.
149 If it is zero, the last block will not be padded.
150 If it is non-zero, padding will be added both before and after compression.
151 The default is to use a block size of 10240 bytes and to pad the last block.
152 Note that a block size of zero will suppress internal blocking
153 and cause writes to be sent directly to the write callback as they occur.
154 .It Fn archive_write_get_bytes_per_block
155 Retrieve the block size to be used for writing.
156 A value of -1 here indicates that the library should use default values.
157 A value of zero indicates that internal blocking is suppressed.
158 .It Fn archive_write_set_bytes_in_last_block
159 Sets the block size used for writing the last block.
160 If this value is zero, the last block will be padded to the same size
162 Otherwise, the final block will be padded to a multiple of this size.
163 In particular, setting it to 1 will cause the final block to not be padded.
164 For compressed output, any padding generated by this option
165 is applied only after the compression.
166 The uncompressed data is always unpadded.
167 The default is to pad the last block to the full block size (note that
168 .Fn archive_write_open_filename
169 will set this based on the file type).
172 functions, this function can be called after the archive is opened.
173 .It Fn archive_write_get_bytes_in_last_block
174 Retrieve the currently-set value for last block size.
175 A value of -1 here indicates that the library should use default values.
177 .Fn archive_write_set_format_cpio ,
178 .Fn archive_write_set_format_pax ,
179 .Fn archive_write_set_format_pax_restricted ,
180 .Fn archive_write_set_format_shar ,
181 .Fn archive_write_set_format_shar_binary ,
182 .Fn archive_write_set_format_ustar
184 Sets the format that will be used for the archive.
185 The library can write
186 POSIX octet-oriented cpio format archives,
195 shar archives that store a variety of file attributes and handle binary files,
200 The pax interchange format is a backwards-compatible tar format that
201 adds key/value attributes to each entry and supports arbitrary
202 filenames, linknames, uids, sizes, etc.
203 .Dq Restricted pax interchange format
204 is the library default; this is the same as pax format, but suppresses
205 the pax extended header for most normal files.
206 In most cases, this will result in ordinary ustar archives.
208 .Fn archive_write_set_compression_bzip2 ,
209 .Fn archive_write_set_compression_compress ,
210 .Fn archive_write_set_compression_gzip ,
211 .Fn archive_write_set_compression_none
213 The resulting archive will be compressed as specified.
214 Note that the compressed output is always properly blocked.
215 .It Fn archive_write_set_compression_program
216 The archive will be fed into the specified compression program.
217 The output of that program is blocked and written to the client
220 .Fn archive_write_set_compressor_options ,
221 .Fn archive_write_set_format_options ,
222 .Fn archive_write_set_options
224 Specifies options that will be passed to the currently-enabled
225 compressor and/or format writer.
226 The argument is a comma-separated list of individual options.
227 Individual options have one of the following forms:
228 .Bl -tag -compact -width indent
230 The option/value pair will be provided to every module.
231 Modules that do not accept an option with this name will ignore it.
233 The option will be provided to every module with a value of
236 The option will be provided to every module with a NULL value.
237 .It Ar module:option=value , Ar module:option , Ar module:!option
238 As above, but the corresponding option and value will be provided
239 only to modules whose name matches
242 The return value will be
244 if any module accepts the option, or
246 if no module accepted the option, or
248 if there was a fatal error while attempting to process the option.
250 The currently supported options are:
251 .Bl -tag -compact -width indent
253 .Bl -tag -compact -width indent
254 .It Cm compression-level
255 The value is interpreted as a decimal integer specifying the
256 gzip compression level.
259 .Bl -tag -compact -width indent
260 .It Cm compression-level
261 The value is interpreted as a decimal integer specifying the
265 .Bl -tag -compact -width indent
266 .It Cm cksum , Cm device , Cm flags , Cm gid , Cm gname , Cm indent , Cm link , Cm md5 , Cm mode , Cm nlink , Cm rmd160 , Cm sha1 , Cm sha256 , Cm sha384 , Cm sha512 , Cm size , Cm time , Cm uid , Cm uname
267 Enable a particular keyword in the mtree output.
268 Prefix with an exclamation mark to disable the corresponding keyword.
269 The default is equivalent to
270 .Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname .
272 Enables all of the above keywords.
274 Enables generation of
276 lines that specify default values for the following files and/or directories.
278 XXX needs explanation XXX
281 .It Fn archive_write_open
282 Freeze the settings, open the archive, and prepare for writing entries.
283 This is the most generic form of this function, which accepts
284 pointers to three callback functions which will be invoked by
285 the compression layer to write the constructed archive.
286 .It Fn archive_write_open_fd
287 A convenience form of
288 .Fn archive_write_open
289 that accepts a file descriptor.
291 .Fn archive_write_open_fd
292 function is safe for use with tape drives or other
293 block-oriented devices.
294 .It Fn archive_write_open_FILE
295 A convenience form of
296 .Fn archive_write_open
301 .Fn archive_write_open_FILE
302 is not safe for writing to tape drives or other devices
303 that require correct blocking.
304 .It Fn archive_write_open_file
305 A deprecated synonym for
306 .Fn archive_write_open_filename .
307 .It Fn archive_write_open_filename
308 A convenience form of
309 .Fn archive_write_open
310 that accepts a filename.
311 A NULL argument indicates that the output should be written to standard output;
314 will open a file with that name.
315 If you have not invoked
316 .Fn archive_write_set_bytes_in_last_block ,
318 .Fn archive_write_open_filename
319 will adjust the last-block padding depending on the file:
320 it will enable padding when writing to standard output or
321 to a character or block device node, it will disable padding otherwise.
322 You can override this by manually invoking
323 .Fn archive_write_set_bytes_in_last_block
325 .Fn archive_write_open .
327 .Fn archive_write_open_filename
328 function is safe for use with tape drives or other
329 block-oriented devices.
330 .It Fn archive_write_open_memory
331 A convenience form of
332 .Fn archive_write_open
333 that accepts a pointer to a block of memory that will receive
337 argument points to a variable that will be updated
338 after each write to reflect how much of the buffer
340 You should be careful to ensure that this variable
341 remains allocated until after the archive is
343 .It Fn archive_write_header
344 Build and write a header using the data in the provided
345 .Tn struct archive_entry
349 for information on creating and populating
350 .Tn struct archive_entry
352 .It Fn archive_write_data
353 Write data corresponding to the header just written.
354 Returns number of bytes written or -1 on error.
355 .It Fn archive_write_finish_entry
356 Close out the entry just written.
357 In particular, this writes out the final padding required by some formats.
358 Ordinarily, clients never need to call this, as it
359 is called automatically by
360 .Fn archive_write_next_header
362 .Fn archive_write_close
364 .It Fn archive_write_close
365 Complete the archive and invoke the close callback.
366 .It Fn archive_write_finish
368 .Fn archive_write_close
369 if it was not invoked manually, then releases all resources.
370 Note that this function was declared to return
372 in libarchive 1.x, which made it impossible to detect errors when
373 .Fn archive_write_close
374 was invoked implicitly from this function.
375 This is corrected beginning with libarchive 2.0.
377 More information about the
379 object and the overall design of the library can be found in the
383 Compression support is built-in to libarchive, which uses zlib and bzlib
384 to handle gzip and bzip2 compression, respectively.
386 To use this library, you will need to define and register
387 callback functions that will be invoked to write data to the
389 These functions are registered by calling
390 .Fn archive_write_open :
391 .Bl -item -offset indent
394 .Fn archive_open_callback "struct archive *" "void *client_data"
397 The open callback is invoked by
398 .Fn archive_write_open .
401 if the underlying file or data source is successfully
403 If the open fails, it should call
404 .Fn archive_set_error
405 to register an error code and message and return
407 .Bl -item -offset indent
410 .Fo archive_write_callback
411 .Fa "struct archive *"
412 .Fa "void *client_data"
413 .Fa "const void *buffer"
418 The write callback is invoked whenever the library
419 needs to write raw bytes to the archive.
420 For correct blocking, each call to the write callback function
421 should translate into a single
424 This is especially critical when writing archives to tape drives.
425 On success, the write callback should return the
426 number of bytes actually written.
427 On error, the callback should invoke
428 .Fn archive_set_error
429 to register an error code and message and return -1.
430 .Bl -item -offset indent
433 .Fn archive_close_callback "struct archive *" "void *client_data"
436 The close callback is invoked by archive_close when
437 the archive processing is complete.
438 The callback should return
441 On failure, the callback should invoke
442 .Fn archive_set_error
443 to register an error code and message and
447 The following sketch illustrates basic usage of the library.
449 the callback functions are simply wrappers around the standard
455 .Bd -literal -offset indent
457 #define _FILE_OFFSET_BITS 64
459 #include <sys/stat.h>
461 #include <archive_entry.h>
472 myopen(struct archive *a, void *client_data)
474 struct mydata *mydata = client_data;
476 mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
480 return (ARCHIVE_FATAL);
484 mywrite(struct archive *a, void *client_data, const void *buff, size_t n)
486 struct mydata *mydata = client_data;
488 return (write(mydata->fd, buff, n));
492 myclose(struct archive *a, void *client_data)
494 struct mydata *mydata = client_data;
502 write_archive(const char *outname, const char **filename)
504 struct mydata *mydata = malloc(sizeof(struct mydata));
506 struct archive_entry *entry;
512 a = archive_write_new();
513 mydata->name = outname;
514 archive_write_set_compression_gzip(a);
515 archive_write_set_format_ustar(a);
516 archive_write_open(a, mydata, myopen, mywrite, myclose);
518 stat(*filename, &st);
519 entry = archive_entry_new();
520 archive_entry_copy_stat(entry, &st);
521 archive_entry_set_pathname(entry, *filename);
522 archive_write_header(a, entry);
523 fd = open(*filename, O_RDONLY);
524 len = read(fd, buff, sizeof(buff));
526 archive_write_data(a, buff, len);
527 len = read(fd, buff, sizeof(buff));
529 archive_entry_free(entry);
532 archive_write_finish(a);
535 int main(int argc, const char **argv)
540 write_archive(outname, argv);
545 Most functions return
547 (zero) on success, or one of several non-zero
548 error codes for errors.
549 Specific error codes include:
551 for operations that might succeed if retried,
553 for unusual conditions that do not prevent further operations, and
555 for serious errors that make remaining operations impossible.
559 .Fn archive_error_string
560 functions can be used to retrieve an appropriate error code and a
561 textual error message.
563 .Fn archive_write_new
564 returns a pointer to a newly-allocated
568 .Fn archive_write_data
569 returns a count of the number of bytes actually written.
570 On error, -1 is returned and the
573 .Fn archive_error_string
574 functions will return appropriate values.
575 Note that if the client-provided write callback function
576 returns a non-zero value, that error will be propagated back to the caller
577 through whatever API function resulted in that call, which
579 .Fn archive_write_header ,
580 .Fn archive_write_data ,
581 .Fn archive_write_close ,
583 .Fn archive_write_finish .
584 The client callback can call
585 .Fn archive_set_error
586 to provide values that can then be retrieved by
589 .Fn archive_error_string .
597 library first appeared in
603 library was written by
604 .An Tim Kientzle Aq kientzle@acm.org .
606 There are many peculiar bugs in historic tar implementations that may cause
607 certain programs to reject archives written by this library.
608 For example, several historic implementations calculated header checksums
609 incorrectly and will thus reject valid archives; GNU tar does not fully support
610 pax interchange format; some old tar implementations required specific
613 The default pax interchange format eliminates most of the historic
614 tar limitations and provides a generic key/value attribute facility
615 for vendor-defined extensions.
616 One oversight in POSIX is the failure to provide a standard attribute
617 for large device numbers.
622 for device numbers that exceed the range supported by the backwards-compatible
624 These keys are compatible with Joerg Schilling's
627 Other implementations may not recognize these keys and will thus be unable
628 to correctly restore device nodes with large device numbers from archives
629 created by this library.