1ARCHIVE_WRITE(3)         BSD Library Functions Manual         ARCHIVE_WRITE(3)
2

NAME

4     archive_write — functions for creating archives
5

LIBRARY

7     Streaming Archive Library (libarchive, -larchive)
8

SYNOPSIS

10     #include <archive.h>
11

DESCRIPTION

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
18   Create archive object
19     See archive_write_new(3).
20
21     To write an archive, you must first obtain an initialized struct archive
22     object from archive_write_new().
23
24   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
28     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
33   Set options
34     See archive_write_set_options(3).
35
36   Open archive
37     See archive_write_open(3).
38
39     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
47   Produce archive
48     See archive_write_header(3) and archive_write_data(3).
49
50     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
57   Release resources
58     See archive_write_free(3).
59
60     After all entries have been written, use the archive_write_free() func‐
61     tion to release all resources.
62

EXAMPLE

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
68           #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
78           struct mydata {
79             const char *name;
80             int fd;
81           };
82
83           int
84           myopen(struct archive *a, void *client_data)
85           {
86             struct mydata *mydata = client_data;
87
88             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
95           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
100             return (write(mydata->fd, buff, n));
101           }
102
103           int
104           myclose(struct archive *a, void *client_data)
105           {
106             struct mydata *mydata = client_data;
107
108             if (mydata->fd > 0)
109               close(mydata->fd);
110             return (0);
111           }
112
113           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
124             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
154           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

SEE ALSO

164     tar(1), libarchive(3), archive_write_set_options(3), cpio(5), mtree(5),
165     tar(5)
166

HISTORY

168     The libarchive library first appeared in FreeBSD 5.3.
169

AUTHORS

171     The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
172

BUGS

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
181     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.
191
192BSD                            February 2, 2012                            BSD
Impressum