1.\" Copyright (c) 2003-2011 Tim Kientzle
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
12.\"
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
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd February 2, 2012
28.Dt ARCHIVE_WRITE 3
29.Os
30.Sh NAME
31.Nm archive_write
32.Nd functions for creating archives
33.Sh LIBRARY
34Streaming Archive Library (libarchive, -larchive)
35.Sh SYNOPSIS
36.In archive.h
37.Sh DESCRIPTION
38These functions provide a complete API for creating streaming
39archive files.
40The general process is to first create the
41.Tn struct archive
42object, set any desired options, initialize the archive, append entries, then
43close the archive and release all resources.
44.\"
45.Ss Create archive object
46See
47.Xr archive_write_new 3 .
48.Pp
49To write an archive, you must first obtain an initialized
50.Tn struct archive
51object from
52.Fn archive_write_new .
53.\"
54.Ss Enable filters and formats, configure block size and padding
55See
56.Xr archive_write_filter 3 ,
57.Xr archive_write_format 3
58and
59.Xr archive_write_blocksize 3 .
60.Pp
61You can then modify this object for the desired operations with the
62various
63.Fn archive_write_set_XXX
64functions.
65In particular, you will need to invoke appropriate
66.Fn archive_write_add_XXX
67and
68.Fn archive_write_set_XXX
69functions to enable the corresponding compression and format
70support.
71.\"
72.Ss Set options
73See
74.Xr archive_write_set_options 3 .
75.\"
76.Ss Open archive
77See
78.Xr archive_write_open 3 .
79.Pp
80Once you have prepared the
81.Tn struct archive
82object, you call
83.Fn archive_write_open
84to actually open the archive and prepare it for writing.
85There are several variants of this function;
86the most basic expects you to provide pointers to several
87functions that can provide blocks of bytes from the archive.
88There are convenience forms that allow you to
89specify a filename, file descriptor,
90.Ft "FILE *"
91object, or a block of memory from which to write the archive data.
92.\"
93.Ss Produce archive
94See
95.Xr archive_write_header 3
96and
97.Xr archive_write_data 3 .
98.Pp
99Individual archive entries are written in a three-step
100process:
101You first initialize a
102.Tn struct archive_entry
103structure with information about the new entry.
104At a minimum, you should set the pathname of the
105entry and provide a
106.Va struct stat
107with a valid
108.Va st_mode
109field, which specifies the type of object and
110.Va st_size
111field, which specifies the size of the data portion of the object.
112.\"
113.Ss Release resources
114See
115.Xr archive_write_free 3 .
116.Pp
117After all entries have been written, use the
118.Fn archive_write_free
119function to release all resources.
120.\"
121.Sh EXAMPLE
122The following sketch illustrates basic usage of the library.
123In this example,
124the callback functions are simply wrappers around the standard
125.Xr open 2 ,
126.Xr write 2 ,
127and
128.Xr close 2
129system calls.
130.Bd -literal -offset indent
131#ifdef __linux__
132#define	_FILE_OFFSET_BITS 64
133#endif
134#include <sys/stat.h>
135#include <archive.h>
136#include <archive_entry.h>
137#include <fcntl.h>
138#include <stdlib.h>
139#include <unistd.h>
140
141struct mydata {
142  const char *name;
143  int fd;
144};
145
146int
147myopen(struct archive *a, void *client_data)
148{
149  struct mydata *mydata = client_data;
150
151  mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
152  if (mydata->fd >= 0)
153    return (ARCHIVE_OK);
154  else
155    return (ARCHIVE_FATAL);
156}
157
158la_ssize_t
159mywrite(struct archive *a, void *client_data, const void *buff, size_t n)
160{
161  struct mydata *mydata = client_data;
162
163  return (write(mydata->fd, buff, n));
164}
165
166int
167myclose(struct archive *a, void *client_data)
168{
169  struct mydata *mydata = client_data;
170
171  if (mydata->fd > 0)
172    close(mydata->fd);
173  return (0);
174}
175
176void
177write_archive(const char *outname, const char **filename)
178{
179  struct mydata *mydata = malloc(sizeof(struct mydata));
180  struct archive *a;
181  struct archive_entry *entry;
182  struct stat st;
183  char buff[8192];
184  int len;
185  int fd;
186
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);
195  }
196  archive_write_open(a, mydata, myopen, mywrite, myclose);
197  while (*filename) {
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));
205      while (len > 0) {
206        archive_write_data(a, buff, len);
207        len = read(fd, buff, sizeof(buff));
208      }
209      close(fd);
210    }
211    archive_entry_free(entry);
212    filename++;
213  }
214  archive_write_free(a);
215}
216
217int main(int argc, const char **argv)
218{
219  const char *outname;
220  argv++;
221  outname = *argv++;
222  write_archive(outname, argv);
223  return 0;
224}
225.Ed
226.Sh SEE ALSO
227.Xr tar 1 ,
228.Xr libarchive 3 ,
229.Xr archive_write_set_options 3 ,
230.Xr cpio 5 ,
231.Xr mtree 5 ,
232.Xr tar 5
233.Sh HISTORY
234The
235.Nm libarchive
236library first appeared in
237.Fx 5.3 .
238.Sh AUTHORS
239.An -nosplit
240The
241.Nm libarchive
242library was written by
243.An Tim Kientzle Aq kientzle@acm.org .
244.Sh BUGS
245There are many peculiar bugs in historic tar implementations that may cause
246certain programs to reject archives written by this library.
247For example, several historic implementations calculated header checksums
248incorrectly and will thus reject valid archives; GNU tar does not fully support
249pax interchange format; some old tar implementations required specific
250field terminations.
251.Pp
252The default pax interchange format eliminates most of the historic
253tar limitations and provides a generic key/value attribute facility
254for vendor-defined extensions.
255One oversight in POSIX is the failure to provide a standard attribute
256for large device numbers.
257This library uses
258.Dq SCHILY.devminor
259and
260.Dq SCHILY.devmajor
261for device numbers that exceed the range supported by the backwards-compatible
262ustar header.
263These keys are compatible with Joerg Schilling's
264.Nm star
265archiver.
266Other implementations may not recognize these keys and will thus be unable
267to correctly restore device nodes with large device numbers from archives
268created by this library.
269