From a14fe904e2c63fefb99446980226a1bec4a95c5c Mon Sep 17 00:00:00 2001 From: Martin Matuska Date: Mon, 3 Apr 2017 13:37:24 +0200 Subject: [PATCH] Add manpage entry for archive_read_disk_set_behavior(). Update and alphabetically sort options in archive_write_disk_set_options(). --- libarchive/archive_read_disk.3 | 48 +++++++++++++++ libarchive/archive_write_disk.3 | 106 +++++++++++++++++++------------- 2 files changed, 112 insertions(+), 42 deletions(-) diff --git a/libarchive/archive_read_disk.3 b/libarchive/archive_read_disk.3 index 55e4bbbd8..e61cc5c12 100644 --- a/libarchive/archive_read_disk.3 +++ b/libarchive/archive_read_disk.3 @@ -29,6 +29,7 @@ .Os .Sh NAME .Nm archive_read_disk_new , +.Nm archive_read_disk_set_behavior , .Nm archive_read_disk_set_symlink_logical , .Nm archive_read_disk_set_symlink_physical , .Nm archive_read_disk_set_symlink_hybrid , @@ -46,6 +47,8 @@ Streaming Archive Library (libarchive, -larchive) .Ft struct archive * .Fn archive_read_disk_new "void" .Ft int +.Fn archive_read_disk_set_behavior "struct archive *" "int" +.Ft int .Fn archive_read_disk_set_symlink_logical "struct archive *" .Ft int .Fn archive_read_disk_set_symlink_physical "struct archive *" @@ -89,6 +92,51 @@ objects. Allocates and initializes a .Tn struct archive object suitable for reading object information from disk. +.It Fn archive_read_disk_set_behavior +Configures various behavior options when reading entries from disk. +The flags field consists of a bitwise OR of one or more of the +following values: +.Bl -tag -compact -width "indent" +.It Cm ARCHIVE_READDISK_HONOR_NODUMP +Skip files and directories with the nodump file attribute (file flag) set. +By default, the nodump file atrribute is ignored. +.It Cm ARCHIVE_READDISK_MAC_COPYFILE +Mac OS X specific. Read metadata (ACLs and extended attributes) with +.Xr copyfile 3 . +By default, metadata is read using +.Xr copyfile 3 . +.It Cm ARCHIVE_READDISK_NO_ACL +Do not read Access Control Lists. +By default, ACLs are read from disk. +.It Cm ARCHIVE_READDISK_NO_FFLAGS +Do not read file attributes (file flags). +By default, file attributes are read from disk. +See +.Xr chattr 1 +.Pq Linux +or +.Xr chflags 1 +.Pq FreeBSD, Mac OS X +for more information on file attributes. +.It Cm ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS +Do not traverse mount points. +By defaut, moint points are traversed. +.It Cm ARCHIVE_READDISK_NO_XATTR +Do not read extended file attributes (xattrs). +By default, extended file attributes are read from disk. +See +.Xr xattr 7 +.Pq Linux , +.Xr xattr 2 +.Pq Mac OS X , +or +.Xr getextattr 8 +.Pq FreeBSD +for more information on extended file attributes. +.It Cm ARCHIVE_READDISK_RESTORE_ATIME +Restore access time of traversed files. +By default, access time of traversed files is not restored. +.El .It Xo .Fn archive_read_disk_set_symlink_logical , .Fn archive_read_disk_set_symlink_physical , diff --git a/libarchive/archive_write_disk.3 b/libarchive/archive_write_disk.3 index 4891b8572..3e33a08fd 100644 --- a/libarchive/archive_write_disk.3 +++ b/libarchive/archive_write_disk.3 @@ -96,6 +96,33 @@ performance optimization in practice. The options field consists of a bitwise OR of one or more of the following values: .Bl -tag -compact -width "indent" +.It Cm ARCHIVE_EXTRACT_ACL +Attempt to restore Access Control Lists. +By default, extended ACLs are ignored. +.It Cm ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS +Before removing a file system object prior to replacing it, clear +platform-specific file flags which might prevent its removal. +.It Cm ARCHIVE_EXTRACT_FFLAGS +Attempt to restore file attributes (file flags). +By default, file attributes are ignored. +See +.Xr chattr 1 +.Pq Linux +or +.Xr chflags 1 +.Pq FreeBSD, Mac OS X +for more information on file attributes. +.It Cm ARCHIVE_EXTRACT_MAC_METADATA +Mac OS X specific. Restore metadata using +.Xr copyfile 3 . +By default, +.Xr copyfile 3 +metadata is ignored. +.It Cm ARCHIVE_EXTRACT_NO_OVERWRITE +Existing files on disk will not be overwritten. +By default, existing regular files are truncated and overwritten; +existing directories will have their permissions updated; +other pre-existing objects are unlinked and recreated from scratch. .It Cm ARCHIVE_EXTRACT_OWNER The user and group IDs should be set on the restored file. By default, the user and group IDs are not restored. @@ -111,15 +138,37 @@ is not specified, then SUID and SGID bits will only be restored if the default user and group IDs of newly-created objects on disk happen to match those specified in the archive entry. By default, only basic permissions are restored, and umask is obeyed. +.It Cm ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS +Refuse to extract an absolute path. +The default is to not refuse such paths. +.It Cm ARCHIVE_EXTRACT_SECURE_NODOTDOT +Refuse to extract a path that contains a +.Pa .. +element anywhere within it. +The default is to not refuse such paths. +Note that paths ending in +.Pa .. +always cause an error, regardless of this flag. +.It Cm ARCHIVE_EXTRACT_SECURE_SYMLINKS +Refuse to extract any object whose final location would be altered +by a symlink on disk. +This is intended to help guard against a variety of mischief +caused by archives that (deliberately or otherwise) extract +files outside of the current directory. +The default is not to perform this check. +If +.It Cm ARCHIVE_EXTRACT_SPARSE +Scan data for blocks of NUL bytes and try to recreate them with holes. +This results in sparse files, independent of whether the archive format +supports or uses them. +.Cm ARCHIVE_EXTRACT_UNLINK +is specified together with this option, the library will +remove any intermediate symlinks it finds and return an +error only if such symlink could not be removed. .It Cm ARCHIVE_EXTRACT_TIME The timestamps (mtime, ctime, and atime) should be restored. By default, they are ignored. Note that restoring of atime is not currently supported. -.It Cm ARCHIVE_EXTRACT_NO_OVERWRITE -Existing files on disk will not be overwritten. -By default, existing regular files are truncated and overwritten; -existing directories will have their permissions updated; -other pre-existing objects are unlinked and recreated from scratch. .It Cm ARCHIVE_EXTRACT_UNLINK Existing files on disk will be unlinked before any attempt to create them. @@ -127,45 +176,18 @@ In some cases, this can prove to be a significant performance improvement. By default, existing files are truncated and rewritten, but the file is not recreated. In particular, the default behavior does not break existing hard links. -.It Cm ARCHIVE_EXTRACT_ACL -Attempt to restore ACLs. -By default, extended ACLs are ignored. -.It Cm ARCHIVE_EXTRACT_FFLAGS -Attempt to restore extended file flags. -By default, file flags are ignored. .It Cm ARCHIVE_EXTRACT_XATTR -Attempt to restore POSIX.1e extended attributes. +Attempt to restore extended file attributes. By default, they are ignored. -.It Cm ARCHIVE_EXTRACT_SECURE_SYMLINKS -Refuse to extract any object whose final location would be altered -by a symlink on disk. -This is intended to help guard against a variety of mischief -caused by archives that (deliberately or otherwise) extract -files outside of the current directory. -The default is not to perform this check. -If -.Cm ARCHIVE_EXTRACT_UNLINK -is specified together with this option, the library will -remove any intermediate symlinks it finds and return an -error only if such symlink could not be removed. -.It Cm ARCHIVE_EXTRACT_SECURE_NODOTDOT -Refuse to extract a path that contains a -.Pa .. -element anywhere within it. -The default is to not refuse such paths. -Note that paths ending in -.Pa .. -always cause an error, regardless of this flag. -.It Cm ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS -Refuse to extract an absolute path. -The default is to not refuse such paths. -.It Cm ARCHIVE_EXTRACT_SPARSE -Scan data for blocks of NUL bytes and try to recreate them with holes. -This results in sparse files, independent of whether the archive format -supports or uses them. -.It Cm ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS -Before removing a file system object prior to replacing it, clear -platform-specific file flags which might prevent its removal. +See +.Xr xattr 7 +.Pq Linux , +.Xr xattr 2 +.Pq Mac OS X , +or +.Xr getextattr 8 +.Pq FreeBSD +for more information on extended file attributes. .El .It Xo .Fn archive_write_disk_set_group_lookup , -- 2.47.2