ARCHIVE_WRITE(3) Library Functions Manual ARCHIVE_WRITE(3)
NAME
archive_write — functions for creating archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
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.
Create archive object
See archive_write_new(3).
To write an archive, you must first obtain an initialized struct archive object from archive_write_new().
Enable filters and formats, configure block size and padding
See archive_write_filter(3), archive_write_format(3) and archive_write_blocksize(3).
You can then modify this object for the desired operations with the various archive_write_set_XXX() functions. In particular, you will need to invoke appropriate archive_write_add_XXX() and archive_write_set_XXX() functions to enable the corresponding compression and format support.
Set options
See archive_write_set_options(3).
Open archive
See archive_write_open(3).
Once you have prepared the struct archive object, you call archive_write_open() to actually open the archive and prepare it for writing. There are several variants of this function; the most basic expects you to provide pointers to several functions that can provide blocks of bytes from the archive. There are convenience forms that allow you to specify a filename, file descriptor, FILE * object, or a block of memory from which to write the archive data.
Produce archive
See archive_write_header(3) and archive_write_data(3).
Individual archive entries are written in a three-step process: You first initialize a struct archive_entry structure with information about the new entry. At a minimum, you should set the pathname of the entry and provide a struct stat with a valid st_mode field, which specifies the type of object and st_size field, which specifies the size of the data portion of the object.
Release resources
See archive_write_free(3).
After all entries have been written, use the archive_write_free() function to release all resources.
EXAMPLES
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);
}
la_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;
/* Set archive format and filter according to output file
extension.
* If it fails, set default format. Platform depended
function.
* See supported formats in
archive_write_set_format_filter_by_ext.c */
if (archive_write_set_format_filter_by_ext(a, outname) !=
ARCHIVE_OK) {
archive_write_add_filter_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);
if ((fd = open(*filename, O_RDONLY)) != -1) {
len = read(fd, buff, sizeof(buff));
while (len > 0) {
archive_write_data(a, buff, len);
len = read(fd, buff, sizeof(buff));
}
close(fd);
}
archive_entry_free(entry);
filename++;
}
archive_write_free(a);
}
int main(int
argc, const char **argv)
{
const char *outname;
argv++;
outname = *argv++;
write_archive(outname, argv);
return 0;
}
SEE ALSO
tar(1), archive_write_set_options(3), libarchive(3), cpio(5), mtree(5), tar(5)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle <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. Debian February 2, 2012 ARCHIVE_WRITE(3)
ARCHIVE_WRITE(3) BSD Library Functions Manual ARCHIVE_WRITE(3)
d28 2 a29 2archive_write — functions for creating archives
d33 1 a33 1Streaming Archive Library d38 1 a38 1
#include d43 1 a43 1
These functions provide a d50 2 a51 3
Create
archive object
See archive_write_new(3).
To write an d60 8 a67 5
Enable
filters and formats, configure block size and padding
See archive_write_filter(3), archive_write_format(3) and
archive_write_blocksize(3).
You can then d77 11 a87 7
Set
options
See archive_write_set_options(3).
Open
archive
See archive_write_open(3).
Once you have d100 2 a101 3
Produce
archive
See archive_write_header(3) and archive_write_data(3).
Individual d116 5 a120 3
Release
resources
See archive_write_free(3).
After all d129 1 a129 1
The following sketch illustrates d131 3 a133 2 functions are simply wrappers around the standard open(2), write(2), and close(2) system calls.
d135 1 a135 1#ifdef d141 1 a141 1
#endif
d162 1
a162 1
struct mydata { d168 1 a168 1
int
d173 1
a173 1
mydata->fd = d181 1 a181 1
la_ssize_t
d187 1
a187 1
return d191 1 a191 1
int
d196 1
a196 1
if d202 1 a202 1
void
d214 1
a214 1
a = d250 1 a250 1
int main(int d262 3 a264 3
tar(1), archive_write_set_options(3), libarchive(3), cpio(5), mtree(5), tar(5)
d268 1 a268 1The libarchive library d273 1 a273 1
The libarchive library d278 1 a278 1
There are many peculiar bugs in d286 1 a286 1
The default pax d299 2 a300 4 device numbers from archives created by this library.
BSD February 2, 2012 BSD
@ 1.11 log @libarchive: updated to 3.7.4 Libarchive 3.7.4 is a bugfix and security release Security fixes: rar: Fix OOB in rar e8 filter (CVE-2024-26256) zip: Fix out of boundary access Important bugfixes: 7zip: Limit amount of properties bsdtar: Fix error handling around strtol() usages passphrase: Improve newline handling on Windows passphrase: Never allow empty passwords rar: Fix "File CRC Error" when extracting specific rar4 archives xar: Avoid infinite link loop zip: Update AppleDouble support for directories zstd: Implement core detection @ text @d2 1 a2 1 @ 1.10 log @libarchive: updated to 3.7.3 Libarchive 3.7.3 is a feature, security and bugfix release. New features: PCRE2 support add trailing letter b to bsdtar(1) substitute pattern add support for long options "--group" and "--owner" to tar(1) Security fixes: Fix possible vulnerability in tar error reporting introduced in f27c173 Important bugfixes: ISO9660: preserve the natural order of links rar5: fix decoding unicode filenames on Windows rar5: fix infinite loop if during rar5 decompression the last block produced no data xz filter: fix incorrect eof at the end of an lzip member zip: fix end-of-data marker processing when decompressing zip archives multiple bsdunzip(1) fixes filetime truncation fix on Windows @ text @d2 1 a2 1 @ 1.9 log @libarchive: updated to 3.7.2 Libarchive 3.7.2 is a security, bugfix and feature release. Security fixes: Multiple vulnerabilities have been fixed in the PAX writer (1b4e0d0) Important bugfixes: bsdunzip(1) now correctly handles arguments following an -x after the zipfile New features: bsdunzip(1) now supports the "--version" flag 7-zip reader now translates Windows permissions into UNIX permissions uudecode filter in raw mode now supports file name and file mode zstd filter now supports the "long" write option Libarchive 3.7.1 is a security, feature and bugfix release. Security fixes: SEGV and stack buffer overflow in verbose mode of cpio Feature updates: bsdunzip updated to match latest upstream code Important bugfixes: miscellaneous functional bugfixes build fixes on multiple platforms Libarchive 3.7.0 is a feature and bugfix release. New features: bsdunzip: new tool ported from FreeBSD drop-in replacement for Info-ZIP unzip, not yet ported for Windows 7zip reader: support for Zstandard compression 7zip reader: support for ARM64 filter zstd filter: support for multi-frame zstd archives Other notable bugfixes and improvements: pax: fix year 2038 problem on platforms with 64-bit time_t Windows: Universal Windows Platform (UWP) fixes and improvements Windows: bcrypt usage fixes and improvements Windows: time function usage fixes and improvements @ text @d2 1 a2 1 @ 1.8 log @libarchive: Update to 3.4.3 Libarchive 3.4.3 is a feature and bugfix release. New features: support for pzstd compressed files (#1357) support for RHT.security.selinux tar extended attribute (#1348) Important bugfixes: various zstd fixes and improvements (#1342 #1352 #1359) child process handling fixes (#1372) Libarchive 3.4.2 is a feature and security release. New features: support for atomic file extraction (bsdtar -x --safe-writes) (#1289) support for mbed TLS (PolarSSL) (#1301) Important bugfixes: security fixes in RAR5 reader (#1280 #1326) compression buffer fix in XAR writer (#1317) fix uname and gname longer than 32 characters in PAX writer (#1319) fix segfault when archiving hard links in ISO9660 and XAR writers (#1325) fix support for extracting 7z archive entries with Delta filter (#987) Libarchive 3.4.1 is a feature and security release. New features: Unicode filename support for reading lha/lzh archives New pax write option "xattrhdr" Important bugfixes: security fixes in wide string processing (#1276 #1298) security fixes in RAR5 reader (#1212 #1217 #1296) security fixes and optimizations to write filter logic (#351) security fix related to use of readlink(2) (1dae5a5) sparse file handling fixes (#1218 #1260) Thanks to all contributors and bug reporters. Special thanks to Christos Zoulas (@@zoulasc) from NetBSD for the atomic file extraction feature. @ text @d1 2 a2 2 d277 5 a281 5 ’’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 @ 1.7 log @Update for libarchive-3.4.0: - improvements for Android APK and JAR archives - better support for non-recursive list and extract - tar --exclude-vcs support - fixes for file attributes and flags handling - zipx support - rar 5.0 reader @ text @d1 2 a2 2 d113 1 a113 1EXAMPLE
d247 3 a249 2tar(1), libarchive(3), archive_write_set_options(3), cpio(5), mtree(5), tar(5)
d277 5 a281 5 “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 @ 1.6 log @libarchive: updated to 3.3.3 libarchive 3.3.3: Avoid super-linear slowdown on malformed mtree files Many fixes for building with Visual Studio NO_OVERWRITE doesn't change existing directory attributes New support for Zstandard read and write filters @ text @d1 2 a2 2 d276 5 a280 5 ’’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 @ 1.5 log @Merge for libarchive-3.3.2. @ text @d2 1 a2 1 d74 1 a74 1 See archive_read_set_options(3). @ 1.4 log @Merge libarchive-3.3.1. @ text @d2 1 a2 1 d276 2 a277 2 ‘‘SCHILY.devminor’’ and ‘‘SCHILY.devmajor’’ for device @ 1.3 log @Update for libarchive 3.2.1. @ text @d2 1 a2 1 d276 2 a277 2 ’’SCHILY.devminor’’ and ’’SCHILY.devmajor’’ for device @ 1.2 log @Changes 3.1.2: This is a maintenance update to fix issues with the new RAR seeking feature. This new release also contains fixes for build failures when building libarchive using Visual Studio 2012 and MinGW. @ text @d1 2 a2 2 d166 1 a166 1ssize_t
d202 8
d212 1
d223 1
a223 1
while ( len > 0 ) {
d240 1
a240 1
outname = argv++;
d258 1
a258 2
was written by Tim Kientzle ⟨ kientzle@@acm.org⟩
.
archive_write(3) FreeBSD Library Functions Manual archive_write(3)
d26 1 a26 1NAME
d28 2 a29 26archive_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
d31 1 d33 2 a34 1SYNOPSIS
d36 3 a38 1#include d41 1 a41 107
struct archive *
archive_write_new(void);
int
archive_write_get_bytes_per_block(struct archive *);
int
archive_write_set_bytes_per_block(struct archive *, int bytes_per_block);
int
archive_write_set_bytes_in_last_block(struct archive *, int);
int
archive_write_set_compression_bzip2(struct archive *);
int
archive_write_set_compression_compress(struct archive *);
int
archive_write_set_compression_gzip(struct archive *);
int
archive_write_set_compression_none(struct archive *);
int
archive_write_set_compression_program(struct archive *, const char * cmd);
int
archive_write_set_format_cpio(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_binary(struct archive *);
int
archive_write_set_format_ustar(struct archive *);
int
archive_write_set_format_options(struct archive *, const char *);
int
archive_write_set_compressor_options(struct archive *, const char *);
int
archive_write_set_options(struct archive *, const char *);
int
archive_write_open(struct archive *, void *client_data, archive_open_callback *, archive_write_callback *, archive_close_callback *);
int
d43 1 a43 55archive_write_open_fd(struct archive *, int fd);
int
archive_write_open_FILE(struct archive *, FILE *file);
int
archive_write_open_filename(struct archive *, const char *filename);
int
archive_write_open_memory(struct archive *, void *buffer, size_t bufferSize, size_t *outUsed);
int
archive_write_header(struct archive *, struct archive_entry *);
ssize_t
archive_write_data(struct archive *, const void *, size_t);
int
archive_write_finish_entry(struct archive *);
int
archive_write_close(struct archive *);
int
archive_write_finish(struct archive *);
DESCRIPTION
These functions provide a d48 1 a48 2 resources. The following summary describes the functions in approximately the order they are ordinarily used:
d50 7 d58 5 a62 113archive_write_new()
Allocates and initializes a struct archive object suitable for writing a tar archive.
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.
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.
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 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.
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.
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()
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.
archive_write_set_compression_bzip2(), archive_write_set_compression_compress(), archive_write_set_compression_gzip(), archive_write_set_compression_none()
The resulting archive will be compressed as specified. Note that the compressed output is always properly blocked.
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.
archive_write_set_compressor_options(), archive_write_set_format_options(), 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.
d64 48 a111 1option
d113 1 a113 3The option will be provided to every module with a value of ‘‘1’’.
d115 1 a115 234!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
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.
archive_write_open_fd()
A convenience form of archive_write_open() that accepts a file descriptor. The archive_write_open_fd() function is safe for use with tape drives or other block-oriented devices.
archive_write_open_FILE()
A convenience form of archive_write_open() that accepts a FILE * pointer. Note that archive_write_open_FILE() is not safe for writing to tape drives or other devices that require correct blocking.
archive_write_open_file()
A deprecated synonym for archive_write_open_filename().
archive_write_open_filename()
A convenience form of 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 archive_write_set_bytes_in_last_block(), then 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 archive_write_set_bytes_in_last_block() before calling archive_write_open(). The archive_write_open_filename() function is safe for use with tape drives or other block-oriented devices.
archive_write_open_memory()
A convenience form of archive_write_open() that accepts a pointer to a block of memory that will receive the archive. The final 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.
archive_write_header()
Build and write a header using the data in the provided struct archive_entry structure. See archive_entry(3) for information on creating and populating struct archive_entry objects.
archive_write_data()
Write data corresponding to the header just written. Returns number of bytes written or -1 on error.
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 archive_write_next_header() and archive_write_close() as needed.
archive_write_close()
Complete the archive and invoke the close callback.
archive_write_finish()
Invokes archive_write_close() if it was not invoked manually, then releases all resources. Note that this function was declared to return void in libarchive 1.x, which made it impossible to detect errors when 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 archive_write_open():
typedef int archive_open_callback(struct archive *, void *client_data)
The open callback is invoked by 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 archive_set_error() to register an error code and message and return ARCHIVE_FATAL.
typedef ssize_t
archive_write_callback(struct archive *, void *client_data, const void *buffer, size_t length)
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 archive_set_error() to register an error code and message and return -1.
typedef int 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 archive_set_error() to register an error code and message and return ARCHIVE_FATAL.
EXAMPLE
The following sketch illustrates d120 1 a120 1
#ifdef d123 1 a123 1
|
d130 2
a131 2
#define |
d134 3
a136 3
_FILE_OFFSET_BITS 64 |
d139 1 a139 1 |
|
const char *name; |
|
|
int fd; |
};
int
d158 1
a158 1
mydata->fd = d166 1 a166 1
ssize_t
d172 1
a172 1
return d176 1 a176 1
int
d181 1
a181 1
if d187 1 a187 1
void
d199 1
a199 1
a =
d202 1
a202 1
archive_write_set_compression_gzip(a);
d212 4
a215 1
fd = open(*filename, O_RDONLY);
d217 3
a219 19
while ( len > 0 ) {
|
archive_write_data(a, buff, len); |
|
|
len = read(fd, buff, sizeof(buff)); |
}
d223 1
a223 1
archive_write_finish(a);
d226 1
a226 1
int main(int d228 7 a234 31 {
|
const char *outname; |
|
|
argv++; |
|
|
outname = argv++; |
|
|
write_archive(outname, argv); |
|
|
d236 1
d238 2
a239 40
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 archive_errno() and archive_error_string() functions can be used to retrieve an appropriate error code and a textual error message.
archive_write_new() returns a pointer to a newly-allocated struct archive object.
archive_write_data() returns a count of the number of bytes actually written. On error, -1 is returned and the archive_errno() and 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 archive_write_header(), archive_write_data(), archive_write_close(), or archive_write_finish(). The client callback can call archive_set_error() to provide values that can then be retrieved by archive_errno() and archive_error_string().
d241 1 a241 1SEE ALSO
d243 1 a243 6tar(1), libarchive(3), tar(5)
HISTORY
The libarchive library d246 1 a246 1
AUTHORS
d248 3 a250 3The libarchive library was written by Tim Kientzle ⟨kientzle@@acm.org⟩.
d252 1 a252 1BUGS
d254 1 a254 1There are many peculiar bugs in d262 1 a262 1
The default pax d268 2 a269 2 ‘‘SCHILY.devminor’’ and ‘‘SCHILY.devmajor’’ for device d277 2 a278 3
FreeBSD 8.0 May 11, 2008 FreeBSD 8.0
@ 1.1.1.1 log @Import libarchive 2.8.0: - Infrastructure: - Allow command line tools as fallback for missing compression libraries. If compiled without gzip for example, gunzip will be used automatically. - Improved support for a number of platforms like high-resolution timestamps and Extended Attributes on various Unix systems - New convience interface for creating archives based on disk content, complement of the archive_write_disk interface. - Frontends: - bsdcpio ready for public consumption - hand-written date parser replaces the yacc code - Filter system: - Simplified read filter chains - Option support for filters - LZMA, XZ, uudecode handled - Format support: - Write support for mtree files based on file system or archive content - Basic read support for Joliet - Write support for zip files - Write support for shar archives, both text-only and binary-safe @ text @@ 1.1.1.2 log @libarchive-2.8.2: - Fix NULL deference for short self-extracting zip archives - Don't dereference symlinks on Linux when reading ACLs - Better detection of SHA2 support for old OpenSSL versions - Fix parsing of input files for bsdtar -T - Do not leak setup_xattr into the global namespace - Fix build when an older libarchive is already installed - Use O_BINARY opening files in bsdtar - Include missing archive_crc32.h - Correctly include iconv.h required by libxml2 @ text @d1 845 a845 1348 %!PS-Adobe-3.0 %%Creator: groff version 1.19.2 %%CreationDate: Sun Mar 14 02:49:16 2010 %%DocumentNeededResources: font Times-Roman %%DocumentSuppliedResources: procset grops 1.19 2 %%Pages: 107 %%PageOrder: Ascend %%DocumentMedia: Default 612 792 0 () () %%Orientation: Portrait %%EndComments %%BeginDefaults %%PageMedia: Default %%EndDefaults %%BeginProlog %%BeginResource: procset grops 1.19 2 %!PS-Adobe-3.0 Resource-ProcSet /setpacking where{ pop currentpacking true setpacking }if /grops 120 dict dup begin /SC 32 def /A/show load def /B{0 SC 3 -1 roll widthshow}bind def /C{0 exch ashow}bind def /D{0 exch 0 SC 5 2 roll awidthshow}bind def /E{0 rmoveto show}bind def /F{0 rmoveto 0 SC 3 -1 roll widthshow}bind def /G{0 rmoveto 0 exch ashow}bind def /H{0 rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def /I{0 exch rmoveto show}bind def /J{0 exch rmoveto 0 SC 3 -1 roll widthshow}bind def /K{0 exch rmoveto 0 exch ashow}bind def /L{0 exch rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def /M{rmoveto show}bind def /N{rmoveto 0 SC 3 -1 roll widthshow}bind def /O{rmoveto 0 exch ashow}bind def /P{rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def /Q{moveto show}bind def /R{moveto 0 SC 3 -1 roll widthshow}bind def /S{moveto 0 exch ashow}bind def /T{moveto 0 exch 0 SC 5 2 roll awidthshow}bind def /SF{ findfont exch [exch dup 0 exch 0 exch neg 0 0]makefont dup setfont [exch/setfont cvx]cvx bind def }bind def /MF{ findfont [5 2 roll 0 3 1 roll neg 0 0]makefont dup setfont [exch/setfont cvx]cvx bind def }bind def /level0 0 def /RES 0 def /PL 0 def /LS 0 def /MANUAL{ statusdict begin/manualfeed true store end }bind def /PLG{ gsave newpath clippath pathbbox grestore exch pop add exch pop }bind def /BP{ /level0 save def 1 setlinecap 1 setlinejoin 72 RES div dup scale LS{ 90 rotate }{ 0 PL translate }ifelse 1 -1 scale }bind def /EP{ level0 restore showpage }def /DA{ newpath arcn stroke }bind def /SN{ transform .25 sub exch .25 sub exch round .25 add exch round .25 add exch itransform }bind def /DL{ SN moveto SN lineto stroke }bind def /DC{ newpath 0 360 arc closepath }bind def /TM matrix def /DE{ TM currentmatrix pop translate scale newpath 0 0 .5 0 360 arc closepath TM setmatrix }bind def /RC/rcurveto load def /RL/rlineto load def /ST/stroke load def /MT/moveto load def /CL/closepath load def /Fr{ setrgbcolor fill }bind def /setcmykcolor where{ pop /Fk{ setcmykcolor fill }bind def }if /Fg{ setgray fill }bind def /FL/fill load def /LW/setlinewidth load def /Cr/setrgbcolor load def /setcmykcolor where{ pop /Ck/setcmykcolor load def }if /Cg/setgray load def /RE{ findfont dup maxlength 1 index/FontName known not{1 add}if dict begin { 1 index/FID ne{def}{pop pop}ifelse }forall /Encoding exch def dup/FontName exch def currentdict end definefont pop }bind def /DEFS 0 def /EBEGIN{ moveto DEFS begin }bind def /EEND/end load def /CNT 0 def /level1 0 def /PBEGIN{ /level1 save def translate div 3 1 roll div exch scale neg exch neg exch translate 0 setgray 0 setlinecap 1 setlinewidth 0 setlinejoin 10 setmiterlimit []0 setdash /setstrokeadjust where{ pop false setstrokeadjust }if /setoverprint where{ pop false setoverprint }if newpath /CNT countdictstack def userdict begin /showpage{}def /setpagedevice{}def }bind def /PEND{ countdictstack CNT sub{end}repeat level1 restore }bind def end def /setpacking where{ pop setpacking }if %%EndResource %%EndProlog %%BeginSetup %%BeginFeature: *PageSize Default << /PageSize [ 612 792 ] /ImagingBBox null >> setpagedevice %%EndFeature %%IncludeResource: font Times-Roman grops begin/DEFS 1 dict def DEFS begin/u{.001 mul}bind def end/RES 72 def/PL 792 def/LS false def/ENC0[/asciicircum/asciitilde/Scaron/Zcaron /scaron/zcaron/Ydieresis/trademark/quotesingle/Euro/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef /.notdef/.notdef/space/exclam/quotedbl/numbersign/dollar/percent /ampersand/quoteright/parenleft/parenright/asterisk/plus/comma/hyphen /period/slash/zero/one/two/three/four/five/six/seven/eight/nine/colon /semicolon/less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N/O /P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright/circumflex /underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y /z/braceleft/bar/braceright/tilde/.notdef/quotesinglbase/guillemotleft /guillemotright/bullet/florin/fraction/perthousand/dagger/daggerdbl /endash/emdash/ff/fi/fl/ffi/ffl/dotlessi/dotlessj/grave/hungarumlaut /dotaccent/breve/caron/ring/ogonek/quotedblleft/quotedblright/oe/lslash /quotedblbase/OE/Lslash/.notdef/exclamdown/cent/sterling/currency/yen /brokenbar/section/dieresis/copyright/ordfeminine/guilsinglleft /logicalnot/minus/registered/macron/degree/plusminus/twosuperior /threesuperior/acute/mu/paragraph/periodcentered/cedilla/onesuperior /ordmasculine/guilsinglright/onequarter/onehalf/threequarters /questiondown/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE /Ccedilla/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex /Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis /multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute/Thorn /germandbls/agrave/aacute/acircumflex/atilde/adieresis/aring/ae/ccedilla /egrave/eacute/ecircumflex/edieresis/igrave/iacute/icircumflex/idieresis /eth/ntilde/ograve/oacute/ocircumflex/otilde/odieresis/divide/oslash /ugrave/uacute/ucircumflex/udieresis/yacute/thorn/ydieresis]def /Times-Roman@@0 ENC0/Times-Roman RE %%EndSetup %%Page: 1 1 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF()0 12 Q()0 24 Q(struct archi)0
72 Q -.15(ve)-.25 G( *).15 E 0 Cg EP
%%Page: 10 10
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G(_write_ne).15 E
(w\(v)-.25 E(oid\))-.2 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G(_write_get_bytes_per_block\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G(_write_set_bytes_per_block\(struct archi)
.15 E .3 -.15(ve *)-.25 H(, int bytes_per_block\))
.15 E(int)0 72 Q 0 Cg EP
%%Page: 11 11
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_set_bytes_in_last_block\(struct archi).15
E .3 -.15(ve *)-.25 H(, int\)).15 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G
(_write_set_compression_bzip2\(struct archi).15 E
.3 -.15(ve *)-.25 H(\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G
(_write_set_compression_compress\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 12 12
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_set_compression_gzip\(struct archi).15 E
.3 -.15(ve *)-.25 H(\)).15 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G(_write_set_compression_none\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G
(_write_set_compression_program\(struct archi).15
E .3 -.15(ve *)-.25 H(, const char * cmd\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 13 13
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_set_format_cpio\(struct archi).15 E .3
-.15(ve *)-.25 H(\)).15 E(int)0
24 Q(archi)0 36 Q -.15(ve)-.25 G
(_write_set_format_pax\(struct archi).15 E .3
-.15(ve *)-.25 H(\)).15 E(int)0
48 Q(archi)0 60 Q -.15(ve)-.25 G
(_write_set_format_pax_restricted\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 14 14
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_set_format_shar\(struct archi).15 E .3
-.15(ve *)-.25 H(\)).15 E(int)0
24 Q(archi)0 36 Q -.15(ve)-.25 G
(_write_set_format_shar_binary\(struct archi).15
E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G(_write_set_format_ustar\(struct archi).15
E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 15 15
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_set_format_options\(struct archi).15 E .3
-.15(ve *)-.25 H(, const char *\)).15 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G
(_write_set_compressor_options\(struct archi).15
E .3 -.15(ve *)-.25 H(, const char *\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G(_write_set_options\(struct archi).15 E .3
-.15(ve *)-.25 H(, const char *\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 16 16
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_open\(struct archi)0
24 Q .3 -.15(ve *)-.25 H().15 E(v)0 36 Q
(oid *client_data)-.2 E(archi)0 48 Q -.15(ve)
-.25 G(_open_callback *).15 E(archi)0 60 Q
-.15(ve)-.25 G(_write_callback *).15 E(archi)0
72 Q -.15(ve)-.25 G(_close_callback *).15 E 0 Cg EP
%%Page: 17 17
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(\))0 12 Q(int)
0 24 Q(archi)0 36 Q -.15(ve)-.25 G
(_write_open_fd\(struct archi).15 E .3 -.15(ve *)
-.25 H(, int fd\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G(_write_open_FILE\(struct archi).15 E .3
-.15(ve *)-.25 H(, FILE *\214le\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 18 18
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_open_\214lename\(struct archi).15 E .3
-.15(ve *)-.25 H(, const char *\214lename\)).15 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G(_write_open_memory\(struct archi)0 48 Q .3 -.15(ve *)-.25 H().15
E(v)0 60 Q(oid *b)-.2 E(uf)-.2 E(fer)-.25 E
(size_t b)0 72 Q(uf)-.2 E(ferSize)-.25 E 0 Cg
EP
%%Page: 19 19
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(size_t *outUsed)0 12 Q
(\))0 24 Q(int)0 36 Q(archi)0 48 Q
-.15(ve)-.25 G(_write_header\(struct archi).15 E
.3 -.15(ve *)-.25 H(, struct archi).15 E -.15(ve)-.25 G
(_entry *\)).15 E(ssize_t)0 60
Q(archi)0 72 Q -.15(ve)-.25 G
(_write_data\(struct archi).15 E .3 -.15(ve *)
-.25 H(, const v).15 E(oid *, size_t\))
-.2 E 0 Cg EP
%%Page: 20 20
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(int)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_write_\214nish_entry\(struct archi).15 E .3
-.15(ve *)-.25 H(\)).15 E(int)0
36 Q(archi)0 48 Q -.15(ve)-.25 G
(_write_close\(struct archi).15 E .3 -.15(ve *)
-.25 H(\)).15 E(int)0 60 Q
(archi)0 72 Q -.15(ve)-.25 G
(_write_\214nish\(struct archi).15 E .3 -.15
(ve *)-.25 H(\)).15 E 0 Cg EP
%%Page: 21 21
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF()36 72 Q 0 Cg EP %%Page: 41 41 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(The currently supported options are:)0 12 Q (
FILE *)0 12 Q
(pointer)0 24 Q(.)-.55 E(Note that)0 36 Q(archi)0 48 Q -.15(ve)-.25 G
(_write_open_FILE\(size_t *)0 36 Q
(ar)0 48 Q(gument points to a v)-.18 E(ariable that will be updated)-.25
E(after each write to re\215ect ho)0 60 Q 2.5(wm)-.25 G(uch of the b)
-2.5 E(uf)-.2 E(fer)-.25 E(is currently in use.)0 72 Q 0 Cg EP
%%Page: 56 56
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF -1.1(Yo)0 12 S 2.5(us)1.1 G
(hould be careful to ensure that this v)-2.5 E(ariable)-.25 E
(remains allocated until after the archi)0 24 Q .3 -.15(ve i)-.25 H(s)
.15 E(closed.)0 36 Q(v)0 24 Q
(oid)-.2 E(in libarchi)0 36 Q .3 -.15(ve 1)-.25 H
(.x, which made it impossible to detect errors when).15 E(archi)0 48
Q -.15(ve)-.25 G(_write_close\(typedef int)0 48 Q
(archi)0 60 Q -.15(ve)-.25 G
(_open_callback\(struct archi).15 E .3 -.15(ve *)
-.25 H(, v).15 E(oid *client_data\))-.2 E()36 12 Q(The open callback is in)0 24 Q -.2
(vo)-.4 G -.1(ke).2 G 2.5(db).1 G(y)-2.5 E(archi)0 36 Q -.15(ve)-.25
G(_write_open\(\).).15 E(It should return)0 48 Q
(ARCHIVE_OK)0 60 Q
(if the underlying \214le or data source is successfully)0 72 Q 0 Cg EP
%%Page: 67 67
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(opened.)0 12 Q(If the open f)0 24 Q
(ails, it should call)-.1 E(archi)0 36 Q -.15(ve)-.25 G
(_set_error\(\)).15 E(to re)0 48 Q
(gister an error code and message and return)-.15 E(ARCHIVE_F)
0 60 Q -1.21 -1.11(AT A)-.74 H(L.)1.11 E(
typedef ssize_t)0 24 Q
(archi)0 36 Q -.15(ve)-.25 G(_write_callback\(struct archi)0 48 Q .3 -.15(ve *)-.25 H().15
E(v)0 60 Q(oid *client_data)-.2 E
(const v)0 72 Q(oid *b)-.2 E(uf)-.2 E(fer)-.25
E 0 Cg EP
%%Page: 69 69
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(size_t length)0 12 Q
(\))0 24 Q()36 48 Q(The write callback is in)0 60 Q -.2
(vo)-.4 G -.1(ke).2 G 2.5(dw).1 G(hene)-2.5 E -.15(ve)-.25 G 2.5(rt).15
G(he library)-2.5 E(needs to write ra)0 72 Q 2.5(wb)-.15 G
(ytes to the archi)-2.5 E -.15(ve)-.25 G(.).15 E 0 Cg EP
%%Page: 70 70
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF -.15(Fo)0 12 S 2.5(rc).15 G
(orrect blocking, each call to the write callback function)-2.5 E
(should translate into a single)0 24 Q
(write\(2\))0 36 Q(system call.)0 48 Q
(This is especially critical when writing archi)0 60 Q -.15(ve)-.25 G
2.5(st).15 G 2.5(ot)-2.5 G(ape dri)-2.5 E -.15(ve)-.25 G(s.).15 E
(On success, the write callback should return the)0 72 Q 0 Cg EP
%%Page: 71 71
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(number of bytes actually written.)0 12 Q
(On error)0 24 Q 2.5(,t)-.4 G(he callback should in)-2.5 E -.2(vo)-.4 G
-.1(ke).2 G(archi)0 36 Q -.15(ve)-.25 G
(_set_error\(\)).15 E(to re)0 48 Q
(gister an error code and message and return -1.)-.15 E(
typedef int)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_close_callback\(struct archi).15 E .3 -.15
(ve *)-.25 H(, v).15 E(oid *client_data\))-.2 E
()36 48 Q(The close callback is in)0 60 Q -.2(vo)-.4 G
-.1(ke).2 G 2.5(db).1 G 2.5(ya)-2.5 G(rchi)-2.5 E -.15(ve)-.25 G
(_close when).15 E(the archi)0 72 Q .3 -.15(ve p)-.25 H
(rocessing is complete.).15 E 0 Cg EP
%%Page: 73 73
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(The callback should return)0 12 Q
(ARCHIVE_OK)0 24 Q(on success.)0 36 Q(On f)0 48 Q
(ailure, the callback should in)-.1 E -.2(vo)-.4 G -.1(ke).2 G(archi)
0 60 Q -.15(ve)-.25 G(_set_error\(\)).15 E(to re)0 72 Q
(gister an error code and message and)-.15 E 0 Cg EP
%%Page: 74 74
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(return)0 12 Q(ARCHIVE_F)0 24 Q -1.21
-1.11(AT A)-.74 H(L.)1.11 E(
)0 36 Q()0 48 Q(#ifdef __linux__)0 60 Q 4.06
(#de\214ne _FILE_OFFSET_BITS)0 72 R(64)2.5 E 0 Cg EP
%%Page: 77 77
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(#endif)0 12 Q(#include )0 24 Q
(#include ).15 E(#include )-.65 E(#include )0 60 Q
(#include )-.4 E 0 Cg EP
%%Page: 78 78
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(#include )0 12 Q()36 24 Q
(struct mydata {)0 36 Q(const char *name;)36 48 Q(int fd;)36 60 Q(};)0
72 Q 0 Cg EP
%%Page: 79 79
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(
)36 12 Q(int)0 24 Q(myopen\(struct archi)0 36
Q .3 -.15(ve *)-.25 H(a, v).15 E(oid *client_data\))-.2 E({)0 48 Q
(struct mydata *mydata = client_data;)5 60 Q(
)36 72 Q 0 Cg EP
%%Page: 80 80
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(mydata->fd = open\(mydata->name, O_WR)5 12 Q
(ONL)-.4 E 2.5(Y|O)-1 G(_CREA)-2.5 E 1.48 -.74(T, 0)-1.11 H(644\);).74 E
(if \(mydata->fd >= 0\))5 24 Q(return \(ARCHIVE_OK\);)10 36 Q(else)5 48
Q(return \(ARCHIVE_F)10 60 Q -1.21 -1.11(AT A)-.74 H(L\);)1.11 E(})0 72
Q 0 Cg EP
%%Page: 81 81
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(
)36 12 Q(ssize_t)0 24 Q
(mywrite\(struct archi)0 36 Q .3 -.15(ve *)-.25 H(a, v).15 E
(oid *client_data, const v)-.2 E(oid *b)-.2 E(uf)-.2 E(f, size_t n\))
-.25 E({)0 48 Q(struct mydata *mydata = client_data;)5 60 Q(
)36 72 Q
0 Cg EP
%%Page: 82 82
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(return \(write\(mydata->fd, b)5 12 Q(uf)-.2 E
(f, n\)\);)-.25 E(})0 24 Q(
)36 36 Q(int)0 48 Q(myclose\(struct archi)
0 60 Q .3 -.15(ve *)-.25 H(a, v).15 E(oid *client_data\))-.2 E({)0 72 Q
0 Cg EP
%%Page: 83 83
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(struct mydata *mydata = client_data;)5 12 Q(
)
36 24 Q(if \(mydata->fd > 0\))5 36 Q(close\(mydata->fd\);)10 48 Q
(return \(0\);)5 60 Q(})0 72 Q 0 Cg EP
%%Page: 84 84
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(
)36 12 Q -.2(vo)0 24 S(id).2 E(write_archi)0
36 Q -.15(ve)-.25 G(\(const char *outname, const char **\214lename\)).15
E({)0 48 Q(struct mydata *mydata = malloc\(sizeof\(struct mydata\)\);)5
60 Q(struct archi)5 72 Q .3 -.15(ve *)-.25 H(a;).15 E 0 Cg EP
%%Page: 85 85
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(struct archi)5 12 Q -.15(ve)-.25 G
(_entry *entry;).15 E(struct stat st;)5 24 Q(char b)5 36 Q(uf)-.2 E
(f[8192];)-.25 E(int len;)5 48 Q(int fd;)5 60 Q(
)36 72 Q 0 Cg EP
%%Page: 86 86
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF 2.5(a=a)5 12 S(rchi)-2.5 E -.15(ve)-.25 G
(_write_ne).15 E(w\(\);)-.25 E(mydata->name = outname;)5 24 Q(archi)5 36
Q -.15(ve)-.25 G(_write_set_compression_gzip\(a\);).15 E(archi)5 48 Q
-.15(ve)-.25 G(_write_set_format_ustar\(a\);).15 E(archi)5 60 Q -.15(ve)
-.25 G(_write_open\(a, mydata, myopen, mywrite, myclose\);).15 E
(while \(*\214lename\) {)5 72 Q 0 Cg EP
%%Page: 87 87
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(stat\(*\214lename, &st\);)10 12 Q(entry = archi)
10 24 Q -.15(ve)-.25 G(_entry_ne).15 E(w\(\);)-.25 E(archi)10 36 Q -.15
(ve)-.25 G(_entry_cop).15 E(y_stat\(entry)-.1 E 2.5(,&)-.65 G(st\);)-2.5
E(archi)10 48 Q -.15(ve)-.25 G(_entry_set_pathname\(entry).15 E 2.5(,*)
-.65 G(\214lename\);)-2.5 E(archi)10 60 Q -.15(ve)-.25 G
(_write_header\(a, entry\);).15 E(fd = open\(*\214lename, O_RDONL)10 72
Q(Y\);)-1 E 0 Cg EP
%%Page: 88 88
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(len = read\(fd, b)10 12 Q(uf)-.2 E(f, sizeof\(b)
-.25 E(uf)-.2 E(f\)\);)-.25 E(while \( len > 0 \) {)10 24 Q(archi)36 36
Q -.15(ve)-.25 G(_write_data\(a, b).15 E(uf)-.2 E(f, len\);)-.25 E
(len = read\(fd, b)36 48 Q(uf)-.2 E(f, sizeof\(b)-.25 E(uf)-.2 E(f\)\);)
-.25 E(})10 60 Q(archi)10 72 Q -.15(ve)-.25 G(_entry_free\(entry\);).15
E 0 Cg EP
%%Page: 89 89
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(\214lename++;)10 12 Q(})5 24 Q(archi)5 36 Q -.15
(ve)-.25 G(_write_\214nish\(a\);).15 E(})0 48 Q(
)36 60 Q
(int main\(int ar)0 72 Q(gc, const char **ar)-.18 E(gv\))-.18 E 0 Cg EP
%%Page: 90 90
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF({)0 12 Q(const char *outname;)36 24 Q(ar)36 36 Q
(gv++;)-.18 E(outname = ar)36 48 Q(gv++;)-.18 E(write_archi)36 60 Q -.15
(ve)-.25 G(\(outname, ar).15 E(gv\);)-.18 E(return 0;)36 72 Q 0 Cg EP
%%Page: 91 91
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(})0 12 Q(
)0 24 Q()0 36 Q()36 12 Q(archi)0 24 Q -.15(ve)-.25 G
(_write_ne).15 E(w\(\))-.25 E
(returns a pointer to a ne)0 36 Q(wly-allocated)-.25 E(\
struct archi)0 48 Q -.15
(ve)-.25 G().15 E(object.)0 60 Q(
)36 72 Q 0 Cg EP
%%Page: 96 96
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_data\(\)).15 E
(returns a count of the number of bytes actually written.)0 24 Q
(On error)0 36 Q 2.5(,-)-.4 G 2.5(1i)-2.5 G 2.5(sr)-2.5 G
(eturned and the)-2.5 E(archi)0 48 Q -.15(ve)-.25 G
(_errno\(\)).15 E(and)0 60 Q(archi)0 72 Q -.15(ve)
-.25 G(_error_string\(\)).15 E 0 Cg EP
%%Page: 97 97
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(functions will return appropriate v)0 12 Q
(alues.)-.25 E(Note that if the client-pro)0 24 Q
(vided write callback function)-.15 E(returns a non-zero v)0 36 Q
(alue, that error will be propag)-.25 E(ated back to the caller)-.05 E
(through whate)0 48 Q -.15(ve)-.25 G 2.5(rA).15 G
(PI function resulted in that call, which)-2.5 E(may include)0 60 Q
(archi)0 72 Q -.15(ve)-.25 G(_write_header\(\),).15
E 0 Cg EP
%%Page: 98 98
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_data\(\),).15 E(archi)0 24 Q -.15(ve)-.25 G
(_write_close\(\),).15 E(or)0 36 Q(archi)0 48 Q -.15
(ve)-.25 G(_write_\214nish\(\).).15 E
(The client callback can call)0 60 Q(archi)0 72 Q -.15(ve)-.25 G
(_set_error\(\)).15 E 0 Cg EP
%%Page: 99 99
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(to pro)0 12 Q(vide v)-.15 E
(alues that can then be retrie)-.25 E -.15(ve)-.25 G 2.5(db).15 G(y)-2.5
E(archi)0 24 Q -.15(ve)-.25 G(_errno\(\)).15 E(and)0
36 Q(archi)0 48 Q -.15(ve)-.25 G(_error_string\(\).)
.15 E(
)36 36 Q(The)0 48 Q(libarchi)0 60 Q -.15(ve)-.25 G().15 E(library w)0 72 Q(as written by)-.1 E 0 Cg EP %%Page: 103 103 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF -.35(Ti)0 12 S 2.5(mK).35 G (ientzle <kientzle@@acm.or)-2.5 E(g>.)-.18 E(
)36 60 Q(The def)0 72 Q (ault pax interchange format eliminates most of the historic)-.1 E 0 Cg EP %%Page: 105 105 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(tar limitations and pro)0 12 Q (vides a generic k)-.15 E -.15(ey)-.1 G(/v).15 E(alue attrib)-.25 E (ute f)-.2 E(acility)-.1 E(for v)0 24 Q(endor)-.15 E(-de\214ned e)-.2 E (xtensions.)-.15 E(One o)0 36 Q -.15(ve)-.15 G(rsight in POSIX is the f) .15 E(ailure to pro)-.1 E(vide a standard attrib)-.15 E(ute)-.2 E (for lar)0 48 Q(ge de)-.18 E(vice numbers.)-.25 E(This library uses)0 60 Q -.74(``)0 72 S(SCHIL).74 E -1.29(Y.)-1 G(de)1.29 E(vminor')-.25 E(') -.74 E 0 Cg EP %%Page: 106 106 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(and)0 12 Q -.74(``)0 24 S(SCHIL).74 E -1.29(Y.) -1 G(de)1.29 E(vmajor')-.25 E(')-.74 E(for de)0 36 Q (vice numbers that e)-.25 E(xceed the range supported by the backw)-.15 E(ards-compatible)-.1 E(ustar header)0 48 Q(.)-.55 E(These k)0 60 Q -.15 (ey)-.1 G 2.5(sa).15 G(re compatible with Joer)-2.5 E 2.5(gS)-.18 G (chilling')-2.5 E(s)-.55 E(star)0 72 Q 0 Cg EP %%Page: 107 107 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G -.55(r.).15 G (Other implementations may not recognize these k)0 24 Q -.15(ey)-.1 G 2.5(sa).15 G(nd will thus be unable)-2.5 E(to correctly restore de)0 36 Q(vice nodes with lar)-.25 E(ge de)-.18 E(vice numbers from archi)-.25 E -.15(ve)-.25 G(s).15 E(created by this library)0 48 Q(.)-.65 E()0 60 Q()0 72 Q 0 Cg EP %%Trailer end %%EOF @ 1.1.1.3 log @libarchive-2.8.3: Build fix for Linux @ text @d1 1348 a1348 845
archive_write(3) FreeBSD Library Functions Manual archive_write(3)
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
#include <archive.h>
struct archive *
archive_write_new(void);
int
archive_write_get_bytes_per_block(struct archive *);
int
archive_write_set_bytes_per_block(struct archive *, int bytes_per_block);
int
archive_write_set_bytes_in_last_block(struct archive *, int);
int
archive_write_set_compression_bzip2(struct archive *);
int
archive_write_set_compression_compress(struct archive *);
int
archive_write_set_compression_gzip(struct archive *);
int
archive_write_set_compression_none(struct archive *);
int
archive_write_set_compression_program(struct archive *, const char * cmd);
int
archive_write_set_format_cpio(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_binary(struct archive *);
int
archive_write_set_format_ustar(struct archive *);
int
archive_write_set_format_options(struct archive *, const char *);
int
archive_write_set_compressor_options(struct archive *, const char *);
int
archive_write_set_options(struct archive *, const char *);
int
archive_write_open(struct archive *, void *client_data, 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 *, FILE *file);
int
archive_write_open_filename(struct archive *, const char *filename);
int
archive_write_open_memory(struct archive *, void *buffer, size_t bufferSize, size_t *outUsed);
int
archive_write_header(struct archive *, struct archive_entry *);
ssize_t
archive_write_data(struct archive *, const void *, size_t);
int
archive_write_finish_entry(struct archive *);
int
archive_write_close(struct archive *);
int
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:
archive_write_new()
Allocates and initializes a struct archive object suitable for writing a tar archive.
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.
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.
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 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.
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.
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()
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.
archive_write_set_compression_bzip2(), archive_write_set_compression_compress(), archive_write_set_compression_gzip(), archive_write_set_compression_none()
The resulting archive will be compressed as specified. Note that the compressed output is always properly blocked.
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.
archive_write_set_compressor_options(), archive_write_set_format_options(), 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
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.
archive_write_open_fd()
A convenience form of archive_write_open() that accepts a file descriptor. The archive_write_open_fd() function is safe for use with tape drives or other block-oriented devices.
archive_write_open_FILE()
A convenience form of archive_write_open() that accepts a FILE * pointer. Note that archive_write_open_FILE() is not safe for writing to tape drives or other devices that require correct blocking.
archive_write_open_file()
A deprecated synonym for archive_write_open_filename().
archive_write_open_filename()
A convenience form of 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 archive_write_set_bytes_in_last_block(), then 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 archive_write_set_bytes_in_last_block() before calling archive_write_open(). The archive_write_open_filename() function is safe for use with tape drives or other block-oriented devices.
archive_write_open_memory()
A convenience form of archive_write_open() that accepts a pointer to a block of memory that will receive the archive. The final 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.
archive_write_header()
Build and write a header using the data in the provided struct archive_entry structure. See archive_entry(3) for information on creating and populating struct archive_entry objects.
archive_write_data()
Write data corresponding to the header just written. Returns number of bytes written or -1 on error.
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 archive_write_next_header() and archive_write_close() as needed.
archive_write_close()
Complete the archive and invoke the close callback.
archive_write_finish()
Invokes archive_write_close() if it was not invoked manually, then releases all resources. Note that this function was declared to return void in libarchive 1.x, which made it impossible to detect errors when 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 archive_write_open():
typedef int archive_open_callback(struct archive *, void *client_data)
The open callback is invoked by 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 archive_set_error() to register an error code and message and return ARCHIVE_FATAL.
typedef ssize_t
archive_write_callback(struct archive *, void *client_data, const void *buffer, size_t length)
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 archive_set_error() to register an error code and message and return -1.
typedef int 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 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 archive_errno() and archive_error_string() functions can be used to retrieve an appropriate error code and a textual error message.
archive_write_new() returns a pointer to a newly-allocated struct archive object.
archive_write_data() returns a count of the number of bytes actually written. On error, -1 is returned and the archive_errno() and 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 archive_write_header(), archive_write_data(), archive_write_close(), or archive_write_finish(). The client callback can call archive_set_error() to provide values that can then be retrieved by archive_errno() and archive_error_string().
SEE ALSO
tar(1), libarchive(3), tar(5)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle ⟨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.
FreeBSD 9.0 May 11, 2008 FreeBSD 9.0
struct archi)0
72 Q -.15(ve)-.25 G( *).15 E 0 Cg EP
%%Page: 10 10
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G(_write_ne).15 E
(w\(v)-.25 E(oid\))-.2 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G(_write_get_bytes_per_block\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G(_write_set_bytes_per_block\(struct archi)
.15 E .3 -.15(ve *)-.25 H(, int bytes_per_block\))
.15 E(int)0 72 Q 0 Cg EP
%%Page: 11 11
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_set_bytes_in_last_block\(struct archi).15
E .3 -.15(ve *)-.25 H(, int\)).15 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G
(_write_set_compression_bzip2\(struct archi).15 E
.3 -.15(ve *)-.25 H(\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G
(_write_set_compression_compress\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 12 12
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_set_compression_gzip\(struct archi).15 E
.3 -.15(ve *)-.25 H(\)).15 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G(_write_set_compression_none\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G
(_write_set_compression_program\(struct archi).15
E .3 -.15(ve *)-.25 H(, const char * cmd\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 13 13
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_set_format_cpio\(struct archi).15 E .3
-.15(ve *)-.25 H(\)).15 E(int)0
24 Q(archi)0 36 Q -.15(ve)-.25 G
(_write_set_format_pax\(struct archi).15 E .3
-.15(ve *)-.25 H(\)).15 E(int)0
48 Q(archi)0 60 Q -.15(ve)-.25 G
(_write_set_format_pax_restricted\(struct archi)
.15 E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 14 14
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_set_format_shar\(struct archi).15 E .3
-.15(ve *)-.25 H(\)).15 E(int)0
24 Q(archi)0 36 Q -.15(ve)-.25 G
(_write_set_format_shar_binary\(struct archi).15
E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G(_write_set_format_ustar\(struct archi).15
E .3 -.15(ve *)-.25 H(\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 15 15
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_set_format_options\(struct archi).15 E .3
-.15(ve *)-.25 H(, const char *\)).15 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G
(_write_set_compressor_options\(struct archi).15
E .3 -.15(ve *)-.25 H(, const char *\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G(_write_set_options\(struct archi).15 E .3
-.15(ve *)-.25 H(, const char *\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 16 16
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_open\(struct archi)0
24 Q .3 -.15(ve *)-.25 H().15 E(v)0 36 Q
(oid *client_data)-.2 E(archi)0 48 Q -.15(ve)
-.25 G(_open_callback *).15 E(archi)0 60 Q
-.15(ve)-.25 G(_write_callback *).15 E(archi)0
72 Q -.15(ve)-.25 G(_close_callback *).15 E 0 Cg EP
%%Page: 17 17
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(\))0 12 Q(int)
0 24 Q(archi)0 36 Q -.15(ve)-.25 G
(_write_open_fd\(struct archi).15 E .3 -.15(ve *)
-.25 H(, int fd\)).15 E
(int)0 48 Q(archi)0 60 Q -.15(ve)
-.25 G(_write_open_FILE\(struct archi).15 E .3
-.15(ve *)-.25 H(, FILE *\214le\)).15 E
(int)0 72 Q 0 Cg EP
%%Page: 18 18
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_open_\214lename\(struct archi).15 E .3
-.15(ve *)-.25 H(, const char *\214lename\)).15 E
(int)0 24 Q(archi)0 36 Q -.15(ve)
-.25 G(_write_open_memory\(struct archi)0 48 Q .3 -.15(ve *)-.25 H().15
E(v)0 60 Q(oid *b)-.2 E(uf)-.2 E(fer)-.25 E
(size_t b)0 72 Q(uf)-.2 E(ferSize)-.25 E 0 Cg
EP
%%Page: 19 19
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(size_t *outUsed)0 12 Q
(\))0 24 Q(int)0 36 Q(archi)0 48 Q
-.15(ve)-.25 G(_write_header\(struct archi).15 E
.3 -.15(ve *)-.25 H(, struct archi).15 E -.15(ve)-.25 G
(_entry *\)).15 E(ssize_t)0 60
Q(archi)0 72 Q -.15(ve)-.25 G
(_write_data\(struct archi).15 E .3 -.15(ve *)
-.25 H(, const v).15 E(oid *, size_t\))
-.2 E 0 Cg EP
%%Page: 20 20
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(int)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_write_\214nish_entry\(struct archi).15 E .3
-.15(ve *)-.25 H(\)).15 E(int)0
36 Q(archi)0 48 Q -.15(ve)-.25 G
(_write_close\(struct archi).15 E .3 -.15(ve *)
-.25 H(\)).15 E(int)0 60 Q
(archi)0 72 Q -.15(ve)-.25 G
(_write_\214nish\(struct archi).15 E .3 -.15
(ve *)-.25 H(\)).15 E 0 Cg EP
%%Page: 21 21
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF()36 72 Q 0 Cg EP %%Page: 41 41 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(The currently supported options are:)0 12 Q (
FILE *)0 12 Q
(pointer)0 24 Q(.)-.55 E(Note that)0 36 Q(archi)0 48 Q -.15(ve)-.25 G
(_write_open_FILE\(size_t *)0 36 Q
(ar)0 48 Q(gument points to a v)-.18 E(ariable that will be updated)-.25
E(after each write to re\215ect ho)0 60 Q 2.5(wm)-.25 G(uch of the b)
-2.5 E(uf)-.2 E(fer)-.25 E(is currently in use.)0 72 Q 0 Cg EP
%%Page: 56 56
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF -1.1(Yo)0 12 S 2.5(us)1.1 G
(hould be careful to ensure that this v)-2.5 E(ariable)-.25 E
(remains allocated until after the archi)0 24 Q .3 -.15(ve i)-.25 H(s)
.15 E(closed.)0 36 Q(v)0 24 Q
(oid)-.2 E(in libarchi)0 36 Q .3 -.15(ve 1)-.25 H
(.x, which made it impossible to detect errors when).15 E(archi)0 48
Q -.15(ve)-.25 G(_write_close\(typedef int)0 48 Q
(archi)0 60 Q -.15(ve)-.25 G
(_open_callback\(struct archi).15 E .3 -.15(ve *)
-.25 H(, v).15 E(oid *client_data\))-.2 E()36 12 Q(The open callback is in)0 24 Q -.2
(vo)-.4 G -.1(ke).2 G 2.5(db).1 G(y)-2.5 E(archi)0 36 Q -.15(ve)-.25
G(_write_open\(\).).15 E(It should return)0 48 Q
(ARCHIVE_OK)0 60 Q
(if the underlying \214le or data source is successfully)0 72 Q 0 Cg EP
%%Page: 67 67
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(opened.)0 12 Q(If the open f)0 24 Q
(ails, it should call)-.1 E(archi)0 36 Q -.15(ve)-.25 G
(_set_error\(\)).15 E(to re)0 48 Q
(gister an error code and message and return)-.15 E(ARCHIVE_F)
0 60 Q -1.21 -1.11(AT A)-.74 H(L.)1.11 E(
typedef ssize_t)0 24 Q
(archi)0 36 Q -.15(ve)-.25 G(_write_callback\(struct archi)0 48 Q .3 -.15(ve *)-.25 H().15
E(v)0 60 Q(oid *client_data)-.2 E
(const v)0 72 Q(oid *b)-.2 E(uf)-.2 E(fer)-.25
E 0 Cg EP
%%Page: 69 69
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(size_t length)0 12 Q
(\))0 24 Q()36 48 Q(The write callback is in)0 60 Q -.2
(vo)-.4 G -.1(ke).2 G 2.5(dw).1 G(hene)-2.5 E -.15(ve)-.25 G 2.5(rt).15
G(he library)-2.5 E(needs to write ra)0 72 Q 2.5(wb)-.15 G
(ytes to the archi)-2.5 E -.15(ve)-.25 G(.).15 E 0 Cg EP
%%Page: 70 70
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF -.15(Fo)0 12 S 2.5(rc).15 G
(orrect blocking, each call to the write callback function)-2.5 E
(should translate into a single)0 24 Q
(write\(2\))0 36 Q(system call.)0 48 Q
(This is especially critical when writing archi)0 60 Q -.15(ve)-.25 G
2.5(st).15 G 2.5(ot)-2.5 G(ape dri)-2.5 E -.15(ve)-.25 G(s.).15 E
(On success, the write callback should return the)0 72 Q 0 Cg EP
%%Page: 71 71
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(number of bytes actually written.)0 12 Q
(On error)0 24 Q 2.5(,t)-.4 G(he callback should in)-2.5 E -.2(vo)-.4 G
-.1(ke).2 G(archi)0 36 Q -.15(ve)-.25 G
(_set_error\(\)).15 E(to re)0 48 Q
(gister an error code and message and return -1.)-.15 E(
typedef int)0 12 Q
(archi)0 24 Q -.15(ve)-.25 G
(_close_callback\(struct archi).15 E .3 -.15
(ve *)-.25 H(, v).15 E(oid *client_data\))-.2 E
()36 48 Q(The close callback is in)0 60 Q -.2(vo)-.4 G
-.1(ke).2 G 2.5(db).1 G 2.5(ya)-2.5 G(rchi)-2.5 E -.15(ve)-.25 G
(_close when).15 E(the archi)0 72 Q .3 -.15(ve p)-.25 H
(rocessing is complete.).15 E 0 Cg EP
%%Page: 73 73
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(The callback should return)0 12 Q
(ARCHIVE_OK)0 24 Q(on success.)0 36 Q(On f)0 48 Q
(ailure, the callback should in)-.1 E -.2(vo)-.4 G -.1(ke).2 G(archi)
0 60 Q -.15(ve)-.25 G(_set_error\(\)).15 E(to re)0 72 Q
(gister an error code and message and)-.15 E 0 Cg EP
%%Page: 74 74
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(return)0 12 Q(ARCHIVE_F)0 24 Q -1.21
-1.11(AT A)-.74 H(L.)1.11 E(
)0 36 Q()0 48 Q(#ifdef __linux__)0 60 Q 4.06
(#de\214ne _FILE_OFFSET_BITS)0 72 R(64)2.5 E 0 Cg EP
%%Page: 77 77
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(#endif)0 12 Q(#include )0 24 Q
(#include ).15 E(#include )-.65 E(#include )0 60 Q
(#include )-.4 E 0 Cg EP
%%Page: 78 78
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(#include )0 12 Q()36 24 Q
(struct mydata {)0 36 Q(const char *name;)36 48 Q(int fd;)36 60 Q(};)0
72 Q 0 Cg EP
%%Page: 79 79
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(
)36 12 Q(int)0 24 Q(myopen\(struct archi)0 36
Q .3 -.15(ve *)-.25 H(a, v).15 E(oid *client_data\))-.2 E({)0 48 Q
(struct mydata *mydata = client_data;)5 60 Q(
)36 72 Q 0 Cg EP
%%Page: 80 80
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(mydata->fd = open\(mydata->name, O_WR)5 12 Q
(ONL)-.4 E 2.5(Y|O)-1 G(_CREA)-2.5 E 1.48 -.74(T, 0)-1.11 H(644\);).74 E
(if \(mydata->fd >= 0\))5 24 Q(return \(ARCHIVE_OK\);)10 36 Q(else)5 48
Q(return \(ARCHIVE_F)10 60 Q -1.21 -1.11(AT A)-.74 H(L\);)1.11 E(})0 72
Q 0 Cg EP
%%Page: 81 81
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(
)36 12 Q(ssize_t)0 24 Q
(mywrite\(struct archi)0 36 Q .3 -.15(ve *)-.25 H(a, v).15 E
(oid *client_data, const v)-.2 E(oid *b)-.2 E(uf)-.2 E(f, size_t n\))
-.25 E({)0 48 Q(struct mydata *mydata = client_data;)5 60 Q(
)36 72 Q
0 Cg EP
%%Page: 82 82
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(return \(write\(mydata->fd, b)5 12 Q(uf)-.2 E
(f, n\)\);)-.25 E(})0 24 Q(
)36 36 Q(int)0 48 Q(myclose\(struct archi)
0 60 Q .3 -.15(ve *)-.25 H(a, v).15 E(oid *client_data\))-.2 E({)0 72 Q
0 Cg EP
%%Page: 83 83
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(struct mydata *mydata = client_data;)5 12 Q(
)
36 24 Q(if \(mydata->fd > 0\))5 36 Q(close\(mydata->fd\);)10 48 Q
(return \(0\);)5 60 Q(})0 72 Q 0 Cg EP
%%Page: 84 84
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(
)36 12 Q -.2(vo)0 24 S(id).2 E(write_archi)0
36 Q -.15(ve)-.25 G(\(const char *outname, const char **\214lename\)).15
E({)0 48 Q(struct mydata *mydata = malloc\(sizeof\(struct mydata\)\);)5
60 Q(struct archi)5 72 Q .3 -.15(ve *)-.25 H(a;).15 E 0 Cg EP
%%Page: 85 85
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(struct archi)5 12 Q -.15(ve)-.25 G
(_entry *entry;).15 E(struct stat st;)5 24 Q(char b)5 36 Q(uf)-.2 E
(f[8192];)-.25 E(int len;)5 48 Q(int fd;)5 60 Q(
)36 72 Q 0 Cg EP
%%Page: 86 86
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF 2.5(a=a)5 12 S(rchi)-2.5 E -.15(ve)-.25 G
(_write_ne).15 E(w\(\);)-.25 E(mydata->name = outname;)5 24 Q(archi)5 36
Q -.15(ve)-.25 G(_write_set_compression_gzip\(a\);).15 E(archi)5 48 Q
-.15(ve)-.25 G(_write_set_format_ustar\(a\);).15 E(archi)5 60 Q -.15(ve)
-.25 G(_write_open\(a, mydata, myopen, mywrite, myclose\);).15 E
(while \(*\214lename\) {)5 72 Q 0 Cg EP
%%Page: 87 87
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(stat\(*\214lename, &st\);)10 12 Q(entry = archi)
10 24 Q -.15(ve)-.25 G(_entry_ne).15 E(w\(\);)-.25 E(archi)10 36 Q -.15
(ve)-.25 G(_entry_cop).15 E(y_stat\(entry)-.1 E 2.5(,&)-.65 G(st\);)-2.5
E(archi)10 48 Q -.15(ve)-.25 G(_entry_set_pathname\(entry).15 E 2.5(,*)
-.65 G(\214lename\);)-2.5 E(archi)10 60 Q -.15(ve)-.25 G
(_write_header\(a, entry\);).15 E(fd = open\(*\214lename, O_RDONL)10 72
Q(Y\);)-1 E 0 Cg EP
%%Page: 88 88
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(len = read\(fd, b)10 12 Q(uf)-.2 E(f, sizeof\(b)
-.25 E(uf)-.2 E(f\)\);)-.25 E(while \( len > 0 \) {)10 24 Q(archi)36 36
Q -.15(ve)-.25 G(_write_data\(a, b).15 E(uf)-.2 E(f, len\);)-.25 E
(len = read\(fd, b)36 48 Q(uf)-.2 E(f, sizeof\(b)-.25 E(uf)-.2 E(f\)\);)
-.25 E(})10 60 Q(archi)10 72 Q -.15(ve)-.25 G(_entry_free\(entry\);).15
E 0 Cg EP
%%Page: 89 89
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(\214lename++;)10 12 Q(})5 24 Q(archi)5 36 Q -.15
(ve)-.25 G(_write_\214nish\(a\);).15 E(})0 48 Q(
)36 60 Q
(int main\(int ar)0 72 Q(gc, const char **ar)-.18 E(gv\))-.18 E 0 Cg EP
%%Page: 90 90
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF({)0 12 Q(const char *outname;)36 24 Q(ar)36 36 Q
(gv++;)-.18 E(outname = ar)36 48 Q(gv++;)-.18 E(write_archi)36 60 Q -.15
(ve)-.25 G(\(outname, ar).15 E(gv\);)-.18 E(return 0;)36 72 Q 0 Cg EP
%%Page: 91 91
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(})0 12 Q(
)0 24 Q()0 36 Q()36 12 Q(archi)0 24 Q -.15(ve)-.25 G
(_write_ne).15 E(w\(\))-.25 E
(returns a pointer to a ne)0 36 Q(wly-allocated)-.25 E(\
struct archi)0 48 Q -.15
(ve)-.25 G().15 E(object.)0 60 Q(
)36 72 Q 0 Cg EP
%%Page: 96 96
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_data\(\)).15 E
(returns a count of the number of bytes actually written.)0 24 Q
(On error)0 36 Q 2.5(,-)-.4 G 2.5(1i)-2.5 G 2.5(sr)-2.5 G
(eturned and the)-2.5 E(archi)0 48 Q -.15(ve)-.25 G
(_errno\(\)).15 E(and)0 60 Q(archi)0 72 Q -.15(ve)
-.25 G(_error_string\(\)).15 E 0 Cg EP
%%Page: 97 97
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(functions will return appropriate v)0 12 Q
(alues.)-.25 E(Note that if the client-pro)0 24 Q
(vided write callback function)-.15 E(returns a non-zero v)0 36 Q
(alue, that error will be propag)-.25 E(ated back to the caller)-.05 E
(through whate)0 48 Q -.15(ve)-.25 G 2.5(rA).15 G
(PI function resulted in that call, which)-2.5 E(may include)0 60 Q
(archi)0 72 Q -.15(ve)-.25 G(_write_header\(\),).15
E 0 Cg EP
%%Page: 98 98
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G
(_write_data\(\),).15 E(archi)0 24 Q -.15(ve)-.25 G
(_write_close\(\),).15 E(or)0 36 Q(archi)0 48 Q -.15
(ve)-.25 G(_write_\214nish\(\).).15 E
(The client callback can call)0 60 Q(archi)0 72 Q -.15(ve)-.25 G
(_set_error\(\)).15 E 0 Cg EP
%%Page: 99 99
%%BeginPageSetup
BP
%%EndPageSetup
/F0 10/Times-Roman@@0 SF(to pro)0 12 Q(vide v)-.15 E
(alues that can then be retrie)-.25 E -.15(ve)-.25 G 2.5(db).15 G(y)-2.5
E(archi)0 24 Q -.15(ve)-.25 G(_errno\(\)).15 E(and)0
36 Q(archi)0 48 Q -.15(ve)-.25 G(_error_string\(\).)
.15 E(
)36 36 Q(The)0 48 Q(libarchi)0 60 Q -.15(ve)-.25 G().15 E(library w)0 72 Q(as written by)-.1 E 0 Cg EP %%Page: 103 103 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF -.35(Ti)0 12 S 2.5(mK).35 G (ientzle <kientzle@@acm.or)-2.5 E(g>.)-.18 E(
)36 60 Q(The def)0 72 Q (ault pax interchange format eliminates most of the historic)-.1 E 0 Cg EP %%Page: 105 105 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(tar limitations and pro)0 12 Q (vides a generic k)-.15 E -.15(ey)-.1 G(/v).15 E(alue attrib)-.25 E (ute f)-.2 E(acility)-.1 E(for v)0 24 Q(endor)-.15 E(-de\214ned e)-.2 E (xtensions.)-.15 E(One o)0 36 Q -.15(ve)-.15 G(rsight in POSIX is the f) .15 E(ailure to pro)-.1 E(vide a standard attrib)-.15 E(ute)-.2 E (for lar)0 48 Q(ge de)-.18 E(vice numbers.)-.25 E(This library uses)0 60 Q -.74(``)0 72 S(SCHIL).74 E -1.29(Y.)-1 G(de)1.29 E(vminor')-.25 E(') -.74 E 0 Cg EP %%Page: 106 106 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(and)0 12 Q -.74(``)0 24 S(SCHIL).74 E -1.29(Y.) -1 G(de)1.29 E(vmajor')-.25 E(')-.74 E(for de)0 36 Q (vice numbers that e)-.25 E(xceed the range supported by the backw)-.15 E(ards-compatible)-.1 E(ustar header)0 48 Q(.)-.55 E(These k)0 60 Q -.15 (ey)-.1 G 2.5(sa).15 G(re compatible with Joer)-2.5 E 2.5(gS)-.18 G (chilling')-2.5 E(s)-.55 E(star)0 72 Q 0 Cg EP %%Page: 107 107 %%BeginPageSetup BP %%EndPageSetup /F0 10/Times-Roman@@0 SF(archi)0 12 Q -.15(ve)-.25 G -.55(r.).15 G (Other implementations may not recognize these k)0 24 Q -.15(ey)-.1 G 2.5(sa).15 G(nd will thus be unable)-2.5 E(to correctly restore de)0 36 Q(vice nodes with lar)-.25 E(ge de)-.18 E(vice numbers from archi)-.25 E -.15(ve)-.25 G(s).15 E(created by this library)0 48 Q(.)-.65 E()0 60 Q()0 72 Q 0 Cg EP %%Trailer end %%EOF @ 1.1.1.5 log @Import libarchive-3.2.1: - security fixes and other bugfixes - support for multhreading in xz 5.2+ @ text @d1 1348 a1348 289
ARCHIVE_WRITE(3) BSD Library Functions Manual ARCHIVE_WRITE(3)
NAME
archive_write — functions for creating archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
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.
Create
archive object
See archive_write_new(3).
To write an archive, you must first obtain an initialized struct archive object from archive_write_new().
Enable
filters and formats, configure block size and padding
See archive_write_filter(3), archive_write_format(3) and
archive_write_blocksize(3).
You can then modify this object for the desired operations with the various archive_write_set_XXX() functions. In particular, you will need to invoke appropriate archive_write_add_XXX() and archive_write_set_XXX() functions to enable the corresponding compression and format support.
Set
options
See archive_read_set_options(3).
Open
archive
See archive_write_open(3).
Once you have prepared the struct archive object, you call archive_write_open() to actually open the archive and prepare it for writing. There are several variants of this function; the most basic expects you to provide pointers to several functions that can provide blocks of bytes from the archive. There are convenience forms that allow you to specify a filename, file descriptor, FILE * object, or a block of memory from which to write the archive data.
Produce
archive
See archive_write_header(3) and archive_write_data(3).
Individual archive entries are written in a three-step process: You first initialize a struct archive_entry structure with information about the new entry. At a minimum, you should set the pathname of the entry and provide a struct stat with a valid st_mode field, which specifies the type of object and st_size field, which specifies the size of the data portion of the object.
Release
resources
See archive_write_free(3).
After all entries have been written, use the archive_write_free() function to release all resources.
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);
}
la_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;
/* Set archive format and filter according to output file
extension.
* If it fails, set default format. Platform depended
function.
* See supported formats in
archive_write_set_format_filter_by_ext.c */
if (archive_write_set_format_filter_by_ext(a, outname) !=
ARCHIVE_OK) {
archive_write_add_filter_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);
if ((fd = open(*filename, O_RDONLY)) != -1) {
len = read(fd, buff, sizeof(buff));
while (len > 0) {
archive_write_data(a, buff, len);
len = read(fd, buff, sizeof(buff));
}
close(fd);
}
archive_entry_free(entry);
filename++;
}
archive_write_free(a);
}
int main(int
argc, const char **argv)
{
const char *outname;
argv++;
outname = *argv++;
write_archive(outname, argv);
return 0;
}
SEE ALSO
tar(1), libarchive(3), archive_write_set_options(3), cpio(5), mtree(5), tar(5)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle <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.
BSD February 2, 2012 BSD
EXAMPLES
d247 2 a248 3tar(1), archive_write_set_options(3), libarchive(3), cpio(5), mtree(5), tar(5)
@ 1.1.1.11 log @libarchive: import version 3.7.3 @ text @d2 1 a2 1 @ 1.1.1.12 log @Libarchive 3.7.4 is a bugfix and security release Security fixes: rar: Fix OOB in rar e8 filter (CVE-2024-26256) zip: Fix out of boundary access Important bugfixes: 7zip: Limit amount of properties bsdtar: Fix error handling around strtol() usages passphrase: Improve newline handling on Windows passphrase: Never allow empty passwords rar: Fix "File CRC Error" when extracting specific rar4 archives xar: Avoid infinite link loop zip: Update AppleDouble support for directories zstd: Implement core detection @ text @d2 1 a2 1 @ 1.1.1.13 log @libarchive: imported version 3.7.5 Libarchive 3.7.5 Security fixes: fix multiple vulnerabilities identified by SAST cpio: ignore out-of-range gid/uid/size/ino and harden AFIO parsing lzop: prevent integer overflow rar4: protect copy_from_lzss_window_to_unp() rar4: fix CVE-2024-26256 rar4: fix OOB in delta and audio filter rar4: fix out of boundary access with large files rar4: add boundary checks to rgb filter rar4: fix OOB access with unicode filenames rar5: clear 'data ready' cache on window buffer reallocs rpm: calculate huge header sizes correctly unzip: unify EOF handling util: fix out of boundary access in mktemp functions uu: stop processing if lines are too long Important bugfixes: 7zip: fix issue when skipping first file in 7zip archive that is a multiple of 65536 bytes ar: fix archive entries having no type lha: do not allow negative file sizes lha: fix integer truncation on 32-bit systems shar: check strdup return value rar5: don't try to read rediculously long names xar: fix another infinite loop and expat error handling many Windows fixes, cleanups and improvements @ text @d2 1 a2 1 @ 1.1.1.14 log @libarchove: import version 3.7.7 @ text @d1 2 a2 2 d23 2 a24 2ARCHIVE_WRITE(3) Library Functions Manual ARCHIVE_WRITE(3)
d28 2 a29 2archive_write — functions for creating archives
d33 1 a33 1Streaming Archive Library d38 1 a38 1
#include d43 1 a43 1
These functions provide a d50 3 a52 2
Create archive object
d54 1 a54 4See archive_write_new(3).
To write an d58 5 a62 8
Enable filters and formats, configure block size and padding
See archive_write_filter(3), archive_write_format(3) and archive_write_blocksize(3).
d64 1 a64 1You can then d72 7 a78 11
Set options
See archive_write_set_options(3).
Open archive
See archive_write_open(3).
d80 1 a80 1Once you have d91 3 a93 2
Produce archive
d95 1 a95 5See archive_write_header(3) and archive_write_data(3).
Individual d104 3 a106 5
Release resources
See archive_write_free(3).
d108 1 a108 1After all d115 1 a115 1
The following sketch illustrates d117 2 a118 3 functions are simply wrappers around the standard open(2), write(2), and close(2) system calls.
d120 1 a120 1#ifdef d126 1 a126 1
#endif
d147 1
a147 1
struct mydata { d153 1 a153 1
int
d158 1
a158 1
mydata->fd = d166 1 a166 1
la_ssize_t
d172 1
a172 1
return d176 1 a176 1
int
d181 1
a181 1
if d187 1 a187 1
void
d199 1
a199 1
a = d235 1 a235 1
int main(int d247 3 a249 3
tar(1), archive_write_set_options(3), libarchive(3), cpio(5), mtree(5), tar(5)
d253 1 a253 1The libarchive library d258 1 a258 1
The libarchive library d263 1 a263 1
There are many peculiar bugs in d271 1 a271 1
The default pax d284 4 a287 2 device numbers from archives created by this library. Debian February 2, 2012 ARCHIVE_WRITE(3)
@ 1.1.1.15 log @libarchive: imported version 3.7.9 @ text @d2 1 a2 1 @ 1.1.1.16 log @libarchive: import version 3.8.0 Libarchive 3.8.0 is a feature and bugfix release. New features: bsdtar: support --mtime and --clamp-mtime lib: mbedtls 3.x compatibility 7-zip reader: improve self-extracting archive detection xar: xmllite support for the XAR reader and writer zip writer: added XZ, LZMA, ZSTD and BZIP2 support zip writer: added LZMA + RISCV BCJ filter Notable security fixes: rar: do not skip past EOF while reading rar: fix double free with over 4 billion nodes rar: fix heap-buffer-overflow warc: prevent signed integer overflow tar: fix overflow in build_ustar_entry Notable bugfixes: bsdtar: don't hardlink negative inode files together gz: allow setting the original filename for gzip compressed files lib: improve lseek handling lib: support @@-prefixed Unix epoch timestamps as date strings rar: support large headers on 32 bit systems tar reader: Improve LFS support on 32 bit systems @ text @d2 1 a2 1 @ 1.1.1.17 log @libarchive: import version 3.8.1 @ text @d2 1 a2 1 @ 1.1.1.18 log @libarchive: imported version 3.8.2 @ text @d2 1 a2 1 @ 1.1.1.19 log @libarchive: import version 3.8.3 @ text @d2 1 a2 1 @ 1.1.1.20 log @libarchive: import 3.8.4 @ text @d2 1 a2 1 @ 1.1.1.21 log @libarchive: import version 3.8.5 @ text @d2 1 a2 1 @ 1.1.1.22 log @libarchive: imported version 3.8.6 @ text @d2 1 a2 1 @ 1.1.1.23 log @libarchive: imported version 3.8.7 @ text @d2 1 a2 1 @ 1.1.1.24 log @libarchive: import 3.8.8 @ text @d2 1 a2 1 @