1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
|
.\" Copyright (c) 1991, 1992, 1993 Free Software Foundation -*- nroff -*-
.\" See /usr/src/gnu/COPYING for conditions of redistribution
.\"
.\" Written by John F. Woods <jfw@jfwhome.funhouse.com>
.\" Updated by Robert Eckardt <roberte@mep.ruhr-uni-bochum.de>
.\"
.\" $FreeBSD$
.\"
.Dd December 23, 2000
.Os
.Dt TAR 1
.Sh NAME
.Nm tar
.Nd "tape archiver; manipulate ""tar"" archive files"
.Sh SYNOPSIS
.Nm
.Op Oo Fl Oc Ns Ar bundled-options Ar Args
.Op Ar gnu-style-flags
.Op Ar filenames | Fl C Ar directory-name
.Ar ...
.Sh DESCRIPTION
.Nm Tar
is short for
.Dq tape archiver ,
so named for historical reasons; the
.Nm
program creates, adds files to, or extracts files from an archive file
in
.Nm
format, called a
.Ar tarfile .
A
.Ar tarfile
is often a magnetic tape, but can be a floppy diskette or any
regular disk file.
.Pp
The first argument word of the
.Nm
command line is usually a command word of bundled function and modifier
letters, optionally preceded by a dash;
it must contain exactly one function letter from the set
.Cm A ,
.Cm c ,
.Cm d ,
.Cm r ,
.Cm t ,
.Cm u ,
.Cm x ,
for
.Em append ,
.Em create ,
.Em difference ,
.Em replace ,
.Em table of contents ,
.Em update ,
and
.Em extract
(further described below).
The command word can also contain other function modifiers described below,
some of which will take arguments from the command line in the order they
are specified in the command word (review the
.Sx EXAMPLES
section).
Functions and function modifiers can also be specified
with the GNU argument convention (preceded by two dashes, one function or
modifier per word.
Command-line arguments that specify files to
add to, extract from, or list from an archive may be given as shell
pattern matching strings.
.Sh FUNCTIONS
Exactly one of the following functions must be specified.
.Pp
.Bl -tag -width "--concatenate" -compact
.It Fl A
.It Fl -catenate
.It Fl "-concatenate"
Append the contents of named file, which must itself be a
.Nm
archive,
to the end of the archive (erasing the old end-of-archive block).
This has the effect of adding the files contained in the named file to
the first archive, rather than adding the second archive as an element
of the first.
.Em Note :
This option requires a rewritable
.Ar tarfile ,
and therefore does not work on quarter-inch cartridge tapes.
.It Fl c
.It Fl -create
Create a new archive (or truncates an old one) and writes the named files
to it.
.It Fl d
.It Fl -diff
.It Fl -compare
Find differences between files in the archive and corresponding files in
the file system.
.It Fl -delete
Delete named files from the archive.
(Does not work on quarter-inch tapes).
.It Fl r
.It Fl -append
Append files to the end of an archive.
(Does not work on quarter-inch tapes).
.It Fl t
.It Fl -list
List the contents of an archive; if
.Ar filename
arguments are given, only those
files are listed, otherwise the entire table of contents is listed.
.It Fl u
.It Fl -update
Append the named files if the on-disk version has a modification date
more recent than their copy in the archive (if any).
Does not work on quarter-inch tapes.
.It Fl x
.It Fl -extract
.It Fl -get
Extract files from an archive.
The owner, modification time, and file permissions are restored, if possible.
If no
.Ar file
arguments are given, extract all the files in the archive.
If a
.Ar filename
argument matches the name of a directory on the tape, that directory and
its contents are extracted (as well as all directories under that directory).
If the archive contains multiple entries corresponding to the same file
(see the
.Fl -append
command above), the last one extracted will overwrite all earlier versions.
.El
.Sh OPTIONS
The other options to
.Nm
may be combined arbitrarily; single-letter options may be bundled in with
the command word.
Verbose options which take arguments will be
followed by the argument; single-letter options will consume
successive command line arguments (see the
.Sx EXAMPLES
below).
.Pp
.Bl -tag -width "--preserve-permissions" -compact
.It Fl -help
Prints a message listing and briefly describing all the command
options to
.Nm .
.It Fl -atime-preserve
Restore the access times on files which are written to tape (note that
this will change the inode-change time!).
.It Fl b
.It Fl -block-size Ar number
Sets the block size for reading or writing to
.Ar number
* 512-byte blocks.
.It Fl B
.It Fl -read-full-blocks
Re-assemble short reads into full blocks (for reading
.Bx 4.2
pipes).
.It Fl C Ar directory
.It Fl -directory Ar directory
Change to
.Ar directory
before processing the remaining arguments.
.It Fl -checkpoint
Print number of buffer reads/writes while reading/writing the archive.
.It Fl f Xo
.Oo Ar hostname : Oc Ns Ar file
.Xc
.It Fl -file Xo
.Oo Ar hostname : Oc Ns Ar file
.Xc
Read or write the specified
.Ar file
(default is
.Pa /dev/sa0 ) .
If a
.Ar hostname
is specified,
.Nm
will use
.Xr rmt 8
to read or write the specified
.Ar file
on a remote machine.
.Dq Ar -
may be used as a filename, for reading
or writing to/from stdin/stdout.
.It Fl -force-local
Archive file is local even if it has a colon.
.It Fl F Ar file
.It Fl -info-script Ar file
.It Fl -new-volume-script Ar file
Run a script at the end of each archive volume (implies
.Fl M ) .
.It Fl -fast-read
Stop after all non-wildcard extraction targets have been found
in the archive.
.It Fl G
.It Fl -incremental
Create/list/extract old GNU-format incremental backup.
.It Fl g Ar file
.It Fl -listed-incremental Ar file
Create/list/extract new GNU-format incremental backup.
.It Fl h
.It Fl -dereference
Don't write symlinks as symlinks; write the data of the files they name.
.It Fl i
.It Fl -ignore-zeros
Ignore blocks of zeroes in archive (usually means End-Of-File).
.It Fl -ignore-failed-read
Don't exit with non-zero status on unreadable files.
.It Fl j
.It Fl y
.It Fl -bzip
.It Fl -bzip2
.It Fl -bunzip2
Filter the archive through
.Xr bzip2 1 .
.It Fl k
.It Fl -keep-old-files
Keep files which already exist on disk; don't overwrite them from the archive.
.It Fl K Ar file
.It Fl -starting-file Ar file
Begin at
.Ar file
in the archive.
.It Fl l
.It Fl -one-file-system
Stay in local filesystem when creating an archive (do not cross mount
points).
.It Fl L Ar number
.It Fl -tape-length Ar number
Change tapes after writing
.Ar number
* 1024 bytes.
.It Fl m
.It Fl -modification-time
Don't extract file modified time.
.It Fl M
.It Fl -multi-volume
Create/list/extract multi-volume archive.
.It Fl n
.It Fl -norecurse
Don't recurse into subdirectories when creating.
.It Fl -volno-file Ar file
File name with volume number to start with.
.It Fl N Ar date
.It Fl -after-date Ar date
.It Fl -newer Ar date
Only store files with creation time newer than
.Ar date .
.It Fl -newer-mtime Ar date
Only store files with modification time newer than
.Ar date .
.It Fl o
.It Fl -old-archive
.It Fl -portability
Write a V7 format archive, rather than POSIX format.
.It Fl O
.It Fl -to-stdout
Extract files to standard output.
.It Fl p
.It Fl -same-permissions
.It Fl -preserve-permissions
Extract all protection information.
.It Fl -preserve
Has the effect of
.Fl p s .
.It Fl P
.It Fl -absolute-paths
Don't strip leading
.Ql /
from file names.
.It Fl R
.It Fl -record-number
Show record number within archive with each message.
.It Fl -remove-files
Remove files after adding them to the archive.
.It Fl s
.It Fl -same-order
.It Fl -preserve-order
List of names to extract is sorted to match archive.
.It Fl -show-omitted-dirs
Show directories which were omitted while processing the archive.
.It Fl S
.It Fl -sparse
Handle
.Dq sparse
files efficiently.
.It Fl T Ar file
.It Fl I Ar file
.It Fl -files-from Ar file
Get names of files to extract or create from
.Ar file ,
one per line.
.It Fl -null
Modifies behavior of
.Fl T
to expect null-terminated names; disables
.Fl C .
.It Fl -totals
Prints total bytes written with
.Fl -create .
.It Fl U
.It Fl -unlink
.It Fl -unlink-first
Unlink files before creating them.
.It Fl v
.It Fl -verbose
Lists files written to archive with
.Fl -create
or extracted with
.Fl -extract ;
lists file protection information along with file names with
.Fl -list .
.It Fl V Ar volume-name
.It Fl -label Ar volume-name
Create archive with the given
.Ar volume-name .
.It Fl -version
Print
.Nm
program version number.
.It Fl w
.It Fl -interactive
.It Fl -confirmation
Ask for confirmation for every action.
.It Fl W
.It Fl -verify
Attempt to verify the archive after writing it.
.It Fl -exclude Ar pattern
Exclude files matching the
.Ar pattern
(don't extract them, don't add them, don't list them).
.It Fl X Ar file
.It Fl -exclude-from Ar file
Exclude files listed in
.Ar file .
.It Fl Z
.It Fl -compress
.It Fl -uncompress
Filter the archive through
.Xr compress 1 .
.It Fl z
.It Fl -gzip
.It Fl -gunzip
Filter the archive through
.Xr gzip 1 .
.It Fl -use-compress-program Ar program
Filter the archive through
.Ar program
(which must accept
.Fl d
to mean
.Dq decompress ) .
.It Fl -block-compress
Block the output of compression program for tapes or floppies
(otherwise writes will be of odd length, which device drivers may reject).
.It Fl Xo
.Op Cm 0 Ns - Ns Cm 7 Ns
.Op Cm lmh
.Xc
Specify tape drive and density.
.El
.Sh ENVIRONMENT
The environment variable
.Ev TAR_OPTIONS
can hold a set of default options for
.Nm .
These options are interpreted first and can be overwritten by explicit command
line parameters.
.Sh EXAMPLES
To create an archive on tape drive
.Pa /dev/sa0
with a block size of 20 blocks, containing files named
.Pa bert
and
.Pa ernie ,
you can enter
.Dl "tar cfb /dev/sa0 20 bert ernie"
or
.Dl "tar --create --file /dev/sa0 --block-size 20 bert ernie"
Note that the
.Fl f
and
.Fl b
flags both require arguments, which they take from the command line in
the order they were listed in the command word.
.Pp
Because
.Pa /dev/sa0
is the default device, and 20 is the default block
size, the above example could have simply been
.Dl "tar c bert ernie"
.Pp
To extract all the C sources and headers from an archive named
.Pa backup.tar ,
type
.Dl "tar xf backup.tar '*.[ch]'"
Note that the pattern must be quoted to prevent the shell from
attempting to expand it according the files in the current working
directory (the shell does not have access to the list of files in
the archive, of course).
.Pp
To move file hierarchies, use a command line like this:
.Bd -literal
tar -cf - -C srcdir . | tar xpf - -C destdir
.Ed
.Pp
To create a compressed archive on diskette, using
.Xr gzip 1 ,
use a command-line like
.Dl "tar --block-compress -z -c -v -f /dev/fd1a -b 36 tar/"
.Pp
Note that you cannot mix bundled flags and
.Fl -style
flags; you can use
single-letter flags in the manner above, rather than having to type
.Dl "tar --block-compress --gzip --verbose --file /dev/fd1a --block-size 20 tar/"
.Pp
The above-created diskette can be listed with
.Dl "tar tvfbz /dev/fd1a 36"
.Pp
To join two
.Nm
archives into a single archive, use
.Dl "tar Af archive1.tar archive2.tar"
which will add the files contained in
.Pa archive2.tar
onto the end of
.Pa archive1.tar
(note that this can't be done by simply typing
.Dl "cat archive2.tar >> archive1.tar"
because of the end-of-file block at the end of a
.Nm
archive).
.Pp
To archive all files from the directory
.Pa srcdir ,
which were modified
after Feb. 9th 1997, 13:00 h, use
.Dl "tar -c -f backup.tar --newer-mtime 'Feb 9 13:15 1997' srcdir/"
.Pp
Other possible time specifications are
.Sq "02/09/97 13:15" ,
.Sq "1997-02-09 13:15" ,
.Sq "13:15 9 Feb 1997" ,
.Sq "9 Feb 1997 13:15" ,
.Sq "Feb. 9, 1997 1:15pm" ,
.Sq "09-Feb" ,
.Sq "3 weeks ago"
or
.Sq "May first Sunday" .
To specify the correct time zone use either e.g.\&
.Sq "13:15 CEST"
or
.Sq "13:15+200" .
.Sh ENVIRONMENT
The
.Nm
program examines the following environment variables.
.Bl -tag -width "POSIXLY_CORRECT"
.It Ev POSIXLY_CORRECT
Normally,
.Nm
will process flag arguments that appear in the file list.
If set in the environment, this causes
.Nm
to consider the first
non-flag argument to terminate flag processing, as per the POSIX specification.
.It Ev SHELL
In interactive mode, a permissible response to the prompt is to
request to spawn a subshell, which will be
.Pa /bin/sh
unless the
.Ev SHELL
variable is set.
.It Ev TAPE
Changes
.Nm Ns 's
default tape drive (which is still overridden by the
.Fl f
flag).
.It TAR_RSH
The TAR_RSH environment variable allows you to override the default
shell used as the transport for
.Nm .
.El
.Sh FILES
.Bl -tag -width "/dev/sa0"
.It Pa /dev/sa0
The default tape drive.
.El
.Sh COMPATIBILITY
The
.Fl y
is a
.Fx
localism.
The GNU
.Nm
maintainer has now chosen
.Fl j
as the offical
.Xr bzip2 1
compression option in GNU
.Nm
1.13.18 and later.
The
.Fl I
option is for compatibility with Solaris's
.Nm .
.Sh SEE ALSO
.Xr bzip2 1 ,
.Xr compress 1 ,
.Xr gzip 1 ,
.Xr pax 1 ,
.Xr rmt 8
.Sh HISTORY
The
.Nm
format has a rich history, dating back to Sixth Edition
.Ux .
The current implementation of
.Nm
is the GNU implementation, which
originated as the public-domain
.Nm
written by
.An John Gilmore .
.Sh AUTHORS
.An -nosplit
A cast of thousands, including [as listed in the
.Pa ChangeLog
file in the source]
.An John Gilmore
(author of original public domain version),
.An Jay Fenlason
(first GNU author),
.An Joy Kendall ,
.An Jim Kingdon ,
.An David J. MacKenzie ,
.An Michael I Bushnell ,
.An Noah Friedman ,
and innumerable others who have contributed fixes and additions.
.Pp
Man page obtained by the
.Fx
group from the
.Nx 1.0
release.
.Sh BUGS
The
.Fl C
feature does not work like historical
.Nm
programs, and is probably untrustworthy.
.Pp
The
.Fl A
command should work to join an arbitrary number of
.Nm
archives
together, but it does not; attempting to do so leaves the
end-of-archive blocks in place for the second and subsequent archives.
.Pp
The
.Nm
file format is a semi fixed width field format, and the field
for device numbers were designed for 16 bit (8 major, 8 minor)
and cannot absorb our 32 bit (8 major, 16+8 minor) numbers.
|