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_compression_bzip2 ,
42 .Nm archive_write_set_compression_gzip ,
43 .Nm archive_write_set_compression_none ,
44 .Nm archive_write_set_compression_program ,
45 .Nm archive_write_open ,
46 .Nm archive_write_open_fd ,
47 .Nm archive_write_open_FILE ,
48 .Nm archive_write_open_filename ,
49 .Nm archive_write_open_memory ,
50 .Nm archive_write_header ,
51 .Nm archive_write_data ,
52 .Nm archive_write_finish_entry ,
53 .Nm archive_write_close ,
54 .Nm archive_write_finish
55 .Nd functions for creating archives
59 .Fn archive_write_new "void"
61 .Fn archive_write_get_bytes_per_block "struct archive *"
63 .Fn archive_write_set_bytes_per_block "struct archive *" "int bytes_per_block"
65 .Fn archive_write_set_bytes_in_last_block "struct archive *" "int"
67 .Fn archive_write_set_compression_bzip2 "struct archive *"
69 .Fn archive_write_set_compression_gzip "struct archive *"
71 .Fn archive_write_set_compression_none "struct archive *"
73 .Fn archive_write_set_compression_program "struct archive *" "const char * cmd"
75 .Fn archive_write_set_format_cpio "struct archive *"
77 .Fn archive_write_set_format_pax "struct archive *"
79 .Fn archive_write_set_format_pax_restricted "struct archive *"
81 .Fn archive_write_set_format_shar "struct archive *"
83 .Fn archive_write_set_format_shar_binary "struct archive *"
85 .Fn archive_write_set_format_ustar "struct archive *"
87 .Fn archive_write_open "struct archive *" "void *client_data" "archive_open_callback *" "archive_write_callback *" "archive_close_callback *"
89 .Fn archive_write_open_fd "struct archive *" "int fd"
91 .Fn archive_write_open_FILE "struct archive *" "FILE *file"
93 .Fn archive_write_open_filename "struct archive *" "const char *filename"
95 .Fn archive_write_open_memory "struct archive *" "void *buffer" "size_t bufferSize" "size_t *outUsed"
97 .Fn archive_write_header "struct archive *" "struct archive_entry *"
99 .Fn archive_write_data "struct archive *" "const void *" "size_t"
101 .Fn archive_write_finish_entry "struct archive *"
103 .Fn archive_write_close "struct archive *"
105 .Fn archive_write_finish "struct archive *"
107 These functions provide a complete API for creating streaming
109 The general process is to first create the
111 object, set any desired options, initialize the archive, append entries, then
112 close the archive and release all resources.
113 The following summary describes the functions in approximately
114 the order they are ordinarily used:
115 .Bl -tag -width indent
116 .It Fn archive_write_new
117 Allocates and initializes a
119 object suitable for writing a tar archive.
120 .It Fn archive_write_set_bytes_per_block
121 Sets the block size used for writing the archive data.
122 Every call to the write callback function, except possibly the last one, will
123 use this value for the length.
124 The third parameter is a boolean that specifies whether or not the final block
125 written will be padded to the full block size.
126 If it is zero, the last block will not be padded.
127 If it is non-zero, padding will be added both before and after compression.
128 The default is to use a block size of 10240 bytes and to pad the last block.
129 Note that a block size of zero will suppress internal blocking
130 and cause writes to be sent directly to the write callback as they occur.
131 .It Fn archive_write_get_bytes_per_block
132 Retrieve the block size to be used for writing.
133 A value of -1 here indicates that the library should use default values.
134 A value of zero indicates that internal blocking is suppressed.
135 .It Fn archive_write_set_bytes_in_last_block
136 Sets the block size used for writing the last block.
137 If this value is zero, the last block will be padded to the same size
139 Otherwise, the final block will be padded to a multiple of this size.
140 In particular, setting it to 1 will cause the final block to not be padded.
141 For compressed output, any padding generated by this option
142 is applied only after the compression.
143 The uncompressed data is always unpadded.
144 The default is to pad the last block to the full block size (note that
145 .Fn archive_write_open_filename
146 will set this based on the file type).
149 functions, this function can be called after the archive is opened.
150 .It Fn archive_write_get_bytes_in_last_block
151 Retrieve the currently-set value for last block size.
152 A value of -1 here indicates that the library should use default values.
153 .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
154 Sets the format that will be used for the archive.
155 The library can write
156 POSIX octet-oriented cpio format archives,
165 shar archives that store a variety of file attributes and handle binary files,
170 The pax interchange format is a backwards-compatible tar format that
171 adds key/value attributes to each entry and supports arbitrary
172 filenames, linknames, uids, sizes, etc.
173 .Dq Restricted pax interchange format
174 is the library default; this is the same as pax format, but suppresses
175 the pax extended header for most normal files.
176 In most cases, this will result in ordinary ustar archives.
177 .It Fn archive_write_set_compression_bzip2 , Fn archive_write_set_compression_gzip , Fn archive_write_set_compression_none
178 The resulting archive will be compressed as specified.
179 Note that the compressed output is always properly blocked.
180 .It Fn archive_write_set_compression_program
181 The archive will be fed into the specified compression program.
182 The output of that program is blocked and written to the client
184 .It Fn archive_write_open
185 Freeze the settings, open the archive, and prepare for writing entries.
186 This is the most generic form of this function, which accepts
187 pointers to three callback functions which will be invoked by
188 the compression layer to write the constructed archive.
189 .It Fn archive_write_open_fd
190 A convenience form of
191 .Fn archive_write_open
192 that accepts a file descriptor.
194 .Fn archive_write_open_fd
195 function is safe for use with tape drives or other
196 block-oriented devices.
197 .It Fn archive_write_open_FILE
198 A convenience form of
199 .Fn archive_write_open
204 .Fn archive_write_open_FILE
205 is not safe for writing to tape drives or other devices
206 that require correct blocking.
207 .It Fn archive_write_open_file
208 A deprecated synonym for
209 .Fn archive_write_open_filename .
210 .It Fn archive_write_open_filename
211 A convenience form of
212 .Fn archive_write_open
213 that accepts a filename.
214 A NULL argument indicates that the output should be written to standard output;
217 will open a file with that name.
218 If you have not invoked
219 .Fn archive_write_set_bytes_in_last_block ,
221 .Fn archive_write_open_filename
222 will adjust the last-block padding depending on the file:
223 it will enable padding when writing to standard output or
224 to a character or block device node, it will disable padding otherwise.
225 You can override this by manually invoking
226 .Fn archive_write_set_bytes_in_last_block
228 .Fn archive_write_open .
230 .Fn archive_write_open_filename
231 function is safe for use with tape drives or other
232 block-oriented devices.
233 .It Fn archive_write_open_memory
234 A convenience form of
235 .Fn archive_write_open
236 that accepts a pointer to a block of memory that will receive
240 argument points to a variable that will be updated
241 after each write to reflect how much of the buffer
243 You should be careful to ensure that this variable
244 remains allocated until after the archive is
246 .It Fn archive_write_header
247 Build and write a header using the data in the provided
248 .Tn struct archive_entry
252 for information on creating and populating
253 .Tn struct archive_entry
255 .It Fn archive_write_data
256 Write data corresponding to the header just written.
257 Returns number of bytes written or -1 on error.
258 .It Fn archive_write_finish_entry
259 Close out the entry just written.
260 In particular, this writes out the final padding required by some formats.
261 Ordinarily, clients never need to call this, as it
262 is called automatically by
263 .Fn archive_write_next_header
265 .Fn archive_write_close
267 .It Fn archive_write_close
268 Complete the archive and invoke the close callback.
269 .It Fn archive_write_finish
271 .Fn archive_write_close
272 if it was not invoked manually, then releases all resources.
273 Note that this function was declared to return
275 in libarchive 1.x, which made it impossible to detect errors when
276 .Fn archive_write_close
277 was invoked implicitly from this function.
278 This is corrected beginning with libarchive 2.0.
280 More information about the
282 object and the overall design of the library can be found in the
286 Compression support is built-in to libarchive, which uses zlib and bzlib
287 to handle gzip and bzip2 compression, respectively.
289 To use this library, you will need to define and register
290 callback functions that will be invoked to write data to the
292 These functions are registered by calling
293 .Fn archive_write_open :
294 .Bl -item -offset indent
297 .Fn archive_open_callback "struct archive *" "void *client_data"
300 The open callback is invoked by
301 .Fn archive_write_open .
304 if the underlying file or data source is successfully
306 If the open fails, it should call
307 .Fn archive_set_error
308 to register an error code and message and return
310 .Bl -item -offset indent
313 .Fn archive_write_callback "struct archive *" "void *client_data" "void *buffer" "size_t length"
316 The write callback is invoked whenever the library
317 needs to write raw bytes to the archive.
318 For correct blocking, each call to the write callback function
319 should translate into a single
322 This is especially critical when writing archives to tape drives.
323 On success, the write callback should return the
324 number of bytes actually written.
325 On error, the callback should invoke
326 .Fn archive_set_error
327 to register an error code and message and return -1.
328 .Bl -item -offset indent
331 .Fn archive_close_callback "struct archive *" "void *client_data"
334 The close callback is invoked by archive_close when
335 the archive processing is complete.
336 The callback should return
339 On failure, the callback should invoke
340 .Fn archive_set_error
341 to register an error code and message and
345 The following sketch illustrates basic usage of the library.
347 the callback functions are simply wrappers around the standard
353 .Bd -literal -offset indent
354 #include <sys/stat.h>
356 #include <archive_entry.h>
367 myopen(struct archive *a, void *client_data)
369 struct mydata *mydata = client_data;
371 mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
375 return (ARCHIVE_FATAL);
379 mywrite(struct archive *a, void *client_data, void *buff, size_t n)
381 struct mydata *mydata = client_data;
383 return (write(mydata->fd, buff, n));
387 myclose(struct archive *a, void *client_data)
389 struct mydata *mydata = client_data;
397 write_archive(const char *outname, const char **filename)
399 struct mydata *mydata = malloc(sizeof(struct mydata));
401 struct archive_entry *entry;
407 a = archive_write_new();
408 mydata->name = outname;
409 archive_write_set_compression_gzip(a);
410 archive_write_set_format_ustar(a);
411 archive_write_open(a, mydata, myopen, mywrite, myclose);
413 stat(*filename, &st);
414 entry = archive_entry_new();
415 archive_entry_copy_stat(entry, &st);
416 archive_entry_set_pathname(entry, *filename);
417 archive_write_header(a, entry);
418 fd = open(*filename, O_RDONLY);
419 len = read(fd, buff, sizeof(buff));
421 archive_write_data(a, buff, len);
422 len = read(fd, buff, sizeof(buff));
424 archive_entry_free(entry);
427 archive_write_finish(a);
430 int main(int argc, const char **argv)
435 write_archive(outname, argv);
440 Most functions return
442 (zero) on success, or one of several non-zero
443 error codes for errors.
444 Specific error codes include:
446 for operations that might succeed if retried,
448 for unusual conditions that do not prevent further operations, and
450 for serious errors that make remaining operations impossible.
454 .Fn archive_error_string
455 functions can be used to retrieve an appropriate error code and a
456 textual error message.
458 .Fn archive_write_new
459 returns a pointer to a newly-allocated
463 .Fn archive_write_data
464 returns a count of the number of bytes actually written.
465 On error, -1 is returned and the
468 .Fn archive_error_string
469 functions will return appropriate values.
470 Note that if the client-provided write callback function
471 returns a non-zero value, that error will be propagated back to the caller
472 through whatever API function resulted in that call, which
474 .Fn archive_write_header ,
475 .Fn archive_write_data ,
476 .Fn archive_write_close ,
478 .Fn archive_write_finish .
479 The client callback can call
480 .Fn archive_set_error
481 to provide values that can then be retrieved by
484 .Fn archive_error_string .
492 library first appeared in
498 library was written by
499 .An Tim Kientzle Aq kientzle@acm.org .
501 There are many peculiar bugs in historic tar implementations that may cause
502 certain programs to reject archives written by this library.
503 For example, several historic implementations calculated header checksums
504 incorrectly and will thus reject valid archives; GNU tar does not fully support
505 pax interchange format; some old tar implementations required specific
508 The default pax interchange format eliminates most of the historic
509 tar limitations and provides a generic key/value attribute facility
510 for vendor-defined extensions.
511 One oversight in POSIX is the failure to provide a standard attribute
512 for large device numbers.
517 for device numbers that exceed the range supported by the backwards-compatible
519 These keys are compatible with Joerg Schilling's
522 Other implementations may not recognize these keys and will thus be unable
523 to correctly restore device nodes with large device numbers from archives
524 created by this library.