mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-14 10:09:48 +00:00
71b44796d9
with 'star' ACL handling, though there's still a bit more work needed in this area. Added 'write_open_fd' and 'read_open_fd' to simplify, e.g., tar's u and r modes. Eliminated old 'write_open_file_position' as a bad idea. (It required closing/reopening files to do updates, which led to unpleasant implications.) Various other minor fixes, API tweaks, etc.
371 lines
12 KiB
Groff
371 lines
12 KiB
Groff
.\" Copyright (c) 2003-2004 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$
|
|
.\"
|
|
.Dd October 1, 2003
|
|
.Dt archive_write 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm archive_write_new ,
|
|
.Nm archive_write_set_format_cpio ,
|
|
.Nm archive_write_set_format_pax ,
|
|
.Nm archive_write_set_format_pax_restricted ,
|
|
.Nm archive_write_set_format_shar ,
|
|
.Nm archive_write_set_format_shar_binary ,
|
|
.Nm archive_write_set_format_ustar ,
|
|
.Nm archive_write_set_bytes_per_block ,
|
|
.Nm archive_write_set_bytes_in_last_block ,
|
|
.Nm archive_write_set_compressor_gzip ,
|
|
.Nm archive_write_set_compressor_bzip2 ,
|
|
.Nm archive_write_open ,
|
|
.Nm archive_write_open_fd ,
|
|
.Nm archive_write_open_file ,
|
|
.Nm archive_write_prepare ,
|
|
.Nm archive_write_header ,
|
|
.Nm archive_write_data ,
|
|
.Nm archive_write_finish
|
|
.Nd functions for creating archives
|
|
.Sh SYNOPSIS
|
|
.In archive.h
|
|
.Ft struct archive *
|
|
.Fn archive_write_new "void"
|
|
.Ft int
|
|
.Fn archive_write_set_bytes_per_block "archive *" "int bytes_per_block"
|
|
.Ft int
|
|
.Fn archive_write_set_bytes_in_last_block "archive *" "int"
|
|
.Ft int
|
|
.Fn archive_write_set_compressor_gzip "struct archive *"
|
|
.Ft int
|
|
.Fn archive_write_set_compressor_bzip2 "struct archive *"
|
|
.Ft int
|
|
.Fn archive_write_set_format_cpio "struct archive *"
|
|
.Ft int
|
|
.Fn archive_write_set_format_pax "struct archive *"
|
|
.Ft int
|
|
.Fn archive_write_set_format_pax_restricted "struct archive *"
|
|
.Ft int
|
|
.Fn archive_write_set_format_shar "struct archive *"
|
|
.Ft int
|
|
.Fn archive_write_set_format_shar_binary "struct archive *"
|
|
.Ft int
|
|
.Fn archive_write_set_format_ustar "struct archive *"
|
|
.Ft int
|
|
.Fn archive_write_open "struct archive *" "void *client_data" "archive_write_archive_callback *" "archive_open_archive_callback *" "archive_close_archive_callback *"
|
|
.Ft int
|
|
.Fn archive_write_open_fd "struct archive *" "int fd"
|
|
.Ft int
|
|
.Fn archive_write_open_file "struct archive *" "const char *filename"
|
|
.Ft int
|
|
.Fn archive_write_header "struct archive *"
|
|
.Ft int
|
|
.Fn archive_write_data "struct archive *" "const void *" "size_t"
|
|
.Ft int
|
|
.Fn archive_write_finish "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:
|
|
.Bl -tag -width indent
|
|
.It Fn archive_write_new
|
|
Allocates and initializes a
|
|
.Tn struct archive
|
|
object suitable for writing a tar archive.
|
|
.It Fn archive_write_set_bytes_per_block
|
|
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.
|
|
.It Fn archive_write_set_bytes_in_last_block
|
|
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
|
|
.Fn archive_write_open_file
|
|
will set this based on the file type).
|
|
Unlike the other
|
|
.Dq set
|
|
functions, this function can be called after the archive is opened.
|
|
.It Fn archive_write_set_format_cpio , Fn archive_write_set_format_pax , Fn archive_write_set_format_pax_restricted , Fn archive_write_set_format_shar , Fn archive_write_set_format_shar_binary , Fn archive_write_set_format_ustar
|
|
Sets the format that will be used for the archive.
|
|
The library can write
|
|
POSIX octet-oriented cpio format archives,
|
|
POSIX-standard
|
|
.Dq pax interchange
|
|
format archives,
|
|
traditional
|
|
.Dq shar
|
|
archives,
|
|
enhanced
|
|
.Dq binary
|
|
shar archives that store a variety of file attributes and handle binary files,
|
|
and
|
|
POSIX-standard
|
|
.Dq 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.
|
|
.Dq 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.
|
|
.It Fn archive_write_set_compression_gzip , Fn archive_write_set_compression_bzip2
|
|
The resulting archive will be compressed as specified.
|
|
Note that the compressed output is always properly blocked.
|
|
.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 library to write the constructed archive.
|
|
Note: Internally, the callbacks are invoked by the compression layer.
|
|
In order to support external compression programs, the compression
|
|
is permitted to fork and invoke the callbacks from a separate process.
|
|
In particular, clients should not assume that they can communicate
|
|
between the callbacks and the mainline code using shared variables.
|
|
Note that the standard gzip, bzip2, and "none" compression methods do not fork.
|
|
.It Fn archive_write_open_fd
|
|
A convenience form of
|
|
.Fn archive_write_open
|
|
that accepts a file descriptor.
|
|
.It Fn archive_write_open_file
|
|
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_file
|
|
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
|
|
either before or after calling
|
|
.Fn archive_write_open .
|
|
.It Fn archive_write_header
|
|
Build and write a header using the data in the provided
|
|
.Tn struct archive_entry
|
|
structure.
|
|
.It Fn archive_write_data
|
|
Write data corresponding to the header just written.
|
|
.It Fn archive_write_finish
|
|
Complete the archive, invoke the close callback, and release
|
|
all resources.
|
|
.El
|
|
.Pp
|
|
The callback functions are defined as follows:
|
|
.Bl -item -offset indent
|
|
.It
|
|
.Ft typedef ssize_t
|
|
.Fn archive_write_archive_callback "struct archive *" "void *client_data" "void *buffer" "size_t length"
|
|
.It
|
|
.Ft typedef int
|
|
.Fn archive_open_archive_callback "struct archive *" "void *client_data"
|
|
.It
|
|
.Ft typedef int
|
|
.Fn archive_close_archive_callback "struct archive *" "void *client_data"
|
|
.El
|
|
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 tar archives to tape drives.
|
|
.Pp
|
|
More information about tar archive formats and blocking can be found
|
|
in the
|
|
.Xr tar 5
|
|
manual page.
|
|
.Pp
|
|
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 IMPLEMENTATION
|
|
Compression support is built-in to libarchive, which uses zlib and bzlib
|
|
to handle gzip and bzip2 compression, respectively.
|
|
.Sh EXAMPLE
|
|
The following sketch illustrates basic usage of the library. In this example,
|
|
the callback functions are simply wrappers around the standard
|
|
.Xr open 2 ,
|
|
.Xr write 2 ,
|
|
and
|
|
.Xr close 2
|
|
system calls.
|
|
.Bd -literal -offset indent
|
|
void
|
|
write_archive(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;
|
|
|
|
a = archive_write_new();
|
|
mydata->name = name;
|
|
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
|
|
myopen(struct archive *a, void *client_data)
|
|
{
|
|
struct mydata *mydata = client_data;
|
|
|
|
mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
|
|
return (mydata->fd >= 0);
|
|
}
|
|
|
|
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);
|
|
}
|
|
.Ed
|
|
.Sh RETURN VALUES
|
|
Most functions return zero on success, non-zero on error.
|
|
The
|
|
.Fn archive_errno
|
|
and
|
|
.Fn archive_error_string
|
|
functions can be used to retrieve an appropriate error code and a
|
|
textual error message.
|
|
.Pp
|
|
.Fn archive_write_new
|
|
returns a pointer to a newly-allocated
|
|
.Tn struct archive
|
|
object.
|
|
.Pp
|
|
.Fn archive_write_data
|
|
returns a count of the number of bytes actually written.
|
|
On error, -1 is returned and the
|
|
.Fn archive_errno
|
|
and
|
|
.Fn archive_error_string
|
|
functions will return appropriate values.
|
|
Note that if the client-provided write callback function
|
|
returns -1, 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 ,
|
|
or
|
|
.Fn archive_write_finish .
|
|
In such a case, the
|
|
.Fn archive_errno
|
|
or
|
|
.Fn archive_error_string
|
|
fields will not return useful information; you should use
|
|
client-private data to return error information
|
|
back to your mainline code.
|
|
.Sh SEE ALSO
|
|
.Xr tar 1 ,
|
|
.Xr libarchive 3 ,
|
|
.Xr tar 5 .
|
|
.Sh HISTORY
|
|
The
|
|
.Nm libarchive
|
|
library first appeared in
|
|
.Fx 5.3 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm libarchive
|
|
library was written by
|
|
.An Tim Kientzle Aq 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.
|
|
.Pp
|
|
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
|
|
.Dq SCHILY.devminor
|
|
and
|
|
.Dq SCHILY.devmajor
|
|
for device numbers that exceed the range supported by the backwards-compatible
|
|
ustar header.
|
|
These keys are compatible with Joerg Schilling's
|
|
.Nm star
|
|
archiver.
|
|
Other implementations may not recognize these keys and will thus be unable
|
|
to correctly restore large device numbers archived by this library.
|