diff options
author | Tim Kientzle <kientzle@FreeBSD.org> | 2010-11-05 05:11:54 +0000 |
---|---|---|
committer | Tim Kientzle <kientzle@FreeBSD.org> | 2010-11-05 05:11:54 +0000 |
commit | be455be892a17746fab131de4d6d49ab7a9feacc (patch) | |
tree | 5fef6efeec9e79e93d822f8fd3d8d137a4b74fcc | |
parent | 68fdfe2926e1fefffa8a14dbc7187619e6ecd81c (diff) | |
download | src-be455be892a17746fab131de4d6d49ab7a9feacc.tar.gz src-be455be892a17746fab131de4d6d49ab7a9feacc.zip |
Clarify the naming: Methods that free an object should
be called "free". Retain the old "finish" names to preserve
source compatibility for now.
Notes
Notes:
svn path=/head/; revision=214822
-rw-r--r-- | lib/libarchive/archive.h | 26 | ||||
-rw-r--r-- | lib/libarchive/archive_private.h | 2 | ||||
-rw-r--r-- | lib/libarchive/archive_read.3 | 8 | ||||
-rw-r--r-- | lib/libarchive/archive_read.c | 8 | ||||
-rw-r--r-- | lib/libarchive/archive_read_disk.3 | 10 | ||||
-rw-r--r-- | lib/libarchive/archive_read_disk.c | 6 | ||||
-rw-r--r-- | lib/libarchive/archive_read_extract.c | 5 | ||||
-rw-r--r-- | lib/libarchive/archive_virtual.c | 30 | ||||
-rw-r--r-- | lib/libarchive/archive_write.3 | 22 | ||||
-rw-r--r-- | lib/libarchive/archive_write.c | 8 | ||||
-rw-r--r-- | lib/libarchive/archive_write_disk.3 | 6 | ||||
-rw-r--r-- | lib/libarchive/archive_write_disk.c | 6 | ||||
-rw-r--r-- | lib/libarchive/libarchive.3 | 54 |
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.) |