Table of Contents
These functions
provide a complete API for creating streaming archive files. The general
process is to first create the object, set any desired options, initialize
the archive, append entries, then close the archive and release all resources.
The following summary describes the functions in approximately the order
they are ordinarily used: Allocates and initializes a object suitable
for writing a tar archive. Sets the block size used for writing the archive
data. 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 zero, the last block will not be padded. If
it is non-zero, padding will be added both before and after compression.
The default is to use a block size of 10240 bytes and to pad the last block.
Note that a block size of zero will suppress internal blocking and cause
writes to be sent directly to the write callback as they occur. Retrieve
the block size to be used for writing. A value of -1 here indicates that
the library should use default values. A value of zero indicates that internal
blocking is suppressed. 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 after the compression. The uncompressed data is always unpadded.
The default is to pad the last block to the full block size (note that
will set this based on the file type). Unlike the other functions, this
function can be called after the archive is opened. Retrieve the currently-set
value for last block size. A value of -1 here indicates that the library
should use default values. Sets the format that will be used for the archive.
The library can write POSIX octet-oriented cpio format archives, POSIX-standard
format archives, traditional archives, enhanced shar archives that store
a variety of file attributes and handle binary files, and POSIX-standard
archives. The pax interchange format is a backwards-compatible tar format
that adds key/value attributes to each entry and supports arbitrary filenames,
linknames, uids, sizes, etc. is the library default; this is the same as
pax format, but suppresses the pax extended header for most normal files.
In most cases, this will result in ordinary ustar archives. The resulting
archive will be compressed as specified. Note that the compressed output
is always properly blocked. The archive will be fed into the specified
compression program. The output of that program is blocked and written to
the client write callbacks. 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 constructed archive. A convenience
form of that accepts a file descriptor. The function is safe for use with
tape drives or other block-oriented devices. A convenience form of that
accepts a pointer. Note that is not safe for writing to tape drives or
other devices that require correct blocking. A deprecated synonym for
A convenience form of that accepts 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 then 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 before calling
The function is safe for use with tape drives or other block-oriented
devices. A convenience form of that accepts a pointer to a block of memory
that will receive the archive. The final argument points to a variable
that will be updated after each write to reflect how much of the buffer
is currently in use. You should be careful to ensure that this variable
remains allocated until after the archive is closed. Build and write a
header using the data in the provided structure. See for information on
creating and populating objects. Write data corresponding to the header
just written. Returns number of bytes written or -1 on error. Close out the
entry just written. In particular, this writes out the final padding required
by some formats. Ordinarily, clients never need to call this, as it is called
automatically by and as needed. Complete the archive and invoke the close
callback. Invokes if it was not invoked manually, then releases all resources.
Note that this function was declared to return in libarchive 1.x, which
made it impossible to detect errors when was invoked implicitly from this
function. This is corrected beginning with libarchive 2.0. More information
about the object and the overall design of the library can be found in
the overview.
Compression support is built-in to libarchive,
which uses zlib and bzlib to handle gzip and bzip2 compression, respectively.
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 The open callback
is invoked by It should return if the underlying file or data source
is successfully opened. If the open fails, it should call to register an
error code and message and return 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 system call. This is especially critical when writing archives
to tape drives. On success, the write callback should return the number
of bytes actually written. On error, the callback should invoke to register
an error code and message and return -1. The close callback is invoked
by archive_close when the archive processing is complete. The callback should
return on success. On failure, the callback should invoke to register
an error code and message and return
The following sketch illustrates
basic usage of the library. In this example, the callback functions are
simply wrappers around the standard and 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 **filename) {
struct mydata *mydata = malloc(sizeof(struct mydata));
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, myclose);
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;
}
Most functions return (zero) on success, or one of several
non-zero error codes for errors. Specific error codes include: for operations
that might succeed if retried, for unusual conditions that do not prevent
further operations, and for serious errors that make remaining operations
impossible. The and functions can be used to retrieve an appropriate error
code and a textual error message. returns a pointer to a newly-allocated
object. returns a count of the number of bytes actually written. On error,
-1 is returned and the and 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 or The client callback can
call to provide values that can then be retrieved by and
The library first appeared in
The library was written
by
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 facility
for vendor-defined extensions. One oversight in POSIX is the failure to provide
a standard attribute for large device numbers. This library uses and for
device numbers that exceed the range supported by the backwards-compatible
ustar header. These keys are compatible with Joerg Schilling’s archiver.
Other implementations may not recognize these keys and will thus be unable
to correctly restore device nodes with large device numbers from archives
created by this library.
Table of Contents