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 2e53bae476314e4d8b2f7c0f79323054850d921b..c23ab8021f486069d6d0a8d0b8341c3d77e3a090 100644 (file)
--- 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 (file)
index 0000000..4e03b19
--- /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