freebsd/lib/libarchive/archive_write.3

.\" Copyright (c) 2003-2005 Tim Kientzle
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd January 8, 2005
.Dt archive_write 3
.Os
.Sh NAME
.Nm archive_write_new ,
.Nm archive_write_set_format_cpio ,
.Nm archive_write_set_format_pax ,
.Nm archive_write_set_format_pax_restricted ,
.Nm archive_write_set_format_shar ,
.Nm archive_write_set_format_shar_binary ,
.Nm archive_write_set_format_ustar ,
.Nm archive_write_set_bytes_per_block ,
.Nm archive_write_set_bytes_in_last_block ,
.Nm archive_write_set_compressor_gzip ,
.Nm archive_write_set_compressor_bzip2 ,
.Nm archive_write_open ,
.Nm archive_write_open_fd ,
.Nm archive_write_open_file ,
.Nm archive_write_prepare ,
.Nm archive_write_header ,
.Nm archive_write_data ,
.Nm archive_write_close ,
.Nm archive_write_finish
.Nd functions for creating archives
.Sh SYNOPSIS
.In archive.h
.Ft struct archive *
.Fn archive_write_new "void"
.Ft int
.Fn archive_write_set_bytes_per_block "archive *" "int bytes_per_block"
.Ft int
.Fn archive_write_set_bytes_in_last_block "archive *" "int"
.Ft int
.Fn archive_write_set_compressor_gzip "struct archive *"
.Ft int
.Fn archive_write_set_compressor_bzip2 "struct archive *"
.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_open "struct archive *" "void *client_data" "archive_open_archive_callback *" "archive_write_archive_callback *" "archive_close_archive_callback *"
.Ft int
.Fn archive_write_open_fd "struct archive *" "int fd"
.Ft int
.Fn archive_write_open_file "struct archive *" "const char *filename"
.Ft int
.Fn archive_write_header "struct archive *"
.Ft int
.Fn archive_write_data "struct archive *" "const void *" "size_t"
.Ft int
.Fn archive_write_close "struct archive *"
.Ft void
.Fn archive_write_finish "struct archive *"
.Sh DESCRIPTION
These functions provide a complete API for creating streaming
archive files.
The general process is to first create the
.Tn 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:
.Bl -tag -width indent
.It Fn archive_write_new
Allocates and initializes a
.Tn struct archive
object suitable for writing a tar archive.
.It 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.
.It 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_file
will set this based on the file type).
Unlike the other
.Dq set
functions, this function can be called after the archive is opened.
.It 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
.Dq pax interchange
format archives,
traditional
.Dq shar
archives,
enhanced
.Dq binary
shar archives that store a variety of file attributes and handle binary files,
and
POSIX-standard
.Dq 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.
.Dq 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.
.It Fn archive_write_set_compression_gzip , Fn archive_write_set_compression_bzip2
The resulting archive will be compressed as specified.
Note that the compressed output is always properly blocked.
.It 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.
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.)
.It Fn archive_write_open_fd
A convenience form of
.Fn archive_write_open
that accepts a file descriptor.
.It Fn archive_write_open_file
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
.Dq -
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_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
.Fn archive_write_set_bytes_in_last_block
either before or after calling
.Fn archive_write_open .
.It Fn archive_write_header
Build and write a header using the data in the provided
.Tn struct archive_entry
structure.
.It Fn archive_write_data
Write data corresponding to the header just written.
Returns number of bytes written or -1 on error.
.It Fn archive_write_close
Complete the archive and invoke the close callback.
.It Fn archive_write_finish
Invokes
.Fn archive_write_close
if it was not invoked manually, then release all resources.
.El
More information about the
.Va struct archive
object and the overall design of the library can be found in the
.Xr libarchive 3
overview.
.Sh IMPLEMENTATION
Compression support is built-in to libarchive, which uses zlib and bzlib
to handle gzip and bzip2 compression, respectively.
.Sh 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 :
.Bl -item -offset indent
.It
.Ft typedef int
.Fn archive_open_archive_callback "struct archive *" "void *client_data"
.El
.Pp
The open callback is invoked by
.Fn archive_write_open .
It should return
.Cm 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
.Cm ARCHIVE_FATAL .
.Bl -item -offset indent
.It
.Ft typedef ssize_t
.Fn archive_write_archive_callback "struct archive *" "void *client_data" "void *buffer" "size_t length"
.El
.Pp
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
.Xr 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.
.Bl -item -offset indent
.It
.Ft typedef int
.Fn archive_close_archive_callback "struct archive *" "void *client_data"
.El
.Pp
The close callback is invoked by archive_close when
the archive processing is complete.
The callback should return
.Cm ARCHIVE_OK
on success.
On failure, the callback should invoke
.Fn archive_set_error
to register an error code and message and
regurn
.Cm ARCHIVE_FATAL.
.Sh EXAMPLE
The following sketch illustrates basic usage of the library.
In this example,
the callback functions are simply wrappers around the standard
.Xr open 2 ,
.Xr write 2 ,
and
.Xr close 2
system calls.
.Bd -literal -offset indent
void
write_archive(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;

  a = archive_write_new();
  mydata->name = name;
  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
myopen(struct archive *a, void *client_data)
{
  struct mydata *mydata = client_data;

  mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
  return (mydata->fd >= 0);
}

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);
}
.Ed
.Sh RETURN VALUES
Most functions return zero on success, non-zero on error.
The
.Fn archive_errno
and
.Fn archive_error_string
functions can be used to retrieve an appropriate error code and a
textual error message.
.Pp
.Fn archive_write_new
returns a pointer to a newly-allocated
.Tn struct archive
object.
.Pp
.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 ,
or
.Fn archive_write_close .
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 .
.Sh SEE ALSO
.Xr tar 1 ,
.Xr libarchive 3 ,
.Xr tar 5
.Sh HISTORY
The
.Nm libarchive
library first appeared in
.Fx 5.3 .
.Sh AUTHORS
.An -nosplit
The
.Nm libarchive
library was written by
.An Tim Kientzle Aq kientzle@acm.org .
.Sh 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.
.Pp
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
.Dq SCHILY.devminor
and
.Dq SCHILY.devmajor
for device numbers that exceed the range supported by the backwards-compatible
ustar header.
These keys are compatible with Joerg Schilling's
.Nm star
archiver.
Other implementations may not recognize these keys and will thus be unable
to correctly restore large device numbers archived by this library.