From: Roman Neuhauser Date: Mon, 28 Mar 2011 09:17:27 +0000 (-0400) Subject: archive_write_open.3: archive_write_open et al X-Git-Tag: v3.0.0a~583 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=befc8c63c657c4e483d87e7f7bf99ffca26198c0;p=thirdparty%2Flibarchive.git archive_write_open.3: archive_write_open et al SVN-Revision: 3095 --- diff --git a/libarchive/archive_write.3 b/libarchive/archive_write.3 index 2e53bae47..c23ab8021 100644 --- a/libarchive/archive_write.3 +++ b/libarchive/archive_write.3 @@ -28,11 +28,6 @@ .Dt archive_write 3 .Os .Sh NAME -.Nm archive_write_open , -.Nm archive_write_open_fd , -.Nm archive_write_open_FILE , -.Nm archive_write_open_filename , -.Nm archive_write_open_memory , .Nm archive_write_header , .Nm archive_write_data , .Nm archive_write_finish_entry , @@ -43,27 +38,6 @@ .Sh SYNOPSIS .In archive.h .Ft int -.Fo archive_write_open -.Fa "struct archive *" -.Fa "void *client_data" -.Fa "archive_open_callback *" -.Fa "archive_write_callback *" -.Fa "archive_close_callback *" -.Fc -.Ft int -.Fn archive_write_open_fd "struct archive *" "int fd" -.Ft int -.Fn archive_write_open_FILE "struct archive *" "FILE *file" -.Ft int -.Fn archive_write_open_filename "struct archive *" "const char *filename" -.Ft int -.Fo archive_write_open_memory -.Fa "struct archive *" -.Fa "void *buffer" -.Fa "size_t bufferSize" -.Fa "size_t *outUsed" -.Fc -.Ft int .Fn archive_write_header "struct archive *" "struct archive_entry *" .Ft ssize_t .Fn archive_write_data "struct archive *" "const void *" "size_t" @@ -96,72 +70,14 @@ and .Ss Configure block size and padding See .Xr archive_write_blocksize 3 . +.\" +.Ss Open archive +See +.Xr archive_write_open 3 . .Pp The following summary describes the functions in approximately the order they are ordinarily used: .Bl -tag -width indent -.It Fn 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 archive. -.It Fn archive_write_open_fd -A convenience form of -.Fn archive_write_open -that accepts a file descriptor. -The -.Fn archive_write_open_fd -function is safe for use with tape drives or other -block-oriented devices. -.It Fn archive_write_open_FILE -A convenience form of -.Fn archive_write_open -that accepts a -.Ft "FILE *" -pointer. -Note that -.Fn archive_write_open_FILE -is not safe for writing to tape drives or other devices -that require correct blocking. -.It Fn archive_write_open_file -A deprecated synonym for -.Fn archive_write_open_filename . -.It Fn archive_write_open_filename -A convenience form of -.Fn archive_write_open -that accepts a filename. -A NULL argument indicates that the output should be written to standard output; -an argument of -.Dq - -will open a file with that name. -If you have not invoked -.Fn archive_write_set_bytes_in_last_block , -then -.Fn 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 -.Fn archive_write_set_bytes_in_last_block -before calling -.Fn archive_write_open . -The -.Fn archive_write_open_filename -function is safe for use with tape drives or other -block-oriented devices. -.It Fn archive_write_open_memory -A convenience form of -.Fn archive_write_open -that accepts a pointer to a block of memory that will receive -the archive. -The final -.Ft "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 allocated until after the archive is -closed. .It Fn archive_write_header Build and write a header using the data in the provided .Tn struct archive_entry diff --git a/libarchive/archive_write_open.3 b/libarchive/archive_write_open.3 new file mode 100644 index 000000000..4e03b19c1 --- /dev/null +++ b/libarchive/archive_write_open.3 @@ -0,0 +1,231 @@ +.\" Copyright (c) 2003-2011 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libarchive/archive_write.3 201110 2009-12-28 03:31:29Z kientzle $ +.\" +.Dd March 23, 2011 +.Dt archive_write 3 +.Os +.Sh NAME +.Nm archive_write_open , +.Nm archive_write_open_fd , +.Nm archive_write_open_FILE , +.Nm archive_write_open_filename , +.Nm archive_write_open_memory +.Nd functions for creating archives +.Sh SYNOPSIS +.In archive.h +.Ft int +.Fo archive_write_open +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "archive_open_callback *" +.Fa "archive_write_callback *" +.Fa "archive_close_callback *" +.Fc +.Ft int +.Fn archive_write_open_fd "struct archive *" "int fd" +.Ft int +.Fn archive_write_open_FILE "struct archive *" "FILE *file" +.Ft int +.Fn archive_write_open_filename "struct archive *" "const char *filename" +.Ft int +.Fo archive_write_open_memory +.Fa "struct archive *" +.Fa "void *buffer" +.Fa "size_t bufferSize" +.Fa "size_t *outUsed" +.Fc +.Sh DESCRIPTION +.Bl -tag -width indent +.It Fn 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 archive. +.It Fn archive_write_open_fd +A convenience form of +.Fn archive_write_open +that accepts a file descriptor. +The +.Fn archive_write_open_fd +function is safe for use with tape drives or other +block-oriented devices. +.It Fn archive_write_open_FILE +A convenience form of +.Fn archive_write_open +that accepts a +.Ft "FILE *" +pointer. +Note that +.Fn archive_write_open_FILE +is not safe for writing to tape drives or other devices +that require correct blocking. +.It Fn archive_write_open_file +A deprecated synonym for +.Fn archive_write_open_filename . +.It Fn archive_write_open_filename +A convenience form of +.Fn archive_write_open +that accepts a filename. +A NULL argument indicates that the output should be written to standard output; +an argument of +.Dq - +will open a file with that name. +If you have not invoked +.Fn archive_write_set_bytes_in_last_block , +then +.Fn 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 +.Fn archive_write_set_bytes_in_last_block +before calling +.Fn archive_write_open . +The +.Fn archive_write_open_filename +function is safe for use with tape drives or other +block-oriented devices. +.It Fn archive_write_open_memory +A convenience form of +.Fn archive_write_open +that accepts a pointer to a block of memory that will receive +the archive. +The final +.Ft "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 allocated until after the archive is +closed. +.El +More information about the +.Va struct archive +object and the overall design of the library can be found in the +.Xr libarchive 3 +overview. +.\" +.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 +.Fn archive_write_open : +.Bl -item -offset indent +.It +.Ft typedef int +.Fn archive_open_callback "struct archive *" "void *client_data" +.El +.Pp +The open callback is invoked by +.Fn archive_write_open . +It should return +.Cm ARCHIVE_OK +if the underlying file or data source is successfully +opened. +If the open fails, it should call +.Fn archive_set_error +to register an error code and message and return +.Cm ARCHIVE_FATAL . +.Bl -item -offset indent +.It +.Ft typedef ssize_t +.Fo archive_write_callback +.Fa "struct archive *" +.Fa "void *client_data" +.Fa "const void *buffer" +.Fa "size_t length" +.Fc +.El +.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 +.Xr 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 +.Fn archive_set_error +to register an error code and message and return -1. +.Bl -item -offset indent +.It +.Ft typedef int +.Fn archive_close_callback "struct archive *" "void *client_data" +.El +.Pp +The close callback is invoked by archive_close when +the archive processing is complete. +The callback should return +.Cm ARCHIVE_OK +on success. +On failure, the callback should invoke +.Fn archive_set_error +to register an error code and message and +return +.Cm ARCHIVE_FATAL. +.\" .Sh EXAMPLE +.Sh RETURN VALUES +These functions return +.Cm ARCHIVE_OK +on success, or +.Cm ARCHIVE_FATAL . +.Pp +Detailed error codes and textual descriptions are available from the +.Fn archive_errno +and +.Fn archive_error_string +functions. +.Pp +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 +.Fn archive_write_header , +.Fn archive_write_data , +.Fn archive_write_close , +.Fn archive_write_finish , +or +.Fn archive_write_free . +The client callback can call +.Fn archive_set_error +to provide values that can then be retrieved by +.Fn archive_errno +and +.Fn archive_error_string . +.Sh SEE ALSO +.Xr tar 1 , +.Xr libarchive 3 , +.Xr archive_write 3 , +.Xr archive_write_filter 3 , +.Xr archive_write_format 3 , +.Xr archive_write_new 3 , +.Xr archive_write_set_options 3 , +.Xr cpio 5 , +.Xr mtree 5 , +.Xr tar 5