|
Packit Service |
1d0348 |
ARCHIVE_WRITE_OPEN(3) BSD Library Functions Manual ARCHIVE_WRITE_OPEN(3)
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
NAME
|
|
Packit Service |
1d0348 |
archive_write_open, archive_write_open_fd, archive_write_open_FILE,
|
|
Packit Service |
1d0348 |
archive_write_open_filename, archive_write_open_memory — functions for
|
|
Packit Service |
1d0348 |
creating archives
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
LIBRARY
|
|
Packit Service |
1d0348 |
Streaming Archive Library (libarchive, -larchive)
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
SYNOPSIS
|
|
Packit Service |
1d0348 |
#include <archive.h>
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
int
|
|
Packit Service |
1d0348 |
archive_write_open(struct archive *, void *client_data,
|
|
Packit Service |
1d0348 |
archive_open_callback *, archive_write_callback *,
|
|
Packit Service |
1d0348 |
archive_close_callback *);
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
int
|
|
Packit Service |
1d0348 |
archive_write_open_fd(struct archive *, int fd);
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
int
|
|
Packit Service |
1d0348 |
archive_write_open_FILE(struct archive *, FILE *file);
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
int
|
|
Packit Service |
1d0348 |
archive_write_open_filename(struct archive *, const char *filename);
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
int
|
|
Packit Service |
1d0348 |
archive_write_open_memory(struct archive *, void *buffer,
|
|
Packit Service |
1d0348 |
size_t bufferSize, size_t *outUsed);
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
DESCRIPTION
|
|
Packit Service |
1d0348 |
archive_write_open()
|
|
Packit Service |
1d0348 |
Freeze the settings, open the archive, and prepare for writing
|
|
Packit Service |
1d0348 |
entries. This is the most generic form of this function, which
|
|
Packit Service |
1d0348 |
accepts pointers to three callback functions which will be
|
|
Packit Service |
1d0348 |
invoked by the compression layer to write the constructed ar‐
|
|
Packit Service |
1d0348 |
chive. This does not alter the default archive padding.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
archive_write_open_fd()
|
|
Packit Service |
1d0348 |
A convenience form of archive_write_open() that accepts a file
|
|
Packit Service |
1d0348 |
descriptor. The archive_write_open_fd() function is safe for use
|
|
Packit Service |
1d0348 |
with tape drives or other block-oriented devices.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
archive_write_open_FILE()
|
|
Packit Service |
1d0348 |
A convenience form of archive_write_open() that accepts a FILE *
|
|
Packit Service |
1d0348 |
pointer. Note that archive_write_open_FILE() is not safe for
|
|
Packit Service |
1d0348 |
writing to tape drives or other devices that require correct
|
|
Packit Service |
1d0348 |
blocking.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
archive_write_open_file()
|
|
Packit Service |
1d0348 |
A deprecated synonym for archive_write_open_filename().
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
archive_write_open_filename()
|
|
Packit Service |
1d0348 |
A convenience form of archive_write_open() that accepts a file‐
|
|
Packit Service |
1d0348 |
name. A NULL argument indicates that the output should be writ‐
|
|
Packit Service |
1d0348 |
ten to standard output; an argument of “-” will open a file with
|
|
Packit Service |
1d0348 |
that name. If you have not invoked
|
|
Packit Service |
1d0348 |
archive_write_set_bytes_in_last_block(), then
|
|
Packit Service |
1d0348 |
archive_write_open_filename() will adjust the last-block padding
|
|
Packit Service |
1d0348 |
depending on the file: it will enable padding when writing to
|
|
Packit Service |
1d0348 |
standard output or to a character or block device node, it will
|
|
Packit Service |
1d0348 |
disable padding otherwise. You can override this by manually
|
|
Packit Service |
1d0348 |
invoking archive_write_set_bytes_in_last_block() before calling
|
|
Packit Service |
1d0348 |
archive_write_open(). The archive_write_open_filename() function
|
|
Packit Service |
1d0348 |
is safe for use with tape drives or other block-oriented devices.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
archive_write_open_memory()
|
|
Packit Service |
1d0348 |
A convenience form of archive_write_open() that accepts a pointer
|
|
Packit Service |
1d0348 |
to a block of memory that will receive the archive. The final
|
|
Packit Service |
1d0348 |
size_t * argument points to a variable that will be updated after
|
|
Packit Service |
1d0348 |
each write to reflect how much of the buffer is currently in use.
|
|
Packit Service |
1d0348 |
You should be careful to ensure that this variable remains allo‐
|
|
Packit Service |
1d0348 |
cated until after the archive is closed. This function will dis‐
|
|
Packit Service |
1d0348 |
able padding unless you have specifically set the block size.
|
|
Packit Service |
1d0348 |
More information about the struct archive object and the overall design
|
|
Packit Service |
1d0348 |
of the library can be found in the libarchive(3) overview.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
Note that the convenience forms above vary in how they block the output.
|
|
Packit Service |
1d0348 |
See archive_write_blocksize(3) if you need to control the block size used
|
|
Packit Service |
1d0348 |
for writes or the end-of-file padding behavior.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
CLIENT CALLBACKS
|
|
Packit Service |
1d0348 |
To use this library, you will need to define and register callback func‐
|
|
Packit Service |
1d0348 |
tions that will be invoked to write data to the resulting archive. These
|
|
Packit Service |
1d0348 |
functions are registered by calling archive_write_open():
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
typedef int archive_open_callback(struct archive *, void
|
|
Packit Service |
1d0348 |
*client_data)
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The open callback is invoked by archive_write_open(). It should return
|
|
Packit Service |
1d0348 |
ARCHIVE_OK if the underlying file or data source is successfully opened.
|
|
Packit Service |
1d0348 |
If the open fails, it should call archive_set_error() to register an
|
|
Packit Service |
1d0348 |
error code and message and return ARCHIVE_FATAL.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
typedef la_ssize_t archive_write_callback(struct archive *,
|
|
Packit Service |
1d0348 |
void *client_data, const void *buffer, size_t length)
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The write callback is invoked whenever the library needs to write raw
|
|
Packit Service |
1d0348 |
bytes to the archive. For correct blocking, each call to the write call‐
|
|
Packit Service |
1d0348 |
back function should translate into a single write(2) system call. This
|
|
Packit Service |
1d0348 |
is especially critical when writing archives to tape drives. On success,
|
|
Packit Service |
1d0348 |
the write callback should return the number of bytes actually written.
|
|
Packit Service |
1d0348 |
On error, the callback should invoke archive_set_error() to register an
|
|
Packit Service |
1d0348 |
error code and message and return -1.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
typedef int archive_close_callback(struct archive *, void
|
|
Packit Service |
1d0348 |
*client_data)
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The close callback is invoked by archive_close when the archive process‐
|
|
Packit Service |
1d0348 |
ing is complete. The callback should return ARCHIVE_OK on success. On
|
|
Packit Service |
1d0348 |
failure, the callback should invoke archive_set_error() to register an
|
|
Packit Service |
1d0348 |
error code and message and return ARCHIVE_FATAL.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
Note that if the client-provided write callback function returns a non-
|
|
Packit Service |
1d0348 |
zero value, that error will be propagated back to the caller through
|
|
Packit Service |
1d0348 |
whatever API function resulted in that call, which may include
|
|
Packit Service |
1d0348 |
archive_write_header(), archive_write_data(), archive_write_close(),
|
|
Packit Service |
1d0348 |
archive_write_finish(), or archive_write_free(). The client callback can
|
|
Packit Service |
1d0348 |
call archive_set_error() to provide values that can then be retrieved by
|
|
Packit Service |
1d0348 |
archive_errno() and archive_error_string().
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
RETURN VALUES
|
|
Packit Service |
1d0348 |
These functions return ARCHIVE_OK on success, or ARCHIVE_FATAL.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
ERRORS
|
|
Packit Service |
1d0348 |
Detailed error codes and textual descriptions are available from the
|
|
Packit Service |
1d0348 |
archive_errno() and archive_error_string() functions.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
SEE ALSO
|
|
Packit Service |
1d0348 |
tar(1), libarchive(3), archive_write(3), archive_write_blocksize(3),
|
|
Packit Service |
1d0348 |
archive_write_filter(3), archive_write_format(3), archive_write_new(3),
|
|
Packit Service |
1d0348 |
archive_write_set_options(3), cpio(5), mtree(5), tar(5)
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
BSD February 2, 2012 BSD
|