archive_write (3) | C library functions | Unix Manual Pages

archive_write (3) | C library functions | Unix Manual Pages | :man▋

NAME

Synopsis
Description
Implementation
Client Callbacks
Example
Return Values
See Also
History
Authors
Bugs

SYNOPSIS

DESCRIPTION

These functions provide a complete API for creating streaming archive files. The general process is to first create the struct archive 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:

`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 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.
`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 after 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, traditional "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 backwards-compatible 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 suppresses the pax extended header for most normal files. In most cases, this will result in ordinary ustar archives.
`archive_write_set_compression_gzip,` `archive_write_set_compression_bzip2`
	The resulting archive will be compressed as specified. 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 constructed 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 accepts a file descriptor.
`archive_write_open_file`
	A convenience form of `archive_write_open` 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 `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` either before or after calling `archive_write_open`.
`archive_write_header`
	Build and write a header using the data in the provided 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 successfully 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 actually 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 **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);
}