diff options
Diffstat (limited to 'archivers/libarchive/files/doc/man/archive_write.3')
| -rw-r--r-- | archivers/libarchive/files/doc/man/archive_write.3 | 750 |
1 files changed, 506 insertions, 244 deletions
diff --git a/archivers/libarchive/files/doc/man/archive_write.3 b/archivers/libarchive/files/doc/man/archive_write.3 index c07b6b570ea..c4b93958177 100644 --- a/archivers/libarchive/files/doc/man/archive_write.3 +++ b/archivers/libarchive/files/doc/man/archive_write.3 @@ -1,123 +1,199 @@ -.\" Copyright (c) 2003-2007 Tim Kientzle -.\" All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" $FreeBSD: src/lib/libarchive/archive_write.3,v 1.22 2007/05/29 01:00:19 kientzle Exp $ -.\" -.Dd August 19, 2006 -.Dt archive_write 3 -.Os -.Sh NAME -.Nm archive_write_new , -.Nm archive_write_set_format_cpio , -.Nm archive_write_set_format_pax , -.Nm archive_write_set_format_pax_restricted , -.Nm archive_write_set_format_shar , -.Nm archive_write_set_format_shar_binary , -.Nm archive_write_set_format_ustar , -.Nm archive_write_get_bytes_per_block , -.Nm archive_write_set_bytes_per_block , -.Nm archive_write_set_bytes_in_last_block , -.Nm archive_write_set_compression_bzip2 , -.Nm archive_write_set_compression_gzip , -.Nm archive_write_set_compression_none , -.Nm archive_write_set_compression_program , -.Nm archive_write_open , -.Nm archive_write_open_fd , -.Nm archive_write_open_FILE , -.Nm archive_write_open_filename , -.Nm archive_write_open_memory , -.Nm archive_write_header , -.Nm archive_write_data , -.Nm archive_write_finish_entry , -.Nm archive_write_close , -.Nm archive_write_finish -.Nd functions for creating archives -.Sh SYNOPSIS -.In archive.h -.Ft struct archive * -.Fn archive_write_new "void" -.Ft int -.Fn archive_write_get_bytes_per_block "struct archive *" -.Ft int -.Fn archive_write_set_bytes_per_block "struct archive *" "int bytes_per_block" -.Ft int -.Fn archive_write_set_bytes_in_last_block "struct archive *" "int" -.Ft int -.Fn archive_write_set_compression_bzip2 "struct archive *" -.Ft int -.Fn archive_write_set_compression_gzip "struct archive *" -.Ft int -.Fn archive_write_set_compression_none "struct archive *" -.Ft int -.Fn archive_write_set_compression_program "struct archive *" "const char * cmd" -.Ft int -.Fn archive_write_set_format_cpio "struct archive *" -.Ft int -.Fn archive_write_set_format_pax "struct archive *" -.Ft int -.Fn archive_write_set_format_pax_restricted "struct archive *" -.Ft int -.Fn archive_write_set_format_shar "struct archive *" -.Ft int -.Fn archive_write_set_format_shar_binary "struct archive *" -.Ft int -.Fn archive_write_set_format_ustar "struct archive *" -.Ft int -.Fn archive_write_open "struct archive *" "void *client_data" "archive_open_callback *" "archive_write_callback *" "archive_close_callback *" -.Ft int -.Fn archive_write_open_fd "struct archive *" "int fd" -.Ft int -.Fn archive_write_open_FILE "struct archive *" "FILE *file" -.Ft int -.Fn archive_write_open_filename "struct archive *" "const char *filename" -.Ft int -.Fn archive_write_open_memory "struct archive *" "void *buffer" "size_t bufferSize" "size_t *outUsed" -.Ft int -.Fn archive_write_header "struct archive *" "struct archive_entry *" -.Ft ssize_t -.Fn archive_write_data "struct archive *" "const void *" "size_t" -.Ft int -.Fn archive_write_finish_entry "struct archive *" -.Ft int -.Fn archive_write_close "struct archive *" -.Ft int -.Fn archive_write_finish "struct archive *" -.Sh DESCRIPTION +.TH archive_write 3 "August 19, 2006" "" +.SH NAME +\fBarchive_write_new\fP, +\fBarchive_write_set_format_cpio\fP, +\fBarchive_write_set_format_pax\fP, +\fBarchive_write_set_format_pax_restricted\fP, +\fBarchive_write_set_format_shar\fP, +\fBarchive_write_set_format_shar_binary\fP, +\fBarchive_write_set_format_ustar\fP, +\fBarchive_write_get_bytes_per_block\fP, +\fBarchive_write_set_bytes_per_block\fP, +\fBarchive_write_set_bytes_in_last_block\fP, +\fBarchive_write_set_compression_bzip2\fP, +\fBarchive_write_set_compression_gzip\fP, +\fBarchive_write_set_compression_none\fP, +\fBarchive_write_set_compression_program\fP, +\fBarchive_write_open\fP, +\fBarchive_write_open_fd\fP, +\fBarchive_write_open_FILE\fP, +\fBarchive_write_open_filename\fP, +\fBarchive_write_open_memory\fP, +\fBarchive_write_header\fP, +\fBarchive_write_data\fP, +\fBarchive_write_finish_entry\fP, +\fBarchive_write_close\fP, +\fBarchive_write_finish\fP +\- functions for creating archives +.SH SYNOPSIS +\fB#include <archive.h>\fP +.br +\fIstruct archive *\fP +.RE +.nh +\fBarchive_write_new\fP +.hy +("void"); +\fIint\fP +.RE +.nh +\fBarchive_write_get_bytes_per_block\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_bytes_per_block\fP +.hy +("struct archive *" "int bytes_per_block"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_bytes_in_last_block\fP +.hy +("struct archive *" "int"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_compression_bzip2\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_compression_gzip\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_compression_none\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_compression_program\fP +.hy +("struct archive *" "const char * cmd"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_cpio\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_pax\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_pax_restricted\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_shar\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_shar_binary\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_set_format_ustar\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_open\fP +.hy +("struct archive *" "void *client_data" "archive_open_callback *" "archive_write_callback *" "archive_close_callback *"); +\fIint\fP +.RE +.nh +\fBarchive_write_open_fd\fP +.hy +("struct archive *" "int fd"); +\fIint\fP +.RE +.nh +\fBarchive_write_open_FILE\fP +.hy +("struct archive *" "FILE *file"); +\fIint\fP +.RE +.nh +\fBarchive_write_open_filename\fP +.hy +("struct archive *" "const char *filename"); +\fIint\fP +.RE +.nh +\fBarchive_write_open_memory\fP +.hy +("struct archive *" "void *buffer" "size_t bufferSize" "size_t *outUsed"); +\fIint\fP +.RE +.nh +\fBarchive_write_header\fP +.hy +("struct archive *" "struct archive_entry *"); +\fIssize_t\fP +.RE +.nh +\fBarchive_write_data\fP +.hy +("struct archive *" "const void *" "size_t"); +\fIint\fP +.RE +.nh +\fBarchive_write_finish_entry\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_close\fP +.hy +("struct archive *"); +\fIint\fP +.RE +.nh +\fBarchive_write_finish\fP +.hy +("struct archive *"); +.SH DESCRIPTION These functions provide a complete API for creating streaming archive files. The general process is to first create the -.Tn struct archive +Tn 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: -.Bl -tag -width indent -.It Fn archive_write_new +.TP +.nh +\fBarchive_write_new\fP +.hy +(); Allocates and initializes a -.Tn struct archive +Tn struct archive object suitable for writing a tar archive. -.It Fn archive_write_set_bytes_per_block +.TP +.nh +\fBarchive_write_set_bytes_per_block\fP +.hy +(); 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. @@ -128,11 +204,19 @@ 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. -.It Fn archive_write_get_bytes_per_block +.TP +.nh +\fBarchive_write_get_bytes_per_block\fP +.hy +(); 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. -.It Fn archive_write_set_bytes_in_last_block +.TP +.nh +\fBarchive_write_set_bytes_in_last_block\fP +.hy +(); 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. @@ -142,257 +226,401 @@ 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 -.Fn archive_write_open_filename +.nh +\fBarchive_write_open_filename\fP +.hy +(); will set this based on the file type). Unlike the other -.Dq set +``set'' functions, this function can be called after the archive is opened. -.It Fn archive_write_get_bytes_in_last_block +.TP +.nh +\fBarchive_write_get_bytes_in_last_block\fP +.hy +(); Retrieve the currently-set value for last block size. A value of -1 here indicates that the library should use default values. -.It Fn archive_write_set_format_cpio , Fn archive_write_set_format_pax , Fn archive_write_set_format_pax_restricted , Fn archive_write_set_format_shar , Fn archive_write_set_format_shar_binary , Fn archive_write_set_format_ustar +.TP +.nh +\fBarchive_write_set_format_cpio\fP +.hy +(, .nh); +\fBarchive_write_set_format_pax\fP +.hy +(, .nh); +\fBarchive_write_set_format_pax_restricted\fP +.hy +(, .nh); +\fBarchive_write_set_format_shar\fP +.hy +(, .nh); +\fBarchive_write_set_format_shar_binary\fP +.hy +(, .nh); +\fBarchive_write_set_format_ustar\fP +.hy +(); Sets the format that will be used for the archive. The library can write POSIX octet-oriented cpio format archives, POSIX-standard -.Dq pax interchange +``pax interchange'' format archives, traditional -.Dq shar +``shar'' archives, enhanced -.Dq binary +``binary'' shar archives that store a variety of file attributes and handle binary files, and POSIX-standard -.Dq ustar +``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. -.Dq Restricted pax interchange format +``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. -.It Fn archive_write_set_compression_bzip2 , Fn archive_write_set_compression_gzip , Fn archive_write_set_compression_none +.TP +.nh +\fBarchive_write_set_compression_bzip2\fP +.hy +(, .nh); +\fBarchive_write_set_compression_gzip\fP +.hy +(, .nh); +\fBarchive_write_set_compression_none\fP +.hy +(); The resulting archive will be compressed as specified. Note that the compressed output is always properly blocked. -.It Fn archive_write_set_compression_program +.TP +.nh +\fBarchive_write_set_compression_program\fP +.hy +(); The archive will be fed into the specified compression program. The output of that program is blocked and written to the client write callbacks. -.It Fn archive_write_open +.TP +.nh +\fBarchive_write_open\fP +.hy +(); 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. -.It Fn archive_write_open_fd +.TP +.nh +\fBarchive_write_open_fd\fP +.hy +(); A convenience form of -.Fn archive_write_open +.nh +\fBarchive_write_open\fP +.hy +(); that accepts a file descriptor. The -.Fn archive_write_open_fd +.nh +\fBarchive_write_open_fd\fP +.hy +(); function is safe for use with tape drives or other block-oriented devices. -.It Fn archive_write_open_FILE +.TP +.nh +\fBarchive_write_open_FILE\fP +.hy +(); A convenience form of -.Fn archive_write_open +.nh +\fBarchive_write_open\fP +.hy +(); that accepts a -.Ft "FILE *" +\fI"FILE *"\fP +.RE pointer. Note that -.Fn archive_write_open_FILE +.nh +\fBarchive_write_open_FILE\fP +.hy +(); is not safe for writing to tape drives or other devices that require correct blocking. -.It Fn archive_write_open_file +.TP +.nh +\fBarchive_write_open_file\fP +.hy +(); A deprecated synonym for -.Fn archive_write_open_filename . -.It Fn archive_write_open_filename +.nh +\fBarchive_write_open_filename\fP +.hy +(.); +.TP +.nh +\fBarchive_write_open_filename\fP +.hy +(); A convenience form of -.Fn archive_write_open +.nh +\fBarchive_write_open\fP +.hy +(); that accepts a filename. A NULL argument indicates that the output should be written to standard output; an argument of -.Dq - +``-'' will open a file with that name. If you have not invoked -.Fn archive_write_set_bytes_in_last_block , +.nh +\fBarchive_write_set_bytes_in_last_block\fP +.hy +(,); then -.Fn archive_write_open_filename +.nh +\fBarchive_write_open_filename\fP +.hy +(); 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 -.Fn archive_write_set_bytes_in_last_block +.nh +\fBarchive_write_set_bytes_in_last_block\fP +.hy +(); before calling -.Fn archive_write_open . +.nh +\fBarchive_write_open\fP +.hy +(.); The -.Fn archive_write_open_filename +.nh +\fBarchive_write_open_filename\fP +.hy +(); function is safe for use with tape drives or other block-oriented devices. -.It Fn archive_write_open_memory +.TP +.nh +\fBarchive_write_open_memory\fP +.hy +(); A convenience form of -.Fn archive_write_open +.nh +\fBarchive_write_open\fP +.hy +(); that accepts a pointer to a block of memory that will receive the archive. The final -.Ft "size_t *" +\fI"size_t *"\fP +.RE 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. -.It Fn archive_write_header +.TP +.nh +\fBarchive_write_header\fP +.hy +(); Build and write a header using the data in the provided -.Tn struct archive_entry +Tn struct archive_entry structure. See -.Xr archive_entry 3 +\fBarchive_entry\fP(3) for information on creating and populating -.Tn struct archive_entry +Tn struct archive_entry objects. -.It Fn archive_write_data +.TP +.nh +\fBarchive_write_data\fP +.hy +(); Write data corresponding to the header just written. Returns number of bytes written or -1 on error. -.It Fn archive_write_finish_entry +.TP +.nh +\fBarchive_write_finish_entry\fP +.hy +(); 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 -.Fn archive_write_next_header +.nh +\fBarchive_write_next_header\fP +.hy +(); and -.Fn archive_write_close +.nh +\fBarchive_write_close\fP +.hy +(); as needed. -.It Fn archive_write_close +.TP +.nh +\fBarchive_write_close\fP +.hy +(); Complete the archive and invoke the close callback. -.It Fn archive_write_finish +.TP +.nh +\fBarchive_write_finish\fP +.hy +(); Invokes -.Fn archive_write_close +.nh +\fBarchive_write_close\fP +.hy +(); if it was not invoked manually, then releases all resources. Note that this function was declared to return -.Ft void +\fIvoid\fP +.RE in libarchive 1.x, which made it impossible to detect errors when -.Fn archive_write_close +.nh +\fBarchive_write_close\fP +.hy +(); was invoked implicitly from this function. This is corrected beginning with libarchive 2.0. -.El More information about the -.Va struct archive +\fIstruct\fP archive object and the overall design of the library can be found in the -.Xr libarchive 3 +\fBlibarchive\fP(3) overview. -.Sh IMPLEMENTATION +.SH IMPLEMENTATION Compression support is built-in to libarchive, which uses zlib and bzlib to handle gzip and bzip2 compression, respectively. -.Sh CLIENT CALLBACKS +.SH CLIENT CALLBACKS 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 -.Fn archive_write_open : -.Bl -item -offset indent -.It -.Ft typedef int -.Fn archive_open_callback "struct archive *" "void *client_data" -.El -.Pp +.nh +\fBarchive_write_open\fP +.hy +(:); +.IP +\fItypedef int\fP +.RE +.nh +\fBarchive_open_callback\fP +.hy +("struct archive *" "void *client_data"); The open callback is invoked by -.Fn archive_write_open . +.nh +\fBarchive_write_open\fP +.hy +(.); It should return -.Cm ARCHIVE_OK +\fBARCHIVE_OK\fP if the underlying file or data source is successfully opened. If the open fails, it should call -.Fn archive_set_error +.nh +\fBarchive_set_error\fP +.hy +(); to register an error code and message and return -.Cm ARCHIVE_FATAL . -.Bl -item -offset indent -.It -.Ft typedef ssize_t -.Fn archive_write_callback "struct archive *" "void *client_data" "void *buffer" "size_t length" -.El -.Pp +\fBARCHIVE_FATAL\fP. +.IP +\fItypedef ssize_t\fP +.RE +.nh +\fBarchive_write_callback\fP +.hy +("struct archive *" "void *client_data" "void *buffer" "size_t length"); 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 -.Xr write 2 +\fBwrite\fP(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 -.Fn archive_set_error +.nh +\fBarchive_set_error\fP +.hy +(); to register an error code and message and return -1. -.Bl -item -offset indent -.It -.Ft typedef int -.Fn archive_close_callback "struct archive *" "void *client_data" -.El -.Pp +.IP +\fItypedef int\fP +.RE +.nh +\fBarchive_close_callback\fP +.hy +("struct archive *" "void *client_data"); The close callback is invoked by archive_close when the archive processing is complete. The callback should return -.Cm ARCHIVE_OK +\fBARCHIVE_OK\fP on success. On failure, the callback should invoke -.Fn archive_set_error +.nh +\fBarchive_set_error\fP +.hy +(); to register an error code and message and return -.Cm ARCHIVE_FATAL. -.Sh EXAMPLE +\fBARCHIVE_FATAL.\fP +.SH EXAMPLE The following sketch illustrates basic usage of the library. In this example, the callback functions are simply wrappers around the standard -.Xr open 2 , -.Xr write 2 , +\fBopen\fP(2), +\fBwrite\fP(2), and -.Xr close 2 +\fBclose\fP(2) system calls. -.Bd -literal -offset indent +.RS #include <sys/stat.h> #include <archive.h> #include <archive_entry.h> #include <fcntl.h> #include <stdlib.h> #include <unistd.h> - struct mydata { const char *name; int fd; }; - int myopen(struct archive *a, void *client_data) { struct mydata *mydata = client_data; - mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644); if (mydata->fd >= 0) return (ARCHIVE_OK); else return (ARCHIVE_FATAL); } - ssize_t mywrite(struct archive *a, void *client_data, void *buff, size_t n) { struct mydata *mydata = client_data; - return (write(mydata->fd, buff, n)); } - int myclose(struct archive *a, void *client_data) { struct mydata *mydata = client_data; - if (mydata->fd > 0) close(mydata->fd); return (0); } - void write_archive(const char *outname, const char **filename) { @@ -403,7 +631,6 @@ write_archive(const char *outname, const char **filename) char buff[8192]; int len; int fd; - a = archive_write_new(); mydata->name = outname; archive_write_set_compression_gzip(a); @@ -426,7 +653,6 @@ write_archive(const char *outname, const char **filename) } archive_write_finish(a); } - int main(int argc, const char **argv) { const char *outname; @@ -435,89 +661,125 @@ int main(int argc, const char **argv) write_archive(outname, argv); return 0; } -.Ed -.Sh RETURN VALUES +.RE +.SH RETURN VALUES Most functions return -.Cm ARCHIVE_OK +\fBARCHIVE_OK\fP (zero) on success, or one of several non-zero error codes for errors. Specific error codes include: -.Cm ARCHIVE_RETRY +\fBARCHIVE_RETRY\fP for operations that might succeed if retried, -.Cm ARCHIVE_WARN +\fBARCHIVE_WARN\fP for unusual conditions that do not prevent further operations, and -.Cm ARCHIVE_FATAL +\fBARCHIVE_FATAL\fP for serious errors that make remaining operations impossible. The -.Fn archive_errno +.nh +\fBarchive_errno\fP +.hy +(); and -.Fn archive_error_string +.nh +\fBarchive_error_string\fP +.hy +(); functions can be used to retrieve an appropriate error code and a textual error message. -.Pp -.Fn archive_write_new +.nh +\fBarchive_write_new\fP +.hy +(); returns a pointer to a newly-allocated -.Tn struct archive +Tn struct archive object. -.Pp -.Fn archive_write_data +.nh +\fBarchive_write_data\fP +.hy +(); returns a count of the number of bytes actually written. On error, -1 is returned and the -.Fn archive_errno +.nh +\fBarchive_errno\fP +.hy +(); and -.Fn archive_error_string +.nh +\fBarchive_error_string\fP +.hy +(); 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 -.Fn archive_write_header , -.Fn archive_write_data , -.Fn archive_write_close , +.nh +\fBarchive_write_header\fP +.hy +(,); +.nh +\fBarchive_write_data\fP +.hy +(,); +.nh +\fBarchive_write_close\fP +.hy +(,); or -.Fn archive_write_finish . +.nh +\fBarchive_write_finish\fP +.hy +(.); The client callback can call -.Fn archive_set_error +.nh +\fBarchive_set_error\fP +.hy +(); to provide values that can then be retrieved by -.Fn archive_errno +.nh +\fBarchive_errno\fP +.hy +(); and -.Fn archive_error_string . -.Sh SEE ALSO -.Xr tar 1 , -.Xr libarchive 3 , -.Xr tar 5 -.Sh HISTORY +.nh +\fBarchive_error_string\fP +.hy +(.); +.SH SEE ALSO +\fBtar\fP(1), +\fBlibarchive\fP(3), +\fBtar\fP(5) +.SH HISTORY The -.Nm libarchive +\fBlibarchive\fP library first appeared in -.Fx 5.3 . -.Sh AUTHORS -.An -nosplit +FreeBSD 5.3. +.SH AUTHORS +-nosplit The -.Nm libarchive +\fBlibarchive\fP library was written by -.An Tim Kientzle Aq kientzle@acm.org . -.Sh BUGS +Tim Kientzle <kientzle@acm.org.> +.SH BUGS 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. -.Pp 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 -.Dq SCHILY.devminor +``SCHILY.devminor'' and -.Dq SCHILY.devmajor +``SCHILY.devmajor'' for device numbers that exceed the range supported by the backwards-compatible ustar header. These keys are compatible with Joerg Schilling's -.Nm star +\fBstar\fP archiver. Other implementations may not recognize these keys and will thus be unable to correctly restore device nodes with large device numbers from archives |