MWu8GcQZ

1/var/backups/alternatives.tar.1.gz.\" This file is part of GNU tar. -*- nroff -*-
2.\" Copyright 2013-2014, 2016 Free Software Foundation, Inc.
3.\"
4.\" GNU tar is free software; you can redistribute it and/or modify
5.\" it under the terms of the GNU General Public License as published by
6.\" the Free Software Foundation; either version 3 of the License, or
7.\" (at your option) any later version.
8.\"
9.\" GNU tar is distributed in the hope that it will be useful,
10.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12.\" GNU General Public License for more details.
13.\"
14.\" You should have received a copy of the GNU General Public License
15.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
16.TH TAR 1 "March 23, 2016" "TAR" "GNU TAR Manual"
17.SH NAME
18tar \- an archiving utility
19.SH SYNOPSIS
20.SS Traditional usage
21\fBtar\fR {\fBA\fR|\fBc\fR|\fBd\fR|\fBr\fR|\fBt\fR|\fBu\fR|\fBx\fR}\
22[\fBGnSkUWOmpsMBiajJzZhPlRvwo\fR] [\fIARG\fR...]
23.SS UNIX-style usage
24.sp
25\fBtar\fR \fB\-A\fR [\fIOPTIONS\fR] \fIARCHIVE\fR \fIARCHIVE\fR
26.sp
27\fBtar\fR \fB\-c\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
28.sp
29\fBtar\fR \fB\-d\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
30.sp
31\fBtar\fR \fB\-t\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
32.sp
33\fBtar\fR \fB\-r\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
34.sp
35\fBtar\fR \fB\-u\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
36.sp
37\fBtar\fR \fB\-x\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
38.SS GNU-style usage
39.sp
40\fBtar\fR {\fB\-\-catenate\fR|\fB\-\-concatenate\fR} [\fIOPTIONS\fR] \fIARCHIVE\fR \fIARCHIVE\fR
41.sp
42\fBtar\fR \fB\-\-create\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
43.sp
44\fBtar\fR {\fB\-\-diff\fR|\fB\-\-compare\fR} [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
45.sp
46\fBtar\fR \fB\-\-delete\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
47.sp
48\fBtar\fR \fB\-\-append\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
49.sp
50\fBtar\fR \fB\-\-list\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
51.sp
52\fBtar\fR \fB\-\-test\-label\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fILABEL\fR...]
53.sp
54\fBtar\fR \fB\-\-update\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
55.sp
56\fBtar\fR \fB\-\-update\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
57.sp
58\fBtar\fR {\fB\-\-extract\fR|\fB\-\-get\fR} [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
59.SH NOTE
60This manpage is a short description of GNU \fBtar\fR.  For a detailed
61discussion, including examples and usage recommendations, refer to the
62\fBGNU Tar Manual\fR available in texinfo format.  If the \fBinfo\fR
63reader and the tar documentation are properly installed on your
64system, the command
65.PP
66.RS +4
67.B info tar
68.RE
69.PP
70should give you access to the complete manual.
71.PP
72You can also view the manual using the info mode in
73.BR emacs (1),
74or find it in various formats online at
75.PP
76.RS +4
77.B http://www.gnu.org/software/tar/manual
78.RE
79.PP
80If any discrepancies occur between this manpage and the
81\fBGNU Tar Manual\fR, the later shall be considered the authoritative
82source.
83.SH DESCRIPTION
84GNU
85.B tar
86is an archiving program designed to store multiple files in a single
87file (an \fBarchive\fR), and to manipulate such archives.  The archive
88can be either a regular file or a device (e.g. a tape drive, hence the name
89of the program, which stands for \fBt\fRape \fBar\fRchiver), which can
90be located either on the local or on a remote machine.
91.PP
92
93.SS Option styles
94Options to GNU \fBtar\fR can be given in three different styles.
95In
96.BR "traditional style" ,
97the first argument is a cluster of option letters and all subsequent
98arguments supply arguments to those options that require them.  The
99arguments are read in the same order as the option letters.  Any
100command line words that remain after all options has been processed
101are treated as non-optional arguments: file or archive member names.
102.PP
103For example, the \fBc\fR option requires creating the archive, the
104\fBv\fR option requests the verbose operation, and the \fBf\fR option
105takes an argument that sets the name of the archive to operate upon.
106The following command, written in the traditional style, instructs tar
107to store all files from the directory
108.B /etc
109into the archive file
110.B etc.tar
111verbosely listing the files being archived:
112.PP
113.EX
114.B tar cfv a.tar /etc
115.EE
116.PP
117In
118.BR "UNIX " or " short-option style" ,
119each option letter is prefixed with a single dash, as in other command
120line utilities.  If an option takes argument, the argument follows it,
121either as a separate command line word, or immediately following the
122option.  However, if the option takes an \fBoptional\fR argument, the
123argument must follow the option letter without any intervening
124whitespace, as in \fB\-g/tmp/snar.db\fR.
125.PP
126Any number of options not taking arguments can be
127clustered together after a single dash, e.g. \fB\-vkp\fR.  Options
128that take arguments (whether mandatory or optional), can appear at
129the end of such a cluster, e.g. \fB\-vkpf a.tar\fR.
130.PP
131The example command above written in the
132.B short-option style
133could look like:
134.PP
135.EX
136.B tar -cvf a.tar /etc
137or
138.B tar -c -v -f a.tar /etc
139.EE
140.PP
141In
142.BR "GNU " or " long-option style" ,
143each option begins with two dashes and has a meaningful name,
144consisting of lower-case letters and dashes.  When used, the long
145option can be abbreviated to its initial letters, provided that
146this does not create ambiguity.  Arguments to long options are
147supplied either as a separate command line word, immediately following
148the option, or separated from the option by an equals sign with no
149intervening whitespace.  Optional arguments must always use the latter
150method.
151.PP
152Here are several ways of writing the example command in this style:
153.PP
154.EX
155.B tar --create --file a.tar --verbose /etc
156.EE
157or (abbreviating some options):
158.EX
159.B tar --cre --file=a.tar --verb /etc
160.EE
161.PP
162The options in all three styles can be intermixed, although doing so
163with old options is not encouraged.
164.SS Operation mode
165The options listed in the table below tell GNU \fBtar\fR what
166operation it is to perform.  Exactly one of them must be given.
167Meaning of non-optional arguments depends on the operation mode
168requested.
169.TP
170\fB\-A\fR, \fB\-\-catenate\fR, \fB\-\-concatenate\fR
171Append archive to the end of another archive.  The arguments are
172treated as the names of archives to append.  All archives must be of
173the same format as the archive they are appended to, otherwise the
174resulting archive might be unusable with non-GNU implementations of
175\fBtar\fR.  Notice also that when more than one archive is given, the
176members from archives other than the first one will be accessible in
177the resulting archive only if using the \fB\-i\fR
178(\fB\-\-ignore\-zeros\fR) option.
179
180Compressed archives cannot be concatenated.
181.TP
182\fB\-c\fR, \fB\-\-create\fR
183Create a new archive.  Arguments supply the names of the files to be
184archived.  Directories are archived recursively, unless the
185\fB\-\-no\-recursion\fR option is given.
186.TP
187\fB\-d\fR, \fB\-\-diff\fR, \fB\-\-compare\fR
188Find differences between archive and file system.  The arguments are
189optional and specify archive members to compare.  If not given, the
190current working directory is assumed.
191.TP
192\fB\-\-delete\fR
193Delete from the archive.  The arguments supply names of the archive
194members to be removed.  At least one argument must be given.
195
196This option does not operate on compressed archives.  There is no
197short option equivalent.
198.TP
199\fB\-r\fR, \fB\-\-append\fR
200Append files to the end of an archive.  Arguments have the same
201meaning as for \fB\-c\fR (\fB\-\-create\fR).
202.TP
203\fB\-t\fR, \fB\-\-list\fR
204List the contents of an archive.  Arguments are optional.  When given,
205they specify the names of the members to list.
206.TP
207\fB\-\-test\-label
208Test the archive volume label and exit.  When used without arguments,
209it prints the volume label (if any) and exits with status \fB0\fR.
210When one or more command line arguments are given.
211.B tar
212compares the volume label with each argument.  It exits with code
213\fB0\fR if a match is found, and with code \fB1\fR otherwise.  No
214output is displayed, unless used together with the \fB\-v\fR
215(\fB\-\-verbose\fR) option.
216
217There is no short option equivalent for this option.
218.TP
219\fB\-u\fR, \fB\-\-update\fR
220Append files which are newer than the corresponding copy in the
221archive.  Arguments have the same meaning as with \fB\-c\fR and
222\fB\-r\fR options.
223.TP
224\fB\-x\fR, \fB\-\-extract\fR, \fB\-\-get\fR
225Extract files from an archive.  Arguments are optional.  When given,
226they specify names of the archive members to be extracted.
227.TP
228.TP
229\fB\-\-show\-defaults\fR
230Show built-in defaults for various \fBtar\fR options and exit.  No
231arguments are allowed.
232.TP
233\fB\-?\fR, \fB\-\-help
234Display a short option summary and exit.  No arguments allowed.
235.TP
236\fB\-\-usage\fR
237Display a list of available options and exit.  No arguments allowed.
238.TP
239\fB\-\-version\fR
240Print program version and copyright information and exit.
241.SH OPTIONS
242.SS Operation modifiers
243.TP
244\fB\-\-check\-device\fR
245Check device numbers when creating incremental archives (default).
246.TP
247\fB\-g\fR, \fB\-\-listed\-incremental\fR=\fIFILE\fR
248Handle new GNU-format incremental backups.  \fIFILE\fR is the name of
249a \fBsnapshot file\fR, where tar stores additional information which
250is used to decide which files changed since the previous incremental
251dump and, consequently, must be dumped again.  If \fIFILE\fR does not
252exist when creating an archive, it will be created and all files will
253be added to the resulting archive (the \fBlevel 0\fR dump).  To create
254incremental archives of non-zero level \fBN\fR, create a copy of the
255snapshot file created during the level \fBN-1\fR, and use it as
256\fIFILE\fR. 
257
258When listing or extracting, the actual contents of \fIFILE\fR is not
259inspected, it is needed only due to syntactical requirements.  It is
260therefore common practice to use \fB/dev/null\fR in its place.
261.TP
262\fB\-\-hole\-detection\fR=\fIMETHOD\fR
263Use \fIMETHOD\fR to detect holes in sparse files.  This option implies
264\fB\-\-sparse\fR.  Valid values for \fIMETHOD\fR are \fBseek\fR and
265\fBraw\fR.  Default is \fBseek\fR with fallback to \fBraw\fR when not
266applicable.
267.TP
268\fB\-G\fR, \fB\-\-incremental\fR
269Handle old GNU-format incremental backups.
270.TP
271\fB\-\-ignore\-failed\-read\fR
272Do not exit with nonzero on unreadable files.
273.TP
274\fB\-\-level\fR=\fINUMBER\fR
275Set dump level for created listed-incremental archive.  Currently only
276\fB\-\-level=0\fR is meaningful: it instructs \fBtar\fR to truncate
277the snapshot file before dumping, thereby forcing a level 0 dump.
278.TP
279\fB\-n\fR, \fB\-\-seek\fR
280Assume the archive is seekable.  Normally \fBtar\fR determines
281automatically whether the archive can be seeked or not.  This option
282is intended for use in cases when such recognition fails.  It takes
283effect only if the archive is open for reading (e.g. with
284.B \-\-list
285or
286.B \-\-extract
287options).		    
288.TP
289\fB\-\-no\-check\-device\fR
290Do not check device numbers when creating incremental archives.
291.TP
292\fB\-\-no\-seek\fR
293Assume the archive is not seekable.
294.TP
295\fB\-\-occurrence\fR[=\fIN\fR]
296Process only the \fIN\fRth occurrence of each file in the
297archive.  This option is valid only when used with one of the
298following subcommands: \fB\-\-delete\fR, \fB\-\-diff\fR,
299\fB\-\-extract\fR or \fB\-\-list\fR and when a list of files is given
300either on the command line or via the \fB\-T\fR option.  The default
301\fIN\fR is \fB1\fR.
302.TP
303\fB\-\-restrict\fR
304Disable the use of some potentially harmful options.
305.TP
306\fB\-\-sparse\-version\fR=\fIMAJOR\fR[.\fIMINOR\fR]
307Set version of the sparse format to use (implies \fB\-\-sparse\fR).
308This option implies
309.BR \-\-sparse .
310Valid argument values are
311.BR 0.0 ,
312.BR 0.1 ", and"
313.BR 1.0 .
314For a detailed discussion of sparse formats, refer to the \fBGNU Tar
315Manual\fR, appendix \fBD\fR, "\fBSparse Formats\fR".  Using \fBinfo\fR
316reader, it can be accessed running the following command:
317.BR "info tar 'Sparse Formats'" .
318.TP
319\fB\-S\fR, \fB\-\-sparse\fR
320Handle sparse files efficiently.  Some files in the file system may
321have segments which were actually never written (quite often these are
322database files created by such systems as \fBDBM\fR).  When given this
323option, \fBtar\fR attempts to determine if the file is sparse prior to
324archiving it, and if so, to reduce the resulting archive size by not
325dumping empty parts of the file.
326.SS Overwrite control
327These options control \fBtar\fR actions when extracting a file over
328an existing copy on disk.
329.TP
330\fB\-k\fR, \fB\-\-keep\-old\-files\fR
331Don't replace existing files when extracting.
332.TP
333\fB\-\-keep\-newer\-files\fR
334Don't replace existing files that are newer than their archive copies.
335.TP
336\fB\-\-no\-overwrite\-dir\fR
337Preserve metadata of existing directories.
338.TP
339\fB\-\-one\-top\-level\fR[\fB=\fIDIR\fR]
340Extract all files into \fIDIR\fR, or, if used without argument, into a
341subdirectory named by the base name of the archive (minus standard
342compression suffixes recognizable by \fB\-\-auto\-compress).
343.TP
344\fB\-\-overwrite\fR
345Overwrite existing files when extracting.
346.TP
347\fB\-\-overwrite\-dir\fR
348Overwrite metadata of existing directories when extracting (default).
349.TP
350\fB\-\-recursive\-unlink\fR
351Recursively remove all files in the directory prior to extracting it.
352.TP
353\fB\-\-remove\-files\fR
354Remove files from disk after adding them to the archive.
355.TP
356\fB\-\-skip\-old\-files
357Don't replace existing files when extracting, silently skip over them.
358.TP
359\fB\-U\fR, \fB\-\-unlink\-first\fR
360Remove each file prior to extracting over it.
361.TP
362\fB\-W\fR, \fB\-\-verify\fR
363Verify the archive after writing it.
364.SS Output stream selection
365.TP
366\fB\-\-ignore\-command\-error\fR
367.TP
368Ignore subprocess exit codes.
369.TP
370\fB\-\-no\-ignore\-command\-error\fR
371Treat non-zero exit codes of children as error (default).
372.TP
373\fB\-O\fR, \fB\-\-to\-stdout\fR
374Extract files to standard output.
375.TP
376\fB\-\-to\-command\fR=\fICOMMAND\fR
377Pipe extracted files to \fICOMMAND\fR.  The argument is the pathname
378of an external program, optionally with command line arguments.  The
379program will be invoked and the contents of the file being extracted
380supplied to it on its standard output.  Additional data will be
381supplied via the following environment variables:
382.RS
383.TP
384.B TAR_FILETYPE
385Type of the file. It is a single letter with the following meaning:
386.sp
387.nf
388.ta 8n 20n
389	f	Regular file
390	d	Directory
391	l	Symbolic link
392	h	Hard link
393	b	Block device
394	c	Character device
395.fi
396
397Currently only regular files are supported.
398.TP
399.B TAR_MODE
400File mode, an octal number.
401.TP
402.B TAR_FILENAME
403The name of the file.
404.TP
405.B TAR_REALNAME
406Name of the file as stored in the archive.
407.TP
408.B TAR_UNAME
409Name of the file owner.
410.TP
411.B TAR_GNAME
412Name of the file owner group.
413.TP
414.B TAR_ATIME
415Time of last access. It is a decimal number, representing seconds
416since the Epoch.  If the archive provides times with nanosecond
417precision, the nanoseconds are appended to the timestamp after a
418decimal point.
419.TP
420.B TAR_MTIME
421Time of last modification.
422.TP
423.B TAR_CTIME
424Time of last status change.
425.TP
426.B TAR_SIZE
427Size of the file.
428.TP
429.B TAR_UID
430UID of the file owner.
431.TP
432.B TAR_GID
433GID of the file owner.
434.RE
435.RS
436
437Additionally, the following variables contain information about
438\fBtar\fR operation mode and the archive being processed:
439.TP
440.B TAR_VERSION
441GNU \fBtar\fR version number.
442.TP
443.B TAR_ARCHIVE
444The name of the archive \fBtar\fR is processing.
445.TP
446.B TAR_BLOCKING_FACTOR
447Current blocking factor, i.e. number of 512-byte blocks in a record.
448.TP
449.B TAR_VOLUME
450Ordinal number of the volume \fBtar\fR is processing (set if
451reading a multi-volume archive).
452.TP
453.B TAR_FORMAT
454Format of the archive being processed.  One of:
455.BR gnu ,
456.BR oldgnu ,
457.BR posix ,
458.BR ustar ,
459.BR v7 .
460.B TAR_SUBCOMMAND
461A short option (with a leading dash) describing the operation \fBtar\fR is
462executing. 
463.RE
464.SS Handling of file attributes
465.TP
466\fB\-\-atime\-preserve\fR[=\fIMETHOD\fR]
467Preserve access times on dumped files, either by restoring the times
468after reading (\fIMETHOD\fR=\fBreplace\fR, this is the default) or by
469not setting the times in the first place (\fIMETHOD\fR=\fBsystem\fR)
470.TP
471\fB\-\-delay\-directory\-restore\fR
472Delay setting modification times and permissions of extracted
473directories until the end of extraction.  Use this option when
474extracting from an archive which has unusual member ordering.
475.TP
476\fB\-\-group\fR=\fINAME\fR[:\fIGID\fR]
477Force \fINAME\fR as group for added files.  If \fIGID\fR is not
478supplied, \fINAME\fR can be either a user name or numeric GID.  In
479this case the missing part (GID or name) will be inferred from the
480current host's group database.
481
482When used with \fB\-\-group\-map\fR=\fIFILE\fR, affects only those
483files whose owner group is not listed in \fIFILE\fR.
484.TP
485\fB\-\-group\-map\fR=\fIFILE\fR
486Read group translation map from \fIFILE\fR.  Empty lines are ignored.
487Comments are introduced with \fB#\fR sign and extend to the end of line.
488Each non-empty line in \fIFILE\fR defines translation for a single
489group.  It must consist of two fields, delimited by any amount of whitespace:
490
491.EX
492\fIOLDGRP\fR \fINEWGRP\fR[\fB:\fINEWGID\fR]
493.EE
494
495\fIOLDGRP\fR is either a valid group name or a GID prefixed with
496\fB+\fR.  Unless \fINEWGID\fR is supplied, \fINEWGRP\fR must also be
497either a valid group name or a \fB+\fIGID\fR.  Otherwise, both
498\fINEWGRP\fR and \fINEWGID\fR need not be listed in the system group
499database.
500
501As a result, each input file with owner group \fIOLDGRP\fR will be
502stored in archive with owner group \fINEWGRP\fR and GID \fINEWGID\fR.
503.TP
504\fB\-\-mode\fR=\fICHANGES\fR
505Force symbolic mode \fICHANGES\fR for added files.
506.TP
507\fB\-\-mtime\fR=\fIDATE-OR-FILE\fR
508Set mtime for added files.  \fIDATE-OR-FILE\fR is either a date/time
509in almost arbitrary format, or the name of an existing file.  In the
510latter case the mtime of that file will be used.
511.TP
512\fB\-m\fR, \fB\-\-touch\fR
513Don't extract file modified time.
514.TP
515\fB\-\-no\-delay\-directory\-restore\fR
516Cancel the effect of the prior \fB\-\-delay\-directory\-restore\fR option.
517.TP
518\fB\-\-no\-same\-owner\fR
519Extract files as yourself (default for ordinary users).
520.TP
521\fB\-\-no\-same\-permissions\fR
522Apply the user's umask when extracting permissions from the archive
523(default for ordinary users).
524.TP
525\fB\-\-numeric\-owner\fR
526Always use numbers for user/group names.
527.TP
528\fB\-\-owner\fR=\fINAME\fR[:\fIUID\fR]
529Force \fINAME\fR as owner for added files.  If \fIUID\fR is not
530supplied, \fINAME\fR can be either a user name or numeric UID.  In
531this case the missing part (UID or name) will be inferred from the
532current host's user database.
533
534When used with \fB\-\-owner\-map\fR=\fIFILE\fR, affects only those
535files whose owner is not listed in \fIFILE\fR.
536.TP
537\fB\-\-owner\-map\fR=\fIFILE\fR
538Read owner translation map from \fIFILE\fR.  Empty lines are ignored.
539Comments are introduced with \fB#\fR sign and extend to the end of line.
540Each non-empty line in \fIFILE\fR defines translation for a single
541UID.  It must consist of two fields, delimited by any amount of whitespace:
542
543.EX
544\fIOLDUSR\fR \fINEWUSR\fR[\fB:\fINEWUID\fR]
545.EE
546
547\fIOLDUSR\fR is either a valid user name or a UID prefixed with
548\fB+\fR.  Unless \fINEWUID\fR is supplied, \fINEWUSR\fR must also be
549either a valid user name or a \fB+\fIUID\fR.  Otherwise, both
550\fINEWUSR\fR and \fINEWUID\fR need not be listed in the system user
551database.
552
553As a result, each input file owned by \fIOLDUSR\fR will be
554stored in archive with owner name \fINEWUSR\fR and UID \fINEWUID\fR.
555.TP
556\fB\-p\fR, \fB\-\-preserve\-permissions\fR, \fB\-\-same\-permissions\fR
557extract information about file permissions (default for superuser)
558.TP
559\fB\-\-preserve\fR
560Same as both \fB\-p\fR and \fB\-s\fR.
561.TP
562\fB\-\-same\-owner\fR
563Try extracting files with the same ownership as exists in the archive
564(default for superuser).
565.TP
566\fB\-s\fR, \fB\-\-preserve\-order\fR, \fB\-\-same\-order\fR
567Sort names to extract to match archive
568.TP
569\fB\-\-sort=\fIORDER\fR
570When creating an archive, sort directory entries according to
571\fIORDER\fR, which is one of
572.BR none ,
573.BR name ", or"
574.BR inode .
575
576The default is \fB\-\-sort=none\fR, which stores archive members in
577the same order as returned by the operating system.
578
579Using \fB\-\-sort=name\fR ensures the member ordering in the created archive
580is uniform and reproducible.
581
582Using \fB\-\-sort=inode\fR reduces the number of disk seeks made when
583creating the archive and thus can considerably speed up archivation.
584This sorting order is supported only if the underlying system provides
585the necessary information.
586.SS Extended file attributes
587.TP
588.B \-\-acls
589Enable POSIX ACLs support.
590.TP
591.B \-\-no\-acls
592Disable POSIX ACLs support.
593.TP
594.B \-\-selinux
595Enable SELinux context support.
596.TP
597.B \-\-no-selinux
598Disable SELinux context support.
599.TP
600.B \-\-xattrs
601Enable extended attributes support.
602.TP
603.B \-\-no\-xattrs
604Disable extended attributes support.
605.TP
606.BI \-\-xattrs\-exclude= PATTERN
607Specify the exclude pattern for xattr keys.  \fIPATTERN\fR is a POSIX
608regular expression, e.g. \fB\-\-xattrs\-exclude='^user\.'\fR, to exclude
609attributes from the user namespace.
610.TP
611.BI \-\-xattrs\-include= PATTERN
612Specify the include pattern for xattr keys.  \fIPATTERN\fR is a POSIX
613regular expression.
614.SS Device selection and switching
615.TP
616\fB\-f\fR, \fB\-\-file\fR=\fIARCHIVE\fR
617Use archive file or device \fIARCHIVE\fR.  If this option is not
618given, \fBtar\fR will first examine the environment variable `TAPE'.
619If it is set, its value will be used as the archive name.  Otherwise,
620\fBtar\fR will assume the compiled-in default.  The default
621value can be inspected either using the
622.B \-\-show\-defaults
623option, or at the end of the \fBtar \-\-help\fR output.
624
625An archive name that has a colon in it specifies a file or device on a
626remote machine.  The part before the colon is taken as the machine
627name or IP address, and the part after it as the file or device
628pathname, e.g.:
629
630.EX
631--file=remotehost:/dev/sr0
632.EE
633
634An optional username can be prefixed to the hostname, placing a \fB@\fR
635sign between them.
636
637By default, the remote host is accessed via the
638.BR rsh (1)
639command.  Nowadays it is common to use
640.BR ssh (1)
641instead.  You can do so by giving the following command line option:
642
643.EX
644--rsh-command=/usr/bin/ssh
645.EE
646
647The remote machine should have the
648.BR rmt (8)
649command installed.  If its pathname does not match \fBtar\fR's
650default, you can inform \fBtar\fR about the correct pathname using the
651.B \-\-rmt\-command
652option.
653.TP
654\fB\-\-force\-local\fR
655Archive file is local even if it has a colon.
656.TP
657\fB\-F\fR, \fB\-\-info\-script\fR=\fICOMMAND\fR, \fB\-\-new\-volume\-script\fR=\fICOMMAND\fR
658Run \fICOMMAND\fR at the end of each tape (implies \fB\-M\fR).  The
659command can include arguments.  When started, it will inherit \fBtar\fR's
660environment plus the following variables:
661.RS
662.TP
663.B TAR_VERSION
664GNU \fBtar\fR version number.
665.TP
666.B TAR_ARCHIVE
667The name of the archive \fBtar\fR is processing.
668.TP
669.B TAR_BLOCKING_FACTOR
670Current blocking factor, i.e. number of 512-byte blocks in a record.
671.TP
672.B TAR_VOLUME
673Ordinal number of the volume \fBtar\fR is processing (set if
674reading a multi-volume archive).
675.TP
676.B TAR_FORMAT
677Format of the archive being processed.  One of:
678.BR gnu ,
679.BR oldgnu ,
680.BR posix ,
681.BR ustar ,
682.BR v7 .
683.TP
684.B TAR_SUBCOMMAND
685A short option (with a leading dash) describing the operation \fBtar\fR is
686executing.
687.TP
688.B TAR_FD
689File descriptor which can be used to communicate the new volume name
690to
691.BR tar .  
692.RE
693.RS
694
695If the info script fails, \fBtar\fR exits; otherwise, it begins writing
696the next volume.
697.RE
698.TP
699\fB\-L\fR, \fB\-\-tape\-length\fR=\fIN\fR
700Change tape after writing \fIN\fRx1024 bytes.  If \fIN\fR is followed
701by a size suffix (see the subsection
702.B Size suffixes
703below), the suffix specifies the multiplicative factor to be used
704instead of 1024.
705
706This option implies
707.BR \-M .
708.TP
709\fB\-M\fR, \fB\-\-multi\-volume\fR
710Create/list/extract multi-volume archive.
711.TP
712\fB\-\-rmt\-command\fR=\fICOMMAND\fR
713Use \fICOMMAND\fR instead of \fBrmt\fR when accessing remote
714archives.  See the description of the
715.B \-f
716option, above.
717.TP
718\fB\-\-rsh\-command\fR=\fICOMMAND\fR
719Use \fICOMMAND\fR instead of \fBrsh\fR when accessing remote
720archives.  See the description of the
721.B \-f
722option, above.
723.TP
724\fB\-\-volno\-file\fR=\fIFILE\fR
725When this option is used in conjunction with
726.BR \-\-multi\-volume ,
727.B tar
728will keep track of which volume of a multi-volume archive it is
729working in \fIFILE\fR. 
730.SS Device blocking
731.TP
732\fB\-b\fR, \fB\-\-blocking\-factor\fR=\fIBLOCKS\fR
733Set record size to \fIBLOCKS\fRx\fB512\fR bytes.
734.TP
735\fB\-B\fR, \fB\-\-read\-full\-records\fR
736When listing or extracting, accept incomplete input records after
737end-of-file marker.  
738.TP
739\fB\-i\fR, \fB\-\-ignore\-zeros\fR
740Ignore zeroed blocks in archive.  Normally two consecutive 512-blocks
741filled with zeroes mean EOF and tar stops reading after encountering
742them.  This option instructs it to read further and is useful when
743reading archives created with the \fB\-A\fR option.
744.TP
745\fB\-\-record\-size\fR=\fINUMBER\fR
746Set record size.  \fINUMBER\fR is the number of bytes per record.  It
747must be multiple of \fB512\fR.  It can can be suffixed with a \fBsize
748suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes.  See the
749subsection
750.BR "Size suffixes" ,
751for a list of valid suffixes.
752.SS Archive format selection
753.TP
754\fB\-H\fR, \fB\-\-format\fR=\fIFORMAT\fR
755Create archive of the given format.  Valid formats are:
756.RS
757.TP
758.B gnu
759GNU tar 1.13.x format
760.TP
761.B oldgnu
762GNU format as per tar <= 1.12.
763.TP
764\fBpax\fR, \fBposix\fR
765POSIX 1003.1-2001 (pax) format.
766.TP
767.B ustar
768POSIX 1003.1-1988 (ustar) format.
769.TP
770.B v7
771Old V7 tar format.
772.RE
773.TP
774\fB\-\-old\-archive\fR, \fB\-\-portability\fR
775Same as \fB\-\-format=v7\fR.
776.TP
777\fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]...
778Control pax keywords when creating \fBPAX\fR archives (\fB\-H
779pax\fR).  This option is equivalent to the \fB\-o\fR option of the
780.BR pax (1) utility.
781.TP
782\fB\-\-posix\fR
783Same as \fB\-\-format=posix\fR.
784.TP
785\fB\-V\fR, \fB\-\-label\fR=\fITEXT\fR
786Create archive with volume name \fITEXT\fR.  If listing or extracting,
787use \fITEXT\fR as a globbing pattern for volume name.
788.SS Compression options
789.TP
790\fB\-a\fR, \fB\-\-auto\-compress\fR
791Use archive suffix to determine the compression program.
792.TP
793\fB\-I\fR, \fB\-\-use\-compress\-program\fI=\fICOMMAND\fR
794Filter data through \fICOMMAND\fR.  It must accept the \fB\-d\fR
795option, for decompression.  The argument can contain command line
796options.
797.TP
798\fB\-j\fR, \fB\-\-bzip2\fR
799Filter the archive through
800.BR bzip2 (1).
801.TP
802\fB\-J\fR, \fB\-\-xz\fR
803Filter the archive through
804.BR xz (1).
805.TP
806\fB\-\-lzip\fR
807Filter the archive through
808.BR lzip (1).
809.TP
810\fB\-\-lzma\fR
811Filter the archive through
812.BR lzma (1).
813.TP
814\fB\-\-lzop\fR
815Filter the archive through
816.BR lzop (1).
817.TP
818\fB\-\-no\-auto\-compress\fR
819Do not use archive suffix to determine the compression program.
820.TP
821\fB\-z\fR, \fB\-\-gzip\fR, \fB\-\-gunzip\fR, \fB\-\-ungzip\fR
822Filter the archive through
823.BR gzip (1).
824.TP
825\fB\-Z\fR, \fB\-\-compress\fR, \fB\-\-uncompress\fR
826Filter the archive through
827.BR compress (1).
828.SS Local file selection
829.TP
830\fB\-\-add\-file\fR=\fIFILE\fR
831Add \fIFILE\fR to the archive (useful if its name starts with a dash).
832.TP
833\fB\-\-backup\fR[=\fICONTROL\fR]
834Backup before removal.  The \fICONTROL\fR argument, if supplied,
835controls the backup policy.  Its valid values are:
836.RS
837.TP
838.BR none ", " off
839Never make backups.
840.TP
841.BR t ", " numbered
842Make numbered backups.
843.TP
844.BR nil ", " existing
845Make numbered backups if numbered backups exist, simple backups otherwise.
846.TP
847.BR never ", " simple
848Always make simple backups
849.RS
850.RE
851
852If \fICONTROL\fR is not given, the value is taken from the
853.B VERSION_CONTROL
854environment variable.  If it is not set, \fBexisting\fR is assumed.
855.RE
856.TP
857\fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR
858Change to \fIDIR\fR before performing any operations.  This option is
859order-sensitive, i.e. it affects all options that follow.
860.TP
861\fB\-\-exclude\fR=\fIPATTERN\fR
862Exclude files matching \fIPATTERN\fR, a
863.BR glob (3)-style
864wildcard pattern.
865.TP
866\fB\-\-exclude\-backups\fR
867Exclude backup and lock files.
868.TP
869\fB\-\-exclude\-caches\fR
870Exclude contents of directories containing file \fBCACHEDIR.TAG\fR,
871except for the tag file itself.
872.TP
873\fB\-\-exclude\-caches\-all\fR
874Exclude directories containing file \fBCACHEDIR.TAG\fR and the file itself.
875.TP
876\fB\-\-exclude\-caches\-under\fR
877Exclude everything under directories containing \fBCACHEDIR.TAG\fR
878.TP
879\fB\-\-exclude\-ignore=\fIFILE\fR
880Before dumping a directory, see if it contains \fIFILE\fR.
881If so, read exclusion patterns from this file.  The patterns affect
882only the directory itself.
883.TP
884\fB\-\-exclude\-ignore\-recursive=\fIFILE\fR
885Same as \fB\-\-exclude\-ignore\fR, except that patterns from
886\fIFILE\fR affect both the directory and all its subdirectories.
887.TP
888\fB\-\-exclude\-tag\fR=\fIFILE\fR
889Exclude contents of directories containing \fIFILE\fR, except for
890\fIFILE\fR itself.
891.TP
892\fB\-\-exclude\-tag\-all\fR=\fIFILE\fR
893Exclude directories containing \fIFILE\fR.
894.TP
895\fB\-\-exclude\-tag\-under\fR=\fIFILE\fR
896Exclude everything under directories containing \fIFILE\fR.
897.TP
898\fB\-\-exclude\-vcs\fR
899Exclude version control system directories.
900.TP
901\fB\-\-exclude\-vcs\-ignores\fR
902Exclude files that match patterns read from VCS-specific ignore
903files.  Supported files are:
904.BR .cvsignore ,
905.BR .gitignore ,
906.BR .bzrignore ", and"
907.BR .hgignore .
908.TP
909\fB\-h\fR, \fB\-\-dereference\fR
910Follow symlinks; archive and dump the files they point to.
911.TP
912\fB\-\-hard\-dereference\fR
913Follow hard links; archive and dump the files they refer to.
914.TP
915\fB\-K\fR, \fB\-\-starting\-file\fR=\fIMEMBER\fR
916Begin at the given member in the archive.
917.TP
918\fB\-\-newer\-mtime\fR=\fIDATE\fR
919Work on files whose data changed after the \fIDATE\fR.  If \fIDATE\fR
920starts with \fB/\fR or \fB.\fR it is taken to be a file name; the
921mtime of that file is used as the date.
922.TP
923\fB\-\-no\-null\fR
924Disable the effect of the previous \fB\-\-null\fR option.
925.TP
926\fB\-\-no\-recursion\fR
927Avoid descending automatically in directories.
928.TP
929\fB\-\-no\-unquote\fR
930Do not unquote input file or member names.
931.TP
932\fB\-\-no\-verbatim\-files\-from\fR
933Treat each line read from a file list as if it were supplied in the
934command line.  I.e., leading and trailing whitespace is removed and,
935if the resulting string begins with a dash, it is treated as \fBtar\fR
936command line option.
937
938This is the default behavior.  The \fB\-\-no\-verbatim\-files\-from\fR
939option is provided as a way to restore it after
940\fB\-\-verbatim\-files\-from\fR option.
941
942This option is positional: it affects all \fB\-\-files\-from\fR
943options that occur after it in, until \fB\-\-verbatim\-files\-from\fR
944option or end of line, whichever occurs first.
945
946It is implied by the \fB\-\-no\-null\fR option.
947.TP
948\fB\-\-null\fR
949Instruct subsequent \fB\-T\fR options to read null-terminated names
950verbatim (disables special handling of names that start with a dash).
951
952See also \fB\-\-verbatim\-files\-from\fR.
953.TP
954\fB\-N\fR, \fB\-\-newer\fR=\fIDATE\fR, \fB\-\-after\-date\fR=\fIDATE\fR
955Only store files newer than DATE.  If \fIDATE\fR starts with \fB/\fR
956or \fB.\fR it is taken to be a file name; the ctime of that file is
957used as the date.
958.TP
959\fB\-\-one\-file\-system\fR
960Stay in local file system when creating archive.
961.TP
962\fB\-P\fR, \fB\-\-absolute\-names\fR
963Don't strip leading slashes from file names when creating archives.
964.TP
965\fB\-\-recursion\fR
966Recurse into directories (default).
967.TP
968\fB\-\-suffix\fR=\fISTRING\fR
969Backup before removal, override usual suffix.  Default suffix is \fB~\fR,
970unless overridden by environment variable \fBSIMPLE_BACKUP_SUFFIX\fR.
971.TP
972\fB\-T\fR, \fB\-\-files\-from\fR=\fIFILE\fR
973Get names to extract or create from \fIFILE\fR.
974
975Unless specified otherwise, the \fIFILE\fR must contain a list of
976names separated by ASCII \fBLF\fR (i.e. one name per line).  The
977names read are handled the same way as command line arguments.  They
978undergo quote removal and word splitting, and any string that starts
979with a \fB\-\fR is handled as \fBtar\fR command line option.
980
981If this behavior is undesirable, it can be turned off using the
982\fB\-\-verbatim\-files\-from\fR option.
983
984The \fB\-\-null\fR option instructs \fBtar\fR that the names in
985\fIFILE\fR are separated by ASCII \fBNUL\fR character, instead of
986\fBLF\fR.  It is useful if the list is generated by
987.BR find (1)
988.B \-print0
989predicate.
990.TP
991\fB\-\-unquote\fR
992Unquote file or member names (default).
993.TP
994\fB\-\-verbatim\-files\-from\fR
995Treat each line obtained from a file list as a file name, even if it
996starts with a dash.  File lists are supplied with the
997\fB\-\-files\-from\fR (\fB\-T\fR) option.  The default behavior is to
998handle names supplied in file lists as if they were typed in the
999command line, i.e. any names starting with a dash are treated as
1000\fBtar\fR options.  The \fB\-\-verbatim\-files\-from\fR option
1001disables this behavior.
1002
1003This option affects all \fB\-\-files\-from\fR options that occur after
1004it in the command line.  Its effect is reverted by the
1005\fB\-\-no\-verbatim\-files\-from} option.
1006
1007This option is implied by the \fB\-\-null\fR option.
1008
1009See also \fB\-\-add\-file\fR.
1010.TP
1011\fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
1012Exclude files matching patterns listed in FILE.
1013.SS  File name transformations
1014.TP
1015\fB\-\-strip\-components\fR=\fINUMBER\fR
1016Strip \fINUMBER\fR leading components from file names on extraction.
1017.TP
1018\fB\-\-transform\fR=\fIEXPRESSION\fR, \fB\-\-xform\fR=\fIEXPRESSION\fR
1019Use sed replace \fIEXPRESSION\fR to transform file names.
1020.SS File name matching options
1021These options affect both exclude and include patterns.
1022.TP
1023\fB\-\-anchored\fR
1024Patterns match file name start.
1025.TP
1026\fB\-\-ignore\-case\fR
1027Ignore case.
1028.TP
1029\fB\-\-no\-anchored\fR
1030Patterns match after any \fB/\fR (default for exclusion).
1031.TP
1032\fB\-\-no\-ignore\-case\fR
1033Case sensitive matching (default).
1034.TP
1035\fB\-\-no\-wildcards\fR
1036Verbatim string matching.
1037.TP
1038\fB\-\-no\-wildcards\-match\-slash\fR
1039Wildcards do not match \fB/\fR.
1040.TP
1041\fB\-\-wildcards\fR
1042Use wildcards (default for exclusion).
1043.TP
1044\fB\-\-wildcards\-match\-slash\fR
1045Wildcards match \fB/\fR (default for exclusion).
1046.SS Informative output
1047.TP
1048\fB\-\-checkpoint\fR[=\fIN\fR]
1049Display progress messages every \fIN\fRth record (default 10).
1050.TP
1051\fB\-\-checkpoint\-action\fR=\fIACTION\fR
1052Run \fIACTION\fR on each checkpoint.
1053.TP
1054\fB\-\-clamp\-mtime\fR
1055Only set time when the file is more recent than what was given with \-\-mtime.
1056.TP
1057\fB\-\-full\-time\fR
1058Print file time to its full resolution.
1059.TP
1060\fB\-\-index\-file\fR=\fIFILE\fR
1061Send verbose output to \fIFILE\fR.
1062.TP
1063\fB\-l\fR, \fB\-\-check\-links\fR
1064Print a message if not all links are dumped.
1065.TP
1066\fB\-\-no\-quote\-chars\fR=\fISTRING\fR
1067Disable quoting for characters from \fISTRING\fR.
1068.TP
1069\fB\-\-quote\-chars\fR=\fISTRING\fR
1070Additionally quote characters from \fISTRING\fR.
1071.TP
1072\fB\-\-quoting\-style\fR=\fISTYLE\fR
1073Set quoting style for file and member names.  Valid values for
1074\fISTYLE\fR are
1075.BR literal ,
1076.BR shell ,
1077.BR shell-always ,
1078.BR c ,
1079.BR c-maybe ,
1080.BR escape ,
1081.BR locale ,
1082.BR clocale .
1083.TP
1084\fB\-R\fR, \fB\-\-block\-number\fR
1085Show block number within archive with each message.
1086.TP
1087\fB\-\-show\-omitted\-dirs\fR
1088When listing or extracting, list each directory that does not match
1089search criteria.
1090.TP
1091\fB\-\-show\-transformed\-names\fR, \fB\-\-show\-stored\-names\fR
1092Show file or archive names after transformation by \fB\-\-strip\fR and
1093\fB\-\-transform\fR options.
1094.TP
1095\fB\-\-totals\fR[=\fISIGNAL\fR]
1096Print total bytes after processing the archive.  If \fISIGNAL\fR is
1097given, print total bytes when this signal is delivered.  Allowed
1098signals are:
1099.BR SIGHUP , 
1100.BR SIGQUIT ,
1101.BR SIGINT ,
1102.BR SIGUSR1 ", and"
1103.BR SIGUSR2 .
1104The \fBSIG\fR prefix can be omitted.
1105.TP
1106\fB\-\-utc\fR
1107Print file modification times in UTC.
1108.TP
1109\fB\-v\fR, \fB\-\-verbose\fR
1110Verbosely list files processed.
1111.TP
1112\fB\-\-warning\fR=\fIKEYWORD\fR
1113Enable or disable warning messages identified by \fIKEYWORD\fR.  The
1114messages are suppressed if \fIKEYWORD\fR is prefixed with \fBno\-\fR
1115and enabled otherwise.
1116
1117Multiple \fB\-\-warning\fR messages accumulate.
1118
1119Keywords controlling general \fBtar\fR operation:
1120.RS
1121.TP
1122.B all
1123Enable all warning messages.  This is the default.
1124.TP
1125.B none
1126Disable all warning messages.
1127.TP
1128.B filename-with-nuls
1129"%s: file name read contains nul character"
1130.TP
1131.B alone-zero-block
1132"A lone zero block at %s"
1133.HP
1134Keywords applicable for \fBtar --create\fR:
1135.TP
1136.B cachedir
1137"%s: contains a cache directory tag %s; %s"
1138.TP
1139.B file-shrank
1140"%s: File shrank by %s bytes; padding with zeros"
1141.TP
1142.B xdev
1143"%s: file is on a different filesystem; not dumped"
1144.TP
1145.B file-ignored
1146"%s: Unknown file type; file ignored"
1147.br
1148"%s: socket ignored"
1149.br
1150"%s: door ignored"
1151.TP
1152.B file-unchanged
1153"%s: file is unchanged; not dumped"
1154.TP
1155.B ignore-archive
1156"%s: file is the archive; not dumped"
1157.TP
1158.B file-removed
1159"%s: File removed before we read it"
1160.TP
1161.B file-changed
1162"%s: file changed as we read it"
1163.HP
1164Keywords applicable for \fBtar --extract\fR:
1165.TP
1166.B existing\-file
1167"%s: skipping existing file"
1168.TP
1169.B timestamp
1170"%s: implausibly old time stamp %s"
1171.br
1172"%s: time stamp %s is %s s in the future"
1173.TP
1174.B contiguous-cast
1175"Extracting contiguous files as regular files"
1176.TP
1177.B symlink-cast
1178"Attempting extraction of symbolic links as hard links"
1179.TP
1180.B unknown-cast
1181"%s: Unknown file type '%c', extracted as normal file"
1182.TP
1183.B ignore-newer
1184"Current %s is newer or same age"
1185.TP
1186.B unknown-keyword
1187"Ignoring unknown extended header keyword '%s'"
1188.TP
1189.B decompress-program
1190Controls verbose description of failures occurring when trying to run
1191alternative decompressor programs.  This warning is disabled by
1192default (unless \fB\-\-verbose\fR is used).  A common example of what
1193you can get when using this warning is:
1194
1195.EX
1196$ \fBtar --warning=decompress-program -x -f archive.Z
1197tar (child): cannot run compress: No such file or directory
1198tar (child): trying gzip
1199.EE
1200
1201This means that \fBtar\fR first tried to decompress
1202\fBarchive.Z\fR using \fBcompress\fR, and, when that
1203failed, switched to \fBgzip\fR.
1204.TP
1205.B record-size
1206"Record size = %lu blocks"
1207.HP
1208Keywords controlling incremental extraction:
1209.TP
1210.B rename-directory
1211"%s: Directory has been renamed from %s"
1212.br
1213"%s: Directory has been renamed"
1214.TP
1215.B new-directory
1216"%s: Directory is new"
1217.TP
1218.B xdev
1219"%s: directory is on a different device: not purging"
1220.TP
1221.B bad-dumpdir
1222"Malformed dumpdir: 'X' never used"
1223.RE
1224.TP
1225\fB\-w\fR, \fB\-\-interactive\fR, \fB\-\-confirmation\fR
1226Ask for confirmation for every action.
1227.SS Compatibility options
1228.TP
1229\fB\-o\fR
1230When creating, same as \fB\-\-old\-archive\fR.  When extracting, same
1231as \fB\-\-no\-same\-owner\fR.
1232.SS Size suffixes
1233.sp
1234.nf
1235.ta 8n 18n 42n
1236.ul
1237	Suffix	Units	Byte Equivalent
1238	b	Blocks	\fISIZE\fR x 512
1239	B	Kilobytes	\fISIZE\fR x 1024
1240	c	Bytes	\fISIZE\fR
1241	G	Gigabytes	\fISIZE\fR x 1024^3
1242	K	Kilobytes	\fISIZE\fR x 1024
1243	k	Kilobytes	\fISIZE\fR x 1024
1244	M	Megabytes	\fISIZE\fR x 1024^2
1245	P	Petabytes	\fISIZE\fR x 1024^5
1246	T	Terabytes	\fISIZE\fR x 1024^4
1247	w	Words	\fISIZE\fR x 2
1248.fi
1249.PP
1250.SH "RETURN VALUE"
1251Tar exit code indicates whether it was able to successfully perform
1252the requested operation, and if not, what kind of error occurred.
1253.TP
1254.B 0
1255Successful termination.
1256.TP
1257.B 1
1258.I Some files differ.
1259If tar was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR)
1260command line option, this means that some files in the archive differ
1261from their disk counterparts.  If tar was given one of the \fB\-\-create\fR,
1262\fB\-\-append\fR or \fB\-\-update\fR options, this exit code means
1263that some files were changed while being archived and so the resulting
1264archive does not contain the exact copy of the file set.
1265.TP
1266.B 2
1267.I Fatal error.
1268This means that some fatal, unrecoverable error occurred.
1269.PP
1270If a subprocess that had been invoked by
1271.B tar
1272exited with a nonzero exit code,
1273.B tar
1274itself exits with that code as well.  This can happen, for example, if
1275a compression option (e.g. \fB\-z\fR) was used and the external
1276compressor program failed.  Another example is
1277.B rmt
1278failure during backup to a remote device.
1279.SH "SEE ALSO"
1280.BR bzip2 (1),
1281.BR compress (1),
1282.BR gzip (1),
1283.BR lzma (1),
1284.BR lzop (1),
1285.BR rmt (8),
1286.BR symlink (7),
1287.BR tar (5),
1288.BR xz (1).
1289.PP
1290Complete \fBtar\fR manual: run
1291.B info tar
1292or use
1293.BR emacs (1)
1294info mode to read it.
1295.PP
1296Online copies of \fBGNU tar\fR documentation in various formats can be
1297found at:
1298.PP
1299.in +4
1300.B http://www.gnu.org/software/tar/manual
1301.SH "BUG REPORTS"
1302Report bugs to <bug\-tar@gnu.org>.
1303.SH COPYRIGHT
1304Copyright \(co 2013 Free Software Foundation, Inc.
1305.br
1306.na
1307License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
1308.br
1309.ad
1310This is free software: you are free to change and redistribute it.
1311There is NO WARRANTY, to the extent permitted by law.
1312.\" Local variables:
1313.\" eval: (add-hook 'write-file-hooks 'time-stamp)
1314.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
1315.\" time-stamp-format: "%:B %:d, %:y"
1316.\" time-stamp-end: "\""
1317.\" time-stamp-line-limit: 20
1318.\" end: