|
Packit |
08bd4c |
ARCHIVE_WRITE(3) BSD Library Functions Manual ARCHIVE_WRITE(3)
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
NAME
|
|
Packit |
08bd4c |
archive_write — functions for creating archives
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
LIBRARY
|
|
Packit |
08bd4c |
Streaming Archive Library (libarchive, -larchive)
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
SYNOPSIS
|
|
Packit |
08bd4c |
#include <archive.h>
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
DESCRIPTION
|
|
Packit |
08bd4c |
These functions provide a complete API for creating streaming archive
|
|
Packit |
08bd4c |
files. The general process is to first create the struct archive object,
|
|
Packit |
08bd4c |
set any desired options, initialize the archive, append entries, then
|
|
Packit |
08bd4c |
close the archive and release all resources.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Create archive object
|
|
Packit |
08bd4c |
See archive_write_new(3).
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
To write an archive, you must first obtain an initialized struct archive
|
|
Packit |
08bd4c |
object from archive_write_new().
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Enable filters and formats, configure block size and padding
|
|
Packit |
08bd4c |
See archive_write_filter(3), archive_write_format(3) and
|
|
Packit |
08bd4c |
archive_write_blocksize(3).
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
You can then modify this object for the desired operations with the vari‐
|
|
Packit |
08bd4c |
ous archive_write_set_XXX() functions. In particular, you will need to
|
|
Packit |
08bd4c |
invoke appropriate archive_write_add_XXX() and archive_write_set_XXX()
|
|
Packit |
08bd4c |
functions to enable the corresponding compression and format support.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Set options
|
|
Packit |
08bd4c |
See archive_read_set_options(3).
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Open archive
|
|
Packit |
08bd4c |
See archive_write_open(3).
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Once you have prepared the struct archive object, you call
|
|
Packit |
08bd4c |
archive_write_open() to actually open the archive and prepare it for
|
|
Packit |
08bd4c |
writing. There are several variants of this function; the most basic
|
|
Packit |
08bd4c |
expects you to provide pointers to several functions that can provide
|
|
Packit |
08bd4c |
blocks of bytes from the archive. There are convenience forms that allow
|
|
Packit |
08bd4c |
you to specify a filename, file descriptor, FILE * object, or a block of
|
|
Packit |
08bd4c |
memory from which to write the archive data.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Produce archive
|
|
Packit |
08bd4c |
See archive_write_header(3) and archive_write_data(3).
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Individual archive entries are written in a three-step process: You first
|
|
Packit |
08bd4c |
initialize a struct archive_entry structure with information about the
|
|
Packit |
08bd4c |
new entry. At a minimum, you should set the pathname of the entry and
|
|
Packit |
08bd4c |
provide a struct stat with a valid st_mode field, which specifies the
|
|
Packit |
08bd4c |
type of object and st_size field, which specifies the size of the data
|
|
Packit |
08bd4c |
portion of the object.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
Release resources
|
|
Packit |
08bd4c |
See archive_write_free(3).
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
After all entries have been written, use the archive_write_free() func‐
|
|
Packit |
08bd4c |
tion to release all resources.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
EXAMPLE
|
|
Packit |
08bd4c |
The following sketch illustrates basic usage of the library. In this
|
|
Packit |
08bd4c |
example, the callback functions are simply wrappers around the standard
|
|
Packit |
08bd4c |
open(2), write(2), and close(2) system calls.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
#ifdef __linux__
|
|
Packit |
08bd4c |
#define _FILE_OFFSET_BITS 64
|
|
Packit |
08bd4c |
#endif
|
|
Packit |
08bd4c |
#include <sys/stat.h>
|
|
Packit |
08bd4c |
#include <archive.h>
|
|
Packit |
08bd4c |
#include <archive_entry.h>
|
|
Packit |
08bd4c |
#include <fcntl.h>
|
|
Packit |
08bd4c |
#include <stdlib.h>
|
|
Packit |
08bd4c |
#include <unistd.h>
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
struct mydata {
|
|
Packit |
08bd4c |
const char *name;
|
|
Packit |
08bd4c |
int fd;
|
|
Packit |
08bd4c |
};
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
int
|
|
Packit |
08bd4c |
myopen(struct archive *a, void *client_data)
|
|
Packit |
08bd4c |
{
|
|
Packit |
08bd4c |
struct mydata *mydata = client_data;
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
|
|
Packit |
08bd4c |
if (mydata->fd >= 0)
|
|
Packit |
08bd4c |
return (ARCHIVE_OK);
|
|
Packit |
08bd4c |
else
|
|
Packit |
08bd4c |
return (ARCHIVE_FATAL);
|
|
Packit |
08bd4c |
}
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
la_ssize_t
|
|
Packit |
08bd4c |
mywrite(struct archive *a, void *client_data, const void *buff, size_t n)
|
|
Packit |
08bd4c |
{
|
|
Packit |
08bd4c |
struct mydata *mydata = client_data;
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
return (write(mydata->fd, buff, n));
|
|
Packit |
08bd4c |
}
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
int
|
|
Packit |
08bd4c |
myclose(struct archive *a, void *client_data)
|
|
Packit |
08bd4c |
{
|
|
Packit |
08bd4c |
struct mydata *mydata = client_data;
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
if (mydata->fd > 0)
|
|
Packit |
08bd4c |
close(mydata->fd);
|
|
Packit |
08bd4c |
return (0);
|
|
Packit |
08bd4c |
}
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
void
|
|
Packit |
08bd4c |
write_archive(const char *outname, const char **filename)
|
|
Packit |
08bd4c |
{
|
|
Packit |
08bd4c |
struct mydata *mydata = malloc(sizeof(struct mydata));
|
|
Packit |
08bd4c |
struct archive *a;
|
|
Packit |
08bd4c |
struct archive_entry *entry;
|
|
Packit |
08bd4c |
struct stat st;
|
|
Packit |
08bd4c |
char buff[8192];
|
|
Packit |
08bd4c |
int len;
|
|
Packit |
08bd4c |
int fd;
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
a = archive_write_new();
|
|
Packit |
08bd4c |
mydata->name = outname;
|
|
Packit |
08bd4c |
/* Set archive format and filter according to output file extension.
|
|
Packit |
08bd4c |
* If it fails, set default format. Platform depended function.
|
|
Packit |
08bd4c |
* See supported formats in archive_write_set_format_filter_by_ext.c */
|
|
Packit |
08bd4c |
if (archive_write_set_format_filter_by_ext(a, outname) != ARCHIVE_OK) {
|
|
Packit |
08bd4c |
archive_write_add_filter_gzip(a);
|
|
Packit |
08bd4c |
archive_write_set_format_ustar(a);
|
|
Packit |
08bd4c |
}
|
|
Packit |
08bd4c |
archive_write_open(a, mydata, myopen, mywrite, myclose);
|
|
Packit |
08bd4c |
while (*filename) {
|
|
Packit |
08bd4c |
stat(*filename, &st);
|
|
Packit |
08bd4c |
entry = archive_entry_new();
|
|
Packit |
08bd4c |
archive_entry_copy_stat(entry, &st);
|
|
Packit |
08bd4c |
archive_entry_set_pathname(entry, *filename);
|
|
Packit |
08bd4c |
archive_write_header(a, entry);
|
|
Packit |
08bd4c |
if ((fd = open(*filename, O_RDONLY)) != -1) {
|
|
Packit |
08bd4c |
len = read(fd, buff, sizeof(buff));
|
|
Packit |
08bd4c |
while (len > 0) {
|
|
Packit |
08bd4c |
archive_write_data(a, buff, len);
|
|
Packit |
08bd4c |
len = read(fd, buff, sizeof(buff));
|
|
Packit |
08bd4c |
}
|
|
Packit |
08bd4c |
close(fd);
|
|
Packit |
08bd4c |
}
|
|
Packit |
08bd4c |
archive_entry_free(entry);
|
|
Packit |
08bd4c |
filename++;
|
|
Packit |
08bd4c |
}
|
|
Packit |
08bd4c |
archive_write_free(a);
|
|
Packit |
08bd4c |
}
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
int main(int argc, const char **argv)
|
|
Packit |
08bd4c |
{
|
|
Packit |
08bd4c |
const char *outname;
|
|
Packit |
08bd4c |
argv++;
|
|
Packit |
08bd4c |
outname = *argv++;
|
|
Packit |
08bd4c |
write_archive(outname, argv);
|
|
Packit |
08bd4c |
return 0;
|
|
Packit |
08bd4c |
}
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
SEE ALSO
|
|
Packit |
08bd4c |
tar(1), libarchive(3), archive_write_set_options(3), cpio(5), mtree(5),
|
|
Packit |
08bd4c |
tar(5)
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
HISTORY
|
|
Packit |
08bd4c |
The libarchive library first appeared in FreeBSD 5.3.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
AUTHORS
|
|
Packit |
08bd4c |
The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
BUGS
|
|
Packit |
08bd4c |
There are many peculiar bugs in historic tar implementations that may
|
|
Packit |
08bd4c |
cause certain programs to reject archives written by this library. For
|
|
Packit |
08bd4c |
example, several historic implementations calculated header checksums
|
|
Packit |
08bd4c |
incorrectly and will thus reject valid archives; GNU tar does not fully
|
|
Packit |
08bd4c |
support pax interchange format; some old tar implementations required
|
|
Packit |
08bd4c |
specific field terminations.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
The default pax interchange format eliminates most of the historic tar
|
|
Packit |
08bd4c |
limitations and provides a generic key/value attribute facility for ven‐
|
|
Packit |
08bd4c |
dor-defined extensions. One oversight in POSIX is the failure to provide
|
|
Packit |
08bd4c |
a standard attribute for large device numbers. This library uses
|
|
Packit |
08bd4c |
“SCHILY.devminor” and “SCHILY.devmajor” for device numbers that exceed
|
|
Packit |
08bd4c |
the range supported by the backwards-compatible ustar header. These keys
|
|
Packit |
08bd4c |
are compatible with Joerg Schilling's star archiver. Other implementa‐
|
|
Packit |
08bd4c |
tions may not recognize these keys and will thus be unable to correctly
|
|
Packit |
08bd4c |
restore device nodes with large device numbers from archives created by
|
|
Packit |
08bd4c |
this library.
|
|
Packit |
08bd4c |
|
|
Packit |
08bd4c |
BSD February 2, 2012 BSD
|