1 .\" Copyright (c) 1991, 1992, 1993 Free Software Foundation -*- nroff -*-
2 .\" See section COPYING for conditions for redistribution
4 .\" Written by John F. Woods <jfw@jfwhome.funhouse.com>
7 .\" from NetBSD: tar.1,v 1.8 1997/06/06 07:59:54 jeremy Exp
14 .Nd GNU tape archiver; manipulate "tar" archive files
18 .Op Cm bundled-options
19 .Op Ar [gnu-style-flags]
24 .Op Fl C Ar directory-name
29 so named for historical reasons; the
31 program creates, adds files to, or extracts files from an archive file
36 A tarfile is often a magnetic tape, but can be a floppy diskette or any
39 The first argument word of the
41 command line is usually a command word of bundled function and modifier
42 letters, optionally preceeded by a dash;
43 it must contain exactly one function letter from the set
51 for append, create, difference, replace, table of contents, update, and
52 extract (further described below). The command word can also contain other
53 function modifiers described below, some of which will take arguments from
54 the command line in the order they are specified in the command word (review
55 the EXAMPLES section). Functions and function modifiers can also be specified
56 with the GNU argument convention (preceeded by two dashes, one function or
57 modifier per word. Command-line arguments that specify files to
58 add to, extract from, or list from an archive may be given as shell
59 pattern matching strings.
61 Exactly one of the following functions must be specified.
63 .Bl -tag -width "--concatenate" -compact
67 Append the contents of named file, which must itself be a tar archive,
68 to the end of the archive (erasing the old end-of-archive block).
69 This has the effect of adding the files contained in the named file to
70 the first archive, rather than adding the second archive as an element
73 This option requires a rewritable tarfile,
74 and therefore does not work on quarter-inch cartridge tapes.
77 Create a new archive (or truncates an old one) and writes the named files
82 Find differences between files in the archive and corresponding files in
85 Delete named files from the archive (Does not work on quarter-inch tapes).
88 Append files to the end of an archive (Does not work on quarter-inch tapes).
91 List the contents of an archive; if filename arguments are given, only those
92 files are listed, otherwise the entire table of contents is listed.
95 Append the named files if the on-disk version has a modification date
96 more recent than their copy in the archive (if any). Does not work on
101 Extract files from an archive. The owner, modification time, and file
102 permissions are restored, if possible. If no
104 arguments are given, extract all the files in the archive. If a
106 argument matches the name of a directory on the tape, that directory and
107 its contents are extracted (as well as all directories under that directory).
108 If the archive contains multiple entries corresponding to the same file
111 command above), the last one extracted will overwrite all earlier versions.
116 may be combined arbitrarily; single-letter options may be bundled in with
117 the command word. Verbose options which take arguments will be
118 followed by the argument; single-letter options will consume
119 successive command line arguments (see the
123 .Bl -tag -width "--preserve-permissions" -compact
125 Prints a message listing and briefly describing all the command
127 .It Fl -atime-preserve
128 Restore the access times on files which are written to tape (note that
129 this will change the inode-change time!).
131 .It Fl -block-size Ar number
132 Sets the block size for reading or writing to N 512-byte blocks.
134 .It Fl -read-full-blocks
135 Re-assemble short reads into full blocks (for reading 4.2BSD pipes).
136 .It Fl C Ar directory
137 .It Fl -directory Ar directory
142 Print directory names while reading the archive.
143 .It Fl f Ar [hostname:]file
144 .It Fl -file Ar [hostname:]file
145 Read or write the specified
147 .Po default is Pa /dev/rst0 Pc .
154 to read or write the specified
156 on a remote machine. If the given
162 uses stdin or stdout.
164 .It Fl -info-script Ar file
165 .It Fl -new-volume-script Ar file
166 Run a script at the end of each archive volume (implies
169 Stop after all non-wildcard extraction targets have been found
173 Create/list/extract old GNU-format incremental backup.
175 .It Fl -listed-incremental Ar file
176 Create/list/extract new GNU-format incremental backup.
179 Don't write symlinks as symlinks; write the data of the files they name.
182 Ignore blocks of zeroes in archive (usually means End-Of-File).
183 .It Fl -ignore-failed-read
184 Don't exit with non-zero status on unreadable files.
186 .It Fl -keep-old-files
187 Keep files which already exist on disk; don't overwrite them from the archive.
189 .It Fl -starting-file Ar file
194 .It Fl -one-file-system
195 Stay in local filesystem when creating an archive (do not cross mount
198 .It Fl -tape-length Ar number
199 Change tapes after writing N*1024 bytes.
201 .It Fl -modification-time
202 Don't extract file modified time.
205 Create/list/extract multi-volume archive.
207 .It Fl -after-date Ar date
208 .It Fl -newer Ar date
209 Only store files newer than
214 Write a V7 format archive, rather than POSIX format.
217 Extract files to standard output.
219 .It Fl -same-permissions
220 .It Fl -preserve-permissions
221 Extract all protection information.
226 .It Fl -absolute-paths
227 Don't strip leading `/'s from file names.
229 .It Fl -record-number
230 Show record number within archive with each message.
232 Remove files after adding them to the archive.
235 .It Fl -preserve-order
236 List of names to extract is sorted to match archive.
239 Handle "sparse" files efficiently.
241 .It Fl -files-from Ar file
242 Get names of files to extract or create from
248 to expect null-terminated names; disables
251 Prints total bytes written with
255 Lists files written to archive with
259 lists file protection information along with file names with
261 .It Fl V Ar volume-name
262 .It Fl -label Ar volume-name
263 Create archive with the given
266 Print tar program version number.
270 Ask for confirmation for every action.
273 Attempt to verify the archive after writing it.
274 .It Fl -exclude Ar pattern
275 Exclude files matching the
277 (don't extract them, don't add them, don't list them).
279 .It Fl -exclude-from Ar file
280 Exclude files listed in
285 Filter the archive through
290 Filter the archive through
292 .It Fl -use-compress-program Ar program
293 Filter the archive through
297 to mean ``decompress'').
298 .It Fl -block-compress
299 Block the output of compression program for tapes or floppies
300 (otherwise writes will be of odd length, which device drivers may reject).
302 Specify tape drive and density.
304 Don't recurse into subdirectories when creating.
306 Unlink files before creating them.
309 To create an archive on tape drive
311 with a block size of 20
312 blocks, containing files named "bert" and "ernie", you can enter
313 .Dl tar cfb /dev/rst0 20 bert ernie
315 .Dl tar --create --file /dev/rst0 --block-size 20 bert ernie
320 flags both require arguments, which they take from the command line in
321 the order they were listed in the command word.
325 is the default device, and 20 is the default block
326 size, the above example could have simply been
329 To extract all the C sources and headers from an archive named
331 .Dl tar xf backup.tar "*.[ch]"
332 Note that the pattern must be quoted to prevent the shell from
333 attempting to expand it according the files in the current working
334 directory (the shell does not have access to the list of files in
335 the archive, of course).
337 To copy a file hierarchy while preserving metadata, type
338 .Dl tar cf - -C srcdir ". |" tar xpf "-C destdir"
340 To create a compressed archive on diskette, using gzip, use a command-line like
341 .Dl tar --block-compress -z -c -v -f /dev/rfd1a -b 36 tar/
342 Note that you cannot mix bundled flags and --style flags; you can use
343 single-letter flags in the manner above, rather than having to type
344 .Dl tar --block-compress --gzip --verbose --file /dev/rfd1a --block-size 20 tar/
346 The above-created diskette can be listed with
347 .Dl tar tvfbz /dev/rfd1a 36
349 To join two tar archives into a single archive, use
350 .Dl tar Af archive1.tar archive2.tar
351 which will add the files contained in archive2.tar onto the end of
352 archive1.tar (note that this can't be done by simply typing
353 .Dl cat archive2.tar >> archive1.tar
354 because of the end-of-file block at the end of a tar archive).
358 program examines the following environment variables:
359 .Bl -tag -width "POSIXLY-CORRECT"
360 .It Ev POSIXLY-CORRECT
363 will process flag arguments that appear in the file list.
364 If set in the environment, this flag causes
366 to consider the first
367 non-flag argument to terminate flag processing, as per the POSIX specification.
369 In interactive mode, a permissible response to the prompt is to
370 request to spawn a subshell, which will be "/bin/sh" unless the
374 Changes the default tape drive (which is still overridden by the
379 .Bl -tag -width "/dev/rst0"
381 The default tape drive.
383 .\" This next request is for sections 1, 6, 7 & 8 only
384 .\" (command return values (to shell) and fprintf/stderr type diagnostics)
393 The tar format has a rich history, dating back to Sixth Edition UNIX.
394 The current implementation of tar is the GNU implementation, which
395 originated as the public-domain tar written by John Gilmore.
397 A cast of thousands, including [as listed in the ChangeLog file in the
398 source] John Gilmore (author of original public
399 domain version), Jay Fenlason (first GNU author), Joy Kendall, Jim
400 Kingdon, David J. MacKenzie, Michael I Bushnell, Noah Friedman, and
401 innumerable others who have contributed fixes and additions.
405 feature does not work like historical tar programs, and is probably
410 command should work to join an arbitrary number of tar archives
411 together, but it does not; attempting to do so leaves the
412 end-of-archive blocks in place for the second and subsequent archives.
projects / pkgsrcv2.git / blob