archive_write(3)

NAME

archive_write_new, archive_write_set_format_cpio, archive_write_set_format_pax,
archive_write_set_format_pax_restricted, archive_write_set_format_shar,
archive_write_set_format_shar_binary, archive_write_set_format_ustar,
archive_write_set_bytes_per_block, archive_write_set_bytes_in_last_block,
archive_write_set_compressor_gzip, archive_write_set_compressor_bzip2, archive_write_open, archive_write_open_fd, archive_write_open_file,
archive_write_prepare,
archive_write_header, archive_write_data,
archive_write_close,
archive_write_finish - functions for creating archives

SYNOPSIS

#include <archive.h>
struct archive *
archive_write_new(void);
int
archive_write_set_bytes_per_block(archive       *,       int
bytes_per_block);
int
archive_write_set_bytes_in_last_block(archive *, int);
int
archive_write_set_compressor_gzip(struct archive *);
int
archive_write_set_compressor_bzip2(struct archive *);
int
archive_write_set_format_cpio(struct archive *);
int
archive_write_set_format_pax(struct archive *);
int
archive_write_set_format_pax_restricted(struct archive *);
int
archive_write_set_format_shar(struct archive *);
int
archive_write_set_format_shar_binary(struct archive *);
int
archive_write_set_format_ustar(struct archive *);
int
archive_write_open(struct archive *, void *client_data,
        archive_open_archive_callback *,
        archive_write_archive_callback *,
        archive_close_archive_callback *);
int
archive_write_open_fd(struct archive *, int fd);
int
archive_write_open_file(struct   archive   *,   const   char
*filename);
int
archive_write_header(struct archive *);
int
archive_write_data(struct archive *, const void *, size_t);
int
archive_write_close(struct archive *);
void
archive_write_finish(struct archive *);

DESCRIPTION

These functions provide a complete API for creating stream
ing archive files. The general process is to first create the struct
archive object, set any desired options, initialize the archive, append en
tries, then close the archive and release all resources. The following
summary describes the functions in approximately the order they are
ordinarily used:
archive_write_new(): Allocates and initializes a struct archive object; suitable for
writing a tar archive.
archive_write_set_bytes_per_block(): Sets the block size used for writing the archive da; ta. Every
call to the write callback function, except possibly; the last
one, will use this value for the length. The third; parameter is
a boolean that specifies whether or not the final; block written
will be padded to the full block size. If it is ze; ro, the last
block will not be padded. If it is non-zero,; padding will be
added both before and after compression. The de; fault is to use a
block size of 10240 bytes and to pad the last block.
archive_write_set_bytes_in_last_block(): Sets the block size used for writing the last block.; If this
value is zero, the last block will be padded to the; same size as
the other blocks. Otherwise, the final block will; be padded to a
multiple of this size. In particular, setting it to; 1 will cause
the final block to not be padded. For compressed; output, any
padding generated by this option is applied only af; ter the compression. The uncompressed data is always unpadded.; The default
is to pad the last block to the full block size; (note that
archive_write_open_file() will set this based on the; file type).
Unlike the other ``set'' functions, this function; can be called
after the archive is opened.
archive_write_set_format_cpio(),
archive_write_set_format_pax(),: archive_write_set_format_pax_restricted(), archive_write_set_format_shar(), archive_write_set_format_shar_binary(), archive_write_set_format_ustar() Sets the format that will be used for the archive.; The library
can write POSIX octet-oriented cpio format archives,; POSIX-standard ``pax interchange'' format archives, tradition; al ``shar''
archives, enhanced ``binary'' shar archives that; store a variety
of file attributes and handle binary files, and; POSIX-standard
``ustar'' archives. The pax interchange format is a; backwardscompatible tar format that adds key/value attributes; to each
entry and supports arbitrary filenames, linknames,; uids, sizes,
etc. ``Restricted pax interchange format'' is the; library
default; this is the same as pax format, but sup; presses the pax
extended header for most normal files. In most cas; es, this will
result in ordinary ustar archives.
archive_write_set_compression_gzip(),: archive_write_set_compression_bzip2() The resulting archive will be compressed as speci; fied. Note that
the compressed output is always properly blocked.
archive_write_open(): Freeze the settings, open the archive, and prepare; for writing
entries. This is the most generic form of this; function, which
accepts pointers to three callback functions which; will be
invoked by the compression layer to write the con; structed
archive. In order to support external compression; programs, the
compression is permitted to fork and invoke the; callbacks from a
separate process. In particular, clients should not; assume that
they can communicate between the callbacks and the; mainline code
using shared variables. (The standard gzip, bzip2,; and "none"
compression methods do not fork.)
archive_write_open_fd(): A convenience form of archive_write_open() that ac; cepts a file
descriptor.
archive_write_open_file(): A convenience form of archive_write_open() that ac; cepts a filename. A NULL argument indicates that the output; should be written to standard output; an argument of ``-'' will; open a file
with that name. If you have not invoked
archive_write_set_bytes_in_last_block(), then archive_write_open_file() will adjust the last-block; padding
depending on the file: it will enable padding when; writing to
standard output or to a character or block device; node, it will
disable padding otherwise. You can override this by; manually
invoking archive_write_set_bytes_in_last_block() ei; ther before or
after calling archive_write_open().
archive_write_header(): Build and write a header using the data in the pro; vided struct
archive_entry structure.
archive_write_data(): Write data corresponding to the header just written.; Returns
number of bytes written or -1 on error.
archive_write_close(): Complete the archive and invoke the close callback.
archive_write_finish(): Invokes archive_write_close() if it was not invoked; manually,
then release all resources.
More information about the struct archive object and the
overall design of the library can be found in the libarchive(3) overview.

