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_read_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 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 archive_write_add_filter_gzip(a);
127 archive_write_set_format_ustar(a);
128 archive_write_open(a, mydata, myopen, mywrite, myclose);
129 while (*filename) {
130 stat(*filename, &st);
131 entry = archive_entry_new();
132 archive_entry_copy_stat(entry, &st);
133 archive_entry_set_pathname(entry, *filename);
134 archive_write_header(a, entry);
135 if ((fd = open(*filename, O_RDONLY)) != -1) {
136 len = read(fd, buff, sizeof(buff));
137 while ( len > 0 ) {
138 archive_write_data(a, buff, len);
139 len = read(fd, buff, sizeof(buff));
140 }
141 close(fd);
142 }
143 archive_entry_free(entry);
144 filename++;
145 }
146 archive_write_free(a);
147 }
148 int main(int argc, const char **argv)
150 {
151 const char *outname;
152 argv++;
153 outname = argv++;
154 write_archive(outname, argv);
155 return 0;
156 }
157
159 tar(1), libarchive(3), archive_write_set_options(3), cpio(5), mtree(5),
160 tar(5)
161
163 The libarchive library first appeared in FreeBSD 5.3.
164
166 The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
167
169 There are many peculiar bugs in historic tar implementations that may
170 cause certain programs to reject archives written by this library. For
171 example, several historic implementations calculated header checksums
172 incorrectly and will thus reject valid archives; GNU tar does not fully
173 support pax interchange format; some old tar implementations required
174 specific field terminations.
175 The default pax interchange format eliminates most of the historic tar
177 limitations and provides a generic key/value attribute facility for ven‐
178 dor-defined extensions. One oversight in POSIX is the failure to provide
179 a standard attribute for large device numbers. This library uses
180 “SCHILY.devminor” and “SCHILY.devmajor” for device numbers that exceed
181 the range supported by the backwards-compatible ustar header. These keys
182 are compatible with Joerg Schilling's star archiver. Other implementa‐
183 tions may not recognize these keys and will thus be unable to correctly
184 restore device nodes with large device numbers from archives created by
185 this library.
186BSD February 2, 2012 BSD