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: src/lib/libarchive/archive_write.3,v 1.21 2007/03/03 07:37:36 kientzle 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_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_compressor_gzip ,
42 .Nm archive_write_set_compressor_bzip2 ,
43 .Nm archive_write_open ,
44 .Nm archive_write_open_fd ,
45 .Nm archive_write_open_FILE ,
46 .Nm archive_write_open_filename ,
47 .Nm archive_write_open_memory ,
48 .Nm archive_write_header ,
49 .Nm archive_write_data ,
50 .Nm archive_write_finish_entry ,
51 .Nm archive_write_close ,
52 .Nm archive_write_finish
53 .Nd functions for creating archives
57 .Fn archive_write_new "void"
59 .Fn archive_write_get_bytes_per_block "struct archive *"
61 .Fn archive_write_set_bytes_per_block "struct archive *" "int bytes_per_block"
63 .Fn archive_write_set_bytes_in_last_block "struct archive *" "int"
65 .Fn archive_write_set_compressor_gzip "struct archive *"
67 .Fn archive_write_set_compressor_bzip2 "struct archive *"
69 .Fn archive_write_set_format_cpio "struct archive *"
71 .Fn archive_write_set_format_pax "struct archive *"
73 .Fn archive_write_set_format_pax_restricted "struct archive *"
75 .Fn archive_write_set_format_shar "struct archive *"
77 .Fn archive_write_set_format_shar_binary "struct archive *"
79 .Fn archive_write_set_format_ustar "struct archive *"
81 .Fn archive_write_open "struct archive *" "void *client_data" "archive_open_callback *" "archive_write_callback *" "archive_close_callback *"
83 .Fn archive_write_open_fd "struct archive *" "int fd"
85 .Fn archive_write_open_FILE "struct archive *" "FILE *file"
87 .Fn archive_write_open_filename "struct archive *" "const char *filename"
89 .Fn archive_write_open_memory "struct archive *" "void *buffer" "size_t bufferSize" "size_t *outUsed"
91 .Fn archive_write_header "struct archive *" "struct archive_entry *"
93 .Fn archive_write_data "struct archive *" "const void *" "size_t"
95 .Fn archive_write_finish_entry "struct archive *"
97 .Fn archive_write_close "struct archive *"
99 .Fn archive_write_finish "struct archive *"
101 These functions provide a complete API for creating streaming
103 The general process is to first create the
105 object, set any desired options, initialize the archive, append entries, then
106 close the archive and release all resources.
107 The following summary describes the functions in approximately
108 the order they are ordinarily used:
109 .Bl -tag -width indent
110 .It Fn archive_write_new
111 Allocates and initializes a
113 object suitable for writing a tar archive.
114 .It Fn archive_write_set_bytes_per_block
115 Sets the block size used for writing the archive data.
116 Every call to the write callback function, except possibly the last one, will
117 use this value for the length.
118 The third parameter is a boolean that specifies whether or not the final block
119 written will be padded to the full block size.
120 If it is zero, the last block will not be padded.
121 If it is non-zero, padding will be added both before and after compression.
122 The default is to use a block size of 10240 bytes and to pad the last block.
123 Note that a block size of zero will suppress internal blocking
124 and cause writes to be sent directly to the write callback as they occur.
125 .It Fn archive_write_get_bytes_per_block
126 Retrieve the block size to be used for writing.
127 A value of -1 here indicates that the library should use default values.
128 A value of zero indicates that internal blocking is suppressed.
129 .It Fn archive_write_set_bytes_in_last_block
130 Sets the block size used for writing the last block.
131 If this value is zero, the last block will be padded to the same size
133 Otherwise, the final block will be padded to a multiple of this size.
134 In particular, setting it to 1 will cause the final block to not be padded.
135 For compressed output, any padding generated by this option
136 is applied only after the compression.
137 The uncompressed data is always unpadded.
138 The default is to pad the last block to the full block size (note that
139 .Fn archive_write_open_filename
140 will set this based on the file type).
143 functions, this function can be called after the archive is opened.
144 .It Fn archive_write_get_bytes_in_last_block
145 Retrieve the currently-set value for last block size.
146 A value of -1 here indicates that the library should use default values.
147 .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
148 Sets the format that will be used for the archive.
149 The library can write
150 POSIX octet-oriented cpio format archives,
159 shar archives that store a variety of file attributes and handle binary files,
164 The pax interchange format is a backwards-compatible tar format that
165 adds key/value attributes to each entry and supports arbitrary
166 filenames, linknames, uids, sizes, etc.
167 .Dq Restricted pax interchange format
168 is the library default; this is the same as pax format, but suppresses
169 the pax extended header for most normal files.
170 In most cases, this will result in ordinary ustar archives.
171 .It Fn archive_write_set_compression_gzip , Fn archive_write_set_compression_bzip2
172 The resulting archive will be compressed as specified.
173 Note that the compressed output is always properly blocked.
174 .It Fn archive_write_open
175 Freeze the settings, open the archive, and prepare for writing entries.
176 This is the most generic form of this function, which accepts
177 pointers to three callback functions which will be invoked by
178 the compression layer to write the constructed archive.
179 .It Fn archive_write_open_fd
180 A convenience form of
181 .Fn archive_write_open
182 that accepts a file descriptor.
184 .Fn archive_write_open_fd
185 function is safe for use with tape drives or other
186 block-oriented devices.
187 .It Fn archive_write_open_FILE
188 A convenience form of
189 .Fn archive_write_open
194 .Fn archive_write_open_FILE
195 is not safe for writing to tape drives or other devices
196 that require correct blocking.
197 .It Fn archive_write_open_file
198 A deprecated synonym for
199 .Fn archive_write_open_filename .
200 .It Fn archive_write_open_filename
201 A convenience form of
202 .Fn archive_write_open
203 that accepts a filename.
204 A NULL argument indicates that the output should be written to standard output;
207 will open a file with that name.
208 If you have not invoked
209 .Fn archive_write_set_bytes_in_last_block ,
211 .Fn archive_write_open_filename
212 will adjust the last-block padding depending on the file:
213 it will enable padding when writing to standard output or
214 to a character or block device node, it will disable padding otherwise.
215 You can override this by manually invoking
216 .Fn archive_write_set_bytes_in_last_block
218 .Fn archive_write_open .
220 .Fn archive_write_open_filename
221 function is safe for use with tape drives or other
222 block-oriented devices.
223 .It Fn archive_write_open_memory
224 A convenience form of
225 .Fn archive_write_open
226 that accepts a pointer to a block of memory that will receive
230 argument points to a variable that will be updated
231 after each write to reflect how much of the buffer
233 You should be careful to ensure that this variable
234 remains allocated until after the archive is
236 .It Fn archive_write_header
237 Build and write a header using the data in the provided
238 .Tn struct archive_entry
242 for information on creating and populating
243 .Tn struct archive_entry
245 .It Fn archive_write_data
246 Write data corresponding to the header just written.
247 Returns number of bytes written or -1 on error.
248 .It Fn archive_write_finish_entry
249 Close out the entry just written.
250 In particular, this writes out the final padding required by some formats.
251 Ordinarily, clients never need to call this, as it
252 is called automatically by
253 .Fn archive_write_next_header
255 .Fn archive_write_close
257 .It Fn archive_write_close
258 Complete the archive and invoke the close callback.
259 .It Fn archive_write_finish
261 .Fn archive_write_close
262 if it was not invoked manually, then releases all resources.
263 Note that this function was declared to return
265 in libarchive 1.x, which made it impossible to detect errors when
266 .Fn archive_write_close
267 was invoked implicitly from this function.
268 This is corrected beginning with libarchive 2.0.
270 More information about the
272 object and the overall design of the library can be found in the
276 Compression support is built-in to libarchive, which uses zlib and bzlib
277 to handle gzip and bzip2 compression, respectively.
279 To use this library, you will need to define and register
280 callback functions that will be invoked to write data to the
282 These functions are registered by calling
283 .Fn archive_write_open :
284 .Bl -item -offset indent
287 .Fn archive_open_callback "struct archive *" "void *client_data"
290 The open callback is invoked by
291 .Fn archive_write_open .
294 if the underlying file or data source is successfully
296 If the open fails, it should call
297 .Fn archive_set_error
298 to register an error code and message and return
300 .Bl -item -offset indent
303 .Fn archive_write_callback "struct archive *" "void *client_data" "void *buffer" "size_t length"
306 The write callback is invoked whenever the library
307 needs to write raw bytes to the archive.
308 For correct blocking, each call to the write callback function
309 should translate into a single
312 This is especially critical when writing archives to tape drives.
313 On success, the write callback should return the
314 number of bytes actually written.
315 On error, the callback should invoke
316 .Fn archive_set_error
317 to register an error code and message and return -1.
318 .Bl -item -offset indent
321 .Fn archive_close_callback "struct archive *" "void *client_data"
324 The close callback is invoked by archive_close when
325 the archive processing is complete.
326 The callback should return
329 On failure, the callback should invoke
330 .Fn archive_set_error
331 to register an error code and message and
335 The following sketch illustrates basic usage of the library.
337 the callback functions are simply wrappers around the standard
343 .Bd -literal -offset indent
344 #include <sys/stat.h>
346 #include <archive_entry.h>
357 myopen(struct archive *a, void *client_data)
359 struct mydata *mydata = client_data;
361 mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
365 return (ARCHIVE_FATAL);
369 mywrite(struct archive *a, void *client_data, void *buff, size_t n)
371 struct mydata *mydata = client_data;
373 return (write(mydata->fd, buff, n));
377 myclose(struct archive *a, void *client_data)
379 struct mydata *mydata = client_data;
387 write_archive(const char *outname, const char **filename)
389 struct mydata *mydata = malloc(sizeof(struct mydata));
391 struct archive_entry *entry;
397 a = archive_write_new();
398 mydata->name = outname;
399 archive_write_set_compression_gzip(a);
400 archive_write_set_format_ustar(a);
401 archive_write_open(a, mydata, myopen, mywrite, myclose);
403 stat(*filename, &st);
404 entry = archive_entry_new();
405 archive_entry_copy_stat(entry, &st);
406 archive_entry_set_pathname(entry, *filename);
407 archive_write_header(a, entry);
408 fd = open(*filename, O_RDONLY);
409 len = read(fd, buff, sizeof(buff));
411 archive_write_data(a, buff, len);
412 len = read(fd, buff, sizeof(buff));
414 archive_entry_free(entry);
417 archive_write_finish(a);
420 int main(int argc, const char **argv)
425 write_archive(outname, argv);
430 Most functions return
432 (zero) on success, or one of several non-zero
433 error codes for errors.
434 Specific error codes include:
436 for operations that might succeed if retried,
438 for unusual conditions that do not prevent further operations, and
440 for serious errors that make remaining operations impossible.
444 .Fn archive_error_string
445 functions can be used to retrieve an appropriate error code and a
446 textual error message.
448 .Fn archive_write_new
449 returns a pointer to a newly-allocated
453 .Fn archive_write_data
454 returns a count of the number of bytes actually written.
455 On error, -1 is returned and the
458 .Fn archive_error_string
459 functions will return appropriate values.
460 Note that if the client-provided write callback function
461 returns a non-zero value, that error will be propagated back to the caller
462 through whatever API function resulted in that call, which
464 .Fn archive_write_header ,
465 .Fn archive_write_data ,
466 .Fn archive_write_close ,
468 .Fn archive_write_finish .
469 The client callback can call
470 .Fn archive_set_error
471 to provide values that can then be retrieved by
474 .Fn archive_error_string .
482 library first appeared in
488 library was written by
489 .An Tim Kientzle Aq kientzle@acm.org .
491 There are many peculiar bugs in historic tar implementations that may cause
492 certain programs to reject archives written by this library.
493 For example, several historic implementations calculated header checksums
494 incorrectly and will thus reject valid archives; GNU tar does not fully support
495 pax interchange format; some old tar implementations required specific
498 The default pax interchange format eliminates most of the historic
499 tar limitations and provides a generic key/value attribute facility
500 for vendor-defined extensions.
501 One oversight in POSIX is the failure to provide a standard attribute
502 for large device numbers.
507 for device numbers that exceed the range supported by the backwards-compatible
509 These keys are compatible with Joerg Schilling's
512 Other implementations may not recognize these keys and will thus be unable
513 to correctly restore device nodes with large device numbers from archives
514 created by this library.