1529 lines
49 KiB
HTML
1529 lines
49 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of TAR</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>TAR</H1>
|
|
Section: GNU TAR Manual (1)<BR>Updated: November 16, 2017<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
tar - an archiving utility
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H3>Traditional usage</H3>
|
|
|
|
<B>tar</B> {<B>A</B>|<B>c</B>|<B>d</B>|<B>r</B>|<B>t</B>|<B>u</B>|<B>x</B>}[<B>GnSkUWOmpsMBiajJzZhPlRvwo</B>] [<I>ARG</I>...]
|
|
<A NAME="lbAE"> </A>
|
|
<H3>UNIX-style usage</H3>
|
|
|
|
<P>
|
|
<B>tar</B> <B>-A</B> [<I>OPTIONS</I>] <I>ARCHIVE</I> <I>ARCHIVE</I>
|
|
<P>
|
|
<B>tar</B> <B>-c</B> [<B>-f</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>FILE</I>...]
|
|
<P>
|
|
<B>tar</B> <B>-d</B> [<B>-f</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>FILE</I>...]
|
|
<P>
|
|
<B>tar</B> <B>-t</B> [<B>-f</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>MEMBER</I>...]
|
|
<P>
|
|
<B>tar</B> <B>-r</B> [<B>-f</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>FILE</I>...]
|
|
<P>
|
|
<B>tar</B> <B>-u</B> [<B>-f</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>FILE</I>...]
|
|
<P>
|
|
<B>tar</B> <B>-x</B> [<B>-f</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>MEMBER</I>...]
|
|
<A NAME="lbAF"> </A>
|
|
<H3>GNU-style usage</H3>
|
|
|
|
<P>
|
|
<B>tar</B> {<B>--catenate</B>|<B>--concatenate</B>} [<I>OPTIONS</I>] <I>ARCHIVE</I> <I>ARCHIVE</I>
|
|
<P>
|
|
<B>tar</B> <B>--create</B> [<B>--file</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>FILE</I>...]
|
|
<P>
|
|
<B>tar</B> {<B>--diff</B>|<B>--compare</B>} [<B>--file</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>FILE</I>...]
|
|
<P>
|
|
<B>tar</B> <B>--delete</B> [<B>--file</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>MEMBER</I>...]
|
|
<P>
|
|
<B>tar</B> <B>--append</B> [<B>-f</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>FILE</I>...]
|
|
<P>
|
|
<B>tar</B> <B>--list</B> [<B>-f</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>MEMBER</I>...]
|
|
<P>
|
|
<B>tar</B> <B>--test-label</B> [<B>--file</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>LABEL</I>...]
|
|
<P>
|
|
<B>tar</B> <B>--update</B> [<B>--file</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>FILE</I>...]
|
|
<P>
|
|
<B>tar</B> <B>--update</B> [<B>-f</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>FILE</I>...]
|
|
<P>
|
|
<B>tar</B> {<B>--extract</B>|<B>--get</B>} [<B>-f</B> <I>ARCHIVE</I>] [<I>OPTIONS</I>] [<I>MEMBER</I>...]
|
|
<A NAME="lbAG"> </A>
|
|
<H2>NOTE</H2>
|
|
|
|
This manpage is a short description of GNU <B>tar</B>. For a detailed
|
|
discussion, including examples and usage recommendations, refer to the
|
|
<B>GNU Tar Manual</B> available in texinfo format. If the <B>info</B>
|
|
reader and the tar documentation are properly installed on your
|
|
system, the command
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="1"><DD>
|
|
<B>info tar</B>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
should give you access to the complete manual.
|
|
<P>
|
|
|
|
You can also view the manual using the info mode in
|
|
<B><A HREF="/cgi-bin/man/man2html?1+emacs">emacs</A></B>(1),
|
|
|
|
or find it in various formats online at
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="2"><DD>
|
|
<B><A HREF="http://www.gnu.org/software/tar/manual">http://www.gnu.org/software/tar/manual</A></B>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
If any discrepancies occur between this manpage and the
|
|
<B>GNU Tar Manual</B>, the later shall be considered the authoritative
|
|
source.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
GNU
|
|
<B>tar</B>
|
|
|
|
is an archiving program designed to store multiple files in a single
|
|
file (an <B>archive</B>), and to manipulate such archives. The archive
|
|
can be either a regular file or a device (e.g. a tape drive, hence the name
|
|
of the program, which stands for <B>t</B>ape <B>ar</B>chiver), which can
|
|
be located either on the local or on a remote machine.
|
|
<P>
|
|
|
|
<P>
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Option styles</H3>
|
|
|
|
Options to GNU <B>tar</B> can be given in three different styles.
|
|
In
|
|
<B>traditional style</B>,
|
|
|
|
the first argument is a cluster of option letters and all subsequent
|
|
arguments supply arguments to those options that require them. The
|
|
arguments are read in the same order as the option letters. Any
|
|
command line words that remain after all options has been processed
|
|
are treated as non-optional arguments: file or archive member names.
|
|
<P>
|
|
|
|
For example, the <B>c</B> option requires creating the archive, the
|
|
<B>v</B> option requests the verbose operation, and the <B>f</B> option
|
|
takes an argument that sets the name of the archive to operate upon.
|
|
The following command, written in the traditional style, instructs tar
|
|
to store all files from the directory
|
|
<B>/etc</B>
|
|
|
|
into the archive file
|
|
<B>etc.tar</B>
|
|
|
|
verbosely listing the files being archived:
|
|
<P>
|
|
|
|
|
|
<B>tar cfv a.tar /etc</B>
|
|
|
|
|
|
<P>
|
|
|
|
In
|
|
<B>UNIX </B>or<B> short-option style</B>,
|
|
|
|
each option letter is prefixed with a single dash, as in other command
|
|
line utilities. If an option takes argument, the argument follows it,
|
|
either as a separate command line word, or immediately following the
|
|
option. However, if the option takes an <B>optional</B> argument, the
|
|
argument must follow the option letter without any intervening
|
|
whitespace, as in <B>-g/tmp/snar.db</B>.
|
|
<P>
|
|
|
|
Any number of options not taking arguments can be
|
|
clustered together after a single dash, e.g. <B>-vkp</B>. Options
|
|
that take arguments (whether mandatory or optional), can appear at
|
|
the end of such a cluster, e.g. <B>-vkpf a.tar</B>.
|
|
<P>
|
|
|
|
The example command above written in the
|
|
<B>short-option style</B>
|
|
|
|
could look like:
|
|
<P>
|
|
|
|
|
|
<B>tar -cvf a.tar /etc</B>
|
|
|
|
or
|
|
<B>tar -c -v -f a.tar /etc</B>
|
|
|
|
|
|
<P>
|
|
|
|
In
|
|
<B>GNU </B>or<B> long-option style</B>,
|
|
|
|
each option begins with two dashes and has a meaningful name,
|
|
consisting of lower-case letters and dashes. When used, the long
|
|
option can be abbreviated to its initial letters, provided that
|
|
this does not create ambiguity. Arguments to long options are
|
|
supplied either as a separate command line word, immediately following
|
|
the option, or separated from the option by an equals sign with no
|
|
intervening whitespace. Optional arguments must always use the latter
|
|
method.
|
|
<P>
|
|
|
|
Here are several ways of writing the example command in this style:
|
|
<P>
|
|
|
|
|
|
<B>tar --create --file a.tar --verbose /etc</B>
|
|
|
|
|
|
or (abbreviating some options):
|
|
|
|
<B>tar --cre --file=a.tar --verb /etc</B>
|
|
|
|
|
|
<P>
|
|
|
|
The options in all three styles can be intermixed, although doing so
|
|
with old options is not encouraged.
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Operation mode</H3>
|
|
|
|
The options listed in the table below tell GNU <B>tar</B> what
|
|
operation it is to perform. Exactly one of them must be given.
|
|
Meaning of non-optional arguments depends on the operation mode
|
|
requested.
|
|
<DL COMPACT>
|
|
<DT id="3"><B>-A</B>, <B>--catenate</B>, <B>--concatenate</B><DD>
|
|
Append archive to the end of another archive. The arguments are
|
|
treated as the names of archives to append. All archives must be of
|
|
the same format as the archive they are appended to, otherwise the
|
|
resulting archive might be unusable with non-GNU implementations of
|
|
<B>tar</B>. Notice also that when more than one archive is given, the
|
|
members from archives other than the first one will be accessible in
|
|
the resulting archive only if using the <B>-i</B>
|
|
(<B>--ignore-zeros</B>) option.
|
|
<P>
|
|
Compressed archives cannot be concatenated.
|
|
<DT id="4"><B>-c</B>, <B>--create</B><DD>
|
|
Create a new archive. Arguments supply the names of the files to be
|
|
archived. Directories are archived recursively, unless the
|
|
<B>--no-recursion</B> option is given.
|
|
<DT id="5"><B>-d</B>, <B>--diff</B>, <B>--compare</B><DD>
|
|
Find differences between archive and file system. The arguments are
|
|
optional and specify archive members to compare. If not given, the
|
|
current working directory is assumed.
|
|
<DT id="6"><B>--delete</B><DD>
|
|
Delete from the archive. The arguments supply names of the archive
|
|
members to be removed. At least one argument must be given.
|
|
<P>
|
|
This option does not operate on compressed archives. There is no
|
|
short option equivalent.
|
|
<DT id="7"><B>-r</B>, <B>--append</B><DD>
|
|
Append files to the end of an archive. Arguments have the same
|
|
meaning as for <B>-c</B> (<B>--create</B>).
|
|
<DT id="8"><B>-t</B>, <B>--list</B><DD>
|
|
List the contents of an archive. Arguments are optional. When given,
|
|
they specify the names of the members to list.
|
|
<DT id="9"><B>--test-label<DD>
|
|
Test the archive volume label and exit. When used without arguments,
|
|
it prints the volume label (if any) and exits with status 0</B>.
|
|
When one or more command line arguments are given.
|
|
<B>tar</B>
|
|
|
|
compares the volume label with each argument. It exits with code
|
|
<B>0</B> if a match is found, and with code <B>1</B> otherwise. No
|
|
output is displayed, unless used together with the <B>-v</B>
|
|
(<B>--verbose</B>) option.
|
|
<P>
|
|
There is no short option equivalent for this option.
|
|
<DT id="10"><B>-u</B>, <B>--update</B><DD>
|
|
Append files which are newer than the corresponding copy in the
|
|
archive. Arguments have the same meaning as with <B>-c</B> and
|
|
<B>-r</B> options. Notice, that newer files don't replace their
|
|
old archive copies, but instead are appended to the end of archive.
|
|
The resulting archive can thus contain several members of the
|
|
same name, corresponding to various versions of the same file.
|
|
<DT id="11"><B>-x</B>, <B>--extract</B>, <B>--get</B><DD>
|
|
Extract files from an archive. Arguments are optional. When given,
|
|
they specify names of the archive members to be extracted.
|
|
<DT id="12"><DT><B>--show-defaults</B><DD>
|
|
<DD>
|
|
Show built-in defaults for various <B>tar</B> options and exit. No
|
|
arguments are allowed.
|
|
<DT id="13"><B>-?</B>, <B>--help<DD>
|
|
Display a short option summary and exit. No arguments allowed.
|
|
<DT id="14">--usage</B><DD>
|
|
Display a list of available options and exit. No arguments allowed.
|
|
<DT id="15"><B>--version</B><DD>
|
|
Print program version and copyright information and exit.
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Operation modifiers</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="16"><B>--check-device</B><DD>
|
|
Check device numbers when creating incremental archives (default).
|
|
<DT id="17"><B>-g</B>, <B>--listed-incremental</B>=<I>FILE</I><DD>
|
|
Handle new GNU-format incremental backups. <I>FILE</I> is the name of
|
|
a <B>snapshot file</B>, where tar stores additional information which
|
|
is used to decide which files changed since the previous incremental
|
|
dump and, consequently, must be dumped again. If <I>FILE</I> does not
|
|
exist when creating an archive, it will be created and all files will
|
|
be added to the resulting archive (the <B>level 0</B> dump). To create
|
|
incremental archives of non-zero level <B>N</B>, create a copy of the
|
|
snapshot file created during the level <B>N-1</B>, and use it as
|
|
<I>FILE</I>.
|
|
<P>
|
|
When listing or extracting, the actual contents of <I>FILE</I> is not
|
|
inspected, it is needed only due to syntactical requirements. It is
|
|
therefore common practice to use <B>/dev/null</B> in its place.
|
|
<DT id="18"><B>--hole-detection</B>=<I>METHOD</I><DD>
|
|
Use <I>METHOD</I> to detect holes in sparse files. This option implies
|
|
<B>--sparse</B>. Valid values for <I>METHOD</I> are <B>seek</B> and
|
|
<B>raw</B>. Default is <B>seek</B> with fallback to <B>raw</B> when not
|
|
applicable.
|
|
<DT id="19"><B>-G</B>, <B>--incremental</B><DD>
|
|
Handle old GNU-format incremental backups.
|
|
<DT id="20"><B>--ignore-failed-read</B><DD>
|
|
Do not exit with nonzero on unreadable files.
|
|
<DT id="21"><B>--level</B>=<I>NUMBER</I><DD>
|
|
Set dump level for created listed-incremental archive. Currently only
|
|
<B>--level=0</B> is meaningful: it instructs <B>tar</B> to truncate
|
|
the snapshot file before dumping, thereby forcing a level 0 dump.
|
|
<DT id="22"><B>-n</B>, <B>--seek</B><DD>
|
|
Assume the archive is seekable. Normally <B>tar</B> determines
|
|
automatically whether the archive can be seeked or not. This option
|
|
is intended for use in cases when such recognition fails. It takes
|
|
effect only if the archive is open for reading (e.g. with
|
|
<B>--list</B>
|
|
|
|
or
|
|
<B>--extract</B>
|
|
|
|
options).<TT> </TT><TT> </TT> <BR>
|
|
<DT id="23"><B>--no-check-device</B><DD>
|
|
Do not check device numbers when creating incremental archives.
|
|
<DT id="24"><B>--no-seek</B><DD>
|
|
Assume the archive is not seekable.
|
|
<DT id="25"><B>--occurrence</B>[=<I>N</I>]<DD>
|
|
Process only the <I>N</I>th occurrence of each file in the
|
|
archive. This option is valid only when used with one of the
|
|
following subcommands: <B>--delete</B>, <B>--diff</B>,
|
|
<B>--extract</B> or <B>--list</B> and when a list of files is given
|
|
either on the command line or via the <B>-T</B> option. The default
|
|
<I>N</I> is <B>1</B>.
|
|
<DT id="26"><B>--restrict</B><DD>
|
|
Disable the use of some potentially harmful options.
|
|
<DT id="27"><B>--sparse-version</B>=<I>MAJOR</I>[.<I>MINOR</I>]<DD>
|
|
Set version of the sparse format to use (implies <B>--sparse</B>).
|
|
This option implies
|
|
<B>--sparse</B>.
|
|
|
|
Valid argument values are
|
|
<B>0.0</B>,
|
|
|
|
<B>0.1</B>, and
|
|
|
|
<B>1.0</B>.
|
|
|
|
For a detailed discussion of sparse formats, refer to the <B>GNU Tar
|
|
Manual</B>, appendix <B>D</B>, "<B>Sparse Formats</B>". Using <B>info</B>
|
|
reader, it can be accessed running the following command:
|
|
<B>info tar 'Sparse Formats'</B>.
|
|
|
|
<DT id="28"><B>-S</B>, <B>--sparse</B><DD>
|
|
Handle sparse files efficiently. Some files in the file system may
|
|
have segments which were actually never written (quite often these are
|
|
database files created by such systems as <B>DBM</B>). When given this
|
|
option, <B>tar</B> attempts to determine if the file is sparse prior to
|
|
archiving it, and if so, to reduce the resulting archive size by not
|
|
dumping empty parts of the file.
|
|
</DL>
|
|
<A NAME="lbAM"> </A>
|
|
<H3>Overwrite control</H3>
|
|
|
|
These options control <B>tar</B> actions when extracting a file over
|
|
an existing copy on disk.
|
|
<DL COMPACT>
|
|
<DT id="29"><B>-k</B>, <B>--keep-old-files</B><DD>
|
|
Don't replace existing files when extracting.
|
|
<DT id="30"><B>--keep-newer-files</B><DD>
|
|
Don't replace existing files that are newer than their archive copies.
|
|
<DT id="31"><B>--keep-directory-symlink</B><DD>
|
|
Don't replace existing symlinks to directories when extracting.
|
|
<DT id="32"><B>--no-overwrite-dir</B><DD>
|
|
Preserve metadata of existing directories.
|
|
<DT id="33"><B>--one-top-level</B>[<B>=</B><I>DIR</I>]<DD>
|
|
Extract all files into <I>DIR</I>, or, if used without argument, into a
|
|
subdirectory named by the base name of the archive (minus standard
|
|
compression suffixes recognizable by <B>--auto-compress).
|
|
<DT id="34">--overwrite</B><DD>
|
|
Overwrite existing files when extracting.
|
|
<DT id="35"><B>--overwrite-dir</B><DD>
|
|
Overwrite metadata of existing directories when extracting (default).
|
|
<DT id="36"><B>--recursive-unlink</B><DD>
|
|
Recursively remove all files in the directory prior to extracting it.
|
|
<DT id="37"><B>--remove-files</B><DD>
|
|
Remove files from disk after adding them to the archive.
|
|
<DT id="38"><B>--skip-old-files<DD>
|
|
Don't replace existing files when extracting, silently skip over them.
|
|
<DT id="39">-U</B>, <B>--unlink-first</B><DD>
|
|
Remove each file prior to extracting over it.
|
|
<DT id="40"><B>-W</B>, <B>--verify</B><DD>
|
|
Verify the archive after writing it.
|
|
</DL>
|
|
<A NAME="lbAN"> </A>
|
|
<H3>Output stream selection</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="41"><B>--ignore-command-error</B><DD>
|
|
<DT id="42">Ignore subprocess exit codes.<DD>
|
|
<DT id="43"><B>--no-ignore-command-error</B><DD>
|
|
Treat non-zero exit codes of children as error (default).
|
|
<DT id="44"><B>-O</B>, <B>--to-stdout</B><DD>
|
|
Extract files to standard output.
|
|
<DT id="45"><B>--to-command</B>=<I>COMMAND</I><DD>
|
|
Pipe extracted files to <I>COMMAND</I>. The argument is the pathname
|
|
of an external program, optionally with command line arguments. The
|
|
program will be invoked and the contents of the file being extracted
|
|
supplied to it on its standard output. Additional data will be
|
|
supplied via the following environment variables:
|
|
<DL COMPACT><DT id="46"><DD>
|
|
<DL COMPACT>
|
|
<DT id="47"><B>TAR_FILETYPE</B>
|
|
|
|
<DD>
|
|
Type of the file. It is a single letter with the following meaning:
|
|
<P>
|
|
<PRE>
|
|
|
|
f Regular file
|
|
d Directory
|
|
l Symbolic link
|
|
h Hard link
|
|
b Block device
|
|
c Character device
|
|
</PRE>
|
|
|
|
<P>
|
|
Currently only regular files are supported.
|
|
<DT id="48"><B>TAR_MODE</B>
|
|
|
|
<DD>
|
|
File mode, an octal number.
|
|
<DT id="49"><B>TAR_FILENAME</B>
|
|
|
|
<DD>
|
|
The name of the file.
|
|
<DT id="50"><B>TAR_REALNAME</B>
|
|
|
|
<DD>
|
|
Name of the file as stored in the archive.
|
|
<DT id="51"><B>TAR_UNAME</B>
|
|
|
|
<DD>
|
|
Name of the file owner.
|
|
<DT id="52"><B>TAR_GNAME</B>
|
|
|
|
<DD>
|
|
Name of the file owner group.
|
|
<DT id="53"><B>TAR_ATIME</B>
|
|
|
|
<DD>
|
|
Time of last access. It is a decimal number, representing seconds
|
|
since the Epoch. If the archive provides times with nanosecond
|
|
precision, the nanoseconds are appended to the timestamp after a
|
|
decimal point.
|
|
<DT id="54"><B>TAR_MTIME</B>
|
|
|
|
<DD>
|
|
Time of last modification.
|
|
<DT id="55"><B>TAR_CTIME</B>
|
|
|
|
<DD>
|
|
Time of last status change.
|
|
<DT id="56"><B>TAR_SIZE</B>
|
|
|
|
<DD>
|
|
Size of the file.
|
|
<DT id="57"><B>TAR_UID</B>
|
|
|
|
<DD>
|
|
UID of the file owner.
|
|
<DT id="58"><B>TAR_GID</B>
|
|
|
|
<DD>
|
|
GID of the file owner.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="59"><DD>
|
|
<P>
|
|
Additionally, the following variables contain information about
|
|
<B>tar</B> operation mode and the archive being processed:
|
|
<DL COMPACT>
|
|
<DT id="60"><B>TAR_VERSION</B>
|
|
|
|
<DD>
|
|
GNU <B>tar</B> version number.
|
|
<DT id="61"><B>TAR_ARCHIVE</B>
|
|
|
|
<DD>
|
|
The name of the archive <B>tar</B> is processing.
|
|
<DT id="62"><B>TAR_BLOCKING_FACTOR</B>
|
|
|
|
<DD>
|
|
Current blocking factor, i.e. number of 512-byte blocks in a record.
|
|
<DT id="63"><B>TAR_VOLUME</B>
|
|
|
|
<DD>
|
|
Ordinal number of the volume <B>tar</B> is processing (set if
|
|
reading a multi-volume archive).
|
|
<DT id="64"><B>TAR_FORMAT</B>
|
|
|
|
<DD>
|
|
Format of the archive being processed. One of:
|
|
<B>gnu</B>,
|
|
|
|
<B>oldgnu</B>,
|
|
|
|
<B>posix</B>,
|
|
|
|
<B>ustar</B>,
|
|
|
|
<B>v7</B>.
|
|
|
|
<B>TAR_SUBCOMMAND</B>
|
|
|
|
A short option (with a leading dash) describing the operation <B>tar</B> is
|
|
executing.
|
|
</DL>
|
|
</DL>
|
|
|
|
</DL>
|
|
<A NAME="lbAO"> </A>
|
|
<H3>Handling of file attributes</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="65"><B>--atime-preserve</B>[=<I>METHOD</I>]<DD>
|
|
Preserve access times on dumped files, either by restoring the times
|
|
after reading (<I>METHOD</I>=<B>replace</B>, this is the default) or by
|
|
not setting the times in the first place (<I>METHOD</I>=<B>system</B>)
|
|
<DT id="66"><B>--delay-directory-restore</B><DD>
|
|
Delay setting modification times and permissions of extracted
|
|
directories until the end of extraction. Use this option when
|
|
extracting from an archive which has unusual member ordering.
|
|
<DT id="67"><B>--group</B>=<I>NAME</I>[:<I>GID</I>]<DD>
|
|
Force <I>NAME</I> as group for added files. If <I>GID</I> is not
|
|
supplied, <I>NAME</I> can be either a user name or numeric GID. In
|
|
this case the missing part (GID or name) will be inferred from the
|
|
current host's group database.
|
|
<P>
|
|
When used with <B>--group-map</B>=<I>FILE</I>, affects only those
|
|
files whose owner group is not listed in <I>FILE</I>.
|
|
<DT id="68"><B>--group-map</B>=<I>FILE</I><DD>
|
|
Read group translation map from <I>FILE</I>. Empty lines are ignored.
|
|
Comments are introduced with <B>#</B> sign and extend to the end of line.
|
|
Each non-empty line in <I>FILE</I> defines translation for a single
|
|
group. It must consist of two fields, delimited by any amount of whitespace:
|
|
<P>
|
|
|
|
<I>OLDGRP</I> <I>NEWGRP</I>[<B>:</B><I>NEWGID</I>]
|
|
|
|
<P>
|
|
<I>OLDGRP</I> is either a valid group name or a GID prefixed with
|
|
<B>+</B>. Unless <I>NEWGID</I> is supplied, <I>NEWGRP</I> must also be
|
|
either a valid group name or a <B>+</B><I>GID</I>. Otherwise, both
|
|
<I>NEWGRP</I> and <I>NEWGID</I> need not be listed in the system group
|
|
database.
|
|
<P>
|
|
As a result, each input file with owner group <I>OLDGRP</I> will be
|
|
stored in archive with owner group <I>NEWGRP</I> and GID <I>NEWGID</I>.
|
|
<DT id="69"><B>--mode</B>=<I>CHANGES</I><DD>
|
|
Force symbolic mode <I>CHANGES</I> for added files.
|
|
<DT id="70"><B>--mtime</B>=<I>DATE-OR-FILE</I><DD>
|
|
Set mtime for added files. <I>DATE-OR-FILE</I> is either a date/time
|
|
in almost arbitrary format, or the name of an existing file. In the
|
|
latter case the mtime of that file will be used.
|
|
<DT id="71"><B>-m</B>, <B>--touch</B><DD>
|
|
Don't extract file modified time.
|
|
<DT id="72"><B>--no-delay-directory-restore</B><DD>
|
|
Cancel the effect of the prior <B>--delay-directory-restore</B> option.
|
|
<DT id="73"><B>--no-same-owner</B><DD>
|
|
Extract files as yourself (default for ordinary users).
|
|
<DT id="74"><B>--no-same-permissions</B><DD>
|
|
Apply the user's umask when extracting permissions from the archive
|
|
(default for ordinary users).
|
|
<DT id="75"><B>--numeric-owner</B><DD>
|
|
Always use numbers for user/group names.
|
|
<DT id="76"><B>--owner</B>=<I>NAME</I>[:<I>UID</I>]<DD>
|
|
Force <I>NAME</I> as owner for added files. If <I>UID</I> is not
|
|
supplied, <I>NAME</I> can be either a user name or numeric UID. In
|
|
this case the missing part (UID or name) will be inferred from the
|
|
current host's user database.
|
|
<P>
|
|
When used with <B>--owner-map</B>=<I>FILE</I>, affects only those
|
|
files whose owner is not listed in <I>FILE</I>.
|
|
<DT id="77"><B>--owner-map</B>=<I>FILE</I><DD>
|
|
Read owner translation map from <I>FILE</I>. Empty lines are ignored.
|
|
Comments are introduced with <B>#</B> sign and extend to the end of line.
|
|
Each non-empty line in <I>FILE</I> defines translation for a single
|
|
UID. It must consist of two fields, delimited by any amount of whitespace:
|
|
<P>
|
|
|
|
<I>OLDUSR</I> <I>NEWUSR</I>[<B>:</B><I>NEWUID</I>]
|
|
|
|
<P>
|
|
<I>OLDUSR</I> is either a valid user name or a UID prefixed with
|
|
<B>+</B>. Unless <I>NEWUID</I> is supplied, <I>NEWUSR</I> must also be
|
|
either a valid user name or a <B>+</B><I>UID</I>. Otherwise, both
|
|
<I>NEWUSR</I> and <I>NEWUID</I> need not be listed in the system user
|
|
database.
|
|
<P>
|
|
As a result, each input file owned by <I>OLDUSR</I> will be
|
|
stored in archive with owner name <I>NEWUSR</I> and UID <I>NEWUID</I>.
|
|
<DT id="78"><B>-p</B>, <B>--preserve-permissions</B>, <B>--same-permissions</B><DD>
|
|
extract information about file permissions (default for superuser)
|
|
<DT id="79"><B>--preserve</B><DD>
|
|
Same as both <B>-p</B> and <B>-s</B>.
|
|
<DT id="80"><B>--same-owner</B><DD>
|
|
Try extracting files with the same ownership as exists in the archive
|
|
(default for superuser).
|
|
<DT id="81"><B>-s</B>, <B>--preserve-order</B>, <B>--same-order</B><DD>
|
|
Sort names to extract to match archive
|
|
<DT id="82"><B>--sort=</B><I>ORDER</I><DD>
|
|
When creating an archive, sort directory entries according to
|
|
<I>ORDER</I>, which is one of
|
|
<B>none</B>,
|
|
|
|
<B>name</B>, or
|
|
|
|
<B>inode</B>.
|
|
|
|
<P>
|
|
The default is <B>--sort=none</B>, which stores archive members in
|
|
the same order as returned by the operating system.
|
|
<P>
|
|
Using <B>--sort=name</B> ensures the member ordering in the created archive
|
|
is uniform and reproducible.
|
|
<P>
|
|
Using <B>--sort=inode</B> reduces the number of disk seeks made when
|
|
creating the archive and thus can considerably speed up archivation.
|
|
This sorting order is supported only if the underlying system provides
|
|
the necessary information.
|
|
</DL>
|
|
<A NAME="lbAP"> </A>
|
|
<H3>Extended file attributes</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="83"><B>--acls</B>
|
|
|
|
<DD>
|
|
Enable POSIX ACLs support.
|
|
<DT id="84"><B>--no-acls</B>
|
|
|
|
<DD>
|
|
Disable POSIX ACLs support.
|
|
<DT id="85"><B>--selinux</B>
|
|
|
|
<DD>
|
|
Enable SELinux context support.
|
|
<DT id="86"><B>--no-selinux</B>
|
|
|
|
<DD>
|
|
Disable SELinux context support.
|
|
<DT id="87"><B>--xattrs</B>
|
|
|
|
<DD>
|
|
Enable extended attributes support.
|
|
<DT id="88"><B>--no-xattrs</B>
|
|
|
|
<DD>
|
|
Disable extended attributes support.
|
|
<DT id="89"><B>--xattrs-exclude=</B><I>PATTERN</I>
|
|
|
|
<DD>
|
|
Specify the exclude pattern for xattr keys. <I>PATTERN</I> is a POSIX
|
|
regular expression, e.g. <B>--xattrs-exclude='^user.'</B>, to exclude
|
|
attributes from the user namespace.
|
|
<DT id="90"><B>--xattrs-include=</B><I>PATTERN</I>
|
|
|
|
<DD>
|
|
Specify the include pattern for xattr keys. <I>PATTERN</I> is a POSIX
|
|
regular expression.
|
|
</DL>
|
|
<A NAME="lbAQ"> </A>
|
|
<H3>Device selection and switching</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="91"><B>-f</B>, <B>--file</B>=<I>ARCHIVE</I><DD>
|
|
Use archive file or device <I>ARCHIVE</I>. If this option is not
|
|
given, <B>tar</B> will first examine the environment variable `TAPE'.
|
|
If it is set, its value will be used as the archive name. Otherwise,
|
|
<B>tar</B> will assume the compiled-in default. The default
|
|
value can be inspected either using the
|
|
<B>--show-defaults</B>
|
|
|
|
option, or at the end of the <B>tar --help</B> output.
|
|
<P>
|
|
An archive name that has a colon in it specifies a file or device on a
|
|
remote machine. The part before the colon is taken as the machine
|
|
name or IP address, and the part after it as the file or device
|
|
pathname, e.g.:
|
|
<P>
|
|
|
|
--file=remotehost:/dev/sr0
|
|
|
|
<P>
|
|
An optional username can be prefixed to the hostname, placing a <B>@</B>
|
|
sign between them.
|
|
<P>
|
|
By default, the remote host is accessed via the
|
|
<B><A HREF="/cgi-bin/man/man2html?1+rsh">rsh</A></B>(1)
|
|
|
|
command. Nowadays it is common to use
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ssh">ssh</A></B>(1)
|
|
|
|
instead. You can do so by giving the following command line option:
|
|
<P>
|
|
|
|
--rsh-command=/usr/bin/ssh
|
|
|
|
<P>
|
|
The remote machine should have the
|
|
<B><A HREF="/cgi-bin/man/man2html?8+rmt">rmt</A></B>(8)
|
|
|
|
command installed. If its pathname does not match <B>tar</B>'s
|
|
default, you can inform <B>tar</B> about the correct pathname using the
|
|
<B>--rmt-command</B>
|
|
|
|
option.
|
|
<DT id="92"><B>--force-local</B><DD>
|
|
Archive file is local even if it has a colon.
|
|
<DT id="93"><B>-F</B>, <B>--info-script</B>=<I>COMMAND</I>, <B>--new-volume-script</B>=<I>COMMAND</I><DD>
|
|
Run <I>COMMAND</I> at the end of each tape (implies <B>-M</B>). The
|
|
command can include arguments. When started, it will inherit <B>tar</B>'s
|
|
environment plus the following variables:
|
|
<DL COMPACT><DT id="94"><DD>
|
|
<DL COMPACT>
|
|
<DT id="95"><B>TAR_VERSION</B>
|
|
|
|
<DD>
|
|
GNU <B>tar</B> version number.
|
|
<DT id="96"><B>TAR_ARCHIVE</B>
|
|
|
|
<DD>
|
|
The name of the archive <B>tar</B> is processing.
|
|
<DT id="97"><B>TAR_BLOCKING_FACTOR</B>
|
|
|
|
<DD>
|
|
Current blocking factor, i.e. number of 512-byte blocks in a record.
|
|
<DT id="98"><B>TAR_VOLUME</B>
|
|
|
|
<DD>
|
|
Ordinal number of the volume <B>tar</B> is processing (set if
|
|
reading a multi-volume archive).
|
|
<DT id="99"><B>TAR_FORMAT</B>
|
|
|
|
<DD>
|
|
Format of the archive being processed. One of:
|
|
<B>gnu</B>,
|
|
|
|
<B>oldgnu</B>,
|
|
|
|
<B>posix</B>,
|
|
|
|
<B>ustar</B>,
|
|
|
|
<B>v7</B>.
|
|
|
|
<DT id="100"><B>TAR_SUBCOMMAND</B>
|
|
|
|
<DD>
|
|
A short option (with a leading dash) describing the operation <B>tar</B> is
|
|
executing.
|
|
<DT id="101"><B>TAR_FD</B>
|
|
|
|
<DD>
|
|
File descriptor which can be used to communicate the new volume name
|
|
to
|
|
<B>tar</B>.
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="102"><DD>
|
|
<P>
|
|
If the info script fails, <B>tar</B> exits; otherwise, it begins writing
|
|
the next volume.
|
|
</DL>
|
|
|
|
<DT id="103"><B>-L</B>, <B>--tape-length</B>=<I>N</I><DD>
|
|
Change tape after writing <I>N</I>x1024 bytes. If <I>N</I> is followed
|
|
by a size suffix (see the subsection
|
|
<B>Size suffixes</B>
|
|
|
|
below), the suffix specifies the multiplicative factor to be used
|
|
instead of 1024.
|
|
<P>
|
|
This option implies
|
|
<B>-M</B>.
|
|
|
|
<DT id="104"><B>-M</B>, <B>--multi-volume</B><DD>
|
|
Create/list/extract multi-volume archive.
|
|
<DT id="105"><B>--rmt-command</B>=<I>COMMAND</I><DD>
|
|
Use <I>COMMAND</I> instead of <B>rmt</B> when accessing remote
|
|
archives. See the description of the
|
|
<B>-f</B>
|
|
|
|
option, above.
|
|
<DT id="106"><B>--rsh-command</B>=<I>COMMAND</I><DD>
|
|
Use <I>COMMAND</I> instead of <B>rsh</B> when accessing remote
|
|
archives. See the description of the
|
|
<B>-f</B>
|
|
|
|
option, above.
|
|
<DT id="107"><B>--volno-file</B>=<I>FILE</I><DD>
|
|
When this option is used in conjunction with
|
|
<B>--multi-volume</B>,
|
|
|
|
<B>tar</B>
|
|
|
|
will keep track of which volume of a multi-volume archive it is
|
|
working in <I>FILE</I>.
|
|
</DL>
|
|
<A NAME="lbAR"> </A>
|
|
<H3>Device blocking</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="108"><B>-b</B>, <B>--blocking-factor</B>=<I>BLOCKS</I><DD>
|
|
Set record size to <I>BLOCKS</I>x<B>512</B> bytes.
|
|
<DT id="109"><B>-B</B>, <B>--read-full-records</B><DD>
|
|
When listing or extracting, accept incomplete input records after
|
|
end-of-file marker.
|
|
<DT id="110"><B>-i</B>, <B>--ignore-zeros</B><DD>
|
|
Ignore zeroed blocks in archive. Normally two consecutive 512-blocks
|
|
filled with zeroes mean EOF and tar stops reading after encountering
|
|
them. This option instructs it to read further and is useful when
|
|
reading archives created with the <B>-A</B> option.
|
|
<DT id="111"><B>--record-size</B>=<I>NUMBER</I><DD>
|
|
Set record size. <I>NUMBER</I> is the number of bytes per record. It
|
|
must be multiple of <B>512</B>. It can can be suffixed with a <B>size
|
|
suffix</B>, e.g. <B>--record-size=10K</B>, for 10 Kilobytes. See the
|
|
subsection
|
|
<B>Size suffixes</B>,
|
|
|
|
for a list of valid suffixes.
|
|
</DL>
|
|
<A NAME="lbAS"> </A>
|
|
<H3>Archive format selection</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="112"><B>-H</B>, <B>--format</B>=<I>FORMAT</I><DD>
|
|
Create archive of the given format. Valid formats are:
|
|
<DL COMPACT><DT id="113"><DD>
|
|
<DL COMPACT>
|
|
<DT id="114"><B>gnu</B>
|
|
|
|
<DD>
|
|
GNU tar 1.13.x format
|
|
<DT id="115"><B>oldgnu</B>
|
|
|
|
<DD>
|
|
GNU format as per tar <= 1.12.
|
|
<DT id="116"><B>pax</B>, <B>posix</B><DD>
|
|
POSIX 1003.1-2001 (pax) format.
|
|
<DT id="117"><B>ustar</B>
|
|
|
|
<DD>
|
|
POSIX 1003.1-1988 (ustar) format.
|
|
<DT id="118"><B>v7</B>
|
|
|
|
<DD>
|
|
Old V7 tar format.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="119"><B>--old-archive</B>, <B>--portability</B><DD>
|
|
Same as <B>--format=v7</B>.
|
|
<DT id="120"><B>--pax-option</B>=<I>keyword</I>[[:]=<I>value</I>][,<I>keyword</I>[[:]=<I>value</I>]]...<DD>
|
|
Control pax keywords when creating <B>PAX</B> archives (<B>-H
|
|
pax</B>). This option is equivalent to the <B>-o</B> option of the
|
|
<B><A HREF="/cgi-bin/man/man2html?1+pax">pax</A></B>(1)<B>utility.</B>
|
|
|
|
<DT id="121"><B>--posix</B><DD>
|
|
Same as <B>--format=posix</B>.
|
|
<DT id="122"><B>-V</B>, <B>--label</B>=<I>TEXT</I><DD>
|
|
Create archive with volume name <I>TEXT</I>. If listing or extracting,
|
|
use <I>TEXT</I> as a globbing pattern for volume name.
|
|
</DL>
|
|
<A NAME="lbAT"> </A>
|
|
<H3>Compression options</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="123"><B>-a</B>, <B>--auto-compress</B><DD>
|
|
Use archive suffix to determine the compression program.
|
|
<DT id="124"><B>-I</B>, <B>--use-compress-program</B><I>=COMMAND</I><DD>
|
|
Filter data through <I>COMMAND</I>. It must accept the <B>-d</B>
|
|
option, for decompression. The argument can contain command line
|
|
options.
|
|
<DT id="125"><B>-j</B>, <B>--bzip2</B><DD>
|
|
Filter the archive through
|
|
<B><A HREF="/cgi-bin/man/man2html?1+bzip2">bzip2</A></B>(1).
|
|
|
|
<DT id="126"><B>-J</B>, <B>--xz</B><DD>
|
|
Filter the archive through
|
|
<B><A HREF="/cgi-bin/man/man2html?1+xz">xz</A></B>(1).
|
|
|
|
<DT id="127"><B>--lzip</B><DD>
|
|
Filter the archive through
|
|
<B><A HREF="/cgi-bin/man/man2html?1+lzip">lzip</A></B>(1).
|
|
|
|
<DT id="128"><B>--lzma</B><DD>
|
|
Filter the archive through
|
|
<B><A HREF="/cgi-bin/man/man2html?1+lzma">lzma</A></B>(1).
|
|
|
|
<DT id="129"><B>--lzop</B><DD>
|
|
Filter the archive through
|
|
<B><A HREF="/cgi-bin/man/man2html?1+lzop">lzop</A></B>(1).
|
|
|
|
<DT id="130"><B>--no-auto-compress</B><DD>
|
|
Do not use archive suffix to determine the compression program.
|
|
<DT id="131"><B>-z</B>, <B>--gzip</B>, <B>--gunzip</B>, <B>--ungzip</B><DD>
|
|
Filter the archive through
|
|
<B><A HREF="/cgi-bin/man/man2html?1+gzip">gzip</A></B>(1).
|
|
|
|
<DT id="132"><B>-Z</B>, <B>--compress</B>, <B>--uncompress</B><DD>
|
|
Filter the archive through
|
|
<B><A HREF="/cgi-bin/man/man2html?1+compress">compress</A></B>(1).
|
|
|
|
<DT id="133"><B>--zstd</B><DD>
|
|
Filter the archive through
|
|
<B><A HREF="/cgi-bin/man/man2html?1+zstd">zstd</A></B>(1).
|
|
|
|
</DL>
|
|
<A NAME="lbAU"> </A>
|
|
<H3>Local file selection</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="134"><B>--add-file</B>=<I>FILE</I><DD>
|
|
Add <I>FILE</I> to the archive (useful if its name starts with a dash).
|
|
<DT id="135"><B>--backup</B>[=<I>CONTROL</I>]<DD>
|
|
Backup before removal. The <I>CONTROL</I> argument, if supplied,
|
|
controls the backup policy. Its valid values are:
|
|
<DL COMPACT><DT id="136"><DD>
|
|
<DL COMPACT>
|
|
<DT id="137"><B>none</B>, <B>off</B>
|
|
|
|
<DD>
|
|
Never make backups.
|
|
<DT id="138"><B>t</B>, <B>numbered</B>
|
|
|
|
<DD>
|
|
Make numbered backups.
|
|
<DT id="139"><B>nil</B>, <B>existing</B>
|
|
|
|
<DD>
|
|
Make numbered backups if numbered backups exist, simple backups otherwise.
|
|
<DT id="140"><B>never</B>, <B>simple</B>
|
|
|
|
<DD>
|
|
Always make simple backups
|
|
<DL COMPACT><DT id="141"><DD>
|
|
</DL>
|
|
|
|
<P>
|
|
If <I>CONTROL</I> is not given, the value is taken from the
|
|
<B>VERSION_CONTROL</B>
|
|
|
|
environment variable. If it is not set, <B>existing</B> is assumed.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="142"><B>-C</B>, <B>--directory</B>=<I>DIR</I><DD>
|
|
Change to <I>DIR</I> before performing any operations. This option is
|
|
order-sensitive, i.e. it affects all options that follow.
|
|
<DT id="143"><B>--exclude</B>=<I>PATTERN</I><DD>
|
|
Exclude files matching <I>PATTERN</I>, a
|
|
<B><A HREF="/cgi-bin/man/man2html?3+glob">glob</A></B>(3)-style
|
|
|
|
wildcard pattern.
|
|
<DT id="144"><B>--exclude-backups</B><DD>
|
|
Exclude backup and lock files.
|
|
<DT id="145"><B>--exclude-caches</B><DD>
|
|
Exclude contents of directories containing file <B>CACHEDIR.TAG</B>,
|
|
except for the tag file itself.
|
|
<DT id="146"><B>--exclude-caches-all</B><DD>
|
|
Exclude directories containing file <B>CACHEDIR.TAG</B> and the file itself.
|
|
<DT id="147"><B>--exclude-caches-under</B><DD>
|
|
Exclude everything under directories containing <B>CACHEDIR.TAG</B>
|
|
<DT id="148"><B>--exclude-ignore=</B><I>FILE</I><DD>
|
|
Before dumping a directory, see if it contains <I>FILE</I>.
|
|
If so, read exclusion patterns from this file. The patterns affect
|
|
only the directory itself.
|
|
<DT id="149"><B>--exclude-ignore-recursive=</B><I>FILE</I><DD>
|
|
Same as <B>--exclude-ignore</B>, except that patterns from
|
|
<I>FILE</I> affect both the directory and all its subdirectories.
|
|
<DT id="150"><B>--exclude-tag</B>=<I>FILE</I><DD>
|
|
Exclude contents of directories containing <I>FILE</I>, except for
|
|
<I>FILE</I> itself.
|
|
<DT id="151"><B>--exclude-tag-all</B>=<I>FILE</I><DD>
|
|
Exclude directories containing <I>FILE</I>.
|
|
<DT id="152"><B>--exclude-tag-under</B>=<I>FILE</I><DD>
|
|
Exclude everything under directories containing <I>FILE</I>.
|
|
<DT id="153"><B>--exclude-vcs</B><DD>
|
|
Exclude version control system directories.
|
|
<DT id="154"><B>--exclude-vcs-ignores</B><DD>
|
|
Exclude files that match patterns read from VCS-specific ignore
|
|
files. Supported files are:
|
|
<B>.cvsignore</B>,
|
|
|
|
<B>.gitignore</B>,
|
|
|
|
<B>.bzrignore</B>, and
|
|
|
|
<B>.hgignore</B>.
|
|
|
|
<DT id="155"><B>-h</B>, <B>--dereference</B><DD>
|
|
Follow symlinks; archive and dump the files they point to.
|
|
<DT id="156"><B>--hard-dereference</B><DD>
|
|
Follow hard links; archive and dump the files they refer to.
|
|
<DT id="157"><B>-K</B>, <B>--starting-file</B>=<I>MEMBER</I><DD>
|
|
Begin at the given member in the archive.
|
|
<DT id="158"><B>--newer-mtime</B>=<I>DATE</I><DD>
|
|
Work on files whose data changed after the <I>DATE</I>. If <I>DATE</I>
|
|
starts with <B>/</B> or <B>.</B> it is taken to be a file name; the
|
|
mtime of that file is used as the date.
|
|
<DT id="159"><B>--no-null</B><DD>
|
|
Disable the effect of the previous <B>--null</B> option.
|
|
<DT id="160"><B>--no-recursion</B><DD>
|
|
Avoid descending automatically in directories.
|
|
<DT id="161"><B>--no-unquote</B><DD>
|
|
Do not unquote input file or member names.
|
|
<DT id="162"><B>--no-verbatim-files-from</B><DD>
|
|
Treat each line read from a file list as if it were supplied in the
|
|
command line. I.e., leading and trailing whitespace is removed and,
|
|
if the resulting string begins with a dash, it is treated as <B>tar</B>
|
|
command line option.
|
|
<P>
|
|
This is the default behavior. The <B>--no-verbatim-files-from</B>
|
|
option is provided as a way to restore it after
|
|
<B>--verbatim-files-from</B> option.
|
|
<P>
|
|
This option is positional: it affects all <B>--files-from</B>
|
|
options that occur after it in, until <B>--verbatim-files-from</B>
|
|
option or end of line, whichever occurs first.
|
|
<P>
|
|
It is implied by the <B>--no-null</B> option.
|
|
<DT id="163"><B>--null</B><DD>
|
|
Instruct subsequent <B>-T</B> options to read null-terminated names
|
|
verbatim (disables special handling of names that start with a dash).
|
|
<P>
|
|
See also <B>--verbatim-files-from</B>.
|
|
<DT id="164"><B>-N</B>, <B>--newer</B>=<I>DATE</I>, <B>--after-date</B>=<I>DATE</I><DD>
|
|
Only store files newer than DATE. If <I>DATE</I> starts with <B>/</B>
|
|
or <B>.</B> it is taken to be a file name; the ctime of that file is
|
|
used as the date.
|
|
<DT id="165"><B>--one-file-system</B><DD>
|
|
Stay in local file system when creating archive.
|
|
<DT id="166"><B>-P</B>, <B>--absolute-names</B><DD>
|
|
Don't strip leading slashes from file names when creating archives.
|
|
<DT id="167"><B>--recursion</B><DD>
|
|
Recurse into directories (default).
|
|
<DT id="168"><B>--suffix</B>=<I>STRING</I><DD>
|
|
Backup before removal, override usual suffix. Default suffix is <B>~</B>,
|
|
unless overridden by environment variable <B>SIMPLE_BACKUP_SUFFIX</B>.
|
|
<DT id="169"><B>-T</B>, <B>--files-from</B>=<I>FILE</I><DD>
|
|
Get names to extract or create from <I>FILE</I>.
|
|
<P>
|
|
Unless specified otherwise, the <I>FILE</I> must contain a list of
|
|
names separated by ASCII <B>LF</B> (i.e. one name per line). The
|
|
names read are handled the same way as command line arguments. They
|
|
undergo quote removal and word splitting, and any string that starts
|
|
with a <B>-</B> is handled as <B>tar</B> command line option.
|
|
<P>
|
|
If this behavior is undesirable, it can be turned off using the
|
|
<B>--verbatim-files-from</B> option.
|
|
<P>
|
|
The <B>--null</B> option instructs <B>tar</B> that the names in
|
|
<I>FILE</I> are separated by ASCII <B>NUL</B> character, instead of
|
|
<B>LF</B>. It is useful if the list is generated by
|
|
<B><A HREF="/cgi-bin/man/man2html?1+find">find</A></B>(1)
|
|
|
|
<B>-print0</B>
|
|
|
|
predicate.
|
|
<DT id="170"><B>--unquote</B><DD>
|
|
Unquote file or member names (default).
|
|
<DT id="171"><B>--verbatim-files-from</B><DD>
|
|
Treat each line obtained from a file list as a file name, even if it
|
|
starts with a dash. File lists are supplied with the
|
|
<B>--files-from</B> (<B>-T</B>) option. The default behavior is to
|
|
handle names supplied in file lists as if they were typed in the
|
|
command line, i.e. any names starting with a dash are treated as
|
|
<B>tar</B> options. The <B>--verbatim-files-from</B> option
|
|
disables this behavior.
|
|
<P>
|
|
This option affects all <B>--files-from</B> options that occur after
|
|
it in the command line. Its effect is reverted by the
|
|
<B>--no-verbatim-files-from} option.
|
|
<P>
|
|
This option is implied by the --null</B> option.
|
|
<P>
|
|
See also <B>--add-file</B>.
|
|
<DT id="172"><B>-X</B>, <B>--exclude-from</B>=<I>FILE</I><DD>
|
|
Exclude files matching patterns listed in FILE.
|
|
</DL>
|
|
<A NAME="lbAV"> </A>
|
|
<H3>File name transformations</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="173"><B>--strip-components</B>=<I>NUMBER</I><DD>
|
|
Strip <I>NUMBER</I> leading components from file names on extraction.
|
|
<DT id="174"><B>--transform</B>=<I>EXPRESSION</I>, <B>--xform</B>=<I>EXPRESSION</I><DD>
|
|
Use sed replace <I>EXPRESSION</I> to transform file names.
|
|
</DL>
|
|
<A NAME="lbAW"> </A>
|
|
<H3>File name matching options</H3>
|
|
|
|
These options affect both exclude and include patterns.
|
|
<DL COMPACT>
|
|
<DT id="175"><B>--anchored</B><DD>
|
|
Patterns match file name start.
|
|
<DT id="176"><B>--ignore-case</B><DD>
|
|
Ignore case.
|
|
<DT id="177"><B>--no-anchored</B><DD>
|
|
Patterns match after any <B>/</B> (default for exclusion).
|
|
<DT id="178"><B>--no-ignore-case</B><DD>
|
|
Case sensitive matching (default).
|
|
<DT id="179"><B>--no-wildcards</B><DD>
|
|
Verbatim string matching.
|
|
<DT id="180"><B>--no-wildcards-match-slash</B><DD>
|
|
Wildcards do not match <B>/</B>.
|
|
<DT id="181"><B>--wildcards</B><DD>
|
|
Use wildcards (default for exclusion).
|
|
<DT id="182"><B>--wildcards-match-slash</B><DD>
|
|
Wildcards match <B>/</B> (default for exclusion).
|
|
</DL>
|
|
<A NAME="lbAX"> </A>
|
|
<H3>Informative output</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="183"><B>--checkpoint</B>[=<I>N</I>]<DD>
|
|
Display progress messages every <I>N</I>th record (default 10).
|
|
<DT id="184"><B>--checkpoint-action</B>=<I>ACTION</I><DD>
|
|
Run <I>ACTION</I> on each checkpoint.
|
|
<DT id="185"><B>--clamp-mtime</B><DD>
|
|
Only set time when the file is more recent than what was given with --mtime.
|
|
<DT id="186"><B>--full-time</B><DD>
|
|
Print file time to its full resolution.
|
|
<DT id="187"><B>--index-file</B>=<I>FILE</I><DD>
|
|
Send verbose output to <I>FILE</I>.
|
|
<DT id="188"><B>-l</B>, <B>--check-links</B><DD>
|
|
Print a message if not all links are dumped.
|
|
<DT id="189"><B>--no-quote-chars</B>=<I>STRING</I><DD>
|
|
Disable quoting for characters from <I>STRING</I>.
|
|
<DT id="190"><B>--quote-chars</B>=<I>STRING</I><DD>
|
|
Additionally quote characters from <I>STRING</I>.
|
|
<DT id="191"><B>--quoting-style</B>=<I>STYLE</I><DD>
|
|
Set quoting style for file and member names. Valid values for
|
|
<I>STYLE</I> are
|
|
<B>literal</B>,
|
|
|
|
<B>shell</B>,
|
|
|
|
<B>shell-always</B>,
|
|
|
|
<B>c</B>,
|
|
|
|
<B>c-maybe</B>,
|
|
|
|
<B>escape</B>,
|
|
|
|
<B>locale</B>,
|
|
|
|
<B>clocale</B>.
|
|
|
|
<DT id="192"><B>-R</B>, <B>--block-number</B><DD>
|
|
Show block number within archive with each message.
|
|
<DT id="193"><B>--show-omitted-dirs</B><DD>
|
|
When listing or extracting, list each directory that does not match
|
|
search criteria.
|
|
<DT id="194"><B>--show-transformed-names</B>, <B>--show-stored-names</B><DD>
|
|
Show file or archive names after transformation by <B>--strip</B> and
|
|
<B>--transform</B> options.
|
|
<DT id="195"><B>--totals</B>[=<I>SIGNAL</I>]<DD>
|
|
Print total bytes after processing the archive. If <I>SIGNAL</I> is
|
|
given, print total bytes when this signal is delivered. Allowed
|
|
signals are:
|
|
<B>SIGHUP</B>,
|
|
|
|
<B>SIGQUIT</B>,
|
|
|
|
<B>SIGINT</B>,
|
|
|
|
<B>SIGUSR1</B>, and
|
|
|
|
<B>SIGUSR2</B>.
|
|
|
|
The <B>SIG</B> prefix can be omitted.
|
|
<DT id="196"><B>--utc</B><DD>
|
|
Print file modification times in UTC.
|
|
<DT id="197"><B>-v</B>, <B>--verbose</B><DD>
|
|
Verbosely list files processed.
|
|
<DT id="198"><B>--warning</B>=<I>KEYWORD</I><DD>
|
|
Enable or disable warning messages identified by <I>KEYWORD</I>. The
|
|
messages are suppressed if <I>KEYWORD</I> is prefixed with <B>no-</B>
|
|
and enabled otherwise.
|
|
<P>
|
|
Multiple <B>--warning</B> messages accumulate.
|
|
<P>
|
|
Keywords controlling general <B>tar</B> operation:
|
|
<DL COMPACT><DT id="199"><DD>
|
|
<DL COMPACT>
|
|
<DT id="200"><B>all</B>
|
|
|
|
<DD>
|
|
Enable all warning messages. This is the default.
|
|
<DT id="201"><B>none</B>
|
|
|
|
<DD>
|
|
Disable all warning messages.
|
|
<DT id="202"><B>filename-with-nuls</B>
|
|
|
|
<DD>
|
|
"%s: file name read contains nul character"
|
|
<DT id="203"><B>alone-zero-block</B>
|
|
|
|
<DD>
|
|
"A lone zero block at %s"
|
|
<DT id="204">
|
|
<DD>Keywords applicable for <B>tar --create</B>:
|
|
<DT id="205"><B>cachedir</B>
|
|
|
|
<DD>
|
|
"%s: contains a cache directory tag %s; %s"
|
|
<DT id="206"><B>file-shrank</B>
|
|
|
|
<DD>
|
|
"%s: File shrank by %s bytes; padding with zeros"
|
|
<DT id="207"><B>xdev</B>
|
|
|
|
<DD>
|
|
"%s: file is on a different filesystem; not dumped"
|
|
<DT id="208"><B>file-ignored</B>
|
|
|
|
<DD>
|
|
"%s: Unknown file type; file ignored"
|
|
<BR>
|
|
|
|
"%s: socket ignored"
|
|
<BR>
|
|
|
|
"%s: door ignored"
|
|
<DT id="209"><B>file-unchanged</B>
|
|
|
|
<DD>
|
|
"%s: file is unchanged; not dumped"
|
|
<DT id="210"><B>ignore-archive</B>
|
|
|
|
<DD>
|
|
"%s: file is the archive; not dumped"
|
|
<DT id="211"><B>file-removed</B>
|
|
|
|
<DD>
|
|
"%s: File removed before we read it"
|
|
<DT id="212"><B>file-changed</B>
|
|
|
|
<DD>
|
|
"%s: file changed as we read it"
|
|
<DT id="213"><B>failed-read</B>
|
|
|
|
<DD>
|
|
Suppresses warnings about unreadable files or directories. This
|
|
keyword applies only if used together with the
|
|
<B>--ignore-failed-read</B>
|
|
|
|
option.
|
|
<DT id="214">
|
|
<DD>Keywords applicable for <B>tar --extract</B>:
|
|
<DT id="215"><B>existing-file</B>
|
|
|
|
<DD>
|
|
"%s: skipping existing file"
|
|
<DT id="216"><B>timestamp</B>
|
|
|
|
<DD>
|
|
"%s: implausibly old time stamp %s"
|
|
<BR>
|
|
|
|
"%s: time stamp %s is %s s in the future"
|
|
<DT id="217"><B>contiguous-cast</B>
|
|
|
|
<DD>
|
|
"Extracting contiguous files as regular files"
|
|
<DT id="218"><B>symlink-cast</B>
|
|
|
|
<DD>
|
|
"Attempting extraction of symbolic links as hard links"
|
|
<DT id="219"><B>unknown-cast</B>
|
|
|
|
<DD>
|
|
"%s: Unknown file type '%c', extracted as normal file"
|
|
<DT id="220"><B>ignore-newer</B>
|
|
|
|
<DD>
|
|
"Current %s is newer or same age"
|
|
<DT id="221"><B>unknown-keyword</B>
|
|
|
|
<DD>
|
|
"Ignoring unknown extended header keyword '%s'"
|
|
<DT id="222"><B>decompress-program</B>
|
|
|
|
<DD>
|
|
Controls verbose description of failures occurring when trying to run
|
|
alternative decompressor programs. This warning is disabled by
|
|
default (unless <B>--verbose</B> is used). A common example of what
|
|
you can get when using this warning is:
|
|
<P>
|
|
|
|
$ <B>tar --warning=decompress-program -x -f archive.Z
|
|
tar (child): cannot run compress: No such file or directory
|
|
tar (child): trying gzip
|
|
|
|
<P>
|
|
This means that tar</B> first tried to decompress
|
|
<B>archive.Z</B> using <B>compress</B>, and, when that
|
|
failed, switched to <B>gzip</B>.
|
|
<DT id="223"><B>record-size</B>
|
|
|
|
<DD>
|
|
"Record size = %lu blocks"
|
|
<DT id="224">
|
|
<DD>Keywords controlling incremental extraction:
|
|
<DT id="225"><B>rename-directory</B>
|
|
|
|
<DD>
|
|
"%s: Directory has been renamed from %s"
|
|
<BR>
|
|
|
|
"%s: Directory has been renamed"
|
|
<DT id="226"><B>new-directory</B>
|
|
|
|
<DD>
|
|
"%s: Directory is new"
|
|
<DT id="227"><B>xdev</B>
|
|
|
|
<DD>
|
|
"%s: directory is on a different device: not purging"
|
|
<DT id="228"><B>bad-dumpdir</B>
|
|
|
|
<DD>
|
|
"Malformed dumpdir: 'X' never used"
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="229"><B>-w</B>, <B>--interactive</B>, <B>--confirmation</B><DD>
|
|
Ask for confirmation for every action.
|
|
</DL>
|
|
<A NAME="lbAY"> </A>
|
|
<H3>Compatibility options</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="230"><B>-o</B><DD>
|
|
When creating, same as <B>--old-archive</B>. When extracting, same
|
|
as <B>--no-same-owner</B>.
|
|
</DL>
|
|
<A NAME="lbAZ"> </A>
|
|
<H3>Size suffixes</H3>
|
|
|
|
<P>
|
|
<PRE>
|
|
|
|
Suffix Units Byte Equivalent
|
|
b Blocks <I>SIZE</I> x 512
|
|
B Kilobytes <I>SIZE</I> x 1024
|
|
c Bytes <I>SIZE</I>
|
|
G Gigabytes <I>SIZE</I> x 1024^3
|
|
K Kilobytes <I>SIZE</I> x 1024
|
|
k Kilobytes <I>SIZE</I> x 1024
|
|
M Megabytes <I>SIZE</I> x 1024^2
|
|
P Petabytes <I>SIZE</I> x 1024^5
|
|
T Terabytes <I>SIZE</I> x 1024^4
|
|
w Words <I>SIZE</I> x 2
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
<A NAME="lbBA"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
Tar exit code indicates whether it was able to successfully perform
|
|
the requested operation, and if not, what kind of error occurred.
|
|
<DL COMPACT>
|
|
<DT id="231"><B>0</B>
|
|
|
|
<DD>
|
|
Successful termination.
|
|
<DT id="232"><B>1</B>
|
|
|
|
<DD>
|
|
<I>Some files differ.</I>
|
|
|
|
If tar was invoked with the <B>--compare</B> (<B>--diff</B>, <B>-d</B>)
|
|
command line option, this means that some files in the archive differ
|
|
from their disk counterparts. If tar was given one of the <B>--create</B>,
|
|
<B>--append</B> or <B>--update</B> options, this exit code means
|
|
that some files were changed while being archived and so the resulting
|
|
archive does not contain the exact copy of the file set.
|
|
<DT id="233"><B>2</B>
|
|
|
|
<DD>
|
|
<I>Fatal error.</I>
|
|
|
|
This means that some fatal, unrecoverable error occurred.
|
|
</DL>
|
|
<P>
|
|
|
|
If a subprocess that had been invoked by
|
|
<B>tar</B>
|
|
|
|
exited with a nonzero exit code,
|
|
<B>tar</B>
|
|
|
|
itself exits with that code as well. This can happen, for example, if
|
|
a compression option (e.g. <B>-z</B>) was used and the external
|
|
compressor program failed. Another example is
|
|
<B>rmt</B>
|
|
|
|
failure during backup to a remote device.
|
|
<A NAME="lbBB"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+bzip2">bzip2</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+compress">compress</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+gzip">gzip</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+lzma">lzma</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+lzop">lzop</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?8+rmt">rmt</A></B>(8),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+symlink">symlink</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+xz">xz</A></B>(1).
|
|
|
|
<P>
|
|
|
|
Complete <B>tar</B> manual: run
|
|
<B>info tar</B>
|
|
|
|
or use
|
|
<B><A HREF="/cgi-bin/man/man2html?1+emacs">emacs</A></B>(1)
|
|
|
|
info mode to read it.
|
|
<P>
|
|
|
|
Online copies of <B>GNU tar</B> documentation in various formats can be
|
|
found at:
|
|
<P>
|
|
|
|
|
|
<B><A HREF="http://www.gnu.org/software/tar/manual">http://www.gnu.org/software/tar/manual</A></B>
|
|
|
|
<A NAME="lbBC"> </A>
|
|
<H2>BUG REPORTS</H2>
|
|
|
|
Report bugs to <<A HREF="mailto:bug-tar@gnu.org">bug-tar@gnu.org</A>>.
|
|
<A NAME="lbBD"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
Copyright © 2013 Free Software Foundation, Inc.
|
|
<BR>
|
|
|
|
|
|
License GPLv3+: GNU GPL version 3 or later <<A HREF="http://gnu.org/licenses/gpl.html">http://gnu.org/licenses/gpl.html</A>>
|
|
<BR>
|
|
|
|
|
|
This is free software: you are free to change and redistribute it.
|
|
There is NO WARRANTY, to the extent permitted by law.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="234"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="235"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DL>
|
|
<DT id="236"><A HREF="#lbAD">Traditional usage</A><DD>
|
|
<DT id="237"><A HREF="#lbAE">UNIX-style usage</A><DD>
|
|
<DT id="238"><A HREF="#lbAF">GNU-style usage</A><DD>
|
|
</DL>
|
|
<DT id="239"><A HREF="#lbAG">NOTE</A><DD>
|
|
<DT id="240"><A HREF="#lbAH">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="241"><A HREF="#lbAI">Option styles</A><DD>
|
|
<DT id="242"><A HREF="#lbAJ">Operation mode</A><DD>
|
|
</DL>
|
|
<DT id="243"><A HREF="#lbAK">OPTIONS</A><DD>
|
|
<DL>
|
|
<DT id="244"><A HREF="#lbAL">Operation modifiers</A><DD>
|
|
<DT id="245"><A HREF="#lbAM">Overwrite control</A><DD>
|
|
<DT id="246"><A HREF="#lbAN">Output stream selection</A><DD>
|
|
<DT id="247"><A HREF="#lbAO">Handling of file attributes</A><DD>
|
|
<DT id="248"><A HREF="#lbAP">Extended file attributes</A><DD>
|
|
<DT id="249"><A HREF="#lbAQ">Device selection and switching</A><DD>
|
|
<DT id="250"><A HREF="#lbAR">Device blocking</A><DD>
|
|
<DT id="251"><A HREF="#lbAS">Archive format selection</A><DD>
|
|
<DT id="252"><A HREF="#lbAT">Compression options</A><DD>
|
|
<DT id="253"><A HREF="#lbAU">Local file selection</A><DD>
|
|
<DT id="254"><A HREF="#lbAV">File name transformations</A><DD>
|
|
<DT id="255"><A HREF="#lbAW">File name matching options</A><DD>
|
|
<DT id="256"><A HREF="#lbAX">Informative output</A><DD>
|
|
<DT id="257"><A HREF="#lbAY">Compatibility options</A><DD>
|
|
<DT id="258"><A HREF="#lbAZ">Size suffixes</A><DD>
|
|
</DL>
|
|
<DT id="259"><A HREF="#lbBA">RETURN VALUE</A><DD>
|
|
<DT id="260"><A HREF="#lbBB">SEE ALSO</A><DD>
|
|
<DT id="261"><A HREF="#lbBC">BUG REPORTS</A><DD>
|
|
<DT id="262"><A HREF="#lbBD">COPYRIGHT</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:28 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|