1 .\" Copyright (c) 2003-2004 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.8 2004/11/05 05:26:30 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_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
54 .Fn archive_write_new "void"
56 .Fn archive_write_set_bytes_per_block "archive *" "int bytes_per_block"
58 .Fn archive_write_set_bytes_in_last_block "archive *" "int"
60 .Fn archive_write_set_compressor_gzip "struct archive *"
62 .Fn archive_write_set_compressor_bzip2 "struct archive *"
64 .Fn archive_write_set_format_cpio "struct archive *"
66 .Fn archive_write_set_format_pax "struct archive *"
68 .Fn archive_write_set_format_pax_restricted "struct archive *"
70 .Fn archive_write_set_format_shar "struct archive *"
72 .Fn archive_write_set_format_shar_binary "struct archive *"
74 .Fn archive_write_set_format_ustar "struct archive *"
76 .Fn archive_write_open "struct archive *" "void *client_data" "archive_write_archive_callback *" "archive_open_archive_callback *" "archive_close_archive_callback *"
78 .Fn archive_write_open_fd "struct archive *" "int fd"
80 .Fn archive_write_open_file "struct archive *" "const char *filename"
82 .Fn archive_write_header "struct archive *"
84 .Fn archive_write_data "struct archive *" "const void *" "size_t"
86 .Fn archive_write_close "struct archive *"
88 .Fn archive_write_finish "struct archive *"
90 These functions provide a complete API for creating streaming
92 The general process is to first create the
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
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
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).
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,
139 shar archives that store a variety of file attributes and handle binary files,
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;
175 will open a file with that name.
176 If you have not invoked
177 .Fn archive_write_set_bytes_in_last_block ,
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
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
198 .Fn archive_write_close
199 if it wasn't invoked manually, then release all resources.
202 The callback functions are defined as follows:
203 .Bl -item -offset indent
206 .Fn archive_write_archive_callback "struct archive *" "void *client_data" "void *buffer" "size_t length"
209 .Fn archive_open_archive_callback "struct archive *" "void *client_data"
212 .Fn archive_close_archive_callback "struct archive *" "void *client_data"
214 For correct blocking, each call to the write callback function
215 should translate into a single
218 This is especially critical when writing tar archives to tape drives.
220 More information about tar archive formats and blocking can be found
225 More information about the
227 object and the overall design of the library can be found in the
231 Compression support is built-in to libarchive, which uses zlib and bzlib
232 to handle gzip and bzip2 compression, respectively.
234 The following sketch illustrates basic usage of the library.
236 the callback functions are simply wrappers around the standard
242 .Bd -literal -offset indent
244 write_archive(const char **filename)
246 struct mydata *mydata = malloc(sizeof(struct mydata));
248 struct archive_entry *entry;
253 a = archive_write_new();
255 archive_write_set_compression_gzip(a);
256 archive_write_set_format_ustar(a);
257 archive_write_open(a, mydata, myopen, mywrite, myclose);
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));
267 archive_write_data(a, buff, len);
268 len = read(fd, buff, sizeof(buff));
270 archive_entry_free(entry);
273 archive_write_finish(a);
277 myopen(struct archive *a, void *client_data)
279 struct mydata *mydata = client_data;
281 mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
282 return (mydata->fd >= 0);
286 mywrite(struct archive *a, void *client_data, void *buff, size_t n)
288 struct mydata *mydata = client_data;
290 return (write(mydata->fd, buff, n));
294 myclose(struct archive *a, void *client_data)
296 struct mydata *mydata = client_data;
304 Most functions return zero on success, non-zero on error.
308 .Fn archive_error_string
309 functions can be used to retrieve an appropriate error code and a
310 textual error message.
312 .Fn archive_write_new
313 returns a pointer to a newly-allocated
317 .Fn archive_write_data
318 returns a count of the number of bytes actually written.
319 On error, -1 is returned and the
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
328 .Fn archive_write_header ,
329 .Fn archive_write_data ,
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
337 .Fn archive_error_string .
345 library first appeared in
351 library was written by
352 .An Tim Kientzle Aq kientzle@acm.org .
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
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.
370 for device numbers that exceed the range supported by the backwards-compatible
372 These keys are compatible with Joerg Schilling's
375 Other implementations may not recognize these keys and will thus be unable
376 to correctly restore large device numbers archived by this library.