From: Alexander Ziaee Date: Fri, 6 Dec 2024 15:50:06 +0000 (-0500) Subject: bsdtar.1: Mention rar support + manual page polish (#2423) X-Git-Tag: v3.8.0~119 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=68238f28ee9e051be0c78f91f99b1ad2a4c74a03;p=thirdparty%2Flibarchive.git bsdtar.1: Mention rar support + manual page polish (#2423) I have been using this for years without realizing it decompresses rar. + add rar to supported decompression formats + use section references to link sections (this makes them clickable in GUIs) + add paragraph breaks for consistent spacing + pdtar is not this program, so use Sy per mdoc style guide + do almost the same in reverse for bsdtar + remove parenthetical around a complete sentance Thank you so much, this is wonderful software. --- diff --git a/tar/bsdtar.1 b/tar/bsdtar.1 index 7a7b0d5d9..c44c57cca 100644 --- a/tar/bsdtar.1 +++ b/tar/bsdtar.1 @@ -32,19 +32,22 @@ .Nm creates and manipulates streaming archive files. This implementation can extract from tar, pax, cpio, zip, jar, ar, xar, -rpm, 7-zip, and ISO 9660 cdrom images and can create tar, pax, cpio, ar, zip, -7-zip, and shar archives. +rar, rpm, 7-zip, and ISO 9660 cdrom images and can create tar, pax, +cpio, ar, zip, 7-zip, and shar archives. .Pp The first synopsis form shows a .Dq bundled option word. This usage is provided for compatibility with historical implementations. -See COMPATIBILITY below for details. +See +.Sx COMPATIBILITY +below for details. .Pp The other synopsis forms show the preferred usage. The first option to .Nm is a mode indicator from the following list: +.Pp .Bl -tag -compact -width indent .It Fl c Create a new archive containing the specified items. @@ -109,16 +112,22 @@ all operating modes. The specified archive is opened and the entries in it will be appended to the current archive. As a simple example, +.Pp .Dl Nm Fl c Fl f Pa - Pa newfile Cm @ Ns Pa original.tar +.Pp writes a new archive to standard output containing a file .Pa newfile and all of the entries from .Pa original.tar . In contrast, +.Pp .Dl Nm Fl c Fl f Pa - Pa newfile Pa original.tar +.Pp creates a new archive with only two entries. Similarly, +.Pp .Dl Nm Fl czf Pa - Fl Fl format Cm pax Cm @ Ns Pa - +.Pp reads an archive from standard input (whose format will be determined automatically) and converts it into a gzip-compressed pax-format archive on stdout. @@ -130,19 +139,29 @@ can be used to convert archives from one format to another. Use the archive suffix to decide a set of the format and the compressions. As a simple example, +.Pp .Dl Nm Fl a Fl cf Pa archive.tgz source.c source.h +.Pp creates a new archive with restricted pax format and gzip compression, +.Pp .Dl Nm Fl a Fl cf Pa archive.tar.bz2.uu source.c source.h +.Pp creates a new archive with restricted pax format and bzip2 compression and uuencode compression, +.Pp .Dl Nm Fl a Fl cf Pa archive.zip source.c source.h +.Pp creates a new archive with zip format, +.Pp .Dl Nm Fl a Fl jcf Pa archive.tgz source.c source.h +.Pp ignores the .Dq -j option, and creates a new archive with restricted pax format and gzip compression, +.Pp .Dl Nm Fl a Fl jcf Pa archive.xxx source.c source.h +.Pp if it is unknown suffix or no suffix, creates a new archive with restricted pax format and bzip2 compression. .It Fl Fl acls @@ -295,7 +314,9 @@ The .Fl Fl include option is especially useful when filtering archives. For example, the command +.Pp .Dl Nm Fl c Fl f Pa new.tar Fl Fl include='*foo*' Cm @ Ns Pa old.tgz +.Pp creates a new archive .Pa new.tar containing only the entries from @@ -393,7 +414,8 @@ and the default behavior in c, r, and u modes or if .Nm is run in x mode as root. Currently supported only for pax formats -(including "pax restricted", the default tar format for bsdtar.) +.Po including "pax restricted", the default tar format for +.Nm bsdtar Pc .It Fl n , Fl Fl norecurse , Fl Fl no-recursion Do not operate recursively on the content of directories. .It Fl Fl newer Ar date @@ -556,6 +578,7 @@ keywords and values. These are passed to the modules that handle particular formats to control how those formats will behave. Each option has one of the following forms: +.Pp .Bl -tag -compact -width indent .It Ar key=value The key will be set to the specified value in every module that supports it. @@ -579,6 +602,7 @@ and for extract and list modes in .Xr archive_read_set_options 3 . .Pp Examples of supported options: +.Pp .Bl -tag -compact -width indent .It Cm iso9660:joliet Support Joliet extensions. @@ -738,6 +762,7 @@ This option is comparable to the .Fl i , Fl Fl ignore-zeros option of GNU tar. .El +.Pp If a provided option is not supported by any module, that is a fatal error. .It Fl P , Fl Fl absolute-paths @@ -910,7 +935,9 @@ This flag also causes .Nm to remove intervening directory symlinks instead of reporting an error. -See the SECURITY section below for more details. +See the +.Sx SECURITY +section below for more details. .It Fl Fl uid Ar id Use the provided user id number and ignore the user name from the archive. @@ -1048,24 +1075,31 @@ that contains two files .Ar source.c and .Ar source.h : +.Pp .Dl Nm Fl czf Pa file.tar.gz Pa source.c Pa source.h .Pp To view a detailed table of contents for this archive: +.Pp .Dl Nm Fl tvf Pa file.tar.gz .Pp To extract all entries from the archive on the default tape drive: +.Pp .Dl Nm Fl x .Pp To examine the contents of an ISO 9660 cdrom image: +.Pp .Dl Nm Fl tf Pa image.iso .Pp To move file hierarchies, invoke .Nm as +.Pp .Dl Nm Fl cf Pa - Fl C Pa srcdir \&. | Nm Fl xpf Pa - Fl C Pa destdir +.Pp or more traditionally +.Pp .Dl cd srcdir \&; Nm Fl cf Pa - \&. | ( cd destdir \&; Nm Fl xpf Pa - ) .Pp In create mode, the list of files and directories to be archived @@ -1074,7 +1108,9 @@ can also include directory change instructions of the form and archive inclusions of the form .Cm @ Ns Pa archive-file . For example, the command line +.Pp .Dl Nm Fl c Fl f Pa new.tar Pa foo1 Cm @ Ns Pa old.tgz Cm -C Ns Pa /tmp Pa foo2 +.Pp will create a new archive .Pa new.tar . .Nm @@ -1122,9 +1158,13 @@ For example, you can generate mtree output which only contains and .Cm uid keywords: +.Pp .Dl Nm Fl cf Pa file.tar Fl Fl format=mtree Fl Fl options='!all,type,time,uid' Pa dir +.Pp or you can set the compression level used by gzip or xz compression: +.Pp .Dl Nm Fl czf Pa file.tar Fl Fl options='compression-level=9' . +.Pp For more details, see the explanation of the .Fn archive_read_set_options and @@ -1142,7 +1182,9 @@ Arguments follow as separate words. The order of the arguments must match the order of the corresponding characters in the bundled command word. For example, +.Pp .Dl Nm Cm tbf 32 Pa file.tar +.Pp specifies three flags .Cm t , .Cm b , @@ -1240,10 +1282,13 @@ is specified, .Nm will refuse to extract the entry. .El +.Pp To protect yourself, you should be wary of any archives that come from untrusted sources. You should examine the contents of an archive with +.Pp .Dl Nm Fl tf Pa filename +.Pp before extraction. You should use the .Fl k @@ -1294,7 +1339,7 @@ command appeared in Seventh Edition Unix, which was released in January, 1979. There have been numerous other implementations, many of which extended the file format. John Gilmore's -.Nm pdtar +.Sy pdtar public-domain implementation (circa November, 1987) was quite influential, and formed the basis of GNU tar. GNU tar was included as the standard system tar @@ -1347,8 +1392,11 @@ although they still extract it correctly. The compression and decompression is implemented internally, so there may be insignificant differences between the compressed output generated by +.Pp .Dl Nm Fl czf Pa - file +.Pp and that generated by +.Pp .Dl Nm Fl cf Pa - file | Nm gzip .Pp The default should be to read and write archives to the standard I/O paths, @@ -1393,5 +1441,5 @@ There is not yet any support for multi-volume archives. Converting between dissimilar archive formats (such as tar and cpio) using the .Cm @ Ns Pa - convention can cause hard link information to be lost. -(This is a consequence of the incompatible ways that different archive -formats store hardlink information.) +This is a consequence of the incompatible ways that different archive +formats store hardlink information.