d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
022c9a28ee
freebsd-dev/lib/libarchive/archive.h.in
Tim Kientzle 91ce8f27d8 Split archive_{read,write}_finish into separate "close" (finish the archive 
and close it) and "finish" (destroy the object) functions.   For backwards
compat and simplicity, have "finish" invoke "close" transparently if needed.
This allows clients to close the archive and check end-of-operation
statistics before destroying the object.
2004-08-07 19:22:50 +00:00

316 lines
13 KiB
C
Raw Blame History

/*-
* 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
/*
* If ARCHIVE_API_VERSION != archive_api_version(), then the library you
* were linked with is using an incompatible API. This is almost
* certainly a fatal problem.
*
* ARCHIVE_API_FEATURE is incremented with each significant feature
* addition, so you can test (at compile or run time) if a particular
* feature is implemented. It's no big deal if ARCHIVE_API_FEATURE !=
* archive_api_feature(), as long as both are high enough to include
* the features you're relying on. Specific values of FEATURE are
* documented here:
*
* 1 - Version tests are available.
* 2 - archive_{read,write}_close available separately from _finish.
*/
#define ARCHIVE_API_VERSION @ARCHIVE_API_VERSION@
int archive_api_version(void);
#define ARCHIVE_API_FEATURE @ARCHIVE_API_FEATURE@
int archive_api_feature(void);
/* Textual name/version of the library. */
const char * archive_version(void);
#include <sys/types.h> /* Linux requires this for off_t */
#include <inttypes.h> /* For int64_t */
#include <unistd.h> /* For ssize_t and size_t */
#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_RETRY (-10) /* Retry might succeed. */
#define ARCHIVE_WARN (-20) /* Partial sucess. */
#define ARCHIVE_FATAL (-30) /* No more operations are possible. */
/*
* As far as possible, archive_errno returns standard platform errno codes.
* Of course, the details vary by platform, so the actual definitions
* here are stored in "archive_platform.h". The symbols are listed here
* for reference; as a rule, clients should not need to know the exact
* platform-dependent error code.
*/
/* Unrecognized or invalid file format. */
/* #define ARCHIVE_ERRNO_FILE_FORMAT */
/* Illegal usage of the library. */
/* #define ARCHIVE_ERRNO_PROGRAMMER_ERROR */
/* Unknown or unclassified error. */
/* #define ARCHIVE_ERRNO_MISC */
/*
* 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
#define ARCHIVE_COMPRESSION_COMPRESS 3
/*
* 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 end processing.
*/
struct archive *archive_read_new(void);
/*
* 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_compress(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);
int archive_read_open_fd(struct archive *, int _fd,
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);
/*
* A zero-copy version of archive_read_data that also exposes the file offset
* of each returned block. Note that the client has no way to specify
* the desired size of the block. The API does gaurantee that offsets will
* be strictly increasing and that returned blocks will not overlap.
*/
int archive_read_data_block(struct archive *a,
const void **buff, size_t *size, off_t *offset);
/*-
* 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_fd': writes data to specified filedes
*/
int archive_read_data_skip(struct archive *);
int archive_read_data_into_buffer(struct archive *, void *buffer,
ssize_t len);
int 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 */
#define ARCHIVE_EXTRACT_UNLINK (16) /* Default: don't unlink existing files */
#define ARCHIVE_EXTRACT_ACL (32) /* Default: don't restore ACLs */
#define ARCHIVE_EXTRACT_FFLAGS (64) /* Default: don't restore fflags */
int archive_read_extract(struct archive *, struct archive_entry *,
int flags);
void archive_read_extract_set_progress_callback(struct archive *,
void (*_progress_func)(void *), void *_user_data);
/* Close the file and release most resources. */
int archive_read_close(struct archive *);
/* Release all resources and destroy the object. */
/* Note that archive_read_finish will call archive_read_close for you. */
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_close to close the output
* 6) archive_write_finish to cleanup the writer and release resources
*/
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_fd(struct archive *, int _fd);
int archive_write_open_file(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);
int archive_write_close(struct archive *);
void archive_write_finish(struct archive *);
/*
* Accessor functions to read/set various information in
* the struct archive object:
*/
/* Bytes written after compression or read before decompression. */
int64_t archive_position_compressed(struct archive *);
/* Bytes written to compressor or read from decompressor. */
int64_t archive_position_uncompressed(struct archive *);
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_error(struct archive *, int _err, const char *fmt, ...);
#endif /* !ARCHIVE_H_INCLUDED */
Reference in New Issue View Git Blame Copy Permalink