Import libarchive-2.5.5.
[dragonfly.git] / contrib / libarchive-2 / libarchive / archive_write.3
blob14003f43c3678112738d94ad8b7c4b84f732068c
1 .\" Copyright (c) 2003-2007 Tim Kientzle
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
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.
12 .\"
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
23 .\" SUCH DAMAGE.
24 .\"
25 .\" $FreeBSD: src/lib/libarchive/archive_write.3,v 1.24 2008/05/26 17:00:23 kientzle Exp $
26 .\"
27 .Dd May 11, 2008
28 .Dt archive_write 3
29 .Os
30 .Sh NAME
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_open ,
47 .Nm archive_write_open_fd ,
48 .Nm archive_write_open_FILE ,
49 .Nm archive_write_open_filename ,
50 .Nm archive_write_open_memory ,
51 .Nm archive_write_header ,
52 .Nm archive_write_data ,
53 .Nm archive_write_finish_entry ,
54 .Nm archive_write_close ,
55 .Nm archive_write_finish
56 .Nd functions for creating archives
57 .Sh SYNOPSIS
58 .In archive.h
59 .Ft struct archive *
60 .Fn archive_write_new "void"
61 .Ft int
62 .Fn archive_write_get_bytes_per_block "struct archive *"
63 .Ft int
64 .Fn archive_write_set_bytes_per_block "struct archive *" "int bytes_per_block"
65 .Ft int
66 .Fn archive_write_set_bytes_in_last_block "struct archive *" "int"
67 .Ft int
68 .Fn archive_write_set_compression_bzip2 "struct archive *"
69 .Ft int
70 .Fn archive_write_set_compression_compress "struct archive *"
71 .Ft int
72 .Fn archive_write_set_compression_gzip "struct archive *"
73 .Ft int
74 .Fn archive_write_set_compression_none "struct archive *"
75 .Ft int
76 .Fo archive_write_set_compression_program
77 .Fa "struct archive *"
78 .Fa "const char * cmd"
79 .Fc
80 .Ft int
81 .Fn archive_write_set_format_cpio "struct archive *"
82 .Ft int
83 .Fn archive_write_set_format_pax "struct archive *"
84 .Ft int
85 .Fn archive_write_set_format_pax_restricted "struct archive *"
86 .Ft int
87 .Fn archive_write_set_format_shar "struct archive *"
88 .Ft int
89 .Fn archive_write_set_format_shar_binary "struct archive *"
90 .Ft int
91 .Fn archive_write_set_format_ustar "struct archive *"
92 .Ft int
93 .Fo archive_write_open
94 .Fa "struct archive *"
95 .Fa "void *client_data"
96 .Fa "archive_open_callback *"
97 .Fa "archive_write_callback *"
98 .Fa "archive_close_callback *"
99 .Fc
100 .Ft int
101 .Fn archive_write_open_fd "struct archive *" "int fd"
102 .Ft int
103 .Fn archive_write_open_FILE "struct archive *" "FILE *file"
104 .Ft int
105 .Fn archive_write_open_filename "struct archive *" "const char *filename"
106 .Ft int
107 .Fo archive_write_open_memory
108 .Fa "struct archive *"
109 .Fa "void *buffer"
110 .Fa "size_t bufferSize"
111 .Fa "size_t *outUsed"
113 .Ft int
114 .Fn archive_write_header "struct archive *" "struct archive_entry *"
115 .Ft ssize_t
116 .Fn archive_write_data "struct archive *" "const void *" "size_t"
117 .Ft int
118 .Fn archive_write_finish_entry "struct archive *"
119 .Ft int
120 .Fn archive_write_close "struct archive *"
121 .Ft int
122 .Fn archive_write_finish "struct archive *"
123 .Sh DESCRIPTION
124 These functions provide a complete API for creating streaming
125 archive files.
126 The general process is to first create the
127 .Tn struct archive
128 object, set any desired options, initialize the archive, append entries, then
129 close the archive and release all resources.
130 The following summary describes the functions in approximately
131 the order they are ordinarily used:
132 .Bl -tag -width indent
133 .It Fn archive_write_new
134 Allocates and initializes a
135 .Tn struct archive
136 object suitable for writing a tar archive.
137 .It Fn archive_write_set_bytes_per_block
138 Sets the block size used for writing the archive data.
139 Every call to the write callback function, except possibly the last one, will
140 use this value for the length.
141 The third parameter is a boolean that specifies whether or not the final block
142 written will be padded to the full block size.
143 If it is zero, the last block will not be padded.
144 If it is non-zero, padding will be added both before and after compression.
145 The default is to use a block size of 10240 bytes and to pad the last block.
146 Note that a block size of zero will suppress internal blocking
147 and cause writes to be sent directly to the write callback as they occur.
148 .It Fn archive_write_get_bytes_per_block
149 Retrieve the block size to be used for writing.
150 A value of -1 here indicates that the library should use default values.
151 A value of zero indicates that internal blocking is suppressed.
152 .It Fn archive_write_set_bytes_in_last_block
153 Sets the block size used for writing the last block.
154 If this value is zero, the last block will be padded to the same size
155 as the other blocks.
156 Otherwise, the final block will be padded to a multiple of this size.
157 In particular, setting it to 1 will cause the final block to not be padded.
158 For compressed output, any padding generated by this option
159 is applied only after the compression.
160 The uncompressed data is always unpadded.
161 The default is to pad the last block to the full block size (note that
162 .Fn archive_write_open_filename
163 will set this based on the file type).
164 Unlike the other
165 .Dq set
166 functions, this function can be called after the archive is opened.
167 .It Fn archive_write_get_bytes_in_last_block
168 Retrieve the currently-set value for last block size.
169 A value of -1 here indicates that the library should use default values.
170 .It Xo
171 .Fn archive_write_set_format_cpio ,
172 .Fn archive_write_set_format_pax ,
173 .Fn archive_write_set_format_pax_restricted ,
174 .Fn archive_write_set_format_shar ,
175 .Fn archive_write_set_format_shar_binary ,
176 .Fn archive_write_set_format_ustar
178 Sets the format that will be used for the archive.
179 The library can write
180 POSIX octet-oriented cpio format archives,
181 POSIX-standard
182 .Dq pax interchange
183 format archives,
184 traditional
185 .Dq shar
186 archives,
187 enhanced
188 .Dq binary
189 shar archives that store a variety of file attributes and handle binary files,
191 POSIX-standard
192 .Dq ustar
193 archives.
194 The pax interchange format is a backwards-compatible tar format that
195 adds key/value attributes to each entry and supports arbitrary
196 filenames, linknames, uids, sizes, etc.
197 .Dq Restricted pax interchange format
198 is the library default; this is the same as pax format, but suppresses
199 the pax extended header for most normal files.
200 In most cases, this will result in ordinary ustar archives.
201 .It Xo
202 .Fn archive_write_set_compression_bzip2 ,
203 .Fn archive_write_set_compression_compress ,
204 .Fn archive_write_set_compression_gzip ,
205 .Fn archive_write_set_compression_none
207 The resulting archive will be compressed as specified.
208 Note that the compressed output is always properly blocked.
209 .It Fn archive_write_set_compression_program
210 The archive will be fed into the specified compression program.
211 The output of that program is blocked and written to the client
212 write callbacks.
213 .It Fn archive_write_open
214 Freeze the settings, open the archive, and prepare for writing entries.
215 This is the most generic form of this function, which accepts
216 pointers to three callback functions which will be invoked by
217 the compression layer to write the constructed archive.
218 .It Fn archive_write_open_fd
219 A convenience form of
220 .Fn archive_write_open
221 that accepts a file descriptor.
223 .Fn archive_write_open_fd
224 function is safe for use with tape drives or other
225 block-oriented devices.
226 .It Fn archive_write_open_FILE
227 A convenience form of
228 .Fn archive_write_open
229 that accepts a
230 .Ft "FILE *"
231 pointer.
232 Note that
233 .Fn archive_write_open_FILE
234 is not safe for writing to tape drives or other devices
235 that require correct blocking.
236 .It Fn archive_write_open_file
237 A deprecated synonym for
238 .Fn archive_write_open_filename .
239 .It Fn archive_write_open_filename
240 A convenience form of
241 .Fn archive_write_open
242 that accepts a filename.
243 A NULL argument indicates that the output should be written to standard output;
244 an argument of
245 .Dq -
246 will open a file with that name.
247 If you have not invoked
248 .Fn archive_write_set_bytes_in_last_block ,
249 then
250 .Fn archive_write_open_filename
251 will adjust the last-block padding depending on the file:
252 it will enable padding when writing to standard output or
253 to a character or block device node, it will disable padding otherwise.
254 You can override this by manually invoking
255 .Fn archive_write_set_bytes_in_last_block
256 before calling
257 .Fn archive_write_open .
259 .Fn archive_write_open_filename
260 function is safe for use with tape drives or other
261 block-oriented devices.
262 .It Fn archive_write_open_memory
263 A convenience form of
264 .Fn archive_write_open
265 that accepts a pointer to a block of memory that will receive
266 the archive.
267 The final
268 .Ft "size_t *"
269 argument points to a variable that will be updated
270 after each write to reflect how much of the buffer
271 is currently in use.
272 You should be careful to ensure that this variable
273 remains allocated until after the archive is
274 closed.
275 .It Fn archive_write_header
276 Build and write a header using the data in the provided
277 .Tn struct archive_entry
278 structure.
280 .Xr archive_entry 3
281 for information on creating and populating
282 .Tn struct archive_entry
283 objects.
284 .It Fn archive_write_data
285 Write data corresponding to the header just written.
286 Returns number of bytes written or -1 on error.
287 .It Fn archive_write_finish_entry
288 Close out the entry just written.
289 In particular, this writes out the final padding required by some formats.
290 Ordinarily, clients never need to call this, as it
291 is called automatically by
292 .Fn archive_write_next_header
294 .Fn archive_write_close
295 as needed.
296 .It Fn archive_write_close
297 Complete the archive and invoke the close callback.
298 .It Fn archive_write_finish
299 Invokes
300 .Fn archive_write_close
301 if it was not invoked manually, then releases all resources.
302 Note that this function was declared to return
303 .Ft void
304 in libarchive 1.x, which made it impossible to detect errors when
305 .Fn archive_write_close
306 was invoked implicitly from this function.
307 This is corrected beginning with libarchive 2.0.
309 More information about the
310 .Va struct archive
311 object and the overall design of the library can be found in the
312 .Xr libarchive 3
313 overview.
314 .Sh IMPLEMENTATION
315 Compression support is built-in to libarchive, which uses zlib and bzlib
316 to handle gzip and bzip2 compression, respectively.
317 .Sh CLIENT CALLBACKS
318 To use this library, you will need to define and register
319 callback functions that will be invoked to write data to the
320 resulting archive.
321 These functions are registered by calling
322 .Fn archive_write_open :
323 .Bl -item -offset indent
325 .Ft typedef int
326 .Fn archive_open_callback "struct archive *" "void *client_data"
329 The open callback is invoked by
330 .Fn archive_write_open .
331 It should return
332 .Cm ARCHIVE_OK
333 if the underlying file or data source is successfully
334 opened.
335 If the open fails, it should call
336 .Fn archive_set_error
337 to register an error code and message and return
338 .Cm ARCHIVE_FATAL .
339 .Bl -item -offset indent
341 .Ft typedef ssize_t
342 .Fo archive_write_callback
343 .Fa "struct archive *"
344 .Fa "void *client_data"
345 .Fa "void *buffer"
346 .Fa "size_t length"
350 The write callback is invoked whenever the library
351 needs to write raw bytes to the archive.
352 For correct blocking, each call to the write callback function
353 should translate into a single
354 .Xr write 2
355 system call.
356 This is especially critical when writing archives to tape drives.
357 On success, the write callback should return the
358 number of bytes actually written.
359 On error, the callback should invoke
360 .Fn archive_set_error
361 to register an error code and message and return -1.
362 .Bl -item -offset indent
364 .Ft typedef int
365 .Fn archive_close_callback "struct archive *" "void *client_data"
368 The close callback is invoked by archive_close when
369 the archive processing is complete.
370 The callback should return
371 .Cm ARCHIVE_OK
372 on success.
373 On failure, the callback should invoke
374 .Fn archive_set_error
375 to register an error code and message and
376 return
377 .Cm ARCHIVE_FATAL.
378 .Sh EXAMPLE
379 The following sketch illustrates basic usage of the library.
380 In this example,
381 the callback functions are simply wrappers around the standard
382 .Xr open 2 ,
383 .Xr write 2 ,
385 .Xr close 2
386 system calls.
387 .Bd -literal -offset indent
388 #include <sys/stat.h>
389 #include <archive.h>
390 #include <archive_entry.h>
391 #include <fcntl.h>
392 #include <stdlib.h>
393 #include <unistd.h>
395 struct mydata {
396         const char *name;
397         int fd;
401 myopen(struct archive *a, void *client_data)
403   struct mydata *mydata = client_data;
405   mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
406   if (mydata->fd >= 0)
407     return (ARCHIVE_OK);
408   else
409     return (ARCHIVE_FATAL);
412 ssize_t
413 mywrite(struct archive *a, void *client_data, void *buff, size_t n)
415   struct mydata *mydata = client_data;
417   return (write(mydata->fd, buff, n));
421 myclose(struct archive *a, void *client_data)
423   struct mydata *mydata = client_data;
425   if (mydata->fd > 0)
426     close(mydata->fd);
427   return (0);
430 void
431 write_archive(const char *outname, const char **filename)
433   struct mydata *mydata = malloc(sizeof(struct mydata));
434   struct archive *a;
435   struct archive_entry *entry;
436   struct stat st;
437   char buff[8192];
438   int len;
439   int fd;
441   a = archive_write_new();
442   mydata->name = outname;
443   archive_write_set_compression_gzip(a);
444   archive_write_set_format_ustar(a);
445   archive_write_open(a, mydata, myopen, mywrite, myclose);
446   while (*filename) {
447     stat(*filename, &st);
448     entry = archive_entry_new();
449     archive_entry_copy_stat(entry, &st);
450     archive_entry_set_pathname(entry, *filename);
451     archive_write_header(a, entry);
452     fd = open(*filename, O_RDONLY);
453     len = read(fd, buff, sizeof(buff));
454     while ( len > 0 ) {
455         archive_write_data(a, buff, len);
456         len = read(fd, buff, sizeof(buff));
457     }
458     archive_entry_free(entry);
459     filename++;
460   }
461   archive_write_finish(a);
464 int main(int argc, const char **argv)
466         const char *outname;
467         argv++;
468         outname = argv++;
469         write_archive(outname, argv);
470         return 0;
473 .Sh RETURN VALUES
474 Most functions return
475 .Cm ARCHIVE_OK
476 (zero) on success, or one of several non-zero
477 error codes for errors.
478 Specific error codes include:
479 .Cm ARCHIVE_RETRY
480 for operations that might succeed if retried,
481 .Cm ARCHIVE_WARN
482 for unusual conditions that do not prevent further operations, and
483 .Cm ARCHIVE_FATAL
484 for serious errors that make remaining operations impossible.
486 .Fn archive_errno
488 .Fn archive_error_string
489 functions can be used to retrieve an appropriate error code and a
490 textual error message.
492 .Fn archive_write_new
493 returns a pointer to a newly-allocated
494 .Tn struct archive
495 object.
497 .Fn archive_write_data
498 returns a count of the number of bytes actually written.
499 On error, -1 is returned and the
500 .Fn archive_errno
502 .Fn archive_error_string
503 functions will return appropriate values.
504 Note that if the client-provided write callback function
505 returns a non-zero value, that error will be propagated back to the caller
506 through whatever API function resulted in that call, which
507 may include
508 .Fn archive_write_header ,
509 .Fn archive_write_data ,
510 .Fn archive_write_close ,
512 .Fn archive_write_finish .
513 The client callback can call
514 .Fn archive_set_error
515 to provide values that can then be retrieved by
516 .Fn archive_errno
518 .Fn archive_error_string .
519 .Sh SEE ALSO
520 .Xr tar 1 ,
521 .Xr libarchive 3 ,
522 .Xr tar 5
523 .Sh HISTORY
525 .Nm libarchive
526 library first appeared in
527 .Fx 5.3 .
528 .Sh AUTHORS
529 .An -nosplit
531 .Nm libarchive
532 library was written by
533 .An Tim Kientzle Aq kientzle@acm.org .
534 .Sh BUGS
535 There are many peculiar bugs in historic tar implementations that may cause
536 certain programs to reject archives written by this library.
537 For example, several historic implementations calculated header checksums
538 incorrectly and will thus reject valid archives; GNU tar does not fully support
539 pax interchange format; some old tar implementations required specific
540 field terminations.
542 The default pax interchange format eliminates most of the historic
543 tar limitations and provides a generic key/value attribute facility
544 for vendor-defined extensions.
545 One oversight in POSIX is the failure to provide a standard attribute
546 for large device numbers.
547 This library uses
548 .Dq SCHILY.devminor
550 .Dq SCHILY.devmajor
551 for device numbers that exceed the range supported by the backwards-compatible
552 ustar header.
553 These keys are compatible with Joerg Schilling's
554 .Nm star
555 archiver.
556 Other implementations may not recognize these keys and will thus be unable
557 to correctly restore device nodes with large device numbers from archives
558 created by this library.