mirror of
https://github.com/cmclark00/retro-imager.git
synced 2025-05-19 16:35:20 +01:00
240 lines
8.6 KiB
HTML
240 lines
8.6 KiB
HTML
<!-- Creator : groff version 1.22.3 -->
|
|
<!-- CreationDate: Tue Feb 11 22:58:45 2020 -->
|
|
<!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), archive_write(3),
|
|
archive_write_blocksize(3), archive_write_filter(3),
|
|
archive_write_format(3), archive_write_new(3),
|
|
archive_write_set_options(3), libarchive(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>
|