summaryrefslogtreecommitdiff
path: root/libarchive/libarchive-2.8.0/doc/text/archive_read_disk.3.txt
diff options
context:
space:
mode:
authorTomas Bzatek <tbzatek@redhat.com>2023-12-17 16:55:58 +0100
committerTomas Bzatek <tbzatek@redhat.com>2023-12-17 16:55:58 +0100
commitb22a4476a66a913a07d5e80334c0400a9b162206 (patch)
treed896eb5f6f9212b5ef424219c45571ce5f152cc0 /libarchive/libarchive-2.8.0/doc/text/archive_read_disk.3.txt
parent7592788feb1a8cb79b85e6a9911a206a5d55896d (diff)
downloadtuxcmd-modules-b22a4476a66a913a07d5e80334c0400a9b162206.tar.xz
libarchive: Remove in-tree libarchive package
Libarchive has become a standard package in most distributions, no need to carry the sources along here.
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/text/archive_read_disk.3.txt')
-rw-r--r--libarchive/libarchive-2.8.0/doc/text/archive_read_disk.3.txt204
1 files changed, 0 insertions, 204 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/text/archive_read_disk.3.txt b/libarchive/libarchive-2.8.0/doc/text/archive_read_disk.3.txt
deleted file mode 100644
index 0522bf4..0000000
--- a/libarchive/libarchive-2.8.0/doc/text/archive_read_disk.3.txt
+++ /dev/null
@@ -1,204 +0,0 @@
-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 sim-
- ple 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 plat-
- forms 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, direc-
- tory 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 impossi-
- ble. 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 rea-
- son. 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 informa-
- tion 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