doc/html/archive_write.3.html

<!-- Creator     : groff version 1.19.2 -->
<!-- CreationDate: Sun Mar 14 19:50:23 2010 -->
<!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; }
       pre   { margin-top: 0; margin-bottom: 0; }
       table { margin-top: 0; margin-bottom: 0; }
</style>
<title></title>
</head>
<body>

<hr>


<p valign="top">archive_write(3) FreeBSD Library Functions
Manual archive_write(3)</p>

<p style="margin-top: 1em" valign="top"><b>NAME</b></p>

<p style="margin-left:8%;"><b>archive_write_new</b>,
<b>archive_write_set_format_cpio</b>,
<b>archive_write_set_format_pax</b>,
<b>archive_write_set_format_pax_restricted</b>,
<b>archive_write_set_format_shar</b>,
<b>archive_write_set_format_shar_binary</b>,
<b>archive_write_set_format_ustar</b>,
<b>archive_write_get_bytes_per_block</b>,
<b>archive_write_set_bytes_per_block</b>,
<b>archive_write_set_bytes_in_last_block</b>,
<b>archive_write_set_compression_bzip2</b>,
<b>archive_write_set_compression_compress</b>,
<b>archive_write_set_compression_gzip</b>,
<b>archive_write_set_compression_none</b>,
<b>archive_write_set_compression_program</b>,
<b>archive_write_set_compressor_options</b>,
<b>archive_write_set_format_options</b>,
<b>archive_write_set_options</b>, <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>,
<b>archive_write_header</b>, <b>archive_write_data</b>,
<b>archive_write_finish_entry</b>,
<b>archive_write_close</b>, <b>archive_write_finish</b>
&mdash; functions for creating archives</p>


<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p>

<p style="margin-left:8%;"><b>#include
&lt;archive.h&gt;</b></p>

<p style="margin-left:8%; margin-top: 1em"><i>struct
archive *</i></p>


<p style="margin-left:14%;"><b>archive_write_new</b>(<i>void</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_get_bytes_per_block</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_bytes_per_block</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>int&nbsp;bytes_per_block</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_bytes_in_last_block</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>int</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_compression_bzip2</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_compression_compress</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_compression_gzip</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_compression_none</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_compression_program</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>const&nbsp;char&nbsp;*&nbsp;cmd</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_format_cpio</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_format_pax</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_format_pax_restricted</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_format_shar</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_format_shar_binary</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_format_ustar</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_format_options</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>const&nbsp;char&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_compressor_options</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>const&nbsp;char&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_set_options</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>const&nbsp;char&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p valign="top"><b>archive_write_open</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>void&nbsp;*client_data</i>,
<i>archive_open_callback&nbsp;*</i>,
<i>archive_write_callback&nbsp;*</i>,
<i>archive_close_callback&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_open_fd</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>int&nbsp;fd</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_open_FILE</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>FILE&nbsp;*file</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_open_filename</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>const&nbsp;char&nbsp;*filename</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p valign="top"><b>archive_write_open_memory</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>void&nbsp;*buffer</i>, <i>size_t&nbsp;bufferSize</i>,
<i>size_t&nbsp;*outUsed</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_header</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>struct&nbsp;archive_entry&nbsp;*</i>);</p>


<p style="margin-left:8%; margin-top: 1em"><i>ssize_t</i></p>


<p style="margin-left:14%;"><b>archive_write_data</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>const&nbsp;void&nbsp;*</i>, <i>size_t</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_finish_entry</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_close</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>

<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>


<p style="margin-left:14%;"><b>archive_write_finish</b>(<i>struct&nbsp;archive&nbsp;*</i>);</p>


<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p>

<p style="margin-left:8%;">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:</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_new</b>()</p>

<p style="margin-left:20%;">Allocates and initializes a
struct archive object suitable for writing a tar
archive.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_set_bytes_per_block</b>()</p>

<p style="margin-left:20%;">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.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_get_bytes_per_block</b>()</p>

<p style="margin-left:20%;">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.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_set_bytes_in_last_block</b>()</p>

<p style="margin-left:20%;">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 <b>archive_write_open_filename</b>() will set
this based on the file type). Unlike the other
&lsquo;&lsquo;set&rsquo;&rsquo; functions, this function can
be called after the archive is opened.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_get_bytes_in_last_block</b>()</p>

<p style="margin-left:20%;">Retrieve the currently-set
value for last block size. A value of -1 here indicates that
the library should use default values.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_set_format_cpio</b>(),
<b>archive_write_set_format_pax</b>(),
<b>archive_write_set_format_pax_restricted</b>(),
<b>archive_write_set_format_shar</b>(),
<b>archive_write_set_format_shar_binary</b>(),
<b>archive_write_set_format_ustar</b>()</p>

