diff options
Diffstat (limited to 'usr.bin/tar/bsdtar.1')
-rw-r--r-- | usr.bin/tar/bsdtar.1 | 1029 |
1 files changed, 0 insertions, 1029 deletions
diff --git a/usr.bin/tar/bsdtar.1 b/usr.bin/tar/bsdtar.1 deleted file mode 100644 index 14c77e9..0000000 --- a/usr.bin/tar/bsdtar.1 +++ /dev/null @@ -1,1029 +0,0 @@ -.\" Copyright (c) 2003-2007 Tim Kientzle -.\" All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" $FreeBSD$ -.\" -.Dd Oct 12, 2009 -.Dt BSDTAR 1 -.Os -.Sh NAME -.Nm tar -.Nd manipulate tape archives -.Sh SYNOPSIS -.Nm -.Op Ar bundled-flags Ao args Ac -.Op Ao Ar file Ac | Ao Ar pattern Ac ... -.Nm -.Brq Fl c -.Op Ar options -.Op Ar files | Ar directories -.Nm -.Brq Fl r | Fl u -.Fl f Ar archive-file -.Op Ar options -.Op Ar files | Ar directories -.Nm -.Brq Fl t | Fl x -.Op Ar options -.Op Ar patterns -.Sh DESCRIPTION -.Nm -creates and manipulates streaming archive files. -This implementation can extract from tar, pax, cpio, zip, jar, ar, xar, -rpm and ISO 9660 cdrom images and can create tar, pax, cpio, ar, 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. -.Pp -The other synopsis forms show the preferred usage. -The first option to -.Nm -is a mode indicator from the following list: -.Bl -tag -compact -width indent -.It Fl c -Create a new archive containing the specified items. -The long option form is -.Fl Fl create . -.It Fl r -Like -.Fl c , -but new entries are appended to the archive. -Note that this only works on uncompressed archives stored in regular files. -The -.Fl f -option is required. -The long option form is -.Fl Fl append . -.It Fl t -List archive contents to stdout. -The long option form is -.Fl Fl list . -.It Fl u -Like -.Fl r , -but new entries are added only if they have a modification date -newer than the corresponding entry in the archive. -Note that this only works on uncompressed archives stored in regular files. -The -.Fl f -option is required. -The long form is -.Fl Fl update . -.It Fl x -Extract to disk from the archive. -If a file with the same name appears more than once in the archive, -each copy will be extracted, with later copies overwriting (replacing) -earlier copies. -The long option form is -.Fl Fl extract . -.El -.Pp -In -.Fl c , -.Fl r , -or -.Fl u -mode, each specified file or directory is added to the -archive in the order specified on the command line. -By default, the contents of each directory are also archived. -.Pp -In extract or list mode, the entire command line -is read and parsed before the archive is opened. -The pathnames or patterns on the command line indicate -which items in the archive should be processed. -Patterns are shell-style globbing patterns as -documented in -.Xr tcsh 1 . -.Sh OPTIONS -Unless specifically stated otherwise, options are applicable in -all operating modes. -.Bl -tag -width indent -.It Cm @ Ns Pa archive -(c and r mode only) -The specified archive is opened and the entries -in it will be appended to the current archive. -As a simple example, -.Dl Nm Fl c Fl f Pa - Pa newfile Cm @ Ns Pa original.tar -writes a new archive to standard output containing a file -.Pa newfile -and all of the entries from -.Pa original.tar . -In contrast, -.Dl Nm Fl c Fl f Pa - Pa newfile Pa original.tar -creates a new archive with only two entries. -Similarly, -.Dl Nm Fl czf Pa - Fl Fl format Cm pax Cm @ Ns Pa - -reads an archive from standard input (whose format will be determined -automatically) and converts it into a gzip-compressed -pax-format archive on stdout. -In this way, -.Nm -can be used to convert archives from one format to another. -.It Fl B , Fl Fl read-full-blocks -Ignored for compatibility with other -.Xr tar 1 -implementations. -.It Fl b Ar blocksize , Fl Fl block-size Ar blocksize -Specify the block size, in 512-byte records, for tape drive I/O. -As a rule, this argument is only needed when reading from or writing -to tape drives, and usually not even then as the default block size of -20 records (10240 bytes) is very common. -.It Fl C Ar directory -In c and r mode, this changes the directory before adding -the following files. -In x mode, change directories after opening the archive -but before extracting entries from the archive. -.It Fl Fl chroot -(x mode only) -.Fn chroot -to the current directory after processing any -.Fl C -options and before extracting any files. -.It Fl Fl disable-copyfile -Mac OS X specific. -Disable the use of -.Xr copyfile 3 . -.It Fl Fl exclude Ar pattern -Do not process files or directories that match the -specified pattern. -Note that exclusions take precedence over patterns or filenames -specified on the command line. -.It Fl Fl format Ar format -(c, r, u mode only) -Use the specified format for the created archive. -Supported formats include -.Dq cpio , -.Dq pax , -.Dq shar , -and -.Dq ustar . -Other formats may also be supported; see -.Xr libarchive-formats 5 -for more information about currently-supported formats. -In r and u modes, when extending an existing archive, the format specified -here must be compatible with the format of the existing archive on disk. -.It Fl f Ar file , Fl Fl file Ar file -Read the archive from or write the archive to the specified file. -The filename can be -.Pa - -for standard input or standard output. -The default varies by system; -on -.Fx , -the default is -.Pa /dev/sa0 ; -on Linux, the default is -.Pa /dev/st0 . -.It Fl Fl gid Ar id -Use the provided group id number. -On extract, this overrides the group id in the archive; -the group name in the archive will be ignored. -On create, this overrides the group id read from disk; -if -.Fl Fl gname -is not also specified, the group name will be set to -match the group id. -.It Fl Fl gname Ar name -Use the provided group name. -On extract, this overrides the group name in the archive; -if the provided group name does not exist on the system, -the group id -(from the archive or from the -.Fl Fl gid -option) -will be used instead. -On create, this sets the group name that will be stored -in the archive; -the name will not be verified against the system group database. -.It Fl H -(c and r mode only) -Symbolic links named on the command line will be followed; the -target of the link will be archived, not the link itself. -.It Fl h -(c and r mode only) -Synonym for -.Fl L . -.It Fl I -Synonym for -.Fl T . -.It Fl Fl help -Show usage. -.It Fl Fl include Ar pattern -Process only files or directories that match the specified pattern. -Note that exclusions specified with -.Fl Fl exclude -take precedence over inclusions. -If no inclusions are explicitly specified, all entries are processed by -default. -The -.Fl Fl include -option is especially useful when filtering archives. -For example, the command -.Dl Nm Fl c Fl f Pa new.tar Fl Fl include='*foo*' Cm @ Ns Pa old.tgz -creates a new archive -.Pa new.tar -containing only the entries from -.Pa old.tgz -containing the string -.Sq foo . -.It Fl J , Fl Fl xz -(c mode only) -Compress the resulting archive with -.Xr xz 1 . -In extract or list modes, this option is ignored. -Note that, unlike other -.Nm tar -implementations, this implementation recognizes XZ compression -automatically when reading archives. -.It Fl j , Fl Fl bzip , Fl Fl bzip2 , Fl Fl bunzip2 -(c mode only) -Compress the resulting archive with -.Xr bzip2 1 . -In extract or list modes, this option is ignored. -Note that, unlike other -.Nm tar -implementations, this implementation recognizes bzip2 compression -automatically when reading archives. -.It Fl k , Fl Fl keep-old-files -(x mode only) -Do not overwrite existing files. -In particular, if a file appears more than once in an archive, -later copies will not overwrite earlier copies. -.It Fl Fl keep-newer-files -(x mode only) -Do not overwrite existing files that are newer than the -versions appearing in the archive being extracted. -.It Fl L , Fl Fl dereference -(c and r mode only) -All symbolic links will be followed. -Normally, symbolic links are archived as such. -With this option, the target of the link will be archived instead. -.It Fl l , Fl Fl check-links -(c and r modes only) -Issue a warning message unless all links to each file are archived. -.It Fl Fl lzma -(c mode only) Compress the resulting archive with the original LZMA algorithm. -Use of this option is discouraged and new archives should be created with -.Fl Fl xz -instead. -Note that, unlike other -.Nm tar -implementations, this implementation recognizes LZMA compression -automatically when reading archives. -.It Fl m , Fl Fl modification-time -(x mode only) -Do not extract modification time. -By default, the modification time is set to the time stored in the archive. -.It Fl n , Fl Fl norecurse , Fl Fl no-recursion -(c, r, u modes only) -Do not recursively archive the contents of directories. -.It Fl Fl newer Ar date -(c, r, u modes only) -Only include files and directories newer than the specified date. -This compares ctime entries. -.It Fl Fl newer-mtime Ar date -(c, r, u modes only) -Like -.Fl Fl newer , -except it compares mtime entries instead of ctime entries. -.It Fl Fl newer-than Pa file -(c, r, u modes only) -Only include files and directories newer than the specified file. -This compares ctime entries. -.It Fl Fl newer-mtime-than Pa file -(c, r, u modes only) -Like -.Fl Fl newer-than , -except it compares mtime entries instead of ctime entries. -.It Fl Fl nodump -(c and r modes only) -Honor the nodump file flag by skipping this file. -.It Fl Fl null -(use with -.Fl I -or -.Fl T ) -Filenames or patterns are separated by null characters, -not by newlines. -This is often used to read filenames output by the -.Fl print0 -option to -.Xr find 1 . -.It Fl Fl no-same-owner -(x mode only) -Do not extract owner and group IDs. -This is the reverse of -.Fl Fl same-owner -and the default behavior if -.Nm -is run as non-root. -.It Fl Fl no-same-permissions -(x mode only) -Do not extract full permissions (SGID, SUID, sticky bit, ACLs, -extended attributes or extended file flags). -This is the reverse of -.Fl p -and the default behavior if -.Nm -is run as non-root. -.It Fl Fl numeric-owner -This is equivalent to -.Fl Fl uname -.Qq -.Fl Fl gname -.Qq . -On extract, it causes user and group names in the archive -to be ignored in favor of the numeric user and group ids. -On create, it causes user and group names to not be stored -in the archive. -.It Fl O , Fl Fl to-stdout -(x, t modes only) -In extract (-x) mode, files will be written to standard out rather than -being extracted to disk. -In list (-t) mode, the file listing will be written to stderr rather than -the usual stdout. -.It Fl o -(x mode) -Use the user and group of the user running the program rather -than those specified in the archive. -Note that this has no significance unless -.Fl p -is specified, and the program is being run by the root user. -In this case, the file modes and flags from -the archive will be restored, but ACLs or owner information in -the archive will be discarded. -.It Fl o -(c, r, u mode) -A synonym for -.Fl Fl format Ar ustar -.It Fl Fl one-file-system -(c, r, and u modes) -Do not cross mount points. -.It Fl Fl options Ar options -Select optional behaviors for particular modules. -The argument is a text string containing comma-separated -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: -.Bl -tag -compact -width indent -.It Ar key=value -The key will be set to the specified value in every module that supports it. -Modules that do not support this key will ignore it. -.It Ar key -The key will be enabled in every module that supports it. -This is equivalent to -.Ar key Ns Cm =1 . -.It Ar !key -The key will be disabled in every module that supports it. -.It Ar module:key=value , Ar module:key , Ar module:!key -As above, but the corresponding key and value will be provided -only to modules whose name matches -.Ar module . -.El -The currently supported modules and keys are: -.Bl -tag -compact -width indent -.It Cm iso9660:joliet -Support Joliet extensions. -This is enabled by default, use -.Cm !joliet -or -.Cm iso9660:!joliet -to disable. -.It Cm iso9660:rockridge -Support Rock Ridge extensions. -This is enabled by default, use -.Cm !rockridge -or -.Cm iso9660:!rockridge -to disable. -.It Cm gzip:compression-level -A decimal integer from 0 to 9 specifying the gzip compression level. -.It Cm xz:compression-level -A decimal integer from 0 to 9 specifying the xz compression level. -.It Cm mtree: Ns Ar keyword -The mtree writer module allows you to specify which mtree keywords -will be included in the output. -Supported keywords include: -.Cm cksum , Cm device , Cm flags , Cm gid , Cm gname , Cm indent , -.Cm link , Cm md5 , Cm mode , Cm nlink , Cm rmd160 , Cm sha1 , Cm sha256 , -.Cm sha384 , Cm sha512 , Cm size , Cm time , Cm uid , Cm uname . -The default is equivalent to: -.Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname . -.It Cm mtree:all -Enables all of the above keywords. -You can also use -.Cm mtree:!all -to disable all keywords. -.It Cm mtree:use-set -Enable generation of -.Cm /set -lines in the output. -.It Cm mtree:indent -Produce human-readable output by indenting options and splitting lines -to fit into 80 columns. -.It Cm zip:compression Ns = Ns Ar type -Use -.Ar type -as compression method. -Supported values are store (uncompressed) and deflate (gzip algorithm). -.El -If a provided option is not supported by any module, that -is a fatal error. -.It Fl P , Fl Fl absolute-paths -Preserve pathnames. -By default, absolute pathnames (those that begin with a / -character) have the leading slash removed both when creating archives -and extracting from them. -Also, -.Nm -will refuse to extract archive entries whose pathnames contain -.Pa .. -or whose target directory would be altered by a symlink. -This option suppresses these behaviors. -.It Fl p , Fl Fl insecure , Fl Fl preserve-permissions -(x mode only) -Preserve file permissions. -Attempt to restore the full permissions, including owner, file modes, file -flags and ACLs, if available, for each item extracted from the archive. -This is the default, if -.Nm -is being run by root and can be overriden by also specifying -.Fl Fl no-same-owner -and -.Fl Fl no-same-permissions . -.It Fl Fl posix -(c, r, u mode only) -Synonym for -.Fl Fl format Ar pax -.It Fl q , Fl Fl fast-read -(x and t mode only) -Extract or list only the first archive entry that matches each pattern -or filename operand. -Exit as soon as each specified pattern or filename has been matched. -By default, the archive is always read to the very end, since -there can be multiple entries with the same name and, by convention, -later entries overwrite earlier entries. -This option is provided as a performance optimization. -.It Fl S -(x mode only) -Extract files as sparse files. -For every block on disk, check first if it contains only NULL bytes and seek -over it otherwise. -This works similar to the conv=sparse option of dd. -.It Fl Fl same-owner -(x mode only) -Extract owner and group IDs. -This is the reverse of -.Fl Fl no-same-owner -and the default behavior if -.Nm -is run as root. -.It Fl Fl strip-components Ar count -(x mode only) -Remove the specified number of leading path elements. -Pathnames with fewer elements will be silently skipped. -Note that the pathname is edited after checking inclusion/exclusion patterns -but before security checks. -.It Fl s Ar pattern -Modify file or archive member names according to -.Pa pattern . -The pattern has the format -.Ar /old/new/ Ns Op gps -where -.Ar old -is a basic regular expression, -.Ar new -is the replacement string of the matched part, -and the optional trailing letters modify -how the replacement is handled. -If -.Ar old -is not matched, the pattern is skipped. -Within -.Ar new , -~ is substituted with the match, \e1 to \e9 with the content of -the corresponding captured group. -The optional trailing g specifies that matching should continue -after the matched part and stopped on the first unmatched pattern. -The optional trailing s specifies that the pattern applies to the value -of symbolic links. -The optional trailing p specifies that after a successful substitution -the original path name and the new path name should be printed to -standard error. -.It Fl T Ar filename , Fl Fl files-from Ar filename -In x or t mode, -.Nm -will read the list of names to be extracted from -.Pa filename . -In c mode, -.Nm -will read names to be archived from -.Pa filename . -The special name -.Dq -C -on a line by itself will cause the current directory to be changed to -the directory specified on the following line. -Names are terminated by newlines unless -.Fl Fl null -is specified. -Note that -.Fl Fl null -also disables the special handling of lines containing -.Dq -C . -.It Fl Fl totals -(c, r, u mode only) -After archiving all files, print a summary to stderr. -.It Fl U , Fl Fl unlink , Fl Fl unlink-first -(x mode only) -Unlink files before creating them. -This can be a minor performance optimization if most files -already exist, but can make things slower if most files -do not already exist. -This flag also causes -.Nm -to remove intervening directory symlinks instead of -reporting an error. -See the 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. -On create, if -.Fl Fl uname -is not also specified, the user name will be set to -match the user id. -.It Fl Fl uname Ar name -Use the provided user name. -On extract, this overrides the user name in the archive; -if the provided user name does not exist on the system, -it will be ignored and the user id -(from the archive or from the -.Fl Fl uid -option) -will be used instead. -On create, this sets the user name that will be stored -in the archive; -the name is not verified against the system user database. -.It Fl Fl use-compress-program Ar program -Pipe the input (in x or t mode) or the output (in c mode) through -.Pa program -instead of using the builtin compression support. -.It Fl v , Fl Fl verbose -Produce verbose output. -In create and extract modes, -.Nm -will list each file name as it is read from or written to -the archive. -In list mode, -.Nm -will produce output similar to that of -.Xr ls 1 . -Additional -.Fl v -options will provide additional detail. -.It Fl Fl version -Print version of -.Nm -and -.Nm libarchive , -and exit. -.It Fl w , Fl Fl confirmation , Fl Fl interactive -Ask for confirmation for every action. -.It Fl X Ar filename , Fl Fl exclude-from Ar filename -Read a list of exclusion patterns from the specified file. -See -.Fl Fl exclude -for more information about the handling of exclusions. -.It Fl y -(c mode only) -Compress the resulting archive with -.Xr bzip2 1 . -In extract or list modes, this option is ignored. -Note that, unlike other -.Nm tar -implementations, this implementation recognizes bzip2 compression -automatically when reading archives. -.It Fl Z , Fl Fl compress , Fl Fl uncompress -(c mode only) -Compress the resulting archive with -.Xr compress 1 . -In extract or list modes, this option is ignored. -Note that, unlike other -.Nm tar -implementations, this implementation recognizes compress compression -automatically when reading archives. -.It Fl z , Fl Fl gunzip , Fl Fl gzip -(c mode only) -Compress the resulting archive with -.Xr gzip 1 . -In extract or list modes, this option is ignored. -Note that, unlike other -.Nm tar -implementations, this implementation recognizes gzip compression -automatically when reading archives. -.El -.Sh ENVIRONMENT -The following environment variables affect the execution of -.Nm : -.Bl -tag -width ".Ev BLOCKSIZE" -.It Ev LANG -The locale to use. -See -.Xr environ 7 -for more information. -.It Ev TAPE -The default device. -The -.Fl f -option overrides this. -Please see the description of the -.Fl f -option above for more details. -.It Ev TZ -The timezone to use when displaying dates. -See -.Xr environ 7 -for more information. -.El -.Sh EXIT STATUS -.Ex -std -.Sh EXAMPLES -The following creates a new archive -called -.Ar file.tar.gz -that contains two files -.Ar source.c -and -.Ar source.h : -.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: -.Dl Nm Fl tvf Pa file.tar.gz -.Pp -To extract all entries from the archive on -the default tape drive: -.Dl Nm Fl x -.Pp -To examine the contents of an ISO 9660 cdrom image: -.Dl Nm Fl tf Pa image.iso -.Pp -To move file hierarchies, invoke -.Nm -as -.Dl Nm Fl cf Pa - Fl C Pa srcdir\ . | Nm Fl xpf Pa - Fl C Pa destdir -or more traditionally -.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 -can also include directory change instructions of the form -.Cm -C Ns Pa foo/baz -and archive inclusions of the form -.Cm @ Ns Pa archive-file . -For example, the command line -.Dl Nm Fl c Fl f Pa new.tar Pa foo1 Cm @ Ns Pa old.tgz Cm -C Ns Pa /tmp Pa foo2 -will create a new archive -.Pa new.tar . -.Nm -will read the file -.Pa foo1 -from the current directory and add it to the output archive. -It will then read each entry from -.Pa old.tgz -and add those entries to the output archive. -Finally, it will switch to the -.Pa /tmp -directory and add -.Pa foo2 -to the output archive. -.Pp -An input file in -.Xr mtree 5 -format can be used to create an output archive with arbitrary ownership, -permissions, or names that differ from existing data on disk: -.Pp -.Dl $ cat input.mtree -.Dl #mtree -.Dl usr/bin uid=0 gid=0 mode=0755 type=dir -.Dl usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls -.Dl $ tar -cvf output.tar @input.mtree -.Pp -The -.Fl Fl newer -and -.Fl Fl newer-mtime -switches accept a variety of common date and time specifications, including -.Dq 12 Mar 2005 7:14:29pm , -.Dq 2005-03-12 19:14 , -.Dq 5 minutes ago , -and -.Dq 19:14 PST May 1 . -.Pp -The -.Fl Fl options -argument can be used to control various details of archive generation -or reading. -For example, you can generate mtree output which only contains -.Cm type , Cm time , -and -.Cm uid -keywords: -.Dl Nm Fl cf Pa file.tar Fl Fl format=mtree Fl Fl options='!all,type,time,uid' Pa dir -or you can set the compression level used by gzip or xz compression: -.Dl Nm Fl czf Pa file.tar Fl Fl options='compression-level=9' . -For more details, see the explanation of the -.Fn archive_read_set_options -and -.Fn archive_write_set_options -API calls that are described in -.Xr archive_read 3 -and -.Xr archive_write 3 . -.Sh COMPATIBILITY -The bundled-arguments format is supported for compatibility -with historic implementations. -It consists of an initial word (with no leading - character) in which -each character indicates an option. -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, -.Dl Nm Cm tbf 32 Pa file.tar -specifies three flags -.Cm t , -.Cm b , -and -.Cm f . -The -.Cm b -and -.Cm f -flags both require arguments, -so there must be two additional items -on the command line. -The -.Ar 32 -is the argument to the -.Cm b -flag, and -.Ar file.tar -is the argument to the -.Cm f -flag. -.Pp -The mode options c, r, t, u, and x and the options -b, f, l, m, o, v, and w comply with SUSv2. -.Pp -For maximum portability, scripts that invoke -.Nm tar -should use the bundled-argument format above, should limit -themselves to the -.Cm c , -.Cm t , -and -.Cm x -modes, and the -.Cm b , -.Cm f , -.Cm m , -.Cm v , -and -.Cm w -options. -.Pp -Additional long options are provided to improve compatibility with other -tar implementations. -.Sh SECURITY -Certain security issues are common to many archiving programs, including -.Nm . -In particular, carefully-crafted archives can request that -.Nm -extract files to locations outside of the target directory. -This can potentially be used to cause unwitting users to overwrite -files they did not intend to overwrite. -If the archive is being extracted by the superuser, any file -on the system can potentially be overwritten. -There are three ways this can happen. -Although -.Nm -has mechanisms to protect against each one, -savvy users should be aware of the implications: -.Bl -bullet -width indent -.It -Archive entries can have absolute pathnames. -By default, -.Nm -removes the leading -.Pa / -character from filenames before restoring them to guard against this problem. -.It -Archive entries can have pathnames that include -.Pa .. -components. -By default, -.Nm -will not extract files containing -.Pa .. -components in their pathname. -.It -Archive entries can exploit symbolic links to restore -files to other directories. -An archive can restore a symbolic link to another directory, -then use that link to restore a file into that directory. -To guard against this, -.Nm -checks each extracted path for symlinks. -If the final path element is a symlink, it will be removed -and replaced with the archive entry. -If -.Fl U -is specified, any intermediate symlink will also be unconditionally removed. -If neither -.Fl U -nor -.Fl P -is specified, -.Nm -will refuse to extract the entry. -.El -To protect yourself, you should be wary of any archives that -come from untrusted sources. -You should examine the contents of an archive with -.Dl Nm Fl tf Pa filename -before extraction. -You should use the -.Fl k -option to ensure that -.Nm -will not overwrite any existing files or the -.Fl U -option to remove any pre-existing files. -You should generally not extract archives while running with super-user -privileges. -Note that the -.Fl P -option to -.Nm -disables the security checks above and allows you to extract -an archive while preserving any absolute pathnames, -.Pa .. -components, or symlinks to other directories. -.Sh SEE ALSO -.Xr bzip2 1 , -.Xr compress 1 , -.Xr cpio 1 , -.Xr gzip 1 , -.Xr mt 1 , -.Xr pax 1 , -.Xr shar 1 , -.Xr xz 1 , -.Xr libarchive 3 , -.Xr libarchive-formats 5 , -.Xr tar 5 -.Sh STANDARDS -There is no current POSIX standard for the tar command; it appeared -in -.St -p1003.1-96 -but was dropped from -.St -p1003.1-2001 . -The options supported by this implementation were developed by surveying a -number of existing tar implementations as well as the old POSIX specification -for tar and the current POSIX specification for pax. -.Pp -The ustar and pax interchange file formats are defined by -.St -p1003.1-2001 -for the pax command. -.Sh HISTORY -A -.Nm tar -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 -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 -in -.Fx -beginning with -.Fx 1.0 . -.Pp -This is a complete re-implementation based on the -.Xr libarchive 3 -library. -It was first released with -.Fx 5.4 -in May, 2005. -.Sh BUGS -This program follows -.St -p1003.1-96 -for the definition of the -.Fl l -option. -Note that GNU tar prior to version 1.15 treated -.Fl l -as a synonym for the -.Fl Fl one-file-system -option. -.Pp -The -.Fl C Pa dir -option may differ from historic implementations. -.Pp -All archive output is written in correctly-sized blocks, even -if the output is being compressed. -Whether or not the last output block is padded to a full -block size varies depending on the format and the -output device. -For tar and cpio formats, the last block of output is padded -to a full block size if the output is being -written to standard output or to a character or block device such as -a tape drive. -If the output is being written to a regular file, the last block -will not be padded. -Many compressors, including -.Xr gzip 1 -and -.Xr bzip2 1 , -complain about the null padding when decompressing an archive created by -.Nm , -although they still extract it correctly. -.Pp -The compression and decompression is implemented internally, so -there may be insignificant differences between the compressed output -generated by -.Dl Nm Fl czf Pa - file -and that generated by -.Dl Nm Fl cf Pa - file | Nm gzip -.Pp -The default should be to read and write archives to the standard I/O paths, -but tradition (and POSIX) dictates otherwise. -.Pp -The -.Cm r -and -.Cm u -modes require that the archive be uncompressed -and located in a regular file on disk. -Other archives can be modified using -.Cm c -mode with the -.Pa @archive-file -extension. -.Pp -To archive a file called -.Pa @foo -or -.Pa -foo -you must specify it as -.Pa ./@foo -or -.Pa ./-foo , -respectively. -.Pp -In create mode, a leading -.Pa ./ -is always removed. -A leading -.Pa / -is stripped unless the -.Fl P -option is specified. -.Pp -There needs to be better support for file selection on both create -and extract. -.Pp -There is not yet any support for multi-volume archives or for archiving -sparse files. -.Pp -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.) |