diff options
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html')
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html | 1014 |
1 files changed, 1014 insertions, 0 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html b/libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html new file mode 100644 index 0000000..3b84d21 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/bsdtar.1.html @@ -0,0 +1,1014 @@ +<!-- Creator : groff version 1.19.2 --> +<!-- CreationDate: Thu Feb 4 20:36:40 2010 --> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" +"http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> +<meta name="generator" content="groff -Thtml, see www.gnu.org"> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<meta name="Content-Style" content="text/css"> +<style type="text/css"> + p { margin-top: 0; margin-bottom: 0; } + pre { margin-top: 0; margin-bottom: 0; } + table { margin-top: 0; margin-bottom: 0; } +</style> +<title></title> +</head> +<body> + +<hr> + + +<p valign="top">BSDTAR(1) FreeBSD General Commands Manual +BSDTAR(1)</p> + +<p style="margin-top: 1em" valign="top"><b>NAME</b></p> + +<p style="margin-left:8%;"><b>tar</b> — manipulate +tape archives</p> + + +<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> + +<p style="margin-left:14%;"><b>tar</b> +[<i>bundled-flags </i>⟨</p> + +<p valign="top">args ⟩] [⟨ <i><br> +file</i> ⟩ | ⟨ <i><br> +pattern</i> ⟩ ...]</p> + +<p style="margin-left:14%;"><b>tar</b> {<b>−c</b>} +[<i>options</i>] +[<i>files </i>| <i>directories</i>] <b><br> +tar</b> {<b>−r </b>| <b>−u</b>} +<b>−f</b> <i>archive-file</i> [<i>options</i>] +[<i>files </i>| <i>directories</i>] <b><br> +tar</b> {<b>−t </b>| <b>−x</b>} +[<i>options</i>] [<i>patterns</i>]</p> + + +<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> + +<p style="margin-left:8%;"><b>tar</b> 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.</p> + +<p style="margin-left:8%; margin-top: 1em">The first +synopsis form shows a ‘‘bundled’’ +option word. This usage is provided for compatibility with +historical implementations. See COMPATIBILITY below for +details.</p> + +<p style="margin-left:8%; margin-top: 1em">The other +synopsis forms show the preferred usage. The first option to +<b>tar</b> is a mode indicator from the following list:</p> + +<p valign="top"><b>−c</b></p> + +<p style="margin-left:20%; margin-top: 1em">Create a new +archive containing the specified items.</p> + +<p valign="top"><b>−r</b></p> + +<p style="margin-left:20%; margin-top: 1em">Like +<b>−c</b>, but new entries are appended to the +archive. Note that this only works on uncompressed archives +stored in regular files. The <b>−f</b> option is +required.</p> + +<p valign="top"><b>−t</b></p> + +<p style="margin-left:20%; margin-top: 1em">List archive +contents to stdout.</p> + +<p valign="top"><b>−u</b></p> + +<p style="margin-left:20%; margin-top: 1em">Like +<b>−r</b>, 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 <b>−f</b> option +is required.</p> + +<p valign="top"><b>−x</b></p> + +<p style="margin-left:20%; margin-top: 1em">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.</p> + +<p style="margin-left:8%; margin-top: 1em">In +<b>−c</b>, <b>−r</b>, or <b>−u</b> 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.</p> + +<p style="margin-left:8%; margin-top: 1em">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 tcsh(1).</p> + +<p style="margin-top: 1em" valign="top"><b>OPTIONS</b></p> + +<p style="margin-left:8%;">Unless specifically stated +otherwise, options are applicable in all operating +modes.</p> + + +<p style="margin-top: 1em" valign="top"><b>@</b><i>archive</i></p> + +<p style="margin-left:20%;">(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,</p> + +<p style="margin-left:29%;"><b>tar −c −f</b> +<i>- newfile</i> <b>@</b><i>original.tar</i></p> + +<p style="margin-left:20%;">writes a new archive to +standard output containing a file <i>newfile</i> and all of +the entries from <i>original.tar</i>. In contrast,</p> + +<p style="margin-left:29%;"><b>tar −c −f</b> +<i>- newfile original.tar</i></p> + +<p style="margin-left:20%;">creates a new archive with only +two entries. Similarly,</p> + +<p style="margin-left:29%;"><b>tar −czf</b> <i>-</i> +<b>−-format pax @</b><i>-</i></p> + +<p style="margin-left:20%;">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, <b>tar</b> can be used to convert +archives from one format to another.</p> + +<p style="margin-top: 1em" valign="top"><b>−b</b> +<i>blocksize</i></p> + +<p style="margin-left:20%;">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.</p> + +<p style="margin-top: 1em" valign="top"><b>−C</b> +<i>directory</i></p> + +<p style="margin-left:20%;">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.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-check-links</b></p> + +<p style="margin-left:20%;">(c and r modes only) Issue a +warning message unless all links to each file are +archived.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-chroot</b></p> + +<p style="margin-left:20%;">(x mode only) <b>chroot</b>() +to the current directory after processing any +<b>−C</b> options and before extracting any files.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-exclude</b> +<i>pattern</i></p> + +<p style="margin-left:20%;">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.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-format</b> +<i>format</i></p> + +<p style="margin-left:20%;">(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 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.</p> + +<p style="margin-top: 1em" valign="top"><b>−f</b> +<i>file</i></p> + +<p style="margin-left:20%;">Read the archive from or write +the archive to the specified file. The filename can be +<i>-</i> for standard input or standard output. If not +specified, the default tape device will be used. (On +FreeBSD, the default tape device is <i>/dev/sa0</i>.)</p> + + +<p style="margin-top: 1em" valign="top"><b>−H</b></p> + +<p style="margin-left:20%; margin-top: 1em">(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.</p> + + +<p style="margin-top: 1em" valign="top"><b>−h</b></p> + +<p style="margin-left:20%; margin-top: 1em">(c and r mode +only) Synonym for <b>−L</b>.</p> + + +<p style="margin-top: 1em" valign="top"><b>−I</b></p> + +<p style="margin-left:20%; margin-top: 1em">Synonym for +<b>−T</b>.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-include</b> +<i>pattern</i></p> + +<p style="margin-left:20%;">Process only files or +directories that match the specified pattern. Note that +exclusions specified with <b>−-exclude</b> take +precedence over inclusions. If no inclusions are explicitly +specified, all entries are processed by default. The +<b>−-include</b> option is especially useful when +filtering archives. For example, the command</p> + +<p style="margin-left:29%;"><b>tar −c −f</b> +<i>new.tar</i> <b>−-include=’*foo*’ +@</b><i>old.tgz</i></p> + +<p style="margin-left:20%;">creates a new archive +<i>new.tar</i> containing only the entries from +<i>old.tgz</i> containing the string ‘foo’.</p> + + +<p style="margin-top: 1em" valign="top"><b>−j</b></p> + +<p style="margin-left:20%; margin-top: 1em">(c mode only) +Compress the resulting archive with bzip2(1). In extract or +list modes, this option is ignored. Note that, unlike other +<b>tar</b> implementations, this implementation recognizes +bzip2 compression automatically when reading archives.</p> + + +<p style="margin-top: 1em" valign="top"><b>−k</b></p> + +<p style="margin-left:20%; margin-top: 1em">(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.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-keep-newer-files</b></p> + +<p style="margin-left:20%;">(x mode only) Do not overwrite +existing files that are newer than the versions appearing in +the archive being extracted.</p> + + +<p style="margin-top: 1em" valign="top"><b>−L</b></p> + +<p style="margin-left:20%; margin-top: 1em">(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.</p> + + +<p style="margin-top: 1em" valign="top"><b>−l</b></p> + +<p style="margin-left:20%; margin-top: 1em">This is a +synonym for the <b>−-check-links</b> option.</p> + + +<p style="margin-top: 1em" valign="top"><b>−m</b></p> + +<p style="margin-left:20%; margin-top: 1em">(x mode only) +Do not extract modification time. By default, the +modification time is set to the time stored in the +archive.</p> + + +<p style="margin-top: 1em" valign="top"><b>−n</b></p> + +<p style="margin-left:20%; margin-top: 1em">(c, r, u modes +only) Do not recursively archive the contents of +directories.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-newer</b> +<i>date</i></p> + +<p style="margin-left:20%;">(c, r, u modes only) Only +include files and directories newer than the specified date. +This compares ctime entries.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-newer-mtime</b> +<i>date</i></p> + +<p style="margin-left:20%;">(c, r, u modes only) Like +<b>−-newer</b>, except it compares mtime entries +instead of ctime entries.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-newer-than</b> +<i>file</i></p> + +<p style="margin-left:20%;">(c, r, u modes only) Only +include files and directories newer than the specified file. +This compares ctime entries.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-newer-mtime-than</b> +<i>file</i></p> + +<p style="margin-left:20%;">(c, r, u modes only) Like +<b>−-newer-than</b>, except it compares mtime entries +instead of ctime entries.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-nodump</b></p> + +<p style="margin-left:20%;">(c and r modes only) Honor the +nodump file flag by skipping this file.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-null</b></p> + +<p style="margin-left:20%; margin-top: 1em">(use with +<b>−I</b>, <b>−T</b>, or <b>−X</b>) +Filenames or patterns are separated by null characters, not +by newlines. This is often used to read filenames output by +the <b>−print0</b> option to find(1).</p> + + +<p style="margin-top: 1em" valign="top"><b>−-numeric-owner</b></p> + +<p style="margin-left:20%;">(x mode only) Ignore symbolic +user and group names when restoring archives to disk, only +numeric uid and gid values will be obeyed.</p> + + +<p style="margin-top: 1em" valign="top"><b>−O</b></p> + +<p style="margin-left:20%; margin-top: 1em">(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.</p> + + +<p style="margin-top: 1em" valign="top"><b>−o</b></p> + +<p style="margin-left:20%; margin-top: 1em">(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 <b>−p</b> 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.</p> + + +<p style="margin-top: 1em" valign="top"><b>−o</b></p> + +<p style="margin-left:20%; margin-top: 1em">(c, r, u mode) +A synonym for <b>−-format</b> <i>ustar</i></p> + + +<p style="margin-top: 1em" valign="top"><b>−-one-file-system</b></p> + +<p style="margin-left:20%;">(c, r, and u modes) Do not +cross mount points.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-options</b> +<i>options</i></p> + +<p style="margin-left:20%;">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:</p> + +<p valign="top"><i>key=value</i></p> + +<p style="margin-left:32%;">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.</p> + +<p valign="top"><i>key</i></p> + +<p style="margin-left:32%; margin-top: 1em">The key will be +enabled in every module that supports it. This is equivalent +to <i>key</i><b>=1</b>.</p> + +<p valign="top"><i>!key</i></p> + +<p style="margin-left:32%; margin-top: 1em">The key will be +disabled in every module that supports it.</p> + +<p valign="top"><i>module:key=value</i>, <i>module:key</i>, +<i>module:!key</i></p> + +<p style="margin-left:32%;">As above, but the corresponding +key and value will be provided only to modules whose name +matches <i>module</i>.</p> + +<p style="margin-left:20%;">The currently supported modules +and keys are:</p> + +<p valign="top"><b>iso9660:joliet</b></p> + +<p style="margin-left:32%;">Support Joliet extensions. This +is enabled by default, use <b>!joliet</b> or +<b>iso9660:!joliet</b> to disable.</p> + +<p valign="top"><b>iso9660:rockridge</b></p> + +<p style="margin-left:32%;">Support Rock Ridge extensions. +This is enabled by default, use <b>!rockridge</b> or +<b>iso9660:!rockridge</b> to disable.</p> + +<p valign="top"><b>gzip:compression-level</b></p> + +<p style="margin-left:32%;">A decimal integer from 0 to 9 +specifying the gzip compression level.</p> + +<p valign="top"><b>xz:compression-level</b></p> + +<p style="margin-left:32%;">A decimal integer from 0 to 9 +specifying the xz compression level.</p> + +<p valign="top"><b>mtree:</b><i>keyword</i></p> + +<p style="margin-left:32%;">The mtree writer module allows +you to specify which mtree keywords will be included in the +output. Supported keywords include: <b>cksum</b>, +<b>device</b>, <b>flags</b>, <b>gid</b>, <b>gname</b>, +<b>indent</b>, <b>link</b>, <b>md5</b>, <b>mode</b>, +<b>nlink</b>, <b>rmd160</b>, <b>sha1</b>, <b>sha256</b>, +<b>sha384</b>, <b>sha512</b>, <b>size</b>, <b>time</b>, +<b>uid</b>, <b>uname</b>. The default is equivalent to: +‘‘device, flags, gid, gname, link, mode, nlink, +size, time, type, uid, uname’’.</p> + +<p valign="top"><b>mtree:all</b></p> + +<p style="margin-left:32%;">Enables all of the above +keywords. You can also use <b>mtree:!all</b> to disable all +keywords.</p> + +<p valign="top"><b>mtree:use-set</b></p> + +<p style="margin-left:32%;">Enable generation of +<b>/set</b> lines in the output.</p> + +<p valign="top"><b>mtree:indent</b></p> + +<p style="margin-left:32%;">Produce human-readable output +by indenting options and splitting lines to fit into 80 +columns.</p> + +<p valign="top"><b>zip:compression</b>=<i>type</i></p> + +<p style="margin-left:32%;">Use <i>type</i> as compression +method. Supported values are store (uncompressed) and +deflate (gzip algorithm).</p> + +<p style="margin-left:20%;">If a provided option is not +supported by any module, that is a fatal error.</p> + + +<p style="margin-top: 1em" valign="top"><b>−P</b></p> + +<p style="margin-left:20%; margin-top: 1em">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, <b>tar</b> +will refuse to extract archive entries whose pathnames +contain <i>..</i> or whose target directory would be altered +by a symlink. This option suppresses these behaviors.</p> + + +<p style="margin-top: 1em" valign="top"><b>−p</b></p> + +<p style="margin-left:20%; margin-top: 1em">(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 <b>tar</b>, the file mode is restored for +newly-created regular files, and all other types of entries +receive default permissions. If <b>tar</b> is being run by +root, the default is to restore the owner unless the +<b>−o</b> option is also specified.</p> + +<p style="margin-top: 1em" valign="top"><b>−q</b> +(<b>−-fast-read</b>)</p> + +<p style="margin-left:20%;">(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.</p> + + +<p style="margin-top: 1em" valign="top"><b>−S</b></p> + +<p style="margin-left:20%; margin-top: 1em">(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.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-strip-components</b> +<i>count</i></p> + +<p style="margin-left:20%;">(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.</p> + +<p style="margin-top: 1em" valign="top"><b>−s</b> +<i>pattern</i></p> + +<p style="margin-left:20%;">Modify file or archive member +names according to <i>pattern</i>. The pattern has the +format <i>/old/new/</i>[gps] where <i>old</i> is a basic +regular expression, <i>new</i> is the replacement string of +the matched part, and the optional trailing letters modify +how the replacement is handled. If <i>old</i> is not +matched, the pattern is skipped. Within <i>new</i>, ~ 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.</p> + +<p style="margin-top: 1em" valign="top"><b>−T</b> +<i>filename</i></p> + +<p style="margin-left:20%;">In x or t mode, <b>tar</b> will +read the list of names to be extracted from <i>filename</i>. +In c mode, <b>tar</b> will read names to be archived from +<i>filename</i>. 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 <b>−-null</b> is specified. Note that +<b>−-null</b> also disables the special handling of +lines containing ‘‘-C’’.</p> + + +<p style="margin-top: 1em" valign="top"><b>−U</b></p> + +<p style="margin-left:20%; margin-top: 1em">(x mode only) +Unlink files before creating them. Without this option, +<b>tar</b> 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.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-use-compress-program</b> +<i>program</i></p> + +<p style="margin-left:20%;">Pipe the input (in x or t mode) +or the output (in c mode) through <i>program</i> instead of +using the builtin compression support.</p> + + +<p style="margin-top: 1em" valign="top"><b>−v</b></p> + +<p style="margin-left:20%; margin-top: 1em">Produce verbose +output. In create and extract modes, <b>tar</b> will list +each file name as it is read from or written to the archive. +In list mode, <b>tar</b> will produce output similar to that +of ls(1). Additional <b>−v</b> options will provide +additional detail.</p> + + +<p style="margin-top: 1em" valign="top"><b>−-version</b></p> + +<p style="margin-left:20%;">Print version of <b>tar</b> and +<b>libarchive</b>, and exit.</p> + + +<p style="margin-top: 1em" valign="top"><b>−w</b></p> + +<p style="margin-left:20%; margin-top: 1em">Ask for +confirmation for every action.</p> + +<p style="margin-top: 1em" valign="top"><b>−X</b> +<i>filename</i></p> + +<p style="margin-left:20%;">Read a list of exclusion +patterns from the specified file. See <b>−-exclude</b> +for more information about the handling of exclusions.</p> + + +<p style="margin-top: 1em" valign="top"><b>−y</b></p> + +<p style="margin-left:20%; margin-top: 1em">(c mode only) +Compress the resulting archive with bzip2(1). In extract or +list modes, this option is ignored. Note that, unlike other +<b>tar</b> implementations, this implementation recognizes +bzip2 compression automatically when reading archives.</p> + + +<p style="margin-top: 1em" valign="top"><b>−z</b></p> + +<p style="margin-left:20%; margin-top: 1em">(c mode only) +Compress the resulting archive with gzip(1). In extract or +list modes, this option is ignored. Note that, unlike other +<b>tar</b> implementations, this implementation recognizes +gzip compression automatically when reading archives.</p> + + +<p style="margin-top: 1em" valign="top"><b>−Z</b></p> + +<p style="margin-left:20%; margin-top: 1em">(c mode only) +Compress the resulting archive with compress(1). In extract +or list modes, this option is ignored. Note that, unlike +other <b>tar</b> implementations, this implementation +recognizes compress compression automatically when reading +archives.</p> + + +<p style="margin-top: 1em" valign="top"><b>ENVIRONMENT</b></p> + +<p style="margin-left:8%;">The following environment +variables affect the execution of <b>tar</b>:</p> + +<p style="margin-top: 1em" valign="top">LANG</p> + +<p style="margin-left:25%; margin-top: 1em">The locale to +use. See environ(7) for more information.</p> + +<p style="margin-top: 1em" valign="top">TAPE</p> + +<p style="margin-left:25%; margin-top: 1em">The default +tape device. The <b>−f</b> option overrides this.</p> + +<p style="margin-top: 1em" valign="top">TZ</p> + +<p style="margin-left:25%; margin-top: 1em">The timezone to +use when displaying dates. See environ(7) for more +information.</p> + +<p style="margin-top: 1em" valign="top"><b>FILES</b> <br> +/dev/sa0</p> + +<p style="margin-left:25%; margin-top: 1em">The default +tape device, if not overridden by the TAPE environment +variable or the <b>−f</b> option.</p> + +<p style="margin-top: 1em" valign="top"><b>EXIT +STATUS</b></p> + +<p style="margin-left:8%;">The <b>tar</b> utility +exits 0 on success, and >0 if an error +occurs.</p> + + +<p style="margin-top: 1em" valign="top"><b>EXAMPLES</b></p> + +<p style="margin-left:8%;">The following creates a new +archive called <i>file.tar.gz</i> that contains two files +<i>source.c</i> and <i>source.h</i>:</p> + +<p style="margin-left:17%;"><b>tar −czf</b> +<i>file.tar.gz source.c source.h</i></p> + +<p style="margin-left:8%; margin-top: 1em">To view a +detailed table of contents for this archive:</p> + +<p style="margin-left:17%;"><b>tar −tvf</b> +<i>file.tar.gz</i></p> + +<p style="margin-left:8%; margin-top: 1em">To extract all +entries from the archive on the default tape drive:</p> + +<p style="margin-left:17%;"><b>tar −x</b></p> + +<p style="margin-left:8%; margin-top: 1em">To examine the +contents of an ISO 9660 cdrom image:</p> + +<p style="margin-left:17%;"><b>tar −tf</b> +<i>image.iso</i></p> + +<p style="margin-left:8%; margin-top: 1em">To move file +hierarchies, invoke <b>tar</b> as</p> + +<p style="margin-left:17%;"><b>tar −cf</b> <i>-</i> +<b>−C</b> <i>srcdir .</i> | <b>tar −xpf</b> +<i>-</i> <b>−C</b> <i>destdir</i></p> + +<p style="margin-left:8%;">or more traditionally</p> + +<p style="margin-left:17%;">cd srcdir ; <b>tar +−cf</b> <i>- .</i> | (<i>cd destdir ;</i> <b>tar +−xpf</b> <i>-</i>)</p> + +<p style="margin-left:8%; margin-top: 1em">In create mode, +the list of files and directories to be archived can also +include directory change instructions of the form +<b>-C</b><i>foo/baz</i> and archive inclusions of the form +<b>@</b><i>archive-file</i>. For example, the command +line</p> + +<p style="margin-left:17%;"><b>tar −c −f</b> +<i>new.tar foo1</i> <b>@</b><i>old.tgz</i> <b>-C</b><i>/tmp +foo2</i></p> + +<p style="margin-left:8%;">will create a new archive +<i>new.tar</i>. <b>tar</b> will read the file <i>foo1</i> +from the current directory and add it to the output archive. +It will then read each entry from <i>old.tgz</i> and add +those entries to the output archive. Finally, it will switch +to the <i>/tmp</i> directory and add <i>foo2</i> to the +output archive.</p> + +<p style="margin-left:8%; margin-top: 1em">An input file in +mtree(5) format can be used to create an output archive with +arbitrary ownership, permissions, or names that differ from +existing data on disk:</p> + +<p style="margin-left:17%; margin-top: 1em">$ cat +input.mtree <br> +#mtree <br> +usr/bin uid=0 gid=0 mode=0755 type=dir <br> +usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls <br> +$ tar -cvf output.tar @input.mtree</p> + +<p style="margin-left:8%; margin-top: 1em">The +<b>−-newer</b> and <b>−-newer-mtime</b> 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’’.</p> + +<p style="margin-left:8%; margin-top: 1em">The +<b>−-options</b> argument can be used to control +various details of archive generation or reading. For +example, you can generate mtree output which only contains +<b>type</b>, <b>time</b>, and <b>uid</b> keywords:</p> + +<p style="margin-left:17%;"><b>tar −cf</b> +<i>file.tar</i> <b>−-format=mtree +−-options=’!all,type,time,uid’</b> +<i>dir</i></p> + +<p style="margin-left:8%;">or you can set the compression +level used by gzip or xz compression:</p> + +<p style="margin-left:17%;"><b>tar −czf</b> +<i>file.tar</i> +<b>−-options=’compression-level=9’</b>.</p> + +<p style="margin-left:8%;">For more details, see the +explanation of the <b>archive_read_set_options</b>() and +<b>archive_write_set_options</b>() API calls that are +described in archive_read(3) and archive_write(3).</p> + + +<p style="margin-top: 1em" valign="top"><b>COMPATIBILITY</b></p> + +<p style="margin-left:8%;">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,</p> + +<p style="margin-left:17%;"><b>tar tbf 32</b> +<i>file.tar</i></p> + +<p style="margin-left:8%;">specifies three flags <b>t</b>, +<b>b</b>, and <b>f</b>. The <b>b</b> and <b>f</b> flags both +require arguments, so there must be two additional items on +the command line. The <i>32</i> is the argument to the +<b>b</b> flag, and <i>file.tar</i> is the argument to the +<b>f</b> flag.</p> + +<p style="margin-left:8%; margin-top: 1em">The mode options +c, r, t, u, and x and the options b, f, l, m, o, v, and w +comply with SUSv2.</p> + +<p style="margin-left:8%; margin-top: 1em">For maximum +portability, scripts that invoke <b>tar</b> should use the +bundled-argument format above, should limit themselves to +the <b>c</b>, <b>t</b>, and <b>x</b> modes, and the +<b>b</b>, <b>f</b>, <b>m</b>, <b>v</b>, and <b>w</b> +options.</p> + +<p style="margin-left:8%; margin-top: 1em">Additional long +options are provided to improve compatibility with other tar +implementations.</p> + + +<p style="margin-top: 1em" valign="top"><b>SECURITY</b></p> + +<p style="margin-left:8%;">Certain security issues are +common to many archiving programs, including <b>tar</b>. In +particular, carefully-crafted archives can request that +<b>tar</b> 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 <b>tar</b> has +mechanisms to protect against each one, savvy users should +be aware of the implications:</p> + +<p style="margin-top: 1em" valign="top"><b>•</b></p> + +<p style="margin-left:20%;">Archive entries can have +absolute pathnames. By default, <b>tar</b> removes the +leading <i>/</i> character from filenames before restoring +them to guard against this problem.</p> + +<p style="margin-top: 1em" valign="top"><b>•</b></p> + +<p style="margin-left:20%;">Archive entries can have +pathnames that include <i>..</i> components. By default, +<b>tar</b> will not extract files containing <i>..</i> +components in their pathname.</p> + +<p style="margin-top: 1em" valign="top"><b>•</b></p> + +<p style="margin-left:20%;">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, <b>tar</b> 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 +<b>−U</b> is specified, any intermediate symlink will +also be unconditionally removed. If neither <b>−U</b> +nor <b>−P</b> is specified, <b>tar</b> will refuse to +extract the entry.</p> + +<p style="margin-left:8%;">To protect yourself, you should +be wary of any archives that come from untrusted sources. +You should examine the contents of an archive with</p> + +<p style="margin-left:17%;"><b>tar −tf</b> +<i>filename</i></p> + +<p style="margin-left:8%;">before extraction. You should +use the <b>−k</b> option to ensure that <b>tar</b> +will not overwrite any existing files or the <b>−U</b> +option to remove any pre-existing files. You should +generally not extract archives while running with super-user +privileges. Note that the <b>−P</b> option to +<b>tar</b> disables the security checks above and allows you +to extract an archive while preserving any absolute +pathnames, <i>..</i> components, or symlinks to other +directories.</p> + +<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> + +<p style="margin-left:8%;">bzip2(1), compress(1), cpio(1), +gzip(1), mt(1), pax(1), shar(1), libarchive(3), +libarchive-formats(5), tar(5)</p> + + +<p style="margin-top: 1em" valign="top"><b>STANDARDS</b></p> + +<p style="margin-left:8%;">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.</p> + +<p style="margin-left:8%; margin-top: 1em">The ustar and +pax interchange file formats are defined by IEEE Std +1003.1-2001 (‘‘POSIX.1’’) for the +pax command.</p> + +<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> + +<p style="margin-left:8%;">A <b>tar</b> 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 +<b>pdtar</b> 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.</p> + +<p style="margin-left:8%; margin-top: 1em">This is a +complete re-implementation based on the libarchive(3) +library.</p> + +<p style="margin-top: 1em" valign="top"><b>BUGS</b></p> + +<p style="margin-left:8%;">This program follows ISO/IEC +9945-1:1996 (‘‘POSIX.1’’) for the +definition of the <b>−l</b> option. Note that GNU tar +prior to version 1.15 treated <b>−l</b> as a synonym +for the <b>−-one-file-system</b> option.</p> + +<p style="margin-left:8%; margin-top: 1em">The +<b>−C</b> <i>dir</i> option may differ from historic +implementations.</p> + +<p style="margin-left:8%; margin-top: 1em">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 gzip(1) and bzip2(1), +complain about the null padding when decompressing an +archive created by <b>tar</b>, although they still extract +it correctly.</p> + +<p style="margin-left:8%; margin-top: 1em">The compression +and decompression is implemented internally, so there may be +insignificant differences between the compressed output +generated by</p> + +<p style="margin-left:17%;"><b>tar −czf</b> <i>- +file</i></p> + +<p style="margin-left:8%;">and that generated by</p> + +<p style="margin-left:17%;"><b>tar −cf</b> <i>- +file</i> | <b>gzip</b></p> + +<p style="margin-left:8%; margin-top: 1em">The default +should be to read and write archives to the standard I/O +paths, but tradition (and POSIX) dictates otherwise.</p> + +<p style="margin-left:8%; margin-top: 1em">The <b>r</b> and +<b>u</b> modes require that the archive be uncompressed and +located in a regular file on disk. Other archives can be +modified using <b>c</b> mode with the <i>@archive-file</i> +extension.</p> + +<p style="margin-left:8%; margin-top: 1em">To archive a +file called <i>@foo</i> or <i>-foo</i> you must specify it +as <i>./@foo</i> or <i>./-foo</i>, respectively.</p> + +<p style="margin-left:8%; margin-top: 1em">In create mode, +a leading <i>./</i> is always removed. A leading <i>/</i> is +stripped unless the <b>−P</b> option is specified.</p> + +<p style="margin-left:8%; margin-top: 1em">There needs to +be better support for file selection on both create and +extract.</p> + +<p style="margin-left:8%; margin-top: 1em">There is not yet +any support for multi-volume archives or for archiving +sparse files.</p> + +<p style="margin-left:8%; margin-top: 1em">Converting +between dissimilar archive formats (such as tar and cpio) +using the <b>@</b><i>-</i> convention can cause hard link +information to be lost. (This is a consequence of the +incompatible ways that different archive formats store +hardlink information.)</p> + +<p style="margin-left:8%; margin-top: 1em">There are +alternative long options for many of the short options that +are deliberately not documented.</p> + + +<p style="margin-left:8%; margin-top: 1em">FreeBSD 8.0 +Oct 12, 2009 FreeBSD 8.0</p> +<hr> +</body> +</html> |