1 .\" Copyright (c) 2003-2006 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: src/lib/libarchive/archive_write.3,v 1.13 2005/11/24 10:06:05 ru Exp $
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_set_bytes_per_block ,
39 .Nm archive_write_set_bytes_in_last_block ,
40 .Nm archive_write_set_compressor_gzip ,
41 .Nm archive_write_set_compressor_bzip2 ,
42 .Nm archive_write_open ,
43 .Nm archive_write_open_fd ,
44 .Nm archive_write_open_FILE ,
45 .Nm archive_write_open_filename ,
46 .Nm archive_write_open_memory ,
47 .Nm archive_write_prepare ,
48 .Nm archive_write_header ,
49 .Nm archive_write_data ,
50 .Nm archive_write_close ,
51 .Nm archive_write_finish
52 .Nd functions for creating archives
56 .Fn archive_write_new "void"
58 .Fn archive_write_set_bytes_per_block "struct archive *" "int bytes_per_block"
60 .Fn archive_write_set_bytes_in_last_block "struct archive *" "int"
62 .Fn archive_write_set_compressor_gzip "struct archive *"
64 .Fn archive_write_set_compressor_bzip2 "struct archive *"
66 .Fn archive_write_set_format_cpio "struct archive *"
68 .Fn archive_write_set_format_pax "struct archive *"
70 .Fn archive_write_set_format_pax_restricted "struct archive *"
72 .Fn archive_write_set_format_shar "struct archive *"
74 .Fn archive_write_set_format_shar_binary "struct archive *"
76 .Fn archive_write_set_format_ustar "struct archive *"
78 .Fn archive_write_open "struct archive *" "void *client_data" "archive_open_callback *" "archive_write_callback *" "archive_close_callback *"
80 .Fn archive_write_open_fd "struct archive *" "int fd"
82 .Fn archive_write_open_FILE "struct archive *" "FILE *file"
84 .Fn archive_write_open_filename "struct archive *" "const char *filename"
86 .Fn archive_write_open_memory "struct archive *" "void *buffer" "size_t bufferSize" "size_t *outUsed"
88 .Fn archive_write_header "struct archive *" "struct archive_entry *"
90 .Fn archive_write_data "struct archive *" "const void *" "size_t"
92 .Fn archive_write_close "struct archive *"
94 .Fn archive_write_finish "struct archive *"
96 These functions provide a complete API for creating streaming
98 The general process is to first create the
100 object, set any desired options, initialize the archive, append entries, then
101 close the archive and release all resources.
102 The following summary describes the functions in approximately
103 the order they are ordinarily used:
104 .Bl -tag -width indent
105 .It Fn archive_write_new
106 Allocates and initializes a
108 object suitable for writing a tar archive.
109 .It Fn archive_write_set_bytes_per_block
110 Sets the block size used for writing the archive data.
111 Every call to the write callback function, except possibly the last one, will
112 use this value for the length.
113 The third parameter is a boolean that specifies whether or not the final block
114 written will be padded to the full block size.
115 If it is zero, the last block will not be padded.
116 If it is non-zero, padding will be added both before and after compression.
117 The default is to use a block size of 10240 bytes and to pad the last block.
118 .It Fn archive_write_set_bytes_in_last_block
119 Sets the block size used for writing the last block.
120 If this value is zero, the last block will be padded to the same size
122 Otherwise, the final block will be padded to a multiple of this size.
123 In particular, setting it to 1 will cause the final block to not be padded.
124 For compressed output, any padding generated by this option
125 is applied only after the compression.
126 The uncompressed data is always unpadded.
127 The default is to pad the last block to the full block size (note that
128 .Fn archive_write_open_file
129 will set this based on the file type).
132 functions, this function can be called after the archive is opened.
133 .It Fn archive_write_set_format_cpio , Fn archive_write_set_format_pax , Fn archive_write_set_format_pax_restricted , Fn archive_write_set_format_shar , Fn archive_write_set_format_shar_binary , Fn archive_write_set_format_ustar
134 Sets the format that will be used for the archive.
135 The library can write
136 POSIX octet-oriented cpio format archives,
145 shar archives that store a variety of file attributes and handle binary files,
150 The pax interchange format is a backwards-compatible tar format that
151 adds key/value attributes to each entry and supports arbitrary
152 filenames, linknames, uids, sizes, etc.
153 .Dq Restricted pax interchange format
154 is the library default; this is the same as pax format, but suppresses
155 the pax extended header for most normal files.
156 In most cases, this will result in ordinary ustar archives.
157 .It Fn archive_write_set_compression_gzip , Fn archive_write_set_compression_bzip2
158 The resulting archive will be compressed as specified.
159 Note that the compressed output is always properly blocked.
160 .It Fn archive_write_open
161 Freeze the settings, open the archive, and prepare for writing entries.
162 This is the most generic form of this function, which accepts
163 pointers to three callback functions which will be invoked by
164 the compression layer to write the constructed archive.
165 .It Fn archive_write_open_fd
166 A convenience form of
167 .Fn archive_write_open
168 that accepts a file descriptor.
170 .It Fn archive_write_open_FILE
171 A convenience form of
172 .Fn archive_write_open
177 .Fn archive_write_open_FILE
178 is not safe for writing to tape drives or other devices
179 that require correct blocking.
180 .Fn archive_write_open_fd
181 function is safe for use with tape drives or other
182 block-oriented devices.
183 .It Fn archive_write_open_file
184 A deprecated synonym for
185 .Fn archive_write_open_filename .
186 .It Fn archive_write_open_filename
187 A convenience form of
188 .Fn archive_write_open
189 that accepts a filename.
190 A NULL argument indicates that the output should be written to standard output;
193 will open a file with that name.
194 If you have not invoked
195 .Fn archive_write_set_bytes_in_last_block ,
197 .Fn archive_write_open_filename
198 will adjust the last-block padding depending on the file:
199 it will enable padding when writing to standard output or
200 to a character or block device node, it will disable padding otherwise.
201 You can override this by manually invoking
202 .Fn archive_write_set_bytes_in_last_block
203 either before or after calling
204 .Fn archive_write_open .
206 .Fn archive_write_open_filename
207 function is safe for use with tape drives or other
208 block-oriented devices.
209 .It Fn archive_write_open_memory
210 A convenience form of
211 .Fn archive_write_open
212 that accepts a pointer to a block of memory that will receive
216 argument points to a variable that will be updated
217 after each write to reflect how much of the buffer
219 You should be careful to ensure that this variable
220 remains allocated until after the archive is
222 .It Fn archive_write_header
223 Build and write a header using the data in the provided
224 .Tn struct archive_entry
228 for information on creating and populating
229 .Tn struct archive_entry
231 .It Fn archive_write_data
232 Write data corresponding to the header just written.
233 Returns number of bytes written or -1 on error.
234 .It Fn archive_write_close
235 Complete the archive and invoke the close callback.
236 .It Fn archive_write_finish
238 .Fn archive_write_close
239 if it was not invoked manually, then releases all resources.
240 Note that this function was declared to return
242 in libarchive 1.x, which made it impossible to detect errors when
243 .Fn archive_write_close
244 was invoked implicitly from this function.
245 This is corrected beginning with libarchive 2.0.
247 More information about the
249 object and the overall design of the library can be found in the
253 Compression support is built-in to libarchive, which uses zlib and bzlib
254 to handle gzip and bzip2 compression, respectively.
256 To use this library, you will need to define and register
257 callback functions that will be invoked to write data to the
259 These functions are registered by calling
260 .Fn archive_write_open :
261 .Bl -item -offset indent
264 .Fn archive_open_callback "struct archive *" "void *client_data"
267 The open callback is invoked by
268 .Fn archive_write_open .
271 if the underlying file or data source is successfully
273 If the open fails, it should call
274 .Fn archive_set_error
275 to register an error code and message and return
277 .Bl -item -offset indent
280 .Fn archive_write_callback "struct archive *" "void *client_data" "void *buffer" "size_t length"
283 The write callback is invoked whenever the library
284 needs to write raw bytes to the archive.
285 For correct blocking, each call to the write callback function
286 should translate into a single
289 This is especially critical when writing archives to tape drives.
290 On success, the write callback should return the
291 number of bytes actually written.
292 On error, the callback should invoke
293 .Fn archive_set_error
294 to register an error code and message and return -1.
295 .Bl -item -offset indent
298 .Fn archive_close_callback "struct archive *" "void *client_data"
301 The close callback is invoked by archive_close when
302 the archive processing is complete.
303 The callback should return
306 On failure, the callback should invoke
307 .Fn archive_set_error
308 to register an error code and message and
312 The following sketch illustrates basic usage of the library.
314 the callback functions are simply wrappers around the standard
320 .Bd -literal -offset indent
321 #include <sys/stat.h>
323 #include <archive_entry.h>
334 myopen(struct archive *a, void *client_data)
336 struct mydata *mydata = client_data;
338 mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
342 return (ARCHIVE_FATAL);
346 mywrite(struct archive *a, void *client_data, void *buff, size_t n)
348 struct mydata *mydata = client_data;
350 return (write(mydata->fd, buff, n));
354 myclose(struct archive *a, void *client_data)
356 struct mydata *mydata = client_data;
364 write_archive(const char *outname, const char **filename)
366 struct mydata *mydata = malloc(sizeof(struct mydata));
368 struct archive_entry *entry;
374 a = archive_write_new();
375 mydata->name = outname;
376 archive_write_set_compression_gzip(a);
377 archive_write_set_format_ustar(a);
378 archive_write_open(a, mydata, myopen, mywrite, myclose);
380 stat(*filename, &st);
381 entry = archive_entry_new();
382 archive_entry_copy_stat(entry, &st);
383 archive_entry_set_pathname(entry, *filename);
384 archive_write_header(a, entry);
385 fd = open(*filename, O_RDONLY);
386 len = read(fd, buff, sizeof(buff));
388 archive_write_data(a, buff, len);
389 len = read(fd, buff, sizeof(buff));
391 archive_entry_free(entry);
394 archive_write_finish(a);
397 int main(int argc, const char **argv)
402 write_archive(outname, argv);
407 Most functions return
409 (zero) on success, or one of several non-zero
410 error codes for errors.
411 Specific error codes include:
413 for operations that might succeed if retried,
415 for unusual conditions that do not prevent further operations, and
417 for serious errors that make remaining operations impossible.
421 .Fn archive_error_string
422 functions can be used to retrieve an appropriate error code and a
423 textual error message.
425 .Fn archive_write_new
426 returns a pointer to a newly-allocated
430 .Fn archive_write_data
431 returns a count of the number of bytes actually written.
432 On error, -1 is returned and the
435 .Fn archive_error_string
436 functions will return appropriate values.
437 Note that if the client-provided write callback function
438 returns a non-zero value, that error will be propagated back to the caller
439 through whatever API function resulted in that call, which
441 .Fn archive_write_header ,
442 .Fn archive_write_data ,
443 .Fn archive_write_close ,
445 .Fn archive_write_finish .
446 The client callback can call
447 .Fn archive_set_error
448 to provide values that can then be retrieved by
451 .Fn archive_error_string .
459 library first appeared in
465 library was written by
466 .An Tim Kientzle Aq kientzle@acm.org .
468 There are many peculiar bugs in historic tar implementations that may cause
469 certain programs to reject archives written by this library.
470 For example, several historic implementations calculated header checksums
471 incorrectly and will thus reject valid archives; GNU tar does not fully support
472 pax interchange format; some old tar implementations required specific
475 The default pax interchange format eliminates most of the historic
476 tar limitations and provides a generic key/value attribute facility
477 for vendor-defined extensions.
478 One oversight in POSIX is the failure to provide a standard attribute
479 for large device numbers.
484 for device numbers that exceed the range supported by the backwards-compatible
486 These keys are compatible with Joerg Schilling's
489 Other implementations may not recognize these keys and will thus be unable
490 to correctly restore device nodes with large device numbers.