Import libarchive and bsdtar. The default tar (/usr/bin/tar) can be choosen
[dragonfly.git] / contrib / libarchive / archive_write.3
1 .\" Copyright (c) 2003-2004 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.8 2004/11/05 05:26:30 kientzle Exp $
26 .\"
27 .Dd October 1, 2003
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_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_prepare ,
46 .Nm archive_write_header ,
47 .Nm archive_write_data ,
48 .Nm archive_write_close ,
49 .Nm archive_write_finish
50 .Nd functions for creating archives
51 .Sh SYNOPSIS
52 .In archive.h
53 .Ft struct archive *
54 .Fn archive_write_new "void"
55 .Ft int
56 .Fn archive_write_set_bytes_per_block "archive *" "int bytes_per_block"
57 .Ft int
58 .Fn archive_write_set_bytes_in_last_block "archive *" "int"
59 .Ft int
60 .Fn archive_write_set_compressor_gzip "struct archive *"
61 .Ft int
62 .Fn archive_write_set_compressor_bzip2 "struct archive *"
63 .Ft int
64 .Fn archive_write_set_format_cpio "struct archive *"
65 .Ft int
66 .Fn archive_write_set_format_pax "struct archive *"
67 .Ft int
68 .Fn archive_write_set_format_pax_restricted "struct archive *"
69 .Ft int
70 .Fn archive_write_set_format_shar "struct archive *"
71 .Ft int
72 .Fn archive_write_set_format_shar_binary "struct archive *"
73 .Ft int
74 .Fn archive_write_set_format_ustar "struct archive *"
75 .Ft int
76 .Fn archive_write_open "struct archive *" "void *client_data" "archive_write_archive_callback *" "archive_open_archive_callback *" "archive_close_archive_callback *"
77 .Ft int
78 .Fn archive_write_open_fd "struct archive *" "int fd"
79 .Ft int
80 .Fn archive_write_open_file "struct archive *" "const char *filename"
81 .Ft int
82 .Fn archive_write_header "struct archive *"
83 .Ft int
84 .Fn archive_write_data "struct archive *" "const void *" "size_t"
85 .Ft int
86 .Fn archive_write_close "struct archive *"
87 .Ft void
88 .Fn archive_write_finish "struct archive *"
89 .Sh DESCRIPTION
90 These functions provide a complete API for creating streaming
91 archive files.
92 The general process is to first create the
93 .Tn struct archive
94 object, set any desired options, initialize the archive, append entries, then
95 close the archive and release all resources.
96 The following summary describes the functions in approximately
97 the order they are ordinarily used:
98 .Bl -tag -width indent
99 .It Fn archive_write_new
100 Allocates and initializes a
101 .Tn struct archive
102 object suitable for writing a tar archive.
103 .It Fn archive_write_set_bytes_per_block
104 Sets the block size used for writing the archive data.
105 Every call to the write callback function, except possibly the last one, will
106 use this value for the length.
107 The third parameter is a boolean that specifies whether or not the final block
108 written will be padded to the full block size.
109 If it is zero, the last block will not be padded.
110 If it is non-zero, padding will be added both before and after compression.
111 The default is to use a block size of 10240 bytes and to pad the last block.
112 .It Fn archive_write_set_bytes_in_last_block
113 Sets the block size used for writing the last block.
114 If this value is zero, the last block will be padded to the same size
115 as the other blocks.
116 Otherwise, the final block will be padded to a multiple of this size.
117 In particular, setting it to 1 will cause the final block to not be padded.
118 For compressed output, any padding generated by this option
119 is applied only after the compression.
120 The uncompressed data is always unpadded.
121 The default is to pad the last block to the full block size (note that
122 .Fn archive_write_open_file
123 will set this based on the file type).
124 Unlike the other
125 .Dq set
126 functions, this function can be called after the archive is opened.
127 .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
128 Sets the format that will be used for the archive.
129 The library can write
130 POSIX octet-oriented cpio format archives,
131 POSIX-standard
132 .Dq pax interchange
133 format archives,
134 traditional
135 .Dq shar
136 archives,
137 enhanced
138 .Dq binary
139 shar archives that store a variety of file attributes and handle binary files,
140 and
141 POSIX-standard
142 .Dq ustar
143 archives.
144 The pax interchange format is a backwards-compatible tar format that
145 adds key/value attributes to each entry and supports arbitrary
146 filenames, linknames, uids, sizes, etc.
147 .Dq Restricted pax interchange format
148 is the library default; this is the same as pax format, but suppresses
149 the pax extended header for most normal files.
150 In most cases, this will result in ordinary ustar archives.
151 .It Fn archive_write_set_compression_gzip , Fn archive_write_set_compression_bzip2
152 The resulting archive will be compressed as specified.
153 Note that the compressed output is always properly blocked.
154 .It Fn archive_write_open
155 Freeze the settings, open the archive, and prepare for writing entries.
156 This is the most generic form of this function, which accepts
157 pointers to three callback functions which will be invoked by
158 the compression layer to write the constructed archive.
159 In order to support external compression programs, the compression
160 is permitted to fork and invoke the callbacks from a separate process.
161 In particular, clients should not assume that they can communicate
162 between the callbacks and the mainline code using shared variables.
163 (The standard gzip, bzip2, and "none" compression methods do not fork.)
164 .It Fn archive_write_open_fd
165 A convenience form of
166 .Fn archive_write_open
167 that accepts a file descriptor.
168 .It Fn archive_write_open_file
169 A convenience form of
170 .Fn archive_write_open
171 that accepts a filename.
172 A NULL argument indicates that the output should be written to standard output;
173 an argument of
174 .Dq -
175 will open a file with that name.
176 If you have not invoked
177 .Fn archive_write_set_bytes_in_last_block ,
178 then
179 .Fn archive_write_open_file
180 will adjust the last-block padding depending on the file:
181 it will enable padding when writing to standard output or
182 to a character or block device node, it will disable padding otherwise.
183 You can override this by manually invoking
184 .Fn archive_write_set_bytes_in_last_block
185 either before or after calling
186 .Fn archive_write_open .
187 .It Fn archive_write_header
188 Build and write a header using the data in the provided
189 .Tn struct archive_entry
190 structure.
191 .It Fn archive_write_data
192 Write data corresponding to the header just written.
193 Returns number of bytes written or -1 on error.
194 .It Fn archive_write_close
195 Complete the archive and invoke the close callback.
196 .It Fn archive_write_finish
197 Invokes
198 .Fn archive_write_close
199 if it wasn't invoked manually, then release all resources.
200 .El
201 .Pp
202 The callback functions are defined as follows:
203 .Bl -item -offset indent
204 .It
205 .Ft typedef ssize_t
206 .Fn archive_write_archive_callback "struct archive *" "void *client_data" "void *buffer" "size_t length"
207 .It
208 .Ft typedef int
209 .Fn archive_open_archive_callback "struct archive *" "void *client_data"
210 .It
211 .Ft typedef int
212 .Fn archive_close_archive_callback "struct archive *" "void *client_data"
213 .El
214 For correct blocking, each call to the write callback function
215 should translate into a single
216 .Xr write 2
217 system call.
218 This is especially critical when writing tar archives to tape drives.
219 .Pp
220 More information about tar archive formats and blocking can be found
221 in the
222 .Xr tar 5
223 manual page.
224 .Pp
225 More information about the
226 .Va struct archive
227 object and the overall design of the library can be found in the
228 .Xr libarchive 3
229 overview.
230 .Sh IMPLEMENTATION
231 Compression support is built-in to libarchive, which uses zlib and bzlib
232 to handle gzip and bzip2 compression, respectively.
233 .Sh EXAMPLE
234 The following sketch illustrates basic usage of the library.
235 In this example,
236 the callback functions are simply wrappers around the standard
237 .Xr open 2 ,
238 .Xr write 2 ,
239 and
240 .Xr close 2
241 system calls.
242 .Bd -literal -offset indent
243 void
244 write_archive(const char **filename)
245 {
246   struct mydata *mydata = malloc(sizeof(struct mydata));
247   struct archive *a;
248   struct archive_entry *entry;
249   struct stat st;
250   char buff[8192];
251   int len;
252
253   a = archive_write_new();
254   mydata->name = name;
255   archive_write_set_compression_gzip(a);
256   archive_write_set_format_ustar(a);
257   archive_write_open(a, mydata, myopen, mywrite, myclose);
258   while (*filename) {
259     stat(*filename, &st);
260     entry = archive_entry_new();
261     archive_entry_copy_stat(entry, &st);
262     archive_entry_set_pathname(entry, *filename);
263     archive_write_header(a, entry);
264     fd = open(*filename, O_RDONLY);
265     len = read(fd, buff, sizeof(buff));
266     while ( len >= 0 ) {
267         archive_write_data(a, buff, len);
268         len = read(fd, buff, sizeof(buff));
269     }
270     archive_entry_free(entry);
271     filename++;
272   }
273   archive_write_finish(a);
274 }
275
276 int
277 myopen(struct archive *a, void *client_data)
278 {
279   struct mydata *mydata = client_data;
280
281   mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
282   return (mydata->fd >= 0);
283 }
284
285 ssize_t
286 mywrite(struct archive *a, void *client_data, void *buff, size_t n)
287 {
288   struct mydata *mydata = client_data;
289
290   return (write(mydata->fd, buff, n));
291 }
292
293 int
294 myclose(struct archive *a, void *client_data)
295 {
296   struct mydata *mydata = client_data;
297
298   if (mydata->fd > 0)
299     close(mydata->fd);
300   return (0);
301 }
302 .Ed
303 .Sh RETURN VALUES
304 Most functions return zero on success, non-zero on error.
305 The
306 .Fn archive_errno
307 and
308 .Fn archive_error_string
309 functions can be used to retrieve an appropriate error code and a
310 textual error message.
311 .Pp
312 .Fn archive_write_new
313 returns a pointer to a newly-allocated
314 .Tn struct archive
315 object.
316 .Pp
317 .Fn archive_write_data
318 returns a count of the number of bytes actually written.
319 On error, -1 is returned and the
320 .Fn archive_errno
321 and
322 .Fn archive_error_string
323 functions will return appropriate values.
324 Note that if the client-provided write callback function
325 returns a non-zero value, that error will be propagated back to the caller
326 through whatever API function resulted in that call, which
327 may include
328 .Fn archive_write_header ,
329 .Fn archive_write_data ,
330 or
331 .Fn archive_write_close .
332 The client callback can call
333 .Fn archive_set_error
334 to provide values that can then be retrieved by
335 .Fn archive_errno
336 and
337 .Fn archive_error_string .
338 .Sh SEE ALSO
339 .Xr tar 1 ,
340 .Xr libarchive 3 ,
341 .Xr tar 5
342 .Sh HISTORY
343 The
344 .Nm libarchive
345 library first appeared in
346 .Fx 5.3 .
347 .Sh AUTHORS
348 .An -nosplit
349 The
350 .Nm libarchive
351 library was written by
352 .An Tim Kientzle Aq kientzle@acm.org .
353 .Sh BUGS
354 There are many peculiar bugs in historic tar implementations that may cause
355 certain programs to reject archives written by this library.
356 For example, several historic implementations calculated header checksums
357 incorrectly and will thus reject valid archives; GNU tar does not fully support
358 pax interchange format; some old tar implementations required specific
359 field terminations.
360 .Pp
361 The default pax interchange format eliminates most of the historic
362 tar limitations and provides a generic key/value attribute facility
363 for vendor-defined extensions.
364 One oversight in POSIX is the failure to provide a standard attribute
365 for large device numbers.
366 This library uses
367 .Dq SCHILY.devminor
368 and
369 .Dq SCHILY.devmajor
370 for device numbers that exceed the range supported by the backwards-compatible
371 ustar header.
372 These keys are compatible with Joerg Schilling's
373 .Nm star
374 archiver.
375 Other implementations may not recognize these keys and will thus be unable
376 to correctly restore large device numbers archived by this library.