diff options
Diffstat (limited to 'libarchive/libarchive-2.4.17/doc/man/archive_write.3')
| -rw-r--r-- | libarchive/libarchive-2.4.17/doc/man/archive_write.3 | 786 |
1 files changed, 0 insertions, 786 deletions
diff --git a/libarchive/libarchive-2.4.17/doc/man/archive_write.3 b/libarchive/libarchive-2.4.17/doc/man/archive_write.3 deleted file mode 100644 index c4b9395..0000000 --- a/libarchive/libarchive-2.4.17/doc/man/archive_write.3 +++ /dev/null @@ -1,786 +0,0 @@ -.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 -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 <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) -{ - 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 <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. -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. |