IMPLEMENTATION

Compression support is built-in to libarchive, which uses
zlib and bzlib to handle gzip and bzip2 compression, respectively.

CLIENT CALLBACKS

To use this library, you will need to define and register
callback functions that will be invoked to write data to the resulting
archive. These
functions are registered by calling archive_write_open():: typedef int archive_open_archive_callback(struct; archive *, void
*client_data)
The open callback is invoked by archive_write_open(). It
should return
ARCHIVE_OK if the underlying file or data source is success
fully opened.
If the open fails, it should call archive_set_error() to
register an
error code and message and return ARCHIVE_FATAL.: typedef ssize_t archive_write_archive_callback(struct; archive *,
void *client_data, void *buffer, size_t length)
The write callback is invoked whenever the library needs to
write raw bytes to the archive. For correct blocking, each call to
the write callback function should translate into a single write(2) system
call. This is especially critical when writing archives to tape drives.
On success, the write callback should return the number of bytes actual
ly written.
On error, the callback should invoke archive_set_error() to
register an error code and message and return -1.: typedef int archive_close_archive_callback(struct; archive *, void
*client_data)
The close callback is invoked by archive_close when the
archive processing is complete. The callback should return ARCHIVE_OK on
success. On
failure, the callback should invoke archive_set_error() to
register an
error code and message and regurn ARCHIVE_FATAL.

EXAMPLE

The following sketch illustrates basic usage of the library.
In this example, the callback functions are simply wrappers around
the standard open(2), write(2), and close(2) system calls.: #include <sys/stat.h>
#include <archive.h>
#include <archive_entry.h>
#include <fcntl.h>
#include <stdlib.h>
#include <unistd.h>; struct mydata {
const char *name;
int fd;; };; int
myopen(struct archive *a, void *client_data)
{
struct mydata *mydata = client_data;

mydata->fd = open(mydata->name, O_WRONLY | O_CREAT,

0644);
if (mydata->fd >= 0)
return (ARCHIVE_OK);

else

return (ARCHIVE_FATAL);

}

ssize_t
mywrite(struct archive *a, void *client_data, void

*buff, size_t n)
{

struct mydata *mydata = client_data;

return (write(mydata->fd, buff, n));

}

int
myclose(struct archive *a, void *client_data)
{

struct mydata *mydata = client_data;

if (mydata->fd > 0)
close(mydata->fd);

return (0);

}

void
write_archive(const char *outname, const char **file

name)
{

struct mydata *mydata = malloc(sizeof(struct myda

ta));
struct archive *a;
struct archive_entry *entry;
struct stat st;
char buff[8192];
int len;
int fd;

a = archive_write_new();
mydata->name = outname;
archive_write_set_compression_gzip(a);
archive_write_set_format_ustar(a);
archive_write_open(a, mydata, myopen, mywrite, my

close);
while (*filename) {

stat(*filename, &st);
entry = archive_entry_new();
archive_entry_copy_stat(entry, &st);
archive_entry_set_pathname(entry, *filename);
archive_write_header(a, entry);
fd = open(*filename, O_RDONLY);
len = read(fd, buff, sizeof(buff));
while ( len > 0 ) {
archive_write_data(a, buff, len);
len = read(fd, buff, sizeof(buff));

}
archive_entry_free(entry);
filename++;

}
archive_write_finish(a);

}

int main(int argc, const char **argv)
{

const char *outname;
argv++;
outname = argv++;
write_archive(outname, argv);
return 0;

}

RETURN VALUES

Most functions return zero on success, non-zero on error.
The
archive_errno() and archive_error_string() functions can be
used to retrieve an appropriate error code and a textual error mes
sage.
archive_write_new() returns a pointer to a newly-allocated
struct archive object.
archive_write_data() returns a count of the number of bytes
actually
written. On error, -1 is returned and the archive_errno()
and
archive_error_string() functions will return appropriate
values. Note that if the client-provided write callback function returns
a non-zero value, that error will be propagated back to the caller
through whatever
API function resulted in that call, which may include
archive_write_header(), archive_write_data(), or
archive_write_close().
The client callback can call archive_set_error() to provide
values that
can then be retrieved by archive_errno() and
archive_error_string().

HISTORY

The libarchive library first appeared in FreeBSD 5.3.

AUTHORS

The libarchive library was written by Tim Kientzle <kient
zle@acm.org>.

BUGS

There are many peculiar bugs in historic tar implementations
that may cause certain programs to reject archives written by this
library. For example, several historic implementations calculated header
checksums incorrectly and will thus reject valid archives; GNU tar
does not fully support pax interchange format; some old tar implementations
required specific field terminations.
The default pax interchange format eliminates most of the
historic tar limitations and provides a generic key/value attribute fa
cility for vendor-defined extensions. One oversight in POSIX is the fail
ure to provide a standard attribute for large device numbers. This library
uses ``SCHILY.devminor'' and ``SCHILY.devmajor'' for device num
bers that exceed the range supported by the backwards-compatible ustar
header.
These keys are compatible with Joerg Schilling's star
archiver. Other implementations may not recognize these keys and will thus
be unable to correctly restore large device numbers archived by this li
brary.
BSD January 8, 2005

docs.sk

comprehensive documentation repository

See also

archive_write(3)

NAME

SYNOPSIS

DESCRIPTION

IMPLEMENTATION

CLIENT CALLBACKS

EXAMPLE

RETURN VALUES

SEE ALSO

HISTORY

AUTHORS

BUGS