Initial import of libarchive.

What it is:
   A library for reading and writing various streaming archive
   formats, especially tar and cpio.  Being a library, it should
   be easy to incorporate into pkg_* tools, sysinstall, and any
   other place that needs to read or write such archives.

Features:
  * Full automatic detection of both compression and archive format.
  * Extensible internal architecture to make it easy to add new formats.
  * Support for "pax interchange format," a new POSIX-standard tar format
    that eliminates essentially all of the restrictions of historic formats.
  * BSD license

Thanks to: jkh for pushing me to start this work, gordon for
  encouraging me to commit it, bde for answering endless style
  questions, and many others for feedback and encouragement.

Status: Pretty good overall, though there are still a few rough edges and
  the library could always use more testing.  Feedback eagerly solicited.

1 files changed, 368 insertions, 0 deletions

diff --git a/lib/libarchive/archive_write.3 b/lib/libarchive/archive_write.3
new file mode 100644
index 0000000..2cebaab
--- /dev/null
+++ b/lib/libarchive/archive_write.3
@@ -0,0 +1,368 @@
+.\" Copyright (c) 2003-2004 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 October 1, 2003
+.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_file ,
+.Nm archive_write_open_tar ,
+.Nm archive_write_prepare ,
+.Nm archive_write_header ,
+.Nm archive_write_data ,
+.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_write_archive_callback *" "archive_open_archive_callback *" "archive_close_archive_callback *"
+.Ft int
+.Fn archive_write_open_file "struct archive *" "const char *filename"
+.Ft int
+.Fn archive_write_open_tar "struct archive *" "const char *archive_name"
+.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_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
+affects this).
+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 library to write the constructed archive.
+.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_open_tar
+A convenience form of
+.Fn archive_write_open
+that accepts an archive name in the same formats accepted by
+.Xr tar 1 .
+In particular, a
+.Pa -
+argument indicates that the output should be written to standard output.
+.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.
+.It Fn archive_write_finish
+Complete the archive, invoke the close callback, and release
+all resources.
+.El
+.Pp
+The callback functions are defined as follows:
+.Bl -item -offset indent
+.It
+.Ft typedef ssize_t
+.Fn archive_write_archive_callback "struct archive *" "void *client_data" "void *buffer" "size_t length"
+.It
+.Ft typedef int
+.Fn archive_open_archive_callback "struct archive *" "void *client_data"
+.It
+.Ft typedef int
+.Fn archive_close_archive_callback "struct archive *" "void *client_data"
+.El
+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 tar archives to tape drives.
+.Pp
+More information about tar archive formats and blocking can be found
+in the
+.Xr tar 5
+manual page.
+.Pp
+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 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 -1, 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_finish .
+In such a case, the
+.Fn archive_errno
+or
+.Fn archive_error_string
+fields will not return useful information; you should use
+client-private data to return error information
+back to your mainline code.
+.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.