<p style="margin-left:20%;">Sets the format that will be
used for the archive. The library can write POSIX
octet-oriented cpio format archives, POSIX-standard
&lsquo;&lsquo;pax interchange&rsquo;&rsquo; format archives,
traditional &lsquo;&lsquo;shar&rsquo;&rsquo; archives,
enhanced &lsquo;&lsquo;binary&rsquo;&rsquo; shar archives
that store a variety of file attributes and handle binary
files, and POSIX-standard &lsquo;&lsquo;ustar&rsquo;&rsquo;
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. &lsquo;&lsquo;Restricted pax
interchange format&rsquo;&rsquo; 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.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_set_compression_bzip2</b>(),
<b>archive_write_set_compression_compress</b>(),
<b>archive_write_set_compression_gzip</b>(),
<b>archive_write_set_compression_none</b>()</p>

<p style="margin-left:20%;">The resulting archive will be
compressed as specified. Note that the compressed output is
always properly blocked.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_set_compression_program</b>()</p>

<p style="margin-left:20%;">The archive will be fed into
the specified compression program. The output of that
program is blocked and written to the client write
callbacks.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_set_compressor_options</b>(),
<b>archive_write_set_format_options</b>(),
<b>archive_write_set_options</b>()</p>

<p style="margin-left:20%;">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:</p>

<p valign="top"><i>option=value</i></p>

<p style="margin-left:32%;">The option/value pair will be
provided to every module. Modules that do not accept an
option with this name will ignore it.</p>

<p valign="top"><i>option</i></p>

<p style="margin-left:32%; margin-top: 1em">The option will
be provided to every module with a value of
&lsquo;&lsquo;1&rsquo;&rsquo;.</p>

<p valign="top"><i>!option</i></p>

<p style="margin-left:32%;">The option will be provided to
every module with a NULL value.</p>

<p valign="top"><i>module:option=value</i>,
<i>module:option</i>, <i>module:!option</i></p>

<p style="margin-left:32%;">As above, but the corresponding
option and value will be provided only to modules whose name
matches <i>module</i>.</p>

<p style="margin-left:20%;">The return value will be
<b>ARCHIVE_OK</b> if any module accepts the option, or
<b>ARCHIVE_WARN</b> if no module accepted the option, or
<b>ARCHIVE_FATAL</b> if there was a fatal error while
attempting to process the option.</p>

<p style="margin-left:20%; margin-top: 1em">The currently
supported options are:</p>

<p valign="top">Compressor gzip <b><br>
compression-level</b></p>

<p style="margin-left:45%;">The value is interpreted as a
decimal integer specifying the gzip compression level.</p>

<p valign="top">Compressor xz <b><br>
compression-level</b></p>

<p style="margin-left:45%;">The value is interpreted as a
decimal integer specifying the compression level.</p>

<p valign="top">Format mtree <b><br>
cksum</b>, <b>device</b>, <b>flags</b>, <b>gid</b>,
<b>gname</b>, <b>indent</b>, <b>link</b>, <b>md5</b>,
<b>mode</b>, <b>nlink</b>, <b>rmd160</b>, <b>sha1</b>,
<b>sha256</b>, <b>sha384</b>, <b>sha512</b>, <b>size</b>,
<b>time</b>, <b>uid</b>, <b>uname</b></p>

<p style="margin-left:45%;">Enable a particular keyword in
the mtree output. Prefix with an exclamation mark to disable
the corresponding keyword. The default is equivalent to
&lsquo;&lsquo;device, flags, gid, gname, link, mode, nlink,
size, time, type, uid, uname&rsquo;&rsquo;.</p>

<p valign="top"><b>all</b></p>

<p style="margin-left:45%; margin-top: 1em">Enables all of
the above keywords.</p>

<p valign="top"><b>use-set</b></p>

<p style="margin-left:45%;">Enables generation of
<b>/set</b> lines that specify default values for the
following files and/or directories.</p>

<p valign="top"><b>indent</b></p>

<p style="margin-left:45%; margin-top: 1em">XXX needs
explanation XXX</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_open</b>()</p>

<p style="margin-left:20%;">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.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_open_fd</b>()</p>

<p style="margin-left:20%;">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" valign="top"><b>archive_write_open_FILE</b>()</p>

<p style="margin-left:20%;">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" valign="top"><b>archive_write_open_file</b>()</p>

<p style="margin-left:20%;">A deprecated synonym for
<b>archive_write_open_filename</b>().</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_open_filename</b>()</p>

