diff options
| author | Tomas Bzatek <tbzatek@redhat.com> | 2010-02-05 11:06:31 +0100 |
|---|---|---|
| committer | Tomas Bzatek <tbzatek@redhat.com> | 2010-02-05 11:06:31 +0100 |
| commit | baea7d877d3cf69679a39e8512a120658a478073 (patch) | |
| tree | 37c9a98cb3d3a322f3f91c8ca656ccd6bd2eaebe /libarchive/libarchive-2.8.0/doc/html/archive_write.3.html | |
| parent | e42a4ff3031aa1c1aaf27aa34d9395fec185924b (diff) | |
| download | tuxcmd-modules-baea7d877d3cf69679a39e8512a120658a478073.tar.xz | |
Rebase libarchive to 2.8.0
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/html/archive_write.3.html')
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/html/archive_write.3.html | 845 |
1 files changed, 845 insertions, 0 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_write.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_write.3.html new file mode 100644 index 0000000..e72c5d5 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/archive_write.3.html @@ -0,0 +1,845 @@ +<!-- Creator : groff version 1.19.2 --> +<!-- CreationDate: Thu Feb 4 20:36:33 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> +— functions for creating archives</p> + + +<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> + +<p style="margin-left:8%;"><b>#include +<archive.h></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 archive *</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 archive *</i>, +<i>int 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 archive *</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 archive *</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 archive *</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 archive *</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 archive *</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 archive *</i>, +<i>const char * 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 archive *</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 archive *</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 archive *</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 archive *</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 archive *</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 archive *</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 archive *</i>, +<i>const char *</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 archive *</i>, +<i>const char *</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 archive *</i>, +<i>const char *</i>);</p> + +<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> + + +<p valign="top"><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:8%; margin-top: 1em"><i>int</i></p> + + +<p style="margin-left:14%;"><b>archive_write_open_fd</b>(<i>struct archive *</i>, +<i>int 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 archive *</i>, +<i>FILE *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 archive *</i>, +<i>const char *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 archive *</i>, +<i>void *buffer</i>, <i>size_t bufferSize</i>, +<i>size_t *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 archive *</i>, +<i>struct archive_entry *</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 archive *</i>, +<i>const void *</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 archive *</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 archive *</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 archive *</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 +‘‘set’’ 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 +‘‘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.</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 +‘‘1’’.</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 +‘‘device, flags, gid, gname, link, mode, nlink, +size, time, type, uid, uname’’.</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 +‘‘-’’ 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 archive *</i>, +<i>void *client_data</i>, +<i>const void *buffer</i>, +<i>size_t 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 <sys/stat.h> <br> +#include <archive.h> <br> +#include <archive_entry.h> <br> +#include <fcntl.h> <br> +#include <stdlib.h> <br> +#include <unistd.h></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->fd = +open(mydata->name, O_WRONLY | O_CREAT, 0644); <br> +if (mydata->fd >= 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->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->fd > 0) <br> +close(mydata->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->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, &st); <br> +entry = archive_entry_new(); <br> +archive_entry_copy_stat(entry, &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 > 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 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 +⟨kientzle@acm.org⟩.</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 +‘‘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 <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 8.0 +May 11, 2008 FreeBSD 8.0</p> +<hr> +</body> +</html> |