diff options
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/man/bsdtar.1')
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/bsdtar.1 | 1024 |
1 files changed, 1024 insertions, 0 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/man/bsdtar.1 b/libarchive/libarchive-2.8.0/doc/man/bsdtar.1 new file mode 100644 index 0000000..bd9f618 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/bsdtar.1 @@ -0,0 +1,1024 @@ +.TH BSDTAR 1 "Oct 12, 2009" "" +.SH NAME +.ad l +\fB\%tar\fP +\- manipulate tape archives +.SH SYNOPSIS +.ad l +.br +\fB\%tar\fP +[\fIbundled-flags\fP <args>] +[<\fIfile\fP> | <\fIpattern\fP> ...] +.br +\fB\%tar\fP +{\fB\-c\fP} +[\fIoptions\fP] +[\fIfiles\fP | \fIdirectories\fP] +.br +\fB\%tar\fP +{\fB\-r\fP | \fB\-u\fP} +\fB\-f\fP \fIarchive-file\fP +[\fIoptions\fP] +[\fIfiles\fP | \fIdirectories\fP] +.br +\fB\%tar\fP +{\fB\-t\fP | \fB\-x\fP} +[\fIoptions\fP] +[\fIpatterns\fP] +.SH DESCRIPTION +.ad l +\fB\%tar\fP +creates and manipulates streaming archive files. +This implementation can extract from tar, pax, cpio, zip, jar, ar, +and ISO 9660 cdrom images and can create tar, pax, cpio, ar, +and shar archives. +.PP +The first synopsis form shows a +``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 +\fB\%tar\fP +is a mode indicator from the following list: +.RS 5 +.TP +\fB\-c\fP +Create a new archive containing the specified items. +.TP +\fB\-r\fP +Like +\fB\-c\fP, +but new entries are appended to the archive. +Note that this only works on uncompressed archives stored in regular files. +The +\fB\-f\fP +option is required. +.TP +\fB\-t\fP +List archive contents to stdout. +.TP +\fB\-u\fP +Like +\fB\-r\fP, +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 +\fB\-f\fP +option is required. +.TP +\fB\-x\fP +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. +.RE +.PP +In +\fB\-c\fP, +\fB\-r\fP, +or +\fB\-u\fP +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 +\fBtcsh\fP(1). +.SH OPTIONS +.ad l +Unless specifically stated otherwise, options are applicable in +all operating modes. +.RS 5 +.TP +\fB@\fP \fIarchive\fP +(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, +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fB@\fP \fIoriginal.tar\fP +.RE +writes a new archive to standard output containing a file +\fInewfile\fP +and all of the entries from +\fIoriginal.tar\fP. +In contrast, +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fIoriginal.tar\fP +.RE +creates a new archive with only two entries. +Similarly, +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fI-\fP \fB\--format\fP \fBpax\fP \fB@\fP \fI-\fP +.RE +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, +\fB\%tar\fP +can be used to convert archives from one format to another. +.TP +\fB\-b\fP \fIblocksize\fP +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. +.TP +\fB\-C\fP \fIdirectory\fP +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. +.TP +\fB\--check-links\fP +(c and r modes only) +Issue a warning message unless all links to each file are archived. +.TP +\fB\--chroot\fP +(x mode only) +\fB\%chroot\fP() +to the current directory after processing any +\fB\-C\fP +options and before extracting any files. +.TP +\fB\--exclude\fP \fIpattern\fP +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. +.TP +\fB\--format\fP \fIformat\fP +(c, r, u mode only) +Use the specified format for the created archive. +Supported formats include +``cpio'', +``pax'', +``shar'', +and +``ustar''. +Other formats may also be supported; see +\fBlibarchive-formats\fP(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. +.TP +\fB\-f\fP \fIfile\fP +Read the archive from or write the archive to the specified file. +The filename can be +\fI-\fP +for standard input or standard output. +If not specified, the default tape device will be used. +(On +FreeBSD, +the default tape device is +\fI/dev/sa0\fP.) +.TP +\fB\-H\fP +(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. +.TP +\fB\-h\fP +(c and r mode only) +Synonym for +\fB\-L\fP. +.TP +\fB\-I\fP +Synonym for +\fB\-T\fP. +.TP +\fB\--include\fP \fIpattern\fP +Process only files or directories that match the specified pattern. +Note that exclusions specified with +\fB\--exclude\fP +take precedence over inclusions. +If no inclusions are explicitly specified, all entries are processed by +default. +The +\fB\--include\fP +option is especially useful when filtering archives. +For example, the command +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fB\--include='*foo*'\fP \fB@\fP \fIold.tgz\fP +.RE +creates a new archive +\fInew.tar\fP +containing only the entries from +\fIold.tgz\fP +containing the string +Sq foo. +.TP +\fB\-j\fP +(c mode only) +Compress the resulting archive with +\fBbzip2\fP(1). +In extract or list modes, this option is ignored. +Note that, unlike other +\fB\%tar\fP +implementations, this implementation recognizes bzip2 compression +automatically when reading archives. +.TP +\fB\-k\fP +(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. +.TP +\fB\--keep-newer-files\fP +(x mode only) +Do not overwrite existing files that are newer than the +versions appearing in the archive being extracted. +.TP +\fB\-L\fP +(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. +.TP +\fB\-l\fP +This is a synonym for the +\fB\--check-links\fP +option. +.TP +\fB\-m\fP +(x mode only) +Do not extract modification time. +By default, the modification time is set to the time stored in the archive. +.TP +\fB\-n\fP +(c, r, u modes only) +Do not recursively archive the contents of directories. +.TP +\fB\--newer\fP \fIdate\fP +(c, r, u modes only) +Only include files and directories newer than the specified date. +This compares ctime entries. +.TP +\fB\--newer-mtime\fP \fIdate\fP +(c, r, u modes only) +Like +\fB\--newer\fP, +except it compares mtime entries instead of ctime entries. +.TP +\fB\--newer-than\fP \fIfile\fP +(c, r, u modes only) +Only include files and directories newer than the specified file. +This compares ctime entries. +.TP +\fB\--newer-mtime-than\fP \fIfile\fP +(c, r, u modes only) +Like +\fB\--newer-than\fP, +except it compares mtime entries instead of ctime entries. +.TP +\fB\--nodump\fP +(c and r modes only) +Honor the nodump file flag by skipping this file. +.TP +\fB\--null\fP +(use with +\fB\-I\fP, +\fB\-T\fP, +or +\fB\-X\fP) +Filenames or patterns are separated by null characters, +not by newlines. +This is often used to read filenames output by the +\fB\-print0\fP +option to +\fBfind\fP(1). +.TP +\fB\--numeric-owner\fP +(x mode only) +Ignore symbolic user and group names when restoring archives to disk, +only numeric uid and gid values will be obeyed. +.TP +\fB\-O\fP +(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. +.TP +\fB\-o\fP +(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 +\fB\-p\fP +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. +.TP +\fB\-o\fP +(c, r, u mode) +A synonym for +\fB\--format\fP \fIustar\fP +.TP +\fB\--one-file-system\fP +(c, r, and u modes) +Do not cross mount points. +.TP +\fB\--options\fP \fIoptions\fP +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: +.RS 5 +.TP +\fIkey=value\fP +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. +.TP +\fIkey\fP +The key will be enabled in every module that supports it. +This is equivalent to +\fIkey\fP \fB=1\fP. +.TP +\fI!key\fP +The key will be disabled in every module that supports it. +.TP +\fImodule:key=value\fP, \fImodule:key\fP, \fImodule:!key\fP +As above, but the corresponding key and value will be provided +only to modules whose name matches +\fImodule\fP. +.RE +The currently supported modules and keys are: +.RS 5 +.TP +\fBiso9660:joliet\fP +Support Joliet extensions. +This is enabled by default, use +\fB!joliet\fP +or +\fBiso9660:!joliet\fP +to disable. +.TP +\fBiso9660:rockridge\fP +Support Rock Ridge extensions. +This is enabled by default, use +\fB!rockridge\fP +or +\fBiso9660:!rockridge\fP +to disable. +.TP +\fBgzip:compression-level\fP +A decimal integer from 0 to 9 specifying the gzip compression level. +.TP +\fBxz:compression-level\fP +A decimal integer from 0 to 9 specifying the xz compression level. +.TP +\fBmtree:\fP \fIkeyword\fP +The mtree writer module allows you to specify which mtree keywords +will be included in the output. +Supported keywords include: +\fBcksum\fP, \fBdevice\fP, \fBflags\fP, \fBgid\fP, \fBgname\fP, \fBindent\fP, +\fBlink\fP, \fBmd5\fP, \fBmode\fP, \fBnlink\fP, \fBrmd160\fP, \fBsha1\fP, \fBsha256\fP, +\fBsha384\fP, \fBsha512\fP, \fBsize\fP, \fBtime\fP, \fBuid\fP, \fBuname\fP. +The default is equivalent to: +``device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname''. +.TP +\fBmtree:all\fP +Enables all of the above keywords. +You can also use +\fBmtree:!all\fP +to disable all keywords. +.TP +\fBmtree:use-set\fP +Enable generation of +\fB/set\fP +lines in the output. +.TP +\fBmtree:indent\fP +Produce human-readable output by indenting options and splitting lines +to fit into 80 columns. +.TP +\fBzip:compression\fP=\fItype\fP +Use +\fItype\fP +as compression method. +Supported values are store (uncompressed) and deflate (gzip algorithm). +.RE +If a provided option is not supported by any module, that +is a fatal error. +.TP +\fB\-P\fP +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, +\fB\%tar\fP +will refuse to extract archive entries whose pathnames contain +\fI\& ..\fP +or whose target directory would be altered by a symlink. +This option suppresses these behaviors. +.TP +\fB\-p\fP +(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. +By default, newly-created files are owned by the user running +\fB\%tar\fP, +the file mode is restored for newly-created regular files, and +all other types of entries receive default permissions. +If +\fB\%tar\fP +is being run by root, the default is to restore the owner unless the +\fB\-o\fP +option is also specified. +.TP +\fB\-q\fP (\fB\--fast-read\fP) +(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. +.TP +\fB\-S\fP +(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 similiar to the conv=sparse option of dd. +.TP +\fB\--strip-components\fP \fIcount\fP +(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. +.TP +\fB\-s\fP \fIpattern\fP +Modify file or archive member names according to +\fIpattern\fP. +The pattern has the format +\fI/old/new/\fP [gps] +where +\fIold\fP +is a basic regular expression, +\fInew\fP +is the replacement string of the matched part, +and the optional trailing letters modify +how the replacement is handled. +If +\fIold\fP +is not matched, the pattern is skipped. +Within +\fInew\fP, +~ is substituted with the match, \1 to \9 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. +.TP +\fB\-T\fP \fIfilename\fP +In x or t mode, +\fB\%tar\fP +will read the list of names to be extracted from +\fIfilename\fP. +In c mode, +\fB\%tar\fP +will read names to be archived from +\fIfilename\fP. +The special name +``-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 +\fB\--null\fP +is specified. +Note that +\fB\--null\fP +also disables the special handling of lines containing +``-C''. +.TP +\fB\-U\fP +(x mode only) +Unlink files before creating them. +Without this option, +\fB\%tar\fP +overwrites existing files, which preserves existing hardlinks. +With this option, existing hardlinks will be broken, as will any +symlink that would affect the location of an extracted file. +.TP +\fB\--use-compress-program\fP \fIprogram\fP +Pipe the input (in x or t mode) or the output (in c mode) through +\fIprogram\fP +instead of using the builtin compression support. +.TP +\fB\-v\fP +Produce verbose output. +In create and extract modes, +\fB\%tar\fP +will list each file name as it is read from or written to +the archive. +In list mode, +\fB\%tar\fP +will produce output similar to that of +\fBls\fP(1). +Additional +\fB\-v\fP +options will provide additional detail. +.TP +\fB\--version\fP +Print version of +\fB\%tar\fP +and +\fB\%libarchive\fP, +and exit. +.TP +\fB\-w\fP +Ask for confirmation for every action. +.TP +\fB\-X\fP \fIfilename\fP +Read a list of exclusion patterns from the specified file. +See +\fB\--exclude\fP +for more information about the handling of exclusions. +.TP +\fB\-y\fP +(c mode only) +Compress the resulting archive with +\fBbzip2\fP(1). +In extract or list modes, this option is ignored. +Note that, unlike other +\fB\%tar\fP +implementations, this implementation recognizes bzip2 compression +automatically when reading archives. +.TP +\fB\-z\fP +(c mode only) +Compress the resulting archive with +\fBgzip\fP(1). +In extract or list modes, this option is ignored. +Note that, unlike other +\fB\%tar\fP +implementations, this implementation recognizes gzip compression +automatically when reading archives. +.TP +\fB\-Z\fP +(c mode only) +Compress the resulting archive with +\fBcompress\fP(1). +In extract or list modes, this option is ignored. +Note that, unlike other +\fB\%tar\fP +implementations, this implementation recognizes compress compression +automatically when reading archives. +.RE +.SH ENVIRONMENT +.ad l +The following environment variables affect the execution of +\fB\%tar\fP: +.RS 5 +.TP +.B LANG +The locale to use. +See +\fBenviron\fP(7) +for more information. +.TP +.B TAPE +The default tape device. +The +\fB\-f\fP +option overrides this. +.TP +.B TZ +The timezone to use when displaying dates. +See +\fBenviron\fP(7) +for more information. +.RE +.SH FILES +.ad l +.RS 5 +.TP +.B /dev/sa0 +The default tape device, if not overridden by the +.IR TAPE +environment variable or the +\fB\-f\fP +option. +.RE +.SH EXIT STATUS +.ad l +The \fBtar\fP utility exits 0 on success, and >0 if an error occurs. +.SH EXAMPLES +.ad l +The following creates a new archive +called +\fIfile.tar.gz\fP +that contains two files +\fIsource.c\fP +and +\fIsource.h\fP: +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fIfile.tar.gz\fP \fIsource.c\fP \fIsource.h\fP +.RE +.PP +To view a detailed table of contents for this +archive: +.RS 4 +\fB\%tar\fP \fB\-tvf\fP \fIfile.tar.gz\fP +.RE +.PP +To extract all entries from the archive on +the default tape drive: +.RS 4 +\fB\%tar\fP \fB\-x\fP +.RE +.PP +To examine the contents of an ISO 9660 cdrom image: +.RS 4 +\fB\%tar\fP \fB\-tf\fP \fIimage.iso\fP +.RE +.PP +To move file hierarchies, invoke +\fB\%tar\fP +as +.RS 4 +\fB\%tar\fP \fB\-cf\fP \fI-\fP \fB\-C\fP \fIsrcdir\\fP. | \fB\%tar\fP \fB\-xpf\fP \fI-\fP \fB\-C\fP \fIdestdir\fP +.RE +or more traditionally +.RS 4 +cd srcdir \&; \fB\%tar\fP \fB\-cf\fP \fI-\\fP. | (cd destdir \&; \fB\%tar\fP \fB\-xpf\fP \fI-\fP) +.RE +.PP +In create mode, the list of files and directories to be archived +can also include directory change instructions of the form +\fB-C\fP \fIfoo/baz\fP +and archive inclusions of the form +\fB@\fP \fIarchive-file\fP. +For example, the command line +.RS 4 +\fB\%tar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fIfoo1\fP \fB@\fP \fIold.tgz\fP \fB-C\fP \fI/tmp\fP \fIfoo2\fP +.RE +will create a new archive +\fInew.tar\fP. +\fB\%tar\fP +will read the file +\fIfoo1\fP +from the current directory and add it to the output archive. +It will then read each entry from +\fIold.tgz\fP +and add those entries to the output archive. +Finally, it will switch to the +\fI/tmp\fP +directory and add +\fIfoo2\fP +to the output archive. +.PP +An input file in +\fBmtree\fP(5) +format can be used to create an output archive with arbitrary ownership, +permissions, or names that differ from existing data on disk: +.PP +.RS 4 +$ cat input.mtree +.RE +.RS 4 +#mtree +.RE +.RS 4 +usr/bin uid=0 gid=0 mode=0755 type=dir +.RE +.RS 4 +usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls +.RE +.RS 4 +$ tar -cvf output.tar @input.mtree +.RE +.PP +The +\fB\--newer\fP +and +\fB\--newer-mtime\fP +switches accept a variety of common date and time specifications, including +``12 Mar 2005 7:14:29pm'', +``2005-03-12 19:14'', +``5 minutes ago'', +and +``19:14 PST May 1''. +.PP +The +\fB\--options\fP +argument can be used to control various details of archive generation +or reading. +For example, you can generate mtree output which only contains +\fBtype\fP, \fBtime\fP, +and +\fBuid\fP +keywords: +.RS 4 +\fB\%tar\fP \fB\-cf\fP \fIfile.tar\fP \fB\--format=mtree\fP \fB\--options='!all,type,time,uid'\fP \fIdir\fP +.RE +or you can set the compression level used by gzip or xz compression: +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fIfile.tar\fP \fB\--options='compression-level=9'\fP. +.RE +For more details, see the explanation of the +\fB\%archive_read_set_options\fP() +and +\fB\%archive_write_set_options\fP() +API calls that are described in +\fBarchive_read\fP(3) +and +\fBarchive_write\fP(3). +.SH COMPATIBILITY +.ad l +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, +.RS 4 +\fB\%tar\fP \fBtbf\fP 32 \fIfile.tar\fP +.RE +specifies three flags +\fBt\fP, +\fBb\fP, +and +\fBf\fP. +The +\fBb\fP +and +\fBf\fP +flags both require arguments, +so there must be two additional items +on the command line. +The +\fI32\fP +is the argument to the +\fBb\fP +flag, and +\fIfile.tar\fP +is the argument to the +\fBf\fP +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 +\fB\%tar\fP +should use the bundled-argument format above, should limit +themselves to the +\fBc\fP, +\fBt\fP, +and +\fBx\fP +modes, and the +\fBb\fP, +\fBf\fP, +\fBm\fP, +\fBv\fP, +and +\fBw\fP +options. +.PP +Additional long options are provided to improve compatibility with other +tar implementations. +.SH SECURITY +.ad l +Certain security issues are common to many archiving programs, including +\fB\%tar\fP. +In particular, carefully-crafted archives can request that +\fB\%tar\fP +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 +\fB\%tar\fP +has mechanisms to protect against each one, +savvy users should be aware of the implications: +.RS 5 +.IP \(bu +Archive entries can have absolute pathnames. +By default, +\fB\%tar\fP +removes the leading +\fI/\fP +character from filenames before restoring them to guard against this problem. +.IP \(bu +Archive entries can have pathnames that include +\fI\& ..\fP +components. +By default, +\fB\%tar\fP +will not extract files containing +\fI\& ..\fP +components in their pathname. +.IP \(bu +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, +\fB\%tar\fP +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 +\fB\-U\fP +is specified, any intermediate symlink will also be unconditionally removed. +If neither +\fB\-U\fP +nor +\fB\-P\fP +is specified, +\fB\%tar\fP +will refuse to extract the entry. +.RE +To protect yourself, you should be wary of any archives that +come from untrusted sources. +You should examine the contents of an archive with +.RS 4 +\fB\%tar\fP \fB\-tf\fP \fIfilename\fP +.RE +before extraction. +You should use the +\fB\-k\fP +option to ensure that +\fB\%tar\fP +will not overwrite any existing files or the +\fB\-U\fP +option to remove any pre-existing files. +You should generally not extract archives while running with super-user +privileges. +Note that the +\fB\-P\fP +option to +\fB\%tar\fP +disables the security checks above and allows you to extract +an archive while preserving any absolute pathnames, +\fI\& ..\fP +components, or symlinks to other directories. +.SH SEE ALSO +.ad l +\fBbzip2\fP(1), +\fBcompress\fP(1), +\fBcpio\fP(1), +\fBgzip\fP(1), +\fBmt\fP(1), +\fBpax\fP(1), +\fBshar\fP(1), +\fBlibarchive\fP(3), +\fBlibarchive-formats\fP(5), +\fBtar\fP(5) +.SH STANDARDS +.ad l +There is no current POSIX standard for the tar command; it appeared +in +ISO/IEC 9945-1:1996 (``POSIX.1'') +but was dropped from +IEEE Std 1003.1-2001 (``POSIX.1''). +The options used 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 +IEEE Std 1003.1-2001 (``POSIX.1'') +for the pax command. +.SH HISTORY +.ad l +A +\fB\%tar\fP +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 +\fB\%pdtar\fP +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 +FreeBSD +beginning with +FreeBSD 1.0. +.PP +This is a complete re-implementation based on the +\fBlibarchive\fP(3) +library. +.SH BUGS +.ad l +This program follows +ISO/IEC 9945-1:1996 (``POSIX.1'') +for the definition of the +\fB\-l\fP +option. +Note that GNU tar prior to version 1.15 treated +\fB\-l\fP +as a synonym for the +\fB\--one-file-system\fP +option. +.PP +The +\fB\-C\fP \fIdir\fP +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 +\fBgzip\fP(1) +and +\fBbzip2\fP(1), +complain about the null padding when decompressing an archive created by +\fB\%tar\fP, +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 +.RS 4 +\fB\%tar\fP \fB\-czf\fP \fI-\fP file +.RE +and that generated by +.RS 4 +\fB\%tar\fP \fB\-cf\fP \fI-\fP file | \fB\%gzip\fP +.RE +.PP +The default should be to read and write archives to the standard I/O paths, +but tradition (and POSIX) dictates otherwise. +.PP +The +\fBr\fP +and +\fBu\fP +modes require that the archive be uncompressed +and located in a regular file on disk. +Other archives can be modified using +\fBc\fP +mode with the +\fI@archive-file\fP +extension. +.PP +To archive a file called +\fI@foo\fP +or +\fI-foo\fP +you must specify it as +\fI\& ./@foo\fP +or +\fI\& ./-foo\fP, +respectively. +.PP +In create mode, a leading +\fI\& ./\fP +is always removed. +A leading +\fI/\fP +is stripped unless the +\fB\-P\fP +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 +\fB@\fP \fI-\fP +convention can cause hard link information to be lost. +(This is a consequence of the incompatible ways that different archive +formats store hardlink information.) +.PP +There are alternative long options for many of the short options that +are deliberately not documented. |