diff options
Diffstat (limited to 'archivers/libarchive/files/doc/man/archive_write.3')
| -rw-r--r-- | archivers/libarchive/files/doc/man/archive_write.3 | 670 |
1 files changed, 670 insertions, 0 deletions
diff --git a/archivers/libarchive/files/doc/man/archive_write.3 b/archivers/libarchive/files/doc/man/archive_write.3 new file mode 100644 index 00000000000..b485dcf796a --- /dev/null +++ b/archivers/libarchive/files/doc/man/archive_write.3 @@ -0,0 +1,670 @@ +.TH archive_write 3 "May 11, 2008" "" +.SH NAME +.ad l +\fB\%archive_write_new\fP, +\fB\%archive_write_set_format_cpio\fP, +\fB\%archive_write_set_format_pax\fP, +\fB\%archive_write_set_format_pax_restricted\fP, +\fB\%archive_write_set_format_shar\fP, +\fB\%archive_write_set_format_shar_binary\fP, +\fB\%archive_write_set_format_ustar\fP, +\fB\%archive_write_get_bytes_per_block\fP, +\fB\%archive_write_set_bytes_per_block\fP, +\fB\%archive_write_set_bytes_in_last_block\fP, +\fB\%archive_write_set_compression_bzip2\fP, +\fB\%archive_write_set_compression_compress\fP, +\fB\%archive_write_set_compression_gzip\fP, +\fB\%archive_write_set_compression_none\fP, +\fB\%archive_write_set_compression_program\fP, +\fB\%archive_write_set_compressor_options\fP, +\fB\%archive_write_set_format_options\fP, +\fB\%archive_write_set_options\fP, +\fB\%archive_write_open\fP, +\fB\%archive_write_open_fd\fP, +\fB\%archive_write_open_FILE\fP, +\fB\%archive_write_open_filename\fP, +\fB\%archive_write_open_memory\fP, +\fB\%archive_write_header\fP, +\fB\%archive_write_data\fP, +\fB\%archive_write_finish_entry\fP, +\fB\%archive_write_close\fP, +\fB\%archive_write_finish\fP +\- functions for creating archives +.SH SYNOPSIS +.ad l +\fB#include <archive.h>\fP +.br +\fIstruct archive *\fP +.br +\fB\%archive_write_new\fP(\fI\%void\fP); +.br +\fIint\fP +.br +\fB\%archive_write_get_bytes_per_block\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_bytes_per_block\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ bytes_per_block\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_bytes_in_last_block\fP(\fI\%struct\ archive\ *\fP, \fI\%int\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compression_bzip2\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compression_compress\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compression_gzip\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compression_none\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compression_program\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\ cmd\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_cpio\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_pax\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_pax_restricted\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_shar\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_shar_binary\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_ustar\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_format_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_compressor_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_set_options\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%archive_open_callback\ *\fP, \fI\%archive_write_callback\ *\fP, \fI\%archive_close_callback\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open_fd\fP(\fI\%struct\ archive\ *\fP, \fI\%int\ fd\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open_FILE\fP(\fI\%struct\ archive\ *\fP, \fI\%FILE\ *file\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open_filename\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ char\ *filename\fP); +.br +\fIint\fP +.br +\fB\%archive_write_open_memory\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *buffer\fP, \fI\%size_t\ bufferSize\fP, \fI\%size_t\ *outUsed\fP); +.br +\fIint\fP +.br +\fB\%archive_write_header\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP); +.br +\fIssize_t\fP +.br +\fB\%archive_write_data\fP(\fI\%struct\ archive\ *\fP, \fI\%const\ void\ *\fP, \fI\%size_t\fP); +.br +\fIint\fP +.br +\fB\%archive_write_finish_entry\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_close\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_write_finish\fP(\fI\%struct\ archive\ *\fP); +.SH DESCRIPTION +.ad l +These functions provide a complete API for creating streaming +archive files. +The general process is to first create the +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: +.RS 5 +.TP +\fB\%archive_write_new\fP() +Allocates and initializes a +Tn struct archive +object suitable for writing a tar archive. +.TP +\fB\%archive_write_set_bytes_per_block\fP() +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. +.TP +\fB\%archive_write_get_bytes_per_block\fP() +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. +.TP +\fB\%archive_write_set_bytes_in_last_block\fP() +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 +\fB\%archive_write_open_filename\fP() +will set this based on the file type). +Unlike the other +``set'' +functions, this function can be called after the archive is opened. +.TP +\fB\%archive_write_get_bytes_in_last_block\fP() +Retrieve the currently-set value for last block size. +A value of -1 here indicates that the library should use default values. +.TP +\fB\%archive_write_set_format_cpio\fP(), +\fB\%archive_write_set_format_pax\fP(), +\fB\%archive_write_set_format_pax_restricted\fP(), +\fB\%archive_write_set_format_shar\fP(), +\fB\%archive_write_set_format_shar_binary\fP(), +\fB\%archive_write_set_format_ustar\fP() +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. +.TP +\fB\%archive_write_set_compression_bzip2\fP(), +\fB\%archive_write_set_compression_compress\fP(), +\fB\%archive_write_set_compression_gzip\fP(), +\fB\%archive_write_set_compression_none\fP() +The resulting archive will be compressed as specified. +Note that the compressed output is always properly blocked. +.TP +\fB\%archive_write_set_compression_program\fP() +The archive will be fed into the specified compression program. +The output of that program is blocked and written to the client +write callbacks. +.TP +\fB\%archive_write_set_compressor_options\fP(), +\fB\%archive_write_set_format_options\fP(), +\fB\%archive_write_set_options\fP() +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: +.RS 5 +.TP +\fIoption=value\fP +The option/value pair will be provided to every module. +Modules that do not accept an option with this name will ignore it. +.TP +\fIoption\fP +The option will be provided to every module with a value of +``1''. +.TP +\fI!option\fP +The option will be provided to every module with a NULL value. +.TP +\fImodule:option=value\fP, \fImodule:option\fP, \fImodule:!option\fP +As above, but the corresponding option and value will be provided +only to modules whose name matches +\fImodule\fP. +.RE +The return value will be +\fBARCHIVE_OK\fP +if any module accepts the option, or +\fBARCHIVE_WARN\fP +if no module accepted the option, or +\fBARCHIVE_FATAL\fP +if there was a fatal error while attempting to process the option. +.PP +The currently supported options are: +.RS 5 +.TP +Compressor gzip +.RS 5 +.TP +\fBcompression-level\fP +The value is interpreted as a decimal integer specifying the +gzip compression level. +.RE +.TP +Compressor xz +.RS 5 +.TP +\fBcompression-level\fP +The value is interpreted as a decimal integer specifying the +compression level. +.RE +.TP +Format mtree +.RS 5 +.TP +\fBcksum\fP, \fBdevice\fP, \fBflags\fP, \fBgid\fP, \fBgname\fP, \fBindent\fP, \fBlink\fP, \fBmd5\fP, \fBmode\fP, \fBnlink\fP, \fBrmd160\fP, \fBsha1\fP, \fBsha256\fP, \fBsha384\fP, \fBsha512\fP, \fBsize\fP, \fBtime\fP, \fBuid\fP, \fBuname\fP +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''. +.TP +\fBall\fP +Enables all of the above keywords. +.TP +\fBuse-set\fP +Enables generation of +\fB/set\fP +lines that specify default values for the following files and/or directories. +.TP +\fBindent\fP +XXX needs explanation XXX +.RE +.RE +.TP +\fB\%archive_write_open\fP() +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. +.TP +\fB\%archive_write_open_fd\fP() +A convenience form of +\fB\%archive_write_open\fP() +that accepts a file descriptor. +The +\fB\%archive_write_open_fd\fP() +function is safe for use with tape drives or other +block-oriented devices. +.TP +\fB\%archive_write_open_FILE\fP() +A convenience form of +\fB\%archive_write_open\fP() +that accepts a +\fIFILE *\fP +pointer. +Note that +\fB\%archive_write_open_FILE\fP() +is not safe for writing to tape drives or other devices +that require correct blocking. +.TP +\fB\%archive_write_open_file\fP() +A deprecated synonym for +\fB\%archive_write_open_filename\fP(). +.TP +\fB\%archive_write_open_filename\fP() +A convenience form of +\fB\%archive_write_open\fP() +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 +\fB\%archive_write_set_bytes_in_last_block\fP(), +then +\fB\%archive_write_open_filename\fP() +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 +\fB\%archive_write_set_bytes_in_last_block\fP() +before calling +\fB\%archive_write_open\fP(). +The +\fB\%archive_write_open_filename\fP() +function is safe for use with tape drives or other +block-oriented devices. +.TP +\fB\%archive_write_open_memory\fP() +A convenience form of +\fB\%archive_write_open\fP() +that accepts a pointer to a block of memory that will receive +the archive. +The final +\fIsize_t *\fP +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. +.TP +\fB\%archive_write_header\fP() +Build and write a header using the data in the provided +Tn struct archive_entry +structure. +See +\fBarchive_entry\fP(3) +for information on creating and populating +Tn struct archive_entry +objects. +.TP +\fB\%archive_write_data\fP() +Write data corresponding to the header just written. +Returns number of bytes written or -1 on error. +.TP +\fB\%archive_write_finish_entry\fP() +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 +\fB\%archive_write_next_header\fP() +and +\fB\%archive_write_close\fP() +as needed. +.TP +\fB\%archive_write_close\fP() +Complete the archive and invoke the close callback. +.TP +\fB\%archive_write_finish\fP() +Invokes +\fB\%archive_write_close\fP() +if it was not invoked manually, then releases all resources. +Note that this function was declared to return +\fIvoid\fP +in libarchive 1.x, which made it impossible to detect errors when +\fB\%archive_write_close\fP() +was invoked implicitly from this function. +This is corrected beginning with libarchive 2.0. +.RE +More information about the +\fIstruct\fP archive +object and the overall design of the library can be found in the +\fBlibarchive\fP(3) +overview. +.SH IMPLEMENTATION +.ad l +Compression support is built-in to libarchive, which uses zlib and bzlib +to handle gzip and bzip2 compression, respectively. +.SH CLIENT CALLBACKS +.ad l +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 +\fB\%archive_write_open\fP(): +.RS 5 +.IP +\fItypedef int\fP +\fB\%archive_open_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) +.RE +.PP +The open callback is invoked by +\fB\%archive_write_open\fP(). +It should return +\fBARCHIVE_OK\fP +if the underlying file or data source is successfully +opened. +If the open fails, it should call +\fB\%archive_set_error\fP() +to register an error code and message and return +\fBARCHIVE_FATAL\fP. +.RS 5 +.IP +\fItypedef ssize_t\fP +\fB\%archive_write_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP, \fI\%const\ void\ *buffer\fP, \fI\%size_t\ length\fP) +.RE +.PP +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 +\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 +\fB\%archive_set_error\fP() +to register an error code and message and return -1. +.RS 5 +.IP +\fItypedef int\fP +\fB\%archive_close_callback\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *client_data\fP) +.RE +.PP +The close callback is invoked by archive_close when +the archive processing is complete. +The callback should return +\fBARCHIVE_OK\fP +on success. +On failure, the callback should invoke +\fB\%archive_set_error\fP() +to register an error code and message and +return +\fBARCHIVE_FATAL.\fP +.SH EXAMPLE +.ad l +The following sketch illustrates basic usage of the library. +In this example, +the callback functions are simply wrappers around the standard +\fBopen\fP(2), +\fBwrite\fP(2), +and +\fBclose\fP(2) +system calls. +.RS 4 +.nf +#ifdef __linux__ +#define _FILE_OFFSET_BITS 64 +#endif +#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, const 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) +{ + struct mydata *mydata = malloc(sizeof(struct mydata)); + struct archive *a; + struct archive_entry *entry; + struct stat st; + char buff[8192]; + int len; + int fd; + a = archive_write_new(); + mydata->name = outname; + archive_write_set_compression_gzip(a); + archive_write_set_format_ustar(a); + archive_write_open(a, mydata, myopen, mywrite, myclose); + while (*filename) { + stat(*filename, &st); + entry = archive_entry_new(); + archive_entry_copy_stat(entry, &st); + archive_entry_set_pathname(entry, *filename); + archive_write_header(a, entry); + fd = open(*filename, O_RDONLY); + len = read(fd, buff, sizeof(buff)); + while ( len > 0 ) { + archive_write_data(a, buff, len); + len = read(fd, buff, sizeof(buff)); + } + archive_entry_free(entry); + filename++; + } + archive_write_finish(a); +} +int main(int argc, const char **argv) +{ + const char *outname; + argv++; + outname = argv++; + write_archive(outname, argv); + return 0; +} +.RE +.SH RETURN VALUES +.ad l +Most functions return +\fBARCHIVE_OK\fP +(zero) on success, or one of several non-zero +error codes for errors. +Specific error codes include: +\fBARCHIVE_RETRY\fP +for operations that might succeed if retried, +\fBARCHIVE_WARN\fP +for unusual conditions that do not prevent further operations, and +\fBARCHIVE_FATAL\fP +for serious errors that make remaining operations impossible. +The +\fB\%archive_errno\fP() +and +\fB\%archive_error_string\fP() +functions can be used to retrieve an appropriate error code and a +textual error message. +.PP +\fB\%archive_write_new\fP() +returns a pointer to a newly-allocated +Tn struct archive +object. +.PP +\fB\%archive_write_data\fP() +returns a count of the number of bytes actually written. +On error, -1 is returned and the +\fB\%archive_errno\fP() +and +\fB\%archive_error_string\fP() +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 +\fB\%archive_write_header\fP(), +\fB\%archive_write_data\fP(), +\fB\%archive_write_close\fP(), +or +\fB\%archive_write_finish\fP(). +The client callback can call +\fB\%archive_set_error\fP() +to provide values that can then be retrieved by +\fB\%archive_errno\fP() +and +\fB\%archive_error_string\fP(). +.SH SEE ALSO +.ad l +\fBtar\fP(1), +\fBlibarchive\fP(3), +\fBtar\fP(5) +.SH HISTORY +.ad l +The +\fB\%libarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \%<kientzle@acm.org.> +.SH BUGS +.ad l +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 +``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 +\fB\%star\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 +created by this library. |