Poster of Linux kernelThe best gift for a Linux geek
archive_write

archive_write

Section: C Library Functions (3)
Local index Up

BSD mandoc
 

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_get_bytes_per_block archive_write_set_bytes_per_block archive_write_set_bytes_in_last_block archive_write_set_compression_bzip2 archive_write_set_compression_compress archive_write_set_compression_gzip archive_write_set_compression_none archive_write_set_compression_program archive_write_set_compressor_options archive_write_set_format_options archive_write_set_options archive_write_open archive_write_open_fd archive_write_open_FILE archive_write_open_filename archive_write_open_memory archive_write_header archive_write_data archive_write_finish_entry archive_write_close archive_write_finish - functions for creating archives  

SYNOPSIS

In archive.h Ft struct archive * Fn archive_write_new void Ft int Fn archive_write_get_bytes_per_block struct archive * Ft int Fn archive_write_set_bytes_per_block struct archive * int bytes_per_block Ft int Fn archive_write_set_bytes_in_last_block struct archive * int Ft int Fn archive_write_set_compression_bzip2 struct archive * Ft int Fn archive_write_set_compression_compress struct archive * Ft int Fn archive_write_set_compression_gzip struct archive * Ft int Fn archive_write_set_compression_none struct archive * Ft int Fn archive_write_set_compression_program struct archive * const char * cmd Ft int Fn archive_write_set_format_cpio struct archive * Ft int Fn archive_write_set_format_pax struct archive * Ft int Fn archive_write_set_format_pax_restricted struct archive * Ft int Fn archive_write_set_format_shar struct archive * Ft int Fn archive_write_set_format_shar_binary struct archive * Ft int Fn archive_write_set_format_ustar struct archive * Ft int Fn archive_write_set_format_options struct archive * const char * Ft int Fn archive_write_set_compressor_options struct archive * const char * Ft int Fn archive_write_set_options struct archive * const char * Ft int Fo archive_write_open Fa struct archive * Fa void *client_data Fa archive_open_callback * Fa archive_write_callback * Fa archive_close_callback * Fc Ft int Fn archive_write_open_fd struct archive * int fd Ft int Fn archive_write_open_FILE struct archive * FILE *file Ft int Fn archive_write_open_filename struct archive * const char *filename Ft int Fo archive_write_open_memory Fa struct archive * Fa void *buffer Fa size_t bufferSize Fa size_t *outUsed Fc Ft int Fn archive_write_header struct archive * struct archive_entry * Ft ssize_t Fn archive_write_data struct archive * const void * size_t Ft int Fn archive_write_finish_entry struct archive * Ft int Fn archive_write_close struct archive * Ft int Fn archive_write_finish struct archive *  

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:

Fn archive_write_new
Allocates and initializes a struct archive object suitable for writing a tar archive.
Fn 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. 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.
Fn archive_write_get_bytes_per_block
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.
Fn 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 Fn archive_write_open_filename will set this based on the file type). Unlike the other ``set'' functions, this function can be called after the archive is opened.
Fn archive_write_get_bytes_in_last_block
Retrieve the currently-set value for last block size. A value of -1 here indicates that the library should use default values.
Fn archive_write_set_format_cpio , Fn archive_write_set_format_pax , Fn archive_write_set_format_pax_restricted , Fn archive_write_set_format_shar , Fn archive_write_set_format_shar_binary , Fn 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.
Fn archive_write_set_compression_bzip2 , Fn archive_write_set_compression_compress , Fn archive_write_set_compression_gzip , Fn archive_write_set_compression_none
The resulting archive will be compressed as specified. Note that the compressed output is always properly blocked.
Fn archive_write_set_compression_program
The archive will be fed into the specified compression program. The output of that program is blocked and written to the client write callbacks.
Fn archive_write_set_compressor_options , Fn archive_write_set_format_options , Fn archive_write_set_options
Specifies options that will be passed to the currently-enabled compressor and/or format writer. The argument is a comma-separated list of individual options. Individual options have one of the following forms:

option=value
The option/value pair will be provided to every module. Modules that do not accept an option with this name will ignore it.
option
The option will be provided to every module with a value of ``1''
!option
The option will be provided to every module with a NULL value.
module:option=value , module:option , module:!option
As above, but the corresponding option and value will be provided only to modules whose name matches module

The return value will be ARCHIVE_OK if any module accepts the option, or ARCHIVE_WARN if no module accepted the option, or ARCHIVE_FATAL if there was a fatal error while attempting to process the option.

The currently supported options are:

Compressor gzip

compression-level
The value is interpreted as a decimal integer specifying the gzip compression level.

