d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clarify the naming: Methods that free an object should

Browse Source 
be called "free".  Retain the old "finish" names to preserve
source compatibility for now.
This commit is contained in:
Tim Kientzle 2010-11-05 05:11:54 +00:00
parent 68fdfe2926
commit be455be892
13 changed files with 116 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
lib/libarchive/archive.h
View File

@ -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.

2
lib/libarchive/archive_private.h
View File

@ -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 *);

8
lib/libarchive/archive_read.3
View File

@ -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);
}

8
lib/libarchive/archive_read.c
View File

@ -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);

10
lib/libarchive/archive_read_disk.3
View File

@ -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

6
lib/libarchive/archive_read_disk.c
View File

@ -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;

5
lib/libarchive/archive_read_extract.c
View File

@ -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);

34
lib/libarchive/archive_virtual.c
View File

@ -42,26 +42,35 @@ archive_read_close(struct archive *a)
return ((a->vtable->archive_close)(a));
}
#if ARCHIVE_API_VERSION > 1
int
archive_write_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_write_finish(struct archive *a)
{
return ((a->vtable->archive_finish)(a));
}
#else
/* Temporarily allow library to compile with either 1.x or 2.0 API. */
void
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));

22
lib/libarchive/archive_write.3
View File

@ -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

8
lib/libarchive/archive_write.c
View File

@ -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);

6
lib/libarchive/archive_write_disk.3
View File

@ -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.

6
lib/libarchive/archive_write_disk.c
View File

@ -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;

54
lib/libarchive/libarchive.3
View File

@ -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.)