1 .\" Copyright (c) 1991, 1992, 1993 Free Software Foundation -*- nroff -*-
2 .\" See /usr/src/gnu/COPYING for conditions of redistribution
4 .\" Written by John F. Woods <jfw@jfwhome.funhouse.com>
5 .\" Updated by Robert Eckardt <roberte@mep.ruhr-uni-bochum.de>
15 tape archiver; manipulate "tar" archive files
18 .Op [-] Ns Ar bundled-options Ar Args
19 .Op Ar gnu-style-flags
21 .Ar filenames | Fl C Ar directory-name
27 so named for historical reasons; the
29 program creates, adds files to, or extracts files from an archive file
34 A tarfile is often a magnetic tape, but can be a floppy diskette or any
37 The first argument word of the
39 command line is usually a command word of bundled function and modifier
40 letters, optionally preceded by a dash;
41 it must contain exactly one function letter from the set
49 for append, create, difference, replace, table of contents, update, and
50 extract (further described below). The command word can also contain other
51 function modifiers described below, some of which will take arguments from
52 the command line in the order they are specified in the command word (review
53 the EXAMPLES section). Functions and function modifiers can also be specified
54 with the GNU argument convention (preceded by two dashes, one function or
55 modifier per word. Command-line arguments that specify files to
56 add to, extract from, or list from an archive may be given as shell
57 pattern matching strings.
59 Exactly one of the following functions must be specified.
61 .Bl -tag -width "--concatenate" -compact
65 Append the contents of named file, which must itself be a tar archive,
66 to the end of the archive (erasing the old end-of-archive block).
67 This has the effect of adding the files contained in the named file to
68 the first archive, rather than adding the second archive as an element
71 This option requires a rewritable tarfile,
72 and therefore does not work on quarter-inch cartridge tapes.
75 Create a new archive (or truncates an old one) and writes the named files
80 Find differences between files in the archive and corresponding files in
83 Delete named files from the archive (Does not work on quarter-inch tapes).
86 Append files to the end of an archive (Does not work on quarter-inch tapes).
89 List the contents of an archive; if filename arguments are given, only those
90 files are listed, otherwise the entire table of contents is listed.
93 Append the named files if the on-disk version has a modification date
94 more recent than their copy in the archive (if any). Does not work on
99 Extract files from an archive. The owner, modification time, and file
100 permissions are restored, if possible. If no
102 arguments are given, extract all the files in the archive. If a
104 argument matches the name of a directory on the tape, that directory and
105 its contents are extracted (as well as all directories under that directory).
106 If the archive contains multiple entries corresponding to the same file
109 command above), the last one extracted will overwrite all earlier versions.
114 may be combined arbitrarily; single-letter options may be bundled in with
115 the command word. Verbose options which take arguments will be
116 followed by the argument; single-letter options will consume
117 successive command line arguments (see the
121 .Bl -tag -width "--preserve-permissions" -compact
123 Prints a message listing and briefly describing all the command
126 .It Fl -atime-preserve
127 Restore the access times on files which are written to tape (note that
128 this will change the inode-change time!).
130 .It Fl -block-size Ar number
131 Sets the block size for reading or writing to
135 .It Fl -read-full-blocks
136 Re-assemble short reads into full blocks (for reading 4.2BSD pipes).
137 .It Fl C Ar directory
138 .It Fl -directory Ar directory
141 before processing the remaining arguments.
143 Print number of buffer reads/writes while reading/writing the archive.
144 .It Fl f Ar [hostname:]file
145 .It Fl -file Ar [hostname:]file
146 Read or write the specified
148 (default is /dev/rsa0). If a
154 to read or write the specified
156 on a remote machine. "-" may be used is a filename, for reading
157 or writing to/from stdin/stdout.
159 Archive file is local even if it has a colon
161 .It Fl -info-script Ar file
162 .It Fl -new-volume-script Ar file
163 Run a script at the end of each archive volume (implies
166 Stop after all non-wildcard extraction targets have been found
170 Create/list/extract old GNU-format incremental backup.
172 .It Fl -listed-incremental Ar file
173 Create/list/extract new GNU-format incremental backup.
176 Don't write symlinks as symlinks; write the data of the files they name.
179 Ignore blocks of zeroes in archive (usually means End-Of-File).
180 .It Fl -ignore-failed-read
181 Don't exit with non-zero status on unreadable files.
183 .It Fl -keep-old-files
184 Keep files which already exist on disk; don't overwrite them from the archive.
186 .It Fl -starting-file Ar file
191 .It Fl -one-file-system
192 Stay in local filesystem when creating an archive (do not cross mount
195 .It Fl -tape-length Ar number
196 Change tapes after writing
200 .It Fl -modification-time
201 Don't extract file modified time.
204 Create/list/extract multi-volume archive.
207 Don't recurse into subdirectories when creating.
208 .It Fl -volno-file Ar file
209 File name with volume number to start with.
211 .It Fl -after-date Ar date
212 .It Fl -newer Ar date
213 Only store files with creation time newer than
215 .It Fl -newer-mtime Ar date
216 Only store files with modification time newer than
221 Write a V7 format archive, rather than POSIX format.
224 Extract files to standard output.
226 .It Fl -same-permissions
227 .It Fl -preserve-permissions
228 Extract all protection information.
233 .It Fl -absolute-paths
234 Don't strip leading `/' from file names.
236 .It Fl -record-number
237 Show record number within archive with each message.
239 Remove files after adding them to the archive.
242 .It Fl -preserve-order
243 List of names to extract is sorted to match archive.
244 .It Fl -show-omitted-dirs
245 Show directories which were omitted while processing the archive.
248 Handle "sparse" files efficiently.
250 .It Fl -files-from Ar file
251 Get names of files to extract or create from
257 to expect null-terminated names; disables
260 Prints total bytes written with
264 Lists files written to archive with
268 lists file protection information along with file names with
270 .It Fl V Ar volume-name
271 .It Fl -label Ar volume-name
272 Create archive with the given
277 program version number.
281 Ask for confirmation for every action.
284 Attempt to verify the archive after writing it.
285 .It Fl -exclude Ar pattern
286 Exclude files matching the
288 (don't extract them, don't add them, don't list them).
290 .It Fl -exclude-from Ar file
291 Exclude files listed in
296 Filter the archive through
301 Filter the archive through
306 Filter the archive through
308 .It Fl -use-compress-program Ar program
309 Filter the archive through
313 to mean ``decompress'').
314 .It Fl -block-compress
315 Block the output of compression program for tapes or floppies
316 (otherwise writes will be of odd length, which device drivers may reject).
318 Specify tape drive and density.
320 Unlink files before creating them.
323 To create an archive on tape drive /dev/rsa0 with a block size of 20
324 blocks, containing files named "bert" and "ernie", you can enter
325 .Dl tar cfb /dev/rsa0 20 bert ernie
327 .Dl tar\ --create\ --file\ /dev/rsa0\ --block-size\ 20\ bert\ ernie
332 flags both require arguments, which they take from the command line in
333 the order they were listed in the command word.
335 Because /dev/rsa0 is the default device, and 20 is the default block
336 size, the above example could have simply been
339 To extract all the C sources and headers from an archive named
341 .Dl tar xf backup.tar '*.[ch]'
342 Note that the pattern must be quoted to prevent the shell from
343 attempting to expand it according the files in the current working
344 directory (the shell does not have access to the list of files in
345 the archive, of course).
347 To move file hierarchies, use a command line like this:
349 tar -cf - -C srcdir . | tar xpf - -C destdir
352 To create a compressed archive on diskette, using gzip, use a command-line like
353 .Dl tar --block-compress -z -c -v -f /dev/rfd1a -b 36 tar/
355 Note that you cannot mix bundled flags and --style flags; you can use
356 single-letter flags in the manner above, rather than having to type
357 .Dl tar --block-compress --gzip --verbose --file /dev/rfd1a --block-size 20 tar/
359 The above-created diskette can be listed with
360 .Dl tar tvfbz /dev/rfd1a 36
362 To join two tar archives into a single archive, use
363 .Dl tar Af archive1.tar archive2.tar
364 which will add the files contained in archive2.tar onto the end of
365 archive1.tar (note that this can't be done by simply typing
366 .Dl cat archive2.tar >> archive1.tar
367 because of the end-of-file block at the end of a tar archive).
369 To archive all files from the directory srcdir, which were modified
370 after Feb. 9th 1997, 13:00 h, use
371 .Dl tar\ -c\ -f\ backup.tar\ --newer-mtime\ 'Feb\ 9\ 13:15\ 1997'\ srcdir/
373 Other possible time specifications are '02/09/97 13:15',
374 \&'1997-02-09 13:15', '13:15 9 Feb 1997', '9 Feb 1997 13:15',
375 \&'Feb. 9, 1997 1:15pm', '09-Feb', '3 weeks ago' or 'May first Sunday'.
376 To specify the correct time zone use either e.g. `13:15 CEST' or `13:15+200'.
381 program examines the following environment variables.
382 .Bl -tag -width "POSIXLY_CORRECT"
386 will process flag arguments that appear in the file list.
387 If set in the environment, this causes
389 to consider the first
390 non-flag argument to terminate flag processing, as per the POSIX specification.
392 In interactive mode, a permissible response to the prompt is to
393 request to spawn a subshell, which will be "/bin/sh" unless the SHELL variable
396 Changes tar's default tape drive (which is still overridden by the
401 .Bl -tag -width "/dev/rsa0"
403 The default tape drive.
405 .\" This next request is for sections 1, 6, 7 & 8 only
406 .\" (command return values (to shell) and fprintf/stderr type diagnostics)
417 The tar format has a rich history, dating back to Sixth Edition UNIX.
418 The current implementation of
420 is the GNU implementation, which
421 originated as the public-domain tar written by John Gilmore.
423 A cast of thousands, including [as listed in the ChangeLog file in the
426 (author of original public domain version),
431 .An David J. MacKenzie ,
432 .An Michael I Bushnell ,
434 and innumerable others who have contributed fixes and additions.
436 Man page obtained by the
438 group from the NetBSD 1.0 release.
442 feature does not work like historical tar programs, and is probably
447 command should work to join an arbitrary number of tar archives
448 together, but it does not; attempting to do so leaves the
449 end-of-archive blocks in place for the second and subsequent archives.
projects / FreeBSD / FreeBSD.git / blob