diff options
Diffstat (limited to 'archivers/libarchive/files/doc/man/archive_write.3')
| -rw-r--r-- | archivers/libarchive/files/doc/man/archive_write.3 | 621 |
1 files changed, 92 insertions, 529 deletions
diff --git a/archivers/libarchive/files/doc/man/archive_write.3 b/archivers/libarchive/files/doc/man/archive_write.3 index b485dcf796a..9387f168667 100644 --- a/archivers/libarchive/files/doc/man/archive_write.3 +++ b/archivers/libarchive/files/doc/man/archive_write.3 @@ -1,150 +1,14 @@ -.TH archive_write 3 "May 11, 2008" "" +.TH ARCHIVE_WRITE 3 "February 2, 2012" "" .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 +\fB\%archive_write\fP \- functions for creating archives +.SH LIBRARY +.ad l +Streaming Archive Library (libarchive, -larchive) .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 @@ -153,340 +17,76 @@ 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 +.SS Create archive object +See +\fBarchive_write_new\fP(3). +.PP +To write an archive, you must first obtain an initialized 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, +object from +\fB\%archive_write_new\fP(). +.SS Enable filters and formats, configure block size and padding +See +\fBarchive_write_filter\fP(3), +\fBarchive_write_format\fP(3) 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. +\fBarchive_write_blocksize\fP(3). .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 +You can then modify this object for the desired operations with the +various +\fB\%archive_write_set_XXX\fP() +functions. +In particular, you will need to invoke appropriate +\fB\%archive_write_add_XXX\fP() +and +\fB\%archive_write_set_XXX\fP() +functions to enable the corresponding compression and format +support. +.SS Set options +See +\fBarchive_read_set_options\fP(3). +.SS Open archive +See +\fBarchive_write_open\fP(3). +.PP +Once you have prepared the +Tn struct archive +object, you call \fB\%archive_write_open\fP() -that accepts a +to actually open the archive and prepare it for writing. +There are several variants of this function; +the most basic expects you to provide pointers to several +functions that can provide blocks of bytes from the archive. +There are convenience forms that allow you to +specify a filename, file descriptor, \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. +object, or a block of memory from which to write the archive data. +.SS Produce archive 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() +\fBarchive_write_header\fP(3) 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 +\fBarchive_write_data\fP(3). .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 +Individual archive entries are written in a three-step +process: +You first initialize a +Tn struct archive_entry +structure with information about the new entry. +At a minimum, you should set the pathname of the +entry and provide a +\fIstruct\fP stat +with a valid +\fIst_mode\fP +field, which specifies the type of object and +\fIst_size\fP +field, which specifies the size of the data portion of the object. +.SS Release resources +See +\fBarchive_write_free\fP(3). .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 +After all entries have been written, use the +\fB\%archive_write_free\fP() +function to release all resources. .SH EXAMPLE .ad l The following sketch illustrates basic usage of the library. @@ -509,8 +109,8 @@ system calls. #include <stdlib.h> #include <unistd.h> struct mydata { - const char *name; - int fd; + const char *name; + int fd; }; int myopen(struct archive *a, void *client_data) @@ -522,7 +122,7 @@ myopen(struct archive *a, void *client_data) else return (ARCHIVE_FATAL); } -ssize_t +la_ssize_t mywrite(struct archive *a, void *client_data, const void *buff, size_t n) { struct mydata *mydata = client_data; @@ -548,8 +148,13 @@ write_archive(const char *outname, const char **filename) int fd; a = archive_write_new(); mydata->name = outname; - archive_write_set_compression_gzip(a); - archive_write_set_format_ustar(a); + /* Set archive format and filter according to output file extension. + * If it fails, set default format. Platform depended function. + * See supported formats in archive_write_set_format_filter_by_ext.c */ + if (archive_write_set_format_filter_by_ext(a, outname) != ARCHIVE_OK) { + archive_write_add_filter_gzip(a); + archive_write_set_format_ustar(a); + } archive_write_open(a, mydata, myopen, mywrite, myclose); while (*filename) { stat(*filename, &st); @@ -557,77 +162,35 @@ write_archive(const char *outname, const char **filename) 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)); + if ((fd = open(*filename, O_RDONLY)) != -1) { + len = read(fd, buff, sizeof(buff)); + while (len > 0) { + archive_write_data(a, buff, len); + len = read(fd, buff, sizeof(buff)); + } + close(fd); } archive_entry_free(entry); filename++; } - archive_write_finish(a); + archive_write_free(a); } int main(int argc, const char **argv) { - const char *outname; - argv++; - outname = argv++; - write_archive(outname, argv); - return 0; + 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), +\fBarchive_write_set_options\fP(3), +\fBcpio\fP(5), +\fBmtree\fP(5), \fBtar\fP(5) .SH HISTORY .ad l |