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, 266 insertions, 0 deletions

diff --git a/lib/libarchive/archive.h.in b/lib/libarchive/archive.h.in
new file mode 100644
index 0000000..54fafcb
--- /dev/null
+++ b/lib/libarchive/archive.h.in
@@ -0,0 +1,266 @@
+/*-
+ * 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
+ *    in this position and unchanged.
+ * 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(S) ``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(S) 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$
+ */
+
+#ifndef ARCHIVE_H_INCLUDED
+#define	ARCHIVE_H_INCLUDED
+
+#include <stdarg.h>
+#include <stdint.h>
+#include <unistd.h>
+
+#define	ARCHIVE_BYTES_PER_RECORD	  512
+#define	ARCHIVE_DEFAULT_BYTES_PER_BLOCK	10240
+
+/* Declare our basic types. */
+struct archive;
+struct archive_entry;
+
+/*
+ * Error codes: Use archive_errno() and archive_error_string()
+ * to retrieve details.  Unless specified otherwise, all functions
+ * that return 'int' use these codes.
+ */
+#define	ARCHIVE_EOF	  1	/* Found end of archive. */
+#define	ARCHIVE_OK	  0	/* Operation was successful. */
+#define	ARCHIVE_WARN	(-1)	/* Sucess, but minor problem. */
+#define	ARCHIVE_RETRY	(-2)	/* Retry might succeed. */
+#define	ARCHIVE_FATAL	(-3)	/* No more operations are possible. */
+
+/*
+ * Callbacks are invoked to automatically read/write/open/close the archive.
+ * You can provide your own for complex tasks (like breaking archives
+ * across multiple tapes) or use standard ones built into the library.
+ */
+
+/* Returns pointer and size of next block of data from archive. */
+typedef ssize_t	archive_read_callback(struct archive *, void *_client_data,
+		    const void **_buffer);
+/* Returns size actually written, zero on EOF, -1 on error. */
+typedef ssize_t	archive_write_callback(struct archive *, void *_client_data,
+		    void *_buffer, size_t _length);
+typedef int	archive_open_callback(struct archive *, void *_client_data);
+typedef int	archive_close_callback(struct archive *, void *_client_data);
+
+/*
+ * Codes for archive_compression.
+ */
+#define	ARCHIVE_COMPRESSION_NONE	0
+#define	ARCHIVE_COMPRESSION_GZIP	1
+#define	ARCHIVE_COMPRESSION_BZIP2	2
+
+/*
+ * Codes returned by archive_format.
+ *
+ * Top 16 bits identifies the format family (e.g., "tar"); lower
+ * 16 bits indicate the variant.  This is updated by read_next_header.
+ * Note that the lower 16 bits will often vary from entry to entry.
+ */
+#define	ARCHIVE_FORMAT_BASE_MASK		0xff0000U
+#define	ARCHIVE_FORMAT_CPIO			0x10000
+#define	ARCHIVE_FORMAT_CPIO_POSIX		(ARCHIVE_FORMAT_CPIO | 1)
+#define ARCHIVE_FORMAT_SHAR			0x20000
+#define ARCHIVE_FORMAT_SHAR_BASE		(ARCHIVE_FORMAT_SHAR | 1)
+#define ARCHIVE_FORMAT_SHAR_DUMP		(ARCHIVE_FORMAT_SHAR | 2)
+#define	ARCHIVE_FORMAT_TAR			0x30000
+#define	ARCHIVE_FORMAT_TAR_USTAR		(ARCHIVE_FORMAT_TAR | 1)
+#define	ARCHIVE_FORMAT_TAR_PAX_INTERCHANGE	(ARCHIVE_FORMAT_TAR | 2)
+#define	ARCHIVE_FORMAT_TAR_PAX_RESTRICTED	(ARCHIVE_FORMAT_TAR | 3)
+#define	ARCHIVE_FORMAT_TAR_GNUTAR		(ARCHIVE_FORMAT_TAR | 4)
+
+/*-
+ * Basic outline for reading an archive:
+ *   1) Ask archive_read_new for an archive reader object.
+ *   2) Update any global properties as appropriate.
+ *      In particular, you'll certainly want to call appropriate
+ *      archive_read_support_XXX functions.
+ *   3) Call archive_read_open_XXX to open the archive
+ *   4) Repeatedly call archive_read_next_header to get information about
+ *      successive archive entries.  Call archive_read_data to extract
+ *      data for entries of interest.
+ *   5) Call archive_read_finish to destroy the object.
+ */
+struct archive	*archive_read_new(void);
+
+/*
+ * XXX Kill this function.  The client callback is now responsible for
+ * read blocking. XXX
+ */
+/*
+  int		 archive_read_set_bytes_per_block(struct archive *,
+		     int bytes_per_blk);
+*/
+
+/*
+ * The archive_read_support_XXX calls enable auto-detect for this
+ * archive handle.  They also link in the necessary support code.
+ * For example, if you don't want bzlib linked in, don't invoke
+ * support_compression_bzip2().  The "all" functions provide the
+ * obvious shorthand.
+ */
+int		 archive_read_support_compression_all(struct archive *);
+int		 archive_read_support_compression_bzip2(struct archive *);
+int		 archive_read_support_compression_gzip(struct archive *);
+int		 archive_read_support_compression_none(struct archive *);
+
+int		 archive_read_support_format_all(struct archive *);
+int		 archive_read_support_format_cpio(struct archive *);
+int		 archive_read_support_format_gnutar(struct archive *);
+int		 archive_read_support_format_tar(struct archive *);
+
+
+/* Open the archive using callbacks for archive I/O. */
+int		 archive_read_open(struct archive *, void *_client_data,
+		     archive_open_callback *, archive_read_callback *,
+		     archive_close_callback *);
+
+/*
+ * The archive_read_open_file function is a convenience function built
+ * on archive_read_open that uses a canned callback suitable for
+ * common situations.  Note that a NULL filename indicates stdin.
+ */
+int		 archive_read_open_file(struct archive *, const char *_file,
+		     size_t _block_size);
+
+/* Parses and returns next entry header. */
+int		 archive_read_next_header(struct archive *,
+		     struct archive_entry **);
+
+/*
+ * Retrieve the byte offset in UNCOMPRESSED data where last-read
+ * header started.
+ */
+int64_t		 archive_read_header_position(struct archive *);
+
+/* Read data from the body of an entry.  Similar to read(2). */
+ssize_t		 archive_read_data(struct archive *, void *, size_t);
+
+/*-
+ * Some convenience functions that are built on archive_read_data:
+ *  'skip': skips entire entry
+ *  'into_buffer': writes data into memory buffer that you provide
+ *  'into_file': writes data to specified filedes
+ */
+int		 archive_read_data_skip(struct archive *);
+ssize_t		 archive_read_data_into_buffer(struct archive *, void *buffer,
+		     ssize_t len);
+ssize_t		 archive_read_data_into_fd(struct archive *, int fd);
+
+/*-
+ * Convenience function to recreate the current entry (whose header
+ * has just been read) on disk.
+ *
+ * This does quite a bit more than just copy data to disk. It also:
+ *  - Creates intermediate directories as required.
+ *  - Manages directory permissions:  non-writable directories will
+ *    be initially created with write permission enabled; when the
+ *    archive is closed, dir permissions are edited to the values specified
+ *    in the archive.
+ *  - Checks hardlinks:  hardlinks will not be extracted unless the
+ *    linked-to file was also extracted within the same session. (TODO)
+ */
+
+/* The "flags" argument selects optional behavior, 'OR' the flags you want. */
+/* TODO: The 'Default' comments here are not quite correct; clean this up. */
+#define	ARCHIVE_EXTRACT_OWNER	(1) /* Default: owner/group not restored */
+#define	ARCHIVE_EXTRACT_PERM	(2) /* Default: restore perm only for reg file*/
+#define	ARCHIVE_EXTRACT_TIME	(4) /* Default: mod time not restored */
+#define	ARCHIVE_EXTRACT_NO_OVERWRITE (8) /* Default: Replace files on disk */
+
+int		 archive_read_extract(struct archive *, struct archive_entry *,
+		     int flags);
+
+/* Close the file, release any resources, and destroy the object. */
+void		 archive_read_finish(struct archive *);
+
+/*-
+ * To create an archive:
+ *   1) Ask archive_write_new for a archive writer object.
+ *   2) Set any global properties.  In particular, you should register
+ *      open/write/close callbacks.
+ *   3) Call archive_write_open to open the file
+ *   4) For each entry:
+ *      - construct an appropriate struct archive_entry structure
+ *      - archive_write_header to write the header
+ *      - archive_write_data to write the entry data
+ *   5) archive_write_finish to close the output and cleanup the writer
+ */
+struct archive	*archive_write_new(void);
+int		 archive_write_set_bytes_per_block(struct archive *,
+		     int bytes_per_block);
+/* XXX This is badly misnamed; suggestions appreciated. XXX */
+int		 archive_write_set_bytes_in_last_block(struct archive *,
+		     int bytes_in_last_block);
+
+int		 archive_write_set_compression_bzip2(struct archive *);
+int		 archive_write_set_compression_gzip(struct archive *);
+int		 archive_write_set_compression_none(struct archive *);
+/* A convenience function to set the format based on the code or name. */
+int		 archive_write_set_format(struct archive *, int format_code);
+int		 archive_write_set_format_by_name(struct archive *,
+		     const char *name);
+/* To minimize link pollution, use one or more of the following. */
+int		 archive_write_set_format_cpio(struct archive *);
+/* TODO: int archive_write_set_format_old_tar(struct archive *); */
+int		 archive_write_set_format_pax(struct archive *);
+int		 archive_write_set_format_pax_restricted(struct archive *);
+int		 archive_write_set_format_shar(struct archive *);
+int		 archive_write_set_format_shar_dump(struct archive *);
+int		 archive_write_set_format_ustar(struct archive *);
+int		 archive_write_open(struct archive *, void *,
+		     archive_open_callback *, archive_write_callback *,
+		     archive_close_callback *);
+int		 archive_write_open_file(struct archive *, const char *_file);
+int		 archive_write_open_file_position(struct archive *,
+		     const char *_filename, int64_t offset);
+int		 archive_write_open_tar(struct archive *, const char *_file);
+
+/*
+ * Note that the library will truncate writes beyond the size provided
+ * to archive_write_header or pad if the provided data is short.
+ */
+int		 archive_write_header(struct archive *,
+		     struct archive_entry *);
+int		 archive_write_data(struct archive *, const void *, size_t);
+void		 archive_write_finish(struct archive *);
+
+/*
+ * Accessor functions to read/set various information in
+ * the struct archive object:
+ */
+const char	*archive_compression_name(struct archive *);
+int		 archive_compression(struct archive *);
+int		 archive_errno(struct archive *);
+const char	*archive_error_string(struct archive *);
+const char	*archive_format_name(struct archive *);
+int		 archive_format(struct archive *);
+/* void		 archive_set_errno(struct archive *, int); */
+/* void		 archive_error_printf(struct archive *, const char *fmt, ...); */
+
+void		 archive_set_error(struct archive *, int _err, const char *fmt, ...);
+
+#endif /* !ARCHIVE_H_INCLUDED */