diff options
Diffstat (limited to 'archivers/libarchive/files/doc/text/archive_write_open.3.txt')
| -rw-r--r-- | archivers/libarchive/files/doc/text/archive_write_open.3.txt | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/archivers/libarchive/files/doc/text/archive_write_open.3.txt b/archivers/libarchive/files/doc/text/archive_write_open.3.txt new file mode 100644 index 00000000000..ded6660bdd1 --- /dev/null +++ b/archivers/libarchive/files/doc/text/archive_write_open.3.txt @@ -0,0 +1,130 @@ +ARCHIVE_WRITE_OPEN(3) BSD Library Functions Manual ARCHIVE_WRITE_OPEN(3) + +NAME + archive_write_open, archive_write_open_fd, archive_write_open_FILE, + archive_write_open_filename, archive_write_open_memory — functions for + creating archives + +LIBRARY + Streaming Archive Library (libarchive, -larchive) + +SYNOPSIS + #include <archive.h> + + int + archive_write_open(struct archive *, void *client_data, + archive_open_callback *, archive_write_callback *, + archive_close_callback *); + + int + archive_write_open_fd(struct archive *, int fd); + + int + archive_write_open_FILE(struct archive *, FILE *file); + + int + archive_write_open_filename(struct archive *, const char *filename); + + int + archive_write_open_memory(struct archive *, void *buffer, + size_t bufferSize, size_t *outUsed); + +DESCRIPTION + archive_write_open() + 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 ar‐ + chive. + + archive_write_open_fd() + A convenience form of archive_write_open() that accepts a file + descriptor. The archive_write_open_fd() function is safe for use + with tape drives or other block-oriented devices. + + archive_write_open_FILE() + A convenience form of archive_write_open() that accepts a FILE * + pointer. Note that archive_write_open_FILE() is not safe for + writing to tape drives or other devices that require correct + blocking. + + archive_write_open_file() + A deprecated synonym for archive_write_open_filename(). + + archive_write_open_filename() + A convenience form of archive_write_open() that accepts a file‐ + name. A NULL argument indicates that the output should be writ‐ + ten to standard output; an argument of “-” will open a file with + that name. If you have not invoked + archive_write_set_bytes_in_last_block(), then + archive_write_open_filename() 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 archive_write_set_bytes_in_last_block() before calling + archive_write_open(). The archive_write_open_filename() function + is safe for use with tape drives or other block-oriented devices. + + archive_write_open_memory() + A convenience form of archive_write_open() that accepts a pointer + to a block of memory that will receive the archive. The final + size_t * 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 allo‐ + cated until after the archive is closed. + More information about the struct archive object and the overall design + of the library can be found in the libarchive(3) overview. + +CLIENT CALLBACKS + To use this library, you will need to define and register callback func‐ + tions that will be invoked to write data to the resulting archive. These + functions are registered by calling archive_write_open(): + + typedef int archive_open_callback(struct archive *, void + *client_data) + + The open callback is invoked by archive_write_open(). It should return + ARCHIVE_OK if the underlying file or data source is successfully opened. + If the open fails, it should call archive_set_error() to register an + error code and message and return ARCHIVE_FATAL. + + typedef la_ssize_t archive_write_callback(struct archive *, + void *client_data, const 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 call‐ + back function should translate into a single write(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 archive_set_error() to register an + error code and message and return -1. + + typedef int archive_close_callback(struct archive *, void + *client_data) + + The close callback is invoked by archive_close when the archive process‐ + ing is complete. The callback should return ARCHIVE_OK on success. On + failure, the callback should invoke archive_set_error() to register an + error code and message and return ARCHIVE_FATAL. + + 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 + archive_write_header(), archive_write_data(), archive_write_close(), + archive_write_finish(), or archive_write_free(). The client callback can + call archive_set_error() to provide values that can then be retrieved by + archive_errno() and archive_error_string(). + +RETURN VALUES + These functions return ARCHIVE_OK on success, or ARCHIVE_FATAL. + +ERRORS + Detailed error codes and textual descriptions are available from the + archive_errno() and archive_error_string() functions. + +SEE ALSO + tar(1), libarchive(3), archive_write(3), archive_write_filter(3), + archive_write_format(3), archive_write_new(3), + archive_write_set_options(3), cpio(5), mtree(5), tar(5) + +BSD February 2, 2012 BSD |