From baea7d877d3cf69679a39e8512a120658a478073 Mon Sep 17 00:00:00 2001 From: Tomas Bzatek Date: Fri, 5 Feb 2010 11:06:31 +0100 Subject: Rebase libarchive to 2.8.0 --- .../doc/html/archive_read_disk.3.html | 341 +++++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100644 libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html (limited to 'libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html') diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html new file mode 100644 index 0000000..2257ffe --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html @@ -0,0 +1,341 @@ + + + + + + + + + + + + + +
+ + +

archive_read_disk(3) FreeBSD Library +Functions Manual archive_read_disk(3)

+ +

NAME

+ +

archive_read_disk_new, +archive_read_disk_set_symlink_logical, +archive_read_disk_set_symlink_physical, +archive_read_disk_set_symlink_hybrid, +archive_read_disk_entry_from_file, +archive_read_disk_gname, +archive_read_disk_uname, +archive_read_disk_set_uname_lookup, +archive_read_disk_set_gname_lookup, +archive_read_disk_set_standard_lookup, +archive_read_close, archive_read_finish +— functions for reading objects from disk

+ + +

SYNOPSIS

+ +

#include +<archive.h>

+ +

struct +archive *

+ + +

archive_read_disk_new(void);

+ +

int

+ + +

archive_read_disk_set_symlink_logical(struct archive *);

+ +

int

+ + +

archive_read_disk_set_symlink_physical(struct archive *);

+ +

int

+ + +

archive_read_disk_set_symlink_hybrid(struct archive *);

+ +

int

+ + +

archive_read_disk_gname(struct archive *, +gid_t);

+ +

int

+ + +

archive_read_disk_uname(struct archive *, +uid_t);

+ +

int

+ + +

archive_read_disk_set_gname_lookup(struct archive *, +void *, +const char *(*lookup)(void *, gid_t), +void (*cleanup)(void *));

+ +

int

+ + +

archive_read_disk_set_uname_lookup(struct archive *, +void *, +const char *(*lookup)(void *, uid_t), +void (*cleanup)(void *));

+ +

int

+ + +

archive_read_disk_set_standard_lookup(struct archive *);

+ +

int

+ + +

archive_read_disk_entry_from_file(struct archive *, +struct archive_entry *, int fd, +const struct stat *);

+ +

int

+ + +

archive_read_close(struct archive *);

+ +

int

+ + +

archive_read_finish(struct archive *);

+ + +

DESCRIPTION

+ +

These functions provide an API +for reading information about objects on disk. In +particular, they provide an interface for populating struct +archive_entry objects.

+ + +

archive_read_disk_new()

+ +

Allocates and initializes a +struct archive object suitable for reading object +information from disk.

+ + +

archive_read_disk_set_symlink_logical(), +archive_read_disk_set_symlink_physical(), +archive_read_disk_set_symlink_hybrid()

+ +

This sets the mode used for +handling symbolic links. The +‘‘logical’’ mode follows all +symbolic links. The ‘‘physical’’ +mode does not follow any symbolic links. The +‘‘hybrid’’ mode currently behaves +identically to the ‘‘logical’’ +mode.

+ + +

archive_read_disk_gname(), +archive_read_disk_uname()

+ +

Returns a user or group name +given a gid or uid value. By default, these always return a +NULL string.

+ + +

archive_read_disk_set_gname_lookup(), +archive_read_disk_set_uname_lookup()

+ +

These allow you to override the +functions used for user and group name lookups. You may also +provide a void * pointer to a private data structure and a +cleanup function for that data. The cleanup function will be +invoked when the struct archive object is destroyed or when +new lookup functions are registered.

+ + +

archive_read_disk_set_standard_lookup()

+ +

This convenience function +installs a standard set of user and group name lookup +functions. These functions use getpwid(3) and getgrid(3) to +convert ids to names, defaulting to NULL if the names cannot +be looked up. These functions also implement a simple memory +cache to reduce the number of calls to getpwid(3) and +getgrid(3).

+ + +

archive_read_disk_entry_from_file()

+ +

