1 .\" Copyright (c) 2003-2011 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
32 .Nd functions for creating archives
34 Streaming Archive Library (libarchive, -larchive)
38 These functions provide a complete API for creating streaming
40 The general process is to first create the
42 object, set any desired options, initialize the archive, append entries, then
43 close the archive and release all resources.
45 .Ss Create archive object
47 .Xr archive_write_new 3 .
49 To write an archive, you must first obtain an initialized
52 .Fn archive_write_new .
54 .Ss Enable filters and formats, configure block size and padding
56 .Xr archive_write_filter 3 ,
57 .Xr archive_write_format 3
59 .Xr archive_write_blocksize 3 .
61 You can then modify this object for the desired operations with the
63 .Fn archive_write_set_XXX
65 In particular, you will need to invoke appropriate
66 .Fn archive_write_add_XXX
68 .Fn archive_write_set_XXX
69 functions to enable the corresponding compression and format
74 .Xr archive_write_set_options 3 .
78 .Xr archive_write_open 3 .
80 Once you have prepared the
83 .Fn archive_write_open
84 to actually open the archive and prepare it for writing.
85 There are several variants of this function;
86 the most basic expects you to provide pointers to several
87 functions that can provide blocks of bytes from the archive.
88 There are convenience forms that allow you to
89 specify a filename, file descriptor,
91 object, or a block of memory from which to write the archive data.
95 .Xr archive_write_header 3
97 .Xr archive_write_data 3 .
99 Individual archive entries are written in a three-step
101 You first initialize a
102 .Tn struct archive_entry
103 structure with information about the new entry.
104 At a minimum, you should set the pathname of the
109 field, which specifies the type of object and
111 field, which specifies the size of the data portion of the object.
113 .Ss Release resources
115 .Xr archive_write_free 3 .
117 After all entries have been written, use the
118 .Fn archive_write_free
119 function to release all resources.
122 The following sketch illustrates basic usage of the library.
124 the callback functions are simply wrappers around the standard
130 .Bd -literal -offset indent
132 #define _FILE_OFFSET_BITS 64
134 #include <sys/stat.h>
136 #include <archive_entry.h>
147 myopen(struct archive *a, void *client_data)
149 struct mydata *mydata = client_data;
151 mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
155 return (ARCHIVE_FATAL);
159 mywrite(struct archive *a, void *client_data, const void *buff, size_t n)
161 struct mydata *mydata = client_data;
163 return (write(mydata->fd, buff, n));
167 myclose(struct archive *a, void *client_data)
169 struct mydata *mydata = client_data;
177 write_archive(const char *outname, const char **filename)
179 struct mydata *mydata = malloc(sizeof(struct mydata));
181 struct archive_entry *entry;
187 a = archive_write_new();
188 mydata->name = outname;
189 /* Set archive format and filter according to output file extension.
190 * If it fails, set default format. Platform depended function.
191 * See supported formats in archive_write_set_format_filter_by_ext.c */
192 if (archive_write_set_format_filter_by_ext(a, outname) != ARCHIVE_OK) {
193 archive_write_add_filter_gzip(a);
194 archive_write_set_format_ustar(a);
196 archive_write_open(a, mydata, myopen, mywrite, myclose);
198 stat(*filename, &st);
199 entry = archive_entry_new();
200 archive_entry_copy_stat(entry, &st);
201 archive_entry_set_pathname(entry, *filename);
202 archive_write_header(a, entry);
203 if ((fd = open(*filename, O_RDONLY)) != -1) {
204 len = read(fd, buff, sizeof(buff));
206 archive_write_data(a, buff, len);
207 len = read(fd, buff, sizeof(buff));
211 archive_entry_free(entry);
214 archive_write_free(a);
217 int main(int argc, const char **argv)
222 write_archive(outname, argv);
228 .Xr archive_write_set_options 3 ,
236 library first appeared in
242 library was written by
243 .An Tim Kientzle Aq kientzle@acm.org .
245 There are many peculiar bugs in historic tar implementations that may cause
246 certain programs to reject archives written by this library.
247 For example, several historic implementations calculated header checksums
248 incorrectly and will thus reject valid archives; GNU tar does not fully support
249 pax interchange format; some old tar implementations required specific
252 The default pax interchange format eliminates most of the historic
253 tar limitations and provides a generic key/value attribute facility
254 for vendor-defined extensions.
255 One oversight in POSIX is the failure to provide a standard attribute
256 for large device numbers.
261 for device numbers that exceed the range supported by the backwards-compatible
263 These keys are compatible with Joerg Schilling's
266 Other implementations may not recognize these keys and will thus be unable
267 to correctly restore device nodes with large device numbers from archives
268 created by this library.