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