Compressor xz

compression-level
The value is interpreted as a decimal integer specifying the compression level.

Format mtree

cksum , device , flags , gid , gname , indent , link , md5 , mode , nlink , rmd160 , sha1 , sha256 , sha384 , sha512 , size , time , uid , uname
Enable a particular keyword in the mtree output. Prefix with an exclamation mark to disable the corresponding keyword. The default is equivalent to ``device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname''
all
Enables all of the above keywords.
use-set
Enables generation of /set lines that specify default values for the following files and/or directories.
indent
XXX needs explanation XXX

Fn 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.
Fn archive_write_open_fd
A convenience form of Fn archive_write_open that accepts a file descriptor. The Fn archive_write_open_fd function is safe for use with tape drives or other block-oriented devices.
Fn archive_write_open_FILE
A convenience form of Fn archive_write_open that accepts a Ft FILE * pointer. Note that Fn archive_write_open_FILE is not safe for writing to tape drives or other devices that require correct blocking.
Fn archive_write_open_file
A deprecated synonym for Fn archive_write_open_filename .
Fn archive_write_open_filename
A convenience form of Fn 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 Fn archive_write_set_bytes_in_last_block , then Fn archive_write_open_filename 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 Fn archive_write_set_bytes_in_last_block before calling Fn archive_write_open . The Fn archive_write_open_filename function is safe for use with tape drives or other block-oriented devices.
Fn archive_write_open_memory
A convenience form of Fn archive_write_open that accepts a pointer to a block of memory that will receive the archive. The final Ft size_t * 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.
Fn archive_write_header
Build and write a header using the data in the provided struct archive_entry structure. See archive_entry3 for information on creating and populating struct archive_entry objects.
Fn archive_write_data
Write data corresponding to the header just written. Returns number of bytes written or -1 on error.
Fn archive_write_finish_entry
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 Fn archive_write_next_header and Fn archive_write_close as needed.
Fn archive_write_close
Complete the archive and invoke the close callback.
Fn archive_write_finish
Invokes Fn archive_write_close if it was not invoked manually, then releases all resources. Note that this function was declared to return Ft void in libarchive 1.x, which made it impossible to detect errors when Fn archive_write_close was invoked implicitly from this function. This is corrected beginning with libarchive 2.0.

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 Fn archive_write_open :

Ft typedef int
Fn archive_open_callback struct archive * void *client_data

The open callback is invoked by Fn 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 Fn archive_set_error to register an error code and message and return ARCHIVE_FATAL

Ft typedef ssize_t
Fo archive_write_callback Fa struct archive * Fa void *client_data Fa const void *buffer Fa size_t length Fc

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 Fn archive_set_error to register an error code and message and return -1.

Ft typedef int
Fn archive_close_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 Fn archive_set_error to register an error code and message and return 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.
#ifdef __linux__
#define _FILE_OFFSET_BITS 64
#endif
#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, const 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;
}
 

RETURN VALUES

Most functions return ARCHIVE_OK (zero) on success, or one of several non-zero error codes for errors. Specific error codes include: ARCHIVE_RETRY for operations that might succeed if retried, ARCHIVE_WARN for unusual conditions that do not prevent further operations, and ARCHIVE_FATAL for serious errors that make remaining operations impossible. The Fn archive_errno and Fn archive_error_string functions can be used to retrieve an appropriate error code and a textual error message.

Fn archive_write_new returns a pointer to a newly-allocated struct archive object.

Fn archive_write_data returns a count of the number of bytes actually written. On error, -1 is returned and the Fn archive_errno and Fn 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 Fn archive_write_header , Fn archive_write_data , Fn archive_write_close , or Fn archive_write_finish . The client callback can call Fn archive_set_error to provide values that can then be retrieved by Fn archive_errno and Fn archive_error_string .  

SEE ALSO

tar(1), libarchive(3), tar(5)  

HISTORY

The libarchive library first appeared in Fx 5.3 .  

AUTHORS

An -nosplit The libarchive library was written by An Tim Kientzle Aq kientzle@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 facility for vendor-defined extensions. One oversight in POSIX is the failure to provide a standard attribute for large device numbers. This library uses ``SCHILY.devminor'' and ``SCHILY.devmajor'' for device numbers 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 device nodes with large device numbers from archives created by this library.


 

Index

NAME
SYNOPSIS
DESCRIPTION
IMPLEMENTATION
CLIENT CALLBACKS
EXAMPLE
RETURN VALUES
SEE ALSO
HISTORY
AUTHORS
BUGS

This document was created by man2html, using the manual pages.
Time: 21:41:54 GMT, April 16, 2011