<p style="margin-left:20%;">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
&lsquo;&lsquo;-&rsquo;&rsquo; 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" valign="top"><b>archive_write_open_memory</b>()</p>

<p style="margin-left:20%;">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.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_header</b>()</p>

<p style="margin-left:20%;">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.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_data</b>()</p>

<p style="margin-left:20%;">Write data corresponding to the
header just written. Returns number of bytes written or -1
on error.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_finish_entry</b>()</p>

<p style="margin-left:20%;">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
<b>archive_write_next_header</b>() and
<b>archive_write_close</b>() as needed.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_close</b>()</p>

<p style="margin-left:20%;">Complete the archive and invoke
the close callback.</p>


<p style="margin-top: 1em" valign="top"><b>archive_write_finish</b>()</p>

<p style="margin-left:20%;">Invokes
<b>archive_write_close</b>() if it was not invoked manually,
then releases all resources. Note that this function was
declared to return <i>void</i> in libarchive 1.x, which made
it impossible to detect errors when
<b>archive_write_close</b>() was invoked implicitly from
this function. This is corrected beginning with libarchive
2.0.</p>

<p style="margin-left:8%;">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-top: 1em" valign="top"><b>IMPLEMENTATION</b></p>

<p style="margin-left:8%;">Compression support is built-in
to libarchive, which uses zlib and bzlib to handle gzip and
bzip2 compression, respectively.</p>

<p style="margin-top: 1em" valign="top"><b>CLIENT
CALLBACKS</b></p>

<p style="margin-left:8%;">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:17%; 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:8%; 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:17%; margin-top: 1em"><i>typedef
ssize_t</i></p>


<p valign="top"><b>archive_write_callback</b>(<i>struct&nbsp;archive&nbsp;*</i>,
<i>void&nbsp;*client_data</i>,
<i>const&nbsp;void&nbsp;*buffer</i>,
<i>size_t&nbsp;length</i>)</p>

<p style="margin-left:8%; 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:17%; 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:8%; 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-top: 1em" valign="top"><b>EXAMPLE</b></p>

<p style="margin-left:8%;">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.</p>

<p style="margin-left:17%; margin-top: 1em">#ifdef
__linux__</p>

<table width="100%" border=0 rules="none" frame="void"
       cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="17%"></td>
<td width="12%">


<p valign="top">#define</p></td>
<td width="13%">


<p valign="top">_FILE_OFFSET_BITS 64</p></td>
<td width="58%">
</td>
</table>

<p style="margin-left:17%;">#endif <br>
#include &lt;sys/stat.h&gt; <br>
#include &lt;archive.h&gt; <br>
#include &lt;archive_entry.h&gt; <br>
#include &lt;fcntl.h&gt; <br>
#include &lt;stdlib.h&gt; <br>
#include &lt;unistd.h&gt;</p>

<p style="margin-left:17%; margin-top: 1em">struct mydata
{</p>

<table width="100%" border=0 rules="none" frame="void"
       cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="29%"></td>
<td width="71%">


<p valign="top">const char *name;</p></td>
<tr valign="top" align="left">
<td width="29%"></td>
<td width="71%">


<p valign="top">int fd;</p></td>
</table>

<p style="margin-left:17%;">};</p>

<p style="margin-left:17%; margin-top: 1em">int <br>
myopen(struct archive *a, void *client_data) <br>
{ <br>
struct mydata *mydata = client_data;</p>

<p style="margin-left:17%; margin-top: 1em">mydata-&gt;fd =
open(mydata-&gt;name, O_WRONLY | O_CREAT, 0644); <br>
if (mydata-&gt;fd &gt;= 0) <br>
return (ARCHIVE_OK); <br>
else <br>
return (ARCHIVE_FATAL); <br>
}</p>

<p style="margin-left:17%; margin-top: 1em">ssize_t <br>
mywrite(struct archive *a, void *client_data, const void
*buff, size_t n) <br>
{ <br>
struct mydata *mydata = client_data;</p>

<p style="margin-left:17%; margin-top: 1em">return
(write(mydata-&gt;fd, buff, n)); <br>
}</p>

<p style="margin-left:17%; margin-top: 1em">int <br>
myclose(struct archive *a, void *client_data) <br>
{ <br>
struct mydata *mydata = client_data;</p>

<p style="margin-left:17%; margin-top: 1em">if
(mydata-&gt;fd &gt; 0) <br>
close(mydata-&gt;fd); <br>
return (0); <br>
}</p>

