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>
7 .\" $FreeBSD: src/gnu/usr.bin/tar/tar.1,v 1.22.2.13 2003/02/23 18:08:58 keramida Exp $
8 .\" $DragonFly: src/gnu/usr.bin/tar/Attic/tar.1,v 1.2 2003/06/17 04:25:49 dillon Exp $
15 .Nd "tape archiver; manipulate ""tar"" archive files"
18 .Op Oo Fl Oc Ns Ar bundled-options Ar Args
19 .Op Ar gnu-style-flags
20 .Op Ar filenames | Fl C Ar directory-name
26 so named for historical reasons; the
28 program creates, adds files to, or extracts files from an archive file
35 is often a magnetic tape, but can be a floppy diskette or any
38 The first argument word of the
40 command line is usually a command word of bundled function and modifier
41 letters, optionally preceded by a dash;
42 it must contain exactly one function letter from the set
55 .Em table of contents ,
59 (further described below).
60 The command word can also contain other function modifiers described below,
61 some of which will take arguments from the command line in the order they
62 are specified in the command word (review the
65 Functions and function modifiers can also be specified
66 with the GNU argument convention (preceded by two dashes, one function or
68 Command-line arguments that specify files to
69 add to, extract from, or list from an archive may be given as shell
70 pattern matching strings.
72 Exactly one of the following functions must be specified.
74 .Bl -tag -width "--concatenate" -compact
78 Append the contents of named file, which must itself be a
81 to the end of the archive (erasing the old end-of-archive block).
82 This has the effect of adding the files contained in the named file to
83 the first archive, rather than adding the second archive as an element
86 This option requires a rewritable
88 and therefore does not work on quarter-inch cartridge tapes.
91 Create a new archive (or truncates an old one) and writes the named files
96 Find differences between files in the archive and corresponding files in
99 Delete named files from the archive.
100 (Does not work on quarter-inch tapes).
103 Append files to the end of an archive.
104 (Does not work on quarter-inch tapes).
107 List the contents of an archive; if
109 arguments are given, only those
110 files are listed, otherwise the entire table of contents is listed.
113 Append the named files if the on-disk version has a modification date
114 more recent than their copy in the archive (if any).
115 Does not work on quarter-inch tapes.
119 Extract files from an archive.
120 The owner, modification time, and file permissions are restored, if possible.
123 arguments are given, extract all the files in the archive.
126 argument matches the name of a directory on the tape, that directory and
127 its contents are extracted (as well as all directories under that directory).
128 If the archive contains multiple entries corresponding to the same file
131 command above), the last one extracted will overwrite all earlier versions.
136 may be combined arbitrarily; single-letter options may be bundled in with
138 Verbose options which take arguments will be
139 followed by the argument; single-letter options will consume
140 successive command line arguments (see the
144 .Bl -tag -width "--preserve-permissions" -compact
146 Prints a message listing and briefly describing all the command
149 .It Fl -atime-preserve
150 Restore the access times on files which are written to tape (note that
151 this will change the inode-change time!).
153 .It Fl -block-size Ar number
154 Sets the block size for reading or writing to
158 .It Fl -read-full-blocks
159 Re-assemble short reads into full blocks (for reading
162 .It Fl C Ar directory
163 .It Fl -directory Ar directory
166 before processing the remaining arguments.
168 Print number of buffer reads/writes while reading/writing the archive.
170 .Oo Ar hostname : Oc Ns Ar file
173 .Oo Ar hostname : Oc Ns Ar file
175 Read or write the specified
185 to read or write the specified
189 may be used as a filename, for reading
190 or writing to/from stdin/stdout.
192 Archive file is local even if it has a colon.
194 .It Fl -info-script Ar file
195 .It Fl -new-volume-script Ar file
196 Run a script at the end of each archive volume (implies
199 Stop after all non-wildcard extraction targets have been found
203 Create/list/extract old GNU-format incremental backup.
205 .It Fl -listed-incremental Ar file
206 Create/list/extract new GNU-format incremental backup.
209 Don't write symlinks as symlinks; write the data of the files they name.
212 Ignore blocks of zeroes in archive (usually means End-Of-File).
213 .It Fl -ignore-failed-read
214 Don't exit with non-zero status on unreadable files.
220 Filter the archive through
223 .It Fl -keep-old-files
224 Keep files which already exist on disk; don't overwrite them from the archive.
226 .It Fl -starting-file Ar file
231 .It Fl -one-file-system
232 Stay in local file system when creating an archive (do not cross mount
235 .It Fl -tape-length Ar number
236 Change tapes after writing
240 .It Fl -modification-time
241 Don't extract file modified time.
244 Create/list/extract multi-volume archive.
247 Don't recurse into subdirectories when creating.
248 .It Fl -volno-file Ar file
249 File name with volume number to start with.
251 .It Fl -after-date Ar date
252 .It Fl -newer Ar date
253 Only store files with creation time newer than
255 .It Fl -newer-mtime Ar date
256 Only store files with modification time newer than
261 Write a V7 format archive, rather than POSIX format.
264 Extract files to standard output.
266 .It Fl -same-permissions
267 .It Fl -preserve-permissions
268 Extract all protection information.
273 .It Fl -absolute-paths
278 .It Fl -record-number
279 Show record number within archive with each message.
281 Remove files after adding them to the archive.
284 .It Fl -preserve-order
285 List of names to extract is sorted to match archive.
286 .It Fl -show-omitted-dirs
287 Show directories which were omitted while processing the archive.
295 .It Fl -files-from Ar file
296 Get names of files to extract or create from
302 to expect null-terminated names; disables
305 Prints total bytes written with
310 Unlink files before creating them.
313 Lists files written to archive with
317 lists file protection information along with file names with
319 .It Fl V Ar volume-name
320 .It Fl -label Ar volume-name
321 Create archive with the given
326 program version number.
330 Ask for confirmation for every action.
333 Attempt to verify the archive after writing it.
334 .It Fl -exclude Ar pattern
335 Exclude files matching the
337 (don't extract them, don't add them, don't list them).
339 .It Fl -exclude-from Ar file
340 Exclude files listed in
345 Filter the archive through
350 Filter the archive through
352 .It Fl -use-compress-program Ar program
353 Filter the archive through
359 .It Fl -block-compress
360 Block the output of compression program for tapes or floppies
361 (otherwise writes will be of odd length, which device drivers may reject).
363 .Op Cm 0 Ns - Ns Cm 7 Ns
366 Specify tape drive and density.
369 The environment variable
371 can hold a set of default options for
373 These options are interpreted first and can be overwritten by explicit command
376 To create an archive on tape drive
378 with a block size of 20 blocks, containing files named
383 .Dl "tar cfb /dev/sa0 20 bert ernie"
385 .Dl "tar --create --file /dev/sa0 --block-size 20 bert ernie"
390 flags both require arguments, which they take from the command line in
391 the order they were listed in the command word.
395 is the default device, and 20 is the default block
396 size, the above example could have simply been
397 .Dl "tar c bert ernie"
399 To extract all the C sources and headers from an archive named
402 .Dl "tar xf backup.tar '*.[ch]'"
403 Note that the pattern must be quoted to prevent the shell from
404 attempting to expand it according the files in the current working
405 directory (the shell does not have access to the list of files in
406 the archive, of course).
408 To move file hierarchies, use a command line like this:
410 tar -cf - -C srcdir . | tar xpf - -C destdir
413 To create a compressed archive on diskette, using
415 use a command-line like
416 .Dl "tar --block-compress -z -c -v -f /dev/fd1a -b 36 tar/"
418 Note that you cannot mix bundled flags and
421 single-letter flags in the manner above, rather than having to type
422 .Dl "tar --block-compress --gzip --verbose --file /dev/fd1a --block-size 20 tar/"
424 The above-created diskette can be listed with
425 .Dl "tar tvfbz /dev/fd1a 36"
429 archives into a single archive, use
430 .Dl "tar Af archive1.tar archive2.tar"
431 which will add the files contained in
435 (note that this can't be done by simply typing
436 .Dl "cat archive2.tar >> archive1.tar"
437 because of the end-of-file block at the end of a
441 To archive all files from the directory
444 after Feb. 9th 1997, 13:00 h, use
445 .Dl "tar -c -f backup.tar --newer-mtime 'Feb 9 13:15 1997' srcdir/"
447 Other possible time specifications are
448 .Sq "02/09/97 13:15" ,
449 .Sq "1997-02-09 13:15" ,
450 .Sq "13:15 9 Feb 1997" ,
451 .Sq "9 Feb 1997 13:15" ,
452 .Sq "Feb. 9, 1997 1:15pm" ,
456 .Sq "May first Sunday" .
457 To specify the correct time zone use either e.g.\&
464 program examines the following environment variables.
465 .Bl -tag -width "POSIXLY_CORRECT"
466 .It Ev POSIXLY_CORRECT
469 will process flag arguments that appear in the file list.
470 If set in the environment, this causes
472 to consider the first
473 non-flag argument to terminate flag processing, as per the POSIX specification.
475 In interactive mode, a permissible response to the prompt is to
476 request to spawn a subshell, which will be
484 default tape drive (which is still overridden by the
488 The TAR_RSH environment variable allows you to override the default
489 shell used as the transport for
493 .Bl -tag -width "/dev/sa0"
495 The default tape drive.
505 maintainer has now chosen
509 compression option in GNU
514 option is for compatibility with Solaris's
525 format has a rich history, dating back to Sixth Edition
527 The current implementation of
529 is the GNU implementation, which
530 originated as the public-domain
536 A cast of thousands, including [as listed in the
540 (author of original public domain version),
545 .An David J. MacKenzie ,
546 .An Michael I Bushnell ,
548 and innumerable others who have contributed fixes and additions.
550 Man page obtained by the
558 feature does not work like historical
560 programs, and is probably untrustworthy.
564 command should work to join an arbitrary number of
567 together, but it does not; attempting to do so leaves the
568 end-of-archive blocks in place for the second and subsequent archives.
572 file format is a semi fixed width field format, and the field
573 for device numbers were designed for 16 bit (8 major, 8 minor)
574 and can not absorb our 32 bit (8 major, 16+8 minor) numbers.
projects / dragonfly.git / blob