1ARCHIVE_WRITE(3) BSD Library Functions Manual ARCHIVE_WRITE(3)
2
4 archive_write — functions for creating archives
5
7 Streaming Archive Library (libarchive, -larchive)
8
10 #include <archive.h>
11
13 These functions provide a complete API for creating streaming archive
14 files. The general process is to first create the struct archive object,
15 set any desired options, initialize the archive, append entries, then
16 close the archive and release all resources.
17 Create archive object
19 See archive_write_new(3).
20 To write an archive, you must first obtain an initialized struct archive
22 object from archive_write_new().
23 Enable filters and formats, configure block size and padding
25 See archive_write_filter(3), archive_write_format(3) and
26 archive_write_blocksize(3).
27 You can then modify this object for the desired operations with the vari‐
29 ous archive_write_set_XXX() functions. In particular, you will need to
30 invoke appropriate archive_write_add_XXX() and archive_write_set_XXX()
31 functions to enable the corresponding compression and format support.
32 Set options
34 See archive_write_set_options(3).
35 Open archive
37 See archive_write_open(3).
38 Once you have prepared the struct archive object, you call
40 archive_write_open() to actually open the archive and prepare it for
41 writing. There are several variants of this function; the most basic
42 expects you to provide pointers to several functions that can provide
43 blocks of bytes from the archive. There are convenience forms that allow
44 you to specify a filename, file descriptor, FILE * object, or a block of
45 memory from which to write the archive data.
46 Produce archive
48 See archive_write_header(3) and archive_write_data(3).
49 Individual archive entries are written in a three-step process: You first
51 initialize a struct archive_entry structure with information about the
52 new entry. At a minimum, you should set the pathname of the entry and
53 provide a struct stat with a valid st_mode field, which specifies the
54 type of object and st_size field, which specifies the size of the data
55 portion of the object.
56 Release resources
58 See archive_write_free(3).
59 After all entries have been written, use the archive_write_free() func‐
61 tion to release all resources.
62
64 The following sketch illustrates basic usage of the library. In this
65 example, the callback functions are simply wrappers around the standard
66 open(2), write(2), and close(2) system calls.
67 #ifdef __linux__
69 #define _FILE_OFFSET_BITS 64
70 #endif
71 #include <sys/stat.h>
72 #include <archive.h>
73 #include <archive_entry.h>
74 #include <fcntl.h>
75 #include <stdlib.h>
76 #include <unistd.h>
77 struct mydata {
79 const char *name;
80 int fd;
81 };
82 int
84 myopen(struct archive *a, void *client_data)
85 {
86 struct mydata *mydata = client_data;
87 mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
89 if (mydata->fd >= 0)
90 return (ARCHIVE_OK);
91 else
92 return (ARCHIVE_FATAL);
93 }
94 la_ssize_t
96 mywrite(struct archive *a, void *client_data, const void *buff, size_t n)
97 {
98 struct mydata *mydata = client_data;
99 return (write(mydata->fd, buff, n));
101 }
102 int
104 myclose(struct archive *a, void *client_data)
105 {
106 struct mydata *mydata = client_data;
107 if (mydata->fd > 0)
109 close(mydata->fd);
110 return (0);
111 }
112 void
114 write_archive(const char *outname, const char **filename)
115 {
116 struct mydata *mydata = malloc(sizeof(struct mydata));
117 struct archive *a;
118 struct archive_entry *entry;
119 struct stat st;
120 char buff[8192];
121 int len;
122 int fd;
123 a = archive_write_new();
125 mydata->name = outname;
126 /* Set archive format and filter according to output file extension.
127 * If it fails, set default format. Platform depended function.
128 * See supported formats in archive_write_set_format_filter_by_ext.c */
129 if (archive_write_set_format_filter_by_ext(a, outname) != ARCHIVE_OK) {
130 archive_write_add_filter_gzip(a);
131 archive_write_set_format_ustar(a);
132 }
133 archive_write_open(a, mydata, myopen, mywrite, myclose);
134 while (*filename) {
135 stat(*filename, &st);
136 entry = archive_entry_new();
137 archive_entry_copy_stat(entry, &st);
138 archive_entry_set_pathname(entry, *filename);
139 archive_write_header(a, entry);
140 if ((fd = open(*filename, O_RDONLY)) != -1) {
141 len = read(fd, buff, sizeof(buff));
142 while (len > 0) {
143 archive_write_data(a, buff, len);
144 len = read(fd, buff, sizeof(buff));
145 }
146 close(fd);
147 }
148 archive_entry_free(entry);
149 filename++;
150 }
151 archive_write_free(a);
152 }
153 int main(int argc, const char **argv)
155 {
156 const char *outname;
157 argv++;
158 outname = *argv++;
159 write_archive(outname, argv);
160 return 0;
161 }
162
164 tar(1), archive_write_set_options(3), libarchive(3), cpio(5), mtree(5),
165 tar(5)
166
168 The libarchive library first appeared in FreeBSD 5.3.
169
171 The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
172
174 There are many peculiar bugs in historic tar implementations that may
175 cause certain programs to reject archives written by this library. For
176 example, several historic implementations calculated header checksums
177 incorrectly and will thus reject valid archives; GNU tar does not fully
178 support pax interchange format; some old tar implementations required
179 specific field terminations.
180 The default pax interchange format eliminates most of the historic tar
182 limitations and provides a generic key/value attribute facility for ven‐
183 dor-defined extensions. One oversight in POSIX is the failure to provide
184 a standard attribute for large device numbers. This library uses
185 “SCHILY.devminor” and “SCHILY.devmajor” for device numbers that exceed
186 the range supported by the backwards-compatible ustar header. These keys
187 are compatible with Joerg Schilling's star archiver. Other implementa‐
188 tions may not recognize these keys and will thus be unable to correctly
189 restore device nodes with large device numbers from archives created by
190 this library.
191BSD February 2, 2012 BSD