<!-- Creator : groff version 1.22.3 -->
<!-- CreationDate: Mon Sep 3 22:55:09 2018 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title></title>
</head>
<body>
<hr>
<p>ARCHIVE_WRITE_OPEN(3) BSD Library Functions Manual
ARCHIVE_WRITE_OPEN(3)</p>
<p style="margin-top: 1em"><b>NAME</b></p>
<p style="margin-left:6%;"><b>archive_write_open</b>,
<b>archive_write_open_fd</b>,
<b>archive_write_open_FILE</b>,
<b>archive_write_open_filename</b>,
<b>archive_write_open_memory</b> — functions for
creating archives</p>
<p style="margin-top: 1em"><b>LIBRARY</b></p>
<p style="margin-left:6%;">Streaming Archive Library
(libarchive, -larchive)</p>
<p style="margin-top: 1em"><b>SYNOPSIS</b></p>
<p style="margin-left:6%;"><b>#include
<archive.h></b></p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p><b>archive_write_open</b>(<i>struct archive *</i>,
<i>void *client_data</i>,
<i>archive_open_callback *</i>,
<i>archive_write_callback *</i>,
<i>archive_close_callback *</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_write_open_fd</b>(<i>struct archive *</i>,
<i>int fd</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_write_open_FILE</b>(<i>struct archive *</i>,
<i>FILE *file</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:12%;"><b>archive_write_open_filename</b>(<i>struct archive *</i>,
<i>const char *filename</i>);</p>
<p style="margin-left:6%; margin-top: 1em"><i>int</i></p>
<p><b>archive_write_open_memory</b>(<i>struct archive *</i>,
<i>void *buffer</i>, <i>size_t bufferSize</i>,
<i>size_t *outUsed</i>);</p>
<p style="margin-top: 1em"><b>DESCRIPTION <br>
archive_write_open</b>()</p>
<p style="margin-left:17%;">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. This
does not alter the default archive padding.</p>
<p style="margin-top: 1em"><b>archive_write_open_fd</b>()</p>
<p style="margin-left:17%;">A convenience form of
<b>archive_write_open</b>() that accepts a file descriptor.
The <b>archive_write_open_fd</b>() function is safe for use
with tape drives or other block-oriented devices.</p>
<p style="margin-top: 1em"><b>archive_write_open_FILE</b>()</p>
<p style="margin-left:17%;">A convenience form of
<b>archive_write_open</b>() that accepts a <i>FILE *</i>
pointer. Note that <b>archive_write_open_FILE</b>() is not
safe for writing to tape drives or other devices that
require correct blocking.</p>
<p style="margin-top: 1em"><b>archive_write_open_file</b>()</p>
<p style="margin-left:17%;">A deprecated synonym for
<b>archive_write_open_filename</b>().</p>
<p style="margin-top: 1em"><b>archive_write_open_filename</b>()</p>
<p style="margin-left:17%;">A convenience form of
<b>archive_write_open</b>() 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
<b>archive_write_set_bytes_in_last_block</b>(), then
<b>archive_write_open_filename</b>() 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
<b>archive_write_set_bytes_in_last_block</b>() before
calling <b>archive_write_open</b>(). The
<b>archive_write_open_filename</b>() function is safe for
use with tape drives or other block-oriented devices.</p>
<p style="margin-top: 1em"><b>archive_write_open_memory</b>()</p>
<p style="margin-left:17%;">A convenience form of
<b>archive_write_open</b>() that accepts a pointer to a
block of memory that will receive the archive. The final
<i>size_t *</i> 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. This function will disable padding unless you have
specifically set the block size.</p>
<p style="margin-left:6%;">More information about the
<i>struct archive</i> object and the overall design of the
library can be found in the libarchive(3) overview.</p>
<p style="margin-left:6%; margin-top: 1em">Note that the
convenience forms above vary in how they block the output.
See archive_write_blocksize(3) if you need to control the
block size used for writes or the end-of-file padding
behavior.</p>
<p style="margin-top: 1em"><b>CLIENT CALLBACKS</b></p>
<p style="margin-left:6%;">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
<b>archive_write_open</b>():</p>
<p style="margin-left:14%; margin-top: 1em"><i>typedef
int</i> <b>archive_open_callback</b>(<i>struct archive
*</i>, <i>void *client_data</i>)</p>
<p style="margin-left:6%; margin-top: 1em">The open
callback is invoked by <b>archive_write_open</b>(). It
should return <b>ARCHIVE_OK</b> if the underlying file or
data source is successfully opened. If the open fails, it
should call <b>archive_set_error</b>() to register an error
code and message and return <b>ARCHIVE_FATAL</b>.</p>
<p style="margin-left:14%; margin-top: 1em"><i>typedef
la_ssize_t</i></p>
<p><b>archive_write_callback</b>(<i>struct archive *</i>,
<i>void *client_data</i>,
<i>const void *buffer</i>,
<i>size_t length</i>)</p>
<p style="margin-left:6%; margin-top: 1em">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
<b>archive_set_error</b>() to register an error code and
message and return -1.</p>
<p style="margin-left:14%; margin-top: 1em"><i>typedef
int</i> <b>archive_close_callback</b>(<i>struct archive
*</i>, <i>void *client_data</i>)</p>
<p style="margin-left:6%; margin-top: 1em">The close
callback is invoked by archive_close when the archive
processing is complete. The callback should return
<b>ARCHIVE_OK</b> on success. On failure, the callback
should invoke <b>archive_set_error</b>() to register an
error code and message and return <b>ARCHIVE_FATAL.</b></p>
<p style="margin-left:6%; margin-top: 1em">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 <b>archive_write_header</b>(),
<b>archive_write_data</b>(), <b>archive_write_close</b>(),
<b>archive_write_finish</b>(), or
<b>archive_write_free</b>(). The client callback can call
<b>archive_set_error</b>() to provide values that can then
be retrieved by <b>archive_errno</b>() and
<b>archive_error_string</b>().</p>
<p style="margin-top: 1em"><b>RETURN VALUES</b></p>
<p style="margin-left:6%;">These functions return
<b>ARCHIVE_OK</b> on success, or <b>ARCHIVE_FATAL</b>.</p>
<p style="margin-top: 1em"><b>ERRORS</b></p>
<p style="margin-left:6%;">Detailed error codes and textual
descriptions are available from the <b>archive_errno</b>()
and <b>archive_error_string</b>() functions.</p>
<p style="margin-top: 1em"><b>SEE ALSO</b></p>
<p style="margin-left:6%;">tar(1), libarchive(3),
archive_write(3), archive_write_blocksize(3),
archive_write_filter(3), archive_write_format(3),
archive_write_new(3), archive_write_set_options(3), cpio(5),
mtree(5), tar(5)</p>
<p style="margin-left:6%; margin-top: 1em">BSD
February 2, 2012 BSD</p>
<hr>
</body>
</html>