From 16f738ecee689c6feb2acb7e4ef4d9bb4144ae7d Mon Sep 17 00:00:00 2001 From: Tomas Bzatek Date: Sun, 8 Jun 2008 11:04:43 +0200 Subject: Initial commit --- .../libarchive-2.4.17/doc/man/archive_write.3 | 786 +++++++++++++++++++++ 1 file changed, 786 insertions(+) create mode 100644 libarchive/libarchive-2.4.17/doc/man/archive_write.3 (limited to 'libarchive/libarchive-2.4.17/doc/man/archive_write.3') diff --git a/libarchive/libarchive-2.4.17/doc/man/archive_write.3 b/libarchive/libarchive-2.4.17/doc/man/archive_write.3 new file mode 100644 index 0000000..c4b9395 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/man/archive_write.3 @@ -0,0 +1,786 @@ +.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 \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 +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: +.TP +.nh +\fBarchive_write_new\fP +.hy +(); +Allocates and initializes a +Tn struct archive +object suitable for writing a tar archive. +.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. +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 +.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. +.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. +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 +.nh +\fBarchive_write_open_filename\fP +.hy +(); +will set this based on the file type). +Unlike the other +``set'' +functions, this function can be called after the archive is opened. +.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. +.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 +``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 +.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. +.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. +.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. +.TP +.nh +\fBarchive_write_open_fd\fP +.hy +(); +A convenience form of +.nh +\fBarchive_write_open\fP +.hy +(); +that accepts a file descriptor. +The +.nh +\fBarchive_write_open_fd\fP +.hy +(); +function is safe for use with tape drives or other +block-oriented devices. +.TP +.nh +\fBarchive_write_open_FILE\fP +.hy +(); +A convenience form of +.nh +\fBarchive_write_open\fP +.hy +(); +that accepts a +\fI"FILE *"\fP +.RE +pointer. +Note that +.nh +\fBarchive_write_open_FILE\fP +.hy +(); +is not safe for writing to tape drives or other devices +that require correct blocking. +.TP +.nh +\fBarchive_write_open_file\fP +.hy +(); +A deprecated synonym for +.nh +\fBarchive_write_open_filename\fP +.hy +(.); +.TP +.nh +\fBarchive_write_open_filename\fP +.hy +(); +A convenience form of +.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 +``-'' +will open a file with that name. +If you have not invoked +.nh +\fBarchive_write_set_bytes_in_last_block\fP +.hy +(,); +then +.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 +.nh +\fBarchive_write_set_bytes_in_last_block\fP +.hy +(); +before calling +.nh +\fBarchive_write_open\fP +.hy +(.); +The +.nh +\fBarchive_write_open_filename\fP +.hy +(); +function is safe for use with tape drives or other +block-oriented devices. +.TP +.nh +\fBarchive_write_open_memory\fP +.hy +(); +A convenience form of +.nh +\fBarchive_write_open\fP +.hy +(); +that accepts a pointer to a block of memory that will receive +the archive. +The final +\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. +.TP +.nh +\fBarchive_write_header\fP +.hy +(); +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 +.nh +\fBarchive_write_data\fP +.hy +(); +Write data corresponding to the header just written. +Returns number of bytes written or -1 on error. +.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 +.nh +\fBarchive_write_next_header\fP +.hy +(); +and +.nh +\fBarchive_write_close\fP +.hy +(); +as needed. +.TP +.nh +\fBarchive_write_close\fP +.hy +(); +Complete the archive and invoke the close callback. +.TP +.nh +\fBarchive_write_finish\fP +.hy +(); +Invokes +.nh +\fBarchive_write_close\fP +.hy +(); +if it was not invoked manually, then releases all resources. +Note that this function was declared to return +\fIvoid\fP +.RE +in libarchive 1.x, which made it impossible to detect errors when +.nh +\fBarchive_write_close\fP +.hy +(); +was invoked implicitly from this function. +This is corrected beginning with libarchive 2.0. +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 +Compression support is built-in to libarchive, which uses zlib and bzlib +to handle gzip and bzip2 compression, respectively. +.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 +.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 +.nh +\fBarchive_write_open\fP +.hy +(.); +It should return +\fBARCHIVE_OK\fP +if the underlying file or data source is successfully +opened. +If the open fails, it should call +.nh +\fBarchive_set_error\fP +.hy +(); +to register an error code and message and return +\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 +\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 +.nh +\fBarchive_set_error\fP +.hy +(); +to register an error code and message and return -1. +.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 +\fBARCHIVE_OK\fP +on success. +On failure, the callback should invoke +.nh +\fBarchive_set_error\fP +.hy +(); +to register an error code and message and +return +\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 +\fBopen\fP(2), +\fBwrite\fP(2), +and +\fBclose\fP(2) +system calls. +.RS +#include +#include +#include +#include +#include +#include +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) +{ + 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 +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 +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(); +functions can be used to retrieve an appropriate error code and a +textual error message. +.nh +\fBarchive_write_new\fP +.hy +(); +returns a pointer to a newly-allocated +Tn struct archive +object. +.nh +\fBarchive_write_data\fP +.hy +(); +returns a count of the number of bytes actually written. +On error, -1 is returned and the +.nh +\fBarchive_errno\fP +.hy +(); +and +.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 +.nh +\fBarchive_write_header\fP +.hy +(,); +.nh +\fBarchive_write_data\fP +.hy +(,); +.nh +\fBarchive_write_close\fP +.hy +(,); +or +.nh +\fBarchive_write_finish\fP +.hy +(.); +The client callback can call +.nh +\fBarchive_set_error\fP +.hy +(); +to provide values that can then be retrieved by +.nh +\fBarchive_errno\fP +.hy +(); +and +.nh +\fBarchive_error_string\fP +.hy +(.); +.SH SEE ALSO +\fBtar\fP(1), +\fBlibarchive\fP(3), +\fBtar\fP(5) +.SH HISTORY +The +\fBlibarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +-nosplit +The +\fBlibarchive\fP +library was written by +Tim Kientzle +.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. +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 +\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 +created by this library. -- cgit v1.2.3