1 .\" Copyright (c) 2003-2005 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.11 2005/02/13 22:25:11 ru 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_open_archive_callback *" "archive_write_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 was not invoked manually, then release all resources.
201 More information about the
203 object and the overall design of the library can be found in the
207 Compression support is built-in to libarchive, which uses zlib and bzlib
208 to handle gzip and bzip2 compression, respectively.
210 To use this library, you will need to define and register
211 callback functions that will be invoked to write data to the
213 These functions are registered by calling
214 .Fn archive_write_open :
215 .Bl -item -offset indent
218 .Fn archive_open_archive_callback "struct archive *" "void *client_data"
221 The open callback is invoked by
222 .Fn archive_write_open .
225 if the underlying file or data source is successfully
227 If the open fails, it should call
228 .Fn archive_set_error
229 to register an error code and message and return
231 .Bl -item -offset indent
234 .Fn archive_write_archive_callback "struct archive *" "void *client_data" "void *buffer" "size_t length"
237 The write callback is invoked whenever the library
238 needs to write raw bytes to the archive.
239 For correct blocking, each call to the write callback function
240 should translate into a single
243 This is especially critical when writing archives to tape drives.
244 On success, the write callback should return the
245 number of bytes actually written.
246 On error, the callback should invoke
247 .Fn archive_set_error
248 to register an error code and message and return -1.
249 .Bl -item -offset indent
252 .Fn archive_close_archive_callback "struct archive *" "void *client_data"
255 The close callback is invoked by archive_close when
256 the archive processing is complete.
257 The callback should return
260 On failure, the callback should invoke
261 .Fn archive_set_error
262 to register an error code and message and
266 The following sketch illustrates basic usage of the library.
268 the callback functions are simply wrappers around the standard
274 .Bd -literal -offset indent
276 write_archive(const char **filename)
278 struct mydata *mydata = malloc(sizeof(struct mydata));
280 struct archive_entry *entry;
285 a = archive_write_new();
287 archive_write_set_compression_gzip(a);
288 archive_write_set_format_ustar(a);
289 archive_write_open(a, mydata, myopen, mywrite, myclose);
291 stat(*filename, &st);
292 entry = archive_entry_new();
293 archive_entry_copy_stat(entry, &st);
294 archive_entry_set_pathname(entry, *filename);
295 archive_write_header(a, entry);
296 fd = open(*filename, O_RDONLY);
297 len = read(fd, buff, sizeof(buff));
299 archive_write_data(a, buff, len);
300 len = read(fd, buff, sizeof(buff));
302 archive_entry_free(entry);
305 archive_write_finish(a);
309 myopen(struct archive *a, void *client_data)
311 struct mydata *mydata = client_data;
313 mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
314 return (mydata->fd >= 0);
318 mywrite(struct archive *a, void *client_data, void *buff, size_t n)
320 struct mydata *mydata = client_data;
322 return (write(mydata->fd, buff, n));
326 myclose(struct archive *a, void *client_data)
328 struct mydata *mydata = client_data;
336 Most functions return zero on success, non-zero on error.
340 .Fn archive_error_string
341 functions can be used to retrieve an appropriate error code and a
342 textual error message.
344 .Fn archive_write_new
345 returns a pointer to a newly-allocated
349 .Fn archive_write_data
350 returns a count of the number of bytes actually written.
351 On error, -1 is returned and the
354 .Fn archive_error_string
355 functions will return appropriate values.
356 Note that if the client-provided write callback function
357 returns a non-zero value, that error will be propagated back to the caller
358 through whatever API function resulted in that call, which
360 .Fn archive_write_header ,
361 .Fn archive_write_data ,
363 .Fn archive_write_close .
364 The client callback can call
365 .Fn archive_set_error
366 to provide values that can then be retrieved by
369 .Fn archive_error_string .
377 library first appeared in
383 library was written by
384 .An Tim Kientzle Aq kientzle@acm.org .
386 There are many peculiar bugs in historic tar implementations that may cause
387 certain programs to reject archives written by this library.
388 For example, several historic implementations calculated header checksums
389 incorrectly and will thus reject valid archives; GNU tar does not fully support
390 pax interchange format; some old tar implementations required specific
393 The default pax interchange format eliminates most of the historic
394 tar limitations and provides a generic key/value attribute facility
395 for vendor-defined extensions.
396 One oversight in POSIX is the failure to provide a standard attribute
397 for large device numbers.
402 for device numbers that exceed the range supported by the backwards-compatible
404 These keys are compatible with Joerg Schilling's
407 Other implementations may not recognize these keys and will thus be unable
408 to correctly restore large device numbers archived by this library.