Populates a struct +archive_entry object with information about a particular +file. The archive_entry object must have already been +created with archive_entry_new(3) and at least one of the +source path or path fields must already be set. (If both are +set, the source path will be used.)

+ +

Information is +read from disk using the path name from the struct +archive_entry object. If a file descriptor is provided, some +information will be obtained using that file descriptor, on +platforms that support the appropriate system calls.

+ +

If a pointer to +a struct stat is provided, information from that structure +will be used instead of reading from the disk where +appropriate. This can provide performance benefits in +scenarios where struct stat information has already been +read from the disk as a side effect of some other operation. +(For example, directory traversal libraries often provide +this information.)

+ +

Where +necessary, user and group ids are converted to user and +group names using the currently registered lookup functions +above. This affects the file ownership fields and ACL values +in the struct archive_entry object.

+ + +

archive_read_close()

+ +

This currently does +nothing.

+ + +

archive_write_finish()

+ +

Invokes +archive_write_close() if it was not invoked manually, +then releases all resources.

+ +

More information about the +struct archive object and the overall design of the +library can be found in the libarchive(3) overview.

+ +

EXAMPLE

+ +

The following illustrates basic +usage of the library by showing how to use it to copy an +item on disk into an archive.

+ +

void
+file_to_archive(struct archive *a, const char *name)
+{
+char buff[8192];
+size_t bytes_read;
+struct archive *ard;
+struct archive_entry *entry;
+int fd;

+ +

ard = +archive_read_disk_new();
+archive_read_disk_set_standard_lookup(ard);
+entry = archive_entry_new();
+fd = open(name, O_RDONLY);
+if (fd < 0)
+return;
+archive_entry_copy_sourcepath(entry, name);
+archive_read_disk_entry_from_file(ard, entry, fd, NULL); +
+archive_write_header(a, entry);
+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_entry_free(entry);
+}

+ +

RETURN +VALUES

+ +

Most functions return +ARCHIVE_OK (zero) on success, or one of several +negative error codes for errors. Specific error codes +include: ARCHIVE_RETRY for operations that might +succeed if retried, ARCHIVE_WARN for unusual +conditions that do not prevent further operations, and +ARCHIVE_FATAL for serious errors that make remaining +operations impossible. The archive_errno(3) and +archive_error_string(3) functions can be used to retrieve an +appropriate error code and a textual error message. (See +archive_util(3) for details.)

+ + +

archive_read_disk_new() +returns a pointer to a newly-allocated struct archive object +or NULL if the allocation failed for any reason.

+ + +

archive_read_disk_gname() +and archive_read_disk_uname() return const char * +pointers to the textual name or NULL if the lookup failed +for any reason. The returned pointer points to internal +storage that may be reused on the next call to either of +these functions; callers should copy the string if they need +to continue accessing it.

+ +

SEE ALSO

+ +

archive_read(3), +archive_write(3), archive_write_disk(3), tar(1), +libarchive(3)

+ +

HISTORY

+ +

The libarchive library +first appeared in FreeBSD 5.3. The +archive_read_disk interface was added to +libarchive 2.6 and first appeared in +FreeBSD 8.0.

+ +

AUTHORS

+ +

The libarchive library +was written by Tim Kientzle +⟨kientzle@freebsd.org⟩.

+ +

BUGS

+ +

The +‘‘standard’’ user name and group +name lookup functions are not the defaults because +getgrid(3) and getpwid(3) are sometimes too large for +particular applications. The current design allows the +application author to use a more compact implementation when +appropriate.

+ +

The full list of +metadata read from disk by +archive_read_disk_entry_from_file() is necessarily +system-dependent.

+ +

The +archive_read_disk_entry_from_file() function reads as +much information as it can from disk. Some method should be +provided to limit this so that clients who do not need ACLs, +for instance, can avoid the extra work needed to look up +such information.

+ +

This API should +provide a set of methods for walking a directory tree. That +would make it a direct parallel of the archive_read(3) API. +When such methods are implemented, the +‘‘hybrid’’ symbolic link mode will +make sense.

+ + +

FreeBSD 8.0 +March 10, 2009 FreeBSD 8.0

+
+ + -- cgit v1.2.3