svn commit: r214822 - head/lib/libarchive
Tim Kientzle
kientzle at FreeBSD.org
Fri Nov 5 05:11:54 UTC 2010
Author: kientzle
Date: Fri Nov 5 05:11:54 2010
New Revision: 214822
URL: http://svn.freebsd.org/changeset/base/214822
Log:
Clarify the naming: Methods that free an object should
be called "free". Retain the old "finish" names to preserve
source compatibility for now.
Modified:
head/lib/libarchive/archive.h
head/lib/libarchive/archive_private.h
head/lib/libarchive/archive_read.3
head/lib/libarchive/archive_read.c
head/lib/libarchive/archive_read_disk.3
head/lib/libarchive/archive_read_disk.c
head/lib/libarchive/archive_read_extract.c
head/lib/libarchive/archive_virtual.c
head/lib/libarchive/archive_write.3
head/lib/libarchive/archive_write.c
head/lib/libarchive/archive_write_disk.3
head/lib/libarchive/archive_write_disk.c
head/lib/libarchive/libarchive.3
Modified: head/lib/libarchive/archive.h
==============================================================================
--- head/lib/libarchive/archive.h Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive.h Fri Nov 5 05:11:54 2010 (r214822)
@@ -482,11 +482,10 @@ __LA_DECL void archive_read_extract_set
/* Close the file and release most resources. */
__LA_DECL int archive_read_close(struct archive *);
/* Release all resources and destroy the object. */
-/* Note that archive_read_finish will call archive_read_close for you. */
-#if ARCHIVE_VERSION_NUMBER < 2000000
-/* Erroneously declared to return void in libarchive 1.x */
-__LA_DECL void archive_read_finish(struct archive *);
-#else
+/* Note that archive_read_free will call archive_read_close for you. */
+__LA_DECL int archive_read_free(struct archive *);
+#if ARCHIVE_VERSION_NUMBER < 4000000
+/* Synonym for archive_read_free() for backwards compatibility. */
__LA_DECL int archive_read_finish(struct archive *);
#endif
@@ -503,7 +502,7 @@ __LA_DECL int archive_read_finish(stru
* - archive_write_header to write the header
* - archive_write_data to write the entry data
* 5) archive_write_close to close the output
- * 6) archive_write_finish to cleanup the writer and release resources
+ * 6) archive_write_free to cleanup the writer and release resources
*/
__LA_DECL struct archive *archive_write_new(void);
__LA_DECL int archive_write_set_bytes_per_block(struct archive *,
@@ -584,13 +583,12 @@ __LA_DECL __LA_SSIZE_T archive_write_da
#endif
__LA_DECL int archive_write_finish_entry(struct archive *);
__LA_DECL int archive_write_close(struct archive *);
-#if ARCHIVE_VERSION_NUMBER < 2000000
-/* Return value was incorrect in libarchive 1.x. */
-__LA_DECL void archive_write_finish(struct archive *);
-#else
-/* Libarchive 2.x and later returns an error if this fails. */
-/* It can fail if the archive wasn't already closed, in which case
- * archive_write_finish() will implicitly call archive_write_close(). */
+
+/* This can fail if the archive wasn't already closed, in which case
+ * archive_write_free() will implicitly call archive_write_close(). */
+__LA_DECL int archive_write_free(struct archive *);
+#if ARCHIVE_VERSION_NUMBER < 4000000
+/* Synonym for archive_write_free() for backwards compatibility. */
__LA_DECL int archive_write_finish(struct archive *);
#endif
@@ -619,7 +617,7 @@ __LA_DECL int archive_write_set_options
* - construct an appropriate struct archive_entry structure
* - archive_write_header to create the file/dir/etc on disk
* - archive_write_data to write the entry data
- * 4) archive_write_finish to cleanup the writer and release resources
+ * 4) archive_write_free to cleanup the writer and release resources
*
* In particular, you can use this in conjunction with archive_read()
* to pull entries out of an archive and create them on disk.
Modified: head/lib/libarchive/archive_private.h
==============================================================================
--- head/lib/libarchive/archive_private.h Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive_private.h Fri Nov 5 05:11:54 2010 (r214822)
@@ -58,7 +58,7 @@
struct archive_vtable {
int (*archive_close)(struct archive *);
- int (*archive_finish)(struct archive *);
+ int (*archive_free)(struct archive *);
int (*archive_write_header)(struct archive *,
struct archive_entry *);
int (*archive_write_finish_entry)(struct archive *);
Modified: head/lib/libarchive/archive_read.3
==============================================================================
--- head/lib/libarchive/archive_read.3 Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive_read.3 Fri Nov 5 05:11:54 2010 (r214822)
@@ -69,7 +69,7 @@
.Nm archive_read_extract2 ,
.Nm archive_read_extract_set_progress_callback ,
.Nm archive_read_close ,
-.Nm archive_read_finish
+.Nm archive_read_free
.Nd functions for reading streaming archives
.Sh SYNOPSIS
.In archive.h
@@ -196,7 +196,7 @@
.Ft int
.Fn archive_read_close "struct archive *"
.Ft int
-.Fn archive_read_finish "struct archive *"
+.Fn archive_read_free "struct archive *"
.Sh DESCRIPTION
These functions provide a complete API for reading streaming archives.
The general process is to first create the
@@ -457,7 +457,7 @@ object and the archive_entry object so t
can be retrieved for the progress display.
.It Fn archive_read_close
Complete the archive and invoke the close callback.
-.It Fn archive_read_finish
+.It Fn archive_read_free
Invokes
.Fn archive_read_close
if it was not invoked manually, then release all resources.
@@ -600,7 +600,7 @@ list_archive(const char *name)
printf("%s\\n",archive_entry_pathname(entry));
archive_read_data_skip(a);
}
- archive_read_finish(a);
+ archive_read_free(a);
free(mydata);
}
Modified: head/lib/libarchive/archive_read.c
==============================================================================
--- head/lib/libarchive/archive_read.c Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive_read.c Fri Nov 5 05:11:54 2010 (r214822)
@@ -60,7 +60,7 @@ static int choose_format(struct archive_
static int cleanup_filters(struct archive_read *);
static struct archive_vtable *archive_read_vtable(void);
static int _archive_read_close(struct archive *);
-static int _archive_read_finish(struct archive *);
+static int _archive_read_free(struct archive *);
static struct archive_vtable *
archive_read_vtable(void)
@@ -69,7 +69,7 @@ archive_read_vtable(void)
static int inited = 0;
if (!inited) {
- av.archive_finish = _archive_read_finish;
+ av.archive_free = _archive_read_free;
av.archive_close = _archive_read_close;
}
return (&av);
@@ -779,7 +779,7 @@ cleanup_filters(struct archive_read *a)
* Release memory and other resources.
*/
static int
-_archive_read_finish(struct archive *_a)
+_archive_read_free(struct archive *_a)
{
struct archive_read *a = (struct archive_read *)_a;
int i;
@@ -787,7 +787,7 @@ _archive_read_finish(struct archive *_a)
int r = ARCHIVE_OK;
__archive_check_magic(_a, ARCHIVE_READ_MAGIC, ARCHIVE_STATE_ANY,
- "archive_read_finish");
+ "archive_read_free");
if (a->archive.state != ARCHIVE_STATE_CLOSED)
r = archive_read_close(&a->archive);
Modified: head/lib/libarchive/archive_read_disk.3
==============================================================================
--- head/lib/libarchive/archive_read_disk.3 Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive_read_disk.3 Fri Nov 5 05:11:54 2010 (r214822)
@@ -39,7 +39,7 @@
.Nm archive_read_disk_set_gname_lookup ,
.Nm archive_read_disk_set_standard_lookup ,
.Nm archive_read_close ,
-.Nm archive_read_finish
+.Nm archive_read_free
.Nd functions for reading objects from disk
.Sh SYNOPSIS
.In archive.h
@@ -81,7 +81,7 @@
.Ft int
.Fn archive_read_close "struct archive *"
.Ft int
-.Fn archive_read_finish "struct archive *"
+.Fn archive_read_free "struct archive *"
.Sh DESCRIPTION
These functions provide an API for reading information about
objects on disk.
@@ -178,9 +178,9 @@ This affects the file ownership fields a
object.
.It Fn archive_read_close
This currently does nothing.
-.It Fn archive_write_finish
+.It Fn archive_read_free
Invokes
-.Fn archive_write_close
+.Fn archive_read_close
if it was not invoked manually, then releases all resources.
.El
More information about the
@@ -213,7 +213,7 @@ file_to_archive(struct archive *a, const
while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
archive_write_data(a, buff, bytes_read);
archive_write_finish_entry(a);
- archive_read_finish(ard);
+ archive_read_free(ard);
archive_entry_free(entry);
}
.Ed
Modified: head/lib/libarchive/archive_read_disk.c
==============================================================================
--- head/lib/libarchive/archive_read_disk.c Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive_read_disk.c Fri Nov 5 05:11:54 2010 (r214822)
@@ -33,7 +33,7 @@ __FBSDID("$FreeBSD$");
#include "archive_private.h"
#include "archive_read_disk_private.h"
-static int _archive_read_finish(struct archive *);
+static int _archive_read_free(struct archive *);
static int _archive_read_close(struct archive *);
static const char *trivial_lookup_gname(void *, gid_t gid);
static const char *trivial_lookup_uname(void *, uid_t uid);
@@ -45,7 +45,7 @@ archive_read_disk_vtable(void)
static int inited = 0;
if (!inited) {
- av.archive_finish = _archive_read_finish;
+ av.archive_free = _archive_read_free;
av.archive_close = _archive_read_close;
}
return (&av);
@@ -129,7 +129,7 @@ archive_read_disk_new(void)
}
static int
-_archive_read_finish(struct archive *_a)
+_archive_read_free(struct archive *_a)
{
struct archive_read_disk *a = (struct archive_read_disk *)_a;
Modified: head/lib/libarchive/archive_read_extract.c
==============================================================================
--- head/lib/libarchive/archive_read_extract.c Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive_read_extract.c Fri Nov 5 05:11:54 2010 (r214822)
@@ -172,10 +172,7 @@ archive_read_extract_cleanup(struct arch
{
int ret = ARCHIVE_OK;
-#if ARCHIVE_API_VERSION > 1
- ret =
-#endif
- archive_write_finish(a->extract->ad);
+ ret = archive_write_free(a->extract->ad);
free(a->extract);
a->extract = NULL;
return (ret);
Modified: head/lib/libarchive/archive_virtual.c
==============================================================================
--- head/lib/libarchive/archive_virtual.c Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive_virtual.c Fri Nov 5 05:11:54 2010 (r214822)
@@ -42,26 +42,35 @@ archive_read_close(struct archive *a)
return ((a->vtable->archive_close)(a));
}
-#if ARCHIVE_API_VERSION > 1
int
-archive_write_finish(struct archive *a)
+archive_write_free(struct archive *a)
{
- return ((a->vtable->archive_finish)(a));
+ return ((a->vtable->archive_free)(a));
}
-#else
-/* Temporarily allow library to compile with either 1.x or 2.0 API. */
-void
+
+#if ARCHIVE_VERSION_NUMBER < 4000000
+/* For backwards compatibility; will be removed with libarchive 4.0. */
+int
archive_write_finish(struct archive *a)
{
- (void)(a->vtable->archive_finish)(a);
+ return ((a->vtable->archive_free)(a));
}
#endif
int
+archive_read_free(struct archive *a)
+{
+ return ((a->vtable->archive_free)(a));
+}
+
+#if ARCHIVE_VERSION_NUMBER < 4000000
+/* For backwards compatibility; will be removed with libarchive 4.0. */
+int
archive_read_finish(struct archive *a)
{
- return ((a->vtable->archive_finish)(a));
+ return ((a->vtable->archive_free)(a));
}
+#endif
int
archive_write_header(struct archive *a, struct archive_entry *entry)
@@ -76,12 +85,7 @@ archive_write_finish_entry(struct archiv
return ((a->vtable->archive_write_finish_entry)(a));
}
-#if ARCHIVE_API_VERSION > 1
ssize_t
-#else
-/* Temporarily allow library to compile with either 1.x or 2.0 API. */
-int
-#endif
archive_write_data(struct archive *a, const void *buff, size_t s)
{
return ((a->vtable->archive_write_data)(a, buff, s));
Modified: head/lib/libarchive/archive_write.3
==============================================================================
--- head/lib/libarchive/archive_write.3 Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive_write.3 Fri Nov 5 05:11:54 2010 (r214822)
@@ -55,7 +55,7 @@
.Nm archive_write_data ,
.Nm archive_write_finish_entry ,
.Nm archive_write_close ,
-.Nm archive_write_finish
+.Nm archive_write_free
.Nd functions for creating archives
.Sh SYNOPSIS
.In archive.h
@@ -125,7 +125,7 @@
.Ft int
.Fn archive_write_close "struct archive *"
.Ft int
-.Fn archive_write_finish "struct archive *"
+.Fn archive_write_free "struct archive *"
.Sh DESCRIPTION
These functions provide a complete API for creating streaming
archive files.
@@ -363,16 +363,16 @@ and
as needed.
.It Fn archive_write_close
Complete the archive and invoke the close callback.
-.It Fn archive_write_finish
+.It Fn archive_write_free
Invokes
.Fn archive_write_close
-if it was not invoked manually, then releases all resources.
-Note that this function was declared to return
-.Ft void
-in libarchive 1.x, which made it impossible to detect errors when
+if necessary, then releases all resources.
+If you need detailed information about
.Fn archive_write_close
-was invoked implicitly from this function.
-This is corrected beginning with libarchive 2.0.
+failures, you should be careful to call it separately, as
+you cannot obtain error information after
+.Fn archive_write_free
+returns.
.El
More information about the
.Va struct archive
@@ -529,7 +529,7 @@ write_archive(const char *outname, const
archive_entry_free(entry);
filename++;
}
- archive_write_finish(a);
+ archive_write_free(a);
}
int main(int argc, const char **argv)
@@ -580,7 +580,7 @@ may include
.Fn archive_write_data ,
.Fn archive_write_close ,
or
-.Fn archive_write_finish .
+.Fn archive_write_free .
The client callback can call
.Fn archive_set_error
to provide values that can then be retrieved by
Modified: head/lib/libarchive/archive_write.c
==============================================================================
--- head/lib/libarchive/archive_write.c Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive_write.c Fri Nov 5 05:11:54 2010 (r214822)
@@ -60,7 +60,7 @@ __FBSDID("$FreeBSD$");
static struct archive_vtable *archive_write_vtable(void);
static int _archive_write_close(struct archive *);
-static int _archive_write_finish(struct archive *);
+static int _archive_write_free(struct archive *);
static int _archive_write_header(struct archive *, struct archive_entry *);
static int _archive_write_finish_entry(struct archive *);
static ssize_t _archive_write_data(struct archive *, const void *, size_t);
@@ -73,7 +73,7 @@ archive_write_vtable(void)
if (!inited) {
av.archive_close = _archive_write_close;
- av.archive_finish = _archive_write_finish;
+ av.archive_free = _archive_write_free;
av.archive_write_header = _archive_write_header;
av.archive_write_finish_entry = _archive_write_finish_entry;
av.archive_write_data = _archive_write_data;
@@ -383,13 +383,13 @@ _archive_write_close(struct archive *_a)
* Destroy the archive structure.
*/
static int
-_archive_write_finish(struct archive *_a)
+_archive_write_free(struct archive *_a)
{
struct archive_write *a = (struct archive_write *)_a;
int r = ARCHIVE_OK;
__archive_check_magic(&a->archive, ARCHIVE_WRITE_MAGIC,
- ARCHIVE_STATE_ANY, "archive_write_finish");
+ ARCHIVE_STATE_ANY, "archive_write_free");
if (a->archive.state != ARCHIVE_STATE_CLOSED)
r = archive_write_close(&a->archive);
Modified: head/lib/libarchive/archive_write_disk.3
==============================================================================
--- head/lib/libarchive/archive_write_disk.3 Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive_write_disk.3 Fri Nov 5 05:11:54 2010 (r214822)
@@ -38,7 +38,7 @@
.Nm archive_write_data ,
.Nm archive_write_finish_entry ,
.Nm archive_write_close ,
-.Nm archive_write_finish
+.Nm archive_write_free
.Nd functions for creating objects on disk
.Sh SYNOPSIS
.In archive.h
@@ -73,7 +73,7 @@
.Ft int
.Fn archive_write_close "struct archive *"
.Ft int
-.Fn archive_write_finish "struct archive *"
+.Fn archive_write_free "struct archive *"
.Sh DESCRIPTION
These functions provide a complete API for creating objects on
disk from
@@ -239,7 +239,7 @@ The
.Nm
library maintains a list of all such deferred attributes and
sets them when this function is invoked.
-.It Fn archive_write_finish
+.It Fn archive_write_free
Invokes
.Fn archive_write_close
if it was not invoked manually, then releases all resources.
Modified: head/lib/libarchive/archive_write_disk.c
==============================================================================
--- head/lib/libarchive/archive_write_disk.c Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/archive_write_disk.c Fri Nov 5 05:11:54 2010 (r214822)
@@ -252,7 +252,7 @@ static ssize_t write_data_block(struct a
static struct archive_vtable *archive_write_disk_vtable(void);
static int _archive_write_close(struct archive *);
-static int _archive_write_finish(struct archive *);
+static int _archive_write_free(struct archive *);
static int _archive_write_header(struct archive *, struct archive_entry *);
static int _archive_write_finish_entry(struct archive *);
static ssize_t _archive_write_data(struct archive *, const void *, size_t);
@@ -291,7 +291,7 @@ archive_write_disk_vtable(void)
if (!inited) {
av.archive_close = _archive_write_close;
- av.archive_finish = _archive_write_finish;
+ av.archive_free = _archive_write_free;
av.archive_write_header = _archive_write_header;
av.archive_write_finish_entry = _archive_write_finish_entry;
av.archive_write_data = _archive_write_data;
@@ -1295,7 +1295,7 @@ _archive_write_close(struct archive *_a)
}
static int
-_archive_write_finish(struct archive *_a)
+_archive_write_free(struct archive *_a)
{
struct archive_write_disk *a = (struct archive_write_disk *)_a;
int ret;
Modified: head/lib/libarchive/libarchive.3
==============================================================================
--- head/lib/libarchive/libarchive.3 Fri Nov 5 02:45:13 2010 (r214821)
+++ head/lib/libarchive/libarchive.3 Fri Nov 5 05:11:54 2010 (r214822)
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd July 17, 2010
+.Dd February 6, 2010
.Dt LIBARCHIVE 3
.Os
.Sh NAME
@@ -61,13 +61,14 @@ GNU-format tar archives,
.It
most common cpio archive formats,
.It
-ISO9660 CD images (with or without RockRidge extensions),
+ISO9660 CD images (including RockRidge and Joliet extensions),
.It
Zip archives.
.El
The library automatically detects archives compressed with
.Xr gzip 1 ,
.Xr bzip2 1 ,
+.Xr xz 1 ,
or
.Xr compress 1
and decompresses them transparently.
@@ -87,6 +88,8 @@ archives,
.It
POSIX octet-oriented cpio archives,
.It
+Zip archive,
+.It
two different variants of shar archives.
.El
Pax interchange format is an extension of the tar archive format that
@@ -168,12 +171,12 @@ You can use
(which works much like the
.Xr read 2
system call)
-to read this data from the archive.
+to read this data from the archive, or
+.Fn archive_read_data_block
+which provides a slightly more efficient interface.
You may prefer to use the higher-level
.Fn archive_read_data_skip ,
which reads and discards the data for this entry,
-.Fn archive_read_data_to_buffer ,
-which reads the data into an in-memory buffer,
.Fn archive_read_data_to_file ,
which copies the data to the provided file descriptor, or
.Fn archive_read_extract ,
@@ -192,7 +195,7 @@ Once you have finished reading data from
should call
.Fn archive_read_close
to close the archive, then call
-.Fn archive_read_finish
+.Fn archive_read_free
to release all resources, including all memory allocated by the library.
.Pp
The
@@ -230,12 +233,34 @@ You can then use
to write the actual data.
.Pp
After all entries have been written, use the
-.Fn archive_write_finish
+.Fn archive_write_free
function to release all resources.
.Pp
The
.Xr archive_write 3
manual page provides more detailed calling information for this API.
+.Sh WRITING ENTRIES TO DISK
+The
+.Xr archive_write_disk 3
+API allows you to write
+.Xr archive_entry 3
+objects to disk using the same API used by
+.Xr archive_write 3 .
+The
+.Xr archive_write_disk 3
+API is used internally by
+.Fn archive_read_extract ;
+using it directly can provide greater control over how entries
+get written to disk.
+This API also makes it possible to share code between
+archive-to-archive copy and archive-to-disk extraction
+operations.
+.Sh READING ENTRIES FROM DISK
+The
+.Xr archive_read_disk 3
+provides some support for populating
+.Xr archive_entry 3
+objects from information in the filesystem.
.Sh DESCRIPTION
Detailed descriptions of each function are provided by the
corresponding manual pages.
@@ -259,7 +284,9 @@ In particular, pax interchange format ca
in arbitrary character sets that exceed
.Va PATH_MAX .
.Sh RETURN VALUES
-Most functions return zero on success, non-zero on error.
+Most functions return
+.Cm ARCHIVE_OK
+(zero) on success, non-zero on error.
The return value indicates the general severity of the error, ranging
from
.Cm ARCHIVE_WARN ,
@@ -329,3 +356,14 @@ stored in a
is supported by all formats.
For example, cpio formats do not support nanosecond timestamps;
old tar formats do not support large device numbers.
+.Pp
+The
+.Xr archive_read_disk 3
+API should support iterating over filesystems;
+that would make it possible to share code among
+disk-to-archive, archive-to-archive, archive-to-disk,
+and disk-to-disk operations.
+Currently, it only supports reading the
+information for a single file.
+(Which is still quite useful, as it hides a lot
+of system-specific details.)
More information about the svn-src-head
mailing list