Clarify the naming: Methods that free an object should

be called "free".  Retain the old "finish" names to preserve
source compatibility for now.

13 files changed, 114 insertions, 77 deletions

diff --git a/lib/libarchive/archive.h b/lib/libarchive/archive.h
index 23095313f99e..f97af7318cc8 100644
--- a/lib/libarchive/archive.h
+++ b/lib/libarchive/archive.h
@@ -482,11 +482,10 @@ __LA_DECL void		archive_read_extract_set_skip_file(struct archive *,
 /* 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(struct archive *);
  *      - 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_data_block(struct archive *,
 #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(struct archive *_a,
  *      - 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.
diff --git a/lib/libarchive/archive_private.h b/lib/libarchive/archive_private.h
index e09ddce0f51b..dc83048a592a 100644
--- a/lib/libarchive/archive_private.h
+++ b/lib/libarchive/archive_private.h
@@ -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 *);
diff --git a/lib/libarchive/archive_read.3 b/lib/libarchive/archive_read.3
index 0e8f45bb8372..850deb65a04c 100644
--- a/lib/libarchive/archive_read.3
+++ b/lib/libarchive/archive_read.3
@@ -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 that various statistics
 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);
 }
 
diff --git a/lib/libarchive/archive_read.c b/lib/libarchive/archive_read.c
index 91c5aa58854a..027ed6081821 100644
--- a/lib/libarchive/archive_read.c
+++ b/lib/libarchive/archive_read.c
@@ -60,7 +60,7 @@ static int	choose_format(struct archive_read *);
 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);
 
diff --git a/lib/libarchive/archive_read_disk.3 b/lib/libarchive/archive_read_disk.3
index 2b37e2cca895..290d3a1430b5 100644
--- a/lib/libarchive/archive_read_disk.3
+++ b/lib/libarchive/archive_read_disk.3
@@ -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 and ACL values in the
 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 char *name)
   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
diff --git a/lib/libarchive/archive_read_disk.c b/lib/libarchive/archive_read_disk.c
index 3c0b815af53b..3fd3133562a5 100644
--- a/lib/libarchive/archive_read_disk.c
+++ b/lib/libarchive/archive_read_disk.c
@@ -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;
 
diff --git a/lib/libarchive/archive_read_extract.c b/lib/libarchive/archive_read_extract.c
index 5ba8d22432b9..86b378ba1297 100644
--- a/lib/libarchive/archive_read_extract.c
+++ b/lib/libarchive/archive_read_extract.c
@@ -172,10 +172,7 @@ archive_read_extract_cleanup(struct archive_read *a)
 {
 	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);
diff --git a/lib/libarchive/archive_virtual.c b/lib/libarchive/archive_virtual.c
index 9ea24d09378d..0214b0090428 100644
--- a/lib/libarchive/archive_virtual.c
+++ b/lib/libarchive/archive_virtual.c
@@ -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 archive *a)
 	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));
diff --git a/lib/libarchive/archive_write.3 b/lib/libarchive/archive_write.3
index 797d51ea7fd3..2de392a6190d 100644
--- a/lib/libarchive/archive_write.3
+++ b/lib/libarchive/archive_write.3
@@ -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 char **filename)
     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
diff --git a/lib/libarchive/archive_write.c b/lib/libarchive/archive_write.c
index cd53fa1a6425..70af46f688d9 100644
--- a/lib/libarchive/archive_write.c
+++ b/lib/libarchive/archive_write.c
@@ -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);
 
diff --git a/lib/libarchive/archive_write_disk.3 b/lib/libarchive/archive_write_disk.3
index e7ef8c34ff89..61138b80e444 100644
--- a/lib/libarchive/archive_write_disk.3
+++ b/lib/libarchive/archive_write_disk.3
@@ -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.
diff --git a/lib/libarchive/archive_write_disk.c b/lib/libarchive/archive_write_disk.c
index 6abd195dd21d..f0ca52530d08 100644
--- a/lib/libarchive/archive_write_disk.c
+++ b/lib/libarchive/archive_write_disk.c
@@ -252,7 +252,7 @@ static ssize_t	write_data_block(struct archive_write_disk *,
 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;
diff --git a/lib/libarchive/libarchive.3 b/lib/libarchive/libarchive.3
index ae50637d3938..115a79c0f16f 100644
--- a/lib/libarchive/libarchive.3
+++ b/lib/libarchive/libarchive.3
@@ -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 the archive, you
 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 can easily accommodate pathnames
 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.)