<p style="margin-left:17%; margin-top: 1em">void <br>
write_archive(const char *outname, const char **filename)
<br>
{ <br>
struct mydata *mydata = malloc(sizeof(struct mydata)); <br>
struct archive *a; <br>
struct archive_entry *entry; <br>
struct stat st; <br>
char buff[8192]; <br>
int len; <br>
int fd;</p>

<p style="margin-left:17%; margin-top: 1em">a =
archive_write_new(); <br>
mydata-&gt;name = outname; <br>
archive_write_set_compression_gzip(a); <br>
archive_write_set_format_ustar(a); <br>
archive_write_open(a, mydata, myopen, mywrite, myclose);
<br>
while (*filename) { <br>
stat(*filename, &amp;st); <br>
entry = archive_entry_new(); <br>
archive_entry_copy_stat(entry, &amp;st); <br>
archive_entry_set_pathname(entry, *filename); <br>
archive_write_header(a, entry); <br>
fd = open(*filename, O_RDONLY); <br>
len = read(fd, buff, sizeof(buff)); <br>
while ( len &gt; 0 ) {</p>

<table width="100%" border=0 rules="none" frame="void"
       cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="29%"></td>
<td width="71%">


<p valign="top">archive_write_data(a, buff, len);</p></td>
<tr valign="top" align="left">
<td width="29%"></td>
<td width="71%">


<p valign="top">len = read(fd, buff, sizeof(buff));</p></td>
</table>

<p style="margin-left:17%;">} <br>
archive_entry_free(entry); <br>
filename++; <br>
} <br>
archive_write_finish(a); <br>
}</p>

<p style="margin-left:17%; margin-top: 1em">int main(int
argc, const char **argv) <br>
{</p>

<table width="100%" border=0 rules="none" frame="void"
       cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="29%"></td>
<td width="71%">


<p valign="top">const char *outname;</p></td>
<tr valign="top" align="left">
<td width="29%"></td>
<td width="71%">


<p valign="top">argv++;</p></td>
<tr valign="top" align="left">
<td width="29%"></td>
<td width="71%">


<p valign="top">outname = argv++;</p></td>
<tr valign="top" align="left">
<td width="29%"></td>
<td width="71%">


<p valign="top">write_archive(outname, argv);</p></td>
<tr valign="top" align="left">
<td width="29%"></td>
<td width="71%">


<p valign="top">return 0;</p></td>
</table>

<p style="margin-left:17%;">}</p>

<p style="margin-top: 1em" valign="top"><b>RETURN
VALUES</b></p>

<p style="margin-left:8%;">Most functions return
<b>ARCHIVE_OK</b> (zero) on success, or one of several
non-zero error codes for errors. Specific error codes
include: <b>ARCHIVE_RETRY</b> for operations that might
succeed if retried, <b>ARCHIVE_WARN</b> for unusual
conditions that do not prevent further operations, and
<b>ARCHIVE_FATAL</b> for serious errors that make remaining
operations impossible. The <b>archive_errno</b>() and
<b>archive_error_string</b>() functions can be used to
retrieve an appropriate error code and a textual error
message.</p>


<p style="margin-left:8%; margin-top: 1em"><b>archive_write_new</b>()
returns a pointer to a newly-allocated struct archive
object.</p>


<p style="margin-left:8%; margin-top: 1em"><b>archive_write_data</b>()
returns a count of the number of bytes actually written. On
error, -1 is returned and the <b>archive_errno</b>() and
<b>archive_error_string</b>() 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
<b>archive_write_header</b>(), <b>archive_write_data</b>(),
<b>archive_write_close</b>(), or
<b>archive_write_finish</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" valign="top"><b>SEE ALSO</b></p>

<p style="margin-left:8%;">tar(1), libarchive(3),
tar(5)</p>

<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p>

<p style="margin-left:8%;">The <b>libarchive</b> library
first appeared in FreeBSD&nbsp;5.3.</p>

<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p>

<p style="margin-left:8%;">The <b>libarchive</b> library
was written by Tim Kientzle
&lang;kientzle@acm.org&rang;.</p>

<p style="margin-top: 1em" valign="top"><b>BUGS</b></p>

<p style="margin-left:8%;">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.</p>

<p style="margin-left:8%; margin-top: 1em">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
&lsquo;&lsquo;SCHILY.devminor&rsquo;&rsquo; and
&lsquo;&lsquo;SCHILY.devmajor&rsquo;&rsquo; for device
numbers that exceed the range supported by the
backwards-compatible ustar header. These keys are compatible
with Joerg Schilling&rsquo;s <b>star</b> 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.</p>


<p style="margin-left:8%; margin-top: 1em">FreeBSD&nbsp;9.0
May&nbsp;11, 2008 FreeBSD&nbsp;9.0</p>
<hr>
</body>
</html>