1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header
5 @settitle GNU tar @value{VERSION}
13 @c ======================================================================
14 @c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF,
15 @c as decided by @set symbols. The PUBLISH rendition does not show
16 @c notes or marks asking for revision. Most users will prefer having more
17 @c information, even if this information is not fully revised for adequacy,
18 @c so DISTRIB is the default for tar distributions. The PROOF rendition
19 @c show all marks to the point of ugliness, but is nevertheless useful to
20 @c those working on the manual itself.
21 @c ======================================================================
32 @set RENDITION The book, version
36 @set RENDITION FTP release, version
40 @set RENDITION Proof reading version
43 @c ---------------------------------------------------------------------
44 @c The @FIXME's, @UNREVISED and @c comments are part Fran@,{c}ois's work
45 @c plan. These annotations are somewhat precious to him; he asks that I
46 @c do not alter them inconsiderately. Much work is needed for GNU tar
47 @c internals (the sources, the programs themselves). Revising the
48 @c adequacy of the manual while revising the sources, and cleaning them
49 @c both at the same time, seems to him like a good way to proceed.
50 @c ---------------------------------------------------------------------
52 @c Output marks for nodes needing revision, but not in PUBLISH rendition.
57 @emph{(This message will disappear, once this node revised.)}
62 @c Output various FIXME information only in PROOF rendition.
68 @strong{<FIXME>} \string\ @strong{</>}
73 @macro FIXME-ref{string}
76 @strong{<REF>} \string\ @strong{</>}
81 @macro FIXME-pxref{string}
84 @strong{<PXREF>} \string\ @strong{</>}
89 @macro FIXME-xref{string}
92 @strong{<XREF>} \string\ @strong{</>}
97 @c @macro option{entry}
99 @c @opindex{--\entry\}
103 @set op-absolute-names @kbd{--absolute-names} (@kbd{-P})
104 @set ref-absolute-names @ref{absolute}
105 @set xref-absolute-names @xref{absolute}
106 @set pxref-absolute-names @pxref{absolute}
108 @set op-after-date @kbd{--after-date=@var{date}} (@kbd{--newer=@var{date}}, @kbd{-N @var{date}})
109 @set ref-after-date @ref{after}
110 @set xref-after-date @xref{after}
111 @set pxref-after-date @pxref{after}
113 @set op-append @kbd{--append} (@kbd{-r})
114 @set ref-append @ref{add}
115 @set xref-append @xref{add}
116 @set pxref-append @pxref{add}
118 @set op-atime-preserve @kbd{--atime-preserve}
119 @set ref-atime-preserve @ref{Attributes}
120 @set xref-atime-preserve @xref{Attributes}
121 @set pxref-atime-preserve @pxref{Attributes}
123 @set op-backup @kbd{--backup}
124 @set ref-backup @ref{Backup options}
125 @set xref-backup @xref{Backup options}
126 @set pxref-backup @pxref{Backup options}
128 @set op-block-number @kbd{--block-number} (@kbd{-R})
129 @set ref-block-number @ref{verbose}
130 @set xref-block-number @xref{verbose}
131 @set pxref-block-number @pxref{verbose}
133 @set op-blocking-factor @kbd{--blocking-factor=@var{512-size}} (@kbd{-b @var{512-size}})
134 @set ref-blocking-factor @ref{Blocking Factor}
135 @set xref-blocking-factor @xref{Blocking Factor}
136 @set pxref-blocking-factor @pxref{Blocking Factor}
138 @set op-bzip2 @kbd{--bzip2} (@kbd{-j})
139 @set ref-bzip2 @ref{gzip}
140 @set xref-bzip2 @xref{gzip}
141 @set pxref-bzip2 @pxref{gzip}
143 @set op-checkpoint @kbd{--checkpoint}
144 @set ref-checkpoint @ref{verbose}
145 @set xref-checkpoint @xref{verbose}
146 @set pxref-checkpoint @pxref{verbose}
148 @set op-compare @kbd{--compare} (@kbd{--diff}, @kbd{-d})
149 @set ref-compare @ref{compare}
150 @set xref-compare @xref{compare}
151 @set pxref-compare @pxref{compare}
153 @set op-compress @kbd{--compress} (@kbd{--uncompress}, @kbd{-Z})
154 @set ref-compress @ref{gzip}
155 @set xref-compress @xref{gzip}
156 @set pxref-compress @pxref{gzip}
158 @set op-concatenate @kbd{--concatenate} (@kbd{--catenate}, @kbd{-A})
159 @set ref-concatenate @ref{concatenate}
160 @set xref-concatenate @xref{concatenate}
161 @set pxref-concatenate @pxref{concatenate}
163 @set op-create @kbd{--create} (@kbd{-c})
164 @set ref-create @ref{create}
165 @set xref-create @xref{create}
166 @set pxref-create @pxref{create}
168 @set op-delete @kbd{--delete}
169 @set ref-delete @ref{delete}
170 @set xref-delete @xref{delete}
171 @set pxref-delete @pxref{delete}
173 @set op-dereference @kbd{--dereference} (@kbd{-h})
174 @set ref-dereference @ref{dereference}
175 @set xref-dereference @xref{dereference}
176 @set pxref-dereference @pxref{dereference}
178 @set op-directory @kbd{--directory=@var{directory}} (@kbd{-C @var{directory}})
179 @set ref-directory @ref{directory}
180 @set xref-directory @xref{directory}
181 @set pxref-directory @pxref{directory}
183 @set op-exclude @kbd{--exclude=@var{pattern}}
184 @set ref-exclude @ref{exclude}
185 @set xref-exclude @xref{exclude}
186 @set pxref-exclude @pxref{exclude}
188 @set op-exclude-from @kbd{--exclude-from=@var{file-of-patterns}} (@kbd{-X @var{file-of-patterns}})
189 @set ref-exclude-from @ref{exclude}
190 @set xref-exclude-from @xref{exclude}
191 @set pxref-exclude-from @pxref{exclude}
193 @set op-extract @kbd{--extract} (@kbd{--get}, @kbd{-x})
194 @set ref-extract @ref{extract}
195 @set xref-extract @xref{extract}
196 @set pxref-extract @pxref{extract}
198 @set op-file @kbd{--file=@var{archive-name}} (@kbd{-f @var{archive-name}})
199 @set ref-file @ref{file}
200 @set xref-file @xref{file}
201 @set pxref-file @pxref{file}
203 @set op-files-from @kbd{--files-from=@var{file-of-names}} (@kbd{-T @var{file-of-names}})
204 @set ref-files-from @ref{files}
205 @set xref-files-from @xref{files}
206 @set pxref-files-from @pxref{files}
208 @set op-force-local @kbd{--force-local}
209 @set ref-force-local @ref{file}
210 @set xref-force-local @xref{file}
211 @set pxref-force-local @pxref{file}
213 @set op-group @kbd{--group=@var{group}}
214 @set ref-group @ref{Option Summary}
215 @set xref-group @xref{Option Summary}
216 @set pxref-group @pxref{Option Summary}
218 @set op-gzip @kbd{--gzip} (@kbd{--gunzip}, @kbd{--ungzip}, @kbd{-z})
219 @set ref-gzip @ref{gzip}
220 @set xref-gzip @xref{gzip}
221 @set pxref-gzip @pxref{gzip}
223 @set op-help @kbd{--help}
224 @set ref-help @ref{help}
225 @set xref-help @xref{help}
226 @set pxref-help @pxref{help}
228 @set op-ignore-failed-read @kbd{--ignore-failed-read}
229 @set ref-ignore-failed-read @ref{create options}
230 @set xref-ignore-failed-read @xref{create options}
231 @set pxref-ignore-failed-read @pxref{create options}
233 @set op-ignore-zeros @kbd{--ignore-zeros} (@kbd{-i})
234 @set ref-ignore-zeros @ref{Reading}
235 @set xref-ignore-zeros @xref{Reading}
236 @set pxref-ignore-zeros @pxref{Reading}
238 @set op-incremental @kbd{--incremental} (@kbd{-G})
239 @set ref-incremental @ref{Inc Dumps}
240 @set xref-incremental @xref{Inc Dumps}
241 @set pxref-incremental @pxref{Inc Dumps}
243 @set op-info-script @kbd{--info-script=@var{script-name}} (@kbd{--new-volume-script=@var{script-name}}, @kbd{-F @var{script-name}})
244 @set ref-info-script @ref{Multi-Volume Archives}
245 @set xref-info-script @xref{Multi-Volume Archives}
246 @set pxref-info-script @pxref{Multi-Volume Archives}
248 @set op-interactive @kbd{--interactive} (@kbd{-w})
249 @set ref-interactive @ref{interactive}
250 @set xref-interactive @xref{interactive}
251 @set pxref-interactive @pxref{interactive}
253 @set op-keep-old-files @kbd{--keep-old-files} (@kbd{-k})
254 @set ref-keep-old-files @ref{Writing}
255 @set xref-keep-old-files @xref{Writing}
256 @set pxref-keep-old-files @pxref{Writing}
258 @set op-label @kbd{--label=@var{archive-label}} (@kbd{-V @var{archive-label}})
259 @set ref-label @ref{label}
260 @set xref-label @xref{label}
261 @set pxref-label @pxref{label}
263 @set op-list @kbd{--list} (@kbd{-t})
264 @set ref-list @ref{list}
265 @set xref-list @xref{list}
266 @set pxref-list @pxref{list}
268 @set op-listed-incremental @kbd{--listed-incremental=@var{snapshot-file}} (@kbd{-g @var{snapshot-file}})
269 @set ref-listed-incremental @ref{Inc Dumps}
270 @set xref-listed-incremental @xref{Inc Dumps}
271 @set pxref-listed-incremental @pxref{Inc Dumps}
273 @set op-mode @kbd{--mode=@var{permissions}}
274 @set ref-mode @ref{Option Summary}
275 @set xref-mode @xref{Option Summary}
276 @set pxref-mode @pxref{Option Summary}
278 @set op-multi-volume @kbd{--multi-volume} (@kbd{-M})
279 @set ref-multi-volume @ref{Multi-Volume Archives}
280 @set xref-multi-volume @xref{Multi-Volume Archives}
281 @set pxref-multi-volume @pxref{Multi-Volume Archives}
283 @set op-newer-mtime @kbd{--newer-mtime=@var{date}}
284 @set ref-newer-mtime @ref{after}
285 @set xref-newer-mtime @xref{after}
286 @set pxref-newer-mtime @pxref{after}
288 @set op-no-recursion @kbd{--no-recursion}
289 @set ref-no-recursion @ref{recurse}
290 @set xref-no-recursion @xref{recurse}
291 @set pxref-no-recursion @pxref{recurse}
293 @set op-no-same-owner @kbd{--no-same-owner}
294 @set ref-no-same-owner @ref{Attributes}
295 @set xref-no-same-owner @xref{Attributes}
296 @set pxref-no-same-owner @pxref{Attributes}
298 @set op-no-same-permissions @kbd{--no-same-permissions}
299 @set ref-no-same-permissions @ref{Attributes}
300 @set xref-no-same-permissions @xref{Attributes}
301 @set pxref-no-same-permissions @pxref{Attributes}
303 @set op-null @kbd{--null}
304 @set ref-null @ref{files}
305 @set xref-null @xref{files}
306 @set pxref-null @pxref{files}
308 @set op-numeric-owner @kbd{--numeric-owner}
309 @set ref-numeric-owner @ref{Attributes}
310 @set xref-numeric-owner @xref{Attributes}
311 @set pxref-numeric-owner @pxref{Attributes}
313 @set op-old-archive @kbd{--old-archive} (@kbd{-o})
314 @set ref-old-archive @ref{old}
315 @set xref-old-archive @xref{old}
316 @set pxref-old-archive @pxref{old}
318 @set op-one-file-system @kbd{--one-file-system} (@kbd{-l})
319 @set ref-one-file-system @ref{one}
320 @set xref-one-file-system @xref{one}
321 @set pxref-one-file-system @pxref{one}
323 @set op-overwrite @kbd{--overwrite}
324 @set ref-overwrite @ref{Overwrite Old Files}
325 @set xref-overwrite @xref{Overwrite Old Files}
326 @set pxref-overwrite @pxref{Overwrite Old Files}
328 @set op-owner @kbd{--owner=@var{user}}
329 @set ref-owner @ref{Option Summary}
330 @set xref-owner @xref{Option Summary}
331 @set pxref-owner @pxref{Option Summary}
333 @set op-posix @kbd{--posix}
334 @set ref-posix @ref{posix}
335 @set xref-posix @xref{posix}
336 @set pxref-posix @pxref{posix}
338 @set op-preserve @kbd{--preserve}
339 @set ref-preserve @ref{Attributes}
340 @set xref-preserve @xref{Attributes}
341 @set pxref-preserve @pxref{Attributes}
343 @set op-record-size @kbd{--record-size=@var{size}}
344 @set ref-record-size @ref{Blocking}
345 @set xref-record-size @xref{Blocking}
346 @set pxref-record-size @pxref{Blocking}
348 @set op-recursive-unlink @kbd{--recursive-unlink}
349 @set ref-recursive-unlink @ref{Writing}
350 @set xref-recursive-unlink @xref{Writing}
351 @set pxref-recursive-unlink @pxref{Writing}
353 @set op-read-full-records @kbd{--read-full-records} (@kbd{-B})
354 @set ref-read-full-records @ref{Blocking}
355 @set xref-read-full-records @xref{Blocking}
356 @set pxref-read-full-records @pxref{Blocking}
357 @c FIXME: or should it be Reading, or Blocking Factor
359 @set op-remove-files @kbd{--remove-files}
360 @set ref-remove-files @ref{Writing}
361 @set xref-remove-files @xref{Writing}
362 @set pxref-remove-files @pxref{Writing}
364 @set op-rsh-command @kbd{rsh-command=@var{command}}
366 @set op-same-order @kbd{--same-order} (@kbd{--preserve-order}, @kbd{-s})
367 @set ref-same-order @ref{Scarce}
368 @set xref-same-order @xref{Scarce}
369 @set pxref-same-order @pxref{Scarce}
370 @c FIXME: or should it be Reading, or Attributes?
372 @set op-same-owner @kbd{--same-owner}
373 @set ref-same-owner @ref{Attributes}
374 @set xref-same-owner @xref{Attributes}
375 @set pxref-same-owner @pxref{Attributes}
377 @set op-same-permissions @kbd{--same-permissions} (@kbd{--preserve-permissions}, @kbd{-p})
378 @set ref-same-permissions @ref{Attributes}
379 @set xref-same-permissions @xref{Attributes}
380 @set pxref-same-permissions @pxref{Attributes}
381 @c FIXME: or should it be Writing?
383 @set op-show-omitted-dirs @kbd{--show-omitted-dirs}
384 @set ref-show-omitted-dirs @ref{verbose}
385 @set xref-show-omitted-dirs @xref{verbose}
386 @set pxref-show-omitted-dirs @pxref{verbose}
388 @set op-sparse @kbd{--sparse} (@kbd{-S})
389 @set ref-sparse @ref{sparse}
390 @set xref-sparse @xref{sparse}
391 @set pxref-sparse @pxref{sparse}
393 @set op-starting-file @kbd{--starting-file=@var{name}} (@kbd{-K @var{name}})
394 @set ref-starting-file @ref{Scarce}
395 @set xref-starting-file @xref{Scarce}
396 @set pxref-starting-file @pxref{Scarce}
398 @set op-suffix @kbd{--suffix=@var{suffix}}
399 @set ref-suffix @ref{Backup options}
400 @set xref-suffix @xref{Backup options}
401 @set pxref-suffix @pxref{Backup options}
403 @set op-tape-length @kbd{--tape-length=@var{1024-size}} (@kbd{-L @var{1024-size}})
404 @set ref-tape-length @ref{Using Multiple Tapes}
405 @set xref-tape-length @xref{Using Multiple Tapes}
406 @set pxref-tape-length @pxref{Using Multiple Tapes}
408 @set op-to-stdout @kbd{--to-stdout} (@kbd{-O})
409 @set ref-to-stdout @ref{Writing}
410 @set xref-to-stdout @xref{Writing}
411 @set pxref-to-stdout @pxref{Writing}
413 @set op-totals @kbd{--totals}
414 @set ref-totals @ref{verbose}
415 @set xref-totals @xref{verbose}
416 @set pxref-totals @pxref{verbose}
418 @set op-touch @kbd{--touch} (@kbd{-m})
419 @set ref-touch @ref{Writing}
420 @set xref-touch @xref{Writing}
421 @set pxref-touch @pxref{Writing}
423 @set op-unlink-first @kbd{--unlink-first} (@kbd{-U})
424 @set ref-unlink-first @ref{Writing}
425 @set xref-unlink-first @xref{Writing}
426 @set pxref-unlink-first @pxref{Writing}
428 @set op-update @kbd{--update} (@kbd{-u})
429 @set ref-update @ref{update}
430 @set xref-update @xref{update}
431 @set pxref-update @pxref{update}
433 @set op-use-compress-prog @kbd{--use-compress-prog=@var{program}}
434 @set ref-use-compress-prog @ref{gzip}
435 @set xref-use-compress-prog @xref{gzip}
436 @set pxref-use-compress-prog @pxref{gzip}
438 @set op-verbose @kbd{--verbose} (@kbd{-v})
439 @set ref-verbose @ref{verbose}
440 @set xref-verbose @xref{verbose}
441 @set pxref-verbose @pxref{verbose}
443 @set op-verify @kbd{--verify} (@kbd{-W})
444 @set ref-verify @ref{verify}
445 @set xref-verify @xref{verify}
446 @set pxref-verify @pxref{verify}
448 @set op-version @kbd{--version}
449 @set ref-version @ref{help}
450 @set xref-version @xref{help}
451 @set pxref-version @pxref{help}
453 @set op-volno-file @kbd{--volno-file=@var{file-of-number}}
454 @set ref-volno-file @ref{Using Multiple Tapes}
455 @set xref-volno-file @xref{Using Multiple Tapes}
456 @set pxref-volno-file @pxref{Using Multiple Tapes}
458 @c Put everything in one index (arbitrarily chosen to be the concept index).
469 This manual is for @acronym{GNU} @command{tar} (version
470 @value{VERSION}, @value{UPDATED}), which creates and extracts files
473 Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
474 2003 Free Software Foundation, Inc.
477 Permission is granted to copy, distribute and/or modify this document
478 under the terms of the GNU Free Documentation License, Version 1.1 or
479 any later version published by the Free Software Foundation; with the
480 Invariant Sections being "GNU General Public License", with the
481 Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts
482 as in (a) below. A copy of the license is included in the section
483 entitled "GNU Free Documentation License".
485 (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
486 this GNU Manual. Buying copies from GNU Press supports the FSF in
487 developing GNU and promoting software freedom.''
491 @dircategory Archiving
493 * Tar: (tar). Making tape (or disk) archives.
496 @dircategory Individual utilities
498 * tar: (tar)tar invocation. Invoking @acronym{GNU} @command{tar}
501 @shorttitlepage @acronym{GNU} @command{tar}
504 @title @acronym{GNU} tar: an archiver tool
505 @subtitle @value{RENDITION} @value{VERSION}, @value{UPDATED}
506 @author Melissa Weisshaus, Jay Fenlason,
507 @author Thomas Bushnell, n/BSG, Amy Gorin
508 @c he said to remove it: Fran@,{c}ois Pinard
509 @c i'm thinking about how the author page *should* look. -mew 2may96
512 @vskip 0pt plus 1filll
518 @top @acronym{GNU} tar: an archiver tool
522 @cindex file archival
523 @cindex archiving files
525 The first part of this master menu lists the major nodes in this Info
526 document. The rest of the menu lists all the lower level nodes.
529 @c The master menu, created with texinfo-master-menu, goes here.
530 @c (However, getdate.texi's menu is interpolated by hand.)
539 * Date input formats::
542 * Free Software Needs Free Documentation::
543 * Copying This Manual::
547 --- The Detailed Node Listing ---
551 * Book Contents:: What this Book Contains
552 * Definitions:: Some Definitions
553 * What tar Does:: What @command{tar} Does
554 * Naming tar Archives:: How @command{tar} Archives are Named
556 * Authors:: @acronym{GNU} @command{tar} Authors
557 * Reports:: Reporting bugs or suggestions
559 Tutorial Introduction to @command{tar}
562 * stylistic conventions::
563 * basic tar options:: Basic @command{tar} Operations and Options
564 * frequent operations::
565 * Two Frequent Options::
566 * create:: How to Create Archives
567 * list:: How to List Archives
568 * extract:: How to Extract Members from an Archive
571 Two Frequently Used Options
577 How to Create Archives
579 * prepare for examples::
580 * Creating the archive::
589 How to Extract Members from an Archive
591 * extracting archives::
596 Invoking @acronym{GNU} @command{tar}
599 * using tar options::
606 The Three Option Styles
608 * Mnemonic Options:: Mnemonic Option Style
609 * Short Options:: Short Option Style
610 * Old Options:: Old Option Style
611 * Mixing:: Mixing Option Styles
613 All @command{tar} Options
615 * Operation Summary::
617 * Short Option Summary::
619 @acronym{GNU} @command{tar} Operations
629 Advanced @acronym{GNU} @command{tar} Operations
638 How to Add Files to Existing Archives: @code{--append}
640 * appending files:: Appending Files to an Archive
647 Options Used by @code{--create}
649 * Ignore Failed Read::
651 Options Used by @code{--extract}
653 * Reading:: Options to Help Read Archives
654 * Writing:: Changing How @command{tar} Writes Files
655 * Scarce:: Coping with Scarce Resources
657 Options to Help Read Archives
659 * read full records::
662 Changing How @command{tar} Writes Files
664 * Dealing with Old Files::
665 * Overwrite Old Files::
669 * Modification Times::
670 * Setting Access Permissions::
671 * Writing to Standard Output::
674 Coping with Scarce Resources
679 Performing Backups and Restoring Files
681 * Full Dumps:: Using @command{tar} to Perform Full Dumps
682 * Inc Dumps:: Using @command{tar} to Perform Incremental Dumps
683 * incremental and listed-incremental:: The Incremental Options
684 * Backup Levels:: Levels of Backups
685 * Backup Parameters:: Setting Parameters for Backups and Restoration
686 * Scripted Backups:: Using the Backup Scripts
687 * Scripted Restoration:: Using the Restore Script
689 Setting Parameters for Backups and Restoration
691 * backup-specs example:: An Example Text of @file{Backup-specs}
692 * Script Syntax:: Syntax for @file{Backup-specs}
694 Choosing Files and Names for @command{tar}
696 * file:: Choosing the Archive's Name
697 * Selecting Archive Members::
698 * files:: Reading Names from a File
699 * exclude:: Excluding Some Files
701 * after:: Operating Only on New Files
702 * recurse:: Descending into Directories
703 * one:: Crossing Filesystem Boundaries
705 Reading Names from a File
711 * controlling pattern-patching with exclude::
712 * problems with exclude::
714 Crossing Filesystem Boundaries
716 * directory:: Changing Directory
717 * absolute:: Absolute File Names
721 * General date syntax:: Common rules.
722 * Calendar date items:: 19 Dec 1994.
723 * Time of day items:: 9:20pm.
724 * Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}, ...
725 * Day of week items:: Monday and others.
726 * Relative items in date strings:: next tuesday, 2 years ago.
727 * Pure numbers in date strings:: 19931219, 1440.
728 * Authors of getdate:: Bellovin, Eggert, Salz, Berets, et al.
730 Controlling the Archive Format
732 * Portability:: Making @command{tar} Archives More Portable
733 * Compression:: Using Less Space through Compression
734 * Attributes:: Handling File Attributes
735 * Standard:: The Standard Format
736 * Extensions:: @acronym{GNU} Extensions to the Archive Format
737 * cpio:: Comparison of @command{tar} and @command{cpio}
739 Making @command{tar} Archives More Portable
741 * Portable Names:: Portable Names
742 * dereference:: Symbolic Links
743 * old:: Old V7 Archives
744 * posix:: @sc{posix} archives
745 * Checksumming:: Checksumming Problems
746 * Large or Negative Values:: Large files, negative time stamps, etc.
748 Using Less Space through Compression
750 * gzip:: Creating and Reading Compressed Archives
751 * sparse:: Archiving Sparse Files
753 Tapes and Other Archive Media
755 * Device:: Device selection and switching
756 * Remote Tape Server::
757 * Common Problems and Solutions::
758 * Blocking:: Blocking
759 * Many:: Many archives on one tape
760 * Using Multiple Tapes:: Using Multiple Tapes
761 * label:: Including a Label in the Archive
767 * Format Variations:: Format Variations
768 * Blocking Factor:: The Blocking Factor of an Archive
770 Many Archives on One Tape
772 * Tape Positioning:: Tape Positions and Tape Marks
773 * mt:: The @command{mt} Utility
777 * Multi-Volume Archives:: Archives Longer than One Tape or Disk
778 * Tape Files:: Tape Files
782 * GNU Free Documentation License:: License for copying this manual
788 @chapter Introduction
790 @acronym{GNU} @command{tar} creates
791 and manipulates (@dfn{archives}) which are actually collections of
792 many other files; the program provides users with an organized and
793 systematic method for controlling a large amount of data.
794 The name ``tar'' originally came from the phrase ``Tape ARchive'', but
795 archives need not (and these days, typically do not) reside on tapes.
798 * Book Contents:: What this Book Contains
799 * Definitions:: Some Definitions
800 * What tar Does:: What @command{tar} Does
801 * Naming tar Archives:: How @command{tar} Archives are Named
803 * Authors:: @acronym{GNU} @command{tar} Authors
804 * Reports:: Reporting bugs or suggestions
808 @section What this Book Contains
810 The first part of this chapter introduces you to various terms that will
811 recur throughout the book. It also tells you who has worked on @acronym{GNU}
812 @command{tar} and its documentation, and where you should send bug reports
815 The second chapter is a tutorial (@pxref{Tutorial}) which provides a
816 gentle introduction for people who are new to using @command{tar}. It is
817 meant to be self contained, not requiring any reading from subsequent
818 chapters to make sense. It moves from topic to topic in a logical,
819 progressive order, building on information already explained.
821 Although the tutorial is paced and structured to allow beginners to
822 learn how to use @command{tar}, it is not intended solely for beginners.
823 The tutorial explains how to use the three most frequently used
824 operations (@samp{create}, @samp{list}, and @samp{extract}) as well as
825 two frequently used options (@samp{file} and @samp{verbose}). The other
826 chapters do not refer to the tutorial frequently; however, if a section
827 discusses something which is a complex variant of a basic concept, there
828 may be a cross reference to that basic concept. (The entire book,
829 including the tutorial, assumes that the reader understands some basic
830 concepts of using a Unix-type operating system; @pxref{Tutorial}.)
832 The third chapter presents the remaining five operations, and
833 information about using @command{tar} options and option syntax.
835 @FIXME{this sounds more like a @acronym{GNU} Project Manuals Concept [tm] more
836 than the reality. should think about whether this makes sense to say
837 here, or not.} The other chapters are meant to be used as a
838 reference. Each chapter presents everything that needs to be said
839 about a specific topic.
841 One of the chapters (@pxref{Date input formats}) exists in its
842 entirety in other @acronym{GNU} manuals, and is mostly self-contained.
843 In addition, one section of this manual (@pxref{Standard}) contains a
844 big quote which is taken directly from @command{tar} sources.
846 In general, we give both the long and short (abbreviated) option names
847 at least once in each section where the relevant option is covered, so
848 that novice readers will become familiar with both styles. (A few
849 options have no short versions, and the relevant sections will
853 @section Some Definitions
857 The @command{tar} program is used to create and manipulate @command{tar}
858 archives. An @dfn{archive} is a single file which contains the contents
859 of many files, while still identifying the names of the files, their
860 owner(s), and so forth. (In addition, archives record access
861 permissions, user and group, size in bytes, and last modification time.
862 Some archives also record the file names in each archived directory, as
863 well as other file and directory information.) You can use @command{tar}
864 to @dfn{create} a new archive in a specified directory.
867 @cindex archive member
870 The files inside an archive are called @dfn{members}. Within this
871 manual, we use the term @dfn{file} to refer only to files accessible in
872 the normal ways (by @command{ls}, @command{cat}, and so forth), and the term
873 @dfn{member} to refer only to the members of an archive. Similarly, a
874 @dfn{file name} is the name of a file, as it resides in the filesystem,
875 and a @dfn{member name} is the name of an archive member within the
880 The term @dfn{extraction} refers to the process of copying an archive
881 member (or multiple members) into a file in the filesystem. Extracting
882 all the members of an archive is often called @dfn{extracting the
883 archive}. The term @dfn{unpack} can also be used to refer to the
884 extraction of many or all the members of an archive. Extracting an
885 archive does not destroy the archive's structure, just as creating an
886 archive does not destroy the copies of the files that exist outside of
887 the archive. You may also @dfn{list} the members in a given archive
888 (this is often thought of as ``printing'' them to the standard output,
889 or the command line), or @dfn{append} members to a pre-existing archive.
890 All of these operations can be performed using @command{tar}.
893 @section What @command{tar} Does
896 The @command{tar} program provides the ability to create @command{tar}
897 archives, as well as various other kinds of manipulation. For example,
898 you can use @command{tar} on previously created archives to extract files,
899 to store additional files, or to update or list files which were already
902 Initially, @command{tar} archives were used to store files conveniently on
903 magnetic tape. The name @command{tar} comes from this use; it stands for
904 @code{t}ape @code{ar}chiver. Despite the utility's name, @command{tar} can
905 direct its output to available devices, files, or other programs (using
906 pipes). @command{tar} may even access remote devices or files (as archives).
908 @FIXME{the following table entries need a bit of work..}
910 You can use @command{tar} archives in many ways. We want to stress a few
911 of them: storage, backup, and transportation.
915 Often, @command{tar} archives are used to store related files for
916 convenient file transfer over a network. For example, the
917 @acronym{GNU} Project distributes its software bundled into
918 @command{tar} archives, so that all the files relating to a particular
919 program (or set of related programs) can be transferred as a single
922 A magnetic tape can store several files in sequence. However, the tape
923 has no names for these files; it only knows their relative position on
924 the tape. One way to store several files on one tape and retain their
925 names is by creating a @command{tar} archive. Even when the basic transfer
926 mechanism can keep track of names, as FTP can, the nuisance of handling
927 multiple files, directories, and multiple links makes @command{tar}
930 Archive files are also used for long-term storage. You can think of
931 this as transportation from the present into the future. (It is a
932 science-fiction idiom that you can move through time as well as in
933 space; the idea here is that @command{tar} can be used to move archives in
934 all dimensions, even time!)
937 Because the archive created by @command{tar} is capable of preserving
938 file information and directory structure, @command{tar} is commonly
939 used for performing full and incremental backups of disks. A backup
940 puts a collection of files (possibly pertaining to many users and
941 projects) together on a disk or a tape. This guards against
942 accidental destruction of the information in those files.
943 @acronym{GNU} @command{tar} has special features that allow it to be
944 used to make incremental and full dumps of all the files in a
948 You can create an archive on one system, transfer it to another system,
949 and extract the contents there. This allows you to transport a group of
950 files from one system to another.
953 @node Naming tar Archives
954 @section How @command{tar} Archives are Named
956 Conventionally, @command{tar} archives are given names ending with
957 @samp{.tar}. This is not necessary for @command{tar} to operate properly,
958 but this manual follows that convention in order to accustom readers to
959 it and to make examples more clear.
964 Often, people refer to @command{tar} archives as ``@command{tar} files,'' and
965 archive members as ``files'' or ``entries''. For people familiar with
966 the operation of @command{tar}, this causes no difficulty. However, in
967 this manual, we consistently refer to ``archives'' and ``archive
968 members'' to make learning to use @command{tar} easier for novice users.
970 @node posix compliance
971 @section @sc{posix} Compliance
974 @FIXME{must ask franc,ois about this. dan hagerty thinks this might
975 be an issue, but we're not really sure at this time. dan just tried a
976 test case of mixing up options' orders while the variable was set, and
977 there was no problem...}
979 We make some of our recommendations throughout this book for one
980 reason in addition to what we think of as ``good sense''. The main
981 additional reason for a recommendation is to be compliant with the
982 @sc{posix} standards. If you set the shell environment variable
983 @env{POSIXLY_CORRECT}, @acronym{GNU} @command{tar} will force you to
984 adhere to these standards. Therefore, if this variable is set and you
985 violate one of the @sc{posix} standards in the way you phrase a
986 command, for example, @acronym{GNU} @command{tar} will not allow the
987 command and will signal an error message. You would then have to
988 reorder the options or rephrase the command to comply with the
989 @sc{posix} standards.
991 There is a chance in the future that, if you set this environment
992 variable, your archives will be forced to comply with @sc{posix} standards,
993 also. No @acronym{GNU} @command{tar} extensions will be allowed.
996 @section @acronym{GNU} @command{tar} Authors
998 @acronym{GNU} @command{tar} was originally written by John Gilmore,
999 and modified by many people. The @acronym{GNU} enhancements were
1000 written by Jay Fenlason, then Joy Kendall, and the whole package has
1001 been further maintained by Thomas Bushnell, n/BSG, and finally
1002 Fran@,{c}ois Pinard, with the help of numerous and kind users.
1004 We wish to stress that @command{tar} is a collective work, and owes much to
1005 all those people who reported problems, offered solutions and other
1006 insights, or shared their thoughts and suggestions. An impressive, yet
1007 partial list of those contributors can be found in the @file{THANKS}
1008 file from the @acronym{GNU} @command{tar} distribution.
1010 @FIXME{i want all of these names mentioned, Absolutely. BUT, i'm not
1011 sure i want to spell out the history in this detail, at least not for
1012 the printed book. i'm just not sure it needs to be said this way.
1013 i'll think about it.}
1015 @FIXME{History is more important, and surely more interesting, than
1016 actual names. Quoting names without history would be meaningless. FP}
1018 Jay Fenlason put together a draft of a @acronym{GNU} @command{tar}
1019 manual, borrowing notes from the original man page from John Gilmore.
1020 This was withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy
1021 Gorin worked on a tutorial and manual for @acronym{GNU} @command{tar}.
1022 Fran@,{c}ois Pinard put version 1.11.8 of the manual together by
1023 taking information from all these sources and merging them. Melissa
1024 Weisshaus finally edited and redesigned the book to create version
1025 1.12. @FIXME{update version number as necessary; i'm being
1026 optimistic!} @FIXME{Someone [maybe karl berry? maybe bob chassell?
1027 maybe melissa? maybe julie sussman?] needs to properly index the
1030 For version 1.12, Daniel Hagerty contributed a great deal of technical
1031 consulting. In particular, he is the primary author of @ref{Backups}.
1034 @section Reporting bugs or suggestions
1037 @cindex reporting bugs
1038 If you find problems or have suggestions about this program or manual,
1039 please report them to @file{bug-tar@@gnu.org}.
1042 @chapter Tutorial Introduction to @command{tar}
1044 This chapter guides you through some basic examples of three @command{tar}
1045 operations: @samp{--create}, @samp{--list}, and @samp{--extract}. If
1046 you already know how to use some other version of @command{tar}, then you
1047 may not need to read this chapter. This chapter omits most complicated
1048 details about how @command{tar} works.
1052 * stylistic conventions::
1053 * basic tar options:: Basic @command{tar} Operations and Options
1054 * frequent operations::
1055 * Two Frequent Options::
1056 * create:: How to Create Archives
1057 * list:: How to List Archives
1058 * extract:: How to Extract Members from an Archive
1063 @section Assumptions this Tutorial Makes
1065 This chapter is paced to allow beginners to learn about @command{tar}
1066 slowly. At the same time, we will try to cover all the basic aspects of
1067 these three operations. In order to accomplish both of these tasks, we
1068 have made certain assumptions about your knowledge before reading this
1069 manual, and the hardware you will be using:
1073 Before you start to work through this tutorial, you should understand
1074 what the terms ``archive'' and ``archive member'' mean
1075 (@pxref{Definitions}). In addition, you should understand something
1076 about how Unix-type operating systems work, and you should know how to
1077 use some basic utilities. For example, you should know how to create,
1078 list, copy, rename, edit, and delete files and directories; how to
1079 change between directories; and how to figure out where you are in the
1080 filesystem. You should have some basic understanding of directory
1081 structure and how files are named according to which directory they are
1082 in. You should understand concepts such as standard output and standard
1083 input, what various definitions of the term ``argument'' mean, and the
1084 differences between relative and absolute path names. @FIXME{and what
1088 This manual assumes that you are working from your own home directory
1089 (unless we state otherwise). In this tutorial, you will create a
1090 directory to practice @command{tar} commands in. When we show path names,
1091 we will assume that those paths are relative to your home directory.
1092 For example, my home directory path is @file{/home/fsf/melissa}. All of
1093 my examples are in a subdirectory of the directory named by that path
1094 name; the subdirectory is called @file{practice}.
1097 In general, we show examples of archives which exist on (or can be
1098 written to, or worked with from) a directory on a hard disk. In most
1099 cases, you could write those archives to, or work with them on any other
1100 device, such as a tape drive. However, some of the later examples in
1101 the tutorial and next chapter will not work on tape drives.
1102 Additionally, working with tapes is much more complicated than working
1103 with hard disks. For these reasons, the tutorial does not cover working
1104 with tape drives. @xref{Media}, for complete information on using
1105 @command{tar} archives with tape drives.
1107 @FIXME{this is a cop out. need to add some simple tape drive info.}
1110 @node stylistic conventions
1111 @section Stylistic Conventions
1113 In the examples, @samp{$} represents a typical shell prompt. It
1114 precedes lines you should type; to make this more clear, those lines are
1115 shown in @kbd{this font}, as opposed to lines which represent the
1116 computer's response; those lines are shown in @code{this font}, or
1117 sometimes @samp{like this}. When we have lines which are too long to be
1118 displayed in any other way, we will show them like this:
1121 This is an example of a line which would otherwise not fit in this space.
1124 @FIXME{how often do we use smallexample?}
1126 @node basic tar options
1127 @section Basic @command{tar} Operations and Options
1129 @command{tar} can take a wide variety of arguments which specify and define
1130 the actions it will have on the particular set of files or the archive.
1131 The main types of arguments to @command{tar} fall into one of two classes:
1132 operations, and options.
1134 Some arguments fall into a class called @dfn{operations}; exactly one of
1135 these is both allowed and required for any instance of using @command{tar};
1136 you may @emph{not} specify more than one. People sometimes speak of
1137 @dfn{operating modes}. You are in a particular operating mode when you
1138 have specified the operation which specifies it; there are eight
1139 operations in total, and thus there are eight operating modes.
1141 The other arguments fall into the class known as @dfn{options}. You are
1142 not required to specify any options, and you are allowed to specify more
1143 than one at a time (depending on the way you are using @command{tar} at
1144 that time). Some options are used so frequently, and are so useful for
1145 helping you type commands more carefully that they are effectively
1146 ``required''. We will discuss them in this chapter.
1148 You can write most of the @command{tar} operations and options in any
1149 of three forms: long (mnemonic) form, short form, and old style. Some
1150 of the operations and options have no short or ``old'' forms; however,
1151 the operations and options which we will cover in this tutorial have
1152 corresponding abbreviations. @FIXME{make sure this is still the case,
1153 at the end}We will indicate those abbreviations appropriately to get
1154 you used to seeing them. (Note that the ``old style'' option forms
1155 exist in @acronym{GNU} @command{tar} for compatibility with Unix
1156 @command{tar}. We present a full discussion of this way of writing
1157 options and operations appears in @ref{Old Options}, and we discuss
1158 the other two styles of writing options in @ref{Mnemonic Options} and
1159 @ref{Short Options}.)
1161 In the examples and in the text of this tutorial, we usually use the
1162 long forms of operations and options; but the ``short'' forms produce
1163 the same result and can make typing long @command{tar} commands easier.
1164 For example, instead of typing
1167 @kbd{tar --create --verbose --file=afiles.tar apple angst aspic}
1173 @kbd{tar -c -v -f afiles.tar apple angst aspic}
1179 @kbd{tar -cvf afiles.tar apple angst aspic}
1183 For more information on option syntax, see @ref{Advanced tar}. In
1184 discussions in the text, when we name an option by its long form, we
1185 also give the corresponding short option in parentheses.
1187 The term, ``option'', can be confusing at times, since ``operations''
1188 are often lumped in with the actual, @emph{optional} ``options'' in certain
1189 general class statements. For example, we just talked about ``short and
1190 long forms of options and operations''. However, experienced @command{tar}
1191 users often refer to these by shorthand terms such as, ``short and long
1192 options''. This term assumes that the ``operations'' are included, also.
1193 Context will help you determine which definition of ``options'' to use.
1195 Similarly, the term ``command'' can be confusing, as it is often used in
1196 two different ways. People sometimes refer to @command{tar} ``commands''.
1197 A @command{tar} @dfn{command} is the entire command line of user input
1198 which tells @command{tar} what to do --- including the operation, options,
1199 and any arguments (file names, pipes, other commands, etc). However,
1200 you will also sometimes hear the term ``the @command{tar} command''. When
1201 the word ``command'' is used specifically like this, a person is usually
1202 referring to the @command{tar} @emph{operation}, not the whole line.
1203 Again, use context to figure out which of the meanings the speaker
1206 @node frequent operations
1207 @section The Three Most Frequently Used Operations
1209 Here are the three most frequently used operations (both short and long
1210 forms), as well as a brief description of their meanings. The rest of
1211 this chapter will cover how to use these operations in detail. We will
1212 present the rest of the operations in the next chapter.
1217 Create a new @command{tar} archive.
1220 List the contents of an archive.
1223 Extract one or more members from an archive.
1226 @node Two Frequent Options
1227 @section Two Frequently Used Options
1229 To understand how to run @command{tar} in the three operating modes listed
1230 previously, you also need to understand how to use two of the options to
1231 @command{tar}: @samp{--file} (which takes an archive file as an argument)
1232 and @samp{--verbose}. (You are usually not @emph{required} to specify
1233 either of these options when you run @command{tar}, but they can be very
1234 useful in making things more clear and helping you avoid errors.)
1238 * verbose tutorial::
1243 @unnumberedsubsec The @samp{--file} Option
1246 @item --file=@var{archive-name}
1247 @itemx -f @var{archive-name}
1248 Specify the name of an archive file.
1251 You can specify an argument for the @value{op-file} option whenever you
1252 use @command{tar}; this option determines the name of the archive file
1253 that @command{tar} will work on.
1255 If you don't specify this argument, then @command{tar} will use a
1256 default, usually some physical tape drive attached to your machine.
1257 If there is no tape drive attached, or the default is not meaningful,
1258 then @command{tar} will print an error message. The error message might
1259 look roughly like one of the following:
1262 tar: can't open /dev/rmt8 : No such device or address
1263 tar: can't open /dev/rsmt0 : I/O error
1267 To avoid confusion, we recommend that you always specify an archive file
1268 name by using @value{op-file} when writing your @command{tar} commands.
1269 For more information on using the @value{op-file} option, see
1272 @node verbose tutorial
1273 @unnumberedsubsec The @samp{--verbose} Option
1278 Show the files being worked on as @command{tar} is running.
1281 @value{op-verbose} shows details about the results of running
1282 @command{tar}. This can be especially useful when the results might not be
1283 obvious. For example, if you want to see the progress of @command{tar} as
1284 it writes files into the archive, you can use the @samp{--verbose}
1285 option. In the beginning, you may find it useful to use
1286 @samp{--verbose} at all times; when you are more accustomed to
1287 @command{tar}, you will likely want to use it at certain times but not at
1288 others. We will use @samp{--verbose} at times to help make something
1289 clear, and we will give many examples both using and not using
1290 @samp{--verbose} to show the differences.
1292 Sometimes, a single instance of @samp{--verbose} on the command line
1293 will show a full, @samp{ls} style listing of an archive or files,
1294 @c FIXME: Describe the exact output format, e.g., how hard links are displayed.
1295 giving sizes, owners, and similar information. Other times,
1296 @samp{--verbose} will only show files or members that the particular
1297 operation is operating on at the time. In the latter case, you can
1298 use @samp{--verbose} twice in a command to get a listing such as that
1299 in the former case. For example, instead of saying
1302 @kbd{tar -cvf afiles.tar apple angst aspic}
1306 above, you might say
1309 @kbd{tar -cvvf afiles.tar apple angst aspic}
1313 This works equally well using short or long forms of options. Using
1314 long forms, you would simply write out the mnemonic form of the option
1318 $ @kbd{tar --create --verbose --verbose @dots{}}
1322 Note that you must double the hyphens properly each time.
1324 Later in the tutorial, we will give examples using @w{@samp{--verbose
1328 @unnumberedsubsec Getting Help: Using the @code{--help} Option
1333 The @samp{--help} option to @command{tar} prints out a very brief list of
1334 all operations and option available for the current version of
1335 @command{tar} available on your system.
1339 @section How to Create Archives
1342 One of the basic operations of @command{tar} is @value{op-create}, which
1343 you use to create a @command{tar} archive. We will explain
1344 @samp{--create} first because, in order to learn about the other
1345 operations, you will find it useful to have an archive available to
1348 To make this easier, in this section you will first create a directory
1349 containing three files. Then, we will show you how to create an
1350 @emph{archive} (inside the new directory). Both the directory, and
1351 the archive are specifically for you to practice on. The rest of this
1352 chapter and the next chapter will show many examples using this
1353 directory and the files you will create: some of those files may be
1354 other directories and other archives.
1356 The three files you will archive in this example are called
1357 @file{blues}, @file{folk}, and @file{jazz}. The archive is called
1358 @file{collection.tar}.
1360 This section will proceed slowly, detailing how to use @samp{--create}
1361 in @code{verbose} mode, and showing examples using both short and long
1362 forms. In the rest of the tutorial, and in the examples in the next
1363 chapter, we will proceed at a slightly quicker pace. This section
1364 moves more slowly to allow beginning users to understand how
1365 @command{tar} works.
1368 * prepare for examples::
1369 * Creating the archive::
1375 @node prepare for examples
1376 @subsection Preparing a Practice Directory for Examples
1378 To follow along with this and future examples, create a new directory
1379 called @file{practice} containing files called @file{blues}, @file{folk}
1380 and @file{jazz}. The files can contain any information you like:
1381 ideally, they should contain information which relates to their names,
1382 and be of different lengths. Our examples assume that @file{practice}
1383 is a subdirectory of your home directory.
1385 Now @command{cd} to the directory named @file{practice}; @file{practice}
1386 is now your @dfn{working directory}. (@emph{Please note}: Although
1387 the full path name of this directory is
1388 @file{/@var{homedir}/practice}, in our examples we will refer to
1389 this directory as @file{practice}; the @var{homedir} is presumed.
1391 In general, you should check that the files to be archived exist where
1392 you think they do (in the working directory) by running @command{ls}.
1393 Because you just created the directory and the files and have changed to
1394 that directory, you probably don't need to do that this time.
1396 It is very important to make sure there isn't already a file in the
1397 working directory with the archive name you intend to use (in this case,
1398 @samp{collection.tar}), or that you don't care about its contents.
1399 Whenever you use @samp{create}, @command{tar} will erase the current
1400 contents of the file named by @value{op-file} if it exists. @command{tar}
1401 will not tell you if you are about to overwrite an archive unless you
1402 specify an option which does this. @FIXME{xref to the node for
1403 --backup!}To add files to an existing archive, you need to use a
1404 different option, such as @value{op-append}; see @ref{append} for
1405 information on how to do this.
1407 @node Creating the archive
1408 @subsection Creating the Archive
1410 To place the files @file{blues}, @file{folk}, and @file{jazz} into an
1411 archive named @file{collection.tar}, use the following command:
1414 $ @kbd{tar --create --file=collection.tar blues folk jazz}
1417 The order of the arguments is not very important, @emph{when using long
1418 option forms}. You could also say:
1421 $ @kbd{tar blues --create folk --file=collection.tar jazz}
1425 However, you can see that this order is harder to understand; this is
1426 why we will list the arguments in the order that makes the commands
1427 easiest to understand (and we encourage you to do the same when you use
1428 @command{tar}, to avoid errors).
1430 Note that the part of the command which says,
1431 @w{@kbd{--file=collection.tar}} is considered to be @emph{one} argument.
1432 If you substituted any other string of characters for
1433 @kbd{collection.tar}, then that string would become the name of the
1434 archive file you create.
1436 The order of the options becomes more important when you begin to use
1437 short forms. With short forms, if you type commands in the wrong order
1438 (even if you type them correctly in all other ways), you may end up with
1439 results you don't expect. For this reason, it is a good idea to get
1440 into the habit of typing options in the order that makes inherent sense.
1441 @xref{short create}, for more information on this.
1443 In this example, you type the command as shown above: @samp{--create}
1444 is the operation which creates the new archive
1445 (@file{collection.tar}), and @samp{--file} is the option which lets
1446 you give it the name you chose. The files, @file{blues}, @file{folk},
1447 and @file{jazz}, are now members of the archive, @file{collection.tar}
1448 (they are @dfn{file name arguments} to the @samp{--create} operation).
1449 @FIXME{xref here to the discussion of file name args?}Now that they are
1450 in the archive, they are called @emph{archive members}, not files.
1451 @FIXME{xref to definitions?}
1453 When you create an archive, you @emph{must} specify which files you
1454 want placed in the archive. If you do not specify any archive
1455 members, @acronym{GNU} @command{tar} will complain.
1457 If you now list the contents of the working directory (@kbd{ls}), you will
1458 find the archive file listed as well as the files you saw previously:
1461 blues folk jazz collection.tar
1465 Creating the archive @samp{collection.tar} did not destroy the copies of
1466 the files in the directory.
1468 Keep in mind that if you don't indicate an operation, @command{tar} will not
1469 run and will prompt you for one. If you don't name any files, @command{tar}
1470 will complain. You must have write access to the working directory,
1471 or else you will not be able to create an archive in that directory.
1473 @emph{Caution}: Do not attempt to use @value{op-create} to add files to
1474 an existing archive; it will delete the archive and write a new one.
1475 Use @value{op-append} instead. @xref{append}.
1477 @node create verbose
1478 @subsection Running @samp{--create} with @samp{--verbose}
1480 If you include the @value{op-verbose} option on the command line,
1481 @command{tar} will list the files it is acting on as it is working. In
1482 verbose mode, the @code{create} example above would appear as:
1485 $ @kbd{tar --create --verbose --file=collection.tar blues folk jazz}
1491 This example is just like the example we showed which did not use
1492 @samp{--verbose}, except that @command{tar} generated the remaining lines
1494 (note the different font styles).
1500 In the rest of the examples in this chapter, we will frequently use
1501 @code{verbose} mode so we can show actions or @command{tar} responses that
1502 you would otherwise not see, and which are important for you to
1506 @subsection Short Forms with @samp{create}
1508 As we said before, the @value{op-create} operation is one of the most
1509 basic uses of @command{tar}, and you will use it countless times.
1510 Eventually, you will probably want to use abbreviated (or ``short'')
1511 forms of options. A full discussion of the three different forms that
1512 options can take appears in @ref{Styles}; for now, here is what the
1513 previous example (including the @value{op-verbose} option) looks like
1514 using short option forms:
1517 $ @kbd{tar -cvf collection.tar blues folk jazz}
1524 As you can see, the system responds the same no matter whether you use
1525 long or short option forms.
1527 @FIXME{i don't like how this is worded:} One difference between using
1528 short and long option forms is that, although the exact placement of
1529 arguments following options is no more specific when using short forms,
1530 it is easier to become confused and make a mistake when using short
1531 forms. For example, suppose you attempted the above example in the
1535 $ @kbd{tar -cfv collection.tar blues folk jazz}
1539 In this case, @command{tar} will make an archive file called @file{v},
1540 containing the files @file{blues}, @file{folk}, and @file{jazz}, because
1541 the @samp{v} is the closest ``file name'' to the @samp{-f} option, and
1542 is thus taken to be the chosen archive file name. @command{tar} will try
1543 to add a file called @file{collection.tar} to the @file{v} archive file;
1544 if the file @file{collection.tar} did not already exist, @command{tar} will
1545 report an error indicating that this file does not exist. If the file
1546 @file{collection.tar} does already exist (e.g., from a previous command
1547 you may have run), then @command{tar} will add this file to the archive.
1548 Because the @samp{-v} option did not get registered, @command{tar} will not
1549 run under @samp{verbose} mode, and will not report its progress.
1551 The end result is that you may be quite confused about what happened,
1552 and possibly overwrite a file. To illustrate this further, we will show
1553 you how an example we showed previously would look using short forms.
1558 $ @kbd{tar blues --create folk --file=collection.tar jazz}
1562 is confusing as it is. When shown using short forms, however, it
1563 becomes much more so:
1566 $ @kbd{tar blues -c folk -f collection.tar jazz}
1570 It would be very easy to put the wrong string of characters
1571 immediately following the @samp{-f}, but doing that could sacrifice
1574 For this reason, we recommend that you pay very careful attention to
1575 the order of options and placement of file and archive names,
1576 especially when using short option forms. Not having the option name
1577 written out mnemonically can affect how well you remember which option
1578 does what, and therefore where different names have to be placed.
1579 (Placing options in an unusual order can also cause @command{tar} to
1580 report an error if you have set the shell environment variable
1581 @env{POSIXLY_CORRECT}; @pxref{posix compliance} for more information
1585 @subsection Archiving Directories
1587 @cindex Archiving Directories
1588 @cindex Directories, Archiving
1589 You can archive a directory by specifying its directory name as a
1590 file name argument to @command{tar}. The files in the directory will be
1591 archived relative to the working directory, and the directory will be
1592 re-created along with its contents when the archive is extracted.
1594 To archive a directory, first move to its superior directory. If you
1595 have followed the previous instructions in this tutorial, you should
1604 This will put you into the directory which contains @file{practice},
1605 i.e. your home directory. Once in the superior directory, you can
1606 specify the subdirectory, @file{practice}, as a file name argument. To
1607 store @file{practice} in the new archive file @file{music.tar}, type:
1610 $ @kbd{tar --create --verbose --file=music.tar practice}
1614 @command{tar} should output:
1621 practice/collection.tar
1624 Note that the archive thus created is not in the subdirectory
1625 @file{practice}, but rather in the current working directory---the
1626 directory from which @command{tar} was invoked. Before trying to archive a
1627 directory from its superior directory, you should make sure you have
1628 write access to the superior directory itself, not only the directory
1629 you are trying archive with @command{tar}. For example, you will probably
1630 not be able to store your home directory in an archive by invoking
1631 @command{tar} from the root directory; @value{xref-absolute-names}. (Note
1632 also that @file{collection.tar}, the original archive file, has itself
1633 been archived. @command{tar} will accept any file as a file to be
1634 archived, regardless of its content. When @file{music.tar} is
1635 extracted, the archive file @file{collection.tar} will be re-written
1636 into the file system).
1638 If you give @command{tar} a command such as
1641 $ @kbd{tar --create --file=foo.tar .}
1645 @command{tar} will report @samp{tar: ./foo.tar is the archive; not
1646 dumped}. This happens because @command{tar} creates the archive
1647 @file{foo.tar} in the current directory before putting any files into
1648 it. Then, when @command{tar} attempts to add all the files in the
1649 directory @file{.} to the archive, it notices that the file
1650 @file{./foo.tar} is the same as the archive @file{foo.tar}, and skips
1651 it. (It makes no sense to put an archive into itself.) @acronym{GNU}
1652 @command{tar} will continue in this case, and create the archive
1653 normally, except for the exclusion of that one file. (@emph{Please
1654 note:} Other versions of @command{tar} are not so clever; they will
1655 enter an infinite loop when this happens, so you should not depend on
1656 this behavior unless you are certain you are running @acronym{GNU}
1657 @command{tar}.) @FIXME{bob doesn't like this sentence, since he does
1658 it all the time, and we've been doing it in the editing passes for
1659 this manual: In general, make sure that the archive is not inside a
1660 directory being dumped.}
1663 @section How to List Archives
1665 Frequently, you will find yourself wanting to determine exactly what a
1666 particular archive contains. You can use the @value{op-list} operation
1667 to get the member names as they currently appear in the archive, as well
1668 as various attributes of the files at the time they were archived. For
1669 example, you can examine the archive @file{collection.tar} that you
1670 created in the last section with the command,
1673 $ @kbd{tar --list --file=collection.tar}
1677 The output of @command{tar} would then be:
1685 @FIXME{we hope this will change. if it doesn't, need to show the
1686 creation of bfiles somewhere above!!! : }
1689 The archive @file{bfiles.tar} would list as follows:
1698 Be sure to use a @value{op-file} option just as with @value{op-create}
1699 to specify the name of the archive.
1701 If you use the @value{op-verbose} option with @samp{--list}, then
1702 @command{tar} will print out a listing reminiscent of @w{@samp{ls -l}},
1703 showing owner, file size, and so forth.
1705 If you had used @value{op-verbose} mode, the example above would look
1709 $ @kbd{tar --list --verbose --file=collection.tar folk}
1710 -rw-rw-rw- myself user 62 1990-05-23 10:55 folk
1713 @cindex File name arguments, using @code{--list} with
1714 @cindex @code{--list} with file name arguments
1715 You can specify one or more individual member names as arguments when
1716 using @samp{list}. In this case, @command{tar} will only list the
1717 names of members you identify. For example, @w{@kbd{tar --list
1718 --file=afiles.tar apple}} would only print @file{apple}.
1720 @FIXME{we hope the relevant aspects of this will change:}Because
1721 @command{tar} preserves paths, file names must be specified as they appear
1722 in the archive (ie., relative to the directory from which the archive
1723 was created). Therefore, it is essential when specifying member names
1724 to @command{tar} that you give the exact member names. For example,
1725 @w{@kbd{tar --list --file=bfiles birds}} would produce an error message
1726 something like @samp{tar: birds: Not found in archive}, because there is
1727 no member named @file{birds}, only one named @file{./birds}. While the
1728 names @file{birds} and @file{./birds} name the same file, @emph{member}
1729 names are compared using a simplistic name comparison, in which an exact
1730 match is necessary. @xref{absolute}.
1732 However, @w{@kbd{tar --list --file=collection.tar folk}} would respond
1733 with @file{folk}, because @file{folk} is in the archive file
1734 @file{collection.tar}. If you are not sure of the exact file name, try
1735 listing all the files in the archive and searching for the one you
1736 expect to find; remember that if you use @samp{--list} with no file
1737 names as arguments, @command{tar} will print the names of all the members
1738 stored in the specified archive.
1745 @unnumberedsubsec Listing the Contents of a Stored Directory
1748 @FIXME{i changed the order of these nodes around and haven't had a
1749 chance to play around with this node's example, yet. i have to play
1750 with it and see what it actually does for my own satisfaction, even if
1751 what it says *is* correct..}
1753 To get information about the contents of an archived directory,
1754 use the directory name as a file name argument in conjunction with
1755 @value{op-list}. To find out file attributes, include the
1756 @value{op-verbose} option.
1758 For example, to find out about files in the directory @file{practice}, in
1759 the archive file @file{music.tar}, type:
1762 $ @kbd{tar --list --verbose --file=music.tar practice}
1765 @command{tar} responds:
1768 drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
1769 -rw-rw-rw- myself user 42 1990-05-21 13:29 practice/blues
1770 -rw-rw-rw- myself user 62 1990-05-23 10:55 practice/folk
1771 -rw-rw-rw- myself user 40 1990-05-21 13:30 practice/jazz
1772 -rw-rw-rw- myself user 10240 1990-05-31 21:49 practice/collection.tar
1775 When you use a directory name as a file name argument, @command{tar} acts on
1776 all the files (including sub-directories) in that directory.
1779 @section How to Extract Members from an Archive
1782 @cindex Retrieving files from an archive
1783 @cindex Resurrecting files from an archive
1785 Creating an archive is only half the job---there is no point in storing
1786 files in an archive if you can't retrieve them. The act of retrieving
1787 members from an archive so they can be used and manipulated as
1788 unarchived files again is called @dfn{extraction}. To extract files
1789 from an archive, use the @value{op-extract} operation. As with
1790 @value{op-create}, specify the name of the archive with @value{op-file}.
1791 Extracting an archive does not modify the archive in any way; you can
1792 extract it multiple times if you want or need to.
1794 Using @samp{--extract}, you can extract an entire archive, or specific
1795 files. The files can be directories containing other files, or not. As
1796 with @value{op-create} and @value{op-list}, you may use the short or the
1797 long form of the operation without affecting the performance.
1800 * extracting archives::
1801 * extracting files::
1803 * failing commands::
1806 @node extracting archives
1807 @subsection Extracting an Entire Archive
1809 To extract an entire archive, specify the archive file name only, with
1810 no individual file names as arguments. For example,
1813 $ @kbd{tar -xvf collection.tar}
1820 -rw-rw-rw- me user 28 1996-10-18 16:31 jazz
1821 -rw-rw-rw- me user 21 1996-09-23 16:44 blues
1822 -rw-rw-rw- me user 20 1996-09-23 16:44 folk
1825 @node extracting files
1826 @subsection Extracting Specific Files
1828 To extract specific archive members, give their exact member names as
1829 arguments, as printed by @value{op-list}. If you had mistakenly deleted
1830 one of the files you had placed in the archive @file{collection.tar}
1831 earlier (say, @file{blues}), you can extract it from the archive without
1832 changing the archive's structure. It will be identical to the original
1833 file @file{blues} that you deleted. @FIXME{check this; will the times,
1834 permissions, owner, etc be the same, also?}
1836 First, make sure you are in the @file{practice} directory, and list the
1837 files in the directory. Now, delete the file, @samp{blues}, and list
1838 the files in the directory again.
1840 You can now extract the member @file{blues} from the archive file
1841 @file{collection.tar} like this:
1844 $ @kbd{tar --extract --file=collection.tar blues}
1848 If you list the files in the directory again, you will see that the file
1849 @file{blues} has been restored, with its original permissions, creation
1850 times, and owner.@FIXME{This is only accidentally true, but not in
1851 general. In most cases, one has to be root for restoring the owner, and
1852 use a special option for restoring permissions. Here, it just happens
1853 that the restoring user is also the owner of the archived members, and
1854 that the current @code{umask} is compatible with original permissions.}
1855 (These parameters will be identical to those which
1856 the file had when you originally placed it in the archive; any changes
1857 you may have made before deleting the file from the file system,
1858 however, will @emph{not} have been made to the archive member.) The
1859 archive file, @samp{collection.tar}, is the same as it was before you
1860 extracted @samp{blues}. You can confirm this by running @command{tar} with
1863 @FIXME{we hope this will change:}Remember that as with other operations,
1864 specifying the exact member name is important. @w{@kbd{tar --extract
1865 --file=bfiles.tar birds}} will fail, because there is no member named
1866 @file{birds}. To extract the member named @file{./birds}, you must
1867 specify @w{@kbd{tar --extract --file=bfiles.tar ./birds}}. To find the
1868 exact member names of the members of an archive, use @value{op-list}
1871 You can extract a file to standard output by combining the above options
1872 with the @option{--to-stdout} option (@pxref{Writing to Standard
1875 If you give the @value{op-verbose} option, then @value{op-extract} will
1876 print the names of the archive members as it extracts them.
1879 @subsection Extracting Files that are Directories
1881 Extracting directories which are members of an archive is similar to
1882 extracting other files. The main difference to be aware of is that if
1883 the extracted directory has the same name as any directory already in
1884 the working directory, then files in the extracted directory will be
1885 placed into the directory of the same name. Likewise, if there are
1886 files in the pre-existing directory with the same names as the members
1887 which you extract, the files from the extracted archive will replace
1888 the files already in the working directory (and possible
1889 subdirectories). This will happen regardless of whether or not the
1890 files in the working directory were more recent than those extracted.
1892 However, if a file was stored with a directory name as part of its file
1893 name, and that directory does not exist under the working directory when
1894 the file is extracted, @command{tar} will create the directory.
1896 We can demonstrate how to use @samp{--extract} to extract a directory
1897 file with an example. Change to the @file{practice} directory if you
1898 weren't there, and remove the files @file{folk} and @file{jazz}. Then,
1899 go back to the parent directory and extract the archive
1900 @file{music.tar}. You may either extract the entire archive, or you may
1901 extract only the files you just deleted. To extract the entire archive,
1902 don't give any file names as arguments after the archive name
1903 @file{music.tar}. To extract only the files you deleted, use the
1907 $ @kbd{tar -xvf music.tar practice/folk practice/jazz}
1910 @FIXME{need to show tar's response; used verbose above. also, here's a
1911 good place to demonstrate the -v -v thing. have to write that up
1912 (should be trivial, but i'm too tired!).}
1915 Because you created the directory with @file{practice} as part of the
1916 file names of each of the files by archiving the @file{practice}
1917 directory as @file{practice}, you must give @file{practice} as part
1918 of the file names when you extract those files from the archive.
1920 @FIXME{IMPORTANT! show the final structure, here. figure out what it
1923 @node failing commands
1924 @subsection Commands That Will Fail
1926 Here are some sample commands you might try which will not work, and why
1929 If you try to use this command,
1932 $ @kbd{tar -xvf music.tar folk jazz}
1936 you will get the following response:
1939 tar: folk: Not found in archive
1940 tar: jazz: Not found in archive
1945 This is because these files were not originally @emph{in} the parent
1946 directory @file{..}, where the archive is located; they were in the
1947 @file{practice} directory, and their file names reflect this:
1950 $ @kbd{tar -tvf music.tar}
1956 @FIXME{make sure the above works when going through the examples in
1960 Likewise, if you try to use this command,
1963 $ @kbd{tar -tvf music.tar folk jazz}
1967 you would get a similar response. Members with those names are not in the
1968 archive. You must use the correct member names in order to extract the
1969 files from the archive.
1971 If you have forgotten the correct names of the files in the archive,
1972 use @w{@kbd{tar --list --verbose}} to list them correctly.
1974 @FIXME{more examples, here? hag thinks it's a good idea.}
1977 @section Going Further Ahead in this Manual
1979 @FIXME{need to write up a node here about the things that are going to
1980 be in the rest of the manual.}
1982 @node tar invocation
1983 @chapter Invoking @acronym{GNU} @command{tar}
1986 This chapter is about how one invokes the @acronym{GNU} @command{tar}
1987 command, from the command synopsis (@pxref{Synopsis}). There are
1988 numerous options, and many styles for writing them. One mandatory
1989 option specifies the operation @command{tar} should perform
1990 (@pxref{Operation Summary}), other options are meant to detail how
1991 this operation should be performed (@pxref{Option Summary}).
1992 Non-option arguments are not always interpreted the same way,
1993 depending on what the operation is.
1995 You will find in this chapter everything about option styles and rules for
1996 writing them (@pxref{Styles}). On the other hand, operations and options
1997 are fully described elsewhere, in other chapters. Here, you will find
1998 only synthetic descriptions for operations and options, together with
1999 pointers to other parts of the @command{tar} manual.
2001 Some options are so special they are fully described right in this
2002 chapter. They have the effect of inhibiting the normal operation of
2003 @command{tar} or else, they globally alter the amount of feedback the user
2004 receives about what is going on. These are the @value{op-help} and
2005 @value{op-version} (@pxref{help}), @value{op-verbose} (@pxref{verbose})
2006 and @value{op-interactive} options (@pxref{interactive}).
2010 * using tar options::
2019 @section General Synopsis of @command{tar}
2021 The @acronym{GNU} @command{tar} program is invoked as either one of:
2024 @kbd{tar @var{option}@dots{} [@var{name}]@dots{}}
2025 @kbd{tar @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}}
2028 The second form is for when old options are being used.
2030 You can use @command{tar} to store files in an archive, to extract them from
2031 an archive, and to do other types of archive manipulation. The primary
2032 argument to @command{tar}, which is called the @dfn{operation}, specifies
2033 which action to take. The other arguments to @command{tar} are either
2034 @dfn{options}, which change the way @command{tar} performs an operation,
2035 or file names or archive members, which specify the files or members
2036 @command{tar} is to act on.
2038 You can actually type in arguments in any order, even if in this manual
2039 the options always precede the other arguments, to make examples easier
2040 to understand. Further, the option stating the main operation mode
2041 (the @command{tar} main command) is usually given first.
2043 Each @var{name} in the synopsis above is interpreted as an archive member
2044 name when the main command is one of @value{op-compare}, @value{op-delete},
2045 @value{op-extract}, @value{op-list} or @value{op-update}. When naming
2046 archive members, you must give the exact name of the member in the
2047 archive, as it is printed by @value{op-list}. For @value{op-append}
2048 and @value{op-create}, these @var{name} arguments specify the names
2049 of either files or directory hierarchies to place in the archive.
2050 These files or hierarchies should already exist in the file system,
2051 prior to the execution of the @command{tar} command.
2053 @command{tar} interprets relative file names as being relative to the
2054 working directory. @command{tar} will make all file names relative
2055 (by removing leading slashes when archiving or restoring files),
2056 unless you specify otherwise (using the @value{op-absolute-names}
2057 option). @value{xref-absolute-names}, for more information about
2058 @value{op-absolute-names}.
2060 If you give the name of a directory as either a file name or a member
2061 name, then @command{tar} acts recursively on all the files and directories
2062 beneath that directory. For example, the name @file{/} identifies all
2063 the files in the filesystem to @command{tar}.
2065 The distinction between file names and archive member names is especially
2066 important when shell globbing is used, and sometimes a source of confusion
2067 for newcomers. @xref{Wildcards}, for more information about globbing.
2068 The problem is that shells may only glob using existing files in the
2069 file system. Only @command{tar} itself may glob on archive members, so when
2070 needed, you must ensure that wildcard characters reach @command{tar} without
2071 being interpreted by the shell first. Using a backslash before @samp{*}
2072 or @samp{?}, or putting the whole argument between quotes, is usually
2073 sufficient for this.
2075 Even if @var{name}s are often specified on the command line, they
2076 can also be read from a text file in the file system, using the
2077 @value{op-files-from} option.
2079 If you don't use any file name arguments, @value{op-append},
2080 @value{op-delete} and @value{op-concatenate} will do nothing, while
2081 @value{op-create} will usually yield a diagnostic and inhibit @command{tar}
2082 execution. The other operations of @command{tar} (@value{op-list},
2083 @value{op-extract}, @value{op-compare}, and @value{op-update}) will act
2084 on the entire contents of the archive.
2087 @cindex return status
2088 Besides successful exits, @acronym{GNU} @command{tar} may fail for
2089 many reasons. Some reasons correspond to bad usage, that is, when the
2090 @command{tar} command is improperly written. Errors may be
2091 encountered later, while encountering an error processing the archive
2092 or the files. Some errors are recoverable, in which case the failure
2093 is delayed until @command{tar} has completed all its work. Some
2094 errors are such that it would not meaningful, or at least risky, to
2095 continue processing: @command{tar} then aborts processing immediately.
2096 All abnormal exits, whether immediate or delayed, should always be
2097 clearly diagnosed on @code{stderr}, after a line stating the nature of
2100 @acronym{GNU} @command{tar} returns only a few exit statuses. I'm really
2101 aiming simplicity in that area, for now. If you are not using the
2102 @value{op-compare} option, zero means that everything went well, besides
2103 maybe innocuous warnings. Nonzero means that something went wrong.
2104 Right now, as of today, ``nonzero'' is almost always 2, except for
2105 remote operations, where it may be 128.
2107 @node using tar options
2108 @section Using @command{tar} Options
2110 @acronym{GNU} @command{tar} has a total of eight operating modes which
2111 allow you to perform a variety of tasks. You are required to choose
2112 one operating mode each time you employ the @command{tar} program by
2113 specifying one, and only one operation as an argument to the
2114 @command{tar} command (two lists of four operations each may be found
2115 at @ref{frequent operations} and @ref{Operations}). Depending on
2116 circumstances, you may also wish to customize how the chosen operating
2117 mode behaves. For example, you may wish to change the way the output
2118 looks, or the format of the files that you wish to archive may require
2119 you to do something special in order to make the archive look right.
2121 You can customize and control @command{tar}'s performance by running
2122 @command{tar} with one or more options (such as @value{op-verbose}, which
2123 we used in the tutorial). As we said in the tutorial, @dfn{options} are
2124 arguments to @command{tar} which are (as their name suggests) optional.
2125 Depending on the operating mode, you may specify one or more options.
2126 Different options will have different effects, but in general they all
2127 change details of the operation, such as archive format, archive name,
2128 or level of user interaction. Some options make sense with all
2129 operating modes, while others are meaningful only with particular modes.
2130 You will likely use some options frequently, while you will only use
2131 others infrequently, or not at all. (A full list of options is
2132 available in @pxref{All Options}.)
2134 The @env{TAR_OPTIONS} environment variable specifies default options to
2135 be placed in front of any explicit options. For example, if
2136 @code{TAR_OPTIONS} is @samp{-v --unlink-first}, @command{tar} behaves as
2137 if the two options @option{-v} and @option{--unlink-first} had been
2138 specified before any explicit options. Option specifications are
2139 separated by whitespace. A backslash escapes the next character, so it
2140 can be used to specify an option containing whitespace or a backslash.
2142 Note that @command{tar} options are case sensitive. For example, the
2143 options @samp{-T} and @samp{-t} are different; the first requires an
2144 argument for stating the name of a file providing a list of @var{name}s,
2145 while the second does not require an argument and is another way to
2146 write @value{op-list}.
2148 In addition to the eight operations, there are many options to
2149 @command{tar}, and three different styles for writing both: long (mnemonic)
2150 form, short form, and old style. These styles are discussed below.
2151 Both the options and the operations can be written in any of these three
2154 @FIXME{menu at end of this node. need to think of an actual outline
2155 for this chapter; probably do that after stuff from chap. 4 is
2159 @section The Three Option Styles
2161 There are three styles for writing operations and options to the command
2162 line invoking @command{tar}. The different styles were developed at
2163 different times during the history of @command{tar}. These styles will be
2164 presented below, from the most recent to the oldest.
2166 Some options must take an argument. (For example, @value{op-file} takes
2167 the name of an archive file as an argument. If you do not supply an
2168 archive file name, @command{tar} will use a default, but this can be
2169 confusing; thus, we recommend that you always supply a specific archive
2170 file name.) Where you @emph{place} the arguments generally depends on
2171 which style of options you choose. We will detail specific information
2172 relevant to each option style in the sections on the different option
2173 styles, below. The differences are subtle, yet can often be very
2174 important; incorrect option placement can cause you to overwrite a
2175 number of important files. We urge you to note these differences, and
2176 only use the option style(s) which makes the most sense to you until you
2177 feel comfortable with the others.
2179 @FIXME{hag to write a brief paragraph on the option(s) which can
2180 optionally take an argument}
2183 * Mnemonic Options:: Mnemonic Option Style
2184 * Short Options:: Short Option Style
2185 * Old Options:: Old Option Style
2186 * Mixing:: Mixing Option Styles
2189 @node Mnemonic Options
2190 @subsection Mnemonic Option Style
2192 @FIXME{have to decide whether or ot to replace other occurrences of
2193 "mnemonic" with "long", or *ugh* vice versa.}
2195 Each option has at least one long (or mnemonic) name starting with two
2196 dashes in a row, e.g.@: @samp{--list}. The long names are more clear than
2197 their corresponding short or old names. It sometimes happens that a
2198 single mnemonic option has many different different names which are
2199 synonymous, such as @samp{--compare} and @samp{--diff}. In addition,
2200 long option names can be given unique abbreviations. For example,
2201 @samp{--cre} can be used in place of @samp{--create} because there is no
2202 other mnemonic option which begins with @samp{cre}. (One way to find
2203 this out is by trying it and seeing what happens; if a particular
2204 abbreviation could represent more than one option, @command{tar} will tell
2205 you that that abbreviation is ambiguous and you'll know that that
2206 abbreviation won't work. You may also choose to run @samp{tar --help}
2207 to see a list of options. Be aware that if you run @command{tar} with a
2208 unique abbreviation for the long name of an option you didn't want to
2209 use, you are stuck; @command{tar} will perform the command as ordered.)
2211 Mnemonic options are meant to be obvious and easy to remember, and their
2212 meanings are generally easier to discern than those of their
2213 corresponding short options (see below). For example:
2216 $ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0}
2220 gives a fairly good set of hints about what the command does, even
2221 for those not fully acquainted with @command{tar}.
2223 Mnemonic options which require arguments take those arguments
2224 immediately following the option name; they are introduced by an equal
2225 sign. For example, the @samp{--file} option (which tells the name
2226 of the @command{tar} archive) is given a file such as @file{archive.tar}
2227 as argument by using the notation @samp{--file=archive.tar} for the
2231 @subsection Short Option Style
2233 Most options also have a short option name. Short options start with
2234 a single dash, and are followed by a single character, e.g.@: @samp{-t}
2235 (which is equivalent to @samp{--list}). The forms are absolutely
2236 identical in function; they are interchangeable.
2238 The short option names are faster to type than long option names.
2240 Short options which require arguments take their arguments immediately
2241 following the option, usually separated by white space. It is also
2242 possible to stick the argument right after the short option name, using
2243 no intervening space. For example, you might write @w{@samp{-f
2244 archive.tar}} or @samp{-farchive.tar} instead of using
2245 @samp{--file=archive.tar}. Both @samp{--file=@var{archive-name}} and
2246 @w{@samp{-f @var{archive-name}}} denote the option which indicates a
2247 specific archive, here named @file{archive.tar}.
2249 Short options' letters may be clumped together, but you are not
2250 required to do this (as compared to old options; see below). When
2251 short options are clumped as a set, use one (single) dash for them
2252 all, e.g.@: @w{@samp{@command{tar} -cvf}}. Only the last option in
2253 such a set is allowed to have an argument@footnote{Clustering many
2254 options, the last of which has an argument, is a rather opaque way to
2255 write options. Some wonder if @acronym{GNU} @code{getopt} should not
2256 even be made helpful enough for considering such usages as invalid.}.
2258 When the options are separated, the argument for each option which requires
2259 an argument directly follows that option, as is usual for Unix programs.
2263 $ @kbd{tar -c -v -b 20 -f /dev/rmt0}
2266 If you reorder short options' locations, be sure to move any arguments
2267 that belong to them. If you do not move the arguments properly, you may
2268 end up overwriting files.
2271 @subsection Old Option Style
2274 Like short options, old options are single letters. However, old options
2275 must be written together as a single clumped set, without spaces separating
2276 them or dashes preceding them@footnote{Beware that if you precede options
2277 with a dash, you are announcing the short option style instead of the
2278 old option style; short options are decoded differently.}. This set
2279 of letters must be the first to appear on the command line, after the
2280 @command{tar} program name and some white space; old options cannot appear
2281 anywhere else. The letter of an old option is exactly the same letter as
2282 the corresponding short option. For example, the old option @samp{t} is
2283 the same as the short option @samp{-t}, and consequently, the same as the
2284 mnemonic option @samp{--list}. So for example, the command @w{@samp{tar
2285 cv}} specifies the option @samp{-v} in addition to the operation @samp{-c}.
2287 @FIXME{bob suggests having an uglier example. :-) }
2289 When options that need arguments are given together with the command,
2290 all the associated arguments follow, in the same order as the options.
2291 Thus, the example given previously could also be written in the old
2295 $ @kbd{tar cvbf 20 /dev/rmt0}
2299 Here, @samp{20} is the argument of @samp{-b} and @samp{/dev/rmt0} is
2300 the argument of @samp{-f}.
2302 On the other hand, this old style syntax makes it difficult to match
2303 option letters with their corresponding arguments, and is often
2304 confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example,
2305 @samp{20} is the argument for @samp{-b}, @samp{/dev/rmt0} is the
2306 argument for @samp{-f}, and @samp{-v} does not have a corresponding
2307 argument. Even using short options like in @w{@samp{tar -c -v -b 20 -f
2308 /dev/rmt0}} is clearer, putting all arguments next to the option they
2311 If you want to reorder the letters in the old option argument, be
2312 sure to reorder any corresponding argument appropriately.
2314 This old way of writing @command{tar} options can surprise even experienced
2315 users. For example, the two commands:
2318 @kbd{tar cfz archive.tar.gz file}
2319 @kbd{tar -cfz archive.tar.gz file}
2323 are quite different. The first example uses @file{archive.tar.gz} as
2324 the value for option @samp{f} and recognizes the option @samp{z}. The
2325 second example, however, uses @file{z} as the value for option
2326 @samp{f}---probably not what was intended.
2328 Old options are kept for compatibility with old versions of @command{tar}.
2330 This second example could be corrected in many ways, among which the
2331 following are equivalent:
2334 @kbd{tar -czf archive.tar.gz file}
2335 @kbd{tar -cf archive.tar.gz -z file}
2336 @kbd{tar cf archive.tar.gz -z file}
2339 @FIXME{still could explain this better; it's redundant:}
2341 @cindex option syntax, traditional
2342 As far as we know, all @command{tar} programs, @acronym{GNU} and
2343 non-@acronym{GNU}, support old options. @acronym{GNU} @command{tar}
2344 supports them not only for historical reasons, but also because many
2345 people are used to them. For compatibility with Unix @command{tar},
2346 the first argument is always treated as containing command and option
2347 letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is
2348 equivalent to @w{@samp{tar -c}:} both of them specify the
2349 @value{op-create} command to create an archive.
2352 @subsection Mixing Option Styles
2354 All three styles may be intermixed in a single @command{tar} command,
2355 so long as the rules for each style are fully
2356 respected@footnote{Before @acronym{GNU} @command{tar} version 1.11.6,
2357 a bug prevented intermixing old style options with mnemonic options in
2358 some cases.}. Old style options and either of the modern styles of
2359 options may be mixed within a single @command{tar} command. However,
2360 old style options must be introduced as the first arguments only,
2361 following the rule for old options (old options must appear directly
2362 after the @command{tar} command and some white space). Modern options
2363 may be given only after all arguments to the old options have been
2364 collected. If this rule is not respected, a modern option might be
2365 falsely interpreted as the value of the argument to one of the old
2368 For example, all the following commands are wholly equivalent, and
2369 illustrate the many combinations and orderings of option styles.
2372 @kbd{tar --create --file=archive.tar}
2373 @kbd{tar --create -f archive.tar}
2374 @kbd{tar --create -farchive.tar}
2375 @kbd{tar --file=archive.tar --create}
2376 @kbd{tar --file=archive.tar -c}
2377 @kbd{tar -c --file=archive.tar}
2378 @kbd{tar -c -f archive.tar}
2379 @kbd{tar -c -farchive.tar}
2380 @kbd{tar -cf archive.tar}
2381 @kbd{tar -cfarchive.tar}
2382 @kbd{tar -f archive.tar --create}
2383 @kbd{tar -f archive.tar -c}
2384 @kbd{tar -farchive.tar --create}
2385 @kbd{tar -farchive.tar -c}
2386 @kbd{tar c --file=archive.tar}
2387 @kbd{tar c -f archive.tar}
2388 @kbd{tar c -farchive.tar}
2389 @kbd{tar cf archive.tar}
2390 @kbd{tar f archive.tar --create}
2391 @kbd{tar f archive.tar -c}
2392 @kbd{tar fc archive.tar}
2395 On the other hand, the following commands are @emph{not} equivalent to
2399 @kbd{tar -f -c archive.tar}
2400 @kbd{tar -fc archive.tar}
2401 @kbd{tar -fcarchive.tar}
2402 @kbd{tar -farchive.tarc}
2403 @kbd{tar cfarchive.tar}
2407 These last examples mean something completely different from what the
2408 user intended (judging based on the example in the previous set which
2409 uses long options, whose intent is therefore very clear). The first
2410 four specify that the @command{tar} archive would be a file named
2411 @samp{-c}, @samp{c}, @samp{carchive.tar} or @samp{archive.tarc},
2412 respectively. The first two examples also specify a single non-option,
2413 @var{name} argument having the value @samp{archive.tar}. The last
2414 example contains only old style option letters (repeating option
2415 @samp{c} twice), not all of which are meaningful (eg., @samp{.},
2416 @samp{h}, or @samp{i}), with no argument value. @FIXME{not sure i liked
2417 the first sentence of this paragraph..}
2420 @section All @command{tar} Options
2422 The coming manual sections contain an alphabetical listing of all
2423 @command{tar} operations and options, with brief descriptions and cross
2424 references to more in-depth explanations in the body of the manual.
2425 They also contain an alphabetically arranged table of the short option
2426 forms with their corresponding long option. You can use this table as
2427 a reference for deciphering @command{tar} commands in scripts.
2430 * Operation Summary::
2432 * Short Option Summary::
2435 @node Operation Summary
2436 @subsection Operations
2443 Appends files to the end of the archive. @xref{append}.
2448 Same as @samp{--concatenate}. @xref{concatenate}.
2453 Compares archive members with their counterparts in the file
2454 system, and reports differences in file size, mode, owner,
2455 modification date and contents. @xref{compare}.
2460 Appends other @command{tar} archives to the end of the archive.
2466 Creates a new @command{tar} archive. @xref{create}.
2470 Deletes members from the archive. Don't try this on a archive on a
2471 tape! @xref{delete}.
2476 Same @samp{--compare}. @xref{compare}.
2481 Extracts members from the archive into the file system. @xref{extract}.
2486 Same as @samp{--extract}. @xref{extract}.
2491 Lists the members in an archive. @xref{list}.
2496 @FIXME{It was: A combination of the @samp{--compare} and
2497 @samp{--append} operations. This is not true and rather misleading,
2498 as @value{op-compare} does a lot more than @value{op-update} for
2499 ensuring files are identical.} Adds files to the end of the archive,
2500 but only if they are newer than their counterparts already in the
2501 archive, or if they do not already exist in the archive.
2506 @node Option Summary
2507 @subsection @command{tar} Options
2511 @item --absolute-names
2514 Normally when creating an archive, @command{tar} strips an initial
2515 @samp{/} from member names. This option disables that behavior.
2520 (See @samp{--newer}.) @FIXME-pxref{}
2523 An exclude pattern must match an initial subsequence of the name's components.
2526 @item --atime-preserve
2528 Tells @command{tar} to preserve the access time field in a file's inode when
2529 reading it. Due to limitations in the @code{utimes} system call, the
2530 modification time field is also preserved, which may cause problems if
2531 the file is simultaneously being modified by another program.
2532 This option is incompatible with incremental backups, because
2533 preserving the access time involves updating the last-changed time.
2534 Also, this option does not work on files that you do not own,
2538 @item --backup=@var{backup-type}
2540 Rather than deleting files from the file system, @command{tar} will
2541 back them up using simple or numbered backups, depending upon
2542 @var{backup-type}. @FIXME-xref{}
2544 @item --block-number
2547 With this option present, @command{tar} prints error messages for read errors
2548 with the block number in the archive file. @FIXME-xref{}
2550 @item --blocking-factor=@var{blocking}
2551 @itemx -b @var{blocking}
2553 Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per
2554 record. @FIXME-xref{}
2559 This option tells @command{tar} to read or write archives through
2560 @code{bzip2}. @FIXME-xref{}
2564 This option directs @command{tar} to print periodic checkpoint messages as it
2565 reads through the archive. Its intended for when you want a visual
2566 indication that @command{tar} is still running, but don't want to see
2567 @samp{--verbose} output. @FIXME-xref{}
2573 @command{tar} will use the @command{compress} program when reading or
2574 writing the archive. This allows you to directly act on archives
2575 while saving space. @FIXME-xref{}
2577 @item --confirmation
2579 (See @samp{--interactive}.) @FIXME-pxref{}
2584 When creating a @command{tar} archive, @command{tar} will archive the
2585 file that a symbolic link points to, rather than archiving the
2586 symlink. @FIXME-xref{}
2588 @item --directory=@var{dir}
2591 When this option is specified, @command{tar} will change its current directory
2592 to @var{dir} before performing any operations. When this option is used
2593 during archive creation, it is order sensitive. @FIXME-xref{}
2595 @item --exclude=@var{pattern}
2597 When performing operations, @command{tar} will skip files that match
2598 @var{pattern}. @FIXME-xref{}
2600 @item --exclude-from=@var{file}
2601 @itemx -X @var{file}
2603 Similar to @samp{--exclude}, except @command{tar} will use the list of
2604 patterns in the file @var{file}. @FIXME-xref{}
2606 @item --file=@var{archive}
2607 @itemx -f @var{archive}
2609 @command{tar} will use the file @var{archive} as the @command{tar} archive it
2610 performs operations on, rather than @command{tar}'s compilation dependent
2611 default. @FIXME-xref{}
2613 @item --files-from=@var{file}
2614 @itemx -T @var{file}
2616 @command{tar} will use the contents of @var{file} as a list of archive members
2617 or files to operate on, in addition to those specified on the
2618 command-line. @FIXME-xref{}
2622 Forces @command{tar} to interpret the filename given to @samp{--file}
2623 as a local file, even if it looks like a remote tape drive name.
2626 @item --group=@var{group}
2628 Files added to the @command{tar} archive will have a group id of @var{group},
2629 rather than the group from the source file. @var{group} is first decoded
2630 as a group symbolic name, but if this interpretation fails, it has to be
2631 a decimal numeric group ID. @FIXME-xref{}
2633 Also see the comments for the @value{op-owner} option.
2637 (See @samp{--gzip}.) @FIXME-pxref{}
2644 This option tells @command{tar} to read or write archives through
2645 @command{gzip}, allowing @command{tar} to directly operate on several
2646 kinds of compressed archives transparently. @FIXME-xref{}
2650 @command{tar} will print out a short message summarizing the operations and
2651 options to @command{tar} and exit. @FIXME-xref{}
2654 Ignore case when excluding files.
2657 @item --ignore-failed-read
2659 Do not exit unsuccessfully merely because an unreadable file was encountered.
2662 @item --ignore-zeros
2665 With this option, @command{tar} will ignore zeroed blocks in the
2666 archive, which normally signals EOF. @xref{Reading}.
2671 Used to inform @command{tar} that it is working with an old
2672 @acronym{GNU}-format incremental backup archive. It is intended
2673 primarily for backwards compatibility only. @FIXME-xref{}
2675 @item --index-file=@var{file}
2677 Send verbose output to @var{file} instead of to standard output.
2679 @item --info-script=@var{script-file}
2680 @itemx --new-volume-script=@var{script-file}
2681 @itemx -F @var{script-file}
2683 When @command{tar} is performing multi-tape backups, @var{script-file} is run
2684 at the end of each tape. If @var{script-file} exits with nonzero status,
2685 @command{tar} fails immediately. @FIXME-xref{}
2688 @itemx --confirmation
2691 Specifies that @command{tar} should ask the user for confirmation before
2692 performing potentially destructive options, such as overwriting files.
2695 @item --keep-old-files
2698 Do not overwrite existing files when extracting files from an archive.
2701 @item --label=@var{name}
2702 @itemx -V @var{name}
2704 When creating an archive, instructs @command{tar} to write @var{name}
2705 as a name record in the archive. When extracting or listing archives,
2706 @command{tar} will only operate on archives that have a label matching
2707 the pattern specified in @var{name}. @FIXME-xref{}
2709 @item --listed-incremental=@var{snapshot-file}
2710 @itemx -g @var{snapshot-file}
2712 During a @samp{--create} operation, specifies that the archive that
2713 @command{tar} creates is a new @acronym{GNU}-format incremental
2714 backup, using @var{snapshot-file} to determine which files to backup.
2715 With other operations, informs @command{tar} that the archive is in
2716 incremental format. @FIXME-xref{}
2718 @item --mode=@var{permissions}
2720 When adding files to an archive, @command{tar} will use
2721 @var{permissions} for the archive members, rather than the permissions
2722 from the files. The program @command{chmod} and this @command{tar}
2723 option share the same syntax for what @var{permissions} might be.
2724 @xref{File permissions, Permissions, File permissions, fileutils,
2725 @acronym{GNU} file utilities}. This reference also has useful
2726 information for those not being overly familiar with the Unix
2729 Of course, @var{permissions} might be plainly specified as an octal number.
2730 However, by using generic symbolic modifications to mode bits, this allows
2731 more flexibility. For example, the value @samp{a+rw} adds read and write
2732 permissions for everybody, while retaining executable bits on directories
2733 or on any other file already marked as executable.
2735 @item --multi-volume
2738 Informs @command{tar} that it should create or otherwise operate on a
2739 multi-volume @command{tar} archive. @FIXME-xref{}
2741 @item --new-volume-script
2745 @item --newer=@var{date}
2746 @itemx --after-date=@var{date}
2749 When creating an archive, @command{tar} will only add files that have changed
2750 since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it
2751 is taken to be the name of a file whose last-modified time specifies
2752 the date. @FIXME-xref{}
2754 @item --newer-mtime=@var{date}
2756 Like @samp{--newer}, but add only files whose
2757 contents have changed (as opposed to just @samp{--newer}, which will
2758 also back up files for which any status information has changed).
2761 An exclude pattern can match any subsequence of the name's components.
2764 @item --no-ignore-case
2765 Use case-sensitive matching when excluding files.
2768 @item --no-recursion
2770 With this option, @command{tar} will not recurse into directories.
2773 @item --no-same-owner
2775 When extracting an archive, do not attempt to preserve the owner
2776 specified in the @command{tar} archive. This the default behavior
2777 for ordinary users; this option has an effect only for the superuser.
2779 @item --no-same-permissions
2781 When extracting an archive, subtract the user's umask from files from
2782 the permissions specified in the archive. This is the default behavior
2783 for ordinary users; this option has an effect only for the superuser.
2785 @item --no-wildcards
2786 Do not use wildcards when excluding files.
2789 @item --no-wildcards-match-slash
2790 Wildcards do not match @samp{/} when excluding files.
2795 When @command{tar} is using the @samp{--files-from} option, this option
2796 instructs @command{tar} to expect filenames terminated with @kbd{NUL}, so
2797 @command{tar} can correctly work with file names that contain newlines.
2800 @item --numeric-owner
2802 This option will notify @command{tar} that it should use numeric user
2803 and group IDs when creating a @command{tar} file, rather than names.
2808 (See @samp{--portability}.) @FIXME-pxref{}
2810 @item --one-file-system
2813 Used when creating an archive. Prevents @command{tar} from recursing into
2814 directories that are on different file systems from the current
2815 directory. @FIXME-xref{}
2819 Overwrite existing files and directory metadata when extracting files
2820 from an archive. @xref{Overwrite Old Files}.
2822 @item --overwrite-dir
2824 Overwrite the metadata of existing directories when extracting files
2825 from an archive. @xref{Overwrite Old Files}.
2827 @item --owner=@var{user}
2829 Specifies that @command{tar} should use @var{user} as the owner of members
2830 when creating archives, instead of the user associated with the source
2831 file. @var{user} is first decoded as a user symbolic name, but if
2832 this interpretation fails, it has to be a decimal numeric user ID.
2835 There is no value indicating a missing number, and @samp{0} usually means
2836 @code{root}. Some people like to force @samp{0} as the value to offer in
2837 their distributions for the owner of files, because the @code{root} user is
2838 anonymous anyway, so that might as well be the owner of anonymous archives.
2840 This option does not affect extraction from archives.
2843 @itemx --old-archive
2846 Tells @command{tar} to create an archive that is compatible with Unix V7
2847 @command{tar}. @FIXME-xref{}
2851 Instructs @command{tar} to create a @sc{posix} compliant @command{tar}
2852 archive. @FIXME-xref{}
2856 Synonymous with specifying both @samp{--preserve-permissions} and
2857 @samp{--same-order}. @FIXME-xref{}
2859 @item --preserve-order
2861 (See @samp{--same-order}; @pxref{Reading}.)
2863 @item --preserve-permissions
2864 @itemx --same-permissions
2867 When @command{tar} is extracting an archive, it normally subtracts the
2868 users' umask from the permissions specified in the archive and uses
2869 that number as the permissions to create the destination file.
2870 Specifying this option instructs @command{tar} that it should use the
2871 permissions directly from the archive. @xref{Writing}.
2873 @item --read-full-records
2876 Specifies that @command{tar} should reblock its input, for reading
2877 from pipes on systems with buggy implementations. @xref{Reading}.
2879 @item --record-size=@var{size}
2881 Instructs @command{tar} to use @var{size} bytes per record when accessing the
2882 archive. @FIXME-xref{}
2886 With this option, @command{tar} recurses into directories.
2889 @item --recursive-unlink
2892 directory hierarchies before extracting directories of the same name
2893 from the archive. @xref{Writing}.
2895 @item --remove-files
2897 Directs @command{tar} to remove the source file from the file system after
2898 appending it to an archive. @FIXME-xref{}
2900 @item --rsh-command=@var{cmd}
2902 Notifies @command{tar} that is should use @var{cmd} to communicate with remote
2903 devices. @FIXME-xref{}
2906 @itemx --preserve-order
2909 This option is an optimization for @command{tar} when running on machines with
2910 small amounts of memory. It informs @command{tar} that the list of file
2911 arguments has already been sorted to match the order of files in the
2912 archive. @xref{Reading}.
2916 When extracting an archive, @command{tar} will attempt to preserve the owner
2917 specified in the @command{tar} archive with this option present.
2918 This is the default behavior for the superuser; this option has an
2919 effect only for ordinary users. @FIXME-xref{}
2921 @item --same-permissions
2923 (See @samp{--preserve-permissions}; @pxref{Writing}.)
2925 @item --show-omitted-dirs
2927 Instructs @command{tar} to mention directories its skipping over when
2928 operating on a @command{tar} archive. @FIXME-xref{}
2933 Invokes a @acronym{GNU} extension when adding files to an archive that handles
2934 sparse files efficiently. @FIXME-xref{}
2936 @item --starting-file=@var{name}
2937 @itemx -K @var{name}
2939 This option affects extraction only; @command{tar} will skip extracting
2940 files in the archive until it finds one that matches @var{name}.
2943 @item --suffix=@var{suffix}
2945 Alters the suffix @command{tar} uses when backing up files from the default
2946 @samp{~}. @FIXME-xref{}
2948 @item --tape-length=@var{num}
2951 Specifies the length of tapes that @command{tar} is writing as being
2952 @w{@var{num} x 1024} bytes long. @FIXME-xref{}
2957 During extraction, @command{tar} will extract files to stdout rather
2958 than to the file system. @xref{Writing}.
2962 Displays the total number of bytes written after creating an archive.
2968 Sets the modification time of extracted files to the extraction time,
2969 rather than the modification time stored in the archive.
2974 (See @samp{--compress}.) @FIXME-pxref{}
2978 (See @samp{--gzip}.) @FIXME-pxref{}
2980 @item --unlink-first
2983 Directs @command{tar} to remove the corresponding file from the file
2984 system before extracting it from the archive. @xref{Writing}.
2986 @item --use-compress-program=@var{prog}
2988 Instructs @command{tar} to access the archive through @var{prog}, which is
2989 presumed to be a compression program of some sort. @FIXME-xref{}
2994 Specifies that @command{tar} should be more verbose about the operations its
2995 performing. This option can be specified multiple times for some
2996 operations to increase the amount of information displayed. @FIXME-xref{}
3001 Verifies that the archive was correctly written when creating an
3002 archive. @FIXME-xref{}
3006 @command{tar} will print an informational message about what version
3007 it is and a copyright message, some credits, and then exit.
3010 @item --volno-file=@var{file}
3012 Used in conjunction with @samp{--multi-volume}. @command{tar} will keep track
3013 of which volume of a multi-volume archive its working in @var{file}.
3017 Use wildcards when excluding files.
3020 @item --wildcards-match-slash
3021 Wildcards match @samp{/} when excluding files.
3025 @node Short Option Summary
3026 @subsection Short Options Cross Reference
3028 Here is an alphabetized list of all of the short option forms, matching
3029 them with the equivalent long option.
3035 @samp{--concatenate}
3039 @samp{--read-full-records}
3047 @samp{--info-script}
3051 @samp{--incremental}
3055 @samp{--starting-file}
3059 @samp{--tape-length}
3063 @samp{--multi-volume}
3075 @samp{--absolute-names}
3079 @samp{--block-number}
3091 @samp{--unlink-first}
3103 @samp{--exclude-from}
3111 @samp{--blocking-factor}
3127 @samp{--listed-incremental}
3131 @samp{--dereference}
3135 @samp{--ignore-zeros}
3143 @samp{--keep-old-files}
3147 @samp{--one-file-system}
3155 @samp{--portability}
3159 @samp{--preserve-permissions}
3183 @samp{--interactive}
3196 @section @acronym{GNU} @command{tar} documentation
3198 Being careful, the first thing is really checking that you are using
3199 @acronym{GNU} @command{tar}, indeed. The @value{op-version} option
3200 will generate a message giving confirmation that you are using
3201 @acronym{GNU} @command{tar}, with the precise version of @acronym{GNU}
3202 @command{tar} you are using. @command{tar} identifies itself and
3203 prints the version number to the standard output, then immediately
3204 exits successfully, without doing anything else, ignoring all other
3205 options. For example, @w{@samp{tar --version}} might return:
3208 tar (@acronym{GNU} tar) @value{VERSION}
3212 The first occurrence of @samp{tar} in the result above is the program
3213 name in the package (for example, @command{rmt} is another program),
3214 while the second occurrence of @samp{tar} is the name of the package
3215 itself, containing possibly many programs. The package is currently
3216 named @samp{tar}, after the name of the main program it
3217 contains@footnote{There are plans to merge the @command{cpio} and
3218 @command{tar} packages into a single one which would be called
3219 @code{paxutils}. So, who knows if, one of this days, the
3220 @value{op-version} would not yield @w{@samp{tar (@acronym{GNU}
3223 Another thing you might want to do is checking the spelling or meaning
3224 of some particular @command{tar} option, without resorting to this
3225 manual, for once you have carefully read it. @acronym{GNU}
3226 @command{tar} has a short help feature, triggerable through the
3227 @value{op-help} option. By using this option, @command{tar} will
3228 print a usage message listing all available options on standard
3229 output, then exit successfully, without doing anything else and
3230 ignoring all other options. Even if this is only a brief summary, it
3231 may be several screens long. So, if you are not using some kind of
3232 scrollable window, you might prefer to use something like:
3235 $ @kbd{tar --help | less}
3239 presuming, here, that you like using @command{less} for a pager. Other
3240 popular pagers are @command{more} and @command{pg}. If you know about some
3241 @var{keyword} which interests you and do not want to read all the
3242 @value{op-help} output, another common idiom is doing:
3245 tar --help | grep @var{keyword}
3249 for getting only the pertinent lines.
3251 The perceptive reader would have noticed some contradiction in the
3252 previous paragraphs. It is written that both @value{op-version} and
3253 @value{op-help} print something, and have all other options ignored. In
3254 fact, they cannot ignore each other, and one of them has to win. We do
3255 not specify which is stronger, here; experiment if you really wonder!
3257 The short help output is quite succinct, and you might have to get
3258 back to the full documentation for precise points. If you are reading
3259 this paragraph, you already have the @command{tar} manual in some
3260 form. This manual is available in printed form, as a kind of small
3261 book. It may printed out of the @acronym{GNU} @command{tar}
3262 distribution, provided you have @TeX{} already installed somewhere,
3263 and a laser printer around. Just configure the distribution, execute
3264 the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the
3265 usual way (contact your local guru to know how). If @acronym{GNU}
3266 @command{tar} has been conveniently installed at your place, this
3267 manual is also available in interactive, hypertextual form as an Info
3268 file. Just call @w{@samp{info tar}} or, if you do not have the
3269 @command{info} program handy, use the Info reader provided within
3270 @acronym{GNU} Emacs, calling @samp{tar} from the main Info menu.
3272 There is currently no @code{man} page for @acronym{GNU} @command{tar}.
3273 If you observe such a @code{man} page on the system you are running,
3274 either it does not long to @acronym{GNU} @command{tar}, or it has not
3275 been produced by @acronym{GNU}. Currently, @acronym{GNU}
3276 @command{tar} documentation is provided in Texinfo format only, if we
3277 except, of course, the short result of @kbd{tar --help}.
3280 @section Checking @command{tar} progress
3282 @cindex Progress information
3283 @cindex Status information
3284 @cindex Information on progress and status of operations
3285 @cindex Verbose operation
3286 @cindex Block number where error occurred
3287 @cindex Error message, block number of
3288 @cindex Version of the @command{tar} program
3290 @cindex Getting more information during the operation
3291 @cindex Information during operation
3292 @cindex Feedback from @command{tar}
3294 Typically, @command{tar} performs most operations without reporting any
3295 information to the user except error messages. When using @command{tar}
3296 with many options, particularly ones with complicated or
3297 difficult-to-predict behavior, it is possible to make serious mistakes.
3298 @command{tar} provides several options that make observing @command{tar}
3299 easier. These options cause @command{tar} to print information as it
3300 progresses in its job, and you might want to use them just for being
3301 more careful about what is going on, or merely for entertaining
3302 yourself. If you have encountered a problem when operating on an
3303 archive, however, you may need more information than just an error
3304 message in order to solve the problem. The following options can be
3305 helpful diagnostic tools.
3307 Normally, the @value{op-list} command to list an archive prints just
3308 the file names (one per line) and the other commands are silent.
3309 When used with most operations, the @value{op-verbose} option causes
3310 @command{tar} to print the name of each file or archive member as it
3311 is processed. This and the other options which make @command{tar} print
3312 status information can be useful in monitoring @command{tar}.
3314 With @value{op-create} or @value{op-extract}, @value{op-verbose} used once
3315 just prints the names of the files or members as they are processed.
3316 Using it twice causes @command{tar} to print a longer listing (reminiscent
3317 of @samp{ls -l}) for each member. Since @value{op-list} already prints
3318 the names of the members, @value{op-verbose} used once with @value{op-list}
3319 causes @command{tar} to print an @samp{ls -l} type listing of the files
3320 in the archive. The following examples both extract members with
3324 $ @kbd{tar --extract --file=archive.tar --verbose --verbose}
3325 $ @kbd{tar xvv archive.tar}
3328 Verbose output appears on the standard output except when an archive is
3329 being written to the standard output, as with @samp{tar --create
3330 --file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
3331 installer let standard output be the default archive). In that case
3332 @command{tar} writes verbose output to the standard error stream.
3334 If @option{--index-file=@var{file}} is specified, @command{tar} sends
3335 verbose output to @var{file} rather than to standard output or standard
3338 The @value{op-totals} option---which is only meaningful when used with
3339 @value{op-create}---causes @command{tar} to print the total
3340 amount written to the archive, after it has been fully created.
3342 The @value{op-checkpoint} option prints an occasional message
3343 as @command{tar} reads or writes the archive. In fact, it print
3344 directory names while reading the archive. It is designed for
3345 those who don't need the more detailed (and voluminous) output of
3346 @value{op-block-number}, but do want visual confirmation that @command{tar}
3347 is actually making forward progress.
3349 @FIXME{There is some confusion here. It seems that -R once wrote a
3350 message at @samp{every} record read or written.}
3352 The @value{op-show-omitted-dirs} option, when reading an archive---with
3353 @value{op-list} or @value{op-extract}, for example---causes a message
3354 to be printed for each directory in the archive which is skipped.
3355 This happens regardless of the reason for skipping: the directory might
3356 not have been named on the command line (implicitly or explicitly),
3357 it might be excluded by the use of the @value{op-exclude} option, or
3360 If @value{op-block-number} is used, @command{tar} prints, along with
3361 every message it would normally produce, the block number within the
3362 archive where the message was triggered. Also, supplementary messages
3363 are triggered when reading blocks full of NULs, or when hitting end of
3364 file on the archive. As of now, if the archive if properly terminated
3365 with a NUL block, the reading of the file may stop before end of file
3366 is met, so the position of end of file will not usually show when
3367 @value{op-block-number} is used. Note that @acronym{GNU}
3368 @command{tar} drains the archive before exiting when reading the
3369 archive from a pipe.
3371 This option is especially useful when reading damaged archives, since
3372 it helps pinpoint the damaged sections. It can also be used with
3373 @value{op-list} when listing a file-system backup tape, allowing you to
3374 choose among several backup tapes when retrieving a file later, in
3375 favor of the tape where the file appears earliest (closest to the
3376 front of the tape). @FIXME-xref{when the node name is set and the
3377 backup section written.}
3380 @section Asking for Confirmation During Operations
3381 @cindex Interactive operation
3383 Typically, @command{tar} carries out a command without stopping for
3384 further instructions. In some situations however, you may want to
3385 exclude some files and archive members from the operation (for instance
3386 if disk or storage space is tight). You can do this by excluding
3387 certain files automatically (@pxref{Choosing}), or by performing
3388 an operation interactively, using the @value{op-interactive} option.
3389 @command{tar} also accepts @samp{--confirmation} for this option.
3391 When the @value{op-interactive} option is specified, before
3392 reading, writing, or deleting files, @command{tar} first prints a message
3393 for each such file, telling what operation it intends to take, then asks
3394 for confirmation on the terminal. The actions which require
3395 confirmation include adding a file to the archive, extracting a file
3396 from the archive, deleting a file from the archive, and deleting a file
3397 from disk. To confirm the action, you must type a line of input
3398 beginning with @samp{y}. If your input line begins with anything other
3399 than @samp{y}, @command{tar} skips that file.
3401 If @command{tar} is reading the archive from the standard input,
3402 @command{tar} opens the file @file{/dev/tty} to support the interactive
3405 Verbose output is normally sent to standard output, separate from
3406 other error messages. However, if the archive is produced directly
3407 on standard output, then verbose output is mixed with errors on
3408 @code{stderr}. Producing the archive on standard output may be used
3409 as a way to avoid using disk space, when the archive is soon to be
3410 consumed by another process reading it, say. Some people felt the need
3411 of producing an archive on stdout, still willing to segregate between
3412 verbose output and error output. A possible approach would be using a
3413 named pipe to receive the archive, and having the consumer process to
3414 read from that named pipe. This has the advantage of letting standard
3415 output free to receive verbose output, all separate from errors.
3418 @chapter @acronym{GNU} @command{tar} Operations
3431 @section Basic @acronym{GNU} @command{tar} Operations
3433 The basic @command{tar} operations, @value{op-create}, @value{op-list} and
3434 @value{op-extract}, are currently presented and described in the tutorial
3435 chapter of this manual. This section provides some complementary notes
3436 for these operations.
3439 @item @value{op-create}
3441 Creating an empty archive would have some kind of elegance. One can
3442 initialize an empty archive and later use @value{op-append} for adding
3443 all members. Some applications would not welcome making an exception
3444 in the way of adding the first archive member. On the other hand,
3445 many people reported that it is dangerously too easy for @command{tar}
3446 to destroy a magnetic tape with an empty archive@footnote{This is well
3447 described in @cite{Unix-haters Handbook}, by Simson Garfinkel, Daniel
3448 Weise & Steven Strassmann, IDG Books, ISBN 1-56884-203-1.}. The two most
3453 Mistakingly using @code{create} instead of @code{extract}, when the
3454 intent was to extract the full contents of an archive. This error
3455 is likely: keys @kbd{c} and @kbd{x} are right next ot each other on
3456 the QWERTY keyboard. Instead of being unpacked, the archive then
3457 gets wholly destroyed. When users speak about @dfn{exploding} an
3458 archive, they usually mean something else :-).
3461 Forgetting the argument to @code{file}, when the intent was to create
3462 an archive with a single file in it. This error is likely because a
3463 tired user can easily add the @kbd{f} key to the cluster of option
3464 letters, by the mere force of habit, without realizing the full
3465 consequence of doing so. The usual consequence is that the single
3466 file, which was meant to be saved, is rather destroyed.
3469 So, recognizing the likelihood and the catastrophical nature of these
3470 errors, @acronym{GNU} @command{tar} now takes some distance from elegance, and
3471 cowardly refuses to create an archive when @value{op-create} option is
3472 given, there are no arguments besides options, and @value{op-files-from}
3473 option is @emph{not} used. To get around the cautiousness of @acronym{GNU}
3474 @command{tar} and nevertheless create an archive with nothing in it,
3475 one may still use, as the value for the @value{op-files-from} option,
3476 a file with no names in it, as shown in the following commands:
3479 @kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
3480 @kbd{tar cfT empty-archive.tar /dev/null}
3483 @item @value{op-extract}
3485 A socket is stored, within a @acronym{GNU} @command{tar} archive, as a pipe.
3487 @item @value{op-list}
3489 @acronym{GNU} @command{tar} now shows dates as @samp{1996-08-30},
3490 while it used to show them as @samp{Aug 30 1996}. (One can revert to
3491 the old behavior by defining @code{USE_OLD_CTIME} in @file{src/list.c}
3492 before reinstalling.) But preferably, people should get used to ISO
3493 8601 dates. Local American dates should be made available again with
3494 full date localization support, once ready. In the meantime, programs
3495 not being localizable for dates should prefer international dates,
3496 that's really the way to go.
3498 Look up @url{http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html} if you
3499 are curious, it contains a detailed explanation of the ISO 8601 standard.
3504 @section Advanced @acronym{GNU} @command{tar} Operations
3506 Now that you have learned the basics of using @acronym{GNU}
3507 @command{tar}, you may want to learn about further ways in which
3508 @command{tar} can help you.
3510 This chapter presents five, more advanced operations which you probably
3511 won't use on a daily basis, but which serve more specialized functions.
3512 We also explain the different styles of options and why you might want
3513 to use one or another, or a combination of them in your @command{tar}
3514 commands. Additionally, this chapter includes options which allow you to
3515 define the output from @command{tar} more carefully, and provide help and
3516 error correction in special circumstances.
3518 @FIXME{check this after the chapter is actually revised to make sure
3519 it still introduces the info in the chapter correctly : ).}
3531 @subsection The Five Advanced @command{tar} Operations
3534 In the last chapter, you learned about the first three operations to
3535 @command{tar}. This chapter presents the remaining five operations to
3536 @command{tar}: @samp{--append}, @samp{--update}, @samp{--concatenate},
3537 @samp{--delete}, and @samp{--compare}.
3539 You are not likely to use these operations as frequently as those
3540 covered in the last chapter; however, since they perform specialized
3541 functions, they are quite useful when you do need to use them. We
3542 will give examples using the same directory and files that you created
3543 in the last chapter. As you may recall, the directory is called
3544 @file{practice}, the files are @samp{jazz}, @samp{blues}, @samp{folk},
3545 @samp{rock}, and the two archive files you created are
3546 @samp{collection.tar} and @samp{music.tar}.
3548 We will also use the archive files @samp{afiles.tar} and
3549 @samp{bfiles.tar}. @samp{afiles.tar} contains the members @samp{apple},
3550 @samp{angst}, and @samp{aspic}. @samp{bfiles.tar} contains the members
3551 @samp{./birds}, @samp{baboon}, and @samp{./box}.
3553 Unless we state otherwise, all practicing you do and examples you follow
3554 in this chapter will take place in the @file{practice} directory that
3555 you created in the previous chapter; see @ref{prepare for examples}.
3556 (Below in this section, we will remind you of the state of the examples
3557 where the last chapter left them.)
3559 The five operations that we will cover in this chapter are:
3564 Add new entries to an archive that already exists.
3567 Add more recent copies of archive members to the end of an archive, if
3572 Add one or more pre-existing archives to the end of another archive.
3574 Delete items from an archive (does not work on tapes).
3578 Compare archive members to their counterparts in the file system.
3582 @subsection How to Add Files to Existing Archives: @code{--append}
3585 If you want to add files to an existing archive, you don't need to
3586 create a new archive; you can use @value{op-append}. The archive must
3587 already exist in order to use @samp{--append}. (A related operation
3588 is the @samp{--update} operation; you can use this to add newer
3589 versions of archive members to an existing archive. To learn how to
3590 do this with @samp{--update}, @pxref{update}.)
3592 @FIXME{Explain in second paragraph whether you can get to the previous
3593 version -- explain whole situation somewhat more clearly.}
3595 If you use @value{op-append} to add a file that has the same name as an
3596 archive member to an archive containing that archive member, then the
3597 old member is not deleted. What does happen, however, is somewhat
3598 complex. @command{tar} @emph{allows} you to have infinite numbers of files
3599 with the same name. Some operations treat these same-named members no
3600 differently than any other set of archive members: for example, if you
3601 view an archive with @value{op-list}, you will see all of those members
3602 listed, with their modification times, owners, etc.
3604 Other operations don't deal with these members as perfectly as you might
3605 prefer; if you were to use @value{op-extract} to extract the archive,
3606 only the most recently added copy of a member with the same name as four
3607 other members would end up in the working directory. This is because
3608 @samp{--extract} extracts an archive in the order the members appeared
3609 in the archive; the most recently archived members will be extracted
3610 last. Additionally, an extracted member will @emph{replace} a file of
3611 the same name which existed in the directory already, and @command{tar}
3612 will not prompt you about this. Thus, only the most recently archived
3613 member will end up being extracted, as it will replace the one
3614 extracted before it, and so on.
3616 @FIXME{ hag -- you might want to incorporate some of the above into the
3617 MMwtSN node; not sure. i didn't know how to make it simpler...}
3619 There are a few ways to get around this. @FIXME-xref{Multiple Members
3620 with the Same Name.}
3622 @cindex Members, replacing with other members
3623 @cindex Replacing members with other members
3624 If you want to replace an archive member, use @value{op-delete} to
3625 delete the member you want to remove from the archive, , and then use
3626 @samp{--append} to add the member you want to be in the archive. Note
3627 that you can not change the order of the archive; the most recently
3628 added member will still appear last. In this sense, you cannot truly
3629 ``replace'' one member with another. (Replacing one member with another
3630 will not work on certain types of media, such as tapes; see @ref{delete}
3631 and @ref{Media}, for more information.)
3634 * appending files:: Appending Files to an Archive
3638 @node appending files
3639 @subsubsection Appending Files to an Archive
3641 @cindex Adding files to an Archive
3642 @cindex Appending files to an Archive
3643 @cindex Archives, Appending files to
3645 The simplest way to add a file to an already existing archive is the
3646 @value{op-append} operation, which writes specified files into the
3647 archive whether or not they are already among the archived files.
3648 When you use @samp{--append}, you @emph{must} specify file name
3649 arguments, as there is no default. If you specify a file that already
3650 exists in the archive, another copy of the file will be added to the
3651 end of the archive. As with other operations, the member names of the
3652 newly added files will be exactly the same as their names given on the
3653 command line. The @value{op-verbose} option will print out the names
3654 of the files as they are written into the archive.
3656 @samp{--append} cannot be performed on some tape drives, unfortunately,
3657 due to deficiencies in the formats those tape drives use. The archive
3658 must be a valid @command{tar} archive, or else the results of using this
3659 operation will be unpredictable. @xref{Media}.
3661 To demonstrate using @samp{--append} to add a file to an archive,
3662 create a file called @file{rock} in the @file{practice} directory.
3663 Make sure you are in the @file{practice} directory. Then, run the
3664 following @command{tar} command to add @file{rock} to
3665 @file{collection.tar}:
3668 $ @kbd{tar --append --file=collection.tar rock}
3672 If you now use the @value{op-list} operation, you will see that
3673 @file{rock} has been added to the archive:
3676 $ @kbd{tar --list --file=collection.tar}
3677 -rw-rw-rw- me user 28 1996-10-18 16:31 jazz
3678 -rw-rw-rw- me user 21 1996-09-23 16:44 blues
3679 -rw-rw-rw- me user 20 1996-09-23 16:44 folk
3680 -rw-rw-rw- me user 20 1996-09-23 16:44 rock
3683 @FIXME{in theory, dan will (soon) try to turn this node into what it's
3684 title claims it will become...}
3687 @subsubsection Multiple Files with the Same Name
3689 You can use @value{op-append} to add copies of files which have been
3690 updated since the archive was created. (However, we do not recommend
3691 doing this since there is another @command{tar} option called
3692 @samp{--update}; @pxref{update} for more information. We describe this
3693 use of @samp{--append} here for the sake of completeness.) @FIXME{is
3694 this really a good idea, to give this whole description for something
3695 which i believe is basically a Stupid way of doing something? certain
3696 aspects of it show ways in which tar is more broken than i'd personally
3697 like to admit to, specifically the last sentence. On the other hand, i
3698 don't think it's a good idea to be saying that re explicitly don't
3699 recommend using something, but i can't see any better way to deal with
3700 the situation.}When you extract the archive, the older version will be
3701 effectively lost. This works because files are extracted from an
3702 archive in the order in which they were archived. Thus, when the
3703 archive is extracted, a file archived later in time will replace a
3704 file of the same name which was archived earlier, even though the older
3705 version of the file will remain in the archive unless you delete all
3706 versions of the file.
3708 Supposing you change the file @file{blues} and then append the changed
3709 version to @file{collection.tar}. As you saw above, the original
3710 @file{blues} is in the archive @file{collection.tar}. If you change the
3711 file and append the new version of the file to the archive, there will
3712 be two copies in the archive. When you extract the archive, the older
3713 version of the file will be extracted first, and then replaced by the
3714 newer version when it is extracted.
3716 You can append the new, changed copy of the file @file{blues} to the
3717 archive in this way:
3720 $ @kbd{tar --append --verbose --file=collection.tar blues}
3725 Because you specified the @samp{--verbose} option, @command{tar} has
3726 printed the name of the file being appended as it was acted on. Now
3727 list the contents of the archive:
3730 $ @kbd{tar --list --verbose --file=collection.tar}
3731 -rw-rw-rw- me user 28 1996-10-18 16:31 jazz
3732 -rw-rw-rw- me user 21 1996-09-23 16:44 blues
3733 -rw-rw-rw- me user 20 1996-09-23 16:44 folk
3734 -rw-rw-rw- me user 20 1996-09-23 16:44 rock
3735 -rw-rw-rw- me user 58 1996-10-24 18:30 blues
3739 The newest version of @file{blues} is now at the end of the archive
3740 (note the different creation dates and file sizes). If you extract
3741 the archive, the older version of the file @file{blues} will be
3742 replaced by the newer version. You can confirm this by extracting
3743 the archive and running @samp{ls} on the directory. @xref{Writing},
3744 for more information. (@emph{Please note:} This is the case unless
3745 you employ the @value{op-backup} option. @FIXME-ref{Multiple Members
3746 with the Same Name}.)
3749 @subsection Updating an Archive
3751 @cindex Updating an archive
3753 In the previous section, you learned how to use @value{op-append} to add
3754 a file to an existing archive. A related operation is
3755 @value{op-update}. The @samp{--update} operation updates a @command{tar}
3756 archive by comparing the date of the specified archive members against
3757 the date of the file with the same name. If the file has been modified
3758 more recently than the archive member, then the newer version of the
3759 file is added to the archive (as with @value{op-append}).
3761 Unfortunately, you cannot use @samp{--update} with magnetic tape drives.
3762 The operation will fail.
3764 @FIXME{other examples of media on which --update will fail? need to ask
3765 charles and/or mib/thomas/dave shevett..}
3767 Both @samp{--update} and @samp{--append} work by adding to the end
3768 of the archive. When you extract a file from the archive, only the
3769 version stored last will wind up in the file system, unless you use
3770 the @value{op-backup} option. @FIXME-ref{Multiple Members with the
3778 @subsubsection How to Update an Archive Using @code{--update}
3780 You must use file name arguments with the @value{op-update} operation.
3781 If you don't specify any files, @command{tar} won't act on any files and
3782 won't tell you that it didn't do anything (which may end up confusing
3785 @FIXME{note: the above parenthetical added because in fact, this
3786 behavior just confused the author. :-) }
3788 To see the @samp{--update} option at work, create a new file,
3789 @file{classical}, in your practice directory, and some extra text to the
3790 file @file{blues}, using any text editor. Then invoke @command{tar} with
3791 the @samp{update} operation and the @value{op-verbose} option specified,
3792 using the names of all the files in the practice directory as file name
3796 $ @kbd{tar --update -v -f collection.tar blues folk rock classical}
3803 Because we have specified verbose mode, @command{tar} prints out the names
3804 of the files it is working on, which in this case are the names of the
3805 files that needed to be updated. If you run @samp{tar --list} and look
3806 at the archive, you will see @file{blues} and @file{classical} at its
3807 end. There will be a total of two versions of the member @samp{blues};
3808 the one at the end will be newer and larger, since you added text before
3811 (The reason @command{tar} does not overwrite the older file when updating
3812 it is because writing to the middle of a section of tape is a difficult
3813 process. Tapes are not designed to go backward. @xref{Media}, for more
3814 information about tapes.
3816 @value{op-update} is not suitable for performing backups for two
3817 reasons: it does not change directory content entries, and it
3818 lengthens the archive every time it is used. The @acronym{GNU}
3819 @command{tar} options intended specifically for backups are more
3820 efficient. If you need to run backups, please consult @ref{Backups}.
3823 @subsection Combining Archives with @code{--concatenate}
3825 @cindex Adding archives to an archive
3826 @cindex Concatenating Archives
3827 Sometimes it may be convenient to add a second archive onto the end of
3828 an archive rather than adding individual files to the archive. To add
3829 one or more archives to the end of another archive, you should use the
3830 @value{op-concatenate} operation.
3832 To use @samp{--concatenate}, name the archives to be concatenated on the
3833 command line. (Nothing happens if you don't list any.) The members,
3834 and their member names, will be copied verbatim from those archives. If
3835 this causes multiple members to have the same name, it does not delete
3836 any members; all the members with the same name coexist. @FIXME-ref{For
3837 information on how this affects reading the archive, Multiple
3838 Members with the Same Name.}
3840 To demonstrate how @samp{--concatenate} works, create two small archives
3841 called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
3842 files from @file{practice}:
3845 $ @kbd{tar -cvf bluesrock.tar blues rock}
3848 $ @kbd{tar -cvf folkjazz.tar folk jazz}
3854 If you like, You can run @samp{tar --list} to make sure the archives
3855 contain what they are supposed to:
3858 $ @kbd{tar -tvf bluesrock.tar}
3859 -rw-rw-rw- melissa user 105 1997-01-21 19:42 blues
3860 -rw-rw-rw- melissa user 33 1997-01-20 15:34 rock
3861 $ @kbd{tar -tvf folkjazz.tar}
3862 -rw-rw-rw- melissa user 20 1996-09-23 16:44 folk
3863 -rw-rw-rw- melissa user 65 1997-01-30 14:15 jazz
3866 We can concatenate these two archives with @command{tar}:
3870 $ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
3873 If you now list the contents of the @file{bluesclass.tar}, you will see
3874 that now it also contains the archive members of @file{jazzfolk.tar}:
3877 $ @kbd{tar --list --file=bluesrock.tar}
3884 When you use @samp{--concatenate}, the source and target archives must
3885 already exist and must have been created using compatible format
3886 parameters. @FIXME-pxref{Matching Format Parameters}The new,
3887 concatenated archive will be called by the same name as the first
3888 archive listed on the command line. @FIXME{is there a way to specify a
3891 Like @value{op-append}, this operation cannot be performed on some
3892 tape drives, due to deficiencies in the formats those tape drives use.
3894 @cindex @code{concatenate} vs @command{cat}
3895 @cindex @command{cat} vs @code{concatenate}
3896 It may seem more intuitive to you to want or try to use @command{cat} to
3897 concatenate two archives instead of using the @samp{--concatenate}
3898 operation; after all, @command{cat} is the utility for combining files.
3900 However, @command{tar} archives incorporate an end-of-file marker which
3901 must be removed if the concatenated archives are to be read properly as
3902 one archive. @samp{--concatenate} removes the end-of-archive marker
3903 from the target archive before each new archive is appended. If you use
3904 @command{cat} to combine the archives, the result will not be a valid
3905 @command{tar} format archive. If you need to retrieve files from an
3906 archive that was added to using the @command{cat} utility, use the
3907 @value{op-ignore-zeros} option. @xref{Ignore Zeros}, for further
3908 information on dealing with archives improperly combined using the
3909 @command{cat} shell utility.
3911 @FIXME{this shouldn't go here. where should it go?} You must specify
3912 the source archives using @value{op-file} (@value{pxref-file}). If you
3913 do not specify the target archive, @command{tar} uses the value of the
3914 environment variable @env{TAPE}, or, if this has not been set, the
3915 default archive name.
3918 @subsection Removing Archive Members Using @samp{--delete}
3920 @cindex Deleting files from an archive
3921 @cindex Removing files from an archive
3923 You can remove members from an archive by using the @value{op-delete}
3924 option. Specify the name of the archive with @value{op-file} and then
3925 specify the names of the members to be deleted; if you list no member
3926 names, nothing will be deleted. The @value{op-verbose} option will
3927 cause @command{tar} to print the names of the members as they are deleted.
3928 As with @value{op-extract}, you must give the exact member names when
3929 using @samp{tar --delete}. @samp{--delete} will remove all versions of
3930 the named file from the archive. The @samp{--delete} operation can run
3933 Unlike other operations, @samp{--delete} has no short form.
3935 @cindex Tapes, using @code{--delete} and
3936 @cindex Deleting from tape archives
3937 This operation will rewrite the archive. You can only use
3938 @samp{--delete} on an archive if the archive device allows you to
3939 write to any point on the media, such as a disk; because of this, it
3940 does not work on magnetic tapes. Do not try to delete an archive member
3941 from a magnetic tape; the action will not succeed, and you will be
3942 likely to scramble the archive and damage your tape. There is no safe
3943 way (except by completely re-writing the archive) to delete files from
3944 most kinds of magnetic tape. @xref{Media}.
3946 To delete all versions of the file @file{blues} from the archive
3947 @file{collection.tar} in the @file{practice} directory, make sure you
3948 are in that directory, and then,
3951 $ @kbd{tar --list --file=collection.tar}
3961 $ @kbd{tar --delete --file=collection.tar blues}
3962 $ @kbd{tar --list --file=collection.tar}
3969 @FIXME{I changed the order of these nodes around and haven't had a chance
3970 to fix the above example's results, yet. I have to play with this and
3971 follow it and see what it actually does!}
3973 The @value{op-delete} option has been reported to work properly when
3974 @command{tar} acts as a filter from @code{stdin} to @code{stdout}.
3977 @subsection Comparing Archive Members with the File System
3978 @cindex Verifying the currency of an archive
3981 The @samp{--compare} (@samp{-d}), or @samp{--diff} operation compares
3982 specified archive members against files with the same names, and then
3983 reports differences in file size, mode, owner, modification date and
3984 contents. You should @emph{only} specify archive member names, not file
3985 names. If you do not name any members, then @command{tar} will compare the
3986 entire archive. If a file is represented in the archive but does not
3987 exist in the file system, @command{tar} reports a difference.
3989 You have to specify the record size of the archive when modifying an
3990 archive with a non-default record size.
3992 @command{tar} ignores files in the file system that do not have
3993 corresponding members in the archive.
3995 The following example compares the archive members @file{rock},
3996 @file{blues} and @file{funk} in the archive @file{bluesrock.tar} with
3997 files of the same name in the file system. (Note that there is no file,
3998 @file{funk}; @command{tar} will report an error message.)
4001 $ @kbd{tar --compare --file=bluesrock.tar rock blues funk}
4004 tar: funk not found in archive
4008 @FIXME{what does this actually depend on? i'm making a guess,
4009 here.}Depending on the system where you are running @command{tar} and the
4010 version you are running, @command{tar} may have a different error message,
4014 funk: does not exist
4017 @FIXME-xref{somewhere, for more information about format parameters.
4018 Melissa says: such as "format variations"? But why? Clearly I don't
4019 get it yet; I'll deal when I get to that section.}
4021 The spirit behind the @value{op-compare} option is to check whether the
4022 archive represents the current state of files on disk, more than validating
4023 the integrity of the archive media. For this later goal, @xref{verify}.
4025 @node create options
4026 @section Options Used by @code{--create}
4028 The previous chapter described the basics of how to use
4029 @value{op-create} to create an archive from a set of files.
4030 @xref{create}. This section described advanced options to be used with
4034 * Ignore Failed Read::
4037 @node Ignore Failed Read
4038 @subsection Ignore Fail Read
4041 @item --ignore-failed-read
4042 Do not exit with nonzero on unreadable files or directories.
4045 @node extract options
4046 @section Options Used by @code{--extract}
4049 @FIXME{i need to get dan to go over these options with me and see if
4050 there's a better way of organizing them.}
4052 The previous chapter showed how to use @value{op-extract} to extract
4053 an archive into the filesystem. Various options cause @command{tar} to
4054 extract more information than just file contents, such as the owner,
4055 the permissions, the modification date, and so forth. This section
4056 presents options to be used with @samp{--extract} when certain special
4057 considerations arise. You may review the information presented in
4058 @ref{extract} for more basic information about the
4059 @samp{--extract} operation.
4062 * Reading:: Options to Help Read Archives
4063 * Writing:: Changing How @command{tar} Writes Files
4064 * Scarce:: Coping with Scarce Resources
4068 @subsection Options to Help Read Archives
4069 @cindex Options when reading archives
4070 @cindex Reading incomplete records
4071 @cindex Records, incomplete
4072 @cindex End-of-archive entries, ignoring
4073 @cindex Ignoring end-of-archive entries
4074 @cindex Large lists of file names on small machines
4075 @cindex Small memory
4076 @cindex Running out of space
4079 Normally, @command{tar} will request data in full record increments from
4080 an archive storage device. If the device cannot return a full record,
4081 @command{tar} will report an error. However, some devices do not always
4082 return full records, or do not require the last record of an archive to
4083 be padded out to the next record boundary. To keep reading until you
4084 obtain a full record, or to accept an incomplete record if it contains
4085 an end-of-archive marker, specify the @value{op-read-full-records} option
4086 in conjunction with the @value{op-extract} or @value{op-list} operations.
4087 @value{xref-read-full-records}.
4089 The @value{op-read-full-records} option is turned on by default when
4090 @command{tar} reads an archive from standard input, or from a remote
4091 machine. This is because on BSD Unix systems, attempting to read a
4092 pipe returns however much happens to be in the pipe, even if it is
4093 less than was requested. If this option were not enabled, @command{tar}
4094 would fail as soon as it read an incomplete record from the pipe.
4096 If you're not sure of the blocking factor of an archive, you can
4097 read the archive by specifying @value{op-read-full-records} and
4098 @value{op-blocking-factor}, using a blocking factor larger than what the
4099 archive uses. This lets you avoid having to determine the blocking factor
4100 of an archive. @value{xref-blocking-factor}.
4103 * read full records::
4107 @node read full records
4108 @unnumberedsubsubsec Reading Full Records
4110 @FIXME{need sentence or so of intro here}
4113 @item --read-full-records
4115 Use in conjunction with @value{op-extract} to read an archive which
4116 contains incomplete records, or one which has a blocking factor less
4117 than the one specified.
4121 @unnumberedsubsubsec Ignoring Blocks of Zeros
4123 Normally, @command{tar} stops reading when it encounters a block of zeros
4124 between file entries (which usually indicates the end of the archive).
4125 @value{op-ignore-zeros} allows @command{tar} to completely read an archive
4126 which contains a block of zeros before the end (i.e.@: a damaged
4127 archive, or one which was created by concatenating several archives
4130 The @value{op-ignore-zeros} option is turned off by default because many
4131 versions of @command{tar} write garbage after the end-of-archive entry,
4132 since that part of the media is never supposed to be read. @acronym{GNU}
4133 @command{tar} does not write after the end of an archive, but seeks to
4134 maintain compatiblity among archiving utilities.
4137 @item --ignore-zeros
4139 To ignore blocks of zeros (ie.@: end-of-archive entries) which may be
4140 encountered while reading an archive. Use in conjunction with
4141 @value{op-extract} or @value{op-list}.
4145 @subsection Changing How @command{tar} Writes Files
4146 @cindex Overwriting old files, prevention
4147 @cindex Protecting old files
4148 @cindex Modification times of extracted files
4149 @cindex Permissions of extracted files
4150 @cindex Modes of extracted files
4151 @cindex Writing extracted files to standard output
4152 @cindex Standard output, writing extracted files to
4155 @FIXME{need to mention the brand new option, --backup}
4158 * Dealing with Old Files::
4159 * Overwrite Old Files::
4162 * Recursive Unlink::
4163 * Modification Times::
4164 * Setting Access Permissions::
4165 * Writing to Standard Output::
4169 @node Dealing with Old Files
4170 @unnumberedsubsubsec Options Controlling the Overwriting of Existing Files
4172 When extracting files, if @command{tar} discovers that the extracted
4173 file already exists, it normally replaces the file by removing it before
4174 extracting it, to prevent confusion in the presence of hard or symbolic
4175 links. (If the existing file is a symbolic link, it is removed, not
4176 followed.) However, if a directory cannot be removed because it is
4177 nonempty, @command{tar} normally overwrites its metadata (ownership,
4178 permission, etc.). The @option{--overwrite-dir} option enables this
4179 default behavior. To be more cautious and preserve the metadata of
4180 such a directory, use the @option{--no-overwrite-dir} option.
4182 To be even more cautious and prevent existing files from being replaced, use
4183 the @value{op-keep-old-files} option. It causes @command{tar} to refuse
4184 to replace or update a file that already exists, i.e., a file with the
4185 same name as an archive member prevents extraction of that archive
4186 member. Instead, it reports an error.
4188 To be more aggressive about altering existing files, use the
4189 @value{op-overwrite} option. It causes @command{tar} to overwrite
4190 existing files and to follow existing symbolic links when extracting.
4192 Some people argue that @acronym{GNU} @command{tar} should not hesitate
4193 to overwrite files with other files when extracting. When extracting
4194 a @command{tar} archive, they expect to see a faithful copy of the
4195 state of the filesystem when the archive was created. It is debatable
4196 that this would always be a proper behavior. For example, suppose one
4197 has an archive in which @file{usr/local} is a link to
4198 @file{usr/local2}. Since then, maybe the site removed the link and
4199 renamed the whole hierarchy from @file{/usr/local2} to
4200 @file{/usr/local}. Such things happen all the time. I guess it would
4201 not be welcome at all that @acronym{GNU} @command{tar} removes the
4202 whole hierarchy just to make room for the link to be reinstated
4203 (unless it @emph{also} simultaneously restores the full
4204 @file{/usr/local2}, of course! @acronym{GNU} @command{tar} is indeed
4205 able to remove a whole hierarchy to reestablish a symbolic link, for
4206 example, but @emph{only if} @value{op-recursive-unlink} is specified
4207 to allow this behavior. In any case, single files are silently
4210 Finally, the @value{op-unlink-first} option can improve performance in
4211 some cases by causing @command{tar} to remove files unconditionally
4212 before extracting them.
4214 @node Overwrite Old Files
4215 @unnumberedsubsubsec Overwrite Old Files
4219 Overwrite existing files and directory metadata when extracting files
4223 causes @command{tar} to write extracted files into the file system without
4224 regard to the files already on the system; i.e., files with the same
4225 names as archive members are overwritten when the archive is extracted.
4226 It also causes @command{tar} to extract the ownership, permissions,
4227 and time stamps onto any preexisting files or directories.
4228 If the name of a corresponding file name is a symbolic link, the file
4229 pointed to by the symbolic link will be overwritten instead of the
4230 symbolic link itself (if this is possible). Moreover, special devices,
4231 empty directories and even symbolic links are automatically removed if
4232 they are in the way of extraction.
4234 Be careful when using the @value{op-overwrite} option, particularly when
4235 combined with the @value{op-absolute-names} option, as this combination
4236 can change the contents, ownership or permissions of any file on your
4237 system. Also, many systems do not take kindly to overwriting files that
4238 are currently being executed.
4240 @item --overwrite-dir
4241 Overwrite the metadata of directories when extracting files from an
4242 archive, but remove other files before extracting.
4245 @node Keep Old Files
4246 @unnumberedsubsubsec Keep Old Files
4249 @item --keep-old-files
4251 Do not replace existing files from archive. The
4252 @value{op-keep-old-files} option prevents @command{tar} from replacing
4253 existing files with files with the same name from the archive.
4254 The @value{op-keep-old-files} option is meaningless with @value{op-list}.
4255 Prevents @command{tar} from replacing files in the file system during
4260 @unnumberedsubsubsec Unlink First
4263 @item --unlink-first
4265 Remove files before extracting over them.
4266 This can make @command{tar} run a bit faster if you know in advance
4267 that the extracted files all need to be removed. Normally this option
4268 slows @command{tar} down slightly, so it is disabled by default.
4271 @node Recursive Unlink
4272 @unnumberedsubsubsec Recursive Unlink
4275 @item --recursive-unlink
4276 When this option is specified, try removing files and directory hierarchies
4277 before extracting over them. @emph{This is a dangerous option!}
4280 If you specify the @value{op-recursive-unlink} option,
4281 @command{tar} removes @emph{anything} that keeps you from extracting a file
4282 as far as current permissions will allow it. This could include removal
4283 of the contents of a full directory hierarchy.
4285 @node Modification Times
4286 @unnumberedsubsubsec Setting Modification Times
4288 Normally, @command{tar} sets the modification times of extracted files to
4289 the modification times recorded for the files in the archive, but
4290 limits the permissions of extracted files by the current @code{umask}
4293 To set the modification times of extracted files to the time when
4294 the files were extracted, use the @value{op-touch} option in
4295 conjunction with @value{op-extract}.
4300 Sets the modification time of extracted archive members to the time
4301 they were extracted, not the time recorded for them in the archive.
4302 Use in conjunction with @value{op-extract}.
4305 @node Setting Access Permissions
4306 @unnumberedsubsubsec Setting Access Permissions
4308 To set the modes (access permissions) of extracted files to those
4309 recorded for those files in the archive, use @samp{--same-permissions}
4310 in conjunction with the @value{op-extract} operation. @FIXME{Should be
4311 aliased to ignore-umask.}
4314 @item --preserve-permission
4315 @itemx --same-permission
4316 @itemx --ignore-umask
4318 Set modes of extracted archive members to those recorded in the
4319 archive, instead of current umask settings. Use in conjunction with
4323 @FIXME{Following paragraph needs to be rewritten: why doesn't this cat
4324 files together, why is this useful. is it really useful with
4325 more than one file?}
4327 @node Writing to Standard Output
4328 @unnumberedsubsubsec Writing to Standard Output
4330 To write the extracted files to the standard output, instead of
4331 creating the files on the file system, use @value{op-to-stdout} in
4332 conjunction with @value{op-extract}. This option is useful if you are
4333 extracting files to send them through a pipe, and do not need to
4334 preserve them in the file system. If you extract multiple members,
4335 they appear on standard output concatenated, in the order they are
4336 found in the archive.
4341 Writes files to the standard output. Used in conjunction with
4342 @value{op-extract}. Extract files to standard output. When this option
4343 is used, instead of creating the files specified, @command{tar} writes
4344 the contents of the files extracted to its standard output. This may
4345 be useful if you are only extracting the files in order to send them
4346 through a pipe. This option is meaningless with @value{op-list}.
4349 This can be useful, for example, if you have a tar archive containing
4350 a big file and don't want to store the file on disk before processing
4351 it. You can use a command like this:
4354 tar -xOzf foo.tgz bigfile | process
4357 or even like this if you want to process the concatenation of the files:
4360 tar -xOzf foo.tgz bigfile1 bigfile2 | process
4364 @unnumberedsubsubsec Removing Files
4366 @FIXME{the various macros in the front of the manual think that this
4367 option goes in this section. i have no idea; i only know it's nowhere
4368 else in the book...}
4371 @item --remove-files
4372 Remove files after adding them to the archive.
4376 @subsection Coping with Scarce Resources
4377 @cindex Middle of the archive, starting in the
4378 @cindex Running out of space during extraction
4379 @cindex Disk space, running out of
4380 @cindex Space on the disk, recovering from lack of
4389 @unnumberedsubsubsec Starting File
4392 @item --starting-file=@var{name}
4393 @itemx -K @var{name}
4394 Starts an operation in the middle of an archive. Use in conjunction
4395 with @value{op-extract} or @value{op-list}.
4398 If a previous attempt to extract files failed due to lack of disk
4399 space, you can use @value{op-starting-file} to start extracting only
4400 after member @var{name} of the archive. This assumes, of course, that
4401 there is now free space, or that you are now extracting into a
4402 different file system. (You could also choose to suspend @command{tar},
4403 remove unnecessary files from the file system, and then restart the
4404 same @command{tar} operation. In this case, @value{op-starting-file} is
4405 not necessary. @value{xref-incremental}, @value{xref-interactive},
4406 and @value{ref-exclude}.)
4409 @unnumberedsubsubsec Same Order
4413 @itemx --preserve-order
4415 To process large lists of file names on machines with small amounts of
4416 memory. Use in conjunction with @value{op-compare},
4418 or @value{op-extract}.
4421 @FIXME{we don't need/want --preserve to exist any more (from melissa:
4422 ie, don't want that *version* of the option to exist, or don't want
4423 the option to exist in either version?}
4425 @FIXME{i think this explanation is lacking.}
4427 The @value{op-same-order} option tells @command{tar} that the list of file
4428 names to be listed or extracted is sorted in the same order as the
4429 files in the archive. This allows a large list of names to be used,
4430 even on a small machine that would not otherwise be able to hold all
4431 the names in memory at the same time. Such a sorted list can easily be
4432 created by running @samp{tar -t} on the archive and editing its output.
4434 This option is probably never needed on modern computer systems.
4437 @section Backup options
4439 @cindex backup options
4441 @acronym{GNU} @command{tar} offers options for making backups of files
4442 before writing new versions. These options control the details of
4443 these backups. They may apply to the archive itself before it is
4444 created or rewritten, as well as individual extracted members. Other
4445 @acronym{GNU} programs (@command{cp}, @command{install}, @command{ln},
4446 and @command{mv}, for example) offer similar options.
4448 Backup options may prove unexpectedly useful when extracting archives
4449 containing many members having identical name, or when extracting archives
4450 on systems having file name limitations, making different members appear
4451 has having similar names through the side-effect of name truncation.
4452 (This is true only if we have a good scheme for truncated backup names,
4453 which I'm not sure at all: I suspect work is needed in this area.)
4454 When any existing file is backed up before being overwritten by extraction,
4455 then clashing files are automatically be renamed to be unique, and the
4456 true name is kept for only the last file of a series of clashing files.
4457 By using verbose mode, users may track exactly what happens.
4459 At the detail level, some decisions are still experimental, and may
4460 change in the future, we are waiting comments from our users. So, please
4461 do not learn to depend blindly on the details of the backup features.
4462 For example, currently, directories themselves are never renamed through
4463 using these options, so, extracting a file over a directory still has
4464 good chances to fail. Also, backup options apply to created archives,
4465 not only to extracted members. For created archives, backups will not
4466 be attempted when the archive is a block or character device, or when it
4467 refers to a remote file.
4469 For the sake of simplicity and efficiency, backups are made by renaming old
4470 files prior to creation or extraction, and not by copying. The original
4471 name is restored if the file creation fails. If a failure occurs after a
4472 partial extraction of a file, both the backup and the partially extracted
4477 @item --backup[=@var{method}]
4479 @vindex VERSION_CONTROL
4481 Back up files that are about to be overwritten or removed.
4482 Without this option, the original versions are destroyed.
4484 Use @var{method} to determine the type of backups made.
4485 If @var{method} is not specified, use the value of the @env{VERSION_CONTROL}
4486 environment variable. And if @env{VERSION_CONTROL} is not set,
4487 use the @samp{existing} method.
4489 @vindex version-control @r{Emacs variable}
4490 This option corresponds to the Emacs variable @samp{version-control};
4491 the same values for @var{method} are accepted as in Emacs. This option
4492 also allows more descriptive names. The valid @var{method}s are:
4497 @opindex numbered @r{backup method}
4498 Always make numbered backups.
4502 @opindex existing @r{backup method}
4503 Make numbered backups of files that already have them, simple backups
4508 @opindex simple @r{backup method}
4509 Always make simple backups.
4513 @item --suffix=@var{suffix}
4515 @cindex backup suffix
4516 @vindex SIMPLE_BACKUP_SUFFIX
4517 Append @var{suffix} to each backup file made with @samp{--backup}. If this
4518 option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
4519 environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not
4520 set, the default is @samp{~}, just as in Emacs.
4524 Some people express the desire to @emph{always} use the @value{op-backup}
4525 option, by defining some kind of alias or script. This is not as easy
4526 as one may think, due to the fact that old style options should appear first
4527 and consume arguments a bit unpredictably for an alias or script. But,
4528 if you are ready to give up using old style options, you may resort to
4529 using something like (a Bourne shell function here):
4532 tar () @{ /usr/local/bin/tar --backup $*; @}
4536 @section Notable @command{tar} Usages
4539 @FIXME{Using Unix file linking capability to recreate directory
4540 structures---linking files into one subdirectory and then
4541 @command{tar}ring that directory.}
4543 @FIXME{Nice hairy example using absolute-names, newer, etc.}
4546 You can easily use archive files to transport a group of files from
4547 one system to another: put all relevant files into an archive on one
4548 computer system, transfer the archive to another system, and extract
4549 the contents there. The basic transfer medium might be magnetic tape,
4550 Internet FTP, or even electronic mail (though you must encode the
4551 archive with @command{uuencode} in order to transport it properly by
4552 mail). Both machines do not have to use the same operating system, as
4553 long as they both support the @command{tar} program.
4555 For example, here is how you might copy a directory's contents from
4556 one disk to another, while preserving the dates, modes, owners and
4557 link-structure of all the files therein. In this case, the transfer
4558 medium is a @dfn{pipe}, which is one a Unix redirection mechanism:
4561 $ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
4565 The command also works using short option forms:
4567 @FIXME{The following using standard input/output correct??}
4569 $ @w{@kbd{cd sourcedir; tar --create --file=- . | (cd targetdir; tar --extract --file=-)}}
4573 This is one of the easiest methods to transfer a @command{tar} archive.
4576 @section Looking Ahead: The Rest of this Manual
4578 You have now seen how to use all eight of the operations available to
4579 @command{tar}, and a number of the possible options. The next chapter
4580 explains how to choose and change file and archive names, how to use
4581 files to store names of other files which you can then call as
4582 arguments to @command{tar} (this can help you save time if you expect to
4583 archive the same list of files a number of times), and so forth.
4584 @FIXME{in case it's not obvious, i'm making this up in some sense
4585 based on my imited memory of what the next chapter *really* does. i
4586 just wanted to flesh out this final section a little bit so i'd
4587 remember to sitck it in here. :-)}
4589 If there are too many files to conveniently list on the command line,
4590 you can list the names in a file, and @command{tar} will read that file.
4591 @value{xref-files-from}.
4593 There are various ways of causing @command{tar} to skip over some files,
4594 and not archive them. @xref{Choosing}.
4597 @chapter Performing Backups and Restoring Files
4600 @acronym{GNU} @command{tar} is distributed along with the scripts
4601 which the Free Software Foundation uses for performing backups. There
4602 is no corresponding scripts available yet for doing restoration of
4603 files. Even if there is a good chance those scripts may be satisfying
4604 to you, they are not the only scripts or methods available for doing
4605 backups and restore. You may well create your own, or use more
4606 sophisticated packages dedicated to that purpose.
4608 Some users are enthusiastic about @code{Amanda} (The Advanced Maryland
4609 Automatic Network Disk Archiver), a backup system developed by James
4610 da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
4611 This is free software, and it is available at these places:
4614 http://www.cs.umd.edu/projects/amanda/amanda.html
4615 ftp://ftp.cs.umd.edu/pub/amanda
4620 Here is a possible plan for a future documentation about the backuping
4621 scripts which are provided within the @acronym{GNU} @command{tar}
4628 . + different levels of dumps
4629 . - full dump = dump everything
4630 . - level 1, level 2 dumps etc, -
4631 A level n dump dumps everything changed since the last level
4634 . + how to use scripts for dumps (ie, the concept)
4635 . - scripts to run after editing backup specs (details)
4637 . + Backup Specs, what is it.
4638 . - how to customize
4639 . - actual text of script [/sp/dump/backup-specs]
4642 . - rsh doesn't work
4643 . - rtape isn't installed
4646 . + the --incremental option of tar
4649 . - write protection
4651 . : different sizes and types, useful for different things
4652 . - files and tape marks
4653 one tape mark between files, two at end.
4654 . - positioning the tape
4655 MT writes two at end of write,
4656 backspaces over one when writing again.
4661 This chapter documents both the provided FSF scripts and @command{tar}
4662 options which are more specific to usage as a backup tool.
4664 To @dfn{back up} a file system means to create archives that contain
4665 all the files in that file system. Those archives can then be used to
4666 restore any or all of those files (for instance if a disk crashes or a
4667 file is accidentally deleted). File system @dfn{backups} are also
4671 * Full Dumps:: Using @command{tar} to Perform Full Dumps
4672 * Inc Dumps:: Using @command{tar} to Perform Incremental Dumps
4673 * incremental and listed-incremental:: The Incremental Options
4674 * Backup Levels:: Levels of Backups
4675 * Backup Parameters:: Setting Parameters for Backups and Restoration
4676 * Scripted Backups:: Using the Backup Scripts
4677 * Scripted Restoration:: Using the Restore Script
4681 @section Using @command{tar} to Perform Full Dumps
4687 @cindex corrupted archives
4688 Full dumps should only be made when no other people or programs
4689 are modifying files in the filesystem. If files are modified while
4690 @command{tar} is making the backup, they may not be stored properly in
4691 the archive, in which case you won't be able to restore them if you
4692 have to. (Files not being modified are written with no trouble, and do
4693 not corrupt the entire archive.)
4695 You will want to use the @value{op-label} option to give the archive a
4696 volume label, so you can tell what this archive is even if the label
4697 falls off the tape, or anything like that.
4699 Unless the filesystem you are dumping is guaranteed to fit on
4700 one volume, you will need to use the @value{op-multi-volume} option.
4701 Make sure you have enough tapes on hand to complete the backup.
4703 If you want to dump each filesystem separately you will need to use
4704 the @value{op-one-file-system} option to prevent @command{tar} from crossing
4705 filesystem boundaries when storing (sub)directories.
4707 The @value{op-incremental} option is not needed, since this is a complete
4708 copy of everything in the filesystem, and a full restore from this
4709 backup would only be done onto a completely empty disk.
4711 Unless you are in a hurry, and trust the @command{tar} program (and your
4712 tapes), it is a good idea to use the @value{op-verify} option, to make
4713 sure your files really made it onto the dump properly. This will
4714 also detect cases where the file was modified while (or just after)
4715 it was being archived. Not all media (notably cartridge tapes) are
4716 capable of being verified, unfortunately.
4718 @value{op-listed-incremental} take a file name argument always. If the
4719 file doesn't exist, run a level zero dump, creating the file. If the
4720 file exists, uses that file to see what has changed.
4722 @value{op-incremental} @FIXME{look it up}
4724 @value{op-incremental} handle old @acronym{GNU}-format incremental backup.
4726 This option should only be used when creating an incremental backup of
4727 a filesystem. When the @value{op-incremental} option is used, @command{tar}
4728 writes, at the beginning of the archive, an entry for each of the
4729 directories that will be operated on. The entry for a directory
4730 includes a list of all the files in the directory at the time the
4731 dump was done, and a flag for each file indicating whether the file
4732 is going to be put in the archive. This information is used when
4733 doing a complete incremental restore.
4735 Note that this option causes @command{tar} to create a non-standard
4736 archive that may not be readable by non-@acronym{GNU} versions of the
4737 @command{tar} program.
4739 The @value{op-incremental} option means the archive is an incremental
4740 backup. Its meaning depends on the command that it modifies.
4742 If the @value{op-incremental} option is used with @value{op-list},
4743 @command{tar} will list, for each directory in the archive, the list
4744 of files in that directory at the time the archive was created. This
4745 information is put out in a format that is not easy for humans to
4746 read, but which is unambiguous for a program: each file name is
4747 preceded by either a @samp{Y} if the file is present in the archive,
4748 an @samp{N} if the file is not included in the archive, or a @samp{D}
4749 if the file is a directory (and is included in the archive). Each
4750 file name is terminated by a null character. The last file is
4751 followed by an additional null and a newline to indicate the end of
4754 If the @value{op-incremental} option is used with @value{op-extract}, then
4755 when the entry for a directory is found, all files that currently
4756 exist in that directory but are not listed in the archive @emph{are
4757 deleted from the directory}.
4759 This behavior is convenient when you are restoring a damaged file
4760 system from a succession of incremental backups: it restores the
4761 entire state of the file system to that which obtained when the backup
4762 was made. If you don't use @value{op-incremental}, the file system will
4763 probably fill up with files that shouldn't exist any more.
4765 @value{op-listed-incremental} handle new @acronym{GNU}-format
4766 incremental backup. This option handles new @acronym{GNU}-format
4767 incremental backup. It has much the same effect as
4768 @value{op-incremental}, but also the time when the dump is done and
4769 the list of directories dumped is written to the given
4770 @var{file}. When restoring, only files newer than the saved time are
4771 restored, and the directory list is used to speed up operations.
4773 @value{op-listed-incremental} acts like @value{op-incremental}, but when
4774 used in conjunction with @value{op-create} will also cause @command{tar} to
4775 use the file @var{file}, which contains information about the state
4776 of the filesystem at the time of the last backup, to decide which
4777 files to include in the archive being created. That file will then
4778 be updated by @command{tar}. If the file @var{file} does not exist when
4779 this option is specified, @command{tar} will create it, and include all
4780 appropriate files in the archive.
4782 The file, which is archive independent, contains the date it was last
4783 modified and a list of devices, inode numbers and directory names.
4784 @command{tar} will archive files with newer mod dates or inode change
4785 times, and directories with an unchanged inode number and device but
4786 a changed directory name. The file is updated after the files to
4787 be archived are determined, but before the new archive is actually
4791 @section Using @command{tar} to Perform Incremental Dumps
4794 @cindex incremental dumps
4795 @cindex dumps, incremental
4797 Performing incremental dumps is similar to performing full dumps,
4798 although a few more options will usually be needed.
4800 A standard scheme is to do a @emph{monthly} (full) dump once a month,
4801 a @emph{weekly} dump once a week of everything since the last monthly
4802 and a @emph{daily} every day of everything since the last (weekly or
4805 Here is a sample script to dump the directory hierarchies @samp{/usr}
4811 --blocking-factor=126 \
4813 --label="`hostname` /usr /var `date +%Y-%m-%d`" \
4814 --listed-incremental=/var/log/usr-var.snar \
4819 This script uses the file @file{/var/log/usr-var.snar} as a snapshot to
4820 store information about the previous tar dump.
4822 The blocking factor 126 is an attempt to make the tape drive stream.
4823 Some tape devices cannot handle 64 kB blocks or larger, and require the
4824 block size to be a multiple of 1 kB; for these devices, 126 is the
4825 largest blocking factor that can be used.
4827 @node incremental and listed-incremental
4828 @section The Incremental Options
4831 @value{op-incremental} is used in conjunction with @value{op-create},
4832 @value{op-extract} or @value{op-list} when backing up and restoring file
4833 systems. An archive cannot be extracted or listed with the
4834 @value{op-incremental} option specified unless it was created with the
4835 option specified. This option should only be used by a script, not by
4836 the user, and is usually disregarded in favor of
4837 @value{op-listed-incremental}, which is described below.
4839 @value{op-incremental} in conjunction with @value{op-create} causes
4840 @command{tar} to write, at the beginning of the archive, an entry for
4841 each of the directories that will be archived. The entry for a
4842 directory includes a list of all the files in the directory at the
4843 time the archive was created and a flag for each file indicating
4844 whether or not the file is going to be put in the archive.
4846 Note that this option causes @command{tar} to create a non-standard
4847 archive that may not be readable by non-@acronym{GNU} versions of the
4848 @command{tar} program.
4850 @value{op-incremental} in conjunction with @value{op-extract} causes
4851 @command{tar} to read the lists of directory contents previously stored
4852 in the archive, @emph{delete} files in the file system that did not
4853 exist in their directories when the archive was created, and then
4854 extract the files in the archive.
4856 This behavior is convenient when restoring a damaged file system from
4857 a succession of incremental backups: it restores the entire state of
4858 the file system to that which obtained when the backup was made. If
4859 @value{op-incremental} isn't specified, the file system will probably
4860 fill up with files that shouldn't exist any more.
4862 @value{op-incremental} in conjunction with @value{op-list} causes
4863 @command{tar} to print, for each directory in the archive, the list of
4864 files in that directory at the time the archive was created. This
4865 information is put out in a format that is not easy for humans to
4866 read, but which is unambiguous for a program: each file name is
4867 preceded by either a @samp{Y} if the file is present in the archive,
4868 an @samp{N} if the file is not included in the archive, or a @samp{D}
4869 if the file is a directory (and is included in the archive). Each
4870 file name is terminated by a null character. The last file is followed
4871 by an additional null and a newline to indicate the end of the data.
4873 @value{op-listed-incremental} acts like @value{op-incremental}, but when
4874 used in conjunction with @value{op-create} will also cause @command{tar}
4875 to use the file @var{snapshot-file}, which contains information about
4876 the state of the file system at the time of the last backup, to decide
4877 which files to include in the archive being created. That file will
4878 then be updated by @command{tar}. If the file @var{file} does not exist
4879 when this option is specified, @command{tar} will create it, and include
4880 all appropriate files in the archive.
4882 The file @var{file}, which is archive independent, contains the date
4883 it was last modified and a list of devices, inode numbers and
4884 directory names. @command{tar} will archive files with newer mod dates
4885 or inode change times, and directories with an unchanged inode number
4886 and device but a changed directory name. The file is updated after
4887 the files to be archived are determined, but before the new archive is
4890 Incremental dumps depend crucially on time stamps, so the results are
4891 unreliable if you modify a file's time stamps during dumping (e.g.@:
4892 with the @samp{--atime-preserve} option), or if you set the clock
4895 Despite it should be obvious that a device has a non-volatile value, NFS
4896 devices have non-dependable values when an automounter gets in the picture.
4897 This led to a great deal of spurious redumping in incremental dumps,
4898 so it is somewhat useless to compare two NFS devices numbers over time.
4899 So @command{tar} now considers all NFS devices as being equal when it comes
4900 to comparing directories; this is fairly gross, but there does not seem
4901 to be a better way to go.
4903 @command{tar} doesn't access @var{snapshot-file} when
4904 @value{op-create} or @value{op-list} are specified, but the
4905 @value{op-listed-incremental} option must still be given. A
4906 placeholder @var{snapshot-file} can be specified, e.g.,
4909 @FIXME{this section needs to be written}
4912 @section Levels of Backups
4915 An archive containing all the files in the file system is called a
4916 @dfn{full backup} or @dfn{full dump}. You could insure your data by
4917 creating a full dump every day. This strategy, however, would waste a
4918 substantial amount of archive media and user time, as unchanged files
4919 are daily re-archived.
4921 It is more efficient to do a full dump only occasionally. To back up
4922 files between full dumps, you can a incremental dump. A @dfn{level
4923 one} dump archives all the files that have changed since the last full
4926 A typical dump strategy would be to perform a full dump once a week,
4927 and a level one dump once a day. This means some versions of files
4928 will in fact be archived more than once, but this dump strategy makes
4929 it possible to restore a file system to within one day of accuracy by
4930 only extracting two archives---the last weekly (full) dump and the
4931 last daily (level one) dump. The only information lost would be in
4932 files changed or created since the last daily backup. (Doing dumps
4933 more than once a day is usually not worth the trouble).
4935 @acronym{GNU} @command{tar} comes with scripts you can use to do full
4936 and level-one dumps. Using scripts (shell programs) to perform
4937 backups and restoration is a convenient and reliable alternative to
4938 typing out file name lists and @command{tar} commands by hand.
4940 Before you use these scripts, you need to edit the file
4941 @file{backup-specs}, which specifies parameters used by the backup
4942 scripts and by the restore script. @FIXME{There is no such restore
4943 script!}@FIXME-xref{Script Syntax}Once the backup parameters
4944 are set, you can perform backups or restoration by running the
4947 The name of the restore script is @code{restore}. @FIXME{There is
4948 no such restore script!}The names of the level one and full backup
4949 scripts are, respectively, @code{level-1} and @code{level-0}.
4950 The @code{level-0} script also exists under the name @code{weekly}, and
4951 the @code{level-1} under the name @code{daily}---these additional names
4952 can be changed according to your backup schedule. @FIXME-xref{Scripted
4953 Restoration, for more information on running the restoration script.}
4954 @FIXME-xref{Scripted Backups, for more information on running the
4957 @emph{Please Note:} The backup scripts and the restoration scripts are
4958 designed to be used together. While it is possible to restore files by
4959 hand from an archive which was created using a backup script, and to create
4960 an archive by hand which could then be extracted using the restore script,
4961 it is easier to use the scripts.@FIXME{There is no such restore script!}
4962 @value{xref-incremental}, and @value{xref-listed-incremental},
4963 before making such an attempt.
4965 @FIXME{shorten node names}
4967 @node Backup Parameters
4968 @section Setting Parameters for Backups and Restoration
4971 The file @file{backup-specs} specifies backup parameters for the
4972 backup and restoration scripts provided with @command{tar}. You must
4973 edit @file{backup-specs} to fit your system configuration and schedule
4974 before using these scripts.
4976 @FIXME{This about backup scripts needs to be written: BS is a shell
4977 script .... thus ... @file{backup-specs} is in shell script syntax.}
4979 @FIXME-xref{Script Syntax, for an explanation of this syntax.}
4981 @FIXME{Whats a parameter .... looked at by the backup scripts
4982 ... which will be expecting to find ... now syntax ... value is linked
4983 to lame ... @file{backup-specs} specifies the following parameters:}
4987 The user name of the backup administrator.
4990 The hour at which the backups are done. This can be a number from 0
4991 to 23, or the string @samp{now}.
4994 The device @command{tar} writes the archive to. This device should be
4995 attached to the host on which the dump scripts are run.
4997 @FIXME{examples for all ...}
5000 The command to use to obtain the status of the archive device,
5001 including error count. On some tape drives there may not be such a
5002 command; in that case, simply use @samp{TAPE_STATUS=false}.
5005 The blocking factor @command{tar} will use when writing the dump archive.
5006 @value{xref-blocking-factor}.
5009 A list of file systems to be dumped. You can include any directory
5010 name in the list---subdirectories on that file system will be
5011 included, regardless of how they may look to other networked machines.
5012 Subdirectories on other file systems will be ignored.
5014 The host name specifies which host to run @command{tar} on, and should
5015 normally be the host that actually contains the file system. However,
5016 the host machine must have @acronym{GNU} @command{tar} installed, and
5017 must be able to access the directory containing the backup scripts and
5018 their support files using the same file name that is used on the
5019 machine where the scripts are run (ie. what @command{pwd} will print
5020 when in that directory on that machine). If the host that contains
5021 the file system does not have this capability, you can specify another
5022 host as long as it can access the file system through NFS.
5025 A list of individual files to be dumped. These should be accessible
5026 from the machine on which the backup script is run.
5028 @FIXME{Same file name, be specific. Through NFS ...}
5033 * backup-specs example:: An Example Text of @file{Backup-specs}
5034 * Script Syntax:: Syntax for @file{Backup-specs}
5037 @node backup-specs example
5038 @subsection An Example Text of @file{Backup-specs}
5041 The following is the text of @file{backup-specs} as it appears at FSF:
5044 # site-specific parameters for file system backup.
5046 ADMINISTRATOR=friedman
5048 TAPE_FILE=/dev/nrsmt0
5049 TAPE_STATUS="mts -t $TAPE_FILE"
5064 apple-gunkies:/com/mailer/gnu
5065 apple-gunkies:/com/archive/gnu"
5067 BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
5072 @subsection Syntax for @file{Backup-specs}
5075 @file{backup-specs} is in shell script syntax. The following
5076 conventions should be considered when editing the script:
5077 @FIXME{"conventions?"}
5079 A quoted string is considered to be contiguous, even if it is on more
5080 than one line. Therefore, you cannot include commented-out lines
5081 within a multi-line quoted string. BACKUP_FILES and BACKUP_DIRS are
5082 the two most likely parameters to be multi-line.
5084 A quoted string typically cannot contain wildcards. In
5085 @file{backup-specs}, however, the parameters BACKUP_DIRS and
5086 BACKUP_FILES can contain wildcards.
5088 @node Scripted Backups
5089 @section Using the Backup Scripts
5092 The syntax for running a backup script is:
5095 @file{script-name} [@var{time-to-be-run}]
5098 where @var{time-to-be-run} can be a specific system time, or can be
5099 @kbd{now}. If you do not specify a time, the script runs at the time
5100 specified in @file{backup-specs}. @FIXME-pxref{Script Syntax}
5102 You should start a script with a tape or disk mounted. Once you
5103 start a script, it prompts you for new tapes or disks as it
5104 needs them. Media volumes don't have to correspond to archive
5105 files---a multi-volume archive can be started in the middle of a
5106 tape that already contains the end of another multi-volume archive.
5107 The @code{restore} script prompts for media by its archive volume,
5108 so to avoid an error message you should keep track of which tape
5109 (or disk) contains which volume of the archive. @FIXME{There is
5110 no such restore script!} @FIXME-xref{Scripted Restoration}
5111 @FIXME{Have file names changed?}
5113 The backup scripts write two files on the file system. The first is a
5114 record file in @file{/etc/tar-backup/}, which is used by the scripts
5115 to store and retrieve information about which files were dumped. This
5116 file is not meant to be read by humans, and should not be deleted by
5117 them. @FIXME-xref{incremental and listed-incremental, for a more
5118 detailed explanation of this file.}
5120 The second file is a log file containing the names of the file systems
5121 and files dumped, what time the backup was made, and any error
5122 messages that were generated, as well as how much space was left in
5123 the media volume after the last volume of the archive was written.
5124 You should check this log file after every backup. The file name is
5125 @file{log-@var{mmm-ddd-yyyy}-level-1} or
5126 @file{log-@var{mmm-ddd-yyyy}-full}.
5128 The script also prints the name of each system being dumped to the
5131 @node Scripted Restoration
5132 @section Using the Restore Script
5137 The @command{tar} distribution does not provide restoring scripts.
5144 @strong{Warning:} The @acronym{GNU} @command{tar} distribution does @emph{not}
5145 provide any such @code{restore} script yet. This section is only
5146 listed here for documentation maintenance purposes. In any case,
5147 all contents is subject to change as things develop.
5150 @FIXME{A section on non-scripted restore may be a good idea.}
5152 To restore files that were archived using a scripted backup, use the
5153 @code{restore} script. The syntax for the script is:
5155 where ***** are the file systems to restore from, and
5156 ***** is a regular expression which specifies which files to
5157 restore. If you specify --all, the script restores all the files
5160 You should start the restore script with the media containing the
5161 first volume of the archive mounted. The script will prompt for other
5162 volumes as they are needed. If the archive is on tape, you don't need
5163 to rewind the tape to to its beginning---if the tape head is
5164 positioned past the beginning of the archive, the script will rewind
5165 the tape as needed. @FIXME-xref{Media, for a discussion of tape
5168 If you specify @samp{--all} as the @var{files} argument, the
5169 @code{restore} script extracts all the files in the archived file
5170 system into the active file system.
5173 @strong{Warning:} The script will delete files from the active file
5174 system if they were not in the file system when the archive was made.
5177 @value{xref-incremental}, and @value{ref-listed-incremental},
5178 for an explanation of how the script makes that determination.
5180 @FIXME{this may be an option, not a given}
5185 @chapter Choosing Files and Names for @command{tar}
5188 @FIXME{Melissa (still) Doesn't Really Like This ``Intro'' Paragraph!!!}
5190 Certain options to @command{tar} enable you to specify a name for your
5191 archive. Other options let you decide which files to include or exclude
5192 from the archive, based on when or whether files were modified, whether
5193 the file names do or don't match specified patterns, or whether files
5194 are in specified directories.
5197 * file:: Choosing the Archive's Name
5198 * Selecting Archive Members::
5199 * files:: Reading Names from a File
5200 * exclude:: Excluding Some Files
5202 * after:: Operating Only on New Files
5203 * recurse:: Descending into Directories
5204 * one:: Crossing Filesystem Boundaries
5208 @section Choosing and Naming Archive Files
5209 @cindex Naming an archive
5210 @cindex Archive Name
5211 @cindex Directing output
5212 @cindex Choosing an archive file
5213 @cindex Where is the archive?
5216 @FIXME{should the title of this section actually be, "naming an
5219 By default, @command{tar} uses an archive file name that was compiled when
5220 it was built on the system; usually this name refers to some physical
5221 tape drive on the machine. However, the person who installed @command{tar}
5222 on the system may not set the default to a meaningful value as far as
5223 most users are concerned. As a result, you will usually want to tell
5224 @command{tar} where to find (or create) the archive. The @value{op-file}
5225 option allows you to either specify or name a file to use as the archive
5226 instead of the default archive file location.
5229 @item --file=@var{archive-name}
5230 @itemx -f @var{archive-name}
5231 Name the archive to create or operate on. Use in conjunction with
5235 For example, in this @command{tar} command,
5238 $ @kbd{tar -cvf collection.tar blues folk jazz}
5242 @file{collection.tar} is the name of the archive. It must directly
5243 follow the @samp{-f} option, since whatever directly follows @samp{-f}
5244 @emph{will} end up naming the archive. If you neglect to specify an
5245 archive name, you may end up overwriting a file in the working directory
5246 with the archive you create since @command{tar} will use this file's name
5247 for the archive name.
5249 An archive can be saved as a file in the file system, sent through a
5250 pipe or over a network, or written to an I/O device such as a tape,
5251 floppy disk, or CD write drive.
5253 @cindex Writing new archives
5254 @cindex Archive creation
5255 If you do not name the archive, @command{tar} uses the value of the
5256 environment variable @env{TAPE} as the file name for the archive. If
5257 that is not available, @command{tar} uses a default, compiled-in archive
5258 name, usually that for tape unit zero (ie. @file{/dev/tu00}).
5259 @command{tar} always needs an archive name.
5261 If you use @file{-} as an @var{archive-name}, @command{tar} reads the
5262 archive from standard input (when listing or extracting files), or
5263 writes it to standard output (when creating an archive). If you use
5264 @file{-} as an @var{archive-name} when modifying an archive,
5265 @command{tar} reads the original archive from its standard input and
5266 writes the entire new archive to its standard output.
5268 @FIXME{might want a different example here; this is already used in
5269 "notable tar usages".}
5272 $ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
5277 @cindex Standard input and output
5278 @cindex tar to standard input and output
5279 To specify an archive file on a device attached to a remote machine,
5283 @kbd{--file=@var{hostname}:/@var{dev}/@var{file name}}
5287 @command{tar} will complete the remote connection, if possible, and
5288 prompt you for a username and password. If you use
5289 @samp{--file=@@@var{hostname}:/@var{dev}/@var{file name}}, @command{tar}
5290 will complete the remote connection, if possible, using your username
5291 as the username on the remote machine.
5293 If the archive file name includes a colon (@samp{:}), then it is assumed
5294 to be a file on another machine. If the archive file is
5295 @samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
5296 host @var{host}. The remote host is accessed using the @command{rsh}
5297 program, with a username of @var{user}. If the username is omitted
5298 (along with the @samp{@@} sign), then your user name will be used.
5299 (This is the normal @command{rsh} behavior.) It is necessary for the
5300 remote machine, in addition to permitting your @command{rsh} access, to
5301 have the @file{/usr/ucb/rmt} program installed. If you need to use a
5302 file whose name includes a colon, then the remote tape drive behavior
5303 can be inhibited by using the @value{op-force-local} option.
5305 @FIXME{i know we went over this yesterday, but bob (and now i do again,
5306 too) thinks it's out of the middle of nowhere. it doesn't seem to tie
5307 into what came before it well enough <<i moved it now, is it better
5308 here?>>. bob also comments that if Amanda isn't free software, we
5309 shouldn't mention it..}
5311 When the archive is being created to @file{/dev/null}, @acronym{GNU}
5312 @command{tar} tries to minimize input and output operations. The
5313 Amanda backup system, when used with @acronym{GNU} @command{tar}, has
5314 an initial sizing pass which uses this feature.
5316 @node Selecting Archive Members
5317 @section Selecting Archive Members
5318 @cindex Specifying files to act on
5319 @cindex Specifying archive members
5321 @dfn{File Name arguments} specify which files in the file system
5322 @command{tar} operates on, when creating or adding to an archive, or which
5323 archive members @command{tar} operates on, when reading or deleting from
5324 an archive. @xref{Operations}.
5326 To specify file names, you can include them as the last arguments on
5327 the command line, as follows:
5329 @kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}]
5332 If you specify a directory name as a file name argument, all the files
5333 in that directory are operated on by @command{tar}.
5335 If you do not specify files when @command{tar} is invoked with
5336 @value{op-create}, @command{tar} operates on all the non-directory files in
5337 the working directory. If you specify either @value{op-list} or
5338 @value{op-extract}, @command{tar} operates on all the archive members in the
5339 archive. If you specify any operation other than one of these three,
5340 @command{tar} does nothing.
5342 By default, @command{tar} takes file names from the command line. However,
5343 there are other ways to specify file or member names, or to modify the
5344 manner in which @command{tar} selects the files or members upon which to
5345 operate. @FIXME{add xref here}In general, these methods work both for
5346 specifying the names of files and archive members.
5349 @section Reading Names from a File
5352 @cindex Reading file names from a file
5353 @cindex Lists of file names
5354 @cindex File Name arguments, alternatives
5355 Instead of giving the names of files or archive members on the command
5356 line, you can put the names into a file, and then use the
5357 @value{op-files-from} option to @command{tar}. Give the name of the file
5358 which contains the list of files to include as the argument to
5359 @samp{--files-from}. In the list, the file names should be separated by
5360 newlines. You will frequently use this option when you have generated
5361 the list of files to archive with the @command{find} utility.
5364 @item --files-from=@var{file name}
5365 @itemx -T @var{file name}
5366 Get names to extract or create from file @var{file name}.
5369 If you give a single dash as a file name for @samp{--files-from}, (i.e.,
5370 you specify either @samp{--files-from=-} or @samp{-T -}), then the file
5371 names are read from standard input.
5373 Unless you are running @command{tar} with @samp{--create}, you can not use
5374 both @samp{--files-from=-} and @samp{--file=-} (@samp{-f -}) in the same
5377 @FIXME{add bob's example, from his message on 2-10-97}
5379 The following example shows how to use @command{find} to generate a list of
5380 files smaller than 400K in length and put that list into a file
5381 called @file{small-files}. You can then use the @samp{-T} option to
5382 @command{tar} to specify the files from that file, @file{small-files}, to
5383 create the archive @file{little.tgz}. (The @samp{-z} option to
5384 @command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for
5388 $ @kbd{find . -size -400 -print > small-files}
5389 $ @kbd{tar -c -v -z -T small-files -f little.tgz}
5393 @FIXME{say more here to conclude the example/section?}
5400 @subsection @kbd{NUL} Terminated File Names
5402 @cindex File names, terminated by @kbd{NUL}
5403 @cindex @kbd{NUL} terminated file names
5404 The @value{op-null} option causes @value{op-files-from} to read file
5405 names terminated by a @code{NUL} instead of a newline, so files whose
5406 names contain newlines can be archived using @samp{--files-from}.
5410 Only consider @kbd{NUL} terminated file names, instead of files that
5411 terminate in a newline.
5414 The @samp{--null} option is just like the one in @acronym{GNU}
5415 @command{xargs} and @command{cpio}, and is useful with the
5416 @samp{-print0} predicate of @acronym{GNU} @command{find}. In
5417 @command{tar}, @samp{--null} also causes @value{op-directory} options
5418 to be treated as file names to archive, in case there are any files
5419 out there called @file{-C}.
5421 This example shows how to use @command{find} to generate a list of files
5422 larger than 800K in length and put that list into a file called
5423 @file{long-files}. The @samp{-print0} option to @command{find} just just
5424 like @samp{-print}, except that it separates files with a @kbd{NUL}
5425 rather than with a newline. You can then run @command{tar} with both the
5426 @samp{--null} and @samp{-T} options to specify that @command{tar} get the
5427 files from that file, @file{long-files}, to create the archive
5428 @file{big.tgz}. The @samp{--null} option to @command{tar} will cause
5429 @command{tar} to recognize the @kbd{NUL} separator between files.
5432 $ @kbd{find . -size +800 -print0 > long-files}
5433 $ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
5436 @FIXME{say anything else here to conclude the section?}
5439 @section Excluding Some Files
5440 @cindex File names, excluding files by
5441 @cindex Excluding files by name and pattern
5442 @cindex Excluding files by file system
5445 To avoid operating on files whose names match a particular pattern,
5446 use the @value{op-exclude} or @value{op-exclude-from} options.
5449 @item --exclude=@var{pattern}
5450 Causes @command{tar} to ignore files that match the @var{pattern}.
5454 The @value{op-exclude} option prevents any file or member whose name
5455 matches the shell wildcard (@var{pattern}) from being operated on.
5456 For example, to create an archive with all the contents of the directory
5457 @file{src} except for files whose names end in @file{.o}, use the
5458 command @samp{tar -cf src.tar --exclude='*.o' src}.
5460 You may give multiple @samp{--exclude} options.
5463 @item --exclude-from=@var{file}
5464 @itemx -X @var{file}
5465 Causes @command{tar} to ignore files that match the patterns listed in
5469 @findex exclude-from
5470 Use the @samp{--exclude-from=@var{file-of-patterns}} option to read a
5471 list of patterns, one per line, from @var{file}; @command{tar} will
5472 ignore files matching those patterns. Thus if @command{tar} is
5473 called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a
5474 single line @file{*.o}, no files whose names end in @file{.o} will be
5475 added to the archive.
5477 @FIXME{do the exclude options files need to have stuff separated by
5478 newlines the same as the files-from option does?}
5481 * controlling pattern-patching with exclude::
5482 * problems with exclude::
5485 @node controlling pattern-patching with exclude
5486 @unnumberedsubsec Controlling Pattern-Matching with the @code{exclude} Options
5488 Normally, a pattern matches a name if an initial subsequence of the
5489 name's components matches the pattern, where @samp{*}, @samp{?}, and
5490 @samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards,
5491 and wildcards can match @samp{/}.
5493 Other than optionally stripping leading @samp{/} from names
5494 (@pxref{absolute}), patterns and names are used as-is. For
5495 example, trailing @samp{/} is not trimmed from a user-specified name
5496 before deciding whether to exclude it.
5498 However, this matching procedure can be altered by the options listed
5499 below. These options accumulate. For example:
5502 --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
5505 ignores case when excluding @samp{makefile}, but not when excluding
5510 @itemx --no-anchored
5511 If anchored (the default), a pattern must match an initial subsequence
5512 of the name's components. Otherwise, the pattern can match any subsequence.
5515 @itemx --no-ignore-case
5516 When ignoring case, upper-case patterns match lower-case names and vice versa.
5517 When not ignoring case (the default), matching is case-sensitive.
5520 @itemx --no-wildcards
5521 When using wildcards (the default), @samp{*}, @samp{?}, and @samp{[...]}
5522 are the usual shell wildcards, and @samp{\} escapes wildcards.
5523 Otherwise, none of these characters are special, and patterns must match
5526 @item --wildcards-match-slash
5527 @itemx --no-wildcards-match-slash
5528 When wildcards match slash (the default), a wildcard like @samp{*} in
5529 the pattern can match a @samp{/} in the name. Otherwise, @samp{/} is
5530 matched only by @samp{/}.
5534 The @option{--recursion} and @option{--no-recursion} options
5535 (@pxref{recurse}) also affect how exclude patterns are interpreted. If
5536 recursion is in effect, a pattern excludes a name if it matches any of
5537 the name's parent directories.
5539 @node problems with exclude
5540 @unnumberedsubsec Problems with Using the @code{exclude} Options
5542 Some users find @samp{exclude} options confusing. Here are some common
5547 The main operating mode of @command{tar} does not act on a path name
5548 explicitly listed on the command line if one of its file name
5549 components is excluded. In the example above, if
5550 you create an archive and exclude files that end with @samp{*.o}, but
5551 explicitly name the file @samp{dir.o/foo} after all the options have been
5552 listed, @samp{dir.o/foo} will be excluded from the archive.
5555 You can sometimes confuse the meanings of @value{op-exclude} and
5556 @value{op-exclude-from}. Be careful: use @value{op-exclude} when files
5557 to be excluded are given as a pattern on the command line. Use
5558 @samp{--exclude-from=@var{file-of-patterns}} to introduce the name of a
5559 file which contains a list of patterns, one per line; each of these
5560 patterns can exclude zero, one, or many files.
5563 When you use @value{op-exclude}, be sure to quote the @var{pattern}
5564 parameter, so @acronym{GNU} @command{tar} sees wildcard characters
5565 like @samp{*}. If you do not do this, the shell might expand the
5566 @samp{*} itself using files at hand, so @command{tar} might receive a
5567 list of files instead of one pattern, or none at all, making the
5568 command somewhat illegal. This might not correspond to what you want.
5573 $ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
5580 $ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
5584 You must use use shell syntax, or globbing, rather than @code{regexp}
5585 syntax, when using exclude options in @command{tar}. If you try to use
5586 @code{regexp} syntax to describe files to be excluded, your command
5590 In earlier versions of @command{tar}, what is now the
5591 @samp{--exclude-from=@var{file-of-patterns}} option was called
5592 @samp{--exclude=@var{pattern}} instead. Now,
5593 @samp{--exclude=@var{pattern}} applies to patterns listed on the command
5594 line and @samp{--exclude-from=@var{file-of-patterns}} applies to
5595 patterns listed in a file.
5600 @section Wildcards Patterns and Matching
5602 @dfn{Globbing} is the operation by which @dfn{wildcard} characters,
5603 @samp{*} or @samp{?} for example, are replaced and expanded into all
5604 existing files matching the given pattern. However, @command{tar} often
5605 uses wildcard patterns for matching (or globbing) archive members instead
5606 of actual files in the filesystem. Wildcard patterns are also used for
5607 verifying volume labels of @command{tar} archives. This section has the
5608 purpose of explaining wildcard syntax for @command{tar}.
5610 @FIXME{the next few paragraphs need work.}
5612 A @var{pattern} should be written according to shell syntax, using wildcard
5613 characters to effect globbing. Most characters in the pattern stand
5614 for themselves in the matched string, and case is significant: @samp{a}
5615 will match only @samp{a}, and not @samp{A}. The character @samp{?} in the
5616 pattern matches any single character in the matched string. The character
5617 @samp{*} in the pattern matches zero, one, or more single characters in
5618 the matched string. The character @samp{\} says to take the following
5619 character of the pattern @emph{literally}; it is useful when one needs to
5620 match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
5622 The character @samp{[}, up to the matching @samp{]}, introduces a character
5623 class. A @dfn{character class} is a list of acceptable characters
5624 for the next single character of the matched string. For example,
5625 @samp{[abcde]} would match any of the first five letters of the alphabet.
5626 Note that within a character class, all of the ``special characters''
5627 listed above other than @samp{\} lose their special meaning; for example,
5628 @samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\},
5629 @samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints,
5630 the characters @samp{-} and @samp{]} must either come @emph{first} or
5631 @emph{last} in a character class.)
5633 @cindex Excluding characters from a character class
5634 @cindex Character class, excluding characters from
5635 If the first character of the class after the opening @samp{[}
5636 is @samp{!} or @samp{^}, then the meaning of the class is reversed.
5637 Rather than listing character to match, it lists those characters which
5638 are @emph{forbidden} as the next single character of the matched string.
5640 Other characters of the class stand for themselves. The special
5641 construction @samp{[@var{a}-@var{e}]}, using an hyphen between two
5642 letters, is meant to represent all characters between @var{a} and
5645 @FIXME{need to add a sentence or so here to make this clear for those
5646 who don't have dan around.}
5648 Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
5649 special for wildcard matches. However, if a pattern completely matches
5650 a directory prefix of a matched string, then it matches the full matched
5651 string: excluding a directory also excludes all the files beneath it.
5654 @section Operating Only on New Files
5655 @cindex Excluding file by age
5656 @cindex Modification time, excluding files by
5657 @cindex Age, excluding files by
5660 The @value{op-after-date} option causes @command{tar} to only work on files
5661 whose modification or inode-changed times are newer than the @var{date}
5662 given. If @var{date} starts with @samp{/} or @samp{.}, it is taken to
5663 be a file name; the last-modified time of that file is used as the date.
5664 If you use this option when creating or appending to an archive,
5665 the archive will only include new files. If you use @samp{--after-date}
5666 when extracting an archive, @command{tar} will only extract files newer
5667 than the @var{date} you specify.
5669 If you only want @command{tar} to make the date comparison based on
5670 modification of the actual contents of the file (rather than inode
5671 changes), then use the @value{op-newer-mtime} option.
5673 You may use these options with any operation. Note that these options
5674 differ from the @value{op-update} operation in that they allow you to
5675 specify a particular date against which @command{tar} can compare when
5676 deciding whether or not to archive the files.
5679 @item --after-date=@var{date}
5680 @itemx --newer=@var{date}
5681 @itemx -N @var{date}
5682 Only store files newer than @var{date}.
5684 Acts on files only if their modification or inode-changed times are
5685 later than @var{date}. Use in conjunction with any operation.
5687 If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file
5688 name; the last-modified time of that file is used as the date.
5690 @item --newer-mtime=@var{date}
5691 Acts like @value{op-after-date}, but only looks at modification times.
5694 These options limit @command{tar} to only operating on files which have
5695 been modified after the date specified. A file is considered to have
5696 changed if the contents have been modified, or if the owner,
5697 permissions, and so forth, have been changed. (For more information on
5698 how to specify a date, see @ref{Date input formats}; remember that the
5699 entire date argument must be quoted if it contains any spaces.)
5701 Gurus would say that @value{op-after-date} tests both the @code{mtime}
5702 (time the contents of the file were last modified) and @code{ctime}
5703 (time the file's status was last changed: owner, permissions, etc)
5704 fields, while @value{op-newer-mtime} tests only @code{mtime} field.
5706 To be precise, @value{op-after-date} checks @emph{both} @code{mtime} and
5707 @code{ctime} and processes the file if either one is more recent than
5708 @var{date}, while @value{op-newer-mtime} only checks @code{mtime} and
5709 disregards @code{ctime}. Neither uses @code{atime} (the last time the
5710 contents of the file were looked at).
5712 Date specifiers can have embedded spaces. Because of this, you may need
5713 to quote date arguments to keep the shell from parsing them as separate
5716 @FIXME{Need example of --newer-mtime with quoted argument.}
5719 @strong{Please Note:} @value{op-after-date} and @value{op-newer-mtime}
5720 should not be used for incremental backups. Some files (such as those
5721 in renamed directories) are not selected properly by these options.
5722 @xref{incremental and listed-incremental}.
5726 @FIXME{which tells -- need to fill this in!}
5729 @section Descending into Directories
5730 @cindex Avoiding recursion in directories
5731 @cindex Descending directories, avoiding
5732 @cindex Directories, avoiding recursion
5733 @cindex Recursion in directories, avoiding
5736 @FIXME{arrggh! this is still somewhat confusing to me. :-< }
5738 @FIXME{show dan bob's comments, from 2-10-97}
5740 Usually, @command{tar} will recursively explore all directories (either
5741 those given on the command line or through the @value{op-files-from}
5742 option) for the various files they contain. However, you may not always
5743 want @command{tar} to act this way.
5745 The @value{op-no-recursion} option inhibits @command{tar}'s recursive descent
5746 into specified directories. If you specify @samp{--no-recursion}, you can
5747 use the @command{find} utility for hunting through levels of directories to
5748 construct a list of file names which you could then pass to @command{tar}.
5749 @command{find} allows you to be more selective when choosing which files to
5750 archive; see @ref{files} for more information on using @command{find} with
5751 @command{tar}, or look.
5754 @item --no-recursion
5755 Prevents @command{tar} from recursively descending directories.
5758 Requires @command{tar} to recursively descend directories.
5759 This is the default.
5762 When you use @samp{--no-recursion}, @acronym{GNU} @command{tar} grabs
5763 directory entries themselves, but does not descend on them
5764 recursively. Many people use @command{find} for locating files they
5765 want to back up, and since @command{tar} @emph{usually} recursively
5766 descends on directories, they have to use the @samp{@w{! -d}} option
5767 to @command{find} @FIXME{needs more explanation or a cite to another
5768 info file}as they usually do not want all the files in a directory.
5769 They then use the @value{op-files-from} option to archive the files
5770 located via @command{find}.
5772 The problem when restoring files archived in this manner is that the
5773 directories themselves are not in the archive; so the
5774 @value{op-same-permissions} option does not affect them---while users
5775 might really like it to. Specifying @value{op-no-recursion} is a way to
5776 tell @command{tar} to grab only the directory entries given to it, adding
5777 no new files on its own.
5779 The @value{op-no-recursion} option also applies when extracting: it
5780 causes @command{tar} to extract only the matched directory entries, not
5781 the files under those directories.
5783 The @value{op-no-recursion} option also affects how exclude patterns
5784 are interpreted (@pxref{controlling pattern-patching with exclude}).
5786 The @option{--no-recursion} and @option{--recursion} options apply to
5787 later options and operands, and can be overridden by later occurrences
5788 of @option{--no-recursion} and @option{--recursion}. For example:
5791 $ @kbd{tar -cf jams.tar --norecursion grape --recursion grape/concord}
5795 creates an archive with one entry for @file{grape}, and the recursive
5796 contents of @file{grape/concord}, but no entries under @file{grape}
5797 other than @file{grape/concord}.
5800 @section Crossing Filesystem Boundaries
5801 @cindex File system boundaries, not crossing
5804 @command{tar} will normally automatically cross file system boundaries in
5805 order to archive files which are part of a directory tree. You can
5806 change this behavior by running @command{tar} and specifying
5807 @value{op-one-file-system}. This option only affects files that are
5808 archived because they are in a directory that is being archived;
5809 @command{tar} will still archive files explicitly named on the command line
5810 or through @value{op-files-from}, regardless of where they reside.
5813 @item --one-file-system
5815 Prevents @command{tar} from crossing file system boundaries when
5816 archiving. Use in conjunction with any write operation.
5819 The @samp{--one-file-system} option causes @command{tar} to modify its
5820 normal behavior in archiving the contents of directories. If a file in
5821 a directory is not on the same filesystem as the directory itself, then
5822 @command{tar} will not archive that file. If the file is a directory
5823 itself, @command{tar} will not archive anything beneath it; in other words,
5824 @command{tar} will not cross mount points.
5826 It is reported that using this option, the mount point is is archived,
5827 but nothing under it.
5829 This option is useful for making full or incremental archival backups of
5830 a file system. If this option is used in conjunction with
5831 @value{op-verbose}, files that are excluded are mentioned by name on the
5835 * directory:: Changing Directory
5836 * absolute:: Absolute File Names
5840 @subsection Changing the Working Directory
5842 @FIXME{need to read over this node now for continuity; i've switched
5843 things around some.}
5845 @cindex Changing directory mid-stream
5846 @cindex Directory, changing mid-stream
5847 @cindex Working directory, specifying
5850 To change the working directory in the middle of a list of file names,
5851 either on the command line or in a file specified using
5852 @value{op-files-from}, use @value{op-directory}. This will change the
5853 working directory to the directory @var{directory} after that point in
5857 @item --directory=@var{directory}
5858 @itemx -C @var{directory}
5859 Changes the working directory in the middle of a command line.
5865 $ @kbd{tar -c -f jams.tar grape prune -C food cherry}
5869 will place the files @file{grape} and @file{prune} from the current
5870 directory into the archive @file{jams.tar}, followed by the file
5871 @file{cherry} from the directory @file{food}. This option is especially
5872 useful when you have several widely separated files that you want to
5873 store in the same archive.
5875 Note that the file @file{cherry} is recorded in the archive under the
5876 precise name @file{cherry}, @emph{not} @file{food/cherry}. Thus, the
5877 archive will contain three files that all appear to have come from the
5878 same directory; if the archive is extracted with plain @samp{tar
5879 --extract}, all three files will be written in the current directory.
5881 Contrast this with the command,
5884 $ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}
5888 which records the third file in the archive under the name
5889 @file{red/cherry} so that, if the archive is extracted using
5890 @samp{tar --extract}, the third file will be written in a subdirectory
5891 named @file{orange-colored}.
5893 You can use the @samp{--directory} option to make the archive
5894 independent of the original name of the directory holding the files.
5895 The following command places the files @file{/etc/passwd},
5896 @file{/etc/hosts}, and @file{/lib/libc.a} into the archive
5900 $ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}
5904 However, the names of the archive members will be exactly what they were
5905 on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}.
5906 They will not appear to be related by file name to the original
5907 directories where those files were located.
5909 Note that @samp{--directory} options are interpreted consecutively. If
5910 @samp{--directory} specifies a relative file name, it is interpreted
5911 relative to the then current directory, which might not be the same as
5912 the original current working directory of @command{tar}, due to a previous
5913 @samp{--directory} option.
5915 @FIXME{dan: does this mean that you *can* use the short option form, but
5916 you can *not* use the long option form with --files-from? or is this
5919 When using @samp{--files-from} (@pxref{files}), you can put @samp{-C}
5920 options in the file list. Unfortunately, you cannot put
5921 @samp{--directory} options in the file list. (This interpretation can
5922 be disabled by using the @value{op-null} option.)
5925 @subsection Absolute File Names
5930 @itemx --absolute-names
5931 Do not strip leading slashes from file names, and permit file names
5932 containing a @file{..} file name component.
5935 By default, @acronym{GNU} @command{tar} drops a leading @samp{/} on
5936 input or output, and complains about file names containing a @file{..}
5937 component. This option turns off this behavior.
5939 When @command{tar} extracts archive members from an archive, it strips any
5940 leading slashes (@samp{/}) from the member name. This causes absolute
5941 member names in the archive to be treated as relative file names. This
5942 allows you to have such members extracted wherever you want, instead of
5943 being restricted to extracting the member in the exact directory named
5944 in the archive. For example, if the archive member has the name
5945 @file{/etc/passwd}, @command{tar} will extract it as if the name were
5946 really @file{etc/passwd}.
5948 File names containing @file{..} can cause problems when extracting, so
5949 @command{tar} normally warns you about such files when creating an
5950 archive, and rejects attempts to extracts such files.
5952 Other @command{tar} programs do not do this. As a result, if you
5953 create an archive whose member names start with a slash, they will be
5954 difficult for other people with a non-@acronym{GNU} @command{tar}
5955 program to use. Therefore, @acronym{GNU} @command{tar} also strips
5956 leading slashes from member names when putting members into the
5957 archive. For example, if you ask @command{tar} to add the file
5958 @file{/bin/ls} to an archive, it will do so, but the member name will
5961 If you use the @value{op-absolute-names} option, @command{tar} will do
5962 none of these transformations.
5964 To archive or extract files relative to the root directory, specify
5965 the @value{op-absolute-names} option.
5967 Normally, @command{tar} acts on files relative to the working
5968 directory---ignoring superior directory names when archiving, and
5969 ignoring leading slashes when extracting.
5971 When you specify @value{op-absolute-names}, @command{tar} stores file names
5972 including all superior directory names, and preserves leading slashes.
5973 If you only invoked @command{tar} from the root directory you would never
5974 need the @value{op-absolute-names} option, but using this option may be
5975 more convenient than switching to root.
5977 @FIXME{Should be an example in the tutorial/wizardry section using this
5978 to transfer files between systems.}
5980 @FIXME{Is write access an issue?}
5983 @item --absolute-names
5984 Preserves full file names (including superior directory names) when
5985 archiving files. Preserves leading slash when extracting files.
5989 @FIXME{this is still horrible; need to talk with dan on monday.}
5991 @command{tar} prints out a message about removing the @samp{/} from
5992 file names. This message appears once per @acronym{GNU} @command{tar}
5993 invocation. It represents something which ought to be told; ignoring
5994 what it means can cause very serious surprises, later.
5996 Some people, nevertheless, do not want to see this message. Wanting to
5997 play really dangerously, one may of course redirect @command{tar} standard
5998 error to the sink. For example, under @command{sh}:
6001 $ @kbd{tar -c -f archive.tar /home 2> /dev/null}
6005 Another solution, both nicer and simpler, would be to change to
6006 the @file{/} directory first, and then avoid absolute notation.
6010 $ @kbd{(cd / && tar -c -f archive.tar home)}
6011 $ @kbd{tar -c -f archive.tar -C / home}
6014 @include getdate.texi
6017 @chapter Controlling the Archive Format
6019 @FIXME{need an intro here}
6022 * Portability:: Making @command{tar} Archives More Portable
6023 * Compression:: Using Less Space through Compression
6024 * Attributes:: Handling File Attributes
6025 * Standard:: The Standard Format
6026 * Extensions:: @acronym{GNU} Extensions to the Archive Format
6027 * cpio:: Comparison of @command{tar} and @command{cpio}
6031 @section Making @command{tar} Archives More Portable
6033 Creating a @command{tar} archive on a particular system that is meant to be
6034 useful later on many other machines and with other versions of @command{tar}
6035 is more challenging than you might think. @command{tar} archive formats
6036 have been evolving since the first versions of Unix. Many such formats
6037 are around, and are not always compatible with each other. This section
6038 discusses a few problems, and gives some advice about making @command{tar}
6039 archives more portable.
6041 One golden rule is simplicity. For example, limit your @command{tar}
6042 archives to contain only regular files and directories, avoiding
6043 other kind of special files. Do not attempt to save sparse files or
6044 contiguous files as such. Let's discuss a few more problems, in turn.
6047 * Portable Names:: Portable Names
6048 * dereference:: Symbolic Links
6049 * old:: Old V7 Archives
6050 * posix:: @sc{posix} archives
6051 * Checksumming:: Checksumming Problems
6052 * Large or Negative Values:: Large files, negative time stamps, etc.
6055 @node Portable Names
6056 @subsection Portable Names
6058 Use portable file and member names. A name is portable if it contains
6059 only ASCII letters and digits, @samp{/}, @samp{.}, @samp{_}, and
6060 @samp{-}; it cannot be empty, start with @samp{-} or @samp{//}, or
6061 contain @samp{/-}. Avoid deep directory nesting. For portability to
6062 old Unix hosts, limit your file name components to 14 characters or
6065 If you intend to have your @command{tar} archives to be read under
6066 MSDOS, you should not rely on case distinction for file names, and you
6067 might use the @acronym{GNU} @command{doschk} program for helping you
6068 further diagnosing illegal MSDOS names, which are even more limited
6072 @subsection Symbolic Links
6073 @cindex File names, using symbolic links
6074 @cindex Symbolic link as file name
6076 Normally, when @command{tar} archives a symbolic link, it writes a
6077 block to the archive naming the target of the link. In that way, the
6078 @command{tar} archive is a faithful record of the filesystem contents.
6079 @value{op-dereference} is used with @value{op-create}, and causes
6080 @command{tar} to archive the files symbolic links point to, instead of
6081 the links themselves. When this option is used, when @command{tar}
6082 encounters a symbolic link, it will archive the linked-to file,
6083 instead of simply recording the presence of a symbolic link.
6085 The name under which the file is stored in the file system is not
6086 recorded in the archive. To record both the symbolic link name and
6087 the file name in the system, archive the file under both names. If
6088 all links were recorded automatically by @command{tar}, an extracted file
6089 might be linked to a file name that no longer exists in the file
6092 If a linked-to file is encountered again by @command{tar} while creating
6093 the same archive, an entire second copy of it will be stored. (This
6094 @emph{might} be considered a bug.)
6096 So, for portable archives, do not archive symbolic links as such,
6097 and use @value{op-dereference}: many systems do not support
6098 symbolic links, and moreover, your distribution might be unusable if
6099 it contains unresolved symbolic links.
6102 @subsection Old V7 Archives
6103 @cindex Format, old style
6104 @cindex Old style format
6105 @cindex Old style archives
6107 Certain old versions of @command{tar} cannot handle additional
6108 information recorded by newer @command{tar} programs. To create an
6109 archive in V7 format (not ANSI), which can be read by these old
6110 versions, specify the @value{op-old-archive} option in
6111 conjunction with the @value{op-create}. @command{tar} also
6112 accepts @samp{--portability} for this option. When you specify it,
6113 @command{tar} leaves out information about directories, pipes, fifos,
6114 contiguous files, and device files, and specifies file ownership by
6115 group and user IDs instead of group and user names.
6117 When updating an archive, do not use @value{op-old-archive}
6118 unless the archive was created with using this option.
6120 In most cases, a @emph{new} format archive can be read by an @emph{old}
6121 @command{tar} program without serious trouble, so this option should
6122 seldom be needed. On the other hand, most modern @command{tar}s are
6123 able to read old format archives, so it might be safer for you to
6124 always use @value{op-old-archive} for your distributions.
6127 @subsection @acronym{GNU} @command{tar} and @sc{posix} @command{tar}
6129 @acronym{GNU} @command{tar} was based on an early draft of the
6130 @sc{posix} 1003.1 @code{ustar} standard. @acronym{GNU} extensions to
6131 @command{tar}, such as the support for file names longer than 100
6132 characters, use portions of the @command{tar} header record which were
6133 specified in that @sc{posix} draft as unused. Subsequent changes in
6134 @sc{posix} have allocated the same parts of the header record for
6135 other purposes. As a result, @acronym{GNU} @command{tar} is
6136 incompatible with the current @sc{posix} spec, and with @command{tar}
6137 programs that follow it.
6139 We plan to reimplement these @acronym{GNU} extensions in a new way which is
6140 upward compatible with the latest @sc{posix} @command{tar} format, but we
6141 don't know when this will be done.
6143 In the mean time, there is simply no telling what might happen if you
6144 read a @acronym{GNU} @command{tar} archive, which uses the
6145 @acronym{GNU} extensions, using some other @command{tar} program. So
6146 if you want to read the archive with another @command{tar} program, be
6147 sure to write it using the @samp{--old-archive} option (@samp{-o}).
6149 @FIXME{is there a way to tell which flavor of tar was used to write a
6150 particular archive before you try to read it?}
6152 Traditionally, old @command{tar}s have a limit of 100 characters.
6153 @acronym{GNU} @command{tar} attempted two different approaches to
6154 overcome this limit, using and extending a format specified by a draft
6155 of some P1003.1. The first way was not that successful, and involved
6156 @file{@@MaNgLeD@@} file names, or such; while a second approach used
6157 @file{././@@LongLink} and other tricks, yielding better success. In
6158 theory, @acronym{GNU} @command{tar} should be able to handle file
6159 names of practically unlimited length. So, if @acronym{GNU}
6160 @command{tar} fails to dump and retrieve files having more than 100
6161 characters, then there is a bug in @acronym{GNU} @command{tar},
6164 But, being strictly @sc{posix}, the limit was still 100 characters.
6165 For various other purposes, @acronym{GNU} @command{tar} used areas
6166 left unassigned in the @sc{posix} draft. @sc{posix} later revised
6167 P1003.1 @code{ustar} format by assigning previously unused header
6168 fields, in such a way that the upper limit for file name length was
6169 raised to 256 characters. However, the actual @sc{posix} limit
6170 oscillates between 100 and 256, depending on the precise location of
6171 slashes in full file name (this is rather ugly). Since @acronym{GNU}
6172 @command{tar} use the same fields for quite other purposes, it became
6173 incompatible with the latest @sc{posix} standards.
6175 For longer or non-fitting file names, we plan to use yet another set
6176 of @acronym{GNU} extensions, but this time, complying with the
6177 provisions @sc{posix} offers for extending the format, rather than
6178 conflicting with it. Whenever an archive uses old @acronym{GNU}
6179 @command{tar} extension format or @sc{posix} extensions, would it be
6180 for very long file names or other specialities, this archive becomes
6181 non-portable to other @command{tar} implementations. In fact,
6182 anything can happen. The most forgiving @command{tar}s will merely
6183 unpack the file using a wrong name, and maybe create another file
6184 named something like @file{@@LongName}, with the true file name in it.
6185 @command{tar}s not protecting themselves may segment violate!
6187 Compatibility concerns make all this thing more difficult, as we will
6188 have to support @emph{all} these things together, for a while.
6189 @acronym{GNU} @command{tar} should be able to produce and read true
6190 @sc{posix} format files, while being able to detect old @acronym{GNU}
6191 @command{tar} formats, besides old V7 format, and process them
6192 conveniently. It would take years before this whole area
6195 There are plans to raise this 100 limit to 256, and yet produce
6196 @sc{posix} conforming archives. Past 256, I do not know yet if
6197 @acronym{GNU} @command{tar} will go non-@sc{posix} again, or merely
6198 refuse to archive the file.
6200 There are plans so @acronym{GNU} @command{tar} support more fully the
6201 latest @sc{posix} format, while being able to read old V7 format,
6202 @acronym{GNU} (semi-@sc{posix} plus extension), as well as full
6203 @sc{posix}. One may ask if there is part of the @sc{posix} format
6204 that we still cannot support. This simple question has a complex
6205 answer. Maybe that, on intimate look, some strong limitations will
6206 pop up, but until now, nothing sounds too difficult (but see below).
6207 I only have these few pages of @sc{posix} telling about ``Extended tar
6208 Format'' (P1003.1-1990 -- section 10.1.1), and there are references to
6209 other parts of the standard I do not have, which should normally
6210 enforce limitations on stored file names (I suspect things like fixing
6211 what @kbd{/} and @kbd{@key{NUL}} means). There are also some points
6212 which the standard does not make clear, Existing practice will then
6213 drive what I should do.
6215 @sc{posix} mandates that, when a file name cannot fit within 100 to
6216 256 characters (the variance comes from the fact a @kbd{/} is ideally
6217 needed as the 156'th character), or a link name cannot fit within 100
6218 characters, a warning should be issued and the file @emph{not} be
6219 stored. Unless some @value{op-posix} option is given (or
6220 @env{POSIXLY_CORRECT} is set), I suspect that @acronym{GNU}
6221 @command{tar} should disobey this specification, and automatically
6222 switch to using @acronym{GNU} extensions to overcome file name or link
6223 name length limitations.
6225 There is a problem, however, which I did not intimately studied yet.
6226 Given a truly @sc{posix} archive with names having more than 100
6227 characters, I guess that @acronym{GNU} @command{tar} up to 1.11.8 will
6228 process it as if it were an old V7 archive, and be fooled by some
6229 fields which are coded differently. So, the question is to decide if
6230 the next generation of @acronym{GNU} @command{tar} should produce
6231 @sc{posix} format by default, whenever possible, producing archives
6232 older versions of @acronym{GNU} @command{tar} might not be able to
6233 read correctly. I fear that we will have to suffer such a choice one
6234 of these days, if we want @acronym{GNU} @command{tar} to go closer to
6235 @sc{posix}. We can rush it. Another possibility is to produce the
6236 current @acronym{GNU} @command{tar} format by default for a few years,
6237 but have @acronym{GNU} @command{tar} versions from some 1.@var{POSIX}
6238 and up able to recognize all three formats, and let older
6239 @acronym{GNU} @command{tar} fade out slowly. Then, we could switch to
6240 producing @sc{posix} format by default, with not much harm to those
6241 still having (very old at that time) @acronym{GNU} @command{tar}
6242 versions prior to 1.@var{POSIX}.
6244 @sc{posix} format cannot represent very long names, volume headers,
6245 splitting of files in multi-volumes, sparse files, and incremental
6246 dumps; these would be all disallowed if @value{op-posix} or
6247 @env{POSIXLY_CORRECT}. Otherwise, if @command{tar} is given long
6248 names, or @samp{-[VMSgG]}, then it should automatically go non-@sc{posix}.
6249 I think this is easily granted without much discussion.
6251 Another point is that only @code{mtime} is stored in @sc{posix}
6252 archives, while @acronym{GNU} @command{tar} currently also store
6253 @code{atime} and @code{ctime}. If we want @acronym{GNU} @command{tar}
6254 to go closer to @sc{posix}, my choice would be to drop @code{atime}
6255 and @code{ctime} support on average. On the other hand, I perceive
6256 that full dumps or incremental dumps need @code{atime} and
6257 @code{ctime} support, so for those special applications, @sc{posix}
6258 has to be avoided altogether.
6260 A few users requested that @value{op-sparse} be always active by
6261 default, I think that before replying to them, we have to decide if we
6262 want @acronym{GNU} @command{tar} to go closer to @sc{posix} on
6263 average, while producing files. My choice would be to go closer to
6264 @sc{posix} in the long run. Besides possible double reading, I do not
6265 see any point of not trying to save files as sparse when creating
6266 archives which are neither @sc{posix} nor old-V7, so the actual
6267 @value{op-sparse} would become selected by default when producing such
6268 archives, whatever the reason is. So, @value{op-sparse} alone might
6269 be redefined to force @acronym{GNU}-format archives, and recover its
6270 previous meaning from this fact.
6272 @acronym{GNU}-format as it exists now can easily fool other @sc{posix}
6273 @command{tar}, as it uses fields which @sc{posix} considers to be part
6274 of the file name prefix. I wonder if it would not be a good idea, in
6275 the long run, to try changing @acronym{GNU}-format so any added field
6276 (like @code{ctime}, @code{atime}, file offset in subsequent volumes,
6277 or sparse file descriptions) be wholly and always pushed into an
6278 extension block, instead of using space in the @sc{posix} header
6279 block. I could manage to do that portably between future
6280 @acronym{GNU} @command{tar}s. So other @sc{posix} @command{tar}s
6281 might be at least able to provide kind of correct listings for the
6282 archives produced by @acronym{GNU} @command{tar}, if not able to
6283 process them otherwise.
6285 Using these projected extensions might induce older @command{tar}s to
6286 fail. We would use the same approach as for @sc{posix}. I'll put out
6287 a @command{tar} capable of reading @sc{posix}ier, yet extended
6288 archives, but will not produce this format by default, in
6289 @acronym{GNU} mode. In a few years, when newer @acronym{GNU}
6290 @command{tar}s will have flooded out @command{tar} 1.11.X and
6291 previous, we could switch to producing @sc{posix}ier extended
6292 archives, with no real harm to users, as almost all existing
6293 @acronym{GNU} @command{tar}s will be ready to read @sc{posix}ier
6294 format. In fact, I'll do both changes at the same time, in a few
6295 years, and just prepare @command{tar} for both changes, without
6296 effecting them, from 1.@var{POSIX}. (Both changes: 1---using
6297 @sc{posix} convention for getting over 100 characters; 2---avoiding
6298 mangling @sc{posix} headers for @acronym{GNU} extensions, using only
6299 @sc{posix} mandated extension techniques).
6301 So, a future @command{tar} will have a @value{op-posix} flag forcing
6302 the usage of truly @sc{posix} headers, and so, producing archives
6303 previous @acronym{GNU} @command{tar} will not be able to read. So,
6304 @emph{once} pretest will announce that feature, it would be
6305 particularly useful that users test how exchangeable will be archives
6306 between @acronym{GNU} @command{tar} with @value{op-posix} and other
6307 @sc{posix} @command{tar}.
6309 In a few years, when @acronym{GNU} @command{tar} will produce
6310 @sc{posix} headers by default, @value{op-posix} will have a strong
6311 meaning and will disallow @acronym{GNU} extensions. But in the
6312 meantime, for a long while, @value{op-posix} in @acronym{GNU} tar will
6313 not disallow @acronym{GNU} extensions like @value{op-label},
6314 @value{op-multi-volume}, @value{op-sparse}, or very long file or link
6315 names. However, @value{op-posix} with @acronym{GNU} extensions will
6316 use @sc{posix} headers with reserved-for-users extensions to headers,
6317 and I will be curious to know how well or bad @sc{posix}
6318 @command{tar}s will react to these.
6320 @acronym{GNU} @command{tar} prior to 1.@var{POSIX}, and after
6321 1.@var{POSIX} without @value{op-posix}, generates and checks
6322 @samp{ustar@w{ }@w{ }}, with two suffixed spaces. This is sufficient
6323 for older @acronym{GNU} @command{tar} not to recognize @sc{posix}
6324 archives, and consequently, wrongly decide those archives are in old
6325 V7 format. It is a useful bug for me, because @acronym{GNU}
6326 @command{tar} has other @sc{posix} incompatibilities, and I need to
6327 segregate @acronym{GNU} @command{tar} semi-@sc{posix} archives from
6328 truly @sc{posix} archives, for @acronym{GNU} @command{tar} should be
6329 somewhat compatible with itself, while migrating closer to latest
6330 @sc{posix} standards. So, I'll be very careful about how and when I
6331 will do the correction.
6334 @subsection Checksumming Problems
6336 SunOS and HP-UX @command{tar} fail to accept archives created using
6337 @acronym{GNU} @command{tar} and containing non-ASCII file names, that
6338 is, file names having characters with the eight bit set, because they
6339 use signed checksums, while @acronym{GNU} @command{tar} uses unsigned
6340 checksums while creating archives, as per @sc{posix} standards. On
6341 reading, @acronym{GNU} @command{tar} computes both checksums and
6342 accept any. It is somewhat worrying that a lot of people may go
6343 around doing backup of their files using faulty (or at least
6344 non-standard) software, not learning about it until it's time to
6345 restore their missing files with an incompatible file extractor, or
6348 @acronym{GNU} @command{tar} compute checksums both ways, and accept
6349 any on read, so @acronym{GNU} tar can read Sun tapes even with their
6350 wrong checksums. @acronym{GNU} @command{tar} produces the standard
6351 checksum, however, raising incompatibilities with Sun. That is to
6352 say, @acronym{GNU} @command{tar} has not been modified to
6353 @emph{produce} incorrect archives to be read by buggy @command{tar}'s.
6354 I've been told that more recent Sun @command{tar} now read standard
6355 archives, so maybe Sun did a similar patch, after all?
6357 The story seems to be that when Sun first imported @command{tar}
6358 sources on their system, they recompiled it without realizing that
6359 the checksums were computed differently, because of a change in
6360 the default signing of @code{char}'s in their compiler. So they
6361 started computing checksums wrongly. When they later realized their
6362 mistake, they merely decided to stay compatible with it, and with
6363 themselves afterwards. Presumably, but I do not really know, HP-UX
6364 has chosen that their @command{tar} archives to be compatible with Sun's.
6365 The current standards do not favor Sun @command{tar} format. In any
6366 case, it now falls on the shoulders of SunOS and HP-UX users to get
6367 a @command{tar} able to read the good archives they receive.
6369 @node Large or Negative Values
6370 @subsection Large or Negative Values
6371 @cindex large values
6372 @cindex future time stamps
6373 @cindex negative time stamps
6375 @sc{posix} @command{tar} format uses fixed-sized unsigned octal strings
6376 to represent numeric values. User and group IDs and device major and
6377 minor numbers have unsigned 21-bit representations, and file sizes and
6378 times have unsigned 33-bit representations. @acronym{GNU} @command{tar}
6379 generates @sc{posix} representations when possible, but for values
6380 outside the @sc{posix} range it generates two's-complement base-256
6381 strings: uids, gids, and device numbers have signed 57-bit
6382 representations, and file sizes and times have signed 89-bit
6383 representations. These representations are an extension to @sc{posix}
6384 @command{tar} format, so they are not universally portable.
6386 The most common portability problems with out-of-range numeric values
6387 are large files and future or negative time stamps.
6389 Portable archives should avoid members of 8 GB or larger, as @sc{posix}
6390 @command{tar} format cannot represent them.
6392 Portable archives should avoid time stamps from the future. @sc{posix}
6393 @command{tar} format can represent time stamps in the range 1970-01-01
6394 00:00:00 through 2242-03-16 12:56:31 @sc{utc}. However, many current
6395 hosts use a signed 32-bit @code{time_t}, or internal time stamp format,
6396 and cannot represent time stamps after 2038-01-19 03:14:07 @sc{utc}; so
6397 portable archives must avoid these time stamps for many years to come.
6399 Portable archives should also avoid time stamps before 1970. These time
6400 stamps are a common @sc{posix} extension but their @code{time_t}
6401 representations are negative. Many traditional @command{tar}
6402 implementations generate a two's complement representation for negative
6403 time stamps that assumes a signed 32-bit @code{time_t}; hence they
6404 generate archives that are not portable to hosts with differing
6405 @code{time_t} representations. @acronym{GNU} @command{tar} recognizes this
6406 situation when it is run on host with a signed 32-bit @code{time_t}, but
6407 it issues a warning, as these time stamps are nonstandard and unportable.
6410 @section Using Less Space through Compression
6413 * gzip:: Creating and Reading Compressed Archives
6414 * sparse:: Archiving Sparse Files
6418 @subsection Creating and Reading Compressed Archives
6419 @cindex Compressed archives
6420 @cindex Storing archives in compressed format
6427 Filter the archive through @command{gzip}.
6430 @FIXME{ach; these two bits orig from "compare" (?). where to put?} Some
6431 format parameters must be taken into consideration when modifying an
6432 archive.@FIXME{???} Compressed archives cannot be modified.
6434 You can use @samp{--gzip} and @samp{--gunzip} on physical devices
6435 (tape drives, etc.) and remote files as well as on normal files; data
6436 to or from such devices or remote files is reblocked by another copy
6437 of the @command{tar} program to enforce the specified (or default) record
6438 size. The default compression parameters are used; if you need to
6439 override them, avoid the @value{op-gzip} option and run @command{gzip}
6440 explicitly. (Or set the @env{GZIP} environment variable.)
6442 The @value{op-gzip} option does not work with the @value{op-multi-volume}
6443 option, or with the @value{op-update}, @value{op-append},
6444 @value{op-concatenate}, or @value{op-delete} operations.
6446 It is not exact to say that @acronym{GNU} @command{tar} is to work in concert
6447 with @command{gzip} in a way similar to @command{zip}, say. Surely, it is
6448 possible that @command{tar} and @command{gzip} be done with a single call,
6452 $ @kbd{tar cfz archive.tar.gz subdir}
6456 to save all of @samp{subdir} into a @code{gzip}'ed archive. Later you
6460 $ @kbd{tar xfz archive.tar.gz}
6464 to explode and unpack.
6466 The difference is that the whole archive is compressed. With
6467 @command{zip}, archive members are archived individually. @command{tar}'s
6468 method yields better compression. On the other hand, one can view the
6469 contents of a @command{zip} archive without having to decompress it. As
6470 for the @command{tar} and @command{gzip} tandem, you need to decompress the
6471 archive to see its contents. However, this may be done without needing
6472 disk space, by using pipes internally:
6475 $ @kbd{tar tfz archive.tar.gz}
6478 @cindex corrupted archives
6479 About corrupted compressed archives: @command{gzip}'ed files have no
6480 redundancy, for maximum compression. The adaptive nature of the
6481 compression scheme means that the compression tables are implicitly
6482 spread all over the archive. If you lose a few blocks, the dynamic
6483 construction of the compression tables becomes unsynchronized, and there
6484 is little chance that you could recover later in the archive.
6486 There are pending suggestions for having a per-volume or per-file
6487 compression in @acronym{GNU} @command{tar}. This would allow for viewing the
6488 contents without decompression, and for resynchronizing decompression at
6489 every volume or file, in case of corrupted archives. Doing so, we might
6490 lose some compressibility. But this would have make recovering easier.
6491 So, there are pros and cons. We'll see!
6496 Filter the archive through @code{bzip2}. Otherwise like @value{op-gzip}.
6501 Filter the archive through @command{compress}. Otherwise like
6504 @item --use-compress-program=@var{prog}
6505 Filter through @var{prog} (must accept @samp{-d}).
6508 @value{op-compress} stores an archive in compressed format. This
6509 option is useful in saving time over networks and space in pipes, and
6510 when storage space is at a premium. @value{op-compress} causes
6511 @command{tar} to compress when writing the archive, or to uncompress when
6512 reading the archive.
6514 To perform compression and uncompression on the archive, @command{tar}
6515 runs the @command{compress} utility. @command{tar} uses the default
6516 compression parameters; if you need to override them, avoid the
6517 @value{op-compress} option and run the @command{compress} utility
6518 explicitly. It is useful to be able to call the @command{compress}
6519 utility from within @command{tar} because the @command{compress} utility by
6520 itself cannot access remote tape drives.
6522 The @value{op-compress} option will not work in conjunction with the
6523 @value{op-multi-volume} option or the @value{op-append}, @value{op-update}
6524 and @value{op-delete} operations. @xref{Operations}, for
6525 more information on these operations.
6527 If there is no compress utility available, @command{tar} will report an error.
6528 @strong{Please note} that the @command{compress} program may be covered by
6529 a patent, and therefore we recommend you stop using it.
6531 @value{op-bzip2} acts like @value{op-compress}, except that it uses
6532 the @code{bzip2} utility.
6539 When this option is specified, @command{tar} will compress (when
6540 writing an archive), or uncompress (when reading an archive). Used in
6541 conjunction with the @value{op-create}, @value{op-extract},
6542 @value{op-list} and @value{op-compare} operations.
6545 You can have archives be compressed by using the @value{op-gzip} option.
6546 This will arrange for @command{tar} to use the @command{gzip} program to be
6547 used to compress or uncompress the archive wren writing or reading it.
6549 To use the older, obsolete, @command{compress} program, use the
6550 @value{op-compress} option. The @acronym{GNU} Project recommends you not use
6551 @command{compress}, because there is a patent covering the algorithm it
6552 uses. You could be sued for patent infringement merely by running
6555 I have one question, or maybe it's a suggestion if there isn't a way
6556 to do it now. I would like to use @value{op-gzip}, but I'd also like
6557 the output to be fed through a program like @acronym{GNU}
6558 @command{ecc} (actually, right now that's @samp{exactly} what I'd like
6559 to use :-)), basically adding ECC protection on top of compression.
6560 It seems as if this should be quite easy to do, but I can't work out
6561 exactly how to go about it. Of course, I can pipe the standard output
6562 of @command{tar} through @command{ecc}, but then I lose (though I
6563 haven't started using it yet, I confess) the ability to have
6564 @command{tar} use @command{rmt} for it's I/O (I think).
6566 I think the most straightforward thing would be to let me specify a
6567 general set of filters outboard of compression (preferably ordered,
6568 so the order can be automatically reversed on input operations, and
6569 with the options they require specifiable), but beggars shouldn't be
6570 choosers and anything you decide on would be fine with me.
6572 By the way, I like @command{ecc} but if (as the comments say) it can't
6573 deal with loss of block sync, I'm tempted to throw some time at adding
6574 that capability. Supposing I were to actually do such a thing and
6575 get it (apparently) working, do you accept contributed changes to
6576 utilities like that? (Leigh Clayton @file{loc@@soliton.com}, May 1995).
6578 Isn't that exactly the role of the @value{op-use-compress-prog} option?
6579 I never tried it myself, but I suspect you may want to write a
6580 @var{prog} script or program able to filter stdin to stdout to
6581 way you want. It should recognize the @samp{-d} option, for when
6582 extraction is needed rather than creation.
6584 It has been reported that if one writes compressed data (through the
6585 @value{op-gzip} or @value{op-compress} options) to a DLT and tries to use
6586 the DLT compression mode, the data will actually get bigger and one will
6587 end up with less space on the tape.
6590 @subsection Archiving Sparse Files
6591 @cindex Sparse Files
6597 Handle sparse files efficiently.
6600 This option causes all files to be put in the archive to be tested for
6601 sparseness, and handled specially if they are. The @value{op-sparse}
6602 option is useful when many @code{dbm} files, for example, are being
6603 backed up. Using this option dramatically decreases the amount of
6604 space needed to store such a file.
6606 In later versions, this option may be removed, and the testing and
6607 treatment of sparse files may be done automatically with any special
6608 @acronym{GNU} options. For now, it is an option needing to be specified on
6609 the command line with the creation or updating of an archive.
6611 Files in the filesystem occasionally have ``holes.'' A hole in a file
6612 is a section of the file's contents which was never written. The
6613 contents of a hole read as all zeros. On many operating systems,
6614 actual disk storage is not allocated for holes, but they are counted
6615 in the length of the file. If you archive such a file, @command{tar}
6616 could create an archive longer than the original. To have @command{tar}
6617 attempt to recognize the holes in a file, use @value{op-sparse}. When
6618 you use the @value{op-sparse} option, then, for any file using less
6619 disk space than would be expected from its length, @command{tar} searches
6620 the file for consecutive stretches of zeros. It then records in the
6621 archive for the file where the consecutive stretches of zeros are, and
6622 only archives the ``real contents'' of the file. On extraction (using
6623 @value{op-sparse} is not needed on extraction) any such files have
6624 hols created wherever the continuous stretches of zeros were found.
6625 Thus, if you use @value{op-sparse}, @command{tar} archives won't take
6626 more space than the original.
6628 A file is sparse if it contains blocks of zeros whose existence is
6629 recorded, but that have no space allocated on disk. When you specify
6630 the @value{op-sparse} option in conjunction with the @value{op-create}
6631 operation, @command{tar} tests all files for sparseness while archiving.
6632 If @command{tar} finds a file to be sparse, it uses a sparse representation of
6633 the file in the archive. @value{xref-create}, for more information
6634 about creating archives.
6636 @value{op-sparse} is useful when archiving files, such as dbm files,
6637 likely to contain many nulls. This option dramatically
6638 decreases the amount of space needed to store such an archive.
6641 @strong{Please Note:} Always use @value{op-sparse} when performing file
6642 system backups, to avoid archiving the expanded forms of files stored
6643 sparsely in the system.
6645 Even if your system has no sparse files currently, some may be
6646 created in the future. If you use @value{op-sparse} while making file
6647 system backups as a matter of course, you can be assured the archive
6648 will never take more space on the media than the files take on disk
6649 (otherwise, archiving a disk filled with sparse files might take
6650 hundreds of tapes). @FIXME-xref{incremental when node name is set.}
6653 @command{tar} ignores the @value{op-sparse} option when reading an archive.
6658 Files stored sparsely in the file system are represented sparsely in
6659 the archive. Use in conjunction with write operations.
6662 However, users should be well aware that at archive creation time,
6663 @acronym{GNU} @command{tar} still has to read whole disk file to
6664 locate the @dfn{holes}, and so, even if sparse files use little space
6665 on disk and in the archive, they may sometimes require inordinate
6666 amount of time for reading and examining all-zero blocks of a file.
6667 Although it works, it's painfully slow for a large (sparse) file, even
6668 though the resulting tar archive may be small. (One user reports that
6669 dumping a @file{core} file of over 400 megabytes, but with only about
6670 3 megabytes of actual data, took about 9 minutes on a Sun Sparcstation
6671 ELC, with full CPU utilization.)
6673 This reading is required in all cases and is not related to the fact
6674 the @value{op-sparse} option is used or not, so by merely @emph{not}
6675 using the option, you are not saving time@footnote{Well! We should say
6676 the whole truth, here. When @value{op-sparse} is selected while creating
6677 an archive, the current @command{tar} algorithm requires sparse files to be
6678 read twice, not once. We hope to develop a new archive format for saving
6679 sparse files in which one pass will be sufficient.}.
6681 Programs like @command{dump} do not have to read the entire file; by
6682 examining the file system directly, they can determine in advance
6683 exactly where the holes are and thus avoid reading through them. The
6684 only data it need read are the actual allocated data blocks.
6685 @acronym{GNU} @command{tar} uses a more portable and straightforward
6686 archiving approach, it would be fairly difficult that it does
6687 otherwise. Elizabeth Zwicky writes to @file{comp.unix.internals}, on
6691 What I did say is that you cannot tell the difference between a hole and an
6692 equivalent number of nulls without reading raw blocks. @code{st_blocks} at
6693 best tells you how many holes there are; it doesn't tell you @emph{where}.
6694 Just as programs may, conceivably, care what @code{st_blocks} is (care
6695 to name one that does?), they may also care where the holes are (I have
6696 no examples of this one either, but it's equally imaginable).
6698 I conclude from this that good archivers are not portable. One can
6699 arguably conclude that if you want a portable program, you can in good
6700 conscience restore files with as many holes as possible, since you can't
6705 @section Handling File Attributes
6708 When @command{tar} reads files, this causes them to have the access
6709 times updated. To have @command{tar} attempt to set the access times
6710 back to what they were before they were read, use the
6711 @value{op-atime-preserve} option.
6713 Handling of file attributes
6716 @item --atime-preserve
6717 Preserve access times on files that are read.
6718 This doesn't work for files that
6719 you don't own, unless you're root, and it doesn't interact with
6720 incremental dumps nicely (@pxref{Backups}), and it can set access or
6721 modification times incorrectly if other programs access the file while
6722 @command{tar} is running; but it is good enough for some purposes.
6726 Do not extract file modified time.
6728 When this option is used, @command{tar} leaves the modification times
6729 of the files it extracts as the time when the files were extracted,
6730 instead of setting it to the time recorded in the archive.
6732 This option is meaningless with @value{op-list}.
6735 Create extracted files with the same ownership they have in the
6738 This is the default behavior for the superuser,
6739 so this option is meaningful only for non-root users, when @command{tar}
6740 is executed on those systems able to give files away. This is
6741 considered as a security flaw by many people, at least because it
6742 makes quite difficult to correctly account users for the disk space
6743 they occupy. Also, the @code{suid} or @code{sgid} attributes of
6744 files are easily and silently lost when files are given away.
6746 When writing an archive, @command{tar} writes the user id and user name
6747 separately. If it can't find a user name (because the user id is not
6748 in @file{/etc/passwd}), then it does not write one. When restoring,
6749 and doing a @code{chmod} like when you use @value{op-same-permissions},
6750 @FIXME{same-owner?}it tries to look the name (if one was written)
6751 up in @file{/etc/passwd}. If it fails, then it uses the user id
6752 stored in the archive instead.
6754 @item --no-same-owner
6755 Do not attempt to restore ownership when extracting. This is the
6756 default behavior for ordinary users, so this option has an effect
6757 only for the superuser.
6759 @item --numeric-owner
6760 The @value{op-numeric-owner} option allows (ANSI) archives to be written
6761 without user/group name information or such information to be ignored
6762 when extracting. It effectively disables the generation and/or use
6763 of user/group name information. This option forces extraction using
6764 the numeric ids from the archive, ignoring the names.
6766 This is useful in certain circumstances, when restoring a backup from
6767 an emergency floppy with different passwd/group files for example.
6768 It is otherwise impossible to extract files with the right ownerships
6769 if the password file in use during the extraction does not match the
6770 one belonging to the filesystem(s) being extracted. This occurs,
6771 for example, if you are restoring your files after a major crash and
6772 had booted from an emergency floppy with no password file or put your
6773 disk into another machine to do the restore.
6775 The numeric ids are @emph{always} saved into @command{tar} archives.
6776 The identifying names are added at create time when provided by the
6777 system, unless @value{op-old-archive} is used. Numeric ids could be
6778 used when moving archives between a collection of machines using
6779 a centralized management for attribution of numeric ids to users
6780 and groups. This is often made through using the NIS capabilities.
6782 When making a @command{tar} file for distribution to other sites, it
6783 is sometimes cleaner to use a single owner for all files in the
6784 distribution, and nicer to specify the write permission bits of the
6785 files as stored in the archive independently of their actual value on
6786 the file system. The way to prepare a clean distribution is usually
6787 to have some Makefile rule creating a directory, copying all needed
6788 files in that directory, then setting ownership and permissions as
6789 wanted (there are a lot of possible schemes), and only then making a
6790 @command{tar} archive out of this directory, before cleaning
6791 everything out. Of course, we could add a lot of options to
6792 @acronym{GNU} @command{tar} for fine tuning permissions and ownership.
6793 This is not the good way, I think. @acronym{GNU} @command{tar} is
6794 already crowded with options and moreover, the approach just explained
6795 gives you a great deal of control already.
6798 @itemx --same-permissions
6799 @itemx --preserve-permissions
6800 Extract all protection information.
6802 This option causes @command{tar} to set the modes (access permissions) of
6803 extracted files exactly as recorded in the archive. If this option
6804 is not used, the current @code{umask} setting limits the permissions
6807 This option is meaningless with @value{op-list}.
6810 Same as both @value{op-same-permissions} and @value{op-same-order}.
6812 The @value{op-preserve} option has no equivalent short option name.
6813 It is equivalent to @value{op-same-permissions} plus @value{op-same-order}.
6815 @FIXME{I do not see the purpose of such an option. (Neither I. FP.)}
6820 @section The Standard Format
6823 While an archive may contain many files, the archive itself is a
6824 single ordinary file. Like any other file, an archive file can be
6825 written to a storage device such as a tape or disk, sent through a
6826 pipe or over a network, saved on the active file system, or even
6827 stored in another archive. An archive file is not easy to read or
6828 manipulate without using the @command{tar} utility or Tar mode in
6829 @acronym{GNU} Emacs.
6831 Physically, an archive consists of a series of file entries terminated
6832 by an end-of-archive entry, which consists of 512 zero bytes. A file
6833 entry usually describes one of the files in the archive (an
6834 @dfn{archive member}), and consists of a file header and the contents
6835 of the file. File headers contain file names and statistics, checksum
6836 information which @command{tar} uses to detect file corruption, and
6837 information about file types.
6839 Archives are permitted to have more than one member with the same
6840 member name. One way this situation can occur is if more than one
6841 version of a file has been stored in the archive. For information
6842 about adding new versions of a file to an archive, see @ref{update}.
6843 @FIXME-xref{To learn more about having more than one archive member with the
6844 same name, see -backup node, when it's written.}
6846 In addition to entries describing archive members, an archive may
6847 contain entries which @command{tar} itself uses to store information.
6848 @value{xref-label}, for an example of such an archive entry.
6850 A @command{tar} archive file contains a series of blocks. Each block
6851 contains @code{BLOCKSIZE} bytes. Although this format may be thought
6852 of as being on magnetic tape, other media are often used.
6854 Each file archived is represented by a header block which describes
6855 the file, followed by zero or more blocks which give the contents
6856 of the file. At the end of the archive file there may be a block
6857 filled with binary zeros as an end-of-file marker. A reasonable system
6858 should write a block of zeros at the end, but must not assume that
6859 such a block exists when reading an archive.
6861 The blocks may be @dfn{blocked} for physical I/O operations.
6862 Each record of @var{n} blocks (where @var{n} is set by the
6863 @value{op-blocking-factor} option to @command{tar}) is written with a single
6864 @w{@samp{write ()}} operation. On magnetic tapes, the result of
6865 such a write is a single record. When writing an archive,
6866 the last record of blocks should be written at the full size, with
6867 blocks after the zero block containing all zeros. When reading
6868 an archive, a reasonable system should properly handle an archive
6869 whose last record is shorter than the rest, or which contains garbage
6870 records after a zero block.
6872 The header block is defined in C as follows. In the @acronym{GNU}
6873 @command{tar} distribution, this is part of file @file{src/tar.h}:
6876 @include header.texi
6879 All characters in header blocks are represented by using 8-bit
6880 characters in the local variant of ASCII. Each field within the
6881 structure is contiguous; that is, there is no padding used within
6882 the structure. Each character on the archive medium is stored
6885 Bytes representing the contents of files (after the header block
6886 of each file) are not translated in any way and are not constrained
6887 to represent characters in any character set. The @command{tar} format
6888 does not distinguish text files from binary files, and no translation
6889 of file contents is performed.
6891 The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
6892 @code{gname} are null-terminated character strings. All other fields
6893 are zero-filled octal numbers in ASCII. Each numeric field of width
6894 @var{w} contains @var{w} minus 2 digits, a space, and a null, except
6895 @code{size}, and @code{mtime}, which do not contain the trailing null.
6897 The @code{name} field is the file name of the file, with directory names
6898 (if any) preceding the file name, separated by slashes.
6900 @FIXME{how big a name before field overflows?}
6902 The @code{mode} field provides nine bits specifying file permissions
6903 and three bits to specify the Set UID, Set GID, and Save Text
6904 (@dfn{sticky}) modes. Values for these bits are defined above.
6905 When special permissions are required to create a file with a given
6906 mode, and the user restoring files from the archive does not hold such
6907 permissions, the mode bit(s) specifying those special permissions
6908 are ignored. Modes which are not supported by the operating system
6909 restoring files from the archive will be ignored. Unsupported modes
6910 should be faked up when creating or updating an archive; e.g.@: the
6911 group permission could be copied from the @emph{other} permission.
6913 The @code{uid} and @code{gid} fields are the numeric user and group
6914 ID of the file owners, respectively. If the operating system does
6915 not support numeric user or group IDs, these fields should be ignored.
6917 The @code{size} field is the size of the file in bytes; linked files
6918 are archived with this field specified as zero. @FIXME-xref{Modifiers, in
6919 particular the @value{op-incremental} option.}
6921 The @code{mtime} field is the modification time of the file at the time
6922 it was archived. It is the ASCII representation of the octal value of
6923 the last time the file was modified, represented as an integer number of
6924 seconds since January 1, 1970, 00:00 Coordinated Universal Time.
6926 The @code{chksum} field is the ASCII representation of the octal value
6927 of the simple sum of all bytes in the header block. Each 8-bit
6928 byte in the header is added to an unsigned integer, initialized to
6929 zero, the precision of which shall be no less than seventeen bits.
6930 When calculating the checksum, the @code{chksum} field is treated as
6931 if it were all blanks.
6933 The @code{typeflag} field specifies the type of file archived. If a
6934 particular implementation does not recognize or permit the specified
6935 type, the file will be extracted as if it were a regular file. As this
6936 action occurs, @command{tar} issues a warning to the standard error.
6938 The @code{atime} and @code{ctime} fields are used in making incremental
6939 backups; they store, respectively, the particular file's access time
6940 and last inode-change time.
6942 The @code{offset} is used by the @value{op-multi-volume} option, when
6943 making a multi-volume archive. The offset is number of bytes into
6944 the file that we need to restart at to continue the file on the next
6945 tape, i.e., where we store the location that a continued file is
6948 The following fields were added to deal with sparse files. A file
6949 is @dfn{sparse} if it takes in unallocated blocks which end up being
6950 represented as zeros, i.e., no useful data. A test to see if a file
6951 is sparse is to look at the number blocks allocated for it versus the
6952 number of characters in the file; if there are fewer blocks allocated
6953 for the file than would normally be allocated for a file of that
6954 size, then the file is sparse. This is the method @command{tar} uses to
6955 detect a sparse file, and once such a file is detected, it is treated
6956 differently from non-sparse files.
6958 Sparse files are often @code{dbm} files, or other database-type files
6959 which have data at some points and emptiness in the greater part of
6960 the file. Such files can appear to be very large when an @samp{ls
6961 -l} is done on them, when in truth, there may be a very small amount
6962 of important data contained in the file. It is thus undesirable
6963 to have @command{tar} think that it must back up this entire file, as
6964 great quantities of room are wasted on empty blocks, which can lead
6965 to running out of room on a tape far earlier than is necessary.
6966 Thus, sparse files are dealt with so that these empty blocks are
6967 not written to the tape. Instead, what is written to the tape is a
6968 description, of sorts, of the sparse file: where the holes are, how
6969 big the holes are, and how much data is found at the end of the hole.
6970 This way, the file takes up potentially far less room on the tape,
6971 and when the file is extracted later on, it will look exactly the way
6972 it looked beforehand. The following is a description of the fields
6973 used to handle a sparse file:
6975 The @code{sp} is an array of @code{struct sparse}. Each @code{struct
6976 sparse} contains two 12-character strings which represent an offset
6977 into the file and a number of bytes to be written at that offset.
6978 The offset is absolute, and not relative to the offset in preceding
6981 The header can hold four of these @code{struct sparse} at the moment;
6982 if more are needed, they are not stored in the header.
6984 The @code{isextended} flag is set when an @code{extended_header}
6985 is needed to deal with a file. Note that this means that this flag
6986 can only be set when dealing with a sparse file, and it is only set
6987 in the event that the description of the file will not fit in the
6988 allotted room for sparse structures in the header. In other words,
6989 an extended_header is needed.
6991 The @code{extended_header} structure is used for sparse files which
6992 need more sparse structures than can fit in the header. The header can
6993 fit 4 such structures; if more are needed, the flag @code{isextended}
6994 gets set and the next block is an @code{extended_header}.
6996 Each @code{extended_header} structure contains an array of 21
6997 sparse structures, along with a similar @code{isextended} flag
6998 that the header had. There can be an indeterminate number of such
6999 @code{extended_header}s to describe a sparse file.
7003 @item @code{REGTYPE}
7004 @itemx @code{AREGTYPE}
7005 These flags represent a regular file. In order to be compatible
7006 with older versions of @command{tar}, a @code{typeflag} value of
7007 @code{AREGTYPE} should be silently recognized as a regular file.
7008 New archives should be created using @code{REGTYPE}. Also, for
7009 backward compatibility, @command{tar} treats a regular file whose name
7010 ends with a slash as a directory.
7012 @item @code{LNKTYPE}
7013 This flag represents a file linked to another file, of any type,
7014 previously archived. Such files are identified in Unix by each
7015 file having the same device and inode number. The linked-to name is
7016 specified in the @code{linkname} field with a trailing null.
7018 @item @code{SYMTYPE}
7019 This represents a symbolic link to another file. The linked-to name
7020 is specified in the @code{linkname} field with a trailing null.
7022 @item @code{CHRTYPE}
7023 @itemx @code{BLKTYPE}
7024 These represent character special files and block special files
7025 respectively. In this case the @code{devmajor} and @code{devminor}
7026 fields will contain the major and minor device numbers respectively.
7027 Operating systems may map the device specifications to their own
7028 local specification, or may ignore the entry.
7030 @item @code{DIRTYPE}
7031 This flag specifies a directory or sub-directory. The directory
7032 name in the @code{name} field should end with a slash. On systems where
7033 disk allocation is performed on a directory basis, the @code{size} field
7034 will contain the maximum number of bytes (which may be rounded to
7035 the nearest disk block allocation unit) which the directory may
7036 hold. A @code{size} field of zero indicates no such limiting. Systems
7037 which do not support limiting in this manner should ignore the
7040 @item @code{FIFOTYPE}
7041 This specifies a FIFO special file. Note that the archiving of a
7042 FIFO file archives the existence of this file and not its contents.
7044 @item @code{CONTTYPE}
7045 This specifies a contiguous file, which is the same as a normal
7046 file except that, in operating systems which support it, all its
7047 space is allocated contiguously on the disk. Operating systems
7048 which do not allow contiguous allocation should silently treat this
7049 type as a normal file.
7051 @item @code{A} @dots{} @code{Z}
7052 These are reserved for custom implementations. Some of these are
7053 used in the @acronym{GNU} modified format, as described below.
7057 Other values are reserved for specification in future revisions of
7058 the P1003 standard, and should not be used by any @command{tar} program.
7060 The @code{magic} field indicates that this archive was output in
7061 the P1003 archive format. If this field contains @code{TMAGIC},
7062 the @code{uname} and @code{gname} fields will contain the ASCII
7063 representation of the owner and group of the file respectively.
7064 If found, the user and group IDs are used rather than the values in
7065 the @code{uid} and @code{gid} fields.
7067 For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, pages
7068 169-173 (section 10.1) for @cite{Archive/Interchange File Format}; and
7069 IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
7070 (section E.4.48) for @cite{pax - Portable archive interchange}.
7073 @section @acronym{GNU} Extensions to the Archive Format
7076 The @acronym{GNU} format uses additional file types to describe new types of
7077 files in an archive. These are listed below.
7080 @item GNUTYPE_DUMPDIR
7082 This represents a directory and a list of files created by the
7083 @value{op-incremental} option. The @code{size} field gives the total
7084 size of the associated list of files. Each file name is preceded by
7085 either a @samp{Y} (the file should be in this archive) or an @samp{N}.
7086 (The file is a directory, or is not stored in the archive.) Each file
7087 name is terminated by a null. There is an additional null after the
7090 @item GNUTYPE_MULTIVOL
7092 This represents a file continued from another volume of a multi-volume
7093 archive created with the @value{op-multi-volume} option. The original
7094 type of the file is not given here. The @code{size} field gives the
7095 maximum size of this piece of the file (assuming the volume does
7096 not end before the file is written out). The @code{offset} field
7097 gives the offset from the beginning of the file where this part of
7098 the file begins. Thus @code{size} plus @code{offset} should equal
7099 the original size of the file.
7101 @item GNUTYPE_SPARSE
7103 This flag indicates that we are dealing with a sparse file. Note
7104 that archiving a sparse file requires special operations to find
7105 holes in the file, which mark the positions of these holes, along
7106 with the number of bytes of data to be found after the hole.
7108 @item GNUTYPE_VOLHDR
7110 This file type is used to mark the volume header that was given with
7111 the @value{op-label} option when the archive was created. The @code{name}
7112 field contains the @code{name} given after the @value{op-label} option.
7113 The @code{size} field is zero. Only the first file in each volume
7114 of an archive should have this type.
7118 You may have trouble reading a @acronym{GNU} format archive on a
7119 non-@acronym{GNU} system if the options @value{op-incremental},
7120 @value{op-multi-volume}, @value{op-sparse}, or @value{op-label} were
7121 used when writing the archive. In general, if @command{tar} does not
7122 use the @acronym{GNU}-added fields of the header, other versions of
7123 @command{tar} should be able to read the archive. Otherwise, the
7124 @command{tar} program will give an error, the most likely one being a
7128 @section Comparison of @command{tar} and @command{cpio}
7131 @FIXME{Reorganize the following material}
7133 The @command{cpio} archive formats, like @command{tar}, do have maximum
7134 pathname lengths. The binary and old ASCII formats have a max path
7135 length of 256, and the new ASCII and CRC ASCII formats have a max
7136 path length of 1024. @acronym{GNU} @command{cpio} can read and write archives
7137 with arbitrary pathname lengths, but other @command{cpio} implementations
7138 may crash unexplainedly trying to read them.
7140 @command{tar} handles symbolic links in the form in which it comes in BSD;
7141 @command{cpio} doesn't handle symbolic links in the form in which it comes
7142 in System V prior to SVR4, and some vendors may have added symlinks
7143 to their system without enhancing @command{cpio} to know about them.
7144 Others may have enhanced it in a way other than the way I did it
7145 at Sun, and which was adopted by AT&T (and which is, I think, also
7146 present in the @command{cpio} that Berkeley picked up from AT&T and put
7147 into a later BSD release---I think I gave them my changes).
7149 (SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio}
7150 can handle @command{tar} format input, and write it on output, and it
7151 probably handles symbolic links. They may not have bothered doing
7152 anything to enhance @command{tar} as a result.)
7154 @command{cpio} handles special files; traditional @command{tar} doesn't.
7156 @command{tar} comes with V7, System III, System V, and BSD source;
7157 @command{cpio} comes only with System III, System V, and later BSD
7158 (4.3-tahoe and later).
7160 @command{tar}'s way of handling multiple hard links to a file can handle
7161 file systems that support 32-bit inumbers (e.g., the BSD file system);
7162 @command{cpio}s way requires you to play some games (in its "binary"
7163 format, i-numbers are only 16 bits, and in its "portable ASCII" format,
7164 they're 18 bits---it would have to play games with the "file system ID"
7165 field of the header to make sure that the file system ID/i-number pairs
7166 of different files were always different), and I don't know which
7167 @command{cpio}s, if any, play those games. Those that don't might get
7168 confused and think two files are the same file when they're not, and
7169 make hard links between them.
7171 @command{tar}s way of handling multiple hard links to a file places only
7172 one copy of the link on the tape, but the name attached to that copy
7173 is the @emph{only} one you can use to retrieve the file; @command{cpio}s
7174 way puts one copy for every link, but you can retrieve it using any
7178 What type of check sum (if any) is used, and how is this calculated.
7181 See the attached manual pages for @command{tar} and @command{cpio} format.
7182 @command{tar} uses a checksum which is the sum of all the bytes in the
7183 @command{tar} header for a file; @command{cpio} uses no checksum.
7186 If anyone knows why @command{cpio} was made when @command{tar} was present
7190 It wasn't. @command{cpio} first showed up in PWB/UNIX 1.0; no
7191 generally-available version of UNIX had @command{tar} at the time. I don't
7192 know whether any version that was generally available @emph{within AT&T}
7193 had @command{tar}, or, if so, whether the people within AT&T who did
7194 @command{cpio} knew about it.
7196 On restore, if there is a corruption on a tape @command{tar} will stop at
7197 that point, while @command{cpio} will skip over it and try to restore the
7200 The main difference is just in the command syntax and header format.
7202 @command{tar} is a little more tape-oriented in that everything is blocked
7203 to start on a record boundary.
7206 Is there any differences between the ability to recover crashed
7207 archives between the two of them. (Is there any chance of recovering
7208 crashed archives at all.)
7211 Theoretically it should be easier under @command{tar} since the blocking
7212 lets you find a header with some variation of @samp{dd skip=@var{nn}}.
7213 However, modern @command{cpio}'s and variations have an option to just
7214 search for the next file header after an error with a reasonable chance
7215 of resyncing. However, lots of tape driver software won't allow you to
7216 continue past a media error which should be the only reason for getting
7217 out of sync unless a file changed sizes while you were writing the
7221 If anyone knows why @command{cpio} was made when @command{tar} was present
7222 at the unix scene, please tell me about this too.
7225 Probably because it is more media efficient (by not blocking everything
7226 and using only the space needed for the headers where @command{tar}
7227 always uses 512 bytes per file header) and it knows how to archive
7230 You might want to look at the freely available alternatives. The
7231 major ones are @command{afio}, @acronym{GNU} @command{tar}, and
7232 @command{pax}, each of which have their own extensions with some
7233 backwards compatibility.
7235 Sparse files were @command{tar}red as sparse files (which you can
7236 easily test, because the resulting archive gets smaller, and
7237 @acronym{GNU} @command{cpio} can no longer read it).
7240 @chapter Tapes and Other Archive Media
7243 A few special cases about tape handling warrant more detailed
7244 description. These special cases are discussed below.
7246 Many complexities surround the use of @command{tar} on tape drives. Since
7247 the creation and manipulation of archives located on magnetic tape was
7248 the original purpose of @command{tar}, it contains many features making
7249 such manipulation easier.
7251 Archives are usually written on dismountable media---tape cartridges,
7252 mag tapes, or floppy disks.
7254 The amount of data a tape or disk holds depends not only on its size,
7255 but also on how it is formatted. A 2400 foot long reel of mag tape
7256 holds 40 megabytes of data when formatted at 1600 bits per inch. The
7257 physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
7259 Magnetic media are re-usable---once the archive on a tape is no longer
7260 needed, the archive can be erased and the tape or disk used over.
7261 Media quality does deteriorate with use, however. Most tapes or disks
7262 should be discarded when they begin to produce data errors. EXABYTE
7263 tape cartridges should be discarded when they generate an @dfn{error
7264 count} (number of non-usable bits) of more than 10k.
7266 Magnetic media are written and erased using magnetic fields, and
7267 should be protected from such fields to avoid damage to stored data.
7268 Sticking a floppy disk to a filing cabinet using a magnet is probably
7272 * Device:: Device selection and switching
7273 * Remote Tape Server::
7274 * Common Problems and Solutions::
7275 * Blocking:: Blocking
7276 * Many:: Many archives on one tape
7277 * Using Multiple Tapes:: Using Multiple Tapes
7278 * label:: Including a Label in the Archive
7280 * Write Protection::
7284 @section Device Selection and Switching
7288 @item -f [@var{hostname}:]@var{file}
7289 @itemx --file=[@var{hostname}:]@var{file}
7290 Use archive file or device @var{file} on @var{hostname}.
7293 This option is used to specify the file name of the archive @command{tar}
7296 If the file name is @samp{-}, @command{tar} reads the archive from standard
7297 input (when listing or extracting), or writes it to standard output
7298 (when creating). If the @samp{-} file name is given when updating an
7299 archive, @command{tar} will read the original archive from its standard
7300 input, and will write the entire new archive to its standard output.
7302 If the file name contains a @samp{:}, it is interpreted as
7303 @samp{hostname:file name}. If the @var{hostname} contains an @dfn{at}
7304 sign (@kbd{@@}), it is treated as @samp{user@@hostname:file name}. In
7305 either case, @command{tar} will invoke the command @command{rsh} (or
7306 @command{remsh}) to start up an @file{/etc/rmt} on the remote machine. If
7307 you give an alternate login name, it will be given to the @command{rsh}.
7308 Naturally, the remote machine must have an executable @file{/etc/rmt}.
7309 This program is free software from the University of California, and a
7310 copy of the source code can be found with the sources for @command{tar};
7311 it's compiled and installed by default.
7313 If this option is not given, but the environment variable @env{TAPE}
7314 is set, its value is used; otherwise, old versions of @command{tar}
7315 used a default archive name (which was picked when @command{tar} was
7316 compiled). The default is normally set up to be the @dfn{first} tape
7317 drive or other transportable I/O medium on the system.
7319 Starting with version 1.11.5, @acronym{GNU} @command{tar} uses
7320 standard input and standard output as the default device, and I will
7321 not try anymore supporting automatic device detection at installation
7322 time. This was failing really in too many cases, it was hopeless.
7323 This is now completely left to the installer to override standard
7324 input and standard output for default device, if this seems
7325 preferable. Further, I think @emph{most} actual usages of
7326 @command{tar} are done with pipes or disks, not really tapes,
7327 cartridges or diskettes.
7329 Some users think that using standard input and output is running
7330 after trouble. This could lead to a nasty surprise on your screen if
7331 you forget to specify an output file name---especially if you are going
7332 through a network or terminal server capable of buffering large amounts
7333 of output. We had so many bug reports in that area of configuring
7334 default tapes automatically, and so many contradicting requests, that
7335 we finally consider the problem to be portably intractable. We could
7336 of course use something like @samp{/dev/tape} as a default, but this
7337 is @emph{also} running after various kind of trouble, going from hung
7338 processes to accidental destruction of real tapes. After having seen
7339 all this mess, using standard input and output as a default really
7340 sounds like the only clean choice left, and a very useful one too.
7342 @acronym{GNU} @command{tar} reads and writes archive in records, I
7343 suspect this is the main reason why block devices are preferred over
7344 character devices. Most probably, block devices are more efficient
7345 too. The installer could also check for @samp{DEFTAPE} in
7346 @file{<sys/mtio.h>}.
7350 Archive file is local even if it contains a colon.
7352 @item --rsh-command=@var{command}
7353 Use remote @var{command} instead of @command{rsh}. This option exists
7354 so that people who use something other than the standard @command{rsh}
7355 (e.g., a Kerberized @command{rsh}) can access a remote device.
7357 When this command is not used, the shell command found when
7358 the @command{tar} program was installed is used instead. This is
7359 the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh},
7360 @file{/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}.
7361 The installer may have overridden this by defining the environment
7362 variable @env{RSH} @emph{at installation time}.
7365 Specify drive and density.
7368 @itemx --multi-volume
7369 Create/list/extract multi-volume archive.
7371 This option causes @command{tar} to write a @dfn{multi-volume} archive---one
7372 that may be larger than will fit on the medium used to hold it.
7373 @xref{Multi-Volume Archives}.
7376 @itemx --tape-length=@var{num}
7377 Change tape after writing @var{num} x 1024 bytes.
7379 This option might be useful when your tape drivers do not properly
7380 detect end of physical tapes. By being slightly conservative on the
7381 maximum tape length, you might avoid the problem entirely.
7384 @itemx --info-script=@var{file}
7385 @itemx --new-volume-script=@var{file}
7386 Execute @file{file} at end of each tape. If @file{file} exits with
7387 nonzero status, exit. This implies @value{op-multi-volume}.
7390 @node Remote Tape Server
7391 @section The Remote Tape Server
7393 @cindex remote tape drive
7395 In order to access the tape drive on a remote machine, @command{tar}
7396 uses the remote tape server written at the University of California at
7397 Berkeley. The remote tape server must be installed as @file{/etc/rmt}
7398 on any machine whose tape drive you want to use. @command{tar} calls
7399 @file{/etc/rmt} by running an @command{rsh} or @command{remsh} to the remote
7400 machine, optionally using a different login name if one is supplied.
7402 A copy of the source for the remote tape server is provided. It is
7403 Copyright @copyright{} 1983 by the Regents of the University of
7404 California, but can be freely distributed. Instructions for compiling
7405 and installing it are included in the @file{Makefile}.
7407 @cindex absolute file names
7408 Unless you use the @value{op-absolute-names} option, @acronym{GNU}
7409 @command{tar} will not allow you to create an archive that contains
7410 absolute file names (a file name beginning with @samp{/}.) If you try,
7411 @command{tar} will automatically remove the leading @samp{/} from the
7412 file names it stores in the archive. It will also type a warning
7413 message telling you what it is doing.
7415 When reading an archive that was created with a different
7416 @command{tar} program, @acronym{GNU} @command{tar} automatically
7417 extracts entries in the archive which have absolute file names as if
7418 the file names were not absolute. This is an important feature. A
7419 visitor here once gave a @command{tar} tape to an operator to restore;
7420 the operator used Sun @command{tar} instead of @acronym{GNU}
7421 @command{tar}, and the result was that it replaced large portions of
7422 our @file{/bin} and friends with versions from the tape; needless to
7423 say, we were unhappy about having to recover the file system from
7426 For example, if the archive contained a file @file{/usr/bin/computoy},
7427 @acronym{GNU} @command{tar} would extract the file to @file{usr/bin/computoy},
7428 relative to the current directory. If you want to extract the files in
7429 an archive to the same absolute names that they had when the archive
7430 was created, you should do a @samp{cd /} before extracting the files
7431 from the archive, or you should either use the @value{op-absolute-names}
7432 option, or use the command @samp{tar -C / @dots{}}.
7434 @cindex Ultrix 3.1 and write failure
7435 Some versions of Unix (Ultrix 3.1 is known to have this problem),
7436 can claim that a short write near the end of a tape succeeded,
7437 when it actually failed. This will result in the -M option not
7438 working correctly. The best workaround at the moment is to use a
7439 significantly larger blocking factor than the default 20.
7441 In order to update an archive, @command{tar} must be able to backspace the
7442 archive in order to reread or rewrite a record that was just read (or
7443 written). This is currently possible only on two kinds of files: normal
7444 disk files (or any other file that can be backspaced with @samp{lseek}),
7445 and industry-standard 9-track magnetic tape (or any other kind of tape
7446 that can be backspaced with the @code{MTIOCTOP} @code{ioctl}.
7448 This means that the @value{op-append}, @value{op-update},
7449 @value{op-concatenate}, and @value{op-delete} commands will not work on any
7450 other kind of file. Some media simply cannot be backspaced, which
7451 means these commands and options will never be able to work on them.
7452 These non-backspacing media include pipes and cartridge tape drives.
7454 Some other media can be backspaced, and @command{tar} will work on them
7455 once @command{tar} is modified to do so.
7457 Archives created with the @value{op-multi-volume}, @value{op-label}, and
7458 @value{op-incremental} options may not be readable by other version
7459 of @command{tar}. In particular, restoring a file that was split over
7460 a volume boundary will require some careful work with @command{dd}, if
7461 it can be done at all. Other versions of @command{tar} may also create
7462 an empty file whose name is that of the volume header. Some versions
7463 of @command{tar} may create normal files instead of directories archived
7464 with the @value{op-incremental} option.
7466 @node Common Problems and Solutions
7467 @section Some Common Problems and their Solutions
7474 no such file or directory
7477 errors from @command{tar}:
7478 directory checksum error
7481 errors from media/system:
7492 @dfn{Block} and @dfn{record} terminology is rather confused, and it
7493 is also confusing to the expert reader. On the other hand, readers
7494 who are new to the field have a fresh mind, and they may safely skip
7495 the next two paragraphs, as the remainder of this manual uses those
7496 two terms in a quite consistent way.
7498 John Gilmore, the writer of the public domain @command{tar} from which
7499 @acronym{GNU} @command{tar} was originally derived, wrote (June 1995):
7502 The nomenclature of tape drives comes from IBM, where I believe
7503 they were invented for the IBM 650 or so. On IBM mainframes, what
7504 is recorded on tape are tape blocks. The logical organization of
7505 data is into records. There are various ways of putting records into
7506 blocks, including @code{F} (fixed sized records), @code{V} (variable
7507 sized records), @code{FB} (fixed blocked: fixed size records, @var{n}
7508 to a block), @code{VB} (variable size records, @var{n} to a block),
7509 @code{VSB} (variable spanned blocked: variable sized records that can
7510 occupy more than one block), etc. The @code{JCL} @samp{DD RECFORM=}
7511 parameter specified this to the operating system.
7513 The Unix man page on @command{tar} was totally confused about this.
7514 When I wrote @code{PD TAR}, I used the historically correct terminology
7515 (@command{tar} writes data records, which are grouped into blocks).
7516 It appears that the bogus terminology made it into @sc{posix} (no surprise
7517 here), and now Fran@,{c}ois has migrated that terminology back
7518 into the source code too.
7521 The term @dfn{physical block} means the basic transfer chunk from or
7522 to a device, after which reading or writing may stop without anything
7523 being lost. In this manual, the term @dfn{block} usually refers to
7524 a disk physical block, @emph{assuming} that each disk block is 512
7525 bytes in length. It is true that some disk devices have different
7526 physical blocks, but @command{tar} ignore these differences in its own
7527 format, which is meant to be portable, so a @command{tar} block is always
7528 512 bytes in length, and @dfn{block} always mean a @command{tar} block.
7529 The term @dfn{logical block} often represents the basic chunk of
7530 allocation of many disk blocks as a single entity, which the operating
7531 system treats somewhat atomically; this concept is only barely used
7532 in @acronym{GNU} @command{tar}.
7534 The term @dfn{physical record} is another way to speak of a physical
7535 block, those two terms are somewhat interchangeable. In this manual,
7536 the term @dfn{record} usually refers to a tape physical block,
7537 @emph{assuming} that the @command{tar} archive is kept on magnetic tape.
7538 It is true that archives may be put on disk or used with pipes,
7539 but nevertheless, @command{tar} tries to read and write the archive one
7540 @dfn{record} at a time, whatever the medium in use. One record is made
7541 up of an integral number of blocks, and this operation of putting many
7542 disk blocks into a single tape block is called @dfn{reblocking}, or
7543 more simply, @dfn{blocking}. The term @dfn{logical record} refers to
7544 the logical organization of many characters into something meaningful
7545 to the application. The term @dfn{unit record} describes a small set
7546 of characters which are transmitted whole to or by the application,
7547 and often refers to a line of text. Those two last terms are unrelated
7548 to what we call a @dfn{record} in @acronym{GNU} @command{tar}.
7550 When writing to tapes, @command{tar} writes the contents of the archive
7551 in chunks known as @dfn{records}. To change the default blocking
7552 factor, use the @value{op-blocking-factor} option. Each record will
7553 then be composed of @var{512-size} blocks. (Each @command{tar} block is
7554 512 bytes. @xref{Standard}.) Each file written to the archive uses
7555 at least one full record. As a result, using a larger record size
7556 can result in more wasted space for small files. On the other hand, a
7557 larger record size can often be read and written much more efficiently.
7559 Further complicating the problem is that some tape drives ignore the
7560 blocking entirely. For these, a larger record size can still improve
7561 performance (because the software layers above the tape drive still
7562 honor the blocking), but not as dramatically as on tape drives that
7565 When reading an archive, @command{tar} can usually figure out the
7566 record size on itself. When this is the case, and a non-standard
7567 record size was used when the archive was created, @command{tar} will
7568 print a message about a non-standard blocking factor, and then operate
7569 normally. On some tape devices, however, @command{tar} cannot figure
7570 out the record size itself. On most of those, you can specify a
7571 blocking factor (with @value{op-blocking-factor}) larger than the
7572 actual blocking factor, and then use the @value{op-read-full-records}
7573 option. (If you specify a blocking factor with
7574 @value{op-blocking-factor} and don't use the
7575 @value{op-read-full-records} option, then @command{tar} will not
7576 attempt to figure out the recording size itself.) On some devices,
7577 you must always specify the record size exactly with
7578 @value{op-blocking-factor} when reading, because @command{tar} cannot
7579 figure it out. In any case, use @value{op-list} before doing any
7580 extractions to see whether @command{tar} is reading the archive
7583 @command{tar} blocks are all fixed size (512 bytes), and its scheme for
7584 putting them into records is to put a whole number of them (one or
7585 more) into each record. @command{tar} records are all the same size;
7586 at the end of the file there's a block containing all zeros, which
7587 is how you tell that the remainder of the last record(s) are garbage.
7589 In a standard @command{tar} file (no options), the block size is 512
7590 and the record size is 10240, for a blocking factor of 20. What the
7591 @value{op-blocking-factor} option does is sets the blocking factor,
7592 changing the record size while leaving the block size at 512 bytes.
7593 20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives;
7594 most tape drives these days prefer much bigger records in order to
7595 stream and not waste tape. When writing tapes for myself, some tend
7596 to use a factor of the order of 2048, say, giving a record size of
7597 around one megabyte.
7599 If you use a blocking factor larger than 20, older @command{tar}
7600 programs might not be able to read the archive, so we recommend this
7601 as a limit to use in practice. @acronym{GNU} @command{tar}, however,
7602 will support arbitrarily large record sizes, limited only by the
7603 amount of virtual memory or the physical characteristics of the tape
7607 * Format Variations:: Format Variations
7608 * Blocking Factor:: The Blocking Factor of an Archive
7611 @node Format Variations
7612 @subsection Format Variations
7613 @cindex Format Parameters
7614 @cindex Format Options
7615 @cindex Options, archive format specifying
7616 @cindex Options, format specifying
7619 Format parameters specify how an archive is written on the archive
7620 media. The best choice of format parameters will vary depending on
7621 the type and number of files being archived, and on the media used to
7624 To specify format parameters when accessing or creating an archive,
7625 you can use the options described in the following sections.
7626 If you do not specify any format parameters, @command{tar} uses
7627 default parameters. You cannot modify a compressed archive.
7628 If you create an archive with the @value{op-blocking-factor} option
7629 specified (@value{pxref-blocking-factor}), you must specify that
7630 blocking-factor when operating on the archive. @xref{Formats}, for other
7631 examples of format parameter considerations.
7633 @node Blocking Factor
7634 @subsection The Blocking Factor of an Archive
7635 @cindex Blocking Factor
7637 @cindex Number of blocks per record
7638 @cindex Number of bytes per record
7639 @cindex Bytes per record
7640 @cindex Blocks per record
7643 The data in an archive is grouped into blocks, which are 512 bytes.
7644 Blocks are read and written in whole number multiples called
7645 @dfn{records}. The number of blocks in a record (ie. the size of a
7646 record in units of 512 bytes) is called the @dfn{blocking factor}.
7647 The @value{op-blocking-factor} option specifies the blocking factor of
7648 an archive. The default blocking factor is typically 20 (ie.@:
7649 10240 bytes), but can be specified at installation. To find out
7650 the blocking factor of an existing archive, use @samp{tar --list
7651 --file=@var{archive-name}}. This may not work on some devices.
7653 Records are separated by gaps, which waste space on the archive media.
7654 If you are archiving on magnetic tape, using a larger blocking factor
7655 (and therefore larger records) provides faster throughput and allows you
7656 to fit more data on a tape (because there are fewer gaps). If you are
7657 archiving on cartridge, a very large blocking factor (say 126 or more)
7658 greatly increases performance. A smaller blocking factor, on the other
7659 hand, may be useful when archiving small files, to avoid archiving lots
7660 of nulls as @command{tar} fills out the archive to the end of the record.
7661 In general, the ideal record size depends on the size of the
7662 inter-record gaps on the tape you are using, and the average size of the
7663 files you are archiving. @xref{create}, for information on
7666 @FIXME{Need example of using a cartridge with blocking factor=126 or more.}
7668 Archives with blocking factors larger than 20 cannot be read
7669 by very old versions of @command{tar}, or by some newer versions
7670 of @command{tar} running on old machines with small address spaces.
7671 With @acronym{GNU} @command{tar}, the blocking factor of an archive is limited
7672 only by the maximum record size of the device containing the archive,
7673 or by the amount of available virtual memory.
7675 Also, on some systems, not using adequate blocking factors, as sometimes
7676 imposed by the device drivers, may yield unexpected diagnostics. For
7677 example, this has been reported:
7680 Cannot write to /dev/dlt: Invalid argument
7684 In such cases, it sometimes happen that the @command{tar} bundled by
7685 the system is aware of block size idiosyncrasies, while @acronym{GNU}
7686 @command{tar} requires an explicit specification for the block size,
7687 which it cannot guess. This yields some people to consider
7688 @acronym{GNU} @command{tar} is misbehaving, because by comparison,
7689 @cite{the bundle @command{tar} works OK}. Adding @w{@kbd{-b 256}},
7690 for example, might resolve the problem.
7692 If you use a non-default blocking factor when you create an archive, you
7693 must specify the same blocking factor when you modify that archive. Some
7694 archive devices will also require you to specify the blocking factor when
7695 reading that archive, however this is not typically the case. Usually, you
7696 can use @value{op-list} without specifying a blocking factor---@command{tar}
7697 reports a non-default record size and then lists the archive members as
7698 it would normally. To extract files from an archive with a non-standard
7699 blocking factor (particularly if you're not sure what the blocking factor
7700 is), you can usually use the @value{op-read-full-records} option while
7701 specifying a blocking factor larger then the blocking factor of the archive
7702 (ie. @samp{tar --extract --read-full-records --blocking-factor=300}.
7703 @xref{list}, for more information on the @value{op-list}
7704 operation. @xref{Reading}, for a more detailed explanation of that option.
7707 @item --blocking-factor=@var{number}
7708 @itemx -b @var{number}
7709 Specifies the blocking factor of an archive. Can be used with any
7710 operation, but is usually not necessary with @value{op-list}.
7716 @item -b @var{blocks}
7717 @itemx --blocking-factor=@var{blocks}
7718 Set record size to @math{@var{blocks} * 512} bytes.
7720 This option is used to specify a @dfn{blocking factor} for the archive.
7721 When reading or writing the archive, @command{tar}, will do reads and writes
7722 of the archive in records of @math{@var{block}*512} bytes. This is true
7723 even when the archive is compressed. Some devices requires that all
7724 write operations be a multiple of a certain size, and so, @command{tar}
7725 pads the archive out to the next record boundary.
7727 The default blocking factor is set when @command{tar} is compiled, and is
7728 typically 20. Blocking factors larger than 20 cannot be read by very
7729 old versions of @command{tar}, or by some newer versions of @command{tar}
7730 running on old machines with small address spaces.
7732 With a magnetic tape, larger records give faster throughput and fit
7733 more data on a tape (because there are fewer inter-record gaps).
7734 If the archive is in a disk file or a pipe, you may want to specify
7735 a smaller blocking factor, since a large one will result in a large
7736 number of null bytes at the end of the archive.
7738 When writing cartridge or other streaming tapes, a much larger
7739 blocking factor (say 126 or more) will greatly increase performance.
7740 However, you must specify the same blocking factor when reading or
7741 updating the archive.
7743 Apparently, Exabyte drives have a physical block size of 8K bytes.
7744 If we choose our blocksize as a multiple of 8k bytes, then the problem
7745 seems to dissapper. Id est, we are using block size of 112 right
7746 now, and we haven't had the problem since we switched@dots{}
7748 With @acronym{GNU} @command{tar} the blocking factor is limited only
7749 by the maximum record size of the device containing the archive, or by
7750 the amount of available virtual memory.
7752 However, deblocking or reblocking is virtually avoided in a special
7753 case which often occurs in practice, but which requires all the
7754 following conditions to be simultaneously true:
7757 the archive is subject to a compression option,
7759 the archive is not handled through standard input or output, nor
7760 redirected nor piped,
7762 the archive is directly handled to a local disk, instead of any special
7765 @value{op-blocking-factor} is not explicitly specified on the @command{tar}
7769 In previous versions of @acronym{GNU} @command{tar}, the
7770 @samp{--compress-block} option (or even older:
7771 @samp{--block-compress}) was necessary to reblock compressed archives.
7772 It is now a dummy option just asking not to be used, and otherwise
7773 ignored. If the output goes directly to a local disk, and not through
7774 stdout, then the last write is not extended to a full record size.
7775 Otherwise, reblocking occurs. Here are a few other remarks on this
7781 @command{gzip} will complain about trailing garbage if asked to
7782 uncompress a compressed archive on tape, there is an option to turn
7783 the message off, but it breaks the regularity of simply having to use
7784 @samp{@var{prog} -d} for decompression. It would be nice if gzip was
7785 silently ignoring any number of trailing zeros. I'll ask Jean-loup
7786 Gailly, by sending a copy of this message to him.
7789 @command{compress} does not show this problem, but as Jean-loup pointed
7790 out to Michael, @samp{compress -d} silently adds garbage after
7791 the result of decompression, which tar ignores because it already
7792 recognized its end-of-file indicator. So this bug may be safely
7796 @samp{gzip -d -q} will be silent about the trailing zeros indeed,
7797 but will still return an exit status of 2 which tar reports in turn.
7798 @command{tar} might ignore the exit status returned, but I hate doing
7799 that, as it weakens the protection @command{tar} offers users against
7800 other possible problems at decompression time. If @command{gzip} was
7801 silently skipping trailing zeros @emph{and} also avoiding setting the
7802 exit status in this innocuous case, that would solve this situation.
7805 @command{tar} should become more solid at not stopping to read a pipe at
7806 the first null block encountered. This inelegantly breaks the pipe.
7807 @command{tar} should rather drain the pipe out before exiting itself.
7811 @itemx --ignore-zeros
7812 Ignore blocks of zeros in archive (means EOF).
7814 The @value{op-ignore-zeros} option causes @command{tar} to ignore blocks
7815 of zeros in the archive. Normally a block of zeros indicates the
7816 end of the archive, but when reading a damaged archive, or one which
7817 was created by concatenating several archives together, this option
7818 allows @command{tar} to read the entire archive. This option is not on
7819 by default because many versions of @command{tar} write garbage after
7822 Note that this option causes @command{tar} to read to the end of the
7823 archive file, which may sometimes avoid problems when multiple files
7824 are stored on a single physical tape.
7827 @itemx --read-full-records
7828 Reblock as we read (for reading 4.2BSD pipes).
7830 If @value{op-read-full-records} is used, @command{tar} will not panic if an
7831 attempt to read a record from the archive does not return a full record.
7832 Instead, @command{tar} will keep reading until it has obtained a full
7835 This option is turned on by default when @command{tar} is reading
7836 an archive from standard input, or from a remote machine. This is
7837 because on BSD Unix systems, a read of a pipe will return however
7838 much happens to be in the pipe, even if it is less than @command{tar}
7839 requested. If this option was not used, @command{tar} would fail as
7840 soon as it read an incomplete record from the pipe.
7842 This option is also useful with the commands for updating an archive.
7848 @FIXME{Appropriate options should be moved here from elsewhere.}
7850 @cindex blocking factor
7851 @cindex tape blocking
7853 When handling various tapes or cartridges, you have to take care of
7854 selecting a proper blocking, that is, the number of disk blocks you
7855 put together as a single tape block on the tape, without intervening
7856 tape gaps. A @dfn{tape gap} is a small landing area on the tape
7857 with no information on it, used for decelerating the tape to a
7858 full stop, and for later regaining the reading or writing speed.
7859 When the tape driver starts reading a record, the record has to
7860 be read whole without stopping, as a tape gap is needed to stop the
7861 tape motion without loosing information.
7863 @cindex Exabyte blocking
7864 @cindex DAT blocking
7865 Using higher blocking (putting more disk blocks per tape block) will use
7866 the tape more efficiently as there will be less tape gaps. But reading
7867 such tapes may be more difficult for the system, as more memory will be
7868 required to receive at once the whole record. Further, if there is a
7869 reading error on a huge record, this is less likely that the system will
7870 succeed in recovering the information. So, blocking should not be too
7871 low, nor it should be too high. @command{tar} uses by default a blocking of
7872 20 for historical reasons, and it does not really matter when reading or
7873 writing to disk. Current tape technology would easily accommodate higher
7874 blockings. Sun recommends a blocking of 126 for Exabytes and 96 for DATs.
7875 We were told that for some DLT drives, the blocking should be a multiple
7876 of 4Kb, preferably 64Kb (@w{@kbd{-b 128}}) or 256 for decent performance.
7877 Other manufacturers may use different recommendations for the same tapes.
7878 This might also depends of the buffering techniques used inside modern
7879 tape controllers. Some imposes a minimum blocking, or a maximum blocking.
7880 Others request blocking to be some exponent of two.
7882 So, there is no fixed rule for blocking. But blocking at read time
7883 should ideally be the same as blocking used at write time. At one place
7884 I know, with a wide variety of equipment, they found it best to use a
7885 blocking of 32 to guarantee that their tapes are fully interchangeable.
7887 I was also told that, for recycled tapes, prior erasure (by the same
7888 drive unit that will be used to create the archives) sometimes lowers
7889 the error rates observed at rewriting time.
7891 I might also use @samp{--number-blocks} instead of
7892 @samp{--block-number}, so @samp{--block} will then expand to
7893 @samp{--blocking-factor} unambiguously.
7896 @section Many Archives on One Tape
7898 @FIXME{Appropriate options should be moved here from elsewhere.}
7900 @findex ntape @r{device}
7901 Most tape devices have two entries in the @file{/dev} directory, or
7902 entries that come in pairs, which differ only in the minor number for
7903 this device. Let's take for example @file{/dev/tape}, which often
7904 points to the only or usual tape device of a given system. There might
7905 be a corresponding @file{/dev/nrtape} or @file{/dev/ntape}. The simpler
7906 name is the @emph{rewinding} version of the device, while the name
7907 having @samp{nr} in it is the @emph{no rewinding} version of the same
7910 A rewinding tape device will bring back the tape to its beginning point
7911 automatically when this device is opened or closed. Since @command{tar}
7912 opens the archive file before using it and closes it afterwards, this
7913 means that a simple:
7916 $ @kbd{tar cf /dev/tape @var{directory}}
7920 will reposition the tape to its beginning both prior and after saving
7921 @var{directory} contents to it, thus erasing prior tape contents and
7922 making it so that any subsequent write operation will destroy what has
7925 @cindex tape positioning
7926 So, a rewinding device is normally meant to hold one and only one file.
7927 If you want to put more than one @command{tar} archive on a given tape, you
7928 will need to avoid using the rewinding version of the tape device. You
7929 will also have to pay special attention to tape positioning. Errors in
7930 positioning may overwrite the valuable data already on your tape. Many
7931 people, burnt by past experiences, will only use rewinding devices and
7932 limit themselves to one file per tape, precisely to avoid the risk of
7933 such errors. Be fully aware that writing at the wrong position on a
7934 tape loses all information past this point and most probably until the
7935 end of the tape, and this destroyed information @emph{cannot} be
7938 To save @var{directory-1} as a first archive at the beginning of a
7939 tape, and leave that tape ready for a second archive, you should use:
7942 $ @kbd{mt -f /dev/nrtape rewind}
7943 $ @kbd{tar cf /dev/nrtape @var{directory-1}}
7947 @dfn{Tape marks} are special magnetic patterns written on the tape
7948 media, which are later recognizable by the reading hardware. These
7949 marks are used after each file, when there are many on a single tape.
7950 An empty file (that is to say, two tape marks in a row) signal the
7951 logical end of the tape, after which no file exist. Usually,
7952 non-rewinding tape device drivers will react to the close request issued
7953 by @command{tar} by first writing two tape marks after your archive, and by
7954 backspacing over one of these. So, if you remove the tape at that time
7955 from the tape drive, it is properly terminated. But if you write
7956 another file at the current position, the second tape mark will be
7957 erased by the new information, leaving only one tape mark between files.
7959 So, you may now save @var{directory-2} as a second archive after the
7960 first on the same tape by issuing the command:
7963 $ @kbd{tar cf /dev/nrtape @var{directory-2}}
7967 and so on for all the archives you want to put on the same tape.
7969 Another usual case is that you do not write all the archives the same
7970 day, and you need to remove and store the tape between two archive
7971 sessions. In general, you must remember how many files are already
7972 saved on your tape. Suppose your tape already has 16 files on it, and
7973 that you are ready to write the 17th. You have to take care of skipping
7974 the first 16 tape marks before saving @var{directory-17}, say, by using
7978 $ @kbd{mt -f /dev/nrtape rewind}
7979 $ @kbd{mt -f /dev/nrtape fsf 16}
7980 $ @kbd{tar cf /dev/nrtape @var{directory-17}}
7983 In all the previous examples, we put aside blocking considerations, but
7984 you should do the proper things for that as well. @xref{Blocking}.
7987 * Tape Positioning:: Tape Positions and Tape Marks
7988 * mt:: The @command{mt} Utility
7991 @node Tape Positioning
7992 @subsection Tape Positions and Tape Marks
7995 Just as archives can store more than one file from the file system,
7996 tapes can store more than one archive file. To keep track of where
7997 archive files (or any other type of file stored on tape) begin and
7998 end, tape archive devices write magnetic @dfn{tape marks} on the
7999 archive media. Tape drives write one tape mark between files,
8000 two at the end of all the file entries.
8002 If you think of data as a series of records "rrrr"'s, and tape marks as
8003 "*"'s, a tape might look like the following:
8006 rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
8009 Tape devices read and write tapes using a read/write @dfn{tape
8010 head}---a physical part of the device which can only access one
8011 point on the tape at a time. When you use @command{tar} to read or
8012 write archive data from a tape device, the device will begin reading
8013 or writing from wherever on the tape the tape head happens to be,
8014 regardless of which archive or what part of the archive the tape
8015 head is on. Before writing an archive, you should make sure that no
8016 data on the tape will be overwritten (unless it is no longer needed).
8017 Before reading an archive, you should make sure the tape head is at
8018 the beginning of the archive you want to read. (The @code{restore}
8019 script will find the archive automatically. @FIXME{There is no such
8020 restore script!}@FIXME-xref{Scripted Restoration}@xref{mt}, for
8021 an explanation of the tape moving utility.
8023 If you want to add new archive file entries to a tape, you should
8024 advance the tape to the end of the existing file entries, backspace
8025 over the last tape mark, and write the new archive file. If you were
8026 to add two archives to the example above, the tape might look like the
8030 rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
8034 @subsection The @command{mt} Utility
8037 @FIXME{Is it true that this only works on non-block devices?
8038 should explain the difference, (fixed or variable).}
8039 @value{xref-blocking-factor}.
8041 You can use the @command{mt} utility to advance or rewind a tape past a
8042 specified number of archive files on the tape. This will allow you
8043 to move to the beginning of an archive before extracting or reading
8044 it, or to the end of all the archives before writing a new one.
8045 @FIXME{Why isn't there an "advance 'til you find two tape marks
8048 The syntax of the @command{mt} command is:
8051 @kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]}
8054 where @var{tapename} is the name of the tape device, @var{number} is
8055 the number of times an operation is performed (with a default of one),
8056 and @var{operation} is one of the following:
8058 @FIXME{is there any use for record operations?}
8063 Writes @var{number} tape marks at the current position on the tape.
8066 Moves tape position forward @var{number} files.
8069 Moves tape position back @var{number} files.
8072 Rewinds the tape. (Ignores @var{number}).
8076 Rewinds the tape and takes the tape device off-line. (Ignores @var{number}).
8079 Prints status information about the tape unit.
8083 @FIXME{Is there a better way to frob the spacing on the list?}
8085 If you don't specify a @var{tapename}, @command{mt} uses the environment
8086 variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} uses the device
8089 @command{mt} returns a 0 exit status when the operation(s) were
8090 successful, 1 if the command was unrecognized, and 2 if an operation
8093 @FIXME{New node on how to find an archive?}
8095 If you use @value{op-extract} with the @value{op-label} option specified,
8096 @command{tar} will read an archive label (the tape head has to be positioned
8097 on it) and print an error if the archive label doesn't match the
8098 @var{archive-name} specified. @var{archive-name} can be any regular
8099 expression. If the labels match, @command{tar} extracts the archive.
8101 @FIXME-xref{Matching Format Parameters}@FIXME{fix cross
8102 references}@samp{tar --list --label} will cause @command{tar} to print the
8105 @FIXME{Program to list all the labels on a tape?}
8107 @node Using Multiple Tapes
8108 @section Using Multiple Tapes
8111 Often you might want to write a large archive, one larger than will fit
8112 on the actual tape you are using. In such a case, you can run multiple
8113 @command{tar} commands, but this can be inconvenient, particularly if you
8114 are using options like @value{op-exclude} or dumping entire filesystems.
8115 Therefore, @command{tar} supports multiple tapes automatically.
8117 Use @value{op-multi-volume} on the command line, and then @command{tar} will,
8118 when it reaches the end of the tape, prompt for another tape, and
8119 continue the archive. Each tape will have an independent archive, and
8120 can be read without needing the other. (As an exception to this, the
8121 file that @command{tar} was archiving when it ran out of tape will usually
8122 be split between the two archives; in this case you need to extract from
8123 the first archive, using @value{op-multi-volume}, and then put in the
8124 second tape when prompted, so @command{tar} can restore both halves of the
8127 @acronym{GNU} @command{tar} multi-volume archives do not use a truly
8128 portable format. You need @acronym{GNU} @command{tar} at both end to
8129 process them properly.
8131 When prompting for a new tape, @command{tar} accepts any of the following
8136 Request @command{tar} to explain possible responses
8138 Request @command{tar} to exit immediately.
8139 @item n @var{file name}
8140 Request @command{tar} to write the next volume on the file @var{file name}.
8142 Request @command{tar} to run a subshell.
8144 Request @command{tar} to begin writing the next volume.
8147 (You should only type @samp{y} after you have changed the tape;
8148 otherwise @command{tar} will write over the volume it just finished.)
8150 If you want more elaborate behavior than this, give @command{tar} the
8151 @value{op-info-script} option. The file @var{script-name} is expected
8152 to be a program (or shell script) to be run instead of the normal
8153 prompting procedure. If the program fails, @command{tar} exits;
8154 otherwise, @command{tar} begins writing the next volume. The behavior
8156 @samp{n} response to the normal tape-change prompt is not available
8157 if you use @value{op-info-script}.
8159 The method @command{tar} uses to detect end of tape is not perfect, and
8160 fails on some operating systems or on some devices. You can use the
8161 @value{op-tape-length} option if @command{tar} can't detect the end of the
8162 tape itself. This option selects @value{op-multi-volume} automatically.
8163 The @var{size} argument should then be the usable size of the tape.
8164 But for many devices, and floppy disks in particular, this option is
8165 never required for real, as far as we know.
8167 The volume number used by @command{tar} in its tape-change prompt
8168 can be changed; if you give the @value{op-volno-file} option, then
8169 @var{file-of-number} should be an unexisting file to be created, or else,
8170 a file already containing a decimal number. That number will be used
8171 as the volume number of the first volume written. When @command{tar} is
8172 finished, it will rewrite the file with the now-current volume number.
8173 (This does not change the volume number written on a tape label, as
8174 per @value{ref-label}, it @emph{only} affects the number used in
8177 If you want @command{tar} to cycle through a series of tape drives, then
8178 you can use the @samp{n} response to the tape-change prompt. This is
8179 error prone, however, and doesn't work at all with @value{op-info-script}.
8180 Therefore, if you give @command{tar} multiple @value{op-file} options, then
8181 the specified files will be used, in sequence, as the successive volumes
8182 of the archive. Only when the first one in the sequence needs to be
8183 used again will @command{tar} prompt for a tape change (or run the info
8186 Multi-volume archives
8188 With @value{op-multi-volume}, @command{tar} will not abort when it cannot
8189 read or write any more data. Instead, it will ask you to prepare a new
8190 volume. If the archive is on a magnetic tape, you should change tapes
8191 now; if the archive is on a floppy disk, you should change disks, etc.
8193 Each volume of a multi-volume archive is an independent @command{tar}
8194 archive, complete in itself. For example, you can list or extract any
8195 volume alone; just don't specify @value{op-multi-volume}. However, if one
8196 file in the archive is split across volumes, the only way to extract
8197 it successfully is with a multi-volume extract command @samp{--extract
8198 --multi-volume} (@samp{-xM}) starting on or before the volume where
8201 For example, let's presume someone has two tape drives on a system
8202 named @file{/dev/tape0} and @file{/dev/tape1}. For having @acronym{GNU}
8203 @command{tar} to switch to the second drive when it needs to write the
8204 second tape, and then back to the first tape, etc., just do either of:
8207 $ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}}
8208 $ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
8212 * Multi-Volume Archives:: Archives Longer than One Tape or Disk
8213 * Tape Files:: Tape Files
8216 @node Multi-Volume Archives
8217 @subsection Archives Longer than One Tape or Disk
8218 @cindex Multi-volume archives
8221 To create an archive that is larger than will fit on a single unit of
8222 the media, use the @value{op-multi-volume} option in conjunction with
8223 the @value{op-create} option (@pxref{create}). A
8224 @dfn{multi-volume} archive can be manipulated like any other archive
8225 (provided the @value{op-multi-volume} option is specified), but is
8226 stored on more than one tape or disk.
8228 When you specify @value{op-multi-volume}, @command{tar} does not report an
8229 error when it comes to the end of an archive volume (when reading), or
8230 the end of the media (when writing). Instead, it prompts you to load
8231 a new storage volume. If the archive is on a magnetic tape, you
8232 should change tapes when you see the prompt; if the archive is on a
8233 floppy disk, you should change disks; etc.
8235 You can read each individual volume of a multi-volume archive as if it
8236 were an archive by itself. For example, to list the contents of one
8237 volume, use @value{op-list}, without @value{op-multi-volume} specified.
8238 To extract an archive member from one volume (assuming it is described
8239 that volume), use @value{op-extract}, again without
8240 @value{op-multi-volume}.
8242 If an archive member is split across volumes (ie. its entry begins on
8243 one volume of the media and ends on another), you need to specify
8244 @value{op-multi-volume} to extract it successfully. In this case, you
8245 should load the volume where the archive member starts, and use
8246 @samp{tar --extract --multi-volume}---@command{tar} will prompt for later
8247 volumes as it needs them. @xref{extracting archives}, for more
8248 information about extracting archives.
8250 @value{op-info-script} is like @value{op-multi-volume}, except that
8251 @command{tar} does not prompt you directly to change media volumes when
8252 a volume is full---instead, @command{tar} runs commands you have stored
8253 in @var{script-name}. For example, this option can be used to eject
8254 cassettes, or to broadcast messages such as @samp{Someone please come
8255 change my tape} when performing unattended backups. When @var{script-name}
8256 is done, @command{tar} will assume that the media has been changed.
8258 Multi-volume archives can be modified like any other archive. To add
8259 files to a multi-volume archive, you need to only mount the last
8260 volume of the archive media (and new volumes, if needed). For all
8261 other operations, you need to use the entire archive.
8263 If a multi-volume archive was labeled using @value{op-label}
8264 (@value{pxref-label}) when it was created, @command{tar} will not
8265 automatically label volumes which are added later. To label subsequent
8266 volumes, specify @value{op-label} again in conjunction with the
8267 @value{op-append}, @value{op-update} or @value{op-concatenate} operation.
8269 @cindex Labeling multi-volume archives
8272 @FIXME{There should be a sample program here, including an exit
8273 before end. Is the exit status even checked in tar? :-(}
8276 @item --multi-volume
8278 Creates a multi-volume archive, when used in conjunction with
8279 @value{op-create}. To perform any other operation on a multi-volume
8280 archive, specify @value{op-multi-volume} in conjunction with that
8283 @item --info-script=@var{program-file}
8284 @itemx -F @var{program-file}
8285 Creates a multi-volume archive via a script. Used in conjunction with
8289 Beware that there is @emph{no} real standard about the proper way, for
8290 a @command{tar} archive, to span volume boundaries. If you have a
8291 multi-volume created by some vendor's @command{tar}, there is almost
8292 no chance you could read all the volumes with @acronym{GNU}
8293 @command{tar}. The converse is also true: you may not expect
8294 multi-volume archives created by @acronym{GNU} @command{tar} to be
8295 fully recovered by vendor's @command{tar}. Since there is little
8296 chance that, in mixed system configurations, some vendor's
8297 @command{tar} will work on another vendor's machine, and there is a
8298 great chance that @acronym{GNU} @command{tar} will work on most of
8299 them, your best bet is to install @acronym{GNU} @command{tar} on all
8300 machines between which you know exchange of files is possible.
8303 @subsection Tape Files
8306 To give the archive a name which will be recorded in it, use the
8307 @value{op-label} option. This will write a special block identifying
8308 @var{volume-label} as the name of the archive to the front of the archive
8309 which will be displayed when the archive is listed with @value{op-list}.
8310 If you are creating a multi-volume archive with
8311 @value{op-multi-volume}@FIXME-pxref{Using Multiple Tapes}, then the
8312 volume label will have
8313 @samp{Volume @var{nnn}} appended to the name you give, where @var{nnn} is
8314 the number of the volume of the archive. (If you use the @value{op-label}
8315 option when reading an archive, it checks to make sure the label on the
8316 tape matches the one you give. @value{xref-label}.
8318 When @command{tar} writes an archive to tape, it creates a single
8319 tape file. If multiple archives are written to the same tape, one
8320 after the other, they each get written as separate tape files. When
8321 extracting, it is necessary to position the tape at the right place
8322 before running @command{tar}. To do this, use the @command{mt} command.
8323 For more information on the @command{mt} command and on the organization
8324 of tapes into a sequence of tape files, see @ref{mt}.
8326 People seem to often do:
8329 @kbd{--label="@var{some-prefix} `date +@var{some-format}`"}
8332 or such, for pushing a common date in all volumes or an archive set.
8335 @section Including a Label in the Archive
8336 @cindex Labeling an archive
8337 @cindex Labels on the archive media
8342 @itemx --label=@var{name}
8343 Create archive with volume name @var{name}.
8346 This option causes @command{tar} to write out a @dfn{volume header} at
8347 the beginning of the archive. If @value{op-multi-volume} is used, each
8348 volume of the archive will have a volume header of @samp{@var{name}
8349 Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the
8352 @FIXME{Should the arg to --label be a quoted string?? No.}
8354 To avoid problems caused by misplaced paper labels on the archive
8355 media, you can include a @dfn{label} entry---an archive member which
8356 contains the name of the archive---in the archive itself. Use the
8357 @value{op-label} option in conjunction with the @value{op-create} operation
8358 to include a label entry in the archive as it is being created.
8360 If you create an archive using both @value{op-label} and
8361 @value{op-multi-volume}, each volume of the archive will have an
8362 archive label of the form @samp{@var{archive-label} Volume @var{n}},
8363 where @var{n} is 1 for the first volume, 2 for the next, and so on.
8364 @FIXME-xref{Multi-Volume Archives, for information on creating multiple
8367 If you list or extract an archive using @value{op-label}, @command{tar} will
8368 print an error if the archive label doesn't match the @var{archive-label}
8369 specified, and will then not list nor extract the archive. In those cases,
8370 @var{archive-label} argument is interpreted as a globbing-style pattern
8371 which must match the actual magnetic volume label. @xref{exclude}, for
8372 a precise description of how match is attempted@footnote{Previous versions
8373 of @command{tar} used full regular expression matching, or before that, only
8374 exact string matching, instead of wildcard matchers. We decided for the
8375 sake of simplicity to use a uniform matching device through @command{tar}.}.
8376 If the switch @value{op-multi-volume} is being used, the volume label
8377 matcher will also suffix @var{archive-label} by @w{@samp{ Volume [1-9]*}}
8378 if the initial match fails, before giving up. Since the volume numbering
8379 is automatically added in labels at creation time, it sounded logical to
8380 equally help the user taking care of it when the archive is being read.
8382 The @value{op-label} was once called @samp{--volume}, but is not available
8383 under that name anymore.
8385 To find out an archive's label entry (or to find out if an archive has
8386 a label at all), use @samp{tar --list --verbose}. @command{tar} will
8387 print the label first, and then print archive member information, as
8388 in the example below:
8391 $ @kbd{tar --verbose --list --file=iamanarchive}
8392 V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
8393 -rw-rw-rw- ringo user 40 1990-05-21 13:30 iamafilename
8397 @item --label=@var{archive-label}
8398 @itemx -V @var{archive-label}
8399 Includes an @dfn{archive-label} at the beginning of the archive when
8400 the archive is being created, when used in conjunction with the
8401 @value{op-create} option. Checks to make sure the archive label
8402 matches the one specified (when used in conjunction with the
8403 @value{op-extract} option.
8406 To get a common information on all tapes of a series, use the
8407 @value{op-label} option. For having this information different in each
8408 series created through a single script used on a regular basis, just
8409 manage to get some date string as part of the label. For example:
8412 $ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
8413 $ @kbd{tar --create --file=/dev/tape --multi-volume \
8414 --volume="Daily backup for `date +%Y-%m-%d`"}
8417 Also note that each label has its own date and time, which corresponds
8418 to when @acronym{GNU} @command{tar} initially attempted to write it,
8419 often soon after the operator launches @command{tar} or types the
8420 carriage return telling that the next tape is ready. Comparing date
8421 labels does give an idea of tape throughput only if the delays for
8422 rewinding tapes and the operator switching them were negligible, which
8423 is usually not the case.
8425 @FIXME{was --volume}
8428 @section Verifying Data as It is Stored
8429 @cindex Verifying a write operation
8430 @cindex Double-checking a write operation
8435 Attempt to verify the archive after writing.
8438 This option causes @command{tar} to verify the archive after writing it.
8439 Each volume is checked after it is written, and any discrepancies
8440 are recorded on the standard error output.
8442 Verification requires that the archive be on a back-space-able medium.
8443 This means pipes, some cartridge tape drives, and some other devices
8446 You can insure the accuracy of an archive by comparing files in the
8447 system with archive members. @command{tar} can compare an archive to the
8448 file system as the archive is being written, to verify a write
8449 operation, or can compare a previously written archive, to insure that
8452 To check for discrepancies in an archive immediately after it is
8453 written, use the @value{op-verify} option in conjunction with
8454 the @value{op-create} operation. When this option is
8455 specified, @command{tar} checks archive members against their counterparts
8456 in the file system, and reports discrepancies on the standard error.
8458 To verify an archive, you must be able to read it from before the end
8459 of the last written entry. This option is useful for detecting data
8460 errors on some tapes. Archives written to pipes, some cartridge tape
8461 drives, and some other devices cannot be verified.
8463 One can explicitly compare an already made archive with the file system
8464 by using the @value{op-compare} option, instead of using the more automatic
8465 @value{op-verify} option. @value{xref-compare}.
8467 Note that these two options have a slightly different intent. The
8468 @value{op-compare} option how identical are the logical contents of some
8469 archive with what is on your disks, while the @value{op-verify} option is
8470 really for checking if the physical contents agree and if the recording
8471 media itself is of dependable quality. So, for the @value{op-verify}
8472 operation, @command{tar} tries to defeat all in-memory cache pertaining to
8473 the archive, while it lets the speed optimization undisturbed for the
8474 @value{op-compare} option. If you nevertheless use @value{op-compare} for
8475 media verification, you may have to defeat the in-memory cache yourself,
8476 maybe by opening and reclosing the door latch of your recording unit,
8477 forcing some doubt in your operating system about the fact this is really
8478 the same volume as the one just written or read.
8480 The @value{op-verify} option would not be necessary if drivers were indeed
8481 able to detect dependably all write failures. This sometimes require many
8482 magnetic heads, some able to read after the writes occurred. One would
8483 not say that drivers unable to detect all cases are necessarily flawed,
8484 as long as programming is concerned.
8486 The @value{op-verify} option will not work in conjunction with the
8487 @value{op-multi-volume} option or the @value{op-append},
8488 @value{op-update} and @value{op-delete} operations. @xref{Operations},
8489 for more information on these operations.
8491 Also, since @command{tar} normally strips leading @samp{/} from file
8492 names (@pxref{absolute}), a command like @samp{tar --verify -cf
8493 /tmp/foo.tar /etc} will work as desired only if the working directory is
8494 @file{/}, as @command{tar} uses the archive's relative member names
8495 (e.g., @file{etc/motd}) when verifying the archive.
8497 @node Write Protection
8498 @section Write Protection
8500 Almost all tapes and diskettes, and in a few rare cases, even disks can
8501 be @dfn{write protected}, to protect data on them from being changed.
8502 Once an archive is written, you should write protect the media to prevent
8503 the archive from being accidentally overwritten or deleted. (This will
8504 protect the archive from being changed with a tape or floppy drive---it
8505 will not protect it from magnet fields or other physical hazards).
8507 The write protection device itself is usually an integral part of the
8508 physical media, and can be a two position (write enabled/write
8509 disabled) switch, a notch which can be popped out or covered, a ring
8510 which can be removed from the center of a tape reel, or some other
8513 @node Free Software Needs Free Documentation
8514 @appendix Free Software Needs Free Documentation
8515 @include freemanuals.texi
8517 @node Copying This Manual
8518 @appendix Copying This Manual
8521 * GNU Free Documentation License:: License for copying this manual
8536 @c texinfo-column-for-description: 32