Line 0
Link Here
|
|
|
1 |
\input texinfo @c -*-texinfo-*- |
2 |
@comment %**start of header |
3 |
@setfilename tar.info |
4 |
@include version.texi |
5 |
@settitle GNU tar @value{VERSION} |
6 |
@setchapternewpage odd |
7 |
|
8 |
@finalout |
9 |
|
10 |
@smallbook |
11 |
@c %**end of header |
12 |
|
13 |
@c Maintenance notes: |
14 |
@c 1. Pay attention to @FIXME{}s and @UNREVISED{}s |
15 |
@c 2. Before creating final variant: |
16 |
@c 2.1. Run `make check-options' to make sure all options are properly |
17 |
@c documented; |
18 |
@c 2.2. Run `make master-menu' (see comment before the master menu). |
19 |
|
20 |
@include rendition.texi |
21 |
@include value.texi |
22 |
|
23 |
@defcodeindex op |
24 |
@defcodeindex kw |
25 |
|
26 |
@c Put everything in one index (arbitrarily chosen to be the concept index). |
27 |
@syncodeindex fn cp |
28 |
@syncodeindex ky cp |
29 |
@syncodeindex pg cp |
30 |
@syncodeindex vr cp |
31 |
@syncodeindex kw cp |
32 |
|
33 |
@copying |
34 |
|
35 |
This manual is for @acronym{GNU} @command{tar} (version |
36 |
@value{VERSION}, @value{UPDATED}), which creates and extracts files |
37 |
from archives. |
38 |
|
39 |
Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, |
40 |
2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. |
41 |
|
42 |
@quotation |
43 |
Permission is granted to copy, distribute and/or modify this document |
44 |
under the terms of the GNU Free Documentation License, Version 1.3 or |
45 |
any later version published by the Free Software Foundation; with no |
46 |
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', |
47 |
and with the Back-Cover Texts as in (a) below. A copy of the license |
48 |
is included in the section entitled ``GNU Free Documentation |
49 |
License''. |
50 |
|
51 |
(a) The FSF's Back-Cover Text is: ``You have the freedom to |
52 |
copy and modify this GNU manual. Buying copies from the FSF |
53 |
supports it in developing GNU and promoting software freedom.'' |
54 |
@end quotation |
55 |
@end copying |
56 |
|
57 |
@dircategory Archiving |
58 |
@direntry |
59 |
* Tar: (tar). Making tape (or disk) archives. |
60 |
@end direntry |
61 |
|
62 |
@dircategory Individual utilities |
63 |
@direntry |
64 |
* tar: (tar)tar invocation. Invoking @GNUTAR{}. |
65 |
@end direntry |
66 |
|
67 |
@shorttitlepage @acronym{GNU} @command{tar} |
68 |
|
69 |
@titlepage |
70 |
@title @acronym{GNU} tar: an archiver tool |
71 |
@subtitle @value{RENDITION} @value{VERSION}, @value{UPDATED} |
72 |
@author John Gilmore, Jay Fenlason et al. |
73 |
|
74 |
@page |
75 |
@vskip 0pt plus 1filll |
76 |
@insertcopying |
77 |
@end titlepage |
78 |
|
79 |
@ifnottex |
80 |
@node Top |
81 |
@top @acronym{GNU} tar: an archiver tool |
82 |
|
83 |
@insertcopying |
84 |
|
85 |
@cindex file archival |
86 |
@cindex archiving files |
87 |
|
88 |
The first part of this master menu lists the major nodes in this Info |
89 |
document. The rest of the menu lists all the lower level nodes. |
90 |
@end ifnottex |
91 |
|
92 |
@c The master menu goes here. |
93 |
@c |
94 |
@c NOTE: To update it from within Emacs, make sure mastermenu.el is |
95 |
@c loaded and run texinfo-master-menu. |
96 |
@c To update it from the command line, run |
97 |
@c |
98 |
@c make master-menu |
99 |
|
100 |
@menu |
101 |
* Introduction:: |
102 |
* Tutorial:: |
103 |
* tar invocation:: |
104 |
* operations:: |
105 |
* Backups:: |
106 |
* Choosing:: |
107 |
* Date input formats:: |
108 |
* Formats:: |
109 |
* Media:: |
110 |
* Reliability and security:: |
111 |
|
112 |
Appendices |
113 |
|
114 |
* Changes:: |
115 |
* Configuring Help Summary:: |
116 |
* Fixing Snapshot Files:: |
117 |
* Tar Internals:: |
118 |
* Genfile:: |
119 |
* Free Software Needs Free Documentation:: |
120 |
* GNU Free Documentation License:: |
121 |
* Index of Command Line Options:: |
122 |
* Index:: |
123 |
|
124 |
@detailmenu |
125 |
--- The Detailed Node Listing --- |
126 |
|
127 |
Introduction |
128 |
|
129 |
* Book Contents:: What this Book Contains |
130 |
* Definitions:: Some Definitions |
131 |
* What tar Does:: What @command{tar} Does |
132 |
* Naming tar Archives:: How @command{tar} Archives are Named |
133 |
* Authors:: @GNUTAR{} Authors |
134 |
* Reports:: Reporting bugs or suggestions |
135 |
|
136 |
Tutorial Introduction to @command{tar} |
137 |
|
138 |
* assumptions:: |
139 |
* stylistic conventions:: |
140 |
* basic tar options:: Basic @command{tar} Operations and Options |
141 |
* frequent operations:: |
142 |
* Two Frequent Options:: |
143 |
* create:: How to Create Archives |
144 |
* list:: How to List Archives |
145 |
* extract:: How to Extract Members from an Archive |
146 |
* going further:: |
147 |
|
148 |
Two Frequently Used Options |
149 |
|
150 |
* file tutorial:: |
151 |
* verbose tutorial:: |
152 |
* help tutorial:: |
153 |
|
154 |
How to Create Archives |
155 |
|
156 |
* prepare for examples:: |
157 |
* Creating the archive:: |
158 |
* create verbose:: |
159 |
* short create:: |
160 |
* create dir:: |
161 |
|
162 |
How to List Archives |
163 |
|
164 |
* list dir:: |
165 |
|
166 |
How to Extract Members from an Archive |
167 |
|
168 |
* extracting archives:: |
169 |
* extracting files:: |
170 |
* extract dir:: |
171 |
* extracting untrusted archives:: |
172 |
* failing commands:: |
173 |
|
174 |
Invoking @GNUTAR{} |
175 |
|
176 |
* Synopsis:: |
177 |
* using tar options:: |
178 |
* Styles:: |
179 |
* All Options:: |
180 |
* help:: |
181 |
* defaults:: |
182 |
* verbose:: |
183 |
* checkpoints:: |
184 |
* warnings:: |
185 |
* interactive:: |
186 |
|
187 |
The Three Option Styles |
188 |
|
189 |
* Long Options:: Long Option Style |
190 |
* Short Options:: Short Option Style |
191 |
* Old Options:: Old Option Style |
192 |
* Mixing:: Mixing Option Styles |
193 |
|
194 |
All @command{tar} Options |
195 |
|
196 |
* Operation Summary:: |
197 |
* Option Summary:: |
198 |
* Short Option Summary:: |
199 |
|
200 |
@GNUTAR{} Operations |
201 |
|
202 |
* Basic tar:: |
203 |
* Advanced tar:: |
204 |
* create options:: |
205 |
* extract options:: |
206 |
* backup:: |
207 |
* Applications:: |
208 |
* looking ahead:: |
209 |
|
210 |
Advanced @GNUTAR{} Operations |
211 |
|
212 |
* Operations:: |
213 |
* append:: |
214 |
* update:: |
215 |
* concatenate:: |
216 |
* delete:: |
217 |
* compare:: |
218 |
|
219 |
How to Add Files to Existing Archives: @option{--append} |
220 |
|
221 |
* appending files:: Appending Files to an Archive |
222 |
* multiple:: |
223 |
|
224 |
Updating an Archive |
225 |
|
226 |
* how to update:: |
227 |
|
228 |
Options Used by @option{--create} |
229 |
|
230 |
* override:: Overriding File Metadata. |
231 |
* Ignore Failed Read:: |
232 |
|
233 |
Options Used by @option{--extract} |
234 |
|
235 |
* Reading:: Options to Help Read Archives |
236 |
* Writing:: Changing How @command{tar} Writes Files |
237 |
* Scarce:: Coping with Scarce Resources |
238 |
|
239 |
Options to Help Read Archives |
240 |
|
241 |
* read full records:: |
242 |
* Ignore Zeros:: |
243 |
|
244 |
Changing How @command{tar} Writes Files |
245 |
|
246 |
* Dealing with Old Files:: |
247 |
* Overwrite Old Files:: |
248 |
* Keep Old Files:: |
249 |
* Keep Newer Files:: |
250 |
* Unlink First:: |
251 |
* Recursive Unlink:: |
252 |
* Data Modification Times:: |
253 |
* Setting Access Permissions:: |
254 |
* Directory Modification Times and Permissions:: |
255 |
* Writing to Standard Output:: |
256 |
* Writing to an External Program:: |
257 |
* remove files:: |
258 |
|
259 |
Coping with Scarce Resources |
260 |
|
261 |
* Starting File:: |
262 |
* Same Order:: |
263 |
|
264 |
Performing Backups and Restoring Files |
265 |
|
266 |
* Full Dumps:: Using @command{tar} to Perform Full Dumps |
267 |
* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps |
268 |
* Backup Levels:: Levels of Backups |
269 |
* Backup Parameters:: Setting Parameters for Backups and Restoration |
270 |
* Scripted Backups:: Using the Backup Scripts |
271 |
* Scripted Restoration:: Using the Restore Script |
272 |
|
273 |
Setting Parameters for Backups and Restoration |
274 |
|
275 |
* General-Purpose Variables:: |
276 |
* Magnetic Tape Control:: |
277 |
* User Hooks:: |
278 |
* backup-specs example:: An Example Text of @file{Backup-specs} |
279 |
|
280 |
Choosing Files and Names for @command{tar} |
281 |
|
282 |
* file:: Choosing the Archive's Name |
283 |
* Selecting Archive Members:: |
284 |
* files:: Reading Names from a File |
285 |
* exclude:: Excluding Some Files |
286 |
* wildcards:: Wildcards Patterns and Matching |
287 |
* quoting styles:: Ways of Quoting Special Characters in Names |
288 |
* transform:: Modifying File and Member Names |
289 |
* after:: Operating Only on New Files |
290 |
* recurse:: Descending into Directories |
291 |
* one:: Crossing File System Boundaries |
292 |
|
293 |
Reading Names from a File |
294 |
|
295 |
* nul:: |
296 |
|
297 |
Excluding Some Files |
298 |
|
299 |
* problems with exclude:: |
300 |
|
301 |
Wildcards Patterns and Matching |
302 |
|
303 |
* controlling pattern-matching:: |
304 |
|
305 |
Crossing File System Boundaries |
306 |
|
307 |
* directory:: Changing Directory |
308 |
* absolute:: Absolute File Names |
309 |
|
310 |
Date input formats |
311 |
|
312 |
* General date syntax:: Common rules. |
313 |
* Calendar date items:: 19 Dec 1994. |
314 |
* Time of day items:: 9:20pm. |
315 |
* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}. |
316 |
* Day of week items:: Monday and others. |
317 |
* Relative items in date strings:: next tuesday, 2 years ago. |
318 |
* Pure numbers in date strings:: 19931219, 1440. |
319 |
* Seconds since the Epoch:: @@1078100502. |
320 |
* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". |
321 |
* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al. |
322 |
|
323 |
Controlling the Archive Format |
324 |
|
325 |
* Compression:: Using Less Space through Compression |
326 |
* Attributes:: Handling File Attributes |
327 |
* Portability:: Making @command{tar} Archives More Portable |
328 |
* cpio:: Comparison of @command{tar} and @command{cpio} |
329 |
|
330 |
Using Less Space through Compression |
331 |
|
332 |
* gzip:: Creating and Reading Compressed Archives |
333 |
* sparse:: Archiving Sparse Files |
334 |
|
335 |
Creating and Reading Compressed Archives |
336 |
|
337 |
* lbzip2:: Using lbzip2 with @GNUTAR{}. |
338 |
|
339 |
Making @command{tar} Archives More Portable |
340 |
|
341 |
* Portable Names:: Portable Names |
342 |
* dereference:: Symbolic Links |
343 |
* hard links:: Hard Links |
344 |
* old:: Old V7 Archives |
345 |
* ustar:: Ustar Archives |
346 |
* gnu:: GNU and old GNU format archives. |
347 |
* posix:: @acronym{POSIX} archives |
348 |
* Checksumming:: Checksumming Problems |
349 |
* Large or Negative Values:: Large files, negative time stamps, etc. |
350 |
* Other Tars:: How to Extract GNU-Specific Data Using |
351 |
Other @command{tar} Implementations |
352 |
|
353 |
@GNUTAR{} and @acronym{POSIX} @command{tar} |
354 |
|
355 |
* PAX keywords:: Controlling Extended Header Keywords. |
356 |
|
357 |
How to Extract GNU-Specific Data Using Other @command{tar} Implementations |
358 |
|
359 |
* Split Recovery:: Members Split Between Volumes |
360 |
* Sparse Recovery:: Sparse Members |
361 |
|
362 |
Tapes and Other Archive Media |
363 |
|
364 |
* Device:: Device selection and switching |
365 |
* Remote Tape Server:: |
366 |
* Common Problems and Solutions:: |
367 |
* Blocking:: Blocking |
368 |
* Many:: Many archives on one tape |
369 |
* Using Multiple Tapes:: Using Multiple Tapes |
370 |
* label:: Including a Label in the Archive |
371 |
* verify:: |
372 |
* Write Protection:: |
373 |
|
374 |
Blocking |
375 |
|
376 |
* Format Variations:: Format Variations |
377 |
* Blocking Factor:: The Blocking Factor of an Archive |
378 |
|
379 |
Many Archives on One Tape |
380 |
|
381 |
* Tape Positioning:: Tape Positions and Tape Marks |
382 |
* mt:: The @command{mt} Utility |
383 |
|
384 |
Using Multiple Tapes |
385 |
|
386 |
* Multi-Volume Archives:: Archives Longer than One Tape or Disk |
387 |
* Tape Files:: Tape Files |
388 |
* Tarcat:: Concatenate Volumes into a Single Archive |
389 |
|
390 |
|
391 |
Tar Internals |
392 |
|
393 |
* Standard:: Basic Tar Format |
394 |
* Extensions:: @acronym{GNU} Extensions to the Archive Format |
395 |
* Sparse Formats:: Storing Sparse Files |
396 |
* Snapshot Files:: |
397 |
* Dumpdir:: |
398 |
|
399 |
Storing Sparse Files |
400 |
|
401 |
* Old GNU Format:: |
402 |
* PAX 0:: PAX Format, Versions 0.0 and 0.1 |
403 |
* PAX 1:: PAX Format, Version 1.0 |
404 |
|
405 |
Genfile |
406 |
|
407 |
* Generate Mode:: File Generation Mode. |
408 |
* Status Mode:: File Status Mode. |
409 |
* Exec Mode:: Synchronous Execution mode. |
410 |
|
411 |
Copying This Manual |
412 |
|
413 |
* GNU Free Documentation License:: License for copying this manual |
414 |
|
415 |
@end detailmenu |
416 |
@end menu |
417 |
|
418 |
@node Introduction |
419 |
@chapter Introduction |
420 |
|
421 |
@GNUTAR{} creates |
422 |
and manipulates @dfn{archives} which are actually collections of |
423 |
many other files; the program provides users with an organized and |
424 |
systematic method for controlling a large amount of data. |
425 |
The name ``tar'' originally came from the phrase ``Tape ARchive'', but |
426 |
archives need not (and these days, typically do not) reside on tapes. |
427 |
|
428 |
@menu |
429 |
* Book Contents:: What this Book Contains |
430 |
* Definitions:: Some Definitions |
431 |
* What tar Does:: What @command{tar} Does |
432 |
* Naming tar Archives:: How @command{tar} Archives are Named |
433 |
* Authors:: @GNUTAR{} Authors |
434 |
* Reports:: Reporting bugs or suggestions |
435 |
@end menu |
436 |
|
437 |
@node Book Contents |
438 |
@section What this Book Contains |
439 |
|
440 |
The first part of this chapter introduces you to various terms that will |
441 |
recur throughout the book. It also tells you who has worked on @GNUTAR{} |
442 |
and its documentation, and where you should send bug reports |
443 |
or comments. |
444 |
|
445 |
The second chapter is a tutorial (@pxref{Tutorial}) which provides a |
446 |
gentle introduction for people who are new to using @command{tar}. It is |
447 |
meant to be self-contained, not requiring any reading from subsequent |
448 |
chapters to make sense. It moves from topic to topic in a logical, |
449 |
progressive order, building on information already explained. |
450 |
|
451 |
Although the tutorial is paced and structured to allow beginners to |
452 |
learn how to use @command{tar}, it is not intended solely for beginners. |
453 |
The tutorial explains how to use the three most frequently used |
454 |
operations (@samp{create}, @samp{list}, and @samp{extract}) as well as |
455 |
two frequently used options (@samp{file} and @samp{verbose}). The other |
456 |
chapters do not refer to the tutorial frequently; however, if a section |
457 |
discusses something which is a complex variant of a basic concept, there |
458 |
may be a cross-reference to that basic concept. (The entire book, |
459 |
including the tutorial, assumes that the reader understands some basic |
460 |
concepts of using a Unix-type operating system; @pxref{Tutorial}.) |
461 |
|
462 |
The third chapter presents the remaining five operations, and |
463 |
information about using @command{tar} options and option syntax. |
464 |
|
465 |
The other chapters are meant to be used as a reference. Each chapter |
466 |
presents everything that needs to be said about a specific topic. |
467 |
|
468 |
One of the chapters (@pxref{Date input formats}) exists in its |
469 |
entirety in other @acronym{GNU} manuals, and is mostly self-contained. |
470 |
In addition, one section of this manual (@pxref{Standard}) contains a |
471 |
big quote which is taken directly from @command{tar} sources. |
472 |
|
473 |
In general, we give both long and short (abbreviated) option names |
474 |
at least once in each section where the relevant option is covered, so |
475 |
that novice readers will become familiar with both styles. (A few |
476 |
options have no short versions, and the relevant sections will |
477 |
indicate this.) |
478 |
|
479 |
@node Definitions |
480 |
@section Some Definitions |
481 |
|
482 |
@cindex archive |
483 |
@cindex tar archive |
484 |
The @command{tar} program is used to create and manipulate @command{tar} |
485 |
archives. An @dfn{archive} is a single file which contains the contents |
486 |
of many files, while still identifying the names of the files, their |
487 |
owner(s), and so forth. (In addition, archives record access |
488 |
permissions, user and group, size in bytes, and data modification time. |
489 |
Some archives also record the file names in each archived directory, as |
490 |
well as other file and directory information.) You can use @command{tar} |
491 |
to @dfn{create} a new archive in a specified directory. |
492 |
|
493 |
@cindex member |
494 |
@cindex archive member |
495 |
@cindex file name |
496 |
@cindex member name |
497 |
The files inside an archive are called @dfn{members}. Within this |
498 |
manual, we use the term @dfn{file} to refer only to files accessible in |
499 |
the normal ways (by @command{ls}, @command{cat}, and so forth), and the term |
500 |
@dfn{member} to refer only to the members of an archive. Similarly, a |
501 |
@dfn{file name} is the name of a file, as it resides in the file system, |
502 |
and a @dfn{member name} is the name of an archive member within the |
503 |
archive. |
504 |
|
505 |
@cindex extraction |
506 |
@cindex unpacking |
507 |
The term @dfn{extraction} refers to the process of copying an archive |
508 |
member (or multiple members) into a file in the file system. Extracting |
509 |
all the members of an archive is often called @dfn{extracting the |
510 |
archive}. The term @dfn{unpack} can also be used to refer to the |
511 |
extraction of many or all the members of an archive. Extracting an |
512 |
archive does not destroy the archive's structure, just as creating an |
513 |
archive does not destroy the copies of the files that exist outside of |
514 |
the archive. You may also @dfn{list} the members in a given archive |
515 |
(this is often thought of as ``printing'' them to the standard output, |
516 |
or the command line), or @dfn{append} members to a pre-existing archive. |
517 |
All of these operations can be performed using @command{tar}. |
518 |
|
519 |
@node What tar Does |
520 |
@section What @command{tar} Does |
521 |
|
522 |
@cindex tar |
523 |
The @command{tar} program provides the ability to create @command{tar} |
524 |
archives, as well as various other kinds of manipulation. For example, |
525 |
you can use @command{tar} on previously created archives to extract files, |
526 |
to store additional files, or to update or list files which were already |
527 |
stored. |
528 |
|
529 |
Initially, @command{tar} archives were used to store files conveniently on |
530 |
magnetic tape. The name @command{tar} comes from this use; it stands for |
531 |
@code{t}ape @code{ar}chiver. Despite the utility's name, @command{tar} can |
532 |
direct its output to available devices, files, or other programs (using |
533 |
pipes). @command{tar} may even access remote devices or files (as archives). |
534 |
|
535 |
You can use @command{tar} archives in many ways. We want to stress a few |
536 |
of them: storage, backup, and transportation. |
537 |
|
538 |
@FIXME{the following table entries need a bit of work.} |
539 |
@table @asis |
540 |
@item Storage |
541 |
Often, @command{tar} archives are used to store related files for |
542 |
convenient file transfer over a network. For example, the |
543 |
@acronym{GNU} Project distributes its software bundled into |
544 |
@command{tar} archives, so that all the files relating to a particular |
545 |
program (or set of related programs) can be transferred as a single |
546 |
unit. |
547 |
|
548 |
A magnetic tape can store several files in sequence. However, the tape |
549 |
has no names for these files; it only knows their relative position on |
550 |
the tape. One way to store several files on one tape and retain their |
551 |
names is by creating a @command{tar} archive. Even when the basic transfer |
552 |
mechanism can keep track of names, as FTP can, the nuisance of handling |
553 |
multiple files, directories, and multiple links makes @command{tar} |
554 |
archives useful. |
555 |
|
556 |
Archive files are also used for long-term storage. You can think of |
557 |
this as transportation from the present into the future. (It is a |
558 |
science-fiction idiom that you can move through time as well as in |
559 |
space; the idea here is that @command{tar} can be used to move archives in |
560 |
all dimensions, even time!) |
561 |
|
562 |
@item Backup |
563 |
Because the archive created by @command{tar} is capable of preserving |
564 |
file information and directory structure, @command{tar} is commonly |
565 |
used for performing full and incremental backups of disks. A backup |
566 |
puts a collection of files (possibly pertaining to many users and |
567 |
projects) together on a disk or a tape. This guards against |
568 |
accidental destruction of the information in those files. |
569 |
@GNUTAR{} has special features that allow it to be |
570 |
used to make incremental and full dumps of all the files in a |
571 |
file system. |
572 |
|
573 |
@item Transportation |
574 |
You can create an archive on one system, transfer it to another system, |
575 |
and extract the contents there. This allows you to transport a group of |
576 |
files from one system to another. |
577 |
@end table |
578 |
|
579 |
@node Naming tar Archives |
580 |
@section How @command{tar} Archives are Named |
581 |
|
582 |
Conventionally, @command{tar} archives are given names ending with |
583 |
@samp{.tar}. This is not necessary for @command{tar} to operate properly, |
584 |
but this manual follows that convention in order to accustom readers to |
585 |
it and to make examples more clear. |
586 |
|
587 |
@cindex tar file |
588 |
@cindex entry |
589 |
@cindex tar entry |
590 |
Often, people refer to @command{tar} archives as ``@command{tar} files,'' and |
591 |
archive members as ``files'' or ``entries''. For people familiar with |
592 |
the operation of @command{tar}, this causes no difficulty. However, in |
593 |
this manual, we consistently refer to ``archives'' and ``archive |
594 |
members'' to make learning to use @command{tar} easier for novice users. |
595 |
|
596 |
@node Authors |
597 |
@section @GNUTAR{} Authors |
598 |
|
599 |
@GNUTAR{} was originally written by John Gilmore, |
600 |
and modified by many people. The @acronym{GNU} enhancements were |
601 |
written by Jay Fenlason, then Joy Kendall, and the whole package has |
602 |
been further maintained by Thomas Bushnell, n/BSG, Fran@,{c}ois |
603 |
Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of |
604 |
numerous and kind users. |
605 |
|
606 |
We wish to stress that @command{tar} is a collective work, and owes much to |
607 |
all those people who reported problems, offered solutions and other |
608 |
insights, or shared their thoughts and suggestions. An impressive, yet |
609 |
partial list of those contributors can be found in the @file{THANKS} |
610 |
file from the @GNUTAR{} distribution. |
611 |
|
612 |
@FIXME{i want all of these names mentioned, Absolutely. BUT, i'm not |
613 |
sure i want to spell out the history in this detail, at least not for |
614 |
the printed book. i'm just not sure it needs to be said this way. |
615 |
i'll think about it.} |
616 |
|
617 |
@FIXME{History is more important, and surely more interesting, than |
618 |
actual names. Quoting names without history would be meaningless. FP} |
619 |
|
620 |
Jay Fenlason put together a draft of a @GNUTAR{} |
621 |
manual, borrowing notes from the original man page from John Gilmore. |
622 |
This was withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy |
623 |
Gorin worked on a tutorial and manual for @GNUTAR{}. |
624 |
Fran@,{c}ois Pinard put version 1.11.8 of the manual together by |
625 |
taking information from all these sources and merging them. Melissa |
626 |
Weisshaus finally edited and redesigned the book to create version |
627 |
1.12. The book for versions from 1.14 up to @value{VERSION} were edited |
628 |
by the current maintainer, Sergey Poznyakoff. |
629 |
|
630 |
For version 1.12, Daniel Hagerty contributed a great deal of technical |
631 |
consulting. In particular, he is the primary author of @ref{Backups}. |
632 |
|
633 |
In July, 2003 @GNUTAR{} was put on CVS at savannah.gnu.org |
634 |
(see @url{http://savannah.gnu.org/projects/tar}), and |
635 |
active development and maintenance work has started |
636 |
again. Currently @GNUTAR{} is being maintained by Paul Eggert, Sergey |
637 |
Poznyakoff and Jeff Bailey. |
638 |
|
639 |
Support for @acronym{POSIX} archives was added by Sergey Poznyakoff. |
640 |
|
641 |
@node Reports |
642 |
@section Reporting bugs or suggestions |
643 |
|
644 |
@cindex bug reports |
645 |
@cindex reporting bugs |
646 |
If you find problems or have suggestions about this program or manual, |
647 |
please report them to @file{bug-tar@@gnu.org}. |
648 |
|
649 |
When reporting a bug, please be sure to include as much detail as |
650 |
possible, in order to reproduce it. @FIXME{Be more specific, I'd |
651 |
like to make this node as detailed as 'Bug reporting' node in Emacs |
652 |
manual.} |
653 |
|
654 |
@node Tutorial |
655 |
@chapter Tutorial Introduction to @command{tar} |
656 |
|
657 |
This chapter guides you through some basic examples of three @command{tar} |
658 |
operations: @option{--create}, @option{--list}, and @option{--extract}. If |
659 |
you already know how to use some other version of @command{tar}, then you |
660 |
may not need to read this chapter. This chapter omits most complicated |
661 |
details about how @command{tar} works. |
662 |
|
663 |
@menu |
664 |
* assumptions:: |
665 |
* stylistic conventions:: |
666 |
* basic tar options:: Basic @command{tar} Operations and Options |
667 |
* frequent operations:: |
668 |
* Two Frequent Options:: |
669 |
* create:: How to Create Archives |
670 |
* list:: How to List Archives |
671 |
* extract:: How to Extract Members from an Archive |
672 |
* going further:: |
673 |
@end menu |
674 |
|
675 |
@node assumptions |
676 |
@section Assumptions this Tutorial Makes |
677 |
|
678 |
This chapter is paced to allow beginners to learn about @command{tar} |
679 |
slowly. At the same time, we will try to cover all the basic aspects of |
680 |
these three operations. In order to accomplish both of these tasks, we |
681 |
have made certain assumptions about your knowledge before reading this |
682 |
manual, and the hardware you will be using: |
683 |
|
684 |
@itemize @bullet |
685 |
@item |
686 |
Before you start to work through this tutorial, you should understand |
687 |
what the terms ``archive'' and ``archive member'' mean |
688 |
(@pxref{Definitions}). In addition, you should understand something |
689 |
about how Unix-type operating systems work, and you should know how to |
690 |
use some basic utilities. For example, you should know how to create, |
691 |
list, copy, rename, edit, and delete files and directories; how to |
692 |
change between directories; and how to figure out where you are in the |
693 |
file system. You should have some basic understanding of directory |
694 |
structure and how files are named according to which directory they are |
695 |
in. You should understand concepts such as standard output and standard |
696 |
input, what various definitions of the term @samp{argument} mean, and the |
697 |
differences between relative and absolute file names. @FIXME{and what |
698 |
else?} |
699 |
|
700 |
@item |
701 |
This manual assumes that you are working from your own home directory |
702 |
(unless we state otherwise). In this tutorial, you will create a |
703 |
directory to practice @command{tar} commands in. When we show file names, |
704 |
we will assume that those names are relative to your home directory. |
705 |
For example, my home directory is @file{/home/fsf/melissa}. All of |
706 |
my examples are in a subdirectory of the directory named by that file |
707 |
name; the subdirectory is called @file{practice}. |
708 |
|
709 |
@item |
710 |
In general, we show examples of archives which exist on (or can be |
711 |
written to, or worked with from) a directory on a hard disk. In most |
712 |
cases, you could write those archives to, or work with them on any other |
713 |
device, such as a tape drive. However, some of the later examples in |
714 |
the tutorial and next chapter will not work on tape drives. |
715 |
Additionally, working with tapes is much more complicated than working |
716 |
with hard disks. For these reasons, the tutorial does not cover working |
717 |
with tape drives. @xref{Media}, for complete information on using |
718 |
@command{tar} archives with tape drives. |
719 |
|
720 |
@FIXME{this is a cop out. need to add some simple tape drive info.} |
721 |
@end itemize |
722 |
|
723 |
@node stylistic conventions |
724 |
@section Stylistic Conventions |
725 |
|
726 |
In the examples, @samp{$} represents a typical shell prompt. It |
727 |
precedes lines you should type; to make this more clear, those lines are |
728 |
shown in @kbd{this font}, as opposed to lines which represent the |
729 |
computer's response; those lines are shown in @code{this font}, or |
730 |
sometimes @samp{like this}. |
731 |
|
732 |
@c When we have lines which are too long to be |
733 |
@c displayed in any other way, we will show them like this: |
734 |
|
735 |
@node basic tar options |
736 |
@section Basic @command{tar} Operations and Options |
737 |
|
738 |
@command{tar} can take a wide variety of arguments which specify and define |
739 |
the actions it will have on the particular set of files or the archive. |
740 |
The main types of arguments to @command{tar} fall into one of two classes: |
741 |
operations, and options. |
742 |
|
743 |
Some arguments fall into a class called @dfn{operations}; exactly one of |
744 |
these is both allowed and required for any instance of using @command{tar}; |
745 |
you may @emph{not} specify more than one. People sometimes speak of |
746 |
@dfn{operating modes}. You are in a particular operating mode when you |
747 |
have specified the operation which specifies it; there are eight |
748 |
operations in total, and thus there are eight operating modes. |
749 |
|
750 |
The other arguments fall into the class known as @dfn{options}. You are |
751 |
not required to specify any options, and you are allowed to specify more |
752 |
than one at a time (depending on the way you are using @command{tar} at |
753 |
that time). Some options are used so frequently, and are so useful for |
754 |
helping you type commands more carefully that they are effectively |
755 |
``required''. We will discuss them in this chapter. |
756 |
|
757 |
You can write most of the @command{tar} operations and options in any |
758 |
of three forms: long (mnemonic) form, short form, and old style. Some |
759 |
of the operations and options have no short or ``old'' forms; however, |
760 |
the operations and options which we will cover in this tutorial have |
761 |
corresponding abbreviations. We will indicate those abbreviations |
762 |
appropriately to get you used to seeing them. Note, that the ``old |
763 |
style'' option forms exist in @GNUTAR{} for compatibility with Unix |
764 |
@command{tar}. In this book we present a full discussion of this way |
765 |
of writing options and operations (@pxref{Old Options}), and we discuss |
766 |
the other two styles of writing options (@xref{Long Options}, and |
767 |
@pxref{Short Options}). |
768 |
|
769 |
In the examples and in the text of this tutorial, we usually use the |
770 |
long forms of operations and options; but the ``short'' forms produce |
771 |
the same result and can make typing long @command{tar} commands easier. |
772 |
For example, instead of typing |
773 |
|
774 |
@smallexample |
775 |
@kbd{tar --create --verbose --file=afiles.tar apple angst aspic} |
776 |
@end smallexample |
777 |
|
778 |
@noindent |
779 |
you can type |
780 |
@smallexample |
781 |
@kbd{tar -c -v -f afiles.tar apple angst aspic} |
782 |
@end smallexample |
783 |
|
784 |
@noindent |
785 |
or even |
786 |
@smallexample |
787 |
@kbd{tar -cvf afiles.tar apple angst aspic} |
788 |
@end smallexample |
789 |
|
790 |
@noindent |
791 |
For more information on option syntax, see @ref{Advanced tar}. In |
792 |
discussions in the text, when we name an option by its long form, we |
793 |
also give the corresponding short option in parentheses. |
794 |
|
795 |
The term, ``option'', can be confusing at times, since ``operations'' |
796 |
are often lumped in with the actual, @emph{optional} ``options'' in certain |
797 |
general class statements. For example, we just talked about ``short and |
798 |
long forms of options and operations''. However, experienced @command{tar} |
799 |
users often refer to these by shorthand terms such as, ``short and long |
800 |
options''. This term assumes that the ``operations'' are included, also. |
801 |
Context will help you determine which definition of ``options'' to use. |
802 |
|
803 |
Similarly, the term ``command'' can be confusing, as it is often used in |
804 |
two different ways. People sometimes refer to @command{tar} ``commands''. |
805 |
A @command{tar} @dfn{command} is the entire command line of user input |
806 |
which tells @command{tar} what to do --- including the operation, options, |
807 |
and any arguments (file names, pipes, other commands, etc.). However, |
808 |
you will also sometimes hear the term ``the @command{tar} command''. When |
809 |
the word ``command'' is used specifically like this, a person is usually |
810 |
referring to the @command{tar} @emph{operation}, not the whole line. |
811 |
Again, use context to figure out which of the meanings the speaker |
812 |
intends. |
813 |
|
814 |
@node frequent operations |
815 |
@section The Three Most Frequently Used Operations |
816 |
|
817 |
Here are the three most frequently used operations (both short and long |
818 |
forms), as well as a brief description of their meanings. The rest of |
819 |
this chapter will cover how to use these operations in detail. We will |
820 |
present the rest of the operations in the next chapter. |
821 |
|
822 |
@table @option |
823 |
@item --create |
824 |
@itemx -c |
825 |
Create a new @command{tar} archive. |
826 |
@item --list |
827 |
@itemx -t |
828 |
List the contents of an archive. |
829 |
@item --extract |
830 |
@itemx -x |
831 |
Extract one or more members from an archive. |
832 |
@end table |
833 |
|
834 |
@node Two Frequent Options |
835 |
@section Two Frequently Used Options |
836 |
|
837 |
To understand how to run @command{tar} in the three operating modes listed |
838 |
previously, you also need to understand how to use two of the options to |
839 |
@command{tar}: @option{--file} (which takes an archive file as an argument) |
840 |
and @option{--verbose}. (You are usually not @emph{required} to specify |
841 |
either of these options when you run @command{tar}, but they can be very |
842 |
useful in making things more clear and helping you avoid errors.) |
843 |
|
844 |
@menu |
845 |
* file tutorial:: |
846 |
* verbose tutorial:: |
847 |
* help tutorial:: |
848 |
@end menu |
849 |
|
850 |
@node file tutorial |
851 |
@unnumberedsubsec The @option{--file} Option |
852 |
|
853 |
@table @option |
854 |
@xopindex{file, tutorial} |
855 |
@item --file=@var{archive-name} |
856 |
@itemx -f @var{archive-name} |
857 |
Specify the name of an archive file. |
858 |
@end table |
859 |
|
860 |
You can specify an argument for the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option whenever you |
861 |
use @command{tar}; this option determines the name of the archive file |
862 |
that @command{tar} will work on. |
863 |
|
864 |
@vrindex TAPE |
865 |
If you don't specify this argument, then @command{tar} will examine |
866 |
the environment variable @env{TAPE}. If it is set, its value will be |
867 |
used as the archive name. Otherwise, @command{tar} will use the |
868 |
default archive, determined at compile time. Usually it is |
869 |
standard output or some physical tape drive attached to your machine |
870 |
(you can verify what the default is by running @kbd{tar |
871 |
--show-defaults}, @pxref{defaults}). If there is no tape drive |
872 |
attached, or the default is not meaningful, then @command{tar} will |
873 |
print an error message. The error message might look roughly like one |
874 |
of the following: |
875 |
|
876 |
@smallexample |
877 |
tar: can't open /dev/rmt8 : No such device or address |
878 |
tar: can't open /dev/rsmt0 : I/O error |
879 |
@end smallexample |
880 |
|
881 |
@noindent |
882 |
To avoid confusion, we recommend that you always specify an archive file |
883 |
name by using @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) when writing your @command{tar} commands. |
884 |
For more information on using the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option, see |
885 |
@ref{file}. |
886 |
|
887 |
@node verbose tutorial |
888 |
@unnumberedsubsec The @option{--verbose} Option |
889 |
|
890 |
@table @option |
891 |
@xopindex{verbose, introduced} |
892 |
@item --verbose |
893 |
@itemx -v |
894 |
Show the files being worked on as @command{tar} is running. |
895 |
@end table |
896 |
|
897 |
@option{--verbose} (@option{-v}) shows details about the results of running |
898 |
@command{tar}. This can be especially useful when the results might not be |
899 |
obvious. For example, if you want to see the progress of @command{tar} as |
900 |
it writes files into the archive, you can use the @option{--verbose} |
901 |
option. In the beginning, you may find it useful to use |
902 |
@option{--verbose} at all times; when you are more accustomed to |
903 |
@command{tar}, you will likely want to use it at certain times but not at |
904 |
others. We will use @option{--verbose} at times to help make something |
905 |
clear, and we will give many examples both using and not using |
906 |
@option{--verbose} to show the differences. |
907 |
|
908 |
Each instance of @option{--verbose} on the command line increases the |
909 |
verbosity level by one, so if you need more details on the output, |
910 |
specify it twice. |
911 |
|
912 |
When reading archives (@option{--list}, @option{--extract}, |
913 |
@option{--diff}), @command{tar} by default prints only the names of |
914 |
the members being extracted. Using @option{--verbose} will show a full, |
915 |
@command{ls} style member listing. |
916 |
|
917 |
In contrast, when writing archives (@option{--create}, @option{--append}, |
918 |
@option{--update}), @command{tar} does not print file names by |
919 |
default. So, a single @option{--verbose} option shows the file names |
920 |
being added to the archive, while two @option{--verbose} options |
921 |
enable the full listing. |
922 |
|
923 |
For example, to create an archive in verbose mode: |
924 |
|
925 |
@smallexample |
926 |
$ @kbd{tar -cvf afiles.tar apple angst aspic} |
927 |
apple |
928 |
angst |
929 |
aspic |
930 |
@end smallexample |
931 |
|
932 |
@noindent |
933 |
Creating the same archive with the verbosity level 2 could give: |
934 |
|
935 |
@smallexample |
936 |
$ @kbd{tar -cvvf afiles.tar apple angst aspic} |
937 |
-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple |
938 |
-rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst |
939 |
-rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic |
940 |
@end smallexample |
941 |
|
942 |
@noindent |
943 |
This works equally well using short or long forms of options. Using |
944 |
long forms, you would simply write out the mnemonic form of the option |
945 |
twice, like this: |
946 |
|
947 |
@smallexample |
948 |
$ @kbd{tar --create --verbose --verbose @dots{}} |
949 |
@end smallexample |
950 |
|
951 |
@noindent |
952 |
Note that you must double the hyphens properly each time. |
953 |
|
954 |
Later in the tutorial, we will give examples using @w{@option{--verbose |
955 |
--verbose}}. |
956 |
|
957 |
@anchor{verbose member listing} |
958 |
The full output consists of six fields: |
959 |
|
960 |
@itemize @bullet |
961 |
@item File type and permissions in symbolic form. |
962 |
These are displayed in the same format as the first column of |
963 |
@command{ls -l} output (@pxref{What information is listed, |
964 |
format=verbose, Verbose listing, fileutils, GNU file utilities}). |
965 |
|
966 |
@item Owner name and group separated by a slash character. |
967 |
If these data are not available (for example, when listing a @samp{v7} format |
968 |
archive), numeric @acronym{ID} values are printed instead. |
969 |
|
970 |
@item Size of the file, in bytes. |
971 |
|
972 |
@item File modification date in ISO 8601 format. |
973 |
|
974 |
@item File modification time. |
975 |
|
976 |
@item File name. |
977 |
If the name contains any special characters (white space, newlines, |
978 |
etc.) these are displayed in an unambiguous form using so called |
979 |
@dfn{quoting style}. For the detailed discussion of available styles |
980 |
and on how to use them, see @ref{quoting styles}. |
981 |
|
982 |
Depending on the file type, the name can be followed by some |
983 |
additional information, described in the following table: |
984 |
|
985 |
@table @samp |
986 |
@item -> @var{link-name} |
987 |
The file or archive member is a @dfn{symbolic link} and |
988 |
@var{link-name} is the name of file it links to. |
989 |
|
990 |
@item link to @var{link-name} |
991 |
The file or archive member is a @dfn{hard link} and @var{link-name} is |
992 |
the name of file it links to. |
993 |
|
994 |
@item --Long Link-- |
995 |
The archive member is an old GNU format long link. You will normally |
996 |
not encounter this. |
997 |
|
998 |
@item --Long Name-- |
999 |
The archive member is an old GNU format long name. You will normally |
1000 |
not encounter this. |
1001 |
|
1002 |
@item --Volume Header-- |
1003 |
The archive member is a GNU @dfn{volume header} (@pxref{Tape Files}). |
1004 |
|
1005 |
@item --Continued at byte @var{n}-- |
1006 |
Encountered only at the beginning of a multi-volume archive |
1007 |
(@pxref{Using Multiple Tapes}). This archive member is a continuation |
1008 |
from the previous volume. The number @var{n} gives the offset where |
1009 |
the original file was split. |
1010 |
|
1011 |
@item unknown file type @var{c} |
1012 |
An archive member of unknown type. @var{c} is the type character from |
1013 |
the archive header. If you encounter such a message, it means that |
1014 |
either your archive contains proprietary member types @GNUTAR{} is not |
1015 |
able to handle, or the archive is corrupted. |
1016 |
@end table |
1017 |
|
1018 |
@end itemize |
1019 |
|
1020 |
For example, here is an archive listing containing most of the special |
1021 |
suffixes explained above: |
1022 |
|
1023 |
@smallexample |
1024 |
@group |
1025 |
V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header-- |
1026 |
-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456-- |
1027 |
-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple |
1028 |
lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple |
1029 |
-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues |
1030 |
hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues |
1031 |
@end group |
1032 |
@end smallexample |
1033 |
|
1034 |
@smallexample |
1035 |
@end smallexample |
1036 |
|
1037 |
@node help tutorial |
1038 |
@unnumberedsubsec Getting Help: Using the @option{--help} Option |
1039 |
|
1040 |
@table @option |
1041 |
@opindex help |
1042 |
@item --help |
1043 |
|
1044 |
The @option{--help} option to @command{tar} prints out a very brief list of |
1045 |
all operations and option available for the current version of |
1046 |
@command{tar} available on your system. |
1047 |
@end table |
1048 |
|
1049 |
@node create |
1050 |
@section How to Create Archives |
1051 |
@UNREVISED |
1052 |
|
1053 |
@cindex Creation of the archive |
1054 |
@cindex Archive, creation of |
1055 |
One of the basic operations of @command{tar} is @option{--create} (@option{-c}), which |
1056 |
you use to create a @command{tar} archive. We will explain |
1057 |
@option{--create} first because, in order to learn about the other |
1058 |
operations, you will find it useful to have an archive available to |
1059 |
practice on. |
1060 |
|
1061 |
To make this easier, in this section you will first create a directory |
1062 |
containing three files. Then, we will show you how to create an |
1063 |
@emph{archive} (inside the new directory). Both the directory, and |
1064 |
the archive are specifically for you to practice on. The rest of this |
1065 |
chapter and the next chapter will show many examples using this |
1066 |
directory and the files you will create: some of those files may be |
1067 |
other directories and other archives. |
1068 |
|
1069 |
The three files you will archive in this example are called |
1070 |
@file{blues}, @file{folk}, and @file{jazz}. The archive is called |
1071 |
@file{collection.tar}. |
1072 |
|
1073 |
This section will proceed slowly, detailing how to use @option{--create} |
1074 |
in @code{verbose} mode, and showing examples using both short and long |
1075 |
forms. In the rest of the tutorial, and in the examples in the next |
1076 |
chapter, we will proceed at a slightly quicker pace. This section |
1077 |
moves more slowly to allow beginning users to understand how |
1078 |
@command{tar} works. |
1079 |
|
1080 |
@menu |
1081 |
* prepare for examples:: |
1082 |
* Creating the archive:: |
1083 |
* create verbose:: |
1084 |
* short create:: |
1085 |
* create dir:: |
1086 |
@end menu |
1087 |
|
1088 |
@node prepare for examples |
1089 |
@subsection Preparing a Practice Directory for Examples |
1090 |
|
1091 |
To follow along with this and future examples, create a new directory |
1092 |
called @file{practice} containing files called @file{blues}, @file{folk} |
1093 |
and @file{jazz}. The files can contain any information you like: |
1094 |
ideally, they should contain information which relates to their names, |
1095 |
and be of different lengths. Our examples assume that @file{practice} |
1096 |
is a subdirectory of your home directory. |
1097 |
|
1098 |
Now @command{cd} to the directory named @file{practice}; @file{practice} |
1099 |
is now your @dfn{working directory}. (@emph{Please note}: Although |
1100 |
the full file name of this directory is |
1101 |
@file{/@var{homedir}/practice}, in our examples we will refer to |
1102 |
this directory as @file{practice}; the @var{homedir} is presumed.) |
1103 |
|
1104 |
In general, you should check that the files to be archived exist where |
1105 |
you think they do (in the working directory) by running @command{ls}. |
1106 |
Because you just created the directory and the files and have changed to |
1107 |
that directory, you probably don't need to do that this time. |
1108 |
|
1109 |
It is very important to make sure there isn't already a file in the |
1110 |
working directory with the archive name you intend to use (in this case, |
1111 |
@samp{collection.tar}), or that you don't care about its contents. |
1112 |
Whenever you use @samp{create}, @command{tar} will erase the current |
1113 |
contents of the file named by @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) if it exists. @command{tar} |
1114 |
will not tell you if you are about to overwrite an archive unless you |
1115 |
specify an option which does this (@pxref{backup}, for the |
1116 |
information on how to do so). To add files to an existing archive, |
1117 |
you need to use a different option, such as @option{--append} (@option{-r}); see |
1118 |
@ref{append} for information on how to do this. |
1119 |
|
1120 |
@node Creating the archive |
1121 |
@subsection Creating the Archive |
1122 |
|
1123 |
@xopindex{create, introduced} |
1124 |
To place the files @file{blues}, @file{folk}, and @file{jazz} into an |
1125 |
archive named @file{collection.tar}, use the following command: |
1126 |
|
1127 |
@smallexample |
1128 |
$ @kbd{tar --create --file=collection.tar blues folk jazz} |
1129 |
@end smallexample |
1130 |
|
1131 |
The order of the arguments is not very important, @emph{when using long |
1132 |
option forms}. You could also say: |
1133 |
|
1134 |
@smallexample |
1135 |
$ @kbd{tar blues --create folk --file=collection.tar jazz} |
1136 |
@end smallexample |
1137 |
|
1138 |
@noindent |
1139 |
However, you can see that this order is harder to understand; this is |
1140 |
why we will list the arguments in the order that makes the commands |
1141 |
easiest to understand (and we encourage you to do the same when you use |
1142 |
@command{tar}, to avoid errors). |
1143 |
|
1144 |
Note that the sequence |
1145 |
@option{--file=@-collection.tar} is considered to be @emph{one} argument. |
1146 |
If you substituted any other string of characters for |
1147 |
@kbd{collection.tar}, then that string would become the name of the |
1148 |
archive file you create. |
1149 |
|
1150 |
The order of the options becomes more important when you begin to use |
1151 |
short forms. With short forms, if you type commands in the wrong order |
1152 |
(even if you type them correctly in all other ways), you may end up with |
1153 |
results you don't expect. For this reason, it is a good idea to get |
1154 |
into the habit of typing options in the order that makes inherent sense. |
1155 |
@xref{short create}, for more information on this. |
1156 |
|
1157 |
In this example, you type the command as shown above: @option{--create} |
1158 |
is the operation which creates the new archive |
1159 |
(@file{collection.tar}), and @option{--file} is the option which lets |
1160 |
you give it the name you chose. The files, @file{blues}, @file{folk}, |
1161 |
and @file{jazz}, are now members of the archive, @file{collection.tar} |
1162 |
(they are @dfn{file name arguments} to the @option{--create} operation. |
1163 |
@xref{Choosing}, for the detailed discussion on these.) Now that they are |
1164 |
in the archive, they are called @emph{archive members}, not files. |
1165 |
(@pxref{Definitions,members}). |
1166 |
|
1167 |
When you create an archive, you @emph{must} specify which files you |
1168 |
want placed in the archive. If you do not specify any archive |
1169 |
members, @GNUTAR{} will complain. |
1170 |
|
1171 |
If you now list the contents of the working directory (@command{ls}), you will |
1172 |
find the archive file listed as well as the files you saw previously: |
1173 |
|
1174 |
@smallexample |
1175 |
blues folk jazz collection.tar |
1176 |
@end smallexample |
1177 |
|
1178 |
@noindent |
1179 |
Creating the archive @samp{collection.tar} did not destroy the copies of |
1180 |
the files in the directory. |
1181 |
|
1182 |
Keep in mind that if you don't indicate an operation, @command{tar} will not |
1183 |
run and will prompt you for one. If you don't name any files, @command{tar} |
1184 |
will complain. You must have write access to the working directory, |
1185 |
or else you will not be able to create an archive in that directory. |
1186 |
|
1187 |
@emph{Caution}: Do not attempt to use @option{--create} (@option{-c}) to add files to |
1188 |
an existing archive; it will delete the archive and write a new one. |
1189 |
Use @option{--append} (@option{-r}) instead. @xref{append}. |
1190 |
|
1191 |
@node create verbose |
1192 |
@subsection Running @option{--create} with @option{--verbose} |
1193 |
|
1194 |
@xopindex{create, using with @option{--verbose}} |
1195 |
@xopindex{verbose, using with @option{--create}} |
1196 |
If you include the @option{--verbose} (@option{-v}) option on the command line, |
1197 |
@command{tar} will list the files it is acting on as it is working. In |
1198 |
verbose mode, the @code{create} example above would appear as: |
1199 |
|
1200 |
@smallexample |
1201 |
$ @kbd{tar --create --verbose --file=collection.tar blues folk jazz} |
1202 |
blues |
1203 |
folk |
1204 |
jazz |
1205 |
@end smallexample |
1206 |
|
1207 |
This example is just like the example we showed which did not use |
1208 |
@option{--verbose}, except that @command{tar} generated the remaining |
1209 |
@iftex |
1210 |
lines (note the different font styles). |
1211 |
@end iftex |
1212 |
@ifinfo |
1213 |
lines. |
1214 |
@end ifinfo |
1215 |
|
1216 |
In the rest of the examples in this chapter, we will frequently use |
1217 |
@code{verbose} mode so we can show actions or @command{tar} responses that |
1218 |
you would otherwise not see, and which are important for you to |
1219 |
understand. |
1220 |
|
1221 |
@node short create |
1222 |
@subsection Short Forms with @samp{create} |
1223 |
|
1224 |
As we said before, the @option{--create} (@option{-c}) operation is one of the most |
1225 |
basic uses of @command{tar}, and you will use it countless times. |
1226 |
Eventually, you will probably want to use abbreviated (or ``short'') |
1227 |
forms of options. A full discussion of the three different forms that |
1228 |
options can take appears in @ref{Styles}; for now, here is what the |
1229 |
previous example (including the @option{--verbose} (@option{-v}) option) looks like |
1230 |
using short option forms: |
1231 |
|
1232 |
@smallexample |
1233 |
$ @kbd{tar -cvf collection.tar blues folk jazz} |
1234 |
blues |
1235 |
folk |
1236 |
jazz |
1237 |
@end smallexample |
1238 |
|
1239 |
@noindent |
1240 |
As you can see, the system responds the same no matter whether you use |
1241 |
long or short option forms. |
1242 |
|
1243 |
@FIXME{i don't like how this is worded:} One difference between using |
1244 |
short and long option forms is that, although the exact placement of |
1245 |
arguments following options is no more specific when using short forms, |
1246 |
it is easier to become confused and make a mistake when using short |
1247 |
forms. For example, suppose you attempted the above example in the |
1248 |
following way: |
1249 |
|
1250 |
@smallexample |
1251 |
$ @kbd{tar -cfv collection.tar blues folk jazz} |
1252 |
@end smallexample |
1253 |
|
1254 |
@noindent |
1255 |
In this case, @command{tar} will make an archive file called @file{v}, |
1256 |
containing the files @file{blues}, @file{folk}, and @file{jazz}, because |
1257 |
the @samp{v} is the closest ``file name'' to the @option{-f} option, and |
1258 |
is thus taken to be the chosen archive file name. @command{tar} will try |
1259 |
to add a file called @file{collection.tar} to the @file{v} archive file; |
1260 |
if the file @file{collection.tar} did not already exist, @command{tar} will |
1261 |
report an error indicating that this file does not exist. If the file |
1262 |
@file{collection.tar} does already exist (e.g., from a previous command |
1263 |
you may have run), then @command{tar} will add this file to the archive. |
1264 |
Because the @option{-v} option did not get registered, @command{tar} will not |
1265 |
run under @samp{verbose} mode, and will not report its progress. |
1266 |
|
1267 |
The end result is that you may be quite confused about what happened, |
1268 |
and possibly overwrite a file. To illustrate this further, we will show |
1269 |
you how an example we showed previously would look using short forms. |
1270 |
|
1271 |
This example, |
1272 |
|
1273 |
@smallexample |
1274 |
$ @kbd{tar blues --create folk --file=collection.tar jazz} |
1275 |
@end smallexample |
1276 |
|
1277 |
@noindent |
1278 |
is confusing as it is. When shown using short forms, however, it |
1279 |
becomes much more so: |
1280 |
|
1281 |
@smallexample |
1282 |
$ @kbd{tar blues -c folk -f collection.tar jazz} |
1283 |
@end smallexample |
1284 |
|
1285 |
@noindent |
1286 |
It would be very easy to put the wrong string of characters |
1287 |
immediately following the @option{-f}, but doing that could sacrifice |
1288 |
valuable data. |
1289 |
|
1290 |
For this reason, we recommend that you pay very careful attention to |
1291 |
the order of options and placement of file and archive names, |
1292 |
especially when using short option forms. Not having the option name |
1293 |
written out mnemonically can affect how well you remember which option |
1294 |
does what, and therefore where different names have to be placed. |
1295 |
|
1296 |
@node create dir |
1297 |
@subsection Archiving Directories |
1298 |
|
1299 |
@cindex Archiving Directories |
1300 |
@cindex Directories, Archiving |
1301 |
You can archive a directory by specifying its directory name as a |
1302 |
file name argument to @command{tar}. The files in the directory will be |
1303 |
archived relative to the working directory, and the directory will be |
1304 |
re-created along with its contents when the archive is extracted. |
1305 |
|
1306 |
To archive a directory, first move to its superior directory. If you |
1307 |
have followed the previous instructions in this tutorial, you should |
1308 |
type: |
1309 |
|
1310 |
@smallexample |
1311 |
$ @kbd{cd ..} |
1312 |
$ |
1313 |
@end smallexample |
1314 |
|
1315 |
@noindent |
1316 |
This will put you into the directory which contains @file{practice}, |
1317 |
i.e., your home directory. Once in the superior directory, you can |
1318 |
specify the subdirectory, @file{practice}, as a file name argument. To |
1319 |
store @file{practice} in the new archive file @file{music.tar}, type: |
1320 |
|
1321 |
@smallexample |
1322 |
$ @kbd{tar --create --verbose --file=music.tar practice} |
1323 |
@end smallexample |
1324 |
|
1325 |
@noindent |
1326 |
@command{tar} should output: |
1327 |
|
1328 |
@smallexample |
1329 |
practice/ |
1330 |
practice/blues |
1331 |
practice/folk |
1332 |
practice/jazz |
1333 |
practice/collection.tar |
1334 |
@end smallexample |
1335 |
|
1336 |
Note that the archive thus created is not in the subdirectory |
1337 |
@file{practice}, but rather in the current working directory---the |
1338 |
directory from which @command{tar} was invoked. Before trying to archive a |
1339 |
directory from its superior directory, you should make sure you have |
1340 |
write access to the superior directory itself, not only the directory |
1341 |
you are trying archive with @command{tar}. For example, you will probably |
1342 |
not be able to store your home directory in an archive by invoking |
1343 |
@command{tar} from the root directory; @xref{absolute}. (Note |
1344 |
also that @file{collection.tar}, the original archive file, has itself |
1345 |
been archived. @command{tar} will accept any file as a file to be |
1346 |
archived, regardless of its content. When @file{music.tar} is |
1347 |
extracted, the archive file @file{collection.tar} will be re-written |
1348 |
into the file system). |
1349 |
|
1350 |
If you give @command{tar} a command such as |
1351 |
|
1352 |
@smallexample |
1353 |
$ @kbd{tar --create --file=foo.tar .} |
1354 |
@end smallexample |
1355 |
|
1356 |
@noindent |
1357 |
@command{tar} will report @samp{tar: ./foo.tar is the archive; not |
1358 |
dumped}. This happens because @command{tar} creates the archive |
1359 |
@file{foo.tar} in the current directory before putting any files into |
1360 |
it. Then, when @command{tar} attempts to add all the files in the |
1361 |
directory @file{.} to the archive, it notices that the file |
1362 |
@file{./foo.tar} is the same as the archive @file{foo.tar}, and skips |
1363 |
it. (It makes no sense to put an archive into itself.) @GNUTAR{} |
1364 |
will continue in this case, and create the archive |
1365 |
normally, except for the exclusion of that one file. (@emph{Please |
1366 |
note:} Other implementations of @command{tar} may not be so clever; |
1367 |
they will enter an infinite loop when this happens, so you should not |
1368 |
depend on this behavior unless you are certain you are running |
1369 |
@GNUTAR{}. In general, it is wise to always place the archive outside |
1370 |
of the directory being dumped.) |
1371 |
|
1372 |
@node list |
1373 |
@section How to List Archives |
1374 |
|
1375 |
@opindex list |
1376 |
Frequently, you will find yourself wanting to determine exactly what a |
1377 |
particular archive contains. You can use the @option{--list} |
1378 |
(@option{-t}) operation to get the member names as they currently |
1379 |
appear in the archive, as well as various attributes of the files at |
1380 |
the time they were archived. For example, you can examine the archive |
1381 |
@file{collection.tar} that you created in the last section with the |
1382 |
command, |
1383 |
|
1384 |
@smallexample |
1385 |
$ @kbd{tar --list --file=collection.tar} |
1386 |
@end smallexample |
1387 |
|
1388 |
@noindent |
1389 |
The output of @command{tar} would then be: |
1390 |
|
1391 |
@smallexample |
1392 |
blues |
1393 |
folk |
1394 |
jazz |
1395 |
@end smallexample |
1396 |
|
1397 |
@noindent |
1398 |
The archive @file{bfiles.tar} would list as follows: |
1399 |
|
1400 |
@smallexample |
1401 |
./birds |
1402 |
baboon |
1403 |
./box |
1404 |
@end smallexample |
1405 |
|
1406 |
@noindent |
1407 |
Be sure to use a @option{--file=@var{archive-name}} (@option{-f |
1408 |
@var{archive-name}}) option just as with @option{--create} |
1409 |
(@option{-c}) to specify the name of the archive. |
1410 |
|
1411 |
@xopindex{list, using with @option{--verbose}} |
1412 |
@xopindex{verbose, using with @option{--list}} |
1413 |
If you use the @option{--verbose} (@option{-v}) option with |
1414 |
@option{--list}, then @command{tar} will print out a listing |
1415 |
reminiscent of @w{@samp{ls -l}}, showing owner, file size, and so |
1416 |
forth. This output is described in detail in @ref{verbose member listing}. |
1417 |
|
1418 |
If you had used @option{--verbose} (@option{-v}) mode, the example |
1419 |
above would look like: |
1420 |
|
1421 |
@smallexample |
1422 |
$ @kbd{tar --list --verbose --file=collection.tar folk} |
1423 |
-rw-r--r-- myself/user 62 1990-05-23 10:55 folk |
1424 |
@end smallexample |
1425 |
|
1426 |
@cindex listing member and file names |
1427 |
@anchor{listing member and file names} |
1428 |
It is important to notice that the output of @kbd{tar --list |
1429 |
--verbose} does not necessarily match that produced by @kbd{tar |
1430 |
--create --verbose} while creating the archive. It is because |
1431 |
@GNUTAR{}, unless told explicitly not to do so, removes some directory |
1432 |
prefixes from file names before storing them in the archive |
1433 |
(@xref{absolute}, for more information). In other |
1434 |
words, in verbose mode @GNUTAR{} shows @dfn{file names} when creating |
1435 |
an archive and @dfn{member names} when listing it. Consider this |
1436 |
example: |
1437 |
|
1438 |
@smallexample |
1439 |
@group |
1440 |
$ @kbd{tar --create --verbose --file archive /etc/mail} |
1441 |
tar: Removing leading `/' from member names |
1442 |
/etc/mail/ |
1443 |
/etc/mail/sendmail.cf |
1444 |
/etc/mail/aliases |
1445 |
$ @kbd{tar --test --file archive} |
1446 |
etc/mail/ |
1447 |
etc/mail/sendmail.cf |
1448 |
etc/mail/aliases |
1449 |
@end group |
1450 |
@end smallexample |
1451 |
|
1452 |
@opindex show-stored-names |
1453 |
This default behavior can sometimes be inconvenient. You can force |
1454 |
@GNUTAR{} show member names when creating archive by supplying |
1455 |
@option{--show-stored-names} option. |
1456 |
|
1457 |
@table @option |
1458 |
@item --show-stored-names |
1459 |
Print member (as opposed to @emph{file}) names when creating the archive. |
1460 |
@end table |
1461 |
|
1462 |
@cindex File name arguments, using @option{--list} with |
1463 |
@xopindex{list, using with file name arguments} |
1464 |
You can specify one or more individual member names as arguments when |
1465 |
using @samp{list}. In this case, @command{tar} will only list the |
1466 |
names of members you identify. For example, @w{@kbd{tar --list |
1467 |
--file=afiles.tar apple}} would only print @file{apple}. |
1468 |
|
1469 |
Because @command{tar} preserves file names, these must be specified as |
1470 |
they appear in the archive (i.e., relative to the directory from which |
1471 |
the archive was created). Therefore, it is essential when specifying |
1472 |
member names to @command{tar} that you give the exact member names. |
1473 |
For example, @w{@kbd{tar --list --file=bfiles.tar birds}} would produce an |
1474 |
error message something like @samp{tar: birds: Not found in archive}, |
1475 |
because there is no member named @file{birds}, only one named |
1476 |
@file{./birds}. While the names @file{birds} and @file{./birds} name |
1477 |
the same file, @emph{member} names by default are compared verbatim. |
1478 |
|
1479 |
However, @w{@kbd{tar --list --file=bfiles.tar baboon}} would respond |
1480 |
with @file{baboon}, because this exact member name is in the archive file |
1481 |
@file{bfiles.tar}. If you are not sure of the exact file name, |
1482 |
use @dfn{globbing patterns}, for example: |
1483 |
|
1484 |
@smallexample |
1485 |
$ @kbd{tar --list --file=bfiles.tar --wildcards '*b*'} |
1486 |
@end smallexample |
1487 |
|
1488 |
@noindent |
1489 |
will list all members whose name contains @samp{b}. @xref{wildcards}, |
1490 |
for a detailed discussion of globbing patterns and related |
1491 |
@command{tar} command line options. |
1492 |
|
1493 |
@menu |
1494 |
* list dir:: |
1495 |
@end menu |
1496 |
|
1497 |
@node list dir |
1498 |
@unnumberedsubsec Listing the Contents of a Stored Directory |
1499 |
|
1500 |
To get information about the contents of an archived directory, |
1501 |
use the directory name as a file name argument in conjunction with |
1502 |
@option{--list} (@option{-t}). To find out file attributes, include the |
1503 |
@option{--verbose} (@option{-v}) option. |
1504 |
|
1505 |
For example, to find out about files in the directory @file{practice}, in |
1506 |
the archive file @file{music.tar}, type: |
1507 |
|
1508 |
@smallexample |
1509 |
$ @kbd{tar --list --verbose --file=music.tar practice} |
1510 |
@end smallexample |
1511 |
|
1512 |
@command{tar} responds: |
1513 |
|
1514 |
@smallexample |
1515 |
drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/ |
1516 |
-rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues |
1517 |
-rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk |
1518 |
-rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz |
1519 |
-rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar |
1520 |
@end smallexample |
1521 |
|
1522 |
When you use a directory name as a file name argument, @command{tar} acts on |
1523 |
all the files (including sub-directories) in that directory. |
1524 |
|
1525 |
@node extract |
1526 |
@section How to Extract Members from an Archive |
1527 |
@cindex Extraction |
1528 |
@cindex Retrieving files from an archive |
1529 |
@cindex Resurrecting files from an archive |
1530 |
|
1531 |
@opindex extract |
1532 |
Creating an archive is only half the job---there is no point in storing |
1533 |
files in an archive if you can't retrieve them. The act of retrieving |
1534 |
members from an archive so they can be used and manipulated as |
1535 |
unarchived files again is called @dfn{extraction}. To extract files |
1536 |
from an archive, use the @option{--extract} (@option{--get} or |
1537 |
@option{-x}) operation. As with @option{--create}, specify the name |
1538 |
of the archive with @option{--file} (@option{-f}) option. Extracting |
1539 |
an archive does not modify the archive in any way; you can extract it |
1540 |
multiple times if you want or need to. |
1541 |
|
1542 |
Using @option{--extract}, you can extract an entire archive, or specific |
1543 |
files. The files can be directories containing other files, or not. As |
1544 |
with @option{--create} (@option{-c}) and @option{--list} (@option{-t}), you may use the short or the |
1545 |
long form of the operation without affecting the performance. |
1546 |
|
1547 |
@menu |
1548 |
* extracting archives:: |
1549 |
* extracting files:: |
1550 |
* extract dir:: |
1551 |
* extracting untrusted archives:: |
1552 |
* failing commands:: |
1553 |
@end menu |
1554 |
|
1555 |
@node extracting archives |
1556 |
@subsection Extracting an Entire Archive |
1557 |
|
1558 |
To extract an entire archive, specify the archive file name only, with |
1559 |
no individual file names as arguments. For example, |
1560 |
|
1561 |
@smallexample |
1562 |
$ @kbd{tar -xvf collection.tar} |
1563 |
@end smallexample |
1564 |
|
1565 |
@noindent |
1566 |
produces this: |
1567 |
|
1568 |
@smallexample |
1569 |
-rw-r--r-- me/user 28 1996-10-18 16:31 jazz |
1570 |
-rw-r--r-- me/user 21 1996-09-23 16:44 blues |
1571 |
-rw-r--r-- me/user 20 1996-09-23 16:44 folk |
1572 |
@end smallexample |
1573 |
|
1574 |
@node extracting files |
1575 |
@subsection Extracting Specific Files |
1576 |
|
1577 |
To extract specific archive members, give their exact member names as |
1578 |
arguments, as printed by @option{--list} (@option{-t}). If you had |
1579 |
mistakenly deleted one of the files you had placed in the archive |
1580 |
@file{collection.tar} earlier (say, @file{blues}), you can extract it |
1581 |
from the archive without changing the archive's structure. Its |
1582 |
contents will be identical to the original file @file{blues} that you |
1583 |
deleted. |
1584 |
|
1585 |
First, make sure you are in the @file{practice} directory, and list the |
1586 |
files in the directory. Now, delete the file, @samp{blues}, and list |
1587 |
the files in the directory again. |
1588 |
|
1589 |
You can now extract the member @file{blues} from the archive file |
1590 |
@file{collection.tar} like this: |
1591 |
|
1592 |
@smallexample |
1593 |
$ @kbd{tar --extract --file=collection.tar blues} |
1594 |
@end smallexample |
1595 |
|
1596 |
@noindent |
1597 |
If you list the files in the directory again, you will see that the file |
1598 |
@file{blues} has been restored, with its original permissions, data |
1599 |
modification times, and owner.@footnote{This is only accidentally |
1600 |
true, but not in general. Whereas modification times are always |
1601 |
restored, in most cases, one has to be root for restoring the owner, |
1602 |
and use a special option for restoring permissions. Here, it just |
1603 |
happens that the restoring user is also the owner of the archived |
1604 |
members, and that the current @code{umask} is compatible with original |
1605 |
permissions.} (These parameters will be identical to those which |
1606 |
the file had when you originally placed it in the archive; any changes |
1607 |
you may have made before deleting the file from the file system, |
1608 |
however, will @emph{not} have been made to the archive member.) The |
1609 |
archive file, @samp{collection.tar}, is the same as it was before you |
1610 |
extracted @samp{blues}. You can confirm this by running @command{tar} with |
1611 |
@option{--list} (@option{-t}). |
1612 |
|
1613 |
Remember that as with other operations, specifying the exact member |
1614 |
name is important. @w{@kbd{tar --extract --file=bfiles.tar birds}} |
1615 |
will fail, because there is no member named @file{birds}. To extract |
1616 |
the member named @file{./birds}, you must specify @w{@kbd{tar |
1617 |
--extract --file=bfiles.tar ./birds}}. If you don't remember the |
1618 |
exact member names, use @option{--list} (@option{-t}) option |
1619 |
(@pxref{list}). You can also extract those members that match a |
1620 |
specific @dfn{globbing pattern}. For example, to extract from |
1621 |
@file{bfiles.tar} all files that begin with @samp{b}, no matter their |
1622 |
directory prefix, you could type: |
1623 |
|
1624 |
@smallexample |
1625 |
$ @kbd{tar -x -f bfiles.tar --wildcards --no-anchored 'b*'} |
1626 |
@end smallexample |
1627 |
|
1628 |
@noindent |
1629 |
Here, @option{--wildcards} instructs @command{tar} to treat |
1630 |
command line arguments as globbing patterns and @option{--no-anchored} |
1631 |
informs it that the patterns apply to member names after any @samp{/} |
1632 |
delimiter. The use of globbing patterns is discussed in detail in |
1633 |
@xref{wildcards}. |
1634 |
|
1635 |
You can extract a file to standard output by combining the above options |
1636 |
with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard |
1637 |
Output}). |
1638 |
|
1639 |
If you give the @option{--verbose} option, then @option{--extract} |
1640 |
will print the names of the archive members as it extracts them. |
1641 |
|
1642 |
@node extract dir |
1643 |
@subsection Extracting Files that are Directories |
1644 |
|
1645 |
Extracting directories which are members of an archive is similar to |
1646 |
extracting other files. The main difference to be aware of is that if |
1647 |
the extracted directory has the same name as any directory already in |
1648 |
the working directory, then files in the extracted directory will be |
1649 |
placed into the directory of the same name. Likewise, if there are |
1650 |
files in the pre-existing directory with the same names as the members |
1651 |
which you extract, the files from the extracted archive will replace |
1652 |
the files already in the working directory (and possible |
1653 |
subdirectories). This will happen regardless of whether or not the |
1654 |
files in the working directory were more recent than those extracted |
1655 |
(there exist, however, special options that alter this behavior |
1656 |
@pxref{Writing}). |
1657 |
|
1658 |
However, if a file was stored with a directory name as part of its file |
1659 |
name, and that directory does not exist under the working directory when |
1660 |
the file is extracted, @command{tar} will create the directory. |
1661 |
|
1662 |
We can demonstrate how to use @option{--extract} to extract a directory |
1663 |
file with an example. Change to the @file{practice} directory if you |
1664 |
weren't there, and remove the files @file{folk} and @file{jazz}. Then, |
1665 |
go back to the parent directory and extract the archive |
1666 |
@file{music.tar}. You may either extract the entire archive, or you may |
1667 |
extract only the files you just deleted. To extract the entire archive, |
1668 |
don't give any file names as arguments after the archive name |
1669 |
@file{music.tar}. To extract only the files you deleted, use the |
1670 |
following command: |
1671 |
|
1672 |
@smallexample |
1673 |
$ @kbd{tar -xvf music.tar practice/folk practice/jazz} |
1674 |
practice/folk |
1675 |
practice/jazz |
1676 |
@end smallexample |
1677 |
|
1678 |
@noindent |
1679 |
If you were to specify two @option{--verbose} (@option{-v}) options, @command{tar} |
1680 |
would have displayed more detail about the extracted files, as shown |
1681 |
in the example below: |
1682 |
|
1683 |
@smallexample |
1684 |
$ @kbd{tar -xvvf music.tar practice/folk practice/jazz} |
1685 |
-rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz |
1686 |
-rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk |
1687 |
@end smallexample |
1688 |
|
1689 |
@noindent |
1690 |
Because you created the directory with @file{practice} as part of the |
1691 |
file names of each of the files by archiving the @file{practice} |
1692 |
directory as @file{practice}, you must give @file{practice} as part |
1693 |
of the file names when you extract those files from the archive. |
1694 |
|
1695 |
@node extracting untrusted archives |
1696 |
@subsection Extracting Archives from Untrusted Sources |
1697 |
|
1698 |
Extracting files from archives can overwrite files that already exist. |
1699 |
If you receive an archive from an untrusted source, you should make a |
1700 |
new directory and extract into that directory, so that you don't have |
1701 |
to worry about the extraction overwriting one of your existing files. |
1702 |
For example, if @file{untrusted.tar} came from somewhere else on the |
1703 |
Internet, and you don't necessarily trust its contents, you can |
1704 |
extract it as follows: |
1705 |
|
1706 |
@smallexample |
1707 |
$ @kbd{mkdir newdir} |
1708 |
$ @kbd{cd newdir} |
1709 |
$ @kbd{tar -xvf ../untrusted.tar} |
1710 |
@end smallexample |
1711 |
|
1712 |
It is also a good practice to examine contents of the archive |
1713 |
before extracting it, using @option{--list} (@option{-t}) option, possibly combined |
1714 |
with @option{--verbose} (@option{-v}). |
1715 |
|
1716 |
@node failing commands |
1717 |
@subsection Commands That Will Fail |
1718 |
|
1719 |
Here are some sample commands you might try which will not work, and why |
1720 |
they won't work. |
1721 |
|
1722 |
If you try to use this command, |
1723 |
|
1724 |
@smallexample |
1725 |
$ @kbd{tar -xvf music.tar folk jazz} |
1726 |
@end smallexample |
1727 |
|
1728 |
@noindent |
1729 |
you will get the following response: |
1730 |
|
1731 |
@smallexample |
1732 |
tar: folk: Not found in archive |
1733 |
tar: jazz: Not found in archive |
1734 |
@end smallexample |
1735 |
|
1736 |
@noindent |
1737 |
This is because these files were not originally @emph{in} the parent |
1738 |
directory @file{..}, where the archive is located; they were in the |
1739 |
@file{practice} directory, and their file names reflect this: |
1740 |
|
1741 |
@smallexample |
1742 |
$ @kbd{tar -tvf music.tar} |
1743 |
practice/blues |
1744 |
practice/folk |
1745 |
practice/jazz |
1746 |
@end smallexample |
1747 |
|
1748 |
@FIXME{make sure the above works when going through the examples in |
1749 |
order...} |
1750 |
|
1751 |
@noindent |
1752 |
Likewise, if you try to use this command, |
1753 |
|
1754 |
@smallexample |
1755 |
$ @kbd{tar -tvf music.tar folk jazz} |
1756 |
@end smallexample |
1757 |
|
1758 |
@noindent |
1759 |
you would get a similar response. Members with those names are not in the |
1760 |
archive. You must use the correct member names, or wildcards, in order |
1761 |
to extract the files from the archive. |
1762 |
|
1763 |
If you have forgotten the correct names of the files in the archive, |
1764 |
use @w{@kbd{tar --list --verbose}} to list them correctly. |
1765 |
|
1766 |
@FIXME{more examples, here? hag thinks it's a good idea.} |
1767 |
|
1768 |
@node going further |
1769 |
@section Going Further Ahead in this Manual |
1770 |
@UNREVISED |
1771 |
|
1772 |
@FIXME{need to write up a node here about the things that are going to |
1773 |
be in the rest of the manual.} |
1774 |
|
1775 |
@node tar invocation |
1776 |
@chapter Invoking @GNUTAR{} |
1777 |
|
1778 |
This chapter is about how one invokes the @GNUTAR{} |
1779 |
command, from the command synopsis (@pxref{Synopsis}). There are |
1780 |
numerous options, and many styles for writing them. One mandatory |
1781 |
option specifies the operation @command{tar} should perform |
1782 |
(@pxref{Operation Summary}), other options are meant to detail how |
1783 |
this operation should be performed (@pxref{Option Summary}). |
1784 |
Non-option arguments are not always interpreted the same way, |
1785 |
depending on what the operation is. |
1786 |
|
1787 |
You will find in this chapter everything about option styles and rules for |
1788 |
writing them (@pxref{Styles}). On the other hand, operations and options |
1789 |
are fully described elsewhere, in other chapters. Here, you will find |
1790 |
only synthetic descriptions for operations and options, together with |
1791 |
pointers to other parts of the @command{tar} manual. |
1792 |
|
1793 |
Some options are so special they are fully described right in this |
1794 |
chapter. They have the effect of inhibiting the normal operation of |
1795 |
@command{tar} or else, they globally alter the amount of feedback the user |
1796 |
receives about what is going on. These are the @option{--help} and |
1797 |
@option{--version} (@pxref{help}), @option{--verbose} (@pxref{verbose}) |
1798 |
and @option{--interactive} options (@pxref{interactive}). |
1799 |
|
1800 |
@menu |
1801 |
* Synopsis:: |
1802 |
* using tar options:: |
1803 |
* Styles:: |
1804 |
* All Options:: |
1805 |
* help:: |
1806 |
* defaults:: |
1807 |
* verbose:: |
1808 |
* checkpoints:: |
1809 |
* warnings:: |
1810 |
* interactive:: |
1811 |
@end menu |
1812 |
|
1813 |
@node Synopsis |
1814 |
@section General Synopsis of @command{tar} |
1815 |
|
1816 |
The @GNUTAR{} program is invoked as either one of: |
1817 |
|
1818 |
@smallexample |
1819 |
@kbd{tar @var{option}@dots{} [@var{name}]@dots{}} |
1820 |
@kbd{tar @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}} |
1821 |
@end smallexample |
1822 |
|
1823 |
The second form is for when old options are being used. |
1824 |
|
1825 |
You can use @command{tar} to store files in an archive, to extract them from |
1826 |
an archive, and to do other types of archive manipulation. The primary |
1827 |
argument to @command{tar}, which is called the @dfn{operation}, specifies |
1828 |
which action to take. The other arguments to @command{tar} are either |
1829 |
@dfn{options}, which change the way @command{tar} performs an operation, |
1830 |
or file names or archive members, which specify the files or members |
1831 |
@command{tar} is to act on. |
1832 |
|
1833 |
You can actually type in arguments in any order, even if in this manual |
1834 |
the options always precede the other arguments, to make examples easier |
1835 |
to understand. Further, the option stating the main operation mode |
1836 |
(the @command{tar} main command) is usually given first. |
1837 |
|
1838 |
Each @var{name} in the synopsis above is interpreted as an archive member |
1839 |
name when the main command is one of @option{--compare} |
1840 |
(@option{--diff}, @option{-d}), @option{--delete}, @option{--extract} |
1841 |
(@option{--get}, @option{-x}), @option{--list} (@option{-t}) or |
1842 |
@option{--update} (@option{-u}). When naming archive members, you |
1843 |
must give the exact name of the member in the archive, as it is |
1844 |
printed by @option{--list}. For @option{--append} (@option{-r}) and |
1845 |
@option{--create} (@option{-c}), these @var{name} arguments specify |
1846 |
the names of either files or directory hierarchies to place in the archive. |
1847 |
These files or hierarchies should already exist in the file system, |
1848 |
prior to the execution of the @command{tar} command. |
1849 |
|
1850 |
@command{tar} interprets relative file names as being relative to the |
1851 |
working directory. @command{tar} will make all file names relative |
1852 |
(by removing leading slashes when archiving or restoring files), |
1853 |
unless you specify otherwise (using the @option{--absolute-names} |
1854 |
option). @xref{absolute}, for more information about |
1855 |
@option{--absolute-names}. |
1856 |
|
1857 |
If you give the name of a directory as either a file name or a member |
1858 |
name, then @command{tar} acts recursively on all the files and directories |
1859 |
beneath that directory. For example, the name @file{/} identifies all |
1860 |
the files in the file system to @command{tar}. |
1861 |
|
1862 |
The distinction between file names and archive member names is especially |
1863 |
important when shell globbing is used, and sometimes a source of confusion |
1864 |
for newcomers. @xref{wildcards}, for more information about globbing. |
1865 |
The problem is that shells may only glob using existing files in the |
1866 |
file system. Only @command{tar} itself may glob on archive members, so when |
1867 |
needed, you must ensure that wildcard characters reach @command{tar} without |
1868 |
being interpreted by the shell first. Using a backslash before @samp{*} |
1869 |
or @samp{?}, or putting the whole argument between quotes, is usually |
1870 |
sufficient for this. |
1871 |
|
1872 |
Even if @var{name}s are often specified on the command line, they |
1873 |
can also be read from a text file in the file system, using the |
1874 |
@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) option. |
1875 |
|
1876 |
If you don't use any file name arguments, @option{--append} (@option{-r}), |
1877 |
@option{--delete} and @option{--concatenate} (@option{--catenate}, |
1878 |
@option{-A}) will do nothing, while @option{--create} (@option{-c}) |
1879 |
will usually yield a diagnostic and inhibit @command{tar} execution. |
1880 |
The other operations of @command{tar} (@option{--list}, |
1881 |
@option{--extract}, @option{--compare}, and @option{--update}) |
1882 |
will act on the entire contents of the archive. |
1883 |
|
1884 |
@cindex exit status |
1885 |
@cindex return status |
1886 |
Besides successful exits, @GNUTAR{} may fail for |
1887 |
many reasons. Some reasons correspond to bad usage, that is, when the |
1888 |
@command{tar} command line is improperly written. Errors may be |
1889 |
encountered later, while processing the archive or the files. Some |
1890 |
errors are recoverable, in which case the failure is delayed until |
1891 |
@command{tar} has completed all its work. Some errors are such that |
1892 |
it would be not meaningful, or at least risky, to continue processing: |
1893 |
@command{tar} then aborts processing immediately. All abnormal exits, |
1894 |
whether immediate or delayed, should always be clearly diagnosed on |
1895 |
@code{stderr}, after a line stating the nature of the error. |
1896 |
|
1897 |
Possible exit codes of @GNUTAR{} are summarized in the following |
1898 |
table: |
1899 |
|
1900 |
@table @asis |
1901 |
@item 0 |
1902 |
@samp{Successful termination}. |
1903 |
|
1904 |
@item 1 |
1905 |
@samp{Some files differ}. If tar was invoked with @option{--compare} |
1906 |
(@option{--diff}, @option{-d}) command line option, this means that |
1907 |
some files in the archive differ from their disk counterparts |
1908 |
(@pxref{compare}). If tar was given @option{--create}, |
1909 |
@option{--append} or @option{--update} option, this exit code means |
1910 |
that some files were changed while being archived and so the resulting |
1911 |
archive does not contain the exact copy of the file set. |
1912 |
|
1913 |
@item 2 |
1914 |
@samp{Fatal error}. This means that some fatal, unrecoverable error |
1915 |
occurred. |
1916 |
@end table |
1917 |
|
1918 |
If @command{tar} has invoked a subprocess and that subprocess exited with a |
1919 |
nonzero exit code, @command{tar} exits with that code as well. |
1920 |
This can happen, for example, if @command{tar} was given some |
1921 |
compression option (@pxref{gzip}) and the external compressor program |
1922 |
failed. Another example is @command{rmt} failure during backup to the |
1923 |
remote device (@pxref{Remote Tape Server}). |
1924 |
|
1925 |
@node using tar options |
1926 |
@section Using @command{tar} Options |
1927 |
|
1928 |
@GNUTAR{} has a total of eight operating modes which |
1929 |
allow you to perform a variety of tasks. You are required to choose |
1930 |
one operating mode each time you employ the @command{tar} program by |
1931 |
specifying one, and only one operation as an argument to the |
1932 |
@command{tar} command (the corresponding options may be found |
1933 |
at @ref{frequent operations} and @ref{Operations}). Depending on |
1934 |
circumstances, you may also wish to customize how the chosen operating |
1935 |
mode behaves. For example, you may wish to change the way the output |
1936 |
looks, or the format of the files that you wish to archive may require |
1937 |
you to do something special in order to make the archive look right. |
1938 |
|
1939 |
You can customize and control @command{tar}'s performance by running |
1940 |
@command{tar} with one or more options (such as @option{--verbose} |
1941 |
(@option{-v}), which we used in the tutorial). As we said in the |
1942 |
tutorial, @dfn{options} are arguments to @command{tar} which are (as |
1943 |
their name suggests) optional. Depending on the operating mode, you |
1944 |
may specify one or more options. Different options will have different |
1945 |
effects, but in general they all change details of the operation, such |
1946 |
as archive format, archive name, or level of user interaction. Some |
1947 |
options make sense with all operating modes, while others are |
1948 |
meaningful only with particular modes. You will likely use some |
1949 |
options frequently, while you will only use others infrequently, or |
1950 |
not at all. (A full list of options is available in @pxref{All Options}.) |
1951 |
|
1952 |
@vrindex TAR_OPTIONS, environment variable |
1953 |
@anchor{TAR_OPTIONS} |
1954 |
The @env{TAR_OPTIONS} environment variable specifies default options to |
1955 |
be placed in front of any explicit options. For example, if |
1956 |
@code{TAR_OPTIONS} is @samp{-v --unlink-first}, @command{tar} behaves as |
1957 |
if the two options @option{-v} and @option{--unlink-first} had been |
1958 |
specified before any explicit options. Option specifications are |
1959 |
separated by whitespace. A backslash escapes the next character, so it |
1960 |
can be used to specify an option containing whitespace or a backslash. |
1961 |
|
1962 |
Note that @command{tar} options are case sensitive. For example, the |
1963 |
options @option{-T} and @option{-t} are different; the first requires an |
1964 |
argument for stating the name of a file providing a list of @var{name}s, |
1965 |
while the second does not require an argument and is another way to |
1966 |
write @option{--list} (@option{-t}). |
1967 |
|
1968 |
In addition to the eight operations, there are many options to |
1969 |
@command{tar}, and three different styles for writing both: long (mnemonic) |
1970 |
form, short form, and old style. These styles are discussed below. |
1971 |
Both the options and the operations can be written in any of these three |
1972 |
styles. |
1973 |
|
1974 |
@FIXME{menu at end of this node. need to think of an actual outline |
1975 |
for this chapter; probably do that after stuff from chapter 4 is |
1976 |
incorporated.} |
1977 |
|
1978 |
@node Styles |
1979 |
@section The Three Option Styles |
1980 |
|
1981 |
There are three styles for writing operations and options to the command |
1982 |
line invoking @command{tar}. The different styles were developed at |
1983 |
different times during the history of @command{tar}. These styles will be |
1984 |
presented below, from the most recent to the oldest. |
1985 |
|
1986 |
Some options must take an argument@footnote{For example, @option{--file} |
1987 |
(@option{-f}) takes the name of an archive file as an argument. If |
1988 |
you do not supply an archive file name, @command{tar} will use a |
1989 |
default, but this can be confusing; thus, we recommend that you always |
1990 |
supply a specific archive file name.}. Where you @emph{place} the |
1991 |
arguments generally depends on which style of options you choose. We |
1992 |
will detail specific information relevant to each option style in the |
1993 |
sections on the different option styles, below. The differences are |
1994 |
subtle, yet can often be very important; incorrect option placement |
1995 |
can cause you to overwrite a number of important files. We urge you |
1996 |
to note these differences, and only use the option style(s) which |
1997 |
makes the most sense to you until you feel comfortable with the others. |
1998 |
|
1999 |
Some options @emph{may} take an argument. Such options may have at |
2000 |
most long and short forms, they do not have old style equivalent. The |
2001 |
rules for specifying an argument for such options are stricter than |
2002 |
those for specifying mandatory arguments. Please, pay special |
2003 |
attention to them. |
2004 |
|
2005 |
@menu |
2006 |
* Long Options:: Long Option Style |
2007 |
* Short Options:: Short Option Style |
2008 |
* Old Options:: Old Option Style |
2009 |
* Mixing:: Mixing Option Styles |
2010 |
@end menu |
2011 |
|
2012 |
@node Long Options |
2013 |
@subsection Long Option Style |
2014 |
|
2015 |
@cindex long options |
2016 |
@cindex options, long style |
2017 |
@cindex options, GNU style |
2018 |
@cindex options, mnemonic names |
2019 |
Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with two |
2020 |
dashes in a row, e.g., @option{--list}. The long names are more clear than |
2021 |
their corresponding short or old names. It sometimes happens that a |
2022 |
single long option has many different names which are |
2023 |
synonymous, such as @option{--compare} and @option{--diff}. In addition, |
2024 |
long option names can be given unique abbreviations. For example, |
2025 |
@option{--cre} can be used in place of @option{--create} because there is no |
2026 |
other long option which begins with @samp{cre}. (One way to find |
2027 |
this out is by trying it and seeing what happens; if a particular |
2028 |
abbreviation could represent more than one option, @command{tar} will tell |
2029 |
you that that abbreviation is ambiguous and you'll know that that |
2030 |
abbreviation won't work. You may also choose to run @samp{tar --help} |
2031 |
to see a list of options. Be aware that if you run @command{tar} with a |
2032 |
unique abbreviation for the long name of an option you didn't want to |
2033 |
use, you are stuck; @command{tar} will perform the command as ordered.) |
2034 |
|
2035 |
Long options are meant to be obvious and easy to remember, and their |
2036 |
meanings are generally easier to discern than those of their |
2037 |
corresponding short options (see below). For example: |
2038 |
|
2039 |
@smallexample |
2040 |
$ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0} |
2041 |
@end smallexample |
2042 |
|
2043 |
@noindent |
2044 |
gives a fairly good set of hints about what the command does, even |
2045 |
for those not fully acquainted with @command{tar}. |
2046 |
|
2047 |
@cindex arguments to long options |
2048 |
@cindex long options with mandatory arguments |
2049 |
Long options which require arguments take those arguments |
2050 |
immediately following the option name. There are two ways of |
2051 |
specifying a mandatory argument. It can be separated from the |
2052 |
option name either by an equal sign, or by any amount of |
2053 |
white space characters. For example, the @option{--file} option (which |
2054 |
tells the name of the @command{tar} archive) is given a file such as |
2055 |
@file{archive.tar} as argument by using any of the following notations: |
2056 |
@option{--file=archive.tar} or @option{--file archive.tar}. |
2057 |
|
2058 |
@cindex optional arguments to long options |
2059 |
@cindex long options with optional arguments |
2060 |
In contrast, optional arguments must always be introduced using |
2061 |
an equal sign. For example, the @option{--backup} option takes |
2062 |
an optional argument specifying backup type. It must be used |
2063 |
as @option{--backup=@var{backup-type}}. |
2064 |
|
2065 |
@node Short Options |
2066 |
@subsection Short Option Style |
2067 |
|
2068 |
@cindex short options |
2069 |
@cindex options, short style |
2070 |
@cindex options, traditional |
2071 |
Most options also have a @dfn{short option} name. Short options start with |
2072 |
a single dash, and are followed by a single character, e.g., @option{-t} |
2073 |
(which is equivalent to @option{--list}). The forms are absolutely |
2074 |
identical in function; they are interchangeable. |
2075 |
|
2076 |
The short option names are faster to type than long option names. |
2077 |
|
2078 |
@cindex arguments to short options |
2079 |
@cindex short options with mandatory arguments |
2080 |
Short options which require arguments take their arguments immediately |
2081 |
following the option, usually separated by white space. It is also |
2082 |
possible to stick the argument right after the short option name, using |
2083 |
no intervening space. For example, you might write @w{@option{-f |
2084 |
archive.tar}} or @option{-farchive.tar} instead of using |
2085 |
@option{--file=archive.tar}. Both @option{--file=@var{archive-name}} and |
2086 |
@w{@option{-f @var{archive-name}}} denote the option which indicates a |
2087 |
specific archive, here named @file{archive.tar}. |
2088 |
|
2089 |
@cindex optional arguments to short options |
2090 |
@cindex short options with optional arguments |
2091 |
Short options which take optional arguments take their arguments |
2092 |
immediately following the option letter, @emph{without any intervening |
2093 |
white space characters}. |
2094 |
|
2095 |
Short options' letters may be clumped together, but you are not |
2096 |
required to do this (as compared to old options; see below). When |
2097 |
short options are clumped as a set, use one (single) dash for them |
2098 |
all, e.g., @w{@samp{@command{tar} -cvf}}. Only the last option in |
2099 |
such a set is allowed to have an argument@footnote{Clustering many |
2100 |
options, the last of which has an argument, is a rather opaque way to |
2101 |
write options. Some wonder if @acronym{GNU} @code{getopt} should not |
2102 |
even be made helpful enough for considering such usages as invalid.}. |
2103 |
|
2104 |
When the options are separated, the argument for each option which requires |
2105 |
an argument directly follows that option, as is usual for Unix programs. |
2106 |
For example: |
2107 |
|
2108 |
@smallexample |
2109 |
$ @kbd{tar -c -v -b 20 -f /dev/rmt0} |
2110 |
@end smallexample |
2111 |
|
2112 |
If you reorder short options' locations, be sure to move any arguments |
2113 |
that belong to them. If you do not move the arguments properly, you may |
2114 |
end up overwriting files. |
2115 |
|
2116 |
@node Old Options |
2117 |
@subsection Old Option Style |
2118 |
@cindex options, old style |
2119 |
@cindex old option style |
2120 |
|
2121 |
Like short options, @dfn{old options} are single letters. However, old options |
2122 |
must be written together as a single clumped set, without spaces separating |
2123 |
them or dashes preceding them@footnote{Beware that if you precede options |
2124 |
with a dash, you are announcing the short option style instead of the |
2125 |
old option style; short options are decoded differently.}. This set |
2126 |
of letters must be the first to appear on the command line, after the |
2127 |
@command{tar} program name and some white space; old options cannot appear |
2128 |
anywhere else. The letter of an old option is exactly the same letter as |
2129 |
the corresponding short option. For example, the old option @samp{t} is |
2130 |
the same as the short option @option{-t}, and consequently, the same as the |
2131 |
long option @option{--list}. So for example, the command @w{@samp{tar |
2132 |
cv}} specifies the option @option{-v} in addition to the operation @option{-c}. |
2133 |
|
2134 |
@cindex arguments to old options |
2135 |
@cindex old options with mandatory arguments |
2136 |
When options that need arguments are given together with the command, |
2137 |
all the associated arguments follow, in the same order as the options. |
2138 |
Thus, the example given previously could also be written in the old |
2139 |
style as follows: |
2140 |
|
2141 |
@smallexample |
2142 |
$ @kbd{tar cvbf 20 /dev/rmt0} |
2143 |
@end smallexample |
2144 |
|
2145 |
@noindent |
2146 |
Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is |
2147 |
the argument of @option{-f}. |
2148 |
|
2149 |
On the other hand, this old style syntax makes it difficult to match |
2150 |
option letters with their corresponding arguments, and is often |
2151 |
confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example, |
2152 |
@samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the |
2153 |
argument for @option{-f}, and @option{-v} does not have a corresponding |
2154 |
argument. Even using short options like in @w{@samp{tar -c -v -b 20 -f |
2155 |
/dev/rmt0}} is clearer, putting all arguments next to the option they |
2156 |
pertain to. |
2157 |
|
2158 |
If you want to reorder the letters in the old option argument, be |
2159 |
sure to reorder any corresponding argument appropriately. |
2160 |
|
2161 |
This old way of writing @command{tar} options can surprise even experienced |
2162 |
users. For example, the two commands: |
2163 |
|
2164 |
@smallexample |
2165 |
@kbd{tar cfz archive.tar.gz file} |
2166 |
@kbd{tar -cfz archive.tar.gz file} |
2167 |
@end smallexample |
2168 |
|
2169 |
@noindent |
2170 |
are quite different. The first example uses @file{archive.tar.gz} as |
2171 |
the value for option @samp{f} and recognizes the option @samp{z}. The |
2172 |
second example, however, uses @file{z} as the value for option |
2173 |
@samp{f} --- probably not what was intended. |
2174 |
|
2175 |
Old options are kept for compatibility with old versions of @command{tar}. |
2176 |
|
2177 |
This second example could be corrected in many ways, among which the |
2178 |
following are equivalent: |
2179 |
|
2180 |
@smallexample |
2181 |
@kbd{tar -czf archive.tar.gz file} |
2182 |
@kbd{tar -cf archive.tar.gz -z file} |
2183 |
@kbd{tar cf archive.tar.gz -z file} |
2184 |
@end smallexample |
2185 |
|
2186 |
@cindex option syntax, traditional |
2187 |
As far as we know, all @command{tar} programs, @acronym{GNU} and |
2188 |
non-@acronym{GNU}, support old options. @GNUTAR{} |
2189 |
supports them not only for historical reasons, but also because many |
2190 |
people are used to them. For compatibility with Unix @command{tar}, |
2191 |
the first argument is always treated as containing command and option |
2192 |
letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is |
2193 |
equivalent to @w{@samp{tar -c}:} both of them specify the |
2194 |
@option{--create} (@option{-c}) command to create an archive. |
2195 |
|
2196 |
@node Mixing |
2197 |
@subsection Mixing Option Styles |
2198 |
|
2199 |
@cindex options, mixing different styles |
2200 |
All three styles may be intermixed in a single @command{tar} command, |
2201 |
so long as the rules for each style are fully |
2202 |
respected@footnote{Before @GNUTAR{} version 1.11.6, |
2203 |
a bug prevented intermixing old style options with long options in |
2204 |
some cases.}. Old style options and either of the modern styles of |
2205 |
options may be mixed within a single @command{tar} command. However, |
2206 |
old style options must be introduced as the first arguments only, |
2207 |
following the rule for old options (old options must appear directly |
2208 |
after the @command{tar} command and some white space). Modern options |
2209 |
may be given only after all arguments to the old options have been |
2210 |
collected. If this rule is not respected, a modern option might be |
2211 |
falsely interpreted as the value of the argument to one of the old |
2212 |
style options. |
2213 |
|
2214 |
For example, all the following commands are wholly equivalent, and |
2215 |
illustrate the many combinations and orderings of option styles. |
2216 |
|
2217 |
@smallexample |
2218 |
@kbd{tar --create --file=archive.tar} |
2219 |
@kbd{tar --create -f archive.tar} |
2220 |
@kbd{tar --create -farchive.tar} |
2221 |
@kbd{tar --file=archive.tar --create} |
2222 |
@kbd{tar --file=archive.tar -c} |
2223 |
@kbd{tar -c --file=archive.tar} |
2224 |
@kbd{tar -c -f archive.tar} |
2225 |
@kbd{tar -c -farchive.tar} |
2226 |
@kbd{tar -cf archive.tar} |
2227 |
@kbd{tar -cfarchive.tar} |
2228 |
@kbd{tar -f archive.tar --create} |
2229 |
@kbd{tar -f archive.tar -c} |
2230 |
@kbd{tar -farchive.tar --create} |
2231 |
@kbd{tar -farchive.tar -c} |
2232 |
@kbd{tar c --file=archive.tar} |
2233 |
@kbd{tar c -f archive.tar} |
2234 |
@kbd{tar c -farchive.tar} |
2235 |
@kbd{tar cf archive.tar} |
2236 |
@kbd{tar f archive.tar --create} |
2237 |
@kbd{tar f archive.tar -c} |
2238 |
@kbd{tar fc archive.tar} |
2239 |
@end smallexample |
2240 |
|
2241 |
On the other hand, the following commands are @emph{not} equivalent to |
2242 |
the previous set: |
2243 |
|
2244 |
@smallexample |
2245 |
@kbd{tar -f -c archive.tar} |
2246 |
@kbd{tar -fc archive.tar} |
2247 |
@kbd{tar -fcarchive.tar} |
2248 |
@kbd{tar -farchive.tarc} |
2249 |
@kbd{tar cfarchive.tar} |
2250 |
@end smallexample |
2251 |
|
2252 |
@noindent |
2253 |
These last examples mean something completely different from what the |
2254 |
user intended (judging based on the example in the previous set which |
2255 |
uses long options, whose intent is therefore very clear). The first |
2256 |
four specify that the @command{tar} archive would be a file named |
2257 |
@option{-c}, @samp{c}, @samp{carchive.tar} or @samp{archive.tarc}, |
2258 |
respectively. The first two examples also specify a single non-option, |
2259 |
@var{name} argument having the value @samp{archive.tar}. The last |
2260 |
example contains only old style option letters (repeating option |
2261 |
@samp{c} twice), not all of which are meaningful (eg., @samp{.}, |
2262 |
@samp{h}, or @samp{i}), with no argument value. @FIXME{not sure i liked |
2263 |
the first sentence of this paragraph..} |
2264 |
|
2265 |
@node All Options |
2266 |
@section All @command{tar} Options |
2267 |
|
2268 |
The coming manual sections contain an alphabetical listing of all |
2269 |
@command{tar} operations and options, with brief descriptions and |
2270 |
cross-references to more in-depth explanations in the body of the manual. |
2271 |
They also contain an alphabetically arranged table of the short option |
2272 |
forms with their corresponding long option. You can use this table as |
2273 |
a reference for deciphering @command{tar} commands in scripts. |
2274 |
|
2275 |
@menu |
2276 |
* Operation Summary:: |
2277 |
* Option Summary:: |
2278 |
* Short Option Summary:: |
2279 |
@end menu |
2280 |
|
2281 |
@node Operation Summary |
2282 |
@subsection Operations |
2283 |
|
2284 |
@table @option |
2285 |
|
2286 |
@opsummary{append} |
2287 |
@item --append |
2288 |
@itemx -r |
2289 |
|
2290 |
Appends files to the end of the archive. @xref{append}. |
2291 |
|
2292 |
@opsummary{catenate} |
2293 |
@item --catenate |
2294 |
@itemx -A |
2295 |
|
2296 |
Same as @option{--concatenate}. @xref{concatenate}. |
2297 |
|
2298 |
@opsummary{compare} |
2299 |
@item --compare |
2300 |
@itemx -d |
2301 |
|
2302 |
Compares archive members with their counterparts in the file |
2303 |
system, and reports differences in file size, mode, owner, |
2304 |
modification date and contents. @xref{compare}. |
2305 |
|
2306 |
@opsummary{concatenate} |
2307 |
@item --concatenate |
2308 |
@itemx -A |
2309 |
|
2310 |
Appends other @command{tar} archives to the end of the archive. |
2311 |
@xref{concatenate}. |
2312 |
|
2313 |
@opsummary{create} |
2314 |
@item --create |
2315 |
@itemx -c |
2316 |
|
2317 |
Creates a new @command{tar} archive. @xref{create}. |
2318 |
|
2319 |
@opsummary{delete} |
2320 |
@item --delete |
2321 |
|
2322 |
Deletes members from the archive. Don't try this on an archive on a |
2323 |
tape! @xref{delete}. |
2324 |
|
2325 |
@opsummary{diff} |
2326 |
@item --diff |
2327 |
@itemx -d |
2328 |
|
2329 |
Same @option{--compare}. @xref{compare}. |
2330 |
|
2331 |
@opsummary{extract} |
2332 |
@item --extract |
2333 |
@itemx -x |
2334 |
|
2335 |
Extracts members from the archive into the file system. @xref{extract}. |
2336 |
|
2337 |
@opsummary{get} |
2338 |
@item --get |
2339 |
@itemx -x |
2340 |
|
2341 |
Same as @option{--extract}. @xref{extract}. |
2342 |
|
2343 |
@opsummary{list} |
2344 |
@item --list |
2345 |
@itemx -t |
2346 |
|
2347 |
Lists the members in an archive. @xref{list}. |
2348 |
|
2349 |
@opsummary{update} |
2350 |
@item --update |
2351 |
@itemx -u |
2352 |
|
2353 |
Adds files to the end of the archive, but only if they are newer than |
2354 |
their counterparts already in the archive, or if they do not already |
2355 |
exist in the archive. @xref{update}. |
2356 |
|
2357 |
@end table |
2358 |
|
2359 |
@node Option Summary |
2360 |
@subsection @command{tar} Options |
2361 |
|
2362 |
@table @option |
2363 |
|
2364 |
@opsummary{absolute-names} |
2365 |
@item --absolute-names |
2366 |
@itemx -P |
2367 |
|
2368 |
Normally when creating an archive, @command{tar} strips an initial |
2369 |
@samp{/} from member names. This option disables that behavior. |
2370 |
@xref{absolute}. |
2371 |
|
2372 |
@opsummary{after-date} |
2373 |
@item --after-date |
2374 |
|
2375 |
(See @option{--newer}, @pxref{after}) |
2376 |
|
2377 |
@opsummary{anchored} |
2378 |
@item --anchored |
2379 |
A pattern must match an initial subsequence of the name's components. |
2380 |
@xref{controlling pattern-matching}. |
2381 |
|
2382 |
@opsummary{atime-preserve} |
2383 |
@item --atime-preserve |
2384 |
@itemx --atime-preserve=replace |
2385 |
@itemx --atime-preserve=system |
2386 |
|
2387 |
Attempt to preserve the access time of files when reading them. This |
2388 |
option currently is effective only on files that you own, unless you |
2389 |
have superuser privileges. |
2390 |
|
2391 |
@option{--atime-preserve=replace} remembers the access time of a file |
2392 |
before reading it, and then restores the access time afterwards. This |
2393 |
may cause problems if other programs are reading the file at the same |
2394 |
time, as the times of their accesses will be lost. On most platforms |
2395 |
restoring the access time also requires @command{tar} to restore the |
2396 |
data modification time too, so this option may also cause problems if |
2397 |
other programs are writing the file at the same time (@command{tar} attempts |
2398 |
to detect this situation, but cannot do so reliably due to race |
2399 |
conditions). Worse, on most platforms restoring the access time also |
2400 |
updates the status change time, which means that this option is |
2401 |
incompatible with incremental backups. |
2402 |
|
2403 |
@option{--atime-preserve=system} avoids changing time stamps on files, |
2404 |
without interfering with time stamp updates |
2405 |
caused by other programs, so it works better with incremental backups. |
2406 |
However, it requires a special @code{O_NOATIME} option from the |
2407 |
underlying operating and file system implementation, and it also requires |
2408 |
that searching directories does not update their access times. As of |
2409 |
this writing (November 2005) this works only with Linux, and only with |
2410 |
Linux kernels 2.6.8 and later. Worse, there is currently no reliable |
2411 |
way to know whether this feature actually works. Sometimes |
2412 |
@command{tar} knows that it does not work, and if you use |
2413 |
@option{--atime-preserve=system} then @command{tar} complains and |
2414 |
exits right away. But other times @command{tar} might think that the |
2415 |
option works when it actually does not. |
2416 |
|
2417 |
Currently @option{--atime-preserve} with no operand defaults to |
2418 |
@option{--atime-preserve=replace}, but this may change in the future |
2419 |
as support for @option{--atime-preserve=system} improves. |
2420 |
|
2421 |
If your operating or file system does not support |
2422 |
@option{--atime-preserve=@-system}, you might be able to preserve access |
2423 |
times reliably by using the @command{mount} command. For example, |
2424 |
you can mount the file system read-only, or access the file system via |
2425 |
a read-only loopback mount, or use the @samp{noatime} mount option |
2426 |
available on some systems. However, mounting typically requires |
2427 |
superuser privileges and can be a pain to manage. |
2428 |
|
2429 |
@opsummary{auto-compress} |
2430 |
@item --auto-compress |
2431 |
@itemx -a |
2432 |
|
2433 |
During a @option{--create} operation, enables automatic compressed |
2434 |
format recognition based on the archive suffix. The effect of this |
2435 |
option is cancelled by @option{--no-auto-compress}. @xref{gzip}. |
2436 |
|
2437 |
@opsummary{backup} |
2438 |
@item --backup=@var{backup-type} |
2439 |
|
2440 |
Rather than deleting files from the file system, @command{tar} will |
2441 |
back them up using simple or numbered backups, depending upon |
2442 |
@var{backup-type}. @xref{backup}. |
2443 |
|
2444 |
@opsummary{block-number} |
2445 |
@item --block-number |
2446 |
@itemx -R |
2447 |
|
2448 |
With this option present, @command{tar} prints error messages for read errors |
2449 |
with the block number in the archive file. @xref{block-number}. |
2450 |
|
2451 |
@opsummary{blocking-factor} |
2452 |
@item --blocking-factor=@var{blocking} |
2453 |
@itemx -b @var{blocking} |
2454 |
|
2455 |
Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per |
2456 |
record. @xref{Blocking Factor}. |
2457 |
|
2458 |
@opsummary{bzip2} |
2459 |
@item --bzip2 |
2460 |
@itemx -j |
2461 |
|
2462 |
This option tells @command{tar} to read or write archives through |
2463 |
@code{bzip2}. @xref{gzip}. |
2464 |
|
2465 |
@opsummary{check-device} |
2466 |
@item --check-device |
2467 |
Check device numbers when creating a list of modified files for |
2468 |
incremental archiving. This is the default. @xref{device numbers}, |
2469 |
for a detailed description. |
2470 |
|
2471 |
@opsummary{checkpoint} |
2472 |
@item --checkpoint[=@var{number}] |
2473 |
|
2474 |
This option directs @command{tar} to print periodic checkpoint |
2475 |
messages as it reads through the archive. It is intended for when you |
2476 |
want a visual indication that @command{tar} is still running, but |
2477 |
don't want to see @option{--verbose} output. You can also instruct |
2478 |
@command{tar} to execute a list of actions on each checkpoint, see |
2479 |
@option{--checkpoint-action} below. For a detailed description, see |
2480 |
@ref{checkpoints}. |
2481 |
|
2482 |
@opsummary{checkpoint-action} |
2483 |
@item --checkpoint-action=@var{action} |
2484 |
Instruct @command{tar} to execute an action upon hitting a |
2485 |
breakpoint. Here we give only a brief outline. @xref{checkpoints}, |
2486 |
for a complete description. |
2487 |
|
2488 |
The @var{action} argument can be one of the following: |
2489 |
|
2490 |
@table @asis |
2491 |
@item bell |
2492 |
Produce an audible bell on the console. |
2493 |
|
2494 |
@item dot |
2495 |
@itemx . |
2496 |
Print a single dot on the standard listing stream. |
2497 |
|
2498 |
@item echo |
2499 |
Display a textual message on the standard error, with the status and |
2500 |
number of the checkpoint. This is the default. |
2501 |
|
2502 |
@item echo=@var{string} |
2503 |
Display @var{string} on the standard error. Before output, the string |
2504 |
is subject to meta-character expansion. |
2505 |
|
2506 |
@item exec=@var{command} |
2507 |
Execute the given @var{command}. |
2508 |
|
2509 |
@item sleep=@var{time} |
2510 |
Wait for @var{time} seconds. |
2511 |
|
2512 |
@item ttyout=@var{string} |
2513 |
Output @var{string} on the current console (@file{/dev/tty}). |
2514 |
@end table |
2515 |
|
2516 |
Several @option{--checkpoint-action} options can be specified. The |
2517 |
supplied actions will be executed in order of their appearance in the |
2518 |
command line. |
2519 |
|
2520 |
Using @option{--checkpoint-action} without @option{--checkpoint} |
2521 |
assumes default checkpoint frequency of one checkpoint per 10 records. |
2522 |
|
2523 |
@opsummary{check-links} |
2524 |
@item --check-links |
2525 |
@itemx -l |
2526 |
If this option was given, @command{tar} will check the number of links |
2527 |
dumped for each processed file. If this number does not match the |
2528 |
total number of hard links for the file, a warning message will be |
2529 |
output @footnote{Earlier versions of @GNUTAR{} understood @option{-l} as a |
2530 |
synonym for @option{--one-file-system}. The current semantics, which |
2531 |
complies to UNIX98, was introduced with version |
2532 |
1.15.91. @xref{Changes}, for more information.}. |
2533 |
|
2534 |
@xref{hard links}. |
2535 |
|
2536 |
@opsummary{compress} |
2537 |
@opsummary{uncompress} |
2538 |
@item --compress |
2539 |
@itemx --uncompress |
2540 |
@itemx -Z |
2541 |
|
2542 |
@command{tar} will use the @command{compress} program when reading or |
2543 |
writing the archive. This allows you to directly act on archives |
2544 |
while saving space. @xref{gzip}. |
2545 |
|
2546 |
@opsummary{confirmation} |
2547 |
@item --confirmation |
2548 |
|
2549 |
(See @option{--interactive}.) @xref{interactive}. |
2550 |
|
2551 |
@opsummary{delay-directory-restore} |
2552 |
@item --delay-directory-restore |
2553 |
|
2554 |
Delay setting modification times and permissions of extracted |
2555 |
directories until the end of extraction. @xref{Directory Modification Times and Permissions}. |
2556 |
|
2557 |
@opsummary{dereference} |
2558 |
@item --dereference |
2559 |
@itemx -h |
2560 |
|
2561 |
When reading or writing a file to be archived, @command{tar} accesses |
2562 |
the file that a symbolic link points to, rather than the symlink |
2563 |
itself. @xref{dereference}. |
2564 |
|
2565 |
@opsummary{directory} |
2566 |
@item --directory=@var{dir} |
2567 |
@itemx -C @var{dir} |
2568 |
|
2569 |
When this option is specified, @command{tar} will change its current directory |
2570 |
to @var{dir} before performing any operations. When this option is used |
2571 |
during archive creation, it is order sensitive. @xref{directory}. |
2572 |
|
2573 |
@opsummary{exclude} |
2574 |
@item --exclude=@var{pattern} |
2575 |
|
2576 |
When performing operations, @command{tar} will skip files that match |
2577 |
@var{pattern}. @xref{exclude}. |
2578 |
|
2579 |
@opsummary{exclude-backups} |
2580 |
@item --exclude-backups |
2581 |
Exclude backup and lock files. @xref{exclude,, exclude-backups}. |
2582 |
|
2583 |
@opsummary{exclude-from} |
2584 |
@item --exclude-from=@var{file} |
2585 |
@itemx -X @var{file} |
2586 |
|
2587 |
Similar to @option{--exclude}, except @command{tar} will use the list of |
2588 |
patterns in the file @var{file}. @xref{exclude}. |
2589 |
|
2590 |
@opsummary{exclude-caches} |
2591 |
@item --exclude-caches |
2592 |
|
2593 |
Exclude from dump any directory containing a valid cache directory |
2594 |
tag file, but still dump the directory node and the tag file itself. |
2595 |
|
2596 |
@xref{exclude,, exclude-caches}. |
2597 |
|
2598 |
@opsummary{exclude-caches-under} |
2599 |
@item --exclude-caches-under |
2600 |
|
2601 |
Exclude from dump any directory containing a valid cache directory |
2602 |
tag file, but still dump the directory node itself. |
2603 |
|
2604 |
@xref{exclude}. |
2605 |
|
2606 |
@opsummary{exclude-caches-all} |
2607 |
@item --exclude-caches-all |
2608 |
|
2609 |
Exclude from dump any directory containing a valid cache directory |
2610 |
tag file. @xref{exclude}. |
2611 |
|
2612 |
@opsummary{exclude-tag} |
2613 |
@item --exclude-tag=@var{file} |
2614 |
|
2615 |
Exclude from dump any directory containing file named @var{file}, but |
2616 |
dump the directory node and @var{file} itself. @xref{exclude,, exclude-tag}. |
2617 |
|
2618 |
@opsummary{exclude-tag-under} |
2619 |
@item --exclude-tag-under=@var{file} |
2620 |
|
2621 |
Exclude from dump the contents of any directory containing file |
2622 |
named @var{file}, but dump the directory node itself. @xref{exclude,, |
2623 |
exclude-tag-under}. |
2624 |
|
2625 |
@opsummary{exclude-tag-all} |
2626 |
@item --exclude-tag-all=@var{file} |
2627 |
|
2628 |
Exclude from dump any directory containing file named @var{file}. |
2629 |
@xref{exclude,,exclude-tag-all}. |
2630 |
|
2631 |
@opsummary{exclude-vcs} |
2632 |
@item --exclude-vcs |
2633 |
|
2634 |
Exclude from dump directories and files, that are internal for some |
2635 |
widely used version control systems. |
2636 |
|
2637 |
@xref{exclude,,exclude-vcs}. |
2638 |
|
2639 |
@opsummary{file} |
2640 |
@item --file=@var{archive} |
2641 |
@itemx -f @var{archive} |
2642 |
|
2643 |
@command{tar} will use the file @var{archive} as the @command{tar} archive it |
2644 |
performs operations on, rather than @command{tar}'s compilation dependent |
2645 |
default. @xref{file tutorial}. |
2646 |
|
2647 |
@opsummary{files-from} |
2648 |
@item --files-from=@var{file} |
2649 |
@itemx -T @var{file} |
2650 |
|
2651 |
@command{tar} will use the contents of @var{file} as a list of archive members |
2652 |
or files to operate on, in addition to those specified on the |
2653 |
command-line. @xref{files}. |
2654 |
|
2655 |
@opsummary{force-local} |
2656 |
@item --force-local |
2657 |
|
2658 |
Forces @command{tar} to interpret the file name given to @option{--file} |
2659 |
as a local file, even if it looks like a remote tape drive name. |
2660 |
@xref{local and remote archives}. |
2661 |
|
2662 |
@opsummary{format} |
2663 |
@item --format=@var{format} |
2664 |
@itemx -H @var{format} |
2665 |
|
2666 |
Selects output archive format. @var{Format} may be one of the |
2667 |
following: |
2668 |
|
2669 |
@table @samp |
2670 |
@item v7 |
2671 |
Creates an archive that is compatible with Unix V7 @command{tar}. |
2672 |
|
2673 |
@item oldgnu |
2674 |
Creates an archive that is compatible with GNU @command{tar} version |
2675 |
1.12 or earlier. |
2676 |
|
2677 |
@item gnu |
2678 |
Creates archive in GNU tar 1.13 format. Basically it is the same as |
2679 |
@samp{oldgnu} with the only difference in the way it handles long |
2680 |
numeric fields. |
2681 |
|
2682 |
@item ustar |
2683 |
Creates a @acronym{POSIX.1-1988} compatible archive. |
2684 |
|
2685 |
@item posix |
2686 |
Creates a @acronym{POSIX.1-2001 archive}. |
2687 |
|
2688 |
@end table |
2689 |
|
2690 |
@xref{Formats}, for a detailed discussion of these formats. |
2691 |
|
2692 |
@opsummary{full-time} |
2693 |
@item --full-time |
2694 |
This option instructs @command{tar} to print file times to their full |
2695 |
resolution. Usually this means 1-second resolution, but that depends |
2696 |
on the underlying file system. The @option{--full-time} option takes |
2697 |
effect only when detailed output (verbosity level 2 or higher) has |
2698 |
been requested using the @option{--verbose} option, e.g., when listing |
2699 |
or extracting archives: |
2700 |
|
2701 |
@smallexample |
2702 |
$ @kbd{tar -t -v --full-time -f archive.tar} |
2703 |
@end smallexample |
2704 |
|
2705 |
@noindent |
2706 |
or, when creating an archive: |
2707 |
|
2708 |
@smallexample |
2709 |
$ @kbd{tar -c -vv --full-time -f archive.tar .} |
2710 |
@end smallexample |
2711 |
|
2712 |
Notice, thar when creating the archive you need to specify |
2713 |
@option{--verbose} twice to get a detailed output (@pxref{verbose |
2714 |
tutorial}). |
2715 |
|
2716 |
@opsummary{group} |
2717 |
@item --group=@var{group} |
2718 |
|
2719 |
Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group}, |
2720 |
rather than the group from the source file. @var{group} is first decoded |
2721 |
as a group symbolic name, but if this interpretation fails, it has to be |
2722 |
a decimal numeric group @acronym{ID}. @xref{override}. |
2723 |
|
2724 |
Also see the comments for the @option{--owner=@var{user}} option. |
2725 |
|
2726 |
@opsummary{gzip} |
2727 |
@opsummary{gunzip} |
2728 |
@opsummary{ungzip} |
2729 |
@item --gzip |
2730 |
@itemx --gunzip |
2731 |
@itemx --ungzip |
2732 |
@itemx -z |
2733 |
|
2734 |
This option tells @command{tar} to read or write archives through |
2735 |
@command{gzip}, allowing @command{tar} to directly operate on several |
2736 |
kinds of compressed archives transparently. @xref{gzip}. |
2737 |
|
2738 |
@opsummary{hard-dereference} |
2739 |
@item --hard-dereference |
2740 |
When creating an archive, dereference hard links and store the files |
2741 |
they refer to, instead of creating usual hard link members. |
2742 |
|
2743 |
@xref{hard links}. |
2744 |
|
2745 |
@opsummary{help} |
2746 |
@item --help |
2747 |
@itemx -? |
2748 |
|
2749 |
@command{tar} will print out a short message summarizing the operations and |
2750 |
options to @command{tar} and exit. @xref{help}. |
2751 |
|
2752 |
@opsummary{ignore-case} |
2753 |
@item --ignore-case |
2754 |
Ignore case when matching member or file names with |
2755 |
patterns. @xref{controlling pattern-matching}. |
2756 |
|
2757 |
@opsummary{ignore-command-error} |
2758 |
@item --ignore-command-error |
2759 |
Ignore exit codes of subprocesses. @xref{Writing to an External Program}. |
2760 |
|
2761 |
@opsummary{ignore-failed-read} |
2762 |
@item --ignore-failed-read |
2763 |
|
2764 |
Do not exit unsuccessfully merely because an unreadable file was encountered. |
2765 |
@xref{Reading}. |
2766 |
|
2767 |
@opsummary{ignore-zeros} |
2768 |
@item --ignore-zeros |
2769 |
@itemx -i |
2770 |
|
2771 |
With this option, @command{tar} will ignore zeroed blocks in the |
2772 |
archive, which normally signals EOF. @xref{Reading}. |
2773 |
|
2774 |
@opsummary{incremental} |
2775 |
@item --incremental |
2776 |
@itemx -G |
2777 |
|
2778 |
Informs @command{tar} that it is working with an old |
2779 |
@acronym{GNU}-format incremental backup archive. It is intended |
2780 |
primarily for backwards compatibility only. @xref{Incremental Dumps}, |
2781 |
for a detailed discussion of incremental archives. |
2782 |
|
2783 |
@opsummary{index-file} |
2784 |
@item --index-file=@var{file} |
2785 |
|
2786 |
Send verbose output to @var{file} instead of to standard output. |
2787 |
|
2788 |
@opsummary{info-script} |
2789 |
@opsummary{new-volume-script} |
2790 |
@item --info-script=@var{script-file} |
2791 |
@itemx --new-volume-script=@var{script-file} |
2792 |
@itemx -F @var{script-file} |
2793 |
|
2794 |
When @command{tar} is performing multi-tape backups, @var{script-file} is run |
2795 |
at the end of each tape. If @var{script-file} exits with nonzero status, |
2796 |
@command{tar} fails immediately. @xref{info-script}, for a detailed |
2797 |
discussion of @var{script-file}. |
2798 |
|
2799 |
@opsummary{interactive} |
2800 |
@item --interactive |
2801 |
@itemx --confirmation |
2802 |
@itemx -w |
2803 |
|
2804 |
Specifies that @command{tar} should ask the user for confirmation before |
2805 |
performing potentially destructive options, such as overwriting files. |
2806 |
@xref{interactive}. |
2807 |
|
2808 |
@opsummary{keep-newer-files} |
2809 |
@item --keep-newer-files |
2810 |
|
2811 |
Do not replace existing files that are newer than their archive copies |
2812 |
when extracting files from an archive. |
2813 |
|
2814 |
@opsummary{keep-old-files} |
2815 |
@item --keep-old-files |
2816 |
@itemx -k |
2817 |
|
2818 |
Do not overwrite existing files when extracting files from an archive. |
2819 |
@xref{Keep Old Files}. |
2820 |
|
2821 |
@opsummary{label} |
2822 |
@item --label=@var{name} |
2823 |
@itemx -V @var{name} |
2824 |
|
2825 |
When creating an archive, instructs @command{tar} to write @var{name} |
2826 |
as a name record in the archive. When extracting or listing archives, |
2827 |
@command{tar} will only operate on archives that have a label matching |
2828 |
the pattern specified in @var{name}. @xref{Tape Files}. |
2829 |
|
2830 |
@opsummary{level} |
2831 |
@item --level=@var{n} |
2832 |
Force incremental backup of level @var{n}. As of @GNUTAR version |
2833 |
@value{VERSION}, the option @option{--level=0} truncates the snapshot |
2834 |
file, thereby forcing the level 0 dump. Other values of @var{n} are |
2835 |
effectively ignored. @xref{--level=0}, for details and examples. |
2836 |
|
2837 |
The use of this option is valid only in conjunction with the |
2838 |
@option{--listed-incremental} option. @xref{Incremental Dumps}, |
2839 |
for a detailed description. |
2840 |
|
2841 |
@opsummary{listed-incremental} |
2842 |
@item --listed-incremental=@var{snapshot-file} |
2843 |
@itemx -g @var{snapshot-file} |
2844 |
|
2845 |
During a @option{--create} operation, specifies that the archive that |
2846 |
@command{tar} creates is a new @acronym{GNU}-format incremental |
2847 |
backup, using @var{snapshot-file} to determine which files to backup. |
2848 |
With other operations, informs @command{tar} that the archive is in |
2849 |
incremental format. @xref{Incremental Dumps}. |
2850 |
|
2851 |
@opsummary{lzip} |
2852 |
@item --lzip |
2853 |
|
2854 |
This option tells @command{tar} to read or write archives through |
2855 |
@command{lzip}. @xref{gzip}. |
2856 |
|
2857 |
@opsummary{lzma} |
2858 |
@item --lzma |
2859 |
|
2860 |
This option tells @command{tar} to read or write archives through |
2861 |
@command{lzma}. @xref{gzip}. |
2862 |
|
2863 |
@item --lzop |
2864 |
|
2865 |
This option tells @command{tar} to read or write archives through |
2866 |
@command{lzop}. @xref{gzip}. |
2867 |
|
2868 |
@opsummary{mode} |
2869 |
@item --mode=@var{permissions} |
2870 |
|
2871 |
When adding files to an archive, @command{tar} will use |
2872 |
@var{permissions} for the archive members, rather than the permissions |
2873 |
from the files. @var{permissions} can be specified either as an octal |
2874 |
number or as symbolic permissions, like with |
2875 |
@command{chmod}. @xref{override}. |
2876 |
|
2877 |
@opsummary{mtime} |
2878 |
@item --mtime=@var{date} |
2879 |
|
2880 |
When adding files to an archive, @command{tar} will use @var{date} as |
2881 |
the modification time of members when creating archives, instead of |
2882 |
their actual modification times. The value of @var{date} can be |
2883 |
either a textual date representation (@pxref{Date input formats}) or a |
2884 |
name of the existing file, starting with @samp{/} or @samp{.}. In the |
2885 |
latter case, the modification time of that file is used. @xref{override}. |
2886 |
|
2887 |
@opsummary{multi-volume} |
2888 |
@item --multi-volume |
2889 |
@itemx -M |
2890 |
|
2891 |
Informs @command{tar} that it should create or otherwise operate on a |
2892 |
multi-volume @command{tar} archive. @xref{Using Multiple Tapes}. |
2893 |
|
2894 |
@opsummary{new-volume-script} |
2895 |
@item --new-volume-script |
2896 |
|
2897 |
(see @option{--info-script}) |
2898 |
|
2899 |
@opsummary{newer} |
2900 |
@item --newer=@var{date} |
2901 |
@itemx --after-date=@var{date} |
2902 |
@itemx -N |
2903 |
|
2904 |
When creating an archive, @command{tar} will only add files that have changed |
2905 |
since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it |
2906 |
is taken to be the name of a file whose data modification time specifies |
2907 |
the date. @xref{after}. |
2908 |
|
2909 |
@opsummary{newer-mtime} |
2910 |
@item --newer-mtime=@var{date} |
2911 |
|
2912 |
Like @option{--newer}, but add only files whose |
2913 |
contents have changed (as opposed to just @option{--newer}, which will |
2914 |
also back up files for which any status information has |
2915 |
changed). @xref{after}. |
2916 |
|
2917 |
@opsummary{no-anchored} |
2918 |
@item --no-anchored |
2919 |
An exclude pattern can match any subsequence of the name's components. |
2920 |
@xref{controlling pattern-matching}. |
2921 |
|
2922 |
@opsummary{no-auto-compress} |
2923 |
@item --no-auto-compress |
2924 |
|
2925 |
Disables automatic compressed format recognition based on the archive |
2926 |
suffix. @xref{--auto-compress}. @xref{gzip}. |
2927 |
|
2928 |
@opsummary{no-check-device} |
2929 |
@item --no-check-device |
2930 |
Do not check device numbers when creating a list of modified files |
2931 |
for incremental archiving. @xref{device numbers}, for |
2932 |
a detailed description. |
2933 |
|
2934 |
@opsummary{no-delay-directory-restore} |
2935 |
@item --no-delay-directory-restore |
2936 |
|
2937 |
Modification times and permissions of extracted |
2938 |
directories are set when all files from this directory have been |
2939 |
extracted. This is the default. |
2940 |
@xref{Directory Modification Times and Permissions}. |
2941 |
|
2942 |
@opsummary{no-ignore-case} |
2943 |
@item --no-ignore-case |
2944 |
Use case-sensitive matching. |
2945 |
@xref{controlling pattern-matching}. |
2946 |
|
2947 |
@opsummary{no-ignore-command-error} |
2948 |
@item --no-ignore-command-error |
2949 |
Print warnings about subprocesses that terminated with a nonzero exit |
2950 |
code. @xref{Writing to an External Program}. |
2951 |
|
2952 |
@opsummary{no-null} |
2953 |
@item --no-null |
2954 |
|
2955 |
If the @option{--null} option was given previously, this option |
2956 |
cancels its effect, so that any following @option{--files-from} |
2957 |
options will expect their file lists to be newline-terminated. |
2958 |
|
2959 |
@opsummary{no-overwrite-dir} |
2960 |
@item --no-overwrite-dir |
2961 |
|
2962 |
Preserve metadata of existing directories when extracting files |
2963 |
from an archive. @xref{Overwrite Old Files}. |
2964 |
|
2965 |
@opsummary{no-quote-chars} |
2966 |
@item --no-quote-chars=@var{string} |
2967 |
Remove characters listed in @var{string} from the list of quoted |
2968 |
characters set by the previous @option{--quote-chars} option |
2969 |
(@pxref{quoting styles}). |
2970 |
|
2971 |
@opsummary{no-recursion} |
2972 |
@item --no-recursion |
2973 |
|
2974 |
With this option, @command{tar} will not recurse into directories. |
2975 |
@xref{recurse}. |
2976 |
|
2977 |
@opsummary{no-same-owner} |
2978 |
@item --no-same-owner |
2979 |
@itemx -o |
2980 |
|
2981 |
When extracting an archive, do not attempt to preserve the owner |
2982 |
specified in the @command{tar} archive. This the default behavior |
2983 |
for ordinary users. |
2984 |
|
2985 |
@opsummary{no-same-permissions} |
2986 |
@item --no-same-permissions |
2987 |
|
2988 |
When extracting an archive, subtract the user's umask from files from |
2989 |
the permissions specified in the archive. This is the default behavior |
2990 |
for ordinary users. |
2991 |
|
2992 |
@opsummary{no-seek} |
2993 |
@item --no-seek |
2994 |
|
2995 |
The archive media does not support seeks to arbitrary |
2996 |
locations. Usually @command{tar} determines automatically whether |
2997 |
the archive can be seeked or not. Use this option to disable this |
2998 |
mechanism. |
2999 |
|
3000 |
@opsummary{no-unquote} |
3001 |
@item --no-unquote |
3002 |
Treat all input file or member names literally, do not interpret |
3003 |
escape sequences. @xref{input name quoting}. |
3004 |
|
3005 |
@opsummary{no-wildcards} |
3006 |
@item --no-wildcards |
3007 |
Do not use wildcards. |
3008 |
@xref{controlling pattern-matching}. |
3009 |
|
3010 |
@opsummary{no-wildcards-match-slash} |
3011 |
@item --no-wildcards-match-slash |
3012 |
Wildcards do not match @samp{/}. |
3013 |
@xref{controlling pattern-matching}. |
3014 |
|
3015 |
@opsummary{null} |
3016 |
@item --null |
3017 |
|
3018 |
When @command{tar} is using the @option{--files-from} option, this option |
3019 |
instructs @command{tar} to expect file names terminated with @acronym{NUL}, so |
3020 |
@command{tar} can correctly work with file names that contain newlines. |
3021 |
@xref{nul}. |
3022 |
|
3023 |
@opsummary{numeric-owner} |
3024 |
@item --numeric-owner |
3025 |
|
3026 |
This option will notify @command{tar} that it should use numeric user |
3027 |
and group IDs when creating a @command{tar} file, rather than names. |
3028 |
@xref{Attributes}. |
3029 |
|
3030 |
@item -o |
3031 |
The function of this option depends on the action @command{tar} is |
3032 |
performing. When extracting files, @option{-o} is a synonym for |
3033 |
@option{--no-same-owner}, i.e., it prevents @command{tar} from |
3034 |
restoring ownership of files being extracted. |
3035 |
|
3036 |
When creating an archive, it is a synonym for |
3037 |
@option{--old-archive}. This behavior is for compatibility |
3038 |
with previous versions of @GNUTAR{}, and will be |
3039 |
removed in future releases. |
3040 |
|
3041 |
@xref{Changes}, for more information. |
3042 |
|
3043 |
@opsummary{occurrence} |
3044 |
@item --occurrence[=@var{number}] |
3045 |
|
3046 |
This option can be used in conjunction with one of the subcommands |
3047 |
@option{--delete}, @option{--diff}, @option{--extract} or |
3048 |
@option{--list} when a list of files is given either on the command |
3049 |
line or via @option{-T} option. |
3050 |
|
3051 |
This option instructs @command{tar} to process only the @var{number}th |
3052 |
occurrence of each named file. @var{Number} defaults to 1, so |
3053 |
|
3054 |
@smallexample |
3055 |
tar -x -f archive.tar --occurrence filename |
3056 |
@end smallexample |
3057 |
|
3058 |
@noindent |
3059 |
will extract the first occurrence of the member @file{filename} from @file{archive.tar} |
3060 |
and will terminate without scanning to the end of the archive. |
3061 |
|
3062 |
@opsummary{old-archive} |
3063 |
@item --old-archive |
3064 |
Synonym for @option{--format=v7}. |
3065 |
|
3066 |
@opsummary{one-file-system} |
3067 |
@item --one-file-system |
3068 |
Used when creating an archive. Prevents @command{tar} from recursing into |
3069 |
directories that are on different file systems from the current |
3070 |
directory. |
3071 |
|
3072 |
@opsummary{overwrite} |
3073 |
@item --overwrite |
3074 |
|
3075 |
Overwrite existing files and directory metadata when extracting files |
3076 |
from an archive. @xref{Overwrite Old Files}. |
3077 |
|
3078 |
@opsummary{overwrite-dir} |
3079 |
@item --overwrite-dir |
3080 |
|
3081 |
Overwrite the metadata of existing directories when extracting files |
3082 |
from an archive. @xref{Overwrite Old Files}. |
3083 |
|
3084 |
@opsummary{owner} |
3085 |
@item --owner=@var{user} |
3086 |
|
3087 |
Specifies that @command{tar} should use @var{user} as the owner of members |
3088 |
when creating archives, instead of the user associated with the source |
3089 |
file. @var{user} is first decoded as a user symbolic name, but if |
3090 |
this interpretation fails, it has to be a decimal numeric user @acronym{ID}. |
3091 |
@xref{override}. |
3092 |
|
3093 |
This option does not affect extraction from archives. |
3094 |
|
3095 |
@opsummary{pax-option} |
3096 |
@item --pax-option=@var{keyword-list} |
3097 |
This option enables creation of the archive in @acronym{POSIX.1-2001} |
3098 |
format (@pxref{posix}) and modifies the way @command{tar} handles the |
3099 |
extended header keywords. @var{Keyword-list} is a comma-separated |
3100 |
list of keyword options. @xref{PAX keywords}, for a detailed |
3101 |
discussion. |
3102 |
|
3103 |
@opsummary{portability} |
3104 |
@item --portability |
3105 |
@itemx --old-archive |
3106 |
Synonym for @option{--format=v7}. |
3107 |
|
3108 |
@opsummary{posix} |
3109 |
@item --posix |
3110 |
Same as @option{--format=posix}. |
3111 |
|
3112 |
@opsummary{preserve} |
3113 |
@item --preserve |
3114 |
|
3115 |
Synonymous with specifying both @option{--preserve-permissions} and |
3116 |
@option{--same-order}. @xref{Setting Access Permissions}. |
3117 |
|
3118 |
@opsummary{preserve-order} |
3119 |
@item --preserve-order |
3120 |
|
3121 |
(See @option{--same-order}; @pxref{Reading}.) |
3122 |
|
3123 |
@opsummary{preserve-permissions} |
3124 |
@opsummary{same-permissions} |
3125 |
@item --preserve-permissions |
3126 |
@itemx --same-permissions |
3127 |
@itemx -p |
3128 |
|
3129 |
When @command{tar} is extracting an archive, it normally subtracts the |
3130 |
users' umask from the permissions specified in the archive and uses |
3131 |
that number as the permissions to create the destination file. |
3132 |
Specifying this option instructs @command{tar} that it should use the |
3133 |
permissions directly from the archive. @xref{Setting Access Permissions}. |
3134 |
|
3135 |
@opsummary{quote-chars} |
3136 |
@item --quote-chars=@var{string} |
3137 |
Always quote characters from @var{string}, even if the selected |
3138 |
quoting style would not quote them (@pxref{quoting styles}). |
3139 |
|
3140 |
@opsummary{quoting-style} |
3141 |
@item --quoting-style=@var{style} |
3142 |
Set quoting style to use when printing member and file names |
3143 |
(@pxref{quoting styles}). Valid @var{style} values are: |
3144 |
@code{literal}, @code{shell}, @code{shell-always}, @code{c}, |
3145 |
@code{escape}, @code{locale}, and @code{clocale}. Default quoting |
3146 |
style is @code{escape}, unless overridden while configuring the |
3147 |
package. |
3148 |
|
3149 |
@opsummary{read-full-records} |
3150 |
@item --read-full-records |
3151 |
@itemx -B |
3152 |
|
3153 |
Specifies that @command{tar} should reblock its input, for reading |
3154 |
from pipes on systems with buggy implementations. @xref{Reading}. |
3155 |
|
3156 |
@opsummary{record-size} |
3157 |
@item --record-size=@var{size}[@var{suf}] |
3158 |
|
3159 |
Instructs @command{tar} to use @var{size} bytes per record when accessing the |
3160 |
archive. The argument can be suffixed with a @dfn{size suffix}, e.g. |
3161 |
@option{--record-size=10K} for 10 Kilobytes. @xref{size-suffixes}, |
3162 |
for a list of valid suffixes. @xref{Blocking Factor}, for a detailed |
3163 |
description of this option. |
3164 |
|
3165 |
@opsummary{recursion} |
3166 |
@item --recursion |
3167 |
|
3168 |
With this option, @command{tar} recurses into directories (default). |
3169 |
@xref{recurse}. |
3170 |
|
3171 |
@opsummary{recursive-unlink} |
3172 |
@item --recursive-unlink |
3173 |
|
3174 |
Remove existing |
3175 |
directory hierarchies before extracting directories of the same name |
3176 |
from the archive. @xref{Recursive Unlink}. |
3177 |
|
3178 |
@opsummary{remove-files} |
3179 |
@item --remove-files |
3180 |
|
3181 |
Directs @command{tar} to remove the source file from the file system after |
3182 |
appending it to an archive. @xref{remove files}. |
3183 |
|
3184 |
@opsummary{restrict} |
3185 |
@item --restrict |
3186 |
|
3187 |
Disable use of some potentially harmful @command{tar} options. |
3188 |
Currently this option disables shell invocation from multi-volume menu |
3189 |
(@pxref{Using Multiple Tapes}). |
3190 |
|
3191 |
@opsummary{rmt-command} |
3192 |
@item --rmt-command=@var{cmd} |
3193 |
|
3194 |
Notifies @command{tar} that it should use @var{cmd} instead of |
3195 |
the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}). |
3196 |
|
3197 |
@opsummary{rsh-command} |
3198 |
@item --rsh-command=@var{cmd} |
3199 |
|
3200 |
Notifies @command{tar} that is should use @var{cmd} to communicate with remote |
3201 |
devices. @xref{Device}. |
3202 |
|
3203 |
@opsummary{same-order} |
3204 |
@item --same-order |
3205 |
@itemx --preserve-order |
3206 |
@itemx -s |
3207 |
|
3208 |
This option is an optimization for @command{tar} when running on machines with |
3209 |
small amounts of memory. It informs @command{tar} that the list of file |
3210 |
arguments has already been sorted to match the order of files in the |
3211 |
archive. @xref{Reading}. |
3212 |
|
3213 |
@opsummary{same-owner} |
3214 |
@item --same-owner |
3215 |
|
3216 |
When extracting an archive, @command{tar} will attempt to preserve the owner |
3217 |
specified in the @command{tar} archive with this option present. |
3218 |
This is the default behavior for the superuser; this option has an |
3219 |
effect only for ordinary users. @xref{Attributes}. |
3220 |
|
3221 |
@opsummary{same-permissions} |
3222 |
@item --same-permissions |
3223 |
|
3224 |
(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.) |
3225 |
|
3226 |
@opsummary{seek} |
3227 |
@item --seek |
3228 |
@itemx -n |
3229 |
|
3230 |
Assume that the archive media supports seeks to arbitrary |
3231 |
locations. Usually @command{tar} determines automatically whether |
3232 |
the archive can be seeked or not. This option is intended for use |
3233 |
in cases when such recognition fails. It takes effect only if the |
3234 |
archive is open for reading (e.g. with @option{--list} or |
3235 |
@option{--extract} options). |
3236 |
|
3237 |
@opsummary{show-defaults} |
3238 |
@item --show-defaults |
3239 |
|
3240 |
Displays the default options used by @command{tar} and exits |
3241 |
successfully. This option is intended for use in shell scripts. |
3242 |
Here is an example of what you can see using this option: |
3243 |
|
3244 |
@smallexample |
3245 |
$ @kbd{tar --show-defaults} |
3246 |
--format=gnu -f- -b20 --quoting-style=escape |
3247 |
--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh |
3248 |
@end smallexample |
3249 |
|
3250 |
@noindent |
3251 |
Notice, that this option outputs only one line. The example output |
3252 |
above has been split to fit page boundaries. |
3253 |
|
3254 |
@opsummary{show-omitted-dirs} |
3255 |
@item --show-omitted-dirs |
3256 |
|
3257 |
Instructs @command{tar} to mention the directories it is skipping when |
3258 |
operating on a @command{tar} archive. @xref{show-omitted-dirs}. |
3259 |
|
3260 |
@opsummary{show-transformed-names} |
3261 |
@opsummary{show-stored-names} |
3262 |
@item --show-transformed-names |
3263 |
@itemx --show-stored-names |
3264 |
|
3265 |
Display file or member names after applying any transformations |
3266 |
(@pxref{transform}). In particular, when used in conjunction with one of |
3267 |
the archive creation operations it instructs @command{tar} to list the |
3268 |
member names stored in the archive, as opposed to the actual file |
3269 |
names. @xref{listing member and file names}. |
3270 |
|
3271 |
@opsummary{sparse} |
3272 |
@item --sparse |
3273 |
@itemx -S |
3274 |
|
3275 |
Invokes a @acronym{GNU} extension when adding files to an archive that handles |
3276 |
sparse files efficiently. @xref{sparse}. |
3277 |
|
3278 |
@opsummary{sparse-version} |
3279 |
@item --sparse-version=@var{version} |
3280 |
|
3281 |
Specifies the @dfn{format version} to use when archiving sparse |
3282 |
files. Implies @option{--sparse}. @xref{sparse}. For the description |
3283 |
of the supported sparse formats, @xref{Sparse Formats}. |
3284 |
|
3285 |
@opsummary{starting-file} |
3286 |
@item --starting-file=@var{name} |
3287 |
@itemx -K @var{name} |
3288 |
|
3289 |
This option affects extraction only; @command{tar} will skip extracting |
3290 |
files in the archive until it finds one that matches @var{name}. |
3291 |
@xref{Scarce}. |
3292 |
|
3293 |
@opsummary{strip-components} |
3294 |
@item --strip-components=@var{number} |
3295 |
Strip given @var{number} of leading components from file names before |
3296 |
extraction. For example, if archive @file{archive.tar} contained |
3297 |
@file{/some/file/name}, then running |
3298 |
|
3299 |
@smallexample |
3300 |
tar --extract --file archive.tar --strip-components=2 |
3301 |
@end smallexample |
3302 |
|
3303 |
@noindent |
3304 |
would extract this file to file @file{name}. |
3305 |
|
3306 |
@opsummary{suffix} |
3307 |
@item --suffix=@var{suffix} |
3308 |
|
3309 |
Alters the suffix @command{tar} uses when backing up files from the default |
3310 |
@samp{~}. @xref{backup}. |
3311 |
|
3312 |
@opsummary{tape-length} |
3313 |
@item --tape-length=@var{num}[@var{suf}] |
3314 |
@itemx -L @var{num}[@var{suf}] |
3315 |
|
3316 |
Specifies the length of tapes that @command{tar} is writing as being |
3317 |
@w{@var{num} x 1024} bytes long. If optional @var{suf} is given, it |
3318 |
specifies a multiplicative factor to be used instead of 1024. For |
3319 |
example, @samp{-L2M} means 2 megabytes. @xref{size-suffixes}, for a |
3320 |
list of allowed suffixes. @xref{Using Multiple Tapes}, for a detailed |
3321 |
discussion of this option. |
3322 |
|
3323 |
@opsummary{test-label} |
3324 |
@item --test-label |
3325 |
|
3326 |
Reads the volume label. If an argument is specified, test whether it |
3327 |
matches the volume label. @xref{--test-label option}. |
3328 |
|
3329 |
@opsummary{to-command} |
3330 |
@item --to-command=@var{command} |
3331 |
|
3332 |
During extraction @command{tar} will pipe extracted files to the |
3333 |
standard input of @var{command}. @xref{Writing to an External Program}. |
3334 |
|
3335 |
@opsummary{to-stdout} |
3336 |
@item --to-stdout |
3337 |
@itemx -O |
3338 |
|
3339 |
During extraction, @command{tar} will extract files to stdout rather |
3340 |
than to the file system. @xref{Writing to Standard Output}. |
3341 |
|
3342 |
@opsummary{totals} |
3343 |
@item --totals[=@var{signo}] |
3344 |
|
3345 |
Displays the total number of bytes transferred when processing an |
3346 |
archive. If an argument is given, these data are displayed on |
3347 |
request, when signal @var{signo} is delivered to @command{tar}. |
3348 |
@xref{totals}. |
3349 |
|
3350 |
@opsummary{touch} |
3351 |
@item --touch |
3352 |
@itemx -m |
3353 |
|
3354 |
Sets the data modification time of extracted files to the extraction time, |
3355 |
rather than the data modification time stored in the archive. |
3356 |
@xref{Data Modification Times}. |
3357 |
|
3358 |
@opsummary{transform} |
3359 |
@opsummary{xform} |
3360 |
@item --transform=@var{sed-expr} |
3361 |
@itemx --xform=@var{sed-expr} |
3362 |
Transform file or member names using @command{sed} replacement expression |
3363 |
@var{sed-expr}. For example, |
3364 |
|
3365 |
@smallexample |
3366 |
$ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .} |
3367 |
@end smallexample |
3368 |
|
3369 |
@noindent |
3370 |
will add to @file{archive} files from the current working directory, |
3371 |
replacing initial @samp{./} prefix with @samp{usr/}. For the detailed |
3372 |
discussion, @xref{transform}. |
3373 |
|
3374 |
To see transformed member names in verbose listings, use |
3375 |
@option{--show-transformed-names} option |
3376 |
(@pxref{show-transformed-names}). |
3377 |
|
3378 |
@opsummary{uncompress} |
3379 |
@item --uncompress |
3380 |
|
3381 |
(See @option{--compress}, @pxref{gzip}) |
3382 |
|
3383 |
@opsummary{ungzip} |
3384 |
@item --ungzip |
3385 |
|
3386 |
(See @option{--gzip}, @pxref{gzip}) |
3387 |
|
3388 |
@opsummary{unlink-first} |
3389 |
@item --unlink-first |
3390 |
@itemx -U |
3391 |
|
3392 |
Directs @command{tar} to remove the corresponding file from the file |
3393 |
system before extracting it from the archive. @xref{Unlink First}. |
3394 |
|
3395 |
@opsummary{unquote} |
3396 |
@item --unquote |
3397 |
Enable unquoting input file or member names (default). @xref{input |
3398 |
name quoting}. |
3399 |
|
3400 |
@opsummary{use-compress-program} |
3401 |
@item --use-compress-program=@var{prog} |
3402 |
@itemx -I=@var{prog} |
3403 |
|
3404 |
Instructs @command{tar} to access the archive through @var{prog}, which is |
3405 |
presumed to be a compression program of some sort. @xref{gzip}. |
3406 |
|
3407 |
@opsummary{utc} |
3408 |
@item --utc |
3409 |
|
3410 |
Display file modification dates in @acronym{UTC}. This option implies |
3411 |
@option{--verbose}. |
3412 |
|
3413 |
@opsummary{verbose} |
3414 |
@item --verbose |
3415 |
@itemx -v |
3416 |
|
3417 |
Specifies that @command{tar} should be more verbose about the |
3418 |
operations it is performing. This option can be specified multiple |
3419 |
times for some operations to increase the amount of information displayed. |
3420 |
@xref{verbose}. |
3421 |
|
3422 |
@opsummary{verify} |
3423 |
@item --verify |
3424 |
@itemx -W |
3425 |
|
3426 |
Verifies that the archive was correctly written when creating an |
3427 |
archive. @xref{verify}. |
3428 |
|
3429 |
@opsummary{version} |
3430 |
@item --version |
3431 |
|
3432 |
Print information about the program's name, version, origin and legal |
3433 |
status, all on standard output, and then exit successfully. |
3434 |
@xref{help}. |
3435 |
|
3436 |
@opsummary{volno-file} |
3437 |
@item --volno-file=@var{file} |
3438 |
|
3439 |
Used in conjunction with @option{--multi-volume}. @command{tar} will |
3440 |
keep track of which volume of a multi-volume archive it is working in |
3441 |
@var{file}. @xref{volno-file}. |
3442 |
|
3443 |
@opsummary{warning} |
3444 |
@item --warning=@var{keyword} |
3445 |
|
3446 |
Enable or disable warning messages identified by @var{keyword}. The |
3447 |
messages are suppressed if @var{keyword} is prefixed with @samp{no-}. |
3448 |
@xref{warnings}. |
3449 |
|
3450 |
@opsummary{wildcards} |
3451 |
@item --wildcards |
3452 |
Use wildcards when matching member names with patterns. |
3453 |
@xref{controlling pattern-matching}. |
3454 |
|
3455 |
@opsummary{wildcards-match-slash} |
3456 |
@item --wildcards-match-slash |
3457 |
Wildcards match @samp{/}. |
3458 |
@xref{controlling pattern-matching}. |
3459 |
|
3460 |
@opsummary{xz} |
3461 |
@item --xz |
3462 |
@itemx -J |
3463 |
Use @command{xz} for compressing or decompressing the archives. @xref{gzip}. |
3464 |
|
3465 |
@end table |
3466 |
|
3467 |
@node Short Option Summary |
3468 |
@subsection Short Options Cross Reference |
3469 |
|
3470 |
Here is an alphabetized list of all of the short option forms, matching |
3471 |
them with the equivalent long option. |
3472 |
|
3473 |
@multitable @columnfractions 0.20 0.80 |
3474 |
@headitem Short Option @tab Reference |
3475 |
|
3476 |
@item -A @tab @ref{--concatenate}. |
3477 |
|
3478 |
@item -B @tab @ref{--read-full-records}. |
3479 |
|
3480 |
@item -C @tab @ref{--directory}. |
3481 |
|
3482 |
@item -F @tab @ref{--info-script}. |
3483 |
|
3484 |
@item -G @tab @ref{--incremental}. |
3485 |
|
3486 |
@item -J @tab @ref{--xz}. |
3487 |
|
3488 |
@item -K @tab @ref{--starting-file}. |
3489 |
|
3490 |
@item -L @tab @ref{--tape-length}. |
3491 |
|
3492 |
@item -M @tab @ref{--multi-volume}. |
3493 |
|
3494 |
@item -N @tab @ref{--newer}. |
3495 |
|
3496 |
@item -O @tab @ref{--to-stdout}. |
3497 |
|
3498 |
@item -P @tab @ref{--absolute-names}. |
3499 |
|
3500 |
@item -R @tab @ref{--block-number}. |
3501 |
|
3502 |
@item -S @tab @ref{--sparse}. |
3503 |
|
3504 |
@item -T @tab @ref{--files-from}. |
3505 |
|
3506 |
@item -U @tab @ref{--unlink-first}. |
3507 |
|
3508 |
@item -V @tab @ref{--label}. |
3509 |
|
3510 |
@item -W @tab @ref{--verify}. |
3511 |
|
3512 |
@item -X @tab @ref{--exclude-from}. |
3513 |
|
3514 |
@item -Z @tab @ref{--compress}. |
3515 |
|
3516 |
@item -b @tab @ref{--blocking-factor}. |
3517 |
|
3518 |
@item -c @tab @ref{--create}. |
3519 |
|
3520 |
@item -d @tab @ref{--compare}. |
3521 |
|
3522 |
@item -f @tab @ref{--file}. |
3523 |
|
3524 |
@item -g @tab @ref{--listed-incremental}. |
3525 |
|
3526 |
@item -h @tab @ref{--dereference}. |
3527 |
|
3528 |
@item -i @tab @ref{--ignore-zeros}. |
3529 |
|
3530 |
@item -j @tab @ref{--bzip2}. |
3531 |
|
3532 |
@item -k @tab @ref{--keep-old-files}. |
3533 |
|
3534 |
@item -l @tab @ref{--check-links}. |
3535 |
|
3536 |
@item -m @tab @ref{--touch}. |
3537 |
|
3538 |
@item -o @tab When creating, @ref{--no-same-owner}, when extracting --- |
3539 |
@ref{--portability}. |
3540 |
|
3541 |
The latter usage is deprecated. It is retained for compatibility with |
3542 |
the earlier versions of @GNUTAR{}. In future releases |
3543 |
@option{-o} will be equivalent to @option{--no-same-owner} only. |
3544 |
|
3545 |
@item -p @tab @ref{--preserve-permissions}. |
3546 |
|
3547 |
@item -r @tab @ref{--append}. |
3548 |
|
3549 |
@item -s @tab @ref{--same-order}. |
3550 |
|
3551 |
@item -t @tab @ref{--list}. |
3552 |
|
3553 |
@item -u @tab @ref{--update}. |
3554 |
|
3555 |
@item -v @tab @ref{--verbose}. |
3556 |
|
3557 |
@item -w @tab @ref{--interactive}. |
3558 |
|
3559 |
@item -x @tab @ref{--extract}. |
3560 |
|
3561 |
@item -z @tab @ref{--gzip}. |
3562 |
|
3563 |
@end multitable |
3564 |
|
3565 |
@node help |
3566 |
@section @GNUTAR{} documentation |
3567 |
|
3568 |
@cindex Getting program version number |
3569 |
@opindex version |
3570 |
@cindex Version of the @command{tar} program |
3571 |
Being careful, the first thing is really checking that you are using |
3572 |
@GNUTAR{}, indeed. The @option{--version} option |
3573 |
causes @command{tar} to print information about its name, version, |
3574 |
origin and legal status, all on standard output, and then exit |
3575 |
successfully. For example, @w{@samp{tar --version}} might print: |
3576 |
|
3577 |
@smallexample |
3578 |
tar (GNU tar) @value{VERSION} |
3579 |
Copyright (C) 2010 Free Software Foundation, Inc. |
3580 |
Copyright (C) 2010 Free Software Foundation, Inc. |
3581 |
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. |
3582 |
This is free software: you are free to change and redistribute it. |
3583 |
There is NO WARRANTY, to the extent permitted by law. |
3584 |
|
3585 |
Written by John Gilmore and Jay Fenlason. |
3586 |
@end smallexample |
3587 |
|
3588 |
@noindent |
3589 |
The first occurrence of @samp{tar} in the result above is the program |
3590 |
name in the package (for example, @command{rmt} is another program), |
3591 |
while the second occurrence of @samp{tar} is the name of the package |
3592 |
itself, containing possibly many programs. The package is currently |
3593 |
named @samp{tar}, after the name of the main program it |
3594 |
contains@footnote{There are plans to merge the @command{cpio} and |
3595 |
@command{tar} packages into a single one which would be called |
3596 |
@code{paxutils}. So, who knows if, one of this days, the |
3597 |
@option{--version} would not output @w{@samp{tar (@acronym{GNU} |
3598 |
paxutils) 3.2}}.}. |
3599 |
|
3600 |
@cindex Obtaining help |
3601 |
@cindex Listing all @command{tar} options |
3602 |
@xopindex{help, introduction} |
3603 |
Another thing you might want to do is checking the spelling or meaning |
3604 |
of some particular @command{tar} option, without resorting to this |
3605 |
manual, for once you have carefully read it. @GNUTAR{} |
3606 |
has a short help feature, triggerable through the |
3607 |
@option{--help} option. By using this option, @command{tar} will |
3608 |
print a usage message listing all available options on standard |
3609 |
output, then exit successfully, without doing anything else and |
3610 |
ignoring all other options. Even if this is only a brief summary, it |
3611 |
may be several screens long. So, if you are not using some kind of |
3612 |
scrollable window, you might prefer to use something like: |
3613 |
|
3614 |
@smallexample |
3615 |
$ @kbd{tar --help | less} |
3616 |
@end smallexample |
3617 |
|
3618 |
@noindent |
3619 |
presuming, here, that you like using @command{less} for a pager. Other |
3620 |
popular pagers are @command{more} and @command{pg}. If you know about some |
3621 |
@var{keyword} which interests you and do not want to read all the |
3622 |
@option{--help} output, another common idiom is doing: |
3623 |
|
3624 |
@smallexample |
3625 |
tar --help | grep @var{keyword} |
3626 |
@end smallexample |
3627 |
|
3628 |
@noindent |
3629 |
for getting only the pertinent lines. Notice, however, that some |
3630 |
@command{tar} options have long description lines and the above |
3631 |
command will list only the first of them. |
3632 |
|
3633 |
The exact look of the option summary displayed by @kbd{tar --help} is |
3634 |
configurable. @xref{Configuring Help Summary}, for a detailed description. |
3635 |
|
3636 |
@opindex usage |
3637 |
If you only wish to check the spelling of an option, running @kbd{tar |
3638 |
--usage} may be a better choice. This will display a terse list of |
3639 |
@command{tar} options without accompanying explanations. |
3640 |
|
3641 |
The short help output is quite succinct, and you might have to get |
3642 |
back to the full documentation for precise points. If you are reading |
3643 |
this paragraph, you already have the @command{tar} manual in some |
3644 |
form. This manual is available in a variety of forms from |
3645 |
@url{http://www.gnu.org/software/tar/manual}. It may be printed out of the @GNUTAR{} |
3646 |
distribution, provided you have @TeX{} already installed somewhere, |
3647 |
and a laser printer around. Just configure the distribution, execute |
3648 |
the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the |
3649 |
usual way (contact your local guru to know how). If @GNUTAR{} |
3650 |
has been conveniently installed at your place, this |
3651 |
manual is also available in interactive, hypertextual form as an Info |
3652 |
file. Just call @w{@samp{info tar}} or, if you do not have the |
3653 |
@command{info} program handy, use the Info reader provided within |
3654 |
@acronym{GNU} Emacs, calling @samp{tar} from the main Info menu. |
3655 |
|
3656 |
There is currently no @code{man} page for @GNUTAR{}. |
3657 |
If you observe such a @code{man} page on the system you are running, |
3658 |
either it does not belong to @GNUTAR{}, or it has not |
3659 |
been produced by @acronym{GNU}. Some package maintainers convert |
3660 |
@kbd{tar --help} output to a man page, using @command{help2man}. In |
3661 |
any case, please bear in mind that the authoritative source of |
3662 |
information about @GNUTAR{} is this Texinfo documentation. |
3663 |
|
3664 |
@node defaults |
3665 |
@section Obtaining @GNUTAR{} default values |
3666 |
|
3667 |
@opindex show-defaults |
3668 |
@GNUTAR{} has some predefined defaults that are used when you do not |
3669 |
explicitly specify another values. To obtain a list of such |
3670 |
defaults, use @option{--show-defaults} option. This will output the |
3671 |
values in the form of @command{tar} command line options: |
3672 |
|
3673 |
@smallexample |
3674 |
@group |
3675 |
$ @kbd{tar --show-defaults} |
3676 |
--format=gnu -f- -b20 --quoting-style=escape |
3677 |
--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh |
3678 |
@end group |
3679 |
@end smallexample |
3680 |
|
3681 |
@noindent |
3682 |
Notice, that this option outputs only one line. The example output above |
3683 |
has been split to fit page boundaries. |
3684 |
|
3685 |
@noindent |
3686 |
The above output shows that this version of @GNUTAR{} defaults to |
3687 |
using @samp{gnu} archive format (@pxref{Formats}), it uses standard |
3688 |
output as the archive, if no @option{--file} option has been given |
3689 |
(@pxref{file tutorial}), the default blocking factor is 20 |
3690 |
(@pxref{Blocking Factor}). It also shows the default locations where |
3691 |
@command{tar} will look for @command{rmt} and @command{rsh} binaries. |
3692 |
|
3693 |
@node verbose |
3694 |
@section Checking @command{tar} progress |
3695 |
|
3696 |
Typically, @command{tar} performs most operations without reporting any |
3697 |
information to the user except error messages. When using @command{tar} |
3698 |
with many options, particularly ones with complicated or |
3699 |
difficult-to-predict behavior, it is possible to make serious mistakes. |
3700 |
@command{tar} provides several options that make observing @command{tar} |
3701 |
easier. These options cause @command{tar} to print information as it |
3702 |
progresses in its job, and you might want to use them just for being |
3703 |
more careful about what is going on, or merely for entertaining |
3704 |
yourself. If you have encountered a problem when operating on an |
3705 |
archive, however, you may need more information than just an error |
3706 |
message in order to solve the problem. The following options can be |
3707 |
helpful diagnostic tools. |
3708 |
|
3709 |
@cindex Verbose operation |
3710 |
@opindex verbose |
3711 |
Normally, the @option{--list} (@option{-t}) command to list an archive |
3712 |
prints just the file names (one per line) and the other commands are |
3713 |
silent. When used with most operations, the @option{--verbose} |
3714 |
(@option{-v}) option causes @command{tar} to print the name of each |
3715 |
file or archive member as it is processed. This and the other options |
3716 |
which make @command{tar} print status information can be useful in |
3717 |
monitoring @command{tar}. |
3718 |
|
3719 |
With @option{--create} or @option{--extract}, @option{--verbose} used |
3720 |
once just prints the names of the files or members as they are processed. |
3721 |
Using it twice causes @command{tar} to print a longer listing |
3722 |
(@xref{verbose member listing}, for the description) for each member. |
3723 |
Since @option{--list} already prints the names of the members, |
3724 |
@option{--verbose} used once with @option{--list} causes @command{tar} |
3725 |
to print an @samp{ls -l} type listing of the files in the archive. |
3726 |
The following examples both extract members with long list output: |
3727 |
|
3728 |
@smallexample |
3729 |
$ @kbd{tar --extract --file=archive.tar --verbose --verbose} |
3730 |
$ @kbd{tar xvvf archive.tar} |
3731 |
@end smallexample |
3732 |
|
3733 |
Verbose output appears on the standard output except when an archive is |
3734 |
being written to the standard output, as with @samp{tar --create |
3735 |
--file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the |
3736 |
installer let standard output be the default archive). In that case |
3737 |
@command{tar} writes verbose output to the standard error stream. |
3738 |
|
3739 |
If @option{--index-file=@var{file}} is specified, @command{tar} sends |
3740 |
verbose output to @var{file} rather than to standard output or standard |
3741 |
error. |
3742 |
|
3743 |
@anchor{totals} |
3744 |
@cindex Obtaining total status information |
3745 |
@opindex totals |
3746 |
The @option{--totals} option causes @command{tar} to print on the |
3747 |
standard error the total amount of bytes transferred when processing |
3748 |
an archive. When creating or appending to an archive, this option |
3749 |
prints the number of bytes written to the archive and the average |
3750 |
speed at which they have been written, e.g.: |
3751 |
|
3752 |
@smallexample |
3753 |
@group |
3754 |
$ @kbd{tar -c -f archive.tar --totals /home} |
3755 |
Total bytes written: 7924664320 (7.4GiB, 85MiB/s) |
3756 |
@end group |
3757 |
@end smallexample |
3758 |
|
3759 |
When reading an archive, this option displays the number of bytes |
3760 |
read: |
3761 |
|
3762 |
@smallexample |
3763 |
@group |
3764 |
$ @kbd{tar -x -f archive.tar --totals} |
3765 |
Total bytes read: 7924664320 (7.4GiB, 95MiB/s) |
3766 |
@end group |
3767 |
@end smallexample |
3768 |
|
3769 |
Finally, when deleting from an archive, the @option{--totals} option |
3770 |
displays both numbers plus number of bytes removed from the archive: |
3771 |
|
3772 |
@smallexample |
3773 |
@group |
3774 |
$ @kbd{tar --delete -f foo.tar --totals --wildcards '*~'} |
3775 |
Total bytes read: 9543680 (9.2MiB, 201MiB/s) |
3776 |
Total bytes written: 3829760 (3.7MiB, 81MiB/s) |
3777 |
Total bytes deleted: 1474048 |
3778 |
@end group |
3779 |
@end smallexample |
3780 |
|
3781 |
You can also obtain this information on request. When |
3782 |
@option{--totals} is used with an argument, this argument is |
3783 |
interpreted as a symbolic name of a signal, upon delivery of which the |
3784 |
statistics is to be printed: |
3785 |
|
3786 |
@table @option |
3787 |
@item --totals=@var{signo} |
3788 |
Print statistics upon delivery of signal @var{signo}. Valid arguments |
3789 |
are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and |
3790 |
@code{SIGUSR2}. Shortened names without @samp{SIG} prefix are also |
3791 |
accepted. |
3792 |
@end table |
3793 |
|
3794 |
Both forms of @option{--totals} option can be used simultaneously. |
3795 |
Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to |
3796 |
extract all members from its default archive and print statistics |
3797 |
after finishing the extraction, as well as when receiving signal |
3798 |
@code{SIGUSR1}. |
3799 |
|
3800 |
@anchor{Progress information} |
3801 |
@cindex Progress information |
3802 |
The @option{--checkpoint} option prints an occasional message |
3803 |
as @command{tar} reads or writes the archive. It is designed for |
3804 |
those who don't need the more detailed (and voluminous) output of |
3805 |
@option{--block-number} (@option{-R}), but do want visual confirmation |
3806 |
that @command{tar} is actually making forward progress. By default it |
3807 |
prints a message each 10 records read or written. This can be changed |
3808 |
by giving it a numeric argument after an equal sign: |
3809 |
|
3810 |
@smallexample |
3811 |
$ @kbd{tar -c --checkpoint=1000} /var |
3812 |
tar: Write checkpoint 1000 |
3813 |
tar: Write checkpoint 2000 |
3814 |
tar: Write checkpoint 3000 |
3815 |
@end smallexample |
3816 |
|
3817 |
This example shows the default checkpoint message used by |
3818 |
@command{tar}. If you place a dot immediately after the equal |
3819 |
sign, it will print a @samp{.} at each checkpoint@footnote{This is |
3820 |
actually a shortcut for @option{--checkpoint=@var{n} |
3821 |
--checkpoint-action=dot}. @xref{checkpoints, dot}.}. For example: |
3822 |
|
3823 |
@smallexample |
3824 |
$ @kbd{tar -c --checkpoint=.1000} /var |
3825 |
... |
3826 |
@end smallexample |
3827 |
|
3828 |
The @option{--checkpoint} option provides a flexible mechanism for |
3829 |
executing arbitrary actions upon hitting checkpoints, see the next |
3830 |
section (@pxref{checkpoints}), for more information on it. |
3831 |
|
3832 |
@opindex show-omitted-dirs |
3833 |
@anchor{show-omitted-dirs} |
3834 |
The @option{--show-omitted-dirs} option, when reading an archive---with |
3835 |
@option{--list} or @option{--extract}, for example---causes a message |
3836 |
to be printed for each directory in the archive which is skipped. |
3837 |
This happens regardless of the reason for skipping: the directory might |
3838 |
not have been named on the command line (implicitly or explicitly), |
3839 |
it might be excluded by the use of the |
3840 |
@option{--exclude=@var{pattern}} option, or some other reason. |
3841 |
|
3842 |
@opindex block-number |
3843 |
@cindex Block number where error occurred |
3844 |
@anchor{block-number} |
3845 |
If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along with |
3846 |
every message it would normally produce, the block number within the |
3847 |
archive where the message was triggered. Also, supplementary messages |
3848 |
are triggered when reading blocks full of NULs, or when hitting end of |
3849 |
file on the archive. As of now, if the archive is properly terminated |
3850 |
with a NUL block, the reading of the file may stop before end of file |
3851 |
is met, so the position of end of file will not usually show when |
3852 |
@option{--block-number} (@option{-R}) is used. Note that @GNUTAR{} |
3853 |
drains the archive before exiting when reading the |
3854 |
archive from a pipe. |
3855 |
|
3856 |
@cindex Error message, block number of |
3857 |
This option is especially useful when reading damaged archives, since |
3858 |
it helps pinpoint the damaged sections. It can also be used with |
3859 |
@option{--list} (@option{-t}) when listing a file-system backup tape, allowing you to |
3860 |
choose among several backup tapes when retrieving a file later, in |
3861 |
favor of the tape where the file appears earliest (closest to the |
3862 |
front of the tape). @xref{backup}. |
3863 |
|
3864 |
@node checkpoints |
3865 |
@section Checkpoints |
3866 |
@cindex checkpoints, defined |
3867 |
@opindex checkpoint |
3868 |
@opindex checkpoint-action |
3869 |
|
3870 |
A @dfn{checkpoint} is a moment of time before writing @var{n}th record to |
3871 |
the archive (a @dfn{write checkpoint}), or before reading @var{n}th record |
3872 |
from the archive (a @dfn{read checkpoint}). Checkpoints allow to |
3873 |
periodically execute arbitrary actions. |
3874 |
|
3875 |
The checkpoint facility is enabled using the following option: |
3876 |
|
3877 |
@table @option |
3878 |
@xopindex{checkpoint, defined} |
3879 |
@item --checkpoint[=@var{n}] |
3880 |
Schedule checkpoints before writing or reading each @var{n}th record. |
3881 |
The default value for @var{n} is 10. |
3882 |
@end table |
3883 |
|
3884 |
A list of arbitrary @dfn{actions} can be executed at each checkpoint. |
3885 |
These actions include: pausing, displaying textual messages, and |
3886 |
executing arbitrary external programs. Actions are defined using |
3887 |
the @option{--checkpoint-action} option. |
3888 |
|
3889 |
@table @option |
3890 |
@xopindex{checkpoint-action, defined} |
3891 |
@item --checkpoint-action=@var{action} |
3892 |
Execute an @var{action} at each checkpoint. |
3893 |
@end table |
3894 |
|
3895 |
@cindex @code{echo}, checkpoint action |
3896 |
The simplest value of @var{action} is @samp{echo}. It instructs |
3897 |
@command{tar} to display the default message on the standard error |
3898 |
stream upon arriving at each checkpoint. The default message is (in |
3899 |
@acronym{POSIX} locale) @samp{Write checkpoint @var{n}}, for write |
3900 |
checkpoints, and @samp{Read checkpoint @var{n}}, for read checkpoints. |
3901 |
Here, @var{n} represents ordinal number of the checkpoint. |
3902 |
|
3903 |
In another locales, translated versions of this message are used. |
3904 |
|
3905 |
This is the default action, so running: |
3906 |
|
3907 |
@smallexample |
3908 |
$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=echo} /var |
3909 |
@end smallexample |
3910 |
|
3911 |
@noindent |
3912 |
is equivalent to: |
3913 |
|
3914 |
@smallexample |
3915 |
$ @kbd{tar -c --checkpoint=1000} /var |
3916 |
@end smallexample |
3917 |
|
3918 |
The @samp{echo} action also allows to supply a customized message. |
3919 |
You do so by placing an equals sign and the message right after it, |
3920 |
e.g.: |
3921 |
|
3922 |
@smallexample |
3923 |
--checkpoint-action="echo=Hit %s checkpoint #%u" |
3924 |
@end smallexample |
3925 |
|
3926 |
The @samp{%s} and @samp{%u} in the above example are |
3927 |
@dfn{meta-characters}. The @samp{%s} meta-character is replaced with |
3928 |
the @dfn{type} of the checkpoint: @samp{write} or |
3929 |
@samp{read} (or a corresponding translated version in locales other |
3930 |
than @acronym{POSIX}). The @samp{%u} meta-character is replaced with |
3931 |
the ordinal number of the checkpoint. Thus, the above example could |
3932 |
produce the following output when used with the @option{--create} |
3933 |
option: |
3934 |
|
3935 |
@smallexample |
3936 |
tar: Hit write checkpoint #10 |
3937 |
tar: Hit write checkpoint #20 |
3938 |
tar: Hit write checkpoint #30 |
3939 |
@end smallexample |
3940 |
|
3941 |
Aside from meta-character expansion, the message string is subject to |
3942 |
@dfn{unquoting}, during which the backslash @dfn{escape sequences} are |
3943 |
replaced with their corresponding @acronym{ASCII} characters |
3944 |
(@pxref{escape sequences}). E.g. the following action will produce an |
3945 |
audible bell and the message described above at each checkpoint: |
3946 |
|
3947 |
@smallexample |
3948 |
--checkpoint-action='echo=\aHit %s checkpoint #%u' |
3949 |
@end smallexample |
3950 |
|
3951 |
@cindex @code{bell}, checkpoint action |
3952 |
There is also a special action which produces an audible signal: |
3953 |
@samp{bell}. It is not equivalent to @samp{echo='\a'}, because |
3954 |
@samp{bell} sends the bell directly to the console (@file{/dev/tty}), |
3955 |
whereas @samp{echo='\a'} sends it to the standard error. |
3956 |
|
3957 |
@cindex @code{ttyout}, checkpoint action |
3958 |
The @samp{ttyout=@var{string}} action outputs @var{string} to |
3959 |
@file{/dev/tty}, so it can be used even if the standard output is |
3960 |
redirected elsewhere. The @var{string} is subject to the same |
3961 |
modifications as with @samp{echo} action. In contrast to the latter, |
3962 |
@samp{ttyout} does not prepend @command{tar} executable name to the |
3963 |
string, nor does it output a newline after it. For example, the |
3964 |
following action will print the checkpoint message at the same screen |
3965 |
line, overwriting any previous message: |
3966 |
|
3967 |
@smallexample |
3968 |
--checkpoint-action="ttyout=\rHit %s checkpoint #%u" |
3969 |
@end smallexample |
3970 |
|
3971 |
@cindex @code{dot}, checkpoint action |
3972 |
Another available checkpoint action is @samp{dot} (or @samp{.}). It |
3973 |
instructs @command{tar} to print a single dot on the standard listing |
3974 |
stream, e.g.: |
3975 |
|
3976 |
@smallexample |
3977 |
$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=dot} /var |
3978 |
... |
3979 |
@end smallexample |
3980 |
|
3981 |
For compatibility with previous @GNUTAR{} versions, this action can |
3982 |
be abbreviated by placing a dot in front of the checkpoint frequency, |
3983 |
as shown in the previous section. |
3984 |
|
3985 |
@cindex @code{sleep}, checkpoint action |
3986 |
Yet another action, @samp{sleep}, pauses @command{tar} for a specified |
3987 |
amount of seconds. The following example will stop for 30 seconds at each |
3988 |
checkpoint: |
3989 |
|
3990 |
@smallexample |
3991 |
$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=sleep=30} |
3992 |
@end smallexample |
3993 |
|
3994 |
@cindex @code{exec}, checkpoint action |
3995 |
Finally, the @code{exec} action executes a given external program. |
3996 |
For example: |
3997 |
|
3998 |
@smallexample |
3999 |
$ @kbd{tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint} |
4000 |
@end smallexample |
4001 |
|
4002 |
This program is executed using @command{/bin/sh -c}, with no |
4003 |
additional arguments. Its exit code is ignored. It gets a copy of |
4004 |
@command{tar}'s environment plus the following variables: |
4005 |
|
4006 |
@table @env |
4007 |
@vrindex TAR_VERSION, checkpoint script environment |
4008 |
@item TAR_VERSION |
4009 |
@GNUTAR{} version number. |
4010 |
|
4011 |
@vrindex TAR_ARCHIVE, checkpoint script environment |
4012 |
@item TAR_ARCHIVE |
4013 |
The name of the archive @command{tar} is processing. |
4014 |
|
4015 |
@vrindex TAR_BLOCKING_FACTOR, checkpoint script environment |
4016 |
@item TAR_BLOCKING_FACTOR |
4017 |
Current blocking factor (@pxref{Blocking}). |
4018 |
|
4019 |
@vrindex TAR_CHECKPOINT, checkpoint script environment |
4020 |
@item TAR_CHECKPOINT |
4021 |
Number of the checkpoint. |
4022 |
|
4023 |
@vrindex TAR_SUBCOMMAND, checkpoint script environment |
4024 |
@item TAR_SUBCOMMAND |
4025 |
A short option describing the operation @command{tar} is executing. |
4026 |
@xref{Operations}, for a complete list of subcommand options. |
4027 |
|
4028 |
@vrindex TAR_FORMAT, checkpoint script environment |
4029 |
@item TAR_FORMAT |
4030 |
Format of the archive being processed. @xref{Formats}, for a complete |
4031 |
list of archive format names. |
4032 |
@end table |
4033 |
|
4034 |
Any number of actions can be defined, by supplying several |
4035 |
@option{--checkpoint-action} options in the command line. For |
4036 |
example, the command below displays two messages, pauses |
4037 |
execution for 30 seconds and executes the @file{/sbin/cpoint} script: |
4038 |
|
4039 |
@example |
4040 |
@group |
4041 |
$ @kbd{tar -c -f arc.tar \ |
4042 |
--checkpoint-action='\aecho=Hit %s checkpoint #%u' \ |
4043 |
--checkpoint-action='echo=Sleeping for 30 seconds' \ |
4044 |
--checkpoint-action='sleep=30' \ |
4045 |
--checkpoint-action='exec=/sbin/cpoint'} |
4046 |
@end group |
4047 |
@end example |
4048 |
|
4049 |
This example also illustrates the fact that |
4050 |
@option{--checkpoint-action} can be used without |
4051 |
@option{--checkpoint}. In this case, the default checkpoint frequency |
4052 |
(at each 10th record) is assumed. |
4053 |
|
4054 |
@node warnings |
4055 |
@section Controlling Warning Messages |
4056 |
|
4057 |
Sometimes, while performing the requested task, @GNUTAR{} notices |
4058 |
some conditions that are not exactly errors, but which the user |
4059 |
should be aware of. When this happens, @command{tar} issues a |
4060 |
@dfn{warning message} describing the condition. Warning messages |
4061 |
are output to the standard error and they do not affect the exit |
4062 |
code of @command{tar} command. |
4063 |
|
4064 |
@xopindex{warning, explained} |
4065 |
@GNUTAR{} allows the user to suppress some or all of its warning |
4066 |
messages: |
4067 |
|
4068 |
@table @option |
4069 |
@item --warning=@var{keyword} |
4070 |
Control display of the warning messages identified by @var{keyword}. |
4071 |
If @var{keyword} starts with the prefix @samp{no-}, such messages are |
4072 |
suppressed. Otherwise, they are enabled. |
4073 |
|
4074 |
Multiple @option{--warning} messages accumulate. |
4075 |
|
4076 |
The tables below list allowed values for @var{keyword} along with the |
4077 |
warning messages they control. |
4078 |
@end table |
4079 |
|
4080 |
@subheading Keywords controlling @command{tar} operation |
4081 |
@table @asis |
4082 |
@kwindex all |
4083 |
@item all |
4084 |
Enable all warning messages. This is the default. |
4085 |
@kwindex none |
4086 |
@item none |
4087 |
Disable all warning messages. |
4088 |
@kwindex filename-with-nuls |
4089 |
@cindex @samp{file name read contains nul character}, warning message |
4090 |
@item filename-with-nuls |
4091 |
@samp{%s: file name read contains nul character} |
4092 |
@kwindex alone-zero-block |
4093 |
@cindex @samp{A lone zero block at}, warning message |
4094 |
@item alone-zero-block |
4095 |
@samp{A lone zero block at %s} |
4096 |
@end table |
4097 |
|
4098 |
@subheading Keywords applicable for @command{tar --create} |
4099 |
@table @asis |
4100 |
@kwindex cachedir |
4101 |
@cindex @samp{contains a cache directory tag}, warning message |
4102 |
@item cachedir |
4103 |
@samp{%s: contains a cache directory tag %s; %s} |
4104 |
@kwindex file-shrank |
4105 |
@cindex @samp{File shrank by %s bytes}, warning message |
4106 |
@item file-shrank |
4107 |
@samp{%s: File shrank by %s bytes; padding with zeros} |
4108 |
@kwindex xdev |
4109 |
@cindex @samp{file is on a different filesystem}, warning message |
4110 |
@item xdev |
4111 |
@samp{%s: file is on a different filesystem; not dumped} |
4112 |
@kwindex file-ignored |
4113 |
@cindex @samp{Unknown file type; file ignored}, warning message |
4114 |
@cindex @samp{socket ignored}, warning message |
4115 |
@cindex @samp{door ignored}, warning message |
4116 |
@item file-ignored |
4117 |
@samp{%s: Unknown file type; file ignored} |
4118 |
@*@samp{%s: socket ignored} |
4119 |
@*@samp{%s: door ignored} |
4120 |
@kwindex file-unchanged |
4121 |
@cindex @samp{file is unchanged; not dumped}, warning message |
4122 |
@item file-unchanged |
4123 |
@samp{%s: file is unchanged; not dumped} |
4124 |
@kwindex ignore-archive |
4125 |
@cindex @samp{file is the archive; not dumped}, warning message |
4126 |
@kwindex ignore-archive |
4127 |
@cindex @samp{file is the archive; not dumped}, warning message |
4128 |
@item ignore-archive |
4129 |
@samp{%s: file is the archive; not dumped} |
4130 |
@kwindex file-removed |
4131 |
@cindex @samp{File removed before we read it}, warning message |
4132 |
@item file-removed |
4133 |
@samp{%s: File removed before we read it} |
4134 |
@kwindex file-changed |
4135 |
@cindex @samp{file changed as we read it}, warning message |
4136 |
@item file-changed |
4137 |
@samp{%s: file changed as we read it} |
4138 |
@end table |
4139 |
|
4140 |
@subheading Keywords applicable for @command{tar --extract} |
4141 |
@table @asis |
4142 |
@kwindex timestamp |
4143 |
@cindex @samp{implausibly old time stamp %s}, warning message |
4144 |
@cindex @samp{time stamp %s is %s s in the future}, warning message |
4145 |
@item timestamp |
4146 |
@samp{%s: implausibly old time stamp %s} |
4147 |
@*@samp{%s: time stamp %s is %s s in the future} |
4148 |
@kwindex contiguous-cast |
4149 |
@cindex @samp{Extracting contiguous files as regular files}, warning message |
4150 |
@item contiguous-cast |
4151 |
@samp{Extracting contiguous files as regular files} |
4152 |
@kwindex symlink-cast |
4153 |
@cindex @samp{Attempting extraction of symbolic links as hard links}, warning message |
4154 |
@item symlink-cast |
4155 |
@samp{Attempting extraction of symbolic links as hard links} |
4156 |
@kwindex unknown-cast |
4157 |
@cindex @samp{Unknown file type `%c', extracted as normal file}, warning message |
4158 |
@item unknown-cast |
4159 |
@samp{%s: Unknown file type `%c', extracted as normal file} |
4160 |
@kwindex ignore-newer |
4161 |
@cindex @samp{Current %s is newer or same age}, warning message |
4162 |
@item ignore-newer |
4163 |
@samp{Current %s is newer or same age} |
4164 |
@kwindex unknown-keyword |
4165 |
@cindex @samp{Ignoring unknown extended header keyword `%s'}, warning message |
4166 |
@item unknown-keyword |
4167 |
@samp{Ignoring unknown extended header keyword `%s'} |
4168 |
@kwindex decompress-program |
4169 |
@item decompress-program |
4170 |
Controls verbose description of failures occurring when trying to run |
4171 |
alternative decompressor programs (@pxref{alternative decompression |
4172 |
programs}). This warning is disabled by default (unless |
4173 |
@option{--verbose} is used). A common example of what you can get |
4174 |
when using this warning is: |
4175 |
|
4176 |
@smallexample |
4177 |
$ @kbd{tar --warning=decompress-program -x -f archive.Z} |
4178 |
tar (child): cannot run compress: No such file or directory |
4179 |
tar (child): trying gzip |
4180 |
@end smallexample |
4181 |
|
4182 |
This means that @command{tar} first tried to decompress |
4183 |
@file{archive.Z} using @command{compress}, and, when that |
4184 |
failed, switched to @command{gzip}. |
4185 |
@end table |
4186 |
|
4187 |
@subheading Keywords controlling incremental extraction: |
4188 |
@table @asis |
4189 |
@kwindex rename-directory |
4190 |
@cindex @samp{%s: Directory has been renamed from %s}, warning message |
4191 |
@cindex @samp{%s: Directory has been renamed}, warning message |
4192 |
@item rename-directory |
4193 |
@samp{%s: Directory has been renamed from %s} |
4194 |
@*@samp{%s: Directory has been renamed} |
4195 |
@kwindex new-directory |
4196 |
@cindex @samp{%s: Directory is new}, warning message |
4197 |
@item new-directory |
4198 |
@samp{%s: Directory is new} |
4199 |
@kwindex xdev |
4200 |
@cindex @samp{%s: directory is on a different device: not purging}, warning message |
4201 |
@item xdev |
4202 |
@samp{%s: directory is on a different device: not purging} |
4203 |
@kwindex bad-dumpdir |
4204 |
@cindex @samp{Malformed dumpdir: 'X' never used}, warning message |
4205 |
@item bad-dumpdir |
4206 |
@samp{Malformed dumpdir: 'X' never used} |
4207 |
@end table |
4208 |
|
4209 |
@node interactive |
4210 |
@section Asking for Confirmation During Operations |
4211 |
@cindex Interactive operation |
4212 |
|
4213 |
Typically, @command{tar} carries out a command without stopping for |
4214 |
further instructions. In some situations however, you may want to |
4215 |
exclude some files and archive members from the operation (for instance |
4216 |
if disk or storage space is tight). You can do this by excluding |
4217 |
certain files automatically (@pxref{Choosing}), or by performing |
4218 |
an operation interactively, using the @option{--interactive} (@option{-w}) option. |
4219 |
@command{tar} also accepts @option{--confirmation} for this option. |
4220 |
|
4221 |
@opindex interactive |
4222 |
When the @option{--interactive} (@option{-w}) option is specified, before |
4223 |
reading, writing, or deleting files, @command{tar} first prints a message |
4224 |
for each such file, telling what operation it intends to take, then asks |
4225 |
for confirmation on the terminal. The actions which require |
4226 |
confirmation include adding a file to the archive, extracting a file |
4227 |
from the archive, deleting a file from the archive, and deleting a file |
4228 |
from disk. To confirm the action, you must type a line of input |
4229 |
beginning with @samp{y}. If your input line begins with anything other |
4230 |
than @samp{y}, @command{tar} skips that file. |
4231 |
|
4232 |
If @command{tar} is reading the archive from the standard input, |
4233 |
@command{tar} opens the file @file{/dev/tty} to support the interactive |
4234 |
communications. |
4235 |
|
4236 |
Verbose output is normally sent to standard output, separate from |
4237 |
other error messages. However, if the archive is produced directly |
4238 |
on standard output, then verbose output is mixed with errors on |
4239 |
@code{stderr}. Producing the archive on standard output may be used |
4240 |
as a way to avoid using disk space, when the archive is soon to be |
4241 |
consumed by another process reading it, say. Some people felt the need |
4242 |
of producing an archive on stdout, still willing to segregate between |
4243 |
verbose output and error output. A possible approach would be using a |
4244 |
named pipe to receive the archive, and having the consumer process to |
4245 |
read from that named pipe. This has the advantage of letting standard |
4246 |
output free to receive verbose output, all separate from errors. |
4247 |
|
4248 |
@node operations |
4249 |
@chapter @GNUTAR{} Operations |
4250 |
|
4251 |
@menu |
4252 |
* Basic tar:: |
4253 |
* Advanced tar:: |
4254 |
* create options:: |
4255 |
* extract options:: |
4256 |
* backup:: |
4257 |
* Applications:: |
4258 |
* looking ahead:: |
4259 |
@end menu |
4260 |
|
4261 |
@node Basic tar |
4262 |
@section Basic @GNUTAR{} Operations |
4263 |
|
4264 |
The basic @command{tar} operations, @option{--create} (@option{-c}), |
4265 |
@option{--list} (@option{-t}) and @option{--extract} (@option{--get}, |
4266 |
@option{-x}), are currently presented and described in the tutorial |
4267 |
chapter of this manual. This section provides some complementary notes |
4268 |
for these operations. |
4269 |
|
4270 |
@table @option |
4271 |
@xopindex{create, complementary notes} |
4272 |
@item --create |
4273 |
@itemx -c |
4274 |
|
4275 |
Creating an empty archive would have some kind of elegance. One can |
4276 |
initialize an empty archive and later use @option{--append} |
4277 |
(@option{-r}) for adding all members. Some applications would not |
4278 |
welcome making an exception in the way of adding the first archive |
4279 |
member. On the other hand, many people reported that it is |
4280 |
dangerously too easy for @command{tar} to destroy a magnetic tape with |
4281 |
an empty archive@footnote{This is well described in @cite{Unix-haters |
4282 |
Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG |
4283 |
Books, ISBN 1-56884-203-1.}. The two most common errors are: |
4284 |
|
4285 |
@enumerate |
4286 |
@item |
4287 |
Mistakingly using @code{create} instead of @code{extract}, when the |
4288 |
intent was to extract the full contents of an archive. This error |
4289 |
is likely: keys @kbd{c} and @kbd{x} are right next to each other on |
4290 |
the QWERTY keyboard. Instead of being unpacked, the archive then |
4291 |
gets wholly destroyed. When users speak about @dfn{exploding} an |
4292 |
archive, they usually mean something else :-). |
4293 |
|
4294 |
@item |
4295 |
Forgetting the argument to @code{file}, when the intent was to create |
4296 |
an archive with a single file in it. This error is likely because a |
4297 |
tired user can easily add the @kbd{f} key to the cluster of option |
4298 |
letters, by the mere force of habit, without realizing the full |
4299 |
consequence of doing so. The usual consequence is that the single |
4300 |
file, which was meant to be saved, is rather destroyed. |
4301 |
@end enumerate |
4302 |
|
4303 |
So, recognizing the likelihood and the catastrophic nature of these |
4304 |
errors, @GNUTAR{} now takes some distance from elegance, and |
4305 |
cowardly refuses to create an archive when @option{--create} option is |
4306 |
given, there are no arguments besides options, and |
4307 |
@option{--files-from} (@option{-T}) option is @emph{not} used. To get |
4308 |
around the cautiousness of @GNUTAR{} and nevertheless create an |
4309 |
archive with nothing in it, one may still use, as the value for the |
4310 |
@option{--files-from} option, a file with no names in it, as shown in |
4311 |
the following commands: |
4312 |
|
4313 |
@smallexample |
4314 |
@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null} |
4315 |
@kbd{tar cfT empty-archive.tar /dev/null} |
4316 |
@end smallexample |
4317 |
|
4318 |
@xopindex{extract, complementary notes} |
4319 |
@item --extract |
4320 |
@itemx --get |
4321 |
@itemx -x |
4322 |
|
4323 |
A socket is stored, within a @GNUTAR{} archive, as a pipe. |
4324 |
|
4325 |
@item @option{--list} (@option{-t}) |
4326 |
|
4327 |
@GNUTAR{} now shows dates as @samp{1996-08-30}, |
4328 |
while it used to show them as @samp{Aug 30 1996}. Preferably, |
4329 |
people should get used to ISO 8601 dates. Local American dates should |
4330 |
be made available again with full date localization support, once |
4331 |
ready. In the meantime, programs not being localizable for dates |
4332 |
should prefer international dates, that's really the way to go. |
4333 |
|
4334 |
Look up @url{http://www.cl.cam.ac.uk/@/~mgk25/@/iso-time.html} if you |
4335 |
are curious, it contains a detailed explanation of the ISO 8601 standard. |
4336 |
|
4337 |
@end table |
4338 |
|
4339 |
@node Advanced tar |
4340 |
@section Advanced @GNUTAR{} Operations |
4341 |
|
4342 |
Now that you have learned the basics of using @GNUTAR{}, you may want |
4343 |
to learn about further ways in which @command{tar} can help you. |
4344 |
|
4345 |
This chapter presents five, more advanced operations which you probably |
4346 |
won't use on a daily basis, but which serve more specialized functions. |
4347 |
We also explain the different styles of options and why you might want |
4348 |
to use one or another, or a combination of them in your @command{tar} |
4349 |
commands. Additionally, this chapter includes options which allow you to |
4350 |
define the output from @command{tar} more carefully, and provide help and |
4351 |
error correction in special circumstances. |
4352 |
|
4353 |
@FIXME{check this after the chapter is actually revised to make sure |
4354 |
it still introduces the info in the chapter correctly : ).} |
4355 |
|
4356 |
@menu |
4357 |
* Operations:: |
4358 |
* append:: |
4359 |
* update:: |
4360 |
* concatenate:: |
4361 |
* delete:: |
4362 |
* compare:: |
4363 |
@end menu |
4364 |
|
4365 |
@node Operations |
4366 |
@subsection The Five Advanced @command{tar} Operations |
4367 |
|
4368 |
@cindex basic operations |
4369 |
In the last chapter, you learned about the first three operations to |
4370 |
@command{tar}. This chapter presents the remaining five operations to |
4371 |
@command{tar}: @option{--append}, @option{--update}, @option{--concatenate}, |
4372 |
@option{--delete}, and @option{--compare}. |
4373 |
|
4374 |
You are not likely to use these operations as frequently as those |
4375 |
covered in the last chapter; however, since they perform specialized |
4376 |
functions, they are quite useful when you do need to use them. We |
4377 |
will give examples using the same directory and files that you created |
4378 |
in the last chapter. As you may recall, the directory is called |
4379 |
@file{practice}, the files are @samp{jazz}, @samp{blues}, @samp{folk}, |
4380 |
and the two archive files you created are |
4381 |
@samp{collection.tar} and @samp{music.tar}. |
4382 |
|
4383 |
We will also use the archive files @samp{afiles.tar} and |
4384 |
@samp{bfiles.tar}. The archive @samp{afiles.tar} contains the members @samp{apple}, |
4385 |
@samp{angst}, and @samp{aspic}; @samp{bfiles.tar} contains the members |
4386 |
@samp{./birds}, @samp{baboon}, and @samp{./box}. |
4387 |
|
4388 |
Unless we state otherwise, all practicing you do and examples you follow |
4389 |
in this chapter will take place in the @file{practice} directory that |
4390 |
you created in the previous chapter; see @ref{prepare for examples}. |
4391 |
(Below in this section, we will remind you of the state of the examples |
4392 |
where the last chapter left them.) |
4393 |
|
4394 |
The five operations that we will cover in this chapter are: |
4395 |
|
4396 |
@table @option |
4397 |
@item --append |
4398 |
@itemx -r |
4399 |
Add new entries to an archive that already exists. |
4400 |
@item --update |
4401 |
@itemx -u |
4402 |
Add more recent copies of archive members to the end of an archive, if |
4403 |
they exist. |
4404 |
@item --concatenate |
4405 |
@itemx --catenate |
4406 |
@itemx -A |
4407 |
Add one or more pre-existing archives to the end of another archive. |
4408 |
@item --delete |
4409 |
Delete items from an archive (does not work on tapes). |
4410 |
@item --compare |
4411 |
@itemx --diff |
4412 |
@itemx -d |
4413 |
Compare archive members to their counterparts in the file system. |
4414 |
@end table |
4415 |
|
4416 |
@node append |
4417 |
@subsection How to Add Files to Existing Archives: @option{--append} |
4418 |
|
4419 |
@cindex appending files to existing archive |
4420 |
@opindex append |
4421 |
If you want to add files to an existing archive, you don't need to |
4422 |
create a new archive; you can use @option{--append} (@option{-r}). |
4423 |
The archive must already exist in order to use @option{--append}. (A |
4424 |
related operation is the @option{--update} operation; you can use this |
4425 |
to add newer versions of archive members to an existing archive. To learn how to |
4426 |
do this with @option{--update}, @pxref{update}.) |
4427 |
|
4428 |
If you use @option{--append} to add a file that has the same name as an |
4429 |
archive member to an archive containing that archive member, then the |
4430 |
old member is not deleted. What does happen, however, is somewhat |
4431 |
complex. @command{tar} @emph{allows} you to have infinite number of files |
4432 |
with the same name. Some operations treat these same-named members no |
4433 |
differently than any other set of archive members: for example, if you |
4434 |
view an archive with @option{--list} (@option{-t}), you will see all |
4435 |
of those members listed, with their data modification times, owners, etc. |
4436 |
|
4437 |
Other operations don't deal with these members as perfectly as you might |
4438 |
prefer; if you were to use @option{--extract} to extract the archive, |
4439 |
only the most recently added copy of a member with the same name as |
4440 |
other members would end up in the working directory. This is because |
4441 |
@option{--extract} extracts an archive in the order the members appeared |
4442 |
in the archive; the most recently archived members will be extracted |
4443 |
last. Additionally, an extracted member will @emph{replace} a file of |
4444 |
the same name which existed in the directory already, and @command{tar} |
4445 |
will not prompt you about this@footnote{Unless you give it |
4446 |
@option{--keep-old-files} option, or the disk copy is newer than |
4447 |
the one in the archive and you invoke @command{tar} with |
4448 |
@option{--keep-newer-files} option.}. Thus, only the most recently archived |
4449 |
member will end up being extracted, as it will replace the one |
4450 |
extracted before it, and so on. |
4451 |
|
4452 |
@cindex extracting @var{n}th copy of the file |
4453 |
@xopindex{occurrence, described} |
4454 |
There exists a special option that allows you to get around this |
4455 |
behavior and extract (or list) only a particular copy of the file. |
4456 |
This is @option{--occurrence} option. If you run @command{tar} with |
4457 |
this option, it will extract only the first copy of the file. You |
4458 |
may also give this option an argument specifying the number of |
4459 |
copy to be extracted. Thus, for example if the archive |
4460 |
@file{archive.tar} contained three copies of file @file{myfile}, then |
4461 |
the command |
4462 |
|
4463 |
@smallexample |
4464 |
tar --extract --file archive.tar --occurrence=2 myfile |
4465 |
@end smallexample |
4466 |
|
4467 |
@noindent |
4468 |
would extract only the second copy. @xref{Option |
4469 |
Summary,---occurrence}, for the description of @option{--occurrence} |
4470 |
option. |
4471 |
|
4472 |
@FIXME{ hag -- you might want to incorporate some of the above into the |
4473 |
MMwtSN node; not sure. i didn't know how to make it simpler... |
4474 |
|
4475 |
There are a few ways to get around this. Xref to Multiple Members |
4476 |
with the Same Name, maybe.} |
4477 |
|
4478 |
@cindex Members, replacing with other members |
4479 |
@cindex Replacing members with other members |
4480 |
@xopindex{delete, using before --append} |
4481 |
If you want to replace an archive member, use @option{--delete} to |
4482 |
delete the member you want to remove from the archive, and then use |
4483 |
@option{--append} to add the member you want to be in the archive. Note |
4484 |
that you can not change the order of the archive; the most recently |
4485 |
added member will still appear last. In this sense, you cannot truly |
4486 |
``replace'' one member with another. (Replacing one member with another |
4487 |
will not work on certain types of media, such as tapes; see @ref{delete} |
4488 |
and @ref{Media}, for more information.) |
4489 |
|
4490 |
@menu |
4491 |
* appending files:: Appending Files to an Archive |
4492 |
* multiple:: |
4493 |
@end menu |
4494 |
|
4495 |
@node appending files |
4496 |
@subsubsection Appending Files to an Archive |
4497 |
@cindex Adding files to an Archive |
4498 |
@cindex Appending files to an Archive |
4499 |
@cindex Archives, Appending files to |
4500 |
@opindex append |
4501 |
|
4502 |
The simplest way to add a file to an already existing archive is the |
4503 |
@option{--append} (@option{-r}) operation, which writes specified |
4504 |
files into the archive whether or not they are already among the |
4505 |
archived files. |
4506 |
|
4507 |
When you use @option{--append}, you @emph{must} specify file name |
4508 |
arguments, as there is no default. If you specify a file that already |
4509 |
exists in the archive, another copy of the file will be added to the |
4510 |
end of the archive. As with other operations, the member names of the |
4511 |
newly added files will be exactly the same as their names given on the |
4512 |
command line. The @option{--verbose} (@option{-v}) option will print |
4513 |
out the names of the files as they are written into the archive. |
4514 |
|
4515 |
@option{--append} cannot be performed on some tape drives, unfortunately, |
4516 |
due to deficiencies in the formats those tape drives use. The archive |
4517 |
must be a valid @command{tar} archive, or else the results of using this |
4518 |
operation will be unpredictable. @xref{Media}. |
4519 |
|
4520 |
To demonstrate using @option{--append} to add a file to an archive, |
4521 |
create a file called @file{rock} in the @file{practice} directory. |
4522 |
Make sure you are in the @file{practice} directory. Then, run the |
4523 |
following @command{tar} command to add @file{rock} to |
4524 |
@file{collection.tar}: |
4525 |
|
4526 |
@smallexample |
4527 |
$ @kbd{tar --append --file=collection.tar rock} |
4528 |
@end smallexample |
4529 |
|
4530 |
@noindent |
4531 |
If you now use the @option{--list} (@option{-t}) operation, you will see that |
4532 |
@file{rock} has been added to the archive: |
4533 |
|
4534 |
@smallexample |
4535 |
$ @kbd{tar --list --file=collection.tar} |
4536 |
-rw-r--r-- me/user 28 1996-10-18 16:31 jazz |
4537 |
-rw-r--r-- me/user 21 1996-09-23 16:44 blues |
4538 |
-rw-r--r-- me/user 20 1996-09-23 16:44 folk |
4539 |
-rw-r--r-- me/user 20 1996-09-23 16:44 rock |
4540 |
@end smallexample |
4541 |
|
4542 |
@node multiple |
4543 |
@subsubsection Multiple Members with the Same Name |
4544 |
@cindex members, multiple |
4545 |
@cindex multiple members |
4546 |
|
4547 |
You can use @option{--append} (@option{-r}) to add copies of files |
4548 |
which have been updated since the archive was created. (However, we |
4549 |
do not recommend doing this since there is another @command{tar} |
4550 |
option called @option{--update}; @xref{update}, for more information. |
4551 |
We describe this use of @option{--append} here for the sake of |
4552 |
completeness.) When you extract the archive, the older version will |
4553 |
be effectively lost. This works because files are extracted from an |
4554 |
archive in the order in which they were archived. Thus, when the |
4555 |
archive is extracted, a file archived later in time will replace a |
4556 |
file of the same name which was archived earlier, even though the |
4557 |
older version of the file will remain in the archive unless you delete |
4558 |
all versions of the file. |
4559 |
|
4560 |
Supposing you change the file @file{blues} and then append the changed |
4561 |
version to @file{collection.tar}. As you saw above, the original |
4562 |
@file{blues} is in the archive @file{collection.tar}. If you change the |
4563 |
file and append the new version of the file to the archive, there will |
4564 |
be two copies in the archive. When you extract the archive, the older |
4565 |
version of the file will be extracted first, and then replaced by the |
4566 |
newer version when it is extracted. |
4567 |
|
4568 |
You can append the new, changed copy of the file @file{blues} to the |
4569 |
archive in this way: |
4570 |
|
4571 |
@smallexample |
4572 |
$ @kbd{tar --append --verbose --file=collection.tar blues} |
4573 |
blues |
4574 |
@end smallexample |
4575 |
|
4576 |
@noindent |
4577 |
Because you specified the @option{--verbose} option, @command{tar} has |
4578 |
printed the name of the file being appended as it was acted on. Now |
4579 |
list the contents of the archive: |
4580 |
|
4581 |
@smallexample |
4582 |
$ @kbd{tar --list --verbose --file=collection.tar} |
4583 |
-rw-r--r-- me/user 28 1996-10-18 16:31 jazz |
4584 |
-rw-r--r-- me/user 21 1996-09-23 16:44 blues |
4585 |
-rw-r--r-- me/user 20 1996-09-23 16:44 folk |
4586 |
-rw-r--r-- me/user 20 1996-09-23 16:44 rock |
4587 |
-rw-r--r-- me/user 58 1996-10-24 18:30 blues |
4588 |
@end smallexample |
4589 |
|
4590 |
@noindent |
4591 |
The newest version of @file{blues} is now at the end of the archive |
4592 |
(note the different creation dates and file sizes). If you extract |
4593 |
the archive, the older version of the file @file{blues} will be |
4594 |
replaced by the newer version. You can confirm this by extracting |
4595 |
the archive and running @samp{ls} on the directory. |
4596 |
|
4597 |
If you wish to extract the first occurrence of the file @file{blues} |
4598 |
from the archive, use @option{--occurrence} option, as shown in |
4599 |
the following example: |
4600 |
|
4601 |
@smallexample |
4602 |
$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues} |
4603 |
-rw-r--r-- me/user 21 1996-09-23 16:44 blues |
4604 |
@end smallexample |
4605 |
|
4606 |
@xref{Writing}, for more information on @option{--extract} and |
4607 |
see @ref{Option Summary, --occurrence}, for a description of |
4608 |
@option{--occurrence} option. |
4609 |
|
4610 |
@node update |
4611 |
@subsection Updating an Archive |
4612 |
@cindex Updating an archive |
4613 |
@opindex update |
4614 |
|
4615 |
In the previous section, you learned how to use @option{--append} to |
4616 |
add a file to an existing archive. A related operation is |
4617 |
@option{--update} (@option{-u}). The @option{--update} operation |
4618 |
updates a @command{tar} archive by comparing the date of the specified |
4619 |
archive members against the date of the file with the same name. If |
4620 |
the file has been modified more recently than the archive member, then |
4621 |
the newer version of the file is added to the archive (as with |
4622 |
@option{--append}). |
4623 |
|
4624 |
Unfortunately, you cannot use @option{--update} with magnetic tape drives. |
4625 |
The operation will fail. |
4626 |
|
4627 |
@FIXME{other examples of media on which --update will fail? need to ask |
4628 |
charles and/or mib/thomas/dave shevett..} |
4629 |
|
4630 |
Both @option{--update} and @option{--append} work by adding to the end |
4631 |
of the archive. When you extract a file from the archive, only the |
4632 |
version stored last will wind up in the file system, unless you use |
4633 |
the @option{--backup} option. @xref{multiple}, for a detailed discussion. |
4634 |
|
4635 |
@menu |
4636 |
* how to update:: |
4637 |
@end menu |
4638 |
|
4639 |
@node how to update |
4640 |
@subsubsection How to Update an Archive Using @option{--update} |
4641 |
@opindex update |
4642 |
|
4643 |
You must use file name arguments with the @option{--update} |
4644 |
(@option{-u}) operation. If you don't specify any files, |
4645 |
@command{tar} won't act on any files and won't tell you that it didn't |
4646 |
do anything (which may end up confusing you). |
4647 |
|
4648 |
@c note: the above parenthetical added because in fact, this |
4649 |
@c behavior just confused the author. :-) |
4650 |
|
4651 |
To see the @option{--update} option at work, create a new file, |
4652 |
@file{classical}, in your practice directory, and some extra text to the |
4653 |
file @file{blues}, using any text editor. Then invoke @command{tar} with |
4654 |
the @samp{update} operation and the @option{--verbose} (@option{-v}) |
4655 |
option specified, using the names of all the files in the @file{practice} |
4656 |
directory as file name arguments: |
4657 |
|
4658 |
@smallexample |
4659 |
$ @kbd{tar --update -v -f collection.tar blues folk rock classical} |
4660 |
blues |
4661 |
classical |
4662 |
$ |
4663 |
@end smallexample |
4664 |
|
4665 |
@noindent |
4666 |
Because we have specified verbose mode, @command{tar} prints out the names |
4667 |
of the files it is working on, which in this case are the names of the |
4668 |
files that needed to be updated. If you run @samp{tar --list} and look |
4669 |
at the archive, you will see @file{blues} and @file{classical} at its |
4670 |
end. There will be a total of two versions of the member @samp{blues}; |
4671 |
the one at the end will be newer and larger, since you added text before |
4672 |
updating it. |
4673 |
|
4674 |
The reason @command{tar} does not overwrite the older file when updating |
4675 |
it is because writing to the middle of a section of tape is a difficult |
4676 |
process. Tapes are not designed to go backward. @xref{Media}, for more |
4677 |
information about tapes. |
4678 |
|
4679 |
@option{--update} (@option{-u}) is not suitable for performing backups for two |
4680 |
reasons: it does not change directory content entries, and it |
4681 |
lengthens the archive every time it is used. The @GNUTAR{} |
4682 |
options intended specifically for backups are more |
4683 |
efficient. If you need to run backups, please consult @ref{Backups}. |
4684 |
|
4685 |
@node concatenate |
4686 |
@subsection Combining Archives with @option{--concatenate} |
4687 |
|
4688 |
@cindex Adding archives to an archive |
4689 |
@cindex Concatenating Archives |
4690 |
@opindex concatenate |
4691 |
@opindex catenate |
4692 |
@c @cindex @option{-A} described |
4693 |
Sometimes it may be convenient to add a second archive onto the end of |
4694 |
an archive rather than adding individual files to the archive. To add |
4695 |
one or more archives to the end of another archive, you should use the |
4696 |
@option{--concatenate} (@option{--catenate}, @option{-A}) operation. |
4697 |
|
4698 |
To use @option{--concatenate}, give the first archive with |
4699 |
@option{--file} option and name the rest of archives to be |
4700 |
concatenated on the command line. The members, and their member |
4701 |
names, will be copied verbatim from those archives to the first |
4702 |
one@footnote{This can cause multiple members to have the same name. For |
4703 |
information on how this affects reading the archive, see @ref{multiple}.}. |
4704 |
The new, concatenated archive will be called by the same name as the |
4705 |
one given with the @option{--file} option. As usual, if you omit |
4706 |
@option{--file}, @command{tar} will use the value of the environment |
4707 |
variable @env{TAPE}, or, if this has not been set, the default archive name. |
4708 |
|
4709 |
@FIXME{There is no way to specify a new name...} |
4710 |
|
4711 |
To demonstrate how @option{--concatenate} works, create two small archives |
4712 |
called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant |
4713 |
files from @file{practice}: |
4714 |
|
4715 |
@smallexample |
4716 |
$ @kbd{tar -cvf bluesrock.tar blues rock} |
4717 |
blues |
4718 |
rock |
4719 |
$ @kbd{tar -cvf folkjazz.tar folk jazz} |
4720 |
folk |
4721 |
jazz |
4722 |
@end smallexample |
4723 |
|
4724 |
@noindent |
4725 |
If you like, You can run @samp{tar --list} to make sure the archives |
4726 |
contain what they are supposed to: |
4727 |
|
4728 |
@smallexample |
4729 |
$ @kbd{tar -tvf bluesrock.tar} |
4730 |
-rw-r--r-- melissa/user 105 1997-01-21 19:42 blues |
4731 |
-rw-r--r-- melissa/user 33 1997-01-20 15:34 rock |
4732 |
$ @kbd{tar -tvf jazzfolk.tar} |
4733 |
-rw-r--r-- melissa/user 20 1996-09-23 16:44 folk |
4734 |
-rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz |
4735 |
@end smallexample |
4736 |
|
4737 |
We can concatenate these two archives with @command{tar}: |
4738 |
|
4739 |
@smallexample |
4740 |
$ @kbd{cd ..} |
4741 |
$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar} |
4742 |
@end smallexample |
4743 |
|
4744 |
If you now list the contents of the @file{bluesrock.tar}, you will see |
4745 |
that now it also contains the archive members of @file{jazzfolk.tar}: |
4746 |
|
4747 |
@smallexample |
4748 |
$ @kbd{tar --list --file=bluesrock.tar} |
4749 |
blues |
4750 |
rock |
4751 |
folk |
4752 |
jazz |
4753 |
@end smallexample |
4754 |
|
4755 |
When you use @option{--concatenate}, the source and target archives must |
4756 |
already exist and must have been created using compatible format |
4757 |
parameters. Notice, that @command{tar} does not check whether the |
4758 |
archives it concatenates have compatible formats, it does not |
4759 |
even check if the files are really tar archives. |
4760 |
|
4761 |
Like @option{--append} (@option{-r}), this operation cannot be performed on some |
4762 |
tape drives, due to deficiencies in the formats those tape drives use. |
4763 |
|
4764 |
@cindex @code{concatenate} vs @command{cat} |
4765 |
@cindex @command{cat} vs @code{concatenate} |
4766 |
It may seem more intuitive to you to want or try to use @command{cat} to |
4767 |
concatenate two archives instead of using the @option{--concatenate} |
4768 |
operation; after all, @command{cat} is the utility for combining files. |
4769 |
|
4770 |
However, @command{tar} archives incorporate an end-of-file marker which |
4771 |
must be removed if the concatenated archives are to be read properly as |
4772 |
one archive. @option{--concatenate} removes the end-of-archive marker |
4773 |
from the target archive before each new archive is appended. If you use |
4774 |
@command{cat} to combine the archives, the result will not be a valid |
4775 |
@command{tar} format archive. If you need to retrieve files from an |
4776 |
archive that was added to using the @command{cat} utility, use the |
4777 |
@option{--ignore-zeros} (@option{-i}) option. @xref{Ignore Zeros}, for further |
4778 |
information on dealing with archives improperly combined using the |
4779 |
@command{cat} shell utility. |
4780 |
|
4781 |
@node delete |
4782 |
@subsection Removing Archive Members Using @option{--delete} |
4783 |
@cindex Deleting files from an archive |
4784 |
@cindex Removing files from an archive |
4785 |
|
4786 |
@opindex delete |
4787 |
You can remove members from an archive by using the @option{--delete} |
4788 |
option. Specify the name of the archive with @option{--file} |
4789 |
(@option{-f}) and then specify the names of the members to be deleted; |
4790 |
if you list no member names, nothing will be deleted. The |
4791 |
@option{--verbose} option will cause @command{tar} to print the names |
4792 |
of the members as they are deleted. As with @option{--extract}, you |
4793 |
must give the exact member names when using @samp{tar --delete}. |
4794 |
@option{--delete} will remove all versions of the named file from the |
4795 |
archive. The @option{--delete} operation can run very slowly. |
4796 |
|
4797 |
Unlike other operations, @option{--delete} has no short form. |
4798 |
|
4799 |
@cindex Tapes, using @option{--delete} and |
4800 |
@cindex Deleting from tape archives |
4801 |
This operation will rewrite the archive. You can only use |
4802 |
@option{--delete} on an archive if the archive device allows you to |
4803 |
write to any point on the media, such as a disk; because of this, it |
4804 |
does not work on magnetic tapes. Do not try to delete an archive member |
4805 |
from a magnetic tape; the action will not succeed, and you will be |
4806 |
likely to scramble the archive and damage your tape. There is no safe |
4807 |
way (except by completely re-writing the archive) to delete files from |
4808 |
most kinds of magnetic tape. @xref{Media}. |
4809 |
|
4810 |
To delete all versions of the file @file{blues} from the archive |
4811 |
@file{collection.tar} in the @file{practice} directory, make sure you |
4812 |
are in that directory, and then, |
4813 |
|
4814 |
@smallexample |
4815 |
$ @kbd{tar --list --file=collection.tar} |
4816 |
blues |
4817 |
folk |
4818 |
jazz |
4819 |
rock |
4820 |
$ @kbd{tar --delete --file=collection.tar blues} |
4821 |
$ @kbd{tar --list --file=collection.tar} |
4822 |
folk |
4823 |
jazz |
4824 |
rock |
4825 |
@end smallexample |
4826 |
|
4827 |
@FIXME{Check if the above listing is actually produced after running |
4828 |
all the examples on collection.tar.} |
4829 |
|
4830 |
The @option{--delete} option has been reported to work properly when |
4831 |
@command{tar} acts as a filter from @code{stdin} to @code{stdout}. |
4832 |
|
4833 |
@node compare |
4834 |
@subsection Comparing Archive Members with the File System |
4835 |
@cindex Verifying the currency of an archive |
4836 |
|
4837 |
@opindex compare |
4838 |
The @option{--compare} (@option{-d}), or @option{--diff} operation compares |
4839 |
specified archive members against files with the same names, and then |
4840 |
reports differences in file size, mode, owner, modification date and |
4841 |
contents. You should @emph{only} specify archive member names, not file |
4842 |
names. If you do not name any members, then @command{tar} will compare the |
4843 |
entire archive. If a file is represented in the archive but does not |
4844 |
exist in the file system, @command{tar} reports a difference. |
4845 |
|
4846 |
You have to specify the record size of the archive when modifying an |
4847 |
archive with a non-default record size. |
4848 |
|
4849 |
@command{tar} ignores files in the file system that do not have |
4850 |
corresponding members in the archive. |
4851 |
|
4852 |
The following example compares the archive members @file{rock}, |
4853 |
@file{blues} and @file{funk} in the archive @file{bluesrock.tar} with |
4854 |
files of the same name in the file system. (Note that there is no file, |
4855 |
@file{funk}; @command{tar} will report an error message.) |
4856 |
|
4857 |
@smallexample |
4858 |
$ @kbd{tar --compare --file=bluesrock.tar rock blues funk} |
4859 |
rock |
4860 |
blues |
4861 |
tar: funk not found in archive |
4862 |
@end smallexample |
4863 |
|
4864 |
The spirit behind the @option{--compare} (@option{--diff}, |
4865 |
@option{-d}) option is to check whether the archive represents the |
4866 |
current state of files on disk, more than validating the integrity of |
4867 |
the archive media. For this latter goal, see @ref{verify}. |
4868 |
|
4869 |
@node create options |
4870 |
@section Options Used by @option{--create} |
4871 |
|
4872 |
@xopindex{create, additional options} |
4873 |
The previous chapter described the basics of how to use |
4874 |
@option{--create} (@option{-c}) to create an archive from a set of files. |
4875 |
@xref{create}. This section described advanced options to be used with |
4876 |
@option{--create}. |
4877 |
|
4878 |
@menu |
4879 |
* override:: Overriding File Metadata. |
4880 |
* Ignore Failed Read:: |
4881 |
@end menu |
4882 |
|
4883 |
@node override |
4884 |
@subsection Overriding File Metadata |
4885 |
|
4886 |
As described above, a @command{tar} archive keeps, for each member it contains, |
4887 |
its @dfn{metadata}, such as modification time, mode and ownership of |
4888 |
the file. @GNUTAR{} allows to replace these data with other values |
4889 |
when adding files to the archive. The options described in this |
4890 |
section affect creation of archives of any type. For POSIX archives, |
4891 |
see also @ref{PAX keywords}, for additional ways of controlling |
4892 |
metadata, stored in the archive. |
4893 |
|
4894 |
@table @option |
4895 |
@opindex mode |
4896 |
@item --mode=@var{permissions} |
4897 |
|
4898 |
When adding files to an archive, @command{tar} will use |
4899 |
@var{permissions} for the archive members, rather than the permissions |
4900 |
from the files. @var{permissions} can be specified either as an octal |
4901 |
number or as symbolic permissions, like with |
4902 |
@command{chmod} (@xref{File permissions, Permissions, File |
4903 |
permissions, fileutils, @acronym{GNU} file utilities}. This reference |
4904 |
also has useful information for those not being overly familiar with |
4905 |
the UNIX permission system). Using latter syntax allows for |
4906 |
more flexibility. For example, the value @samp{a+rw} adds read and write |
4907 |
permissions for everybody, while retaining executable bits on directories |
4908 |
or on any other file already marked as executable: |
4909 |
|
4910 |
@smallexample |
4911 |
$ @kbd{tar -c -f archive.tar --mode='a+rw' .} |
4912 |
@end smallexample |
4913 |
|
4914 |
@item --mtime=@var{date} |
4915 |
@opindex mtime |
4916 |
|
4917 |
When adding files to an archive, @command{tar} will use @var{date} as |
4918 |
the modification time of members when creating archives, instead of |
4919 |
their actual modification times. The argument @var{date} can be |
4920 |
either a textual date representation in almost arbitrary format |
4921 |
(@pxref{Date input formats}) or a name of an existing file, starting |
4922 |
with @samp{/} or @samp{.}. In the latter case, the modification time |
4923 |
of that file will be used. |
4924 |
|
4925 |
The following example will set the modification date to 00:00:00, |
4926 |
January 1, 1970: |
4927 |
|
4928 |
@smallexample |
4929 |
$ @kbd{tar -c -f archive.tar --mtime='1970-01-01' .} |
4930 |
@end smallexample |
4931 |
|
4932 |
@noindent |
4933 |
When used with @option{--verbose} (@pxref{verbose tutorial}) @GNUTAR{} |
4934 |
will try to convert the specified date back to its textual |
4935 |
representation and compare it with the one given with |
4936 |
@option{--mtime} options. If the two dates differ, @command{tar} will |
4937 |
print a warning saying what date it will use. This is to help user |
4938 |
ensure he is using the right date. |
4939 |
|
4940 |
For example: |
4941 |
|
4942 |
@smallexample |
4943 |
$ @kbd{tar -c -f archive.tar -v --mtime=yesterday .} |
4944 |
tar: Option --mtime: Treating date `yesterday' as 2006-06-20 |
4945 |
13:06:29.152478 |
4946 |
@dots{} |
4947 |
@end smallexample |
4948 |
|
4949 |
@item --owner=@var{user} |
4950 |
@opindex owner |
4951 |
|
4952 |
Specifies that @command{tar} should use @var{user} as the owner of members |
4953 |
when creating archives, instead of the user associated with the source |
4954 |
file. The argument @var{user} can be either an existing user symbolic |
4955 |
name, or a decimal numeric user @acronym{ID}. |
4956 |
|
4957 |
There is no value indicating a missing number, and @samp{0} usually means |
4958 |
@code{root}. Some people like to force @samp{0} as the value to offer in |
4959 |
their distributions for the owner of files, because the @code{root} user is |
4960 |
anonymous anyway, so that might as well be the owner of anonymous |
4961 |
archives. For example: |
4962 |
|
4963 |
@smallexample |
4964 |
$ @kbd{tar -c -f archive.tar --owner=0 .} |
4965 |
@end smallexample |
4966 |
|
4967 |
@noindent |
4968 |
or: |
4969 |
|
4970 |
@smallexample |
4971 |
$ @kbd{tar -c -f archive.tar --owner=root .} |
4972 |
@end smallexample |
4973 |
|
4974 |
@item --group=@var{group} |
4975 |
@opindex group |
4976 |
|
4977 |
Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group}, |
4978 |
rather than the group from the source file. The argument @var{group} |
4979 |
can be either an existing group symbolic name, or a decimal numeric group @acronym{ID}. |
4980 |
@end table |
4981 |
|
4982 |
@node Ignore Failed Read |
4983 |
@subsection Ignore Fail Read |
4984 |
|
4985 |
@table @option |
4986 |
@item --ignore-failed-read |
4987 |
@opindex ignore-failed-read |
4988 |
Do not exit with nonzero on unreadable files or directories. |
4989 |
@end table |
4990 |
|
4991 |
@node extract options |
4992 |
@section Options Used by @option{--extract} |
4993 |
@cindex options for use with @option{--extract} |
4994 |
|
4995 |
@xopindex{extract, additional options} |
4996 |
The previous chapter showed how to use @option{--extract} to extract |
4997 |
an archive into the file system. Various options cause @command{tar} to |
4998 |
extract more information than just file contents, such as the owner, |
4999 |
the permissions, the modification date, and so forth. This section |
5000 |
presents options to be used with @option{--extract} when certain special |
5001 |
considerations arise. You may review the information presented in |
5002 |
@ref{extract} for more basic information about the |
5003 |
@option{--extract} operation. |
5004 |
|
5005 |
@menu |
5006 |
* Reading:: Options to Help Read Archives |
5007 |
* Writing:: Changing How @command{tar} Writes Files |
5008 |
* Scarce:: Coping with Scarce Resources |
5009 |
@end menu |
5010 |
|
5011 |
@node Reading |
5012 |
@subsection Options to Help Read Archives |
5013 |
@cindex Options when reading archives |
5014 |
|
5015 |
@cindex Reading incomplete records |
5016 |
@cindex Records, incomplete |
5017 |
@opindex read-full-records |
5018 |
Normally, @command{tar} will request data in full record increments from |
5019 |
an archive storage device. If the device cannot return a full record, |
5020 |
@command{tar} will report an error. However, some devices do not always |
5021 |
return full records, or do not require the last record of an archive to |
5022 |
be padded out to the next record boundary. To keep reading until you |
5023 |
obtain a full record, or to accept an incomplete record if it contains |
5024 |
an end-of-archive marker, specify the @option{--read-full-records} (@option{-B}) option |
5025 |
in conjunction with the @option{--extract} or @option{--list} operations. |
5026 |
@xref{Blocking}. |
5027 |
|
5028 |
The @option{--read-full-records} (@option{-B}) option is turned on by default when |
5029 |
@command{tar} reads an archive from standard input, or from a remote |
5030 |
machine. This is because on @acronym{BSD} Unix systems, attempting to read a |
5031 |
pipe returns however much happens to be in the pipe, even if it is |
5032 |
less than was requested. If this option were not enabled, @command{tar} |
5033 |
would fail as soon as it read an incomplete record from the pipe. |
5034 |
|
5035 |
If you're not sure of the blocking factor of an archive, you can |
5036 |
read the archive by specifying @option{--read-full-records} (@option{-B}) and |
5037 |
@option{--blocking-factor=@var{512-size}} (@option{-b |
5038 |
@var{512-size}}), using a blocking factor larger than what the archive |
5039 |
uses. This lets you avoid having to determine the blocking factor |
5040 |
of an archive. @xref{Blocking Factor}. |
5041 |
|
5042 |
@menu |
5043 |
* read full records:: |
5044 |
* Ignore Zeros:: |
5045 |
@end menu |
5046 |
|
5047 |
@node read full records |
5048 |
@unnumberedsubsubsec Reading Full Records |
5049 |
|
5050 |
@FIXME{need sentence or so of intro here} |
5051 |
|
5052 |
@table @option |
5053 |
@opindex read-full-records |
5054 |
@item --read-full-records |
5055 |
@item -B |
5056 |
Use in conjunction with @option{--extract} (@option{--get}, |
5057 |
@option{-x}) to read an archive which contains incomplete records, or |
5058 |
one which has a blocking factor less than the one specified. |
5059 |
@end table |
5060 |
|
5061 |
@node Ignore Zeros |
5062 |
@unnumberedsubsubsec Ignoring Blocks of Zeros |
5063 |
|
5064 |
@cindex End-of-archive blocks, ignoring |
5065 |
@cindex Ignoring end-of-archive blocks |
5066 |
@opindex ignore-zeros |
5067 |
Normally, @command{tar} stops reading when it encounters a block of zeros |
5068 |
between file entries (which usually indicates the end of the archive). |
5069 |
@option{--ignore-zeros} (@option{-i}) allows @command{tar} to |
5070 |
completely read an archive which contains a block of zeros before the |
5071 |
end (i.e., a damaged archive, or one that was created by concatenating |
5072 |
several archives together). |
5073 |
|
5074 |
The @option{--ignore-zeros} (@option{-i}) option is turned off by default because many |
5075 |
versions of @command{tar} write garbage after the end-of-archive entry, |
5076 |
since that part of the media is never supposed to be read. @GNUTAR{} |
5077 |
does not write after the end of an archive, but seeks to |
5078 |
maintain compatibility among archiving utilities. |
5079 |
|
5080 |
@table @option |
5081 |
@item --ignore-zeros |
5082 |
@itemx -i |
5083 |
To ignore blocks of zeros (i.e., end-of-archive entries) which may be |
5084 |
encountered while reading an archive. Use in conjunction with |
5085 |
@option{--extract} or @option{--list}. |
5086 |
@end table |
5087 |
|
5088 |
@node Writing |
5089 |
@subsection Changing How @command{tar} Writes Files |
5090 |
@UNREVISED |
5091 |
|
5092 |
@FIXME{Introductory paragraph} |
5093 |
|
5094 |
@menu |
5095 |
* Dealing with Old Files:: |
5096 |
* Overwrite Old Files:: |
5097 |
* Keep Old Files:: |
5098 |
* Keep Newer Files:: |
5099 |
* Unlink First:: |
5100 |
* Recursive Unlink:: |
5101 |
* Data Modification Times:: |
5102 |
* Setting Access Permissions:: |
5103 |
* Directory Modification Times and Permissions:: |
5104 |
* Writing to Standard Output:: |
5105 |
* Writing to an External Program:: |
5106 |
* remove files:: |
5107 |
@end menu |
5108 |
|
5109 |
@node Dealing with Old Files |
5110 |
@unnumberedsubsubsec Options Controlling the Overwriting of Existing Files |
5111 |
|
5112 |
@xopindex{overwrite-dir, introduced} |
5113 |
When extracting files, if @command{tar} discovers that the extracted |
5114 |
file already exists, it normally replaces the file by removing it before |
5115 |
extracting it, to prevent confusion in the presence of hard or symbolic |
5116 |
links. (If the existing file is a symbolic link, it is removed, not |
5117 |
followed.) However, if a directory cannot be removed because it is |
5118 |
nonempty, @command{tar} normally overwrites its metadata (ownership, |
5119 |
permission, etc.). The @option{--overwrite-dir} option enables this |
5120 |
default behavior. To be more cautious and preserve the metadata of |
5121 |
such a directory, use the @option{--no-overwrite-dir} option. |
5122 |
|
5123 |
@cindex Overwriting old files, prevention |
5124 |
@xopindex{keep-old-files, introduced} |
5125 |
To be even more cautious and prevent existing files from being replaced, use |
5126 |
the @option{--keep-old-files} (@option{-k}) option. It causes @command{tar} to refuse |
5127 |
to replace or update a file that already exists, i.e., a file with the |
5128 |
same name as an archive member prevents extraction of that archive |
5129 |
member. Instead, it reports an error. |
5130 |
|
5131 |
@xopindex{overwrite, introduced} |
5132 |
To be more aggressive about altering existing files, use the |
5133 |
@option{--overwrite} option. It causes @command{tar} to overwrite |
5134 |
existing files and to follow existing symbolic links when extracting. |
5135 |
|
5136 |
@cindex Protecting old files |
5137 |
Some people argue that @GNUTAR{} should not hesitate |
5138 |
to overwrite files with other files when extracting. When extracting |
5139 |
a @command{tar} archive, they expect to see a faithful copy of the |
5140 |
state of the file system when the archive was created. It is debatable |
5141 |
that this would always be a proper behavior. For example, suppose one |
5142 |
has an archive in which @file{usr/local} is a link to |
5143 |
@file{usr/local2}. Since then, maybe the site removed the link and |
5144 |
renamed the whole hierarchy from @file{/usr/local2} to |
5145 |
@file{/usr/local}. Such things happen all the time. I guess it would |
5146 |
not be welcome at all that @GNUTAR{} removes the |
5147 |
whole hierarchy just to make room for the link to be reinstated |
5148 |
(unless it @emph{also} simultaneously restores the full |
5149 |
@file{/usr/local2}, of course!) @GNUTAR{} is indeed |
5150 |
able to remove a whole hierarchy to reestablish a symbolic link, for |
5151 |
example, but @emph{only if} @option{--recursive-unlink} is specified |
5152 |
to allow this behavior. In any case, single files are silently |
5153 |
removed. |
5154 |
|
5155 |
@xopindex{unlink-first, introduced} |
5156 |
Finally, the @option{--unlink-first} (@option{-U}) option can improve performance in |
5157 |
some cases by causing @command{tar} to remove files unconditionally |
5158 |
before extracting them. |
5159 |
|
5160 |
@node Overwrite Old Files |
5161 |
@unnumberedsubsubsec Overwrite Old Files |
5162 |
|
5163 |
@table @option |
5164 |
@opindex overwrite |
5165 |
@item --overwrite |
5166 |
Overwrite existing files and directory metadata when extracting files |
5167 |
from an archive. |
5168 |
|
5169 |
This causes @command{tar} to write extracted files into the file system without |
5170 |
regard to the files already on the system; i.e., files with the same |
5171 |
names as archive members are overwritten when the archive is extracted. |
5172 |
It also causes @command{tar} to extract the ownership, permissions, |
5173 |
and time stamps onto any preexisting files or directories. |
5174 |
If the name of a corresponding file name is a symbolic link, the file |
5175 |
pointed to by the symbolic link will be overwritten instead of the |
5176 |
symbolic link itself (if this is possible). Moreover, special devices, |
5177 |
empty directories and even symbolic links are automatically removed if |
5178 |
they are in the way of extraction. |
5179 |
|
5180 |
Be careful when using the @option{--overwrite} option, particularly when |
5181 |
combined with the @option{--absolute-names} (@option{-P}) option, as this combination |
5182 |
can change the contents, ownership or permissions of any file on your |
5183 |
system. Also, many systems do not take kindly to overwriting files that |
5184 |
are currently being executed. |
5185 |
|
5186 |
@opindex overwrite-dir |
5187 |
@item --overwrite-dir |
5188 |
Overwrite the metadata of directories when extracting files from an |
5189 |
archive, but remove other files before extracting. |
5190 |
@end table |
5191 |
|
5192 |
@node Keep Old Files |
5193 |
@unnumberedsubsubsec Keep Old Files |
5194 |
|
5195 |
@table @option |
5196 |
@opindex keep-old-files |
5197 |
@item --keep-old-files |
5198 |
@itemx -k |
5199 |
Do not replace existing files from archive. The |
5200 |
@option{--keep-old-files} (@option{-k}) option prevents @command{tar} |
5201 |
from replacing existing files with files with the same name from the |
5202 |
archive. The @option{--keep-old-files} option is meaningless with |
5203 |
@option{--list} (@option{-t}). Prevents @command{tar} from replacing |
5204 |
files in the file system during extraction. |
5205 |
@end table |
5206 |
|
5207 |
@node Keep Newer Files |
5208 |
@unnumberedsubsubsec Keep Newer Files |
5209 |
|
5210 |
@table @option |
5211 |
@opindex keep-newer-files |
5212 |
@item --keep-newer-files |
5213 |
Do not replace existing files that are newer than their archive |
5214 |
copies. This option is meaningless with @option{--list} (@option{-t}). |
5215 |
@end table |
5216 |
|
5217 |
@node Unlink First |
5218 |
@unnumberedsubsubsec Unlink First |
5219 |
|
5220 |
@table @option |
5221 |
@opindex unlink-first |
5222 |
@item --unlink-first |
5223 |
@itemx -U |
5224 |
Remove files before extracting over them. |
5225 |
This can make @command{tar} run a bit faster if you know in advance |
5226 |
that the extracted files all need to be removed. Normally this option |
5227 |
slows @command{tar} down slightly, so it is disabled by default. |
5228 |
@end table |
5229 |
|
5230 |
@node Recursive Unlink |
5231 |
@unnumberedsubsubsec Recursive Unlink |
5232 |
|
5233 |
@table @option |
5234 |
@opindex recursive-unlink |
5235 |
@item --recursive-unlink |
5236 |
When this option is specified, try removing files and directory hierarchies |
5237 |
before extracting over them. @emph{This is a dangerous option!} |
5238 |
@end table |
5239 |
|
5240 |
If you specify the @option{--recursive-unlink} option, |
5241 |
@command{tar} removes @emph{anything} that keeps you from extracting a file |
5242 |
as far as current permissions will allow it. This could include removal |
5243 |
of the contents of a full directory hierarchy. |
5244 |
|
5245 |
@node Data Modification Times |
5246 |
@unnumberedsubsubsec Setting Data Modification Times |
5247 |
|
5248 |
@cindex Data modification times of extracted files |
5249 |
@cindex Modification times of extracted files |
5250 |
Normally, @command{tar} sets the data modification times of extracted |
5251 |
files to the corresponding times recorded for the files in the archive, but |
5252 |
limits the permissions of extracted files by the current @code{umask} |
5253 |
setting. |
5254 |
|
5255 |
To set the data modification times of extracted files to the time when |
5256 |
the files were extracted, use the @option{--touch} (@option{-m}) option in |
5257 |
conjunction with @option{--extract} (@option{--get}, @option{-x}). |
5258 |
|
5259 |
@table @option |
5260 |
@opindex touch |
5261 |
@item --touch |
5262 |
@itemx -m |
5263 |
Sets the data modification time of extracted archive members to the time |
5264 |
they were extracted, not the time recorded for them in the archive. |
5265 |
Use in conjunction with @option{--extract} (@option{--get}, @option{-x}). |
5266 |
@end table |
5267 |
|
5268 |
@node Setting Access Permissions |
5269 |
@unnumberedsubsubsec Setting Access Permissions |
5270 |
|
5271 |
@cindex Permissions of extracted files |
5272 |
@cindex Modes of extracted files |
5273 |
To set the modes (access permissions) of extracted files to those |
5274 |
recorded for those files in the archive, use @option{--same-permissions} |
5275 |
in conjunction with the @option{--extract} (@option{--get}, |
5276 |
@option{-x}) operation. |
5277 |
|
5278 |
@table @option |
5279 |
@opindex preserve-permissions |
5280 |
@opindex same-permissions |
5281 |
@item --preserve-permissions |
5282 |
@itemx --same-permissions |
5283 |
@c @itemx --ignore-umask |
5284 |
@itemx -p |
5285 |
Set modes of extracted archive members to those recorded in the |
5286 |
archive, instead of current umask settings. Use in conjunction with |
5287 |
@option{--extract} (@option{--get}, @option{-x}). |
5288 |
@end table |
5289 |
|
5290 |
@node Directory Modification Times and Permissions |
5291 |
@unnumberedsubsubsec Directory Modification Times and Permissions |
5292 |
|
5293 |
After successfully extracting a file member, @GNUTAR{} normally |
5294 |
restores its permissions and modification times, as described in the |
5295 |
previous sections. This cannot be done for directories, because |
5296 |
after extracting a directory @command{tar} will almost certainly |
5297 |
extract files into that directory and this will cause the directory |
5298 |
modification time to be updated. Moreover, restoring that directory |
5299 |
permissions may not permit file creation within it. Thus, restoring |
5300 |
directory permissions and modification times must be delayed at least |
5301 |
until all files have been extracted into that directory. @GNUTAR{} |
5302 |
restores directories using the following approach. |
5303 |
|
5304 |
The extracted directories are created with the mode specified in the |
5305 |
archive, as modified by the umask of the user, which gives sufficient |
5306 |
permissions to allow file creation. The meta-information about the |
5307 |
directory is recorded in the temporary list of directories. When |
5308 |
preparing to extract next archive member, @GNUTAR{} checks if the |
5309 |
directory prefix of this file contains the remembered directory. If |
5310 |
it does not, the program assumes that all files have been extracted |
5311 |
into that directory, restores its modification time and permissions |
5312 |
and removes its entry from the internal list. This approach allows |
5313 |
to correctly restore directory meta-information in the majority of |
5314 |
cases, while keeping memory requirements sufficiently small. It is |
5315 |
based on the fact, that most @command{tar} archives use the predefined |
5316 |
order of members: first the directory, then all the files and |
5317 |
subdirectories in that directory. |
5318 |
|
5319 |
However, this is not always true. The most important exception are |
5320 |
incremental archives (@pxref{Incremental Dumps}). The member order in |
5321 |
an incremental archive is reversed: first all directory members are |
5322 |
stored, followed by other (non-directory) members. So, when extracting |
5323 |
from incremental archives, @GNUTAR{} alters the above procedure. It |
5324 |
remembers all restored directories, and restores their meta-data |
5325 |
only after the entire archive has been processed. Notice, that you do |
5326 |
not need to specify any special options for that, as @GNUTAR{} |
5327 |
automatically detects archives in incremental format. |
5328 |
|
5329 |
There may be cases, when such processing is required for normal archives |
5330 |
too. Consider the following example: |
5331 |
|
5332 |
@smallexample |
5333 |
@group |
5334 |
$ @kbd{tar --no-recursion -cvf archive \ |
5335 |
foo foo/file1 bar bar/file foo/file2} |
5336 |
foo/ |
5337 |
foo/file1 |
5338 |
bar/ |
5339 |
bar/file |
5340 |
foo/file2 |
5341 |
@end group |
5342 |
@end smallexample |
5343 |
|
5344 |
During the normal operation, after encountering @file{bar} |
5345 |
@GNUTAR{} will assume that all files from the directory @file{foo} |
5346 |
were already extracted and will therefore restore its timestamp and |
5347 |
permission bits. However, after extracting @file{foo/file2} the |
5348 |
directory timestamp will be offset again. |
5349 |
|
5350 |
To correctly restore directory meta-information in such cases, use |
5351 |
the @option{--delay-directory-restore} command line option: |
5352 |
|
5353 |
@table @option |
5354 |
@opindex delay-directory-restore |
5355 |
@item --delay-directory-restore |
5356 |
Delays restoring of the modification times and permissions of extracted |
5357 |
directories until the end of extraction. This way, correct |
5358 |
meta-information is restored even if the archive has unusual member |
5359 |
ordering. |
5360 |
|
5361 |
@opindex no-delay-directory-restore |
5362 |
@item --no-delay-directory-restore |
5363 |
Cancel the effect of the previous @option{--delay-directory-restore}. |
5364 |
Use this option if you have used @option{--delay-directory-restore} in |
5365 |
@env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to |
5366 |
temporarily disable it. |
5367 |
@end table |
5368 |
|
5369 |
@node Writing to Standard Output |
5370 |
@unnumberedsubsubsec Writing to Standard Output |
5371 |
|
5372 |
@cindex Writing extracted files to standard output |
5373 |
@cindex Standard output, writing extracted files to |
5374 |
To write the extracted files to the standard output, instead of |
5375 |
creating the files on the file system, use @option{--to-stdout} (@option{-O}) in |
5376 |
conjunction with @option{--extract} (@option{--get}, @option{-x}). This option is useful if you are |
5377 |
extracting files to send them through a pipe, and do not need to |
5378 |
preserve them in the file system. If you extract multiple members, |
5379 |
they appear on standard output concatenated, in the order they are |
5380 |
found in the archive. |
5381 |
|
5382 |
@table @option |
5383 |
@opindex to-stdout |
5384 |
@item --to-stdout |
5385 |
@itemx -O |
5386 |
Writes files to the standard output. Use only in conjunction with |
5387 |
@option{--extract} (@option{--get}, @option{-x}). When this option is |
5388 |
used, instead of creating the files specified, @command{tar} writes |
5389 |
the contents of the files extracted to its standard output. This may |
5390 |
be useful if you are only extracting the files in order to send them |
5391 |
through a pipe. This option is meaningless with @option{--list} |
5392 |
(@option{-t}). |
5393 |
@end table |
5394 |
|
5395 |
This can be useful, for example, if you have a tar archive containing |
5396 |
a big file and don't want to store the file on disk before processing |
5397 |
it. You can use a command like this: |
5398 |
|
5399 |
@smallexample |
5400 |
tar -xOzf foo.tgz bigfile | process |
5401 |
@end smallexample |
5402 |
|
5403 |
or even like this if you want to process the concatenation of the files: |
5404 |
|
5405 |
@smallexample |
5406 |
tar -xOzf foo.tgz bigfile1 bigfile2 | process |
5407 |
@end smallexample |
5408 |
|
5409 |
However, @option{--to-command} may be more convenient for use with |
5410 |
multiple files. See the next section. |
5411 |
|
5412 |
@node Writing to an External Program |
5413 |
@unnumberedsubsubsec Writing to an External Program |
5414 |
|
5415 |
You can instruct @command{tar} to send the contents of each extracted |
5416 |
file to the standard input of an external program: |
5417 |
|
5418 |
@table @option |
5419 |
@opindex to-command |
5420 |
@item --to-command=@var{command} |
5421 |
Extract files and pipe their contents to the standard input of |
5422 |
@var{command}. When this option is used, instead of creating the |
5423 |
files specified, @command{tar} invokes @var{command} and pipes the |
5424 |
contents of the files to its standard output. The @var{command} may |
5425 |
contain command line arguments. The program is executed via |
5426 |
@code{sh -c}. Notice, that @var{command} is executed once for each regular file |
5427 |
extracted. Non-regular files (directories, etc.) are ignored when this |
5428 |
option is used. |
5429 |
@end table |
5430 |
|
5431 |
The command can obtain the information about the file it processes |
5432 |
from the following environment variables: |
5433 |
|
5434 |
@table @env |
5435 |
@vrindex TAR_FILETYPE, to-command environment |
5436 |
@item TAR_FILETYPE |
5437 |
Type of the file. It is a single letter with the following meaning: |
5438 |
|
5439 |
@multitable @columnfractions 0.10 0.90 |
5440 |
@item f @tab Regular file |
5441 |
@item d @tab Directory |
5442 |
@item l @tab Symbolic link |
5443 |
@item h @tab Hard link |
5444 |
@item b @tab Block device |
5445 |
@item c @tab Character device |
5446 |
@end multitable |
5447 |
|
5448 |
Currently only regular files are supported. |
5449 |
|
5450 |
@vrindex TAR_MODE, to-command environment |
5451 |
@item TAR_MODE |
5452 |
File mode, an octal number. |
5453 |
|
5454 |
@vrindex TAR_FILENAME, to-command environment |
5455 |
@item TAR_FILENAME |
5456 |
The name of the file. |
5457 |
|
5458 |
@vrindex TAR_REALNAME, to-command environment |
5459 |
@item TAR_REALNAME |
5460 |
Name of the file as stored in the archive. |
5461 |
|
5462 |
@vrindex TAR_UNAME, to-command environment |
5463 |
@item TAR_UNAME |
5464 |
Name of the file owner. |
5465 |
|
5466 |
@vrindex TAR_GNAME, to-command environment |
5467 |
@item TAR_GNAME |
5468 |
Name of the file owner group. |
5469 |
|
5470 |
@vrindex TAR_ATIME, to-command environment |
5471 |
@item TAR_ATIME |
5472 |
Time of last access. It is a decimal number, representing seconds |
5473 |
since the Epoch. If the archive provides times with nanosecond |
5474 |
precision, the nanoseconds are appended to the timestamp after a |
5475 |
decimal point. |
5476 |
|
5477 |
@vrindex TAR_MTIME, to-command environment |
5478 |
@item TAR_MTIME |
5479 |
Time of last modification. |
5480 |
|
5481 |
@vrindex TAR_CTIME, to-command environment |
5482 |
@item TAR_CTIME |
5483 |
Time of last status change. |
5484 |
|
5485 |
@vrindex TAR_SIZE, to-command environment |
5486 |
@item TAR_SIZE |
5487 |
Size of the file. |
5488 |
|
5489 |
@vrindex TAR_UID, to-command environment |
5490 |
@item TAR_UID |
5491 |
UID of the file owner. |
5492 |
|
5493 |
@vrindex TAR_GID, to-command environment |
5494 |
@item TAR_GID |
5495 |
GID of the file owner. |
5496 |
@end table |
5497 |
|
5498 |
Additionally, the following variables contain information about |
5499 |
tar mode and the archive being processed: |
5500 |
|
5501 |
@table @env |
5502 |
@vrindex TAR_VERSION, to-command environment |
5503 |
@item TAR_VERSION |
5504 |
@GNUTAR{} version number. |
5505 |
|
5506 |
@vrindex TAR_ARCHIVE, to-command environment |
5507 |
@item TAR_ARCHIVE |
5508 |
The name of the archive @command{tar} is processing. |
5509 |
|
5510 |
@vrindex TAR_BLOCKING_FACTOR, to-command environment |
5511 |
@item TAR_BLOCKING_FACTOR |
5512 |
Current blocking factor (@pxref{Blocking}). |
5513 |
|
5514 |
@vrindex TAR_VOLUME, to-command environment |
5515 |
@item TAR_VOLUME |
5516 |
Ordinal number of the volume @command{tar} is processing. |
5517 |
|
5518 |
@vrindex TAR_FORMAT, to-command environment |
5519 |
@item TAR_FORMAT |
5520 |
Format of the archive being processed. @xref{Formats}, for a complete |
5521 |
list of archive format names. |
5522 |
@end table |
5523 |
|
5524 |
If @var{command} exits with a non-0 status, @command{tar} will print |
5525 |
an error message similar to the following: |
5526 |
|
5527 |
@smallexample |
5528 |
tar: 2345: Child returned status 1 |
5529 |
@end smallexample |
5530 |
|
5531 |
Here, @samp{2345} is the PID of the finished process. |
5532 |
|
5533 |
If this behavior is not wanted, use @option{--ignore-command-error}: |
5534 |
|
5535 |
@table @option |
5536 |
@opindex ignore-command-error |
5537 |
@item --ignore-command-error |
5538 |
Ignore exit codes of subprocesses. Notice that if the program |
5539 |
exits on signal or otherwise terminates abnormally, the error message |
5540 |
will be printed even if this option is used. |
5541 |
|
5542 |
@opindex no-ignore-command-error |
5543 |
@item --no-ignore-command-error |
5544 |
Cancel the effect of any previous @option{--ignore-command-error} |
5545 |
option. This option is useful if you have set |
5546 |
@option{--ignore-command-error} in @env{TAR_OPTIONS} |
5547 |
(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it. |
5548 |
@end table |
5549 |
|
5550 |
@node remove files |
5551 |
@unnumberedsubsubsec Removing Files |
5552 |
|
5553 |
@FIXME{The section is too terse. Something more to add? An example, |
5554 |
maybe?} |
5555 |
|
5556 |
@table @option |
5557 |
@opindex remove-files |
5558 |
@item --remove-files |
5559 |
Remove files after adding them to the archive. |
5560 |
@end table |
5561 |
|
5562 |
@node Scarce |
5563 |
@subsection Coping with Scarce Resources |
5564 |
@UNREVISED |
5565 |
|
5566 |
@cindex Small memory |
5567 |
@cindex Running out of space |
5568 |
|
5569 |
@menu |
5570 |
* Starting File:: |
5571 |
* Same Order:: |
5572 |
@end menu |
5573 |
|
5574 |
@node Starting File |
5575 |
@unnumberedsubsubsec Starting File |
5576 |
|
5577 |
@table @option |
5578 |
@opindex starting-file |
5579 |
@item --starting-file=@var{name} |
5580 |
@itemx -K @var{name} |
5581 |
Starts an operation in the middle of an archive. Use in conjunction |
5582 |
with @option{--extract} (@option{--get}, @option{-x}) or @option{--list} (@option{-t}). |
5583 |
@end table |
5584 |
|
5585 |
@cindex Middle of the archive, starting in the |
5586 |
If a previous attempt to extract files failed due to lack of disk |
5587 |
space, you can use @option{--starting-file=@var{name}} (@option{-K |
5588 |
@var{name}}) to start extracting only after member @var{name} of the |
5589 |
archive. This assumes, of course, that there is now free space, or |
5590 |
that you are now extracting into a different file system. (You could |
5591 |
also choose to suspend @command{tar}, remove unnecessary files from |
5592 |
the file system, and then resume the same @command{tar} operation. |
5593 |
In this case, @option{--starting-file} is not necessary.) See also |
5594 |
@ref{interactive}, and @ref{exclude}. |
5595 |
|
5596 |
@node Same Order |
5597 |
@unnumberedsubsubsec Same Order |
5598 |
|
5599 |
@table @option |
5600 |
@cindex Large lists of file names on small machines |
5601 |
@opindex same-order |
5602 |
@opindex preserve-order |
5603 |
@item --same-order |
5604 |
@itemx --preserve-order |
5605 |
@itemx -s |
5606 |
To process large lists of file names on machines with small amounts of |
5607 |
memory. Use in conjunction with @option{--compare} (@option{--diff}, |
5608 |
@option{-d}), @option{--list} (@option{-t}) or @option{--extract} |
5609 |
(@option{--get}, @option{-x}). |
5610 |
@end table |
5611 |
|
5612 |
The @option{--same-order} (@option{--preserve-order}, @option{-s}) option tells @command{tar} that the list of file |
5613 |
names to be listed or extracted is sorted in the same order as the |
5614 |
files in the archive. This allows a large list of names to be used, |
5615 |
even on a small machine that would not otherwise be able to hold all |
5616 |
the names in memory at the same time. Such a sorted list can easily be |
5617 |
created by running @samp{tar -t} on the archive and editing its output. |
5618 |
|
5619 |
This option is probably never needed on modern computer systems. |
5620 |
|
5621 |
@node backup |
5622 |
@section Backup options |
5623 |
|
5624 |
@cindex backup options |
5625 |
|
5626 |
@GNUTAR{} offers options for making backups of files |
5627 |
before writing new versions. These options control the details of |
5628 |
these backups. They may apply to the archive itself before it is |
5629 |
created or rewritten, as well as individual extracted members. Other |
5630 |
@acronym{GNU} programs (@command{cp}, @command{install}, @command{ln}, |
5631 |
and @command{mv}, for example) offer similar options. |
5632 |
|
5633 |
Backup options may prove unexpectedly useful when extracting archives |
5634 |
containing many members having identical name, or when extracting archives |
5635 |
on systems having file name limitations, making different members appear |
5636 |
as having similar names through the side-effect of name truncation. |
5637 |
@FIXME{This is true only if we have a good scheme for truncated backup names, |
5638 |
which I'm not sure at all: I suspect work is needed in this area.} |
5639 |
When any existing file is backed up before being overwritten by extraction, |
5640 |
then clashing files are automatically be renamed to be unique, and the |
5641 |
true name is kept for only the last file of a series of clashing files. |
5642 |
By using verbose mode, users may track exactly what happens. |
5643 |
|
5644 |
At the detail level, some decisions are still experimental, and may |
5645 |
change in the future, we are waiting comments from our users. So, please |
5646 |
do not learn to depend blindly on the details of the backup features. |
5647 |
For example, currently, directories themselves are never renamed through |
5648 |
using these options, so, extracting a file over a directory still has |
5649 |
good chances to fail. Also, backup options apply to created archives, |
5650 |
not only to extracted members. For created archives, backups will not |
5651 |
be attempted when the archive is a block or character device, or when it |
5652 |
refers to a remote file. |
5653 |
|
5654 |
For the sake of simplicity and efficiency, backups are made by renaming old |
5655 |
files prior to creation or extraction, and not by copying. The original |
5656 |
name is restored if the file creation fails. If a failure occurs after a |
5657 |
partial extraction of a file, both the backup and the partially extracted |
5658 |
file are kept. |
5659 |
|
5660 |
@table @samp |
5661 |
@item --backup[=@var{method}] |
5662 |
@opindex backup |
5663 |
@vindex VERSION_CONTROL |
5664 |
@cindex backups |
5665 |
Back up files that are about to be overwritten or removed. |
5666 |
Without this option, the original versions are destroyed. |
5667 |
|
5668 |
Use @var{method} to determine the type of backups made. |
5669 |
If @var{method} is not specified, use the value of the @env{VERSION_CONTROL} |
5670 |
environment variable. And if @env{VERSION_CONTROL} is not set, |
5671 |
use the @samp{existing} method. |
5672 |
|
5673 |
@vindex version-control @r{Emacs variable} |
5674 |
This option corresponds to the Emacs variable @samp{version-control}; |
5675 |
the same values for @var{method} are accepted as in Emacs. This option |
5676 |
also allows more descriptive names. The valid @var{method}s are: |
5677 |
|
5678 |
@table @samp |
5679 |
@item t |
5680 |
@itemx numbered |
5681 |
@cindex numbered @r{backup method} |
5682 |
Always make numbered backups. |
5683 |
|
5684 |
@item nil |
5685 |
@itemx existing |
5686 |
@cindex existing @r{backup method} |
5687 |
Make numbered backups of files that already have them, simple backups |
5688 |
of the others. |
5689 |
|
5690 |
@item never |
5691 |
@itemx simple |
5692 |
@cindex simple @r{backup method} |
5693 |
Always make simple backups. |
5694 |
|
5695 |
@end table |
5696 |
|
5697 |
@item --suffix=@var{suffix} |
5698 |
@opindex suffix |
5699 |
@cindex backup suffix |
5700 |
@vindex SIMPLE_BACKUP_SUFFIX |
5701 |
Append @var{suffix} to each backup file made with @option{--backup}. If this |
5702 |
option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX} |
5703 |
environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not |
5704 |
set, the default is @samp{~}, just as in Emacs. |
5705 |
|
5706 |
@end table |
5707 |
|
5708 |
@node Applications |
5709 |
@section Notable @command{tar} Usages |
5710 |
@UNREVISED |
5711 |
|
5712 |
@FIXME{Using Unix file linking capability to recreate directory |
5713 |
structures---linking files into one subdirectory and then |
5714 |
@command{tar}ring that directory.} |
5715 |
|
5716 |
@FIXME{Nice hairy example using absolute-names, newer, etc.} |
5717 |
|
5718 |
@findex uuencode |
5719 |
You can easily use archive files to transport a group of files from |
5720 |
one system to another: put all relevant files into an archive on one |
5721 |
computer system, transfer the archive to another system, and extract |
5722 |
the contents there. The basic transfer medium might be magnetic tape, |
5723 |
Internet FTP, or even electronic mail (though you must encode the |
5724 |
archive with @command{uuencode} in order to transport it properly by |
5725 |
mail). Both machines do not have to use the same operating system, as |
5726 |
long as they both support the @command{tar} program. |
5727 |
|
5728 |
For example, here is how you might copy a directory's contents from |
5729 |
one disk to another, while preserving the dates, modes, owners and |
5730 |
link-structure of all the files therein. In this case, the transfer |
5731 |
medium is a @dfn{pipe}: |
5732 |
|
5733 |
@smallexample |
5734 |
$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)} |
5735 |
@end smallexample |
5736 |
|
5737 |
@noindent |
5738 |
You can avoid subshells by using @option{-C} option: |
5739 |
|
5740 |
@smallexample |
5741 |
$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -} |
5742 |
@end smallexample |
5743 |
|
5744 |
@noindent |
5745 |
The command also works using long option forms: |
5746 |
|
5747 |
@smallexample |
5748 |
@group |
5749 |
$ @kbd{(cd sourcedir; tar --create --file=- . ) \ |
5750 |
| (cd targetdir; tar --extract --file=-)} |
5751 |
@end group |
5752 |
@end smallexample |
5753 |
|
5754 |
@noindent |
5755 |
or |
5756 |
|
5757 |
@smallexample |
5758 |
@group |
5759 |
$ @kbd{tar --directory sourcedir --create --file=- . \ |
5760 |
| tar --directory targetdir --extract --file=-} |
5761 |
@end group |
5762 |
@end smallexample |
5763 |
|
5764 |
@noindent |
5765 |
This is one of the easiest methods to transfer a @command{tar} archive. |
5766 |
|
5767 |
@node looking ahead |
5768 |
@section Looking Ahead: The Rest of this Manual |
5769 |
|
5770 |
You have now seen how to use all eight of the operations available to |
5771 |
@command{tar}, and a number of the possible options. The next chapter |
5772 |
explains how to choose and change file and archive names, how to use |
5773 |
files to store names of other files which you can then call as |
5774 |
arguments to @command{tar} (this can help you save time if you expect to |
5775 |
archive the same list of files a number of times), and so forth. |
5776 |
@FIXME{in case it's not obvious, i'm making this up in some sense |
5777 |
based on my limited memory of what the next chapter *really* does. i |
5778 |
just wanted to flesh out this final section a little bit so i'd |
5779 |
remember to stick it in here. :-)} |
5780 |
|
5781 |
If there are too many files to conveniently list on the command line, |
5782 |
you can list the names in a file, and @command{tar} will read that file. |
5783 |
@xref{files}. |
5784 |
|
5785 |
There are various ways of causing @command{tar} to skip over some files, |
5786 |
and not archive them. @xref{Choosing}. |
5787 |
|
5788 |
@node Backups |
5789 |
@chapter Performing Backups and Restoring Files |
5790 |
@cindex backups |
5791 |
|
5792 |
@GNUTAR{} is distributed along with the scripts for performing backups |
5793 |
and restores. Even if there is a good chance those scripts may be |
5794 |
satisfying to you, they are not the only scripts or methods available for doing |
5795 |
backups and restore. You may well create your own, or use more |
5796 |
sophisticated packages dedicated to that purpose. |
5797 |
|
5798 |
Some users are enthusiastic about @code{Amanda} (The Advanced Maryland |
5799 |
Automatic Network Disk Archiver), a backup system developed by James |
5800 |
da Silva @file{jds@@cs.umd.edu} and available on many Unix systems. |
5801 |
This is free software, and it is available from @uref{http://www.amanda.org}. |
5802 |
|
5803 |
@FIXME{ |
5804 |
|
5805 |
Here is a possible plan for a future documentation about the backuping |
5806 |
scripts which are provided within the @GNUTAR{} |
5807 |
distribution. |
5808 |
|
5809 |
@itemize @bullet |
5810 |
@item dumps |
5811 |
@itemize @minus |
5812 |
@item what are dumps |
5813 |
@item different levels of dumps |
5814 |
@itemize + |
5815 |
@item full dump = dump everything |
5816 |
@item level 1, level 2 dumps etc |
5817 |
A level @var{n} dump dumps everything changed since the last level |
5818 |
@var{n}-1 dump (?) |
5819 |
@end itemize |
5820 |
@item how to use scripts for dumps (ie, the concept) |
5821 |
@itemize + |
5822 |
@item scripts to run after editing backup specs (details) |
5823 |
@end itemize |
5824 |
@item Backup Specs, what is it. |
5825 |
@itemize + |
5826 |
@item how to customize |
5827 |
@item actual text of script [/sp/dump/backup-specs] |
5828 |
@end itemize |
5829 |
@item Problems |
5830 |
@itemize + |
5831 |
@item rsh doesn't work |
5832 |
@item rtape isn't installed |
5833 |
@item (others?) |
5834 |
@end itemize |
5835 |
@item the @option{--incremental} option of tar |
5836 |
@item tapes |
5837 |
@itemize + |
5838 |
@item write protection |
5839 |
@item types of media, different sizes and types, useful for different things |
5840 |
@item files and tape marks |
5841 |
one tape mark between files, two at end. |
5842 |
@item positioning the tape |
5843 |
MT writes two at end of write, |
5844 |
backspaces over one when writing again. |
5845 |
@end itemize |
5846 |
@end itemize |
5847 |
@end itemize |
5848 |
} |
5849 |
|
5850 |
This chapter documents both the provided shell scripts and @command{tar} |
5851 |
options which are more specific to usage as a backup tool. |
5852 |
|
5853 |
To @dfn{back up} a file system means to create archives that contain |
5854 |
all the files in that file system. Those archives can then be used to |
5855 |
restore any or all of those files (for instance if a disk crashes or a |
5856 |
file is accidentally deleted). File system @dfn{backups} are also |
5857 |
called @dfn{dumps}. |
5858 |
|
5859 |
@menu |
5860 |
* Full Dumps:: Using @command{tar} to Perform Full Dumps |
5861 |
* Incremental Dumps:: Using @command{tar} to Perform Incremental Dumps |
5862 |
* Backup Levels:: Levels of Backups |
5863 |
* Backup Parameters:: Setting Parameters for Backups and Restoration |
5864 |
* Scripted Backups:: Using the Backup Scripts |
5865 |
* Scripted Restoration:: Using the Restore Script |
5866 |
@end menu |
5867 |
|
5868 |
@node Full Dumps |
5869 |
@section Using @command{tar} to Perform Full Dumps |
5870 |
@UNREVISED |
5871 |
|
5872 |
@cindex full dumps |
5873 |
@cindex dumps, full |
5874 |
|
5875 |
@cindex corrupted archives |
5876 |
Full dumps should only be made when no other people or programs |
5877 |
are modifying files in the file system. If files are modified while |
5878 |
@command{tar} is making the backup, they may not be stored properly in |
5879 |
the archive, in which case you won't be able to restore them if you |
5880 |
have to. (Files not being modified are written with no trouble, and do |
5881 |
not corrupt the entire archive.) |
5882 |
|
5883 |
You will want to use the @option{--label=@var{archive-label}} |
5884 |
(@option{-V @var{archive-label}}) option to give the archive a |
5885 |
volume label, so you can tell what this archive is even if the label |
5886 |
falls off the tape, or anything like that. |
5887 |
|
5888 |
Unless the file system you are dumping is guaranteed to fit on |
5889 |
one volume, you will need to use the @option{--multi-volume} (@option{-M}) option. |
5890 |
Make sure you have enough tapes on hand to complete the backup. |
5891 |
|
5892 |
If you want to dump each file system separately you will need to use |
5893 |
the @option{--one-file-system} option to prevent |
5894 |
@command{tar} from crossing file system boundaries when storing |
5895 |
(sub)directories. |
5896 |
|
5897 |
The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps}) |
5898 |
option is not needed, since this is a complete copy of everything in |
5899 |
the file system, and a full restore from this backup would only be |
5900 |
done onto a completely |
5901 |
empty disk. |
5902 |
|
5903 |
Unless you are in a hurry, and trust the @command{tar} program (and your |
5904 |
tapes), it is a good idea to use the @option{--verify} (@option{-W}) |
5905 |
option, to make sure your files really made it onto the dump properly. |
5906 |
This will also detect cases where the file was modified while (or just |
5907 |
after) it was being archived. Not all media (notably cartridge tapes) |
5908 |
are capable of being verified, unfortunately. |
5909 |
|
5910 |
@node Incremental Dumps |
5911 |
@section Using @command{tar} to Perform Incremental Dumps |
5912 |
|
5913 |
@dfn{Incremental backup} is a special form of @GNUTAR{} archive that |
5914 |
stores additional metadata so that exact state of the file system |
5915 |
can be restored when extracting the archive. |
5916 |
|
5917 |
@GNUTAR{} currently offers two options for handling incremental |
5918 |
backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g |
5919 |
@var{snapshot-file}}) and @option{--incremental} (@option{-G}). |
5920 |
|
5921 |
@xopindex{listed-incremental, described} |
5922 |
The option @option{--listed-incremental} instructs tar to operate on |
5923 |
an incremental archive with additional metadata stored in a standalone |
5924 |
file, called a @dfn{snapshot file}. The purpose of this file is to help |
5925 |
determine which files have been changed, added or deleted since the |
5926 |
last backup, so that the next incremental backup will contain only |
5927 |
modified files. The name of the snapshot file is given as an argument |
5928 |
to the option: |
5929 |
|
5930 |
@table @option |
5931 |
@item --listed-incremental=@var{file} |
5932 |
@itemx -g @var{file} |
5933 |
Handle incremental backups with snapshot data in @var{file}. |
5934 |
@end table |
5935 |
|
5936 |
To create an incremental backup, you would use |
5937 |
@option{--listed-incremental} together with @option{--create} |
5938 |
(@pxref{create}). For example: |
5939 |
|
5940 |
@smallexample |
5941 |
$ @kbd{tar --create \ |
5942 |
--file=archive.1.tar \ |
5943 |
--listed-incremental=/var/log/usr.snar \ |
5944 |
/usr} |
5945 |
@end smallexample |
5946 |
|
5947 |
This will create in @file{archive.1.tar} an incremental backup of |
5948 |
the @file{/usr} file system, storing additional metadata in the file |
5949 |
@file{/var/log/usr.snar}. If this file does not exist, it will be |
5950 |
created. The created archive will then be a @dfn{level 0 backup}; |
5951 |
please see the next section for more on backup levels. |
5952 |
|
5953 |
Otherwise, if the file @file{/var/log/usr.snar} exists, it |
5954 |
determines which files are modified. In this case only these files will be |
5955 |
stored in the archive. Suppose, for example, that after running the |
5956 |
above command, you delete file @file{/usr/doc/old} and create |
5957 |
directory @file{/usr/local/db} with the following contents: |
5958 |
|
5959 |
@smallexample |
5960 |
$ @kbd{ls /usr/local/db} |
5961 |
/usr/local/db/data |
5962 |
/usr/local/db/index |
5963 |
@end smallexample |
5964 |
|
5965 |
Some time later you create another incremental backup. You will |
5966 |
then see: |
5967 |
|
5968 |
@smallexample |
5969 |
$ @kbd{tar --create \ |
5970 |
--file=archive.2.tar \ |
5971 |
--listed-incremental=/var/log/usr.snar \ |
5972 |
/usr} |
5973 |
tar: usr/local/db: Directory is new |
5974 |
usr/local/db/ |
5975 |
usr/local/db/data |
5976 |
usr/local/db/index |
5977 |
@end smallexample |
5978 |
|
5979 |
@noindent |
5980 |
The created archive @file{archive.2.tar} will contain only these |
5981 |
three members. This archive is called a @dfn{level 1 backup}. Notice |
5982 |
that @file{/var/log/usr.snar} will be updated with the new data, so if |
5983 |
you plan to create more @samp{level 1} backups, it is necessary to |
5984 |
create a working copy of the snapshot file before running |
5985 |
@command{tar}. The above example will then be modified as follows: |
5986 |
|
5987 |
@smallexample |
5988 |
$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1} |
5989 |
$ @kbd{tar --create \ |
5990 |
--file=archive.2.tar \ |
5991 |
--listed-incremental=/var/log/usr.snar-1 \ |
5992 |
/usr} |
5993 |
@end smallexample |
5994 |
|
5995 |
@anchor{--level=0} |
5996 |
@xopindex{level, described} |
5997 |
You can force @samp{level 0} backups either by removing the snapshot |
5998 |
file before running @command{tar}, or by supplying the |
5999 |
@option{--level=0} option, e.g.: |
6000 |
|
6001 |
@smallexample |
6002 |
$ @kbd{tar --create \ |
6003 |
--file=archive.2.tar \ |
6004 |
--listed-incremental=/var/log/usr.snar-0 \ |
6005 |
--level=0 \ |
6006 |
/usr} |
6007 |
@end smallexample |
6008 |
|
6009 |
Incremental dumps depend crucially on time stamps, so the results are |
6010 |
unreliable if you modify a file's time stamps during dumping (e.g., |
6011 |
with the @option{--atime-preserve=replace} option), or if you set the clock |
6012 |
backwards. |
6013 |
|
6014 |
@anchor{device numbers} |
6015 |
@cindex Device numbers, using in incremental backups |
6016 |
Metadata stored in snapshot files include device numbers, which, |
6017 |
obviously are supposed to be non-volatile values. However, it turns |
6018 |
out that @acronym{NFS} devices have undependable values when an automounter |
6019 |
gets in the picture. This can lead to a great deal of spurious |
6020 |
redumping in incremental dumps, so it is somewhat useless to compare |
6021 |
two @acronym{NFS} devices numbers over time. The solution implemented |
6022 |
currently is to consider all @acronym{NFS} devices as being equal |
6023 |
when it comes to comparing directories; this is fairly gross, but |
6024 |
there does not seem to be a better way to go. |
6025 |
|
6026 |
Apart from using @acronym{NFS}, there are a number of cases where |
6027 |
relying on device numbers can cause spurious redumping of unmodified |
6028 |
files. For example, this occurs when archiving @acronym{LVM} snapshot |
6029 |
volumes. To avoid this, use @option{--no-check-device} option: |
6030 |
|
6031 |
@table @option |
6032 |
@xopindex{no-check-device, described} |
6033 |
@item --no-check-device |
6034 |
Do not rely on device numbers when preparing a list of changed files |
6035 |
for an incremental dump. |
6036 |
|
6037 |
@xopindex{check-device, described} |
6038 |
@item --check-device |
6039 |
Use device numbers when preparing a list of changed files |
6040 |
for an incremental dump. This is the default behavior. The purpose |
6041 |
of this option is to undo the effect of the @option{--no-check-device} |
6042 |
if it was given in @env{TAR_OPTIONS} environment variable |
6043 |
(@pxref{TAR_OPTIONS}). |
6044 |
@end table |
6045 |
|
6046 |
There is also another way to cope with changing device numbers. It is |
6047 |
described in detail in @ref{Fixing Snapshot Files}. |
6048 |
|
6049 |
Note that incremental archives use @command{tar} extensions and may |
6050 |
not be readable by non-@acronym{GNU} versions of the @command{tar} program. |
6051 |
|
6052 |
@xopindex{listed-incremental, using with @option{--extract}} |
6053 |
@xopindex{extract, using with @option{--listed-incremental}} |
6054 |
To extract from the incremental dumps, use |
6055 |
@option{--listed-incremental} together with @option{--extract} |
6056 |
option (@pxref{extracting files}). In this case, @command{tar} does |
6057 |
not need to access snapshot file, since all the data necessary for |
6058 |
extraction are stored in the archive itself. So, when extracting, you |
6059 |
can give whatever argument to @option{--listed-incremental}, the usual |
6060 |
practice is to use @option{--listed-incremental=/dev/null}. |
6061 |
Alternatively, you can use @option{--incremental}, which needs no |
6062 |
arguments. In general, @option{--incremental} (@option{-G}) can be |
6063 |
used as a shortcut for @option{--listed-incremental} when listing or |
6064 |
extracting incremental backups (for more information regarding this |
6065 |
option, @pxref{incremental-op}). |
6066 |
|
6067 |
When extracting from the incremental backup @GNUTAR{} attempts to |
6068 |
restore the exact state the file system had when the archive was |
6069 |
created. In particular, it will @emph{delete} those files in the file |
6070 |
system that did not exist in their directories when the archive was |
6071 |
created. If you have created several levels of incremental files, |
6072 |
then in order to restore the exact contents the file system had when |
6073 |
the last level was created, you will need to restore from all backups |
6074 |
in turn. Continuing our example, to restore the state of @file{/usr} |
6075 |
file system, one would do@footnote{Notice, that since both archives |
6076 |
were created without @option{-P} option (@pxref{absolute}), these |
6077 |
commands should be run from the root file system.}: |
6078 |
|
6079 |
@smallexample |
6080 |
$ @kbd{tar --extract \ |
6081 |
--listed-incremental=/dev/null \ |
6082 |
--file archive.1.tar} |
6083 |
$ @kbd{tar --extract \ |
6084 |
--listed-incremental=/dev/null \ |
6085 |
--file archive.2.tar} |
6086 |
@end smallexample |
6087 |
|
6088 |
To list the contents of an incremental archive, use @option{--list} |
6089 |
(@pxref{list}), as usual. To obtain more information about the |
6090 |
archive, use @option{--listed-incremental} or @option{--incremental} |
6091 |
combined with two @option{--verbose} options@footnote{Two |
6092 |
@option{--verbose} options were selected to avoid breaking usual |
6093 |
verbose listing output (@option{--list --verbose}) when using in |
6094 |
scripts. |
6095 |
|
6096 |
@xopindex{incremental, using with @option{--list}} |
6097 |
@xopindex{listed-incremental, using with @option{--list}} |
6098 |
@xopindex{list, using with @option{--incremental}} |
6099 |
@xopindex{list, using with @option{--listed-incremental}} |
6100 |
Versions of @GNUTAR{} up to 1.15.1 used to dump verbatim binary |
6101 |
contents of the DUMPDIR header (with terminating nulls) when |
6102 |
@option{--incremental} or @option{--listed-incremental} option was |
6103 |
given, no matter what the verbosity level. This behavior, and, |
6104 |
especially, the binary output it produced were considered inconvenient |
6105 |
and were changed in version 1.16.}: |
6106 |
|
6107 |
@smallexample |
6108 |
@kbd{tar --list --incremental --verbose --verbose archive.tar} |
6109 |
@end smallexample |
6110 |
|
6111 |
This command will print, for each directory in the archive, the list |
6112 |
of files in that directory at the time the archive was created. This |
6113 |
information is put out in a format which is both human-readable and |
6114 |
unambiguous for a program: each file name is printed as |
6115 |
|
6116 |
@smallexample |
6117 |
@var{x} @var{file} |
6118 |
@end smallexample |
6119 |
|
6120 |
@noindent |
6121 |
where @var{x} is a letter describing the status of the file: @samp{Y} |
6122 |
if the file is present in the archive, @samp{N} if the file is not |
6123 |
included in the archive, or a @samp{D} if the file is a directory (and |
6124 |
is included in the archive). @xref{Dumpdir}, for the detailed |
6125 |
description of dumpdirs and status codes. Each such |
6126 |
line is terminated by a newline character. The last line is followed |
6127 |
by an additional newline to indicate the end of the data. |
6128 |
|
6129 |
@anchor{incremental-op}The option @option{--incremental} (@option{-G}) |
6130 |
gives the same behavior as @option{--listed-incremental} when used |
6131 |
with @option{--list} and @option{--extract} options. When used with |
6132 |
@option{--create} option, it creates an incremental archive without |
6133 |
creating snapshot file. Thus, it is impossible to create several |
6134 |
levels of incremental backups with @option{--incremental} option. |
6135 |
|
6136 |
@node Backup Levels |
6137 |
@section Levels of Backups |
6138 |
|
6139 |
An archive containing all the files in the file system is called a |
6140 |
@dfn{full backup} or @dfn{full dump}. You could insure your data by |
6141 |
creating a full dump every day. This strategy, however, would waste a |
6142 |
substantial amount of archive media and user time, as unchanged files |
6143 |
are daily re-archived. |
6144 |
|
6145 |
It is more efficient to do a full dump only occasionally. To back up |
6146 |
files between full dumps, you can use @dfn{incremental dumps}. A @dfn{level |
6147 |
one} dump archives all the files that have changed since the last full |
6148 |
dump. |
6149 |
|
6150 |
A typical dump strategy would be to perform a full dump once a week, |
6151 |
and a level one dump once a day. This means some versions of files |
6152 |
will in fact be archived more than once, but this dump strategy makes |
6153 |
it possible to restore a file system to within one day of accuracy by |
6154 |
only extracting two archives---the last weekly (full) dump and the |
6155 |
last daily (level one) dump. The only information lost would be in |
6156 |
files changed or created since the last daily backup. (Doing dumps |
6157 |
more than once a day is usually not worth the trouble.) |
6158 |
|
6159 |
@GNUTAR{} comes with scripts you can use to do full |
6160 |
and level-one (actually, even level-two and so on) dumps. Using |
6161 |
scripts (shell programs) to perform backups and restoration is a |
6162 |
convenient and reliable alternative to typing out file name lists |
6163 |
and @command{tar} commands by hand. |
6164 |
|
6165 |
Before you use these scripts, you need to edit the file |
6166 |
@file{backup-specs}, which specifies parameters used by the backup |
6167 |
scripts and by the restore script. This file is usually located |
6168 |
in @file{/etc/backup} directory. @xref{Backup Parameters}, for its |
6169 |
detailed description. Once the backup parameters are set, you can |
6170 |
perform backups or restoration by running the appropriate script. |
6171 |
|
6172 |
The name of the backup script is @code{backup}. The name of the |
6173 |
restore script is @code{restore}. The following sections describe |
6174 |
their use in detail. |
6175 |
|
6176 |
@emph{Please Note:} The backup and restoration scripts are |
6177 |
designed to be used together. While it is possible to restore files by |
6178 |
hand from an archive which was created using a backup script, and to create |
6179 |
an archive by hand which could then be extracted using the restore script, |
6180 |
it is easier to use the scripts. @xref{Incremental Dumps}, before |
6181 |
making such an attempt. |
6182 |
|
6183 |
@node Backup Parameters |
6184 |
@section Setting Parameters for Backups and Restoration |
6185 |
|
6186 |
The file @file{backup-specs} specifies backup parameters for the |
6187 |
backup and restoration scripts provided with @command{tar}. You must |
6188 |
edit @file{backup-specs} to fit your system configuration and schedule |
6189 |
before using these scripts. |
6190 |
|
6191 |
Syntactically, @file{backup-specs} is a shell script, containing |
6192 |
mainly variable assignments. However, any valid shell construct |
6193 |
is allowed in this file. Particularly, you may wish to define |
6194 |
functions within that script (e.g., see @code{RESTORE_BEGIN} below). |
6195 |
For more information about shell script syntax, please refer to |
6196 |
@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta |
6197 |
g_02, the definition of the Shell Command Language}. See also |
6198 |
@ref{Top,,Bash Features,bashref,Bash Reference Manual}. |
6199 |
|
6200 |
The shell variables controlling behavior of @code{backup} and |
6201 |
@code{restore} are described in the following subsections. |
6202 |
|
6203 |
@menu |
6204 |
* General-Purpose Variables:: |
6205 |
* Magnetic Tape Control:: |
6206 |
* User Hooks:: |
6207 |
* backup-specs example:: An Example Text of @file{Backup-specs} |
6208 |
@end menu |
6209 |
|
6210 |
@node General-Purpose Variables |
6211 |
@subsection General-Purpose Variables |
6212 |
|
6213 |
@defvr {Backup variable} ADMINISTRATOR |
6214 |
The user name of the backup administrator. @code{Backup} scripts |
6215 |
sends a backup report to this address. |
6216 |
@end defvr |
6217 |
|
6218 |
@defvr {Backup variable} BACKUP_HOUR |
6219 |
The hour at which the backups are done. This can be a number from 0 |
6220 |
to 23, or the time specification in form @var{hours}:@var{minutes}, |
6221 |
or the string @samp{now}. |
6222 |
|
6223 |
This variable is used by @code{backup}. Its value may be overridden |
6224 |
using @option{--time} option (@pxref{Scripted Backups}). |
6225 |
@end defvr |
6226 |
|
6227 |
@defvr {Backup variable} TAPE_FILE |
6228 |
|
6229 |
The device @command{tar} writes the archive to. If @var{TAPE_FILE} |
6230 |
is a remote archive (@pxref{remote-dev}), backup script will suppose |
6231 |
that your @command{mt} is able to access remote devices. If @var{RSH} |
6232 |
(@pxref{RSH}) is set, @option{--rsh-command} option will be added to |
6233 |
invocations of @command{mt}. |
6234 |
@end defvr |
6235 |
|
6236 |
@defvr {Backup variable} BLOCKING |
6237 |
|
6238 |
The blocking factor @command{tar} will use when writing the dump archive. |
6239 |
@xref{Blocking Factor}. |
6240 |
@end defvr |
6241 |
|
6242 |
@defvr {Backup variable} BACKUP_DIRS |
6243 |
|
6244 |
A list of file systems to be dumped (for @code{backup}), or restored |
6245 |
(for @code{restore}). You can include any directory |
6246 |
name in the list --- subdirectories on that file system will be |
6247 |
included, regardless of how they may look to other networked machines. |
6248 |
Subdirectories on other file systems will be ignored. |
6249 |
|
6250 |
The host name specifies which host to run @command{tar} on, and should |
6251 |
normally be the host that actually contains the file system. However, |
6252 |
the host machine must have @GNUTAR{} installed, and |
6253 |
must be able to access the directory containing the backup scripts and |
6254 |
their support files using the same file name that is used on the |
6255 |
machine where the scripts are run (i.e., what @command{pwd} will print |
6256 |
when in that directory on that machine). If the host that contains |
6257 |
the file system does not have this capability, you can specify another |
6258 |
host as long as it can access the file system through @acronym{NFS}. |
6259 |
|
6260 |
If the list of file systems is very long you may wish to put it |
6261 |
in a separate file. This file is usually named |
6262 |
@file{/etc/backup/dirs}, but this name may be overridden in |
6263 |
@file{backup-specs} using @code{DIRLIST} variable. |
6264 |
@end defvr |
6265 |
|
6266 |
@defvr {Backup variable} DIRLIST |
6267 |
|
6268 |
The name of the file that contains a list of file systems to backup |
6269 |
or restore. By default it is @file{/etc/backup/dirs}. |
6270 |
@end defvr |
6271 |
|
6272 |
@defvr {Backup variable} BACKUP_FILES |
6273 |
|
6274 |
A list of individual files to be dumped (for @code{backup}), or restored |
6275 |
(for @code{restore}). These should be accessible from the machine on |
6276 |
which the backup script is run. |
6277 |
|
6278 |
If the list of individual files is very long you may wish to store it |
6279 |
in a separate file. This file is usually named |
6280 |
@file{/etc/backup/files}, but this name may be overridden in |
6281 |
@file{backup-specs} using @code{FILELIST} variable. |
6282 |
@end defvr |
6283 |
|
6284 |
@defvr {Backup variable} FILELIST |
6285 |
|
6286 |
The name of the file that contains a list of individual files to backup |
6287 |
or restore. By default it is @file{/etc/backup/files}. |
6288 |
@end defvr |
6289 |
|
6290 |
@defvr {Backup variable} MT |
6291 |
|
6292 |
Full file name of @command{mt} binary. |
6293 |
@end defvr |
6294 |
|
6295 |
@defvr {Backup variable} RSH |
6296 |
@anchor{RSH} |
6297 |
Full file name of @command{rsh} binary or its equivalent. You may wish to |
6298 |
set it to @code{ssh}, to improve security. In this case you will have |
6299 |
to use public key authentication. |
6300 |
@end defvr |
6301 |
|
6302 |
@defvr {Backup variable} RSH_COMMAND |
6303 |
|
6304 |
Full file name of @command{rsh} binary on remote machines. This will |
6305 |
be passed via @option{--rsh-command} option to the remote invocation |
6306 |
of @GNUTAR{}. |
6307 |
@end defvr |
6308 |
|
6309 |
@defvr {Backup variable} VOLNO_FILE |
6310 |
|
6311 |
Name of temporary file to hold volume numbers. This needs to be accessible |
6312 |
by all the machines which have file systems to be dumped. |
6313 |
@end defvr |
6314 |
|
6315 |
@defvr {Backup variable} XLIST |
6316 |
|
6317 |
Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file |
6318 |
located on the remote machine and containing the list of files to |
6319 |
be excluded from the backup. Exclude file lists are searched in |
6320 |
/etc/tar-backup directory. A common use for exclude file lists |
6321 |
is to exclude files containing security-sensitive information |
6322 |
(e.g., @file{/etc/shadow} from backups). |
6323 |
|
6324 |
This variable affects only @code{backup}. |
6325 |
@end defvr |
6326 |
|
6327 |
@defvr {Backup variable} SLEEP_TIME |
6328 |
|
6329 |
Time to sleep between dumps of any two successive file systems |
6330 |
|
6331 |
This variable affects only @code{backup}. |
6332 |
@end defvr |
6333 |
|
6334 |
@defvr {Backup variable} DUMP_REMIND_SCRIPT |
6335 |
|
6336 |
Script to be run when it's time to insert a new tape in for the next |
6337 |
volume. Administrators may want to tailor this script for their site. |
6338 |
If this variable isn't set, @GNUTAR{} will display its built-in |
6339 |
prompt, and will expect confirmation from the console. For the |
6340 |
description of the default prompt, see @ref{change volume prompt}. |
6341 |
|
6342 |
@end defvr |
6343 |
|
6344 |
@defvr {Backup variable} SLEEP_MESSAGE |
6345 |
|
6346 |
Message to display on the terminal while waiting for dump time. Usually |
6347 |
this will just be some literal text. |
6348 |
@end defvr |
6349 |
|
6350 |
@defvr {Backup variable} TAR |
6351 |
|
6352 |
Full file name of the @GNUTAR{} executable. If this is not set, backup |
6353 |
scripts will search @command{tar} in the current shell path. |
6354 |
@end defvr |
6355 |
|
6356 |
@node Magnetic Tape Control |
6357 |
@subsection Magnetic Tape Control |
6358 |
|
6359 |
Backup scripts access tape device using special @dfn{hook functions}. |
6360 |
These functions take a single argument --- the name of the tape |
6361 |
device. Their names are kept in the following variables: |
6362 |
|
6363 |
@defvr {Backup variable} MT_BEGIN |
6364 |
The name of @dfn{begin} function. This function is called before |
6365 |
accessing the drive. By default it retensions the tape: |
6366 |
|
6367 |
@smallexample |
6368 |
MT_BEGIN=mt_begin |
6369 |
|
6370 |
mt_begin() @{ |
6371 |
mt -f "$1" retension |
6372 |
@} |
6373 |
@end smallexample |
6374 |
@end defvr |
6375 |
|
6376 |
@defvr {Backup variable} MT_REWIND |
6377 |
The name of @dfn{rewind} function. The default definition is as |
6378 |
follows: |
6379 |
|
6380 |
@smallexample |
6381 |
MT_REWIND=mt_rewind |
6382 |
|
6383 |
mt_rewind() @{ |
6384 |
mt -f "$1" rewind |
6385 |
@} |
6386 |
@end smallexample |
6387 |
|
6388 |
@end defvr |
6389 |
|
6390 |
@defvr {Backup variable} MT_OFFLINE |
6391 |
The name of the function switching the tape off line. By default |
6392 |
it is defined as follows: |
6393 |
|
6394 |
@smallexample |
6395 |
MT_OFFLINE=mt_offline |
6396 |
|
6397 |
mt_offline() @{ |
6398 |
mt -f "$1" offl |
6399 |
@} |
6400 |
@end smallexample |
6401 |
@end defvr |
6402 |
|
6403 |
@defvr {Backup variable} MT_STATUS |
6404 |
The name of the function used to obtain the status of the archive device, |
6405 |
including error count. Default definition: |
6406 |
|
6407 |
@smallexample |
6408 |
MT_STATUS=mt_status |
6409 |
|
6410 |
mt_status() @{ |
6411 |
mt -f "$1" status |
6412 |
@} |
6413 |
@end smallexample |
6414 |
@end defvr |
6415 |
|
6416 |
@node User Hooks |
6417 |
@subsection User Hooks |
6418 |
|
6419 |
@dfn{User hooks} are shell functions executed before and after |
6420 |
each @command{tar} invocation. Thus, there are @dfn{backup |
6421 |
hooks}, which are executed before and after dumping each file |
6422 |
system, and @dfn{restore hooks}, executed before and |
6423 |
after restoring a file system. Each user hook is a shell function |
6424 |
taking four arguments: |
6425 |
|
6426 |
@deffn {User Hook Function} hook @var{level} @var{host} @var{fs} @var{fsname} |
6427 |
Its arguments are: |
6428 |
|
6429 |
@table @var |
6430 |
@item level |
6431 |
Current backup or restore level. |
6432 |
|
6433 |
@item host |
6434 |
Name or IP address of the host machine being dumped or restored. |
6435 |
|
6436 |
@item fs |
6437 |
Full file name of the file system being dumped or restored. |
6438 |
|
6439 |
@item fsname |
6440 |
File system name with directory separators replaced with colons. This |
6441 |
is useful, e.g., for creating unique files. |
6442 |
@end table |
6443 |
@end deffn |
6444 |
|
6445 |
Following variables keep the names of user hook functions: |
6446 |
|
6447 |
@defvr {Backup variable} DUMP_BEGIN |
6448 |
Dump begin function. It is executed before dumping the file system. |
6449 |
@end defvr |
6450 |
|
6451 |
@defvr {Backup variable} DUMP_END |
6452 |
Executed after dumping the file system. |
6453 |
@end defvr |
6454 |
|
6455 |
@defvr {Backup variable} RESTORE_BEGIN |
6456 |
Executed before restoring the file system. |
6457 |
@end defvr |
6458 |
|
6459 |
@defvr {Backup variable} RESTORE_END |
6460 |
Executed after restoring the file system. |
6461 |
@end defvr |
6462 |
|
6463 |
@node backup-specs example |
6464 |
@subsection An Example Text of @file{Backup-specs} |
6465 |
|
6466 |
The following is an example of @file{backup-specs}: |
6467 |
|
6468 |
@smallexample |
6469 |
# site-specific parameters for file system backup. |
6470 |
|
6471 |
ADMINISTRATOR=friedman |
6472 |
BACKUP_HOUR=1 |
6473 |
TAPE_FILE=/dev/nrsmt0 |
6474 |
|
6475 |
# Use @code{ssh} instead of the less secure @code{rsh} |
6476 |
RSH=/usr/bin/ssh |
6477 |
RSH_COMMAND=/usr/bin/ssh |
6478 |
|
6479 |
# Override MT_STATUS function: |
6480 |
my_status() @{ |
6481 |
mts -t $TAPE_FILE |
6482 |
@} |
6483 |
MT_STATUS=my_status |
6484 |
|
6485 |
# Disable MT_OFFLINE function |
6486 |
MT_OFFLINE=: |
6487 |
|
6488 |
BLOCKING=124 |
6489 |
BACKUP_DIRS=" |
6490 |
albert:/fs/fsf |
6491 |
apple-gunkies:/gd |
6492 |
albert:/fs/gd2 |
6493 |
albert:/fs/gp |
6494 |
geech:/usr/jla |
6495 |
churchy:/usr/roland |
6496 |
albert:/ |
6497 |
albert:/usr |
6498 |
apple-gunkies:/ |
6499 |
apple-gunkies:/usr |
6500 |
gnu:/hack |
6501 |
gnu:/u |
6502 |
apple-gunkies:/com/mailer/gnu |
6503 |
apple-gunkies:/com/archive/gnu" |
6504 |
|
6505 |
BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]" |
6506 |
|
6507 |
@end smallexample |
6508 |
|
6509 |
@node Scripted Backups |
6510 |
@section Using the Backup Scripts |
6511 |
|
6512 |
The syntax for running a backup script is: |
6513 |
|
6514 |
@smallexample |
6515 |
backup --level=@var{level} --time=@var{time} |
6516 |
@end smallexample |
6517 |
|
6518 |
The @option{--level} option requests the dump level. Thus, to produce |
6519 |
a full dump, specify @code{--level=0} (this is the default, so |
6520 |
@option{--level} may be omitted if its value is |
6521 |
@code{0})@footnote{For backward compatibility, the @code{backup} will also |
6522 |
try to deduce the requested dump level from the name of the |
6523 |
script itself. If the name consists of a string @samp{level-} |
6524 |
followed by a single decimal digit, that digit is taken as |
6525 |
the dump level number. Thus, you may create a link from @code{backup} |
6526 |
to @code{level-1} and then run @code{level-1} whenever you need to |
6527 |
create a level one dump.}. |
6528 |
|
6529 |
The @option{--time} option determines when should the backup be |
6530 |
run. @var{Time} may take three forms: |
6531 |
|
6532 |
@table @asis |
6533 |
@item @var{hh}:@var{mm} |
6534 |
|
6535 |
The dump must be run at @var{hh} hours @var{mm} minutes. |
6536 |
|
6537 |
@item @var{hh} |
6538 |
|
6539 |
The dump must be run at @var{hh} hours. |
6540 |
|
6541 |
@item now |
6542 |
|
6543 |
The dump must be run immediately. |
6544 |
@end table |
6545 |
|
6546 |
You should start a script with a tape or disk mounted. Once you |
6547 |
start a script, it prompts you for new tapes or disks as it |
6548 |
needs them. Media volumes don't have to correspond to archive |
6549 |
files --- a multi-volume archive can be started in the middle of a |
6550 |
tape that already contains the end of another multi-volume archive. |
6551 |
The @code{restore} script prompts for media by its archive volume, |
6552 |
so to avoid an error message you should keep track of which tape |
6553 |
(or disk) contains which volume of the archive (@pxref{Scripted |
6554 |
Restoration}). |
6555 |
|
6556 |
The backup scripts write two files on the file system. The first is a |
6557 |
record file in @file{/etc/tar-backup/}, which is used by the scripts |
6558 |
to store and retrieve information about which files were dumped. This |
6559 |
file is not meant to be read by humans, and should not be deleted by |
6560 |
them. @xref{Snapshot Files}, for a more detailed explanation of this |
6561 |
file. |
6562 |
|
6563 |
The second file is a log file containing the names of the file systems |
6564 |
and files dumped, what time the backup was made, and any error |
6565 |
messages that were generated, as well as how much space was left in |
6566 |
the media volume after the last volume of the archive was written. |
6567 |
You should check this log file after every backup. The file name is |
6568 |
@file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy} |
6569 |
represents current date, and @var{n} represents current dump level number. |
6570 |
|
6571 |
The script also prints the name of each system being dumped to the |
6572 |
standard output. |
6573 |
|
6574 |
Following is the full list of options accepted by @code{backup} |
6575 |
script: |
6576 |
|
6577 |
@table @option |
6578 |
@item -l @var{level} |
6579 |
@itemx --level=@var{level} |
6580 |
Do backup level @var{level} (default 0). |
6581 |
|
6582 |
@item -f |
6583 |
@itemx --force |
6584 |
Force backup even if today's log file already exists. |
6585 |
|
6586 |
@item -v[@var{level}] |
6587 |
@itemx --verbose[=@var{level}] |
6588 |
Set verbosity level. The higher the level is, the more debugging |
6589 |
information will be output during execution. Default @var{level} |
6590 |
is 100, which means the highest debugging level. |
6591 |
|
6592 |
@item -t @var{start-time} |
6593 |
@itemx --time=@var{start-time} |
6594 |
Wait till @var{time}, then do backup. |
6595 |
|
6596 |
@item -h |
6597 |
@itemx --help |
6598 |
Display short help message and exit. |
6599 |
|
6600 |
@item -V |
6601 |
@itemx --version |
6602 |
Display information about the program's name, version, origin and legal |
6603 |
status, all on standard output, and then exit successfully. |
6604 |
@end table |
6605 |
|
6606 |
|
6607 |
@node Scripted Restoration |
6608 |
@section Using the Restore Script |
6609 |
|
6610 |
To restore files that were archived using a scripted backup, use the |
6611 |
@code{restore} script. Its usage is quite straightforward. In the |
6612 |
simplest form, invoke @code{restore --all}, it will |
6613 |
then restore all the file systems and files specified in |
6614 |
@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}). |
6615 |
|
6616 |
You may select the file systems (and/or files) to restore by |
6617 |
giving @code{restore} a list of @dfn{patterns} in its command |
6618 |
line. For example, running |
6619 |
|
6620 |
@smallexample |
6621 |
restore 'albert:*' |
6622 |
@end smallexample |
6623 |
|
6624 |
@noindent |
6625 |
will restore all file systems on the machine @samp{albert}. A more |
6626 |
complicated example: |
6627 |
|
6628 |
@smallexample |
6629 |
restore 'albert:*' '*:/var' |
6630 |
@end smallexample |
6631 |
|
6632 |
@noindent |
6633 |
This command will restore all file systems on the machine @samp{albert} |
6634 |
as well as @file{/var} file system on all machines. |
6635 |
|
6636 |
By default @code{restore} will start restoring files from the lowest |
6637 |
available dump level (usually zero) and will continue through |
6638 |
all available dump levels. There may be situations where such a |
6639 |
thorough restore is not necessary. For example, you may wish to |
6640 |
restore only files from the recent level one backup. To do so, |
6641 |
use @option{--level} option, as shown in the example below: |
6642 |
|
6643 |
@smallexample |
6644 |
restore --level=1 |
6645 |
@end smallexample |
6646 |
|
6647 |
The full list of options accepted by @code{restore} follows: |
6648 |
|
6649 |
@table @option |
6650 |
@item -a |
6651 |
@itemx --all |
6652 |
Restore all file systems and files specified in @file{backup-specs}. |
6653 |
|
6654 |
@item -l @var{level} |
6655 |
@itemx --level=@var{level} |
6656 |
Start restoring from the given backup level, instead of the default 0. |
6657 |
|
6658 |
@item -v[@var{level}] |
6659 |
@itemx --verbose[=@var{level}] |
6660 |
Set verbosity level. The higher the level is, the more debugging |
6661 |
information will be output during execution. Default @var{level} |
6662 |
is 100, which means the highest debugging level. |
6663 |
|
6664 |
@item -h |
6665 |
@itemx --help |
6666 |
Display short help message and exit. |
6667 |
|
6668 |
@item -V |
6669 |
@itemx --version |
6670 |
Display information about the program's name, version, origin and legal |
6671 |
status, all on standard output, and then exit successfully. |
6672 |
@end table |
6673 |
|
6674 |
You should start the restore script with the media containing the |
6675 |
first volume of the archive mounted. The script will prompt for other |
6676 |
volumes as they are needed. If the archive is on tape, you don't need |
6677 |
to rewind the tape to to its beginning---if the tape head is |
6678 |
positioned past the beginning of the archive, the script will rewind |
6679 |
the tape as needed. @xref{Tape Positioning}, for a discussion of tape |
6680 |
positioning. |
6681 |
|
6682 |
@quotation |
6683 |
@strong{Warning:} The script will delete files from the active file |
6684 |
system if they were not in the file system when the archive was made. |
6685 |
@end quotation |
6686 |
|
6687 |
@xref{Incremental Dumps}, for an explanation of how the script makes |
6688 |
that determination. |
6689 |
|
6690 |
@node Choosing |
6691 |
@chapter Choosing Files and Names for @command{tar} |
6692 |
|
6693 |
Certain options to @command{tar} enable you to specify a name for your |
6694 |
archive. Other options let you decide which files to include or exclude |
6695 |
from the archive, based on when or whether files were modified, whether |
6696 |
the file names do or don't match specified patterns, or whether files |
6697 |
are in specified directories. |
6698 |
|
6699 |
This chapter discusses these options in detail. |
6700 |
|
6701 |
@menu |
6702 |
* file:: Choosing the Archive's Name |
6703 |
* Selecting Archive Members:: |
6704 |
* files:: Reading Names from a File |
6705 |
* exclude:: Excluding Some Files |
6706 |
* wildcards:: Wildcards Patterns and Matching |
6707 |
* quoting styles:: Ways of Quoting Special Characters in Names |
6708 |
* transform:: Modifying File and Member Names |
6709 |
* after:: Operating Only on New Files |
6710 |
* recurse:: Descending into Directories |
6711 |
* one:: Crossing File System Boundaries |
6712 |
@end menu |
6713 |
|
6714 |
@node file |
6715 |
@section Choosing and Naming Archive Files |
6716 |
|
6717 |
@cindex Naming an archive |
6718 |
@cindex Archive Name |
6719 |
@cindex Choosing an archive file |
6720 |
@cindex Where is the archive? |
6721 |
@opindex file |
6722 |
By default, @command{tar} uses an archive file name that was compiled when |
6723 |
it was built on the system; usually this name refers to some physical |
6724 |
tape drive on the machine. However, the person who installed @command{tar} |
6725 |
on the system may not have set the default to a meaningful value as far as |
6726 |
most users are concerned. As a result, you will usually want to tell |
6727 |
@command{tar} where to find (or create) the archive. The |
6728 |
@option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) |
6729 |
option allows you to either specify or name a file to use as the archive |
6730 |
instead of the default archive file location. |
6731 |
|
6732 |
@table @option |
6733 |
@xopindex{file, short description} |
6734 |
@item --file=@var{archive-name} |
6735 |
@itemx -f @var{archive-name} |
6736 |
Name the archive to create or operate on. Use in conjunction with |
6737 |
any operation. |
6738 |
@end table |
6739 |
|
6740 |
For example, in this @command{tar} command, |
6741 |
|
6742 |
@smallexample |
6743 |
$ @kbd{tar -cvf collection.tar blues folk jazz} |
6744 |
@end smallexample |
6745 |
|
6746 |
@noindent |
6747 |
@file{collection.tar} is the name of the archive. It must directly |
6748 |
follow the @option{-f} option, since whatever directly follows @option{-f} |
6749 |
@emph{will} end up naming the archive. If you neglect to specify an |
6750 |
archive name, you may end up overwriting a file in the working directory |
6751 |
with the archive you create since @command{tar} will use this file's name |
6752 |
for the archive name. |
6753 |
|
6754 |
An archive can be saved as a file in the file system, sent through a |
6755 |
pipe or over a network, or written to an I/O device such as a tape, |
6756 |
floppy disk, or CD write drive. |
6757 |
|
6758 |
@cindex Writing new archives |
6759 |
@cindex Archive creation |
6760 |
If you do not name the archive, @command{tar} uses the value of the |
6761 |
environment variable @env{TAPE} as the file name for the archive. If |
6762 |
that is not available, @command{tar} uses a default, compiled-in archive |
6763 |
name, usually that for tape unit zero (i.e., @file{/dev/tu00}). |
6764 |
|
6765 |
@cindex Standard input and output |
6766 |
@cindex tar to standard input and output |
6767 |
If you use @file{-} as an @var{archive-name}, @command{tar} reads the |
6768 |
archive from standard input (when listing or extracting files), or |
6769 |
writes it to standard output (when creating an archive). If you use |
6770 |
@file{-} as an @var{archive-name} when modifying an archive, |
6771 |
@command{tar} reads the original archive from its standard input and |
6772 |
writes the entire new archive to its standard output. |
6773 |
|
6774 |
The following example is a convenient way of copying directory |
6775 |
hierarchy from @file{sourcedir} to @file{targetdir}. |
6776 |
|
6777 |
@smallexample |
6778 |
$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)} |
6779 |
@end smallexample |
6780 |
|
6781 |
The @option{-C} option allows to avoid using subshells: |
6782 |
|
6783 |
@smallexample |
6784 |
$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -} |
6785 |
@end smallexample |
6786 |
|
6787 |
In both examples above, the leftmost @command{tar} invocation archives |
6788 |
the contents of @file{sourcedir} to the standard output, while the |
6789 |
rightmost one reads this archive from its standard input and |
6790 |
extracts it. The @option{-p} option tells it to restore permissions |
6791 |
of the extracted files. |
6792 |
|
6793 |
@cindex Remote devices |
6794 |
@cindex tar to a remote device |
6795 |
@anchor{remote-dev} |
6796 |
To specify an archive file on a device attached to a remote machine, |
6797 |
use the following: |
6798 |
|
6799 |
@smallexample |
6800 |
@kbd{--file=@var{hostname}:/@var{dev}/@var{file-name}} |
6801 |
@end smallexample |
6802 |
|
6803 |
@noindent |
6804 |
@command{tar} will set up the remote connection, if possible, and |
6805 |
prompt you for a username and password. If you use |
6806 |
@option{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar} |
6807 |
will attempt to set up the remote connection using your username |
6808 |
as the username on the remote machine. |
6809 |
|
6810 |
@cindex Local and remote archives |
6811 |
@anchor{local and remote archives} |
6812 |
If the archive file name includes a colon (@samp{:}), then it is assumed |
6813 |
to be a file on another machine. If the archive file is |
6814 |
@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the |
6815 |
host @var{host}. The remote host is accessed using the @command{rsh} |
6816 |
program, with a username of @var{user}. If the username is omitted |
6817 |
(along with the @samp{@@} sign), then your user name will be used. |
6818 |
(This is the normal @command{rsh} behavior.) It is necessary for the |
6819 |
remote machine, in addition to permitting your @command{rsh} access, to |
6820 |
have the @file{rmt} program installed (this command is included in |
6821 |
the @GNUTAR{} distribution and by default is installed under |
6822 |
@file{@var{prefix}/libexec/rmt}, where @var{prefix} means your |
6823 |
installation prefix). If you need to use a file whose name includes a |
6824 |
colon, then the remote tape drive behavior |
6825 |
can be inhibited by using the @option{--force-local} option. |
6826 |
|
6827 |
When the archive is being created to @file{/dev/null}, @GNUTAR{} |
6828 |
tries to minimize input and output operations. The Amanda backup |
6829 |
system, when used with @GNUTAR{}, has an initial sizing pass which |
6830 |
uses this feature. |
6831 |
|
6832 |
@node Selecting Archive Members |
6833 |
@section Selecting Archive Members |
6834 |
@cindex Specifying files to act on |
6835 |
@cindex Specifying archive members |
6836 |
|
6837 |
@dfn{File Name arguments} specify which files in the file system |
6838 |
@command{tar} operates on, when creating or adding to an archive, or which |
6839 |
archive members @command{tar} operates on, when reading or deleting from |
6840 |
an archive. @xref{Operations}. |
6841 |
|
6842 |
To specify file names, you can include them as the last arguments on |
6843 |
the command line, as follows: |
6844 |
@smallexample |
6845 |
@kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}] |
6846 |
@end smallexample |
6847 |
|
6848 |
If a file name begins with dash (@samp{-}), precede it with |
6849 |
@option{--add-file} option to prevent it from being treated as an |
6850 |
option. |
6851 |
|
6852 |
@anchor{input name quoting} |
6853 |
By default @GNUTAR{} attempts to @dfn{unquote} each file or member |
6854 |
name, replacing @dfn{escape sequences} according to the following |
6855 |
table: |
6856 |
|
6857 |
@multitable @columnfractions 0.20 0.60 |
6858 |
@headitem Escape @tab Replaced with |
6859 |
@item \a @tab Audible bell (@acronym{ASCII} 7) |
6860 |
@item \b @tab Backspace (@acronym{ASCII} 8) |
6861 |
@item \f @tab Form feed (@acronym{ASCII} 12) |
6862 |
@item \n @tab New line (@acronym{ASCII} 10) |
6863 |
@item \r @tab Carriage return (@acronym{ASCII} 13) |
6864 |
@item \t @tab Horizontal tabulation (@acronym{ASCII} 9) |
6865 |
@item \v @tab Vertical tabulation (@acronym{ASCII} 11) |
6866 |
@item \? @tab @acronym{ASCII} 127 |
6867 |
@item \@var{n} @tab @acronym{ASCII} @var{n} (@var{n} should be an octal number |
6868 |
of up to 3 digits) |
6869 |
@end multitable |
6870 |
|
6871 |
A backslash followed by any other symbol is retained. |
6872 |
|
6873 |
This default behavior is controlled by the following command line |
6874 |
option: |
6875 |
|
6876 |
@table @option |
6877 |
@opindex unquote |
6878 |
@item --unquote |
6879 |
Enable unquoting input file or member names (default). |
6880 |
|
6881 |
@opindex no-unquote |
6882 |
@item --no-unquote |
6883 |
Disable unquoting input file or member names. |
6884 |
@end table |
6885 |
|
6886 |
If you specify a directory name as a file name argument, all the files |
6887 |
in that directory are operated on by @command{tar}. |
6888 |
|
6889 |
If you do not specify files, @command{tar} behavior differs depending |
6890 |
on the operation mode as described below: |
6891 |
|
6892 |
When @command{tar} is invoked with @option{--create} (@option{-c}), |
6893 |
@command{tar} will stop immediately, reporting the following: |
6894 |
|
6895 |
@smallexample |
6896 |
@group |
6897 |
$ @kbd{tar cf a.tar} |
6898 |
tar: Cowardly refusing to create an empty archive |
6899 |
Try `tar --help' or `tar --usage' for more information. |
6900 |
@end group |
6901 |
@end smallexample |
6902 |
|
6903 |
If you specify either @option{--list} (@option{-t}) or |
6904 |
@option{--extract} (@option{--get}, @option{-x}), @command{tar} |
6905 |
operates on all the archive members in the archive. |
6906 |
|
6907 |
If run with @option{--diff} option, tar will compare the archive with |
6908 |
the contents of the current working directory. |
6909 |
|
6910 |
If you specify any other operation, @command{tar} does nothing. |
6911 |
|
6912 |
By default, @command{tar} takes file names from the command line. However, |
6913 |
there are other ways to specify file or member names, or to modify the |
6914 |
manner in which @command{tar} selects the files or members upon which to |
6915 |
operate. In general, these methods work both for specifying the names |
6916 |
of files and archive members. |
6917 |
|
6918 |
@node files |
6919 |
@section Reading Names from a File |
6920 |
|
6921 |
@cindex Reading file names from a file |
6922 |
@cindex Lists of file names |
6923 |
@cindex File Name arguments, alternatives |
6924 |
@cindex @command{find}, using with @command{tar} |
6925 |
Instead of giving the names of files or archive members on the command |
6926 |
line, you can put the names into a file, and then use the |
6927 |
@option{--files-from=@var{file-of-names}} (@option{-T |
6928 |
@var{file-of-names}}) option to @command{tar}. Give the name of the |
6929 |
file which contains the list of files to include as the argument to |
6930 |
@option{--files-from}. In the list, the file names should be separated by |
6931 |
newlines. You will frequently use this option when you have generated |
6932 |
the list of files to archive with the @command{find} utility. |
6933 |
|
6934 |
@table @option |
6935 |
@opindex files-from |
6936 |
@item --files-from=@var{file-name} |
6937 |
@itemx -T @var{file-name} |
6938 |
Get names to extract or create from file @var{file-name}. |
6939 |
@end table |
6940 |
|
6941 |
If you give a single dash as a file name for @option{--files-from}, (i.e., |
6942 |
you specify either @code{--files-from=-} or @code{-T -}), then the file |
6943 |
names are read from standard input. |
6944 |
|
6945 |
Unless you are running @command{tar} with @option{--create}, you can not use |
6946 |
both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same |
6947 |
command. |
6948 |
|
6949 |
Any number of @option{-T} options can be given in the command line. |
6950 |
|
6951 |
The following example shows how to use @command{find} to generate a list of |
6952 |
files smaller than 400K in length and put that list into a file |
6953 |
called @file{small-files}. You can then use the @option{-T} option to |
6954 |
@command{tar} to specify the files from that file, @file{small-files}, to |
6955 |
create the archive @file{little.tgz}. (The @option{-z} option to |
6956 |
@command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for |
6957 |
more information.) |
6958 |
|
6959 |
@smallexample |
6960 |
$ @kbd{find . -size -400 -print > small-files} |
6961 |
$ @kbd{tar -c -v -z -T small-files -f little.tgz} |
6962 |
@end smallexample |
6963 |
|
6964 |
@noindent |
6965 |
In the file list given by @option{-T} option, any file name beginning |
6966 |
with @samp{-} character is considered a @command{tar} option and is |
6967 |
processed accordingly@footnote{Versions of @GNUTAR{} up to 1.15.1 |
6968 |
recognized only @option{-C} option in file lists, and only if the |
6969 |
option and its argument occupied two consecutive lines.}. For example, |
6970 |
the common use of this feature is to change to another directory by |
6971 |
specifying @option{-C} option: |
6972 |
|
6973 |
@smallexample |
6974 |
@group |
6975 |
$ @kbd{cat list} |
6976 |
-C/etc |
6977 |
passwd |
6978 |
hosts |
6979 |
-C/lib |
6980 |
libc.a |
6981 |
$ @kbd{tar -c -f foo.tar --files-from list} |
6982 |
@end group |
6983 |
@end smallexample |
6984 |
|
6985 |
@noindent |
6986 |
In this example, @command{tar} will first switch to @file{/etc} |
6987 |
directory and add files @file{passwd} and @file{hosts} to the |
6988 |
archive. Then it will change to @file{/lib} directory and will archive |
6989 |
the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will |
6990 |
contain: |
6991 |
|
6992 |
@smallexample |
6993 |
@group |
6994 |
$ @kbd{tar tf foo.tar} |
6995 |
passwd |
6996 |
hosts |
6997 |
libc.a |
6998 |
@end group |
6999 |
@end smallexample |
7000 |
|
7001 |
@noindent |
7002 |
@xopindex{directory, using in @option{--files-from} argument} |
7003 |
Notice that the option parsing algorithm used with @option{-T} is |
7004 |
stricter than the one used by shell. Namely, when specifying option |
7005 |
arguments, you should observe the following rules: |
7006 |
|
7007 |
@itemize @bullet |
7008 |
@item |
7009 |
When using short (single-letter) option form, its argument must |
7010 |
immediately follow the option letter, without any intervening |
7011 |
whitespace. For example: @code{-Cdir}. |
7012 |
|
7013 |
@item |
7014 |
When using long option form, the option argument must be separated |
7015 |
from the option by a single equal sign. No whitespace is allowed on |
7016 |
any side of the equal sign. For example: @code{--directory=dir}. |
7017 |
|
7018 |
@item |
7019 |
For both short and long option forms, the option argument can be given |
7020 |
on the next line after the option name, e.g.: |
7021 |
|
7022 |
@smallexample |
7023 |
@group |
7024 |
--directory |
7025 |
dir |
7026 |
@end group |
7027 |
@end smallexample |
7028 |
|
7029 |
@noindent |
7030 |
and |
7031 |
|
7032 |
@smallexample |
7033 |
@group |
7034 |
-C |
7035 |
dir |
7036 |
@end group |
7037 |
@end smallexample |
7038 |
@end itemize |
7039 |
|
7040 |
@opindex add-file |
7041 |
If you happen to have a file whose name starts with @samp{-}, |
7042 |
precede it with @option{--add-file} option to prevent it from |
7043 |
being recognized as an option. For example: @code{--add-file=--my-file}. |
7044 |
|
7045 |
@menu |
7046 |
* nul:: |
7047 |
@end menu |
7048 |
|
7049 |
@node nul |
7050 |
@subsection @code{NUL}-Terminated File Names |
7051 |
|
7052 |
@cindex File names, terminated by @code{NUL} |
7053 |
@cindex @code{NUL}-terminated file names |
7054 |
The @option{--null} option causes |
7055 |
@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) |
7056 |
to read file names terminated by a @code{NUL} instead of a newline, so |
7057 |
files whose names contain newlines can be archived using |
7058 |
@option{--files-from}. |
7059 |
|
7060 |
@table @option |
7061 |
@xopindex{null, described} |
7062 |
@item --null |
7063 |
Only consider @code{NUL}-terminated file names, instead of files that |
7064 |
terminate in a newline. |
7065 |
|
7066 |
@xopindex{no-null, described} |
7067 |
@item --no-null |
7068 |
Undo the effect of any previous @option{--null} option. |
7069 |
@end table |
7070 |
|
7071 |
The @option{--null} option is just like the one in @acronym{GNU} |
7072 |
@command{xargs} and @command{cpio}, and is useful with the |
7073 |
@option{-print0} predicate of @acronym{GNU} @command{find}. In |
7074 |
@command{tar}, @option{--null} also disables special handling for |
7075 |
file names that begin with dash. |
7076 |
|
7077 |
This example shows how to use @command{find} to generate a list of files |
7078 |
larger than 800K in length and put that list into a file called |
7079 |
@file{long-files}. The @option{-print0} option to @command{find} is just |
7080 |
like @option{-print}, except that it separates files with a @code{NUL} |
7081 |
rather than with a newline. You can then run @command{tar} with both the |
7082 |
@option{--null} and @option{-T} options to specify that @command{tar} gets the |
7083 |
files from that file, @file{long-files}, to create the archive |
7084 |
@file{big.tgz}. The @option{--null} option to @command{tar} will cause |
7085 |
@command{tar} to recognize the @code{NUL} separator between files. |
7086 |
|
7087 |
@smallexample |
7088 |
$ @kbd{find . -size +800 -print0 > long-files} |
7089 |
$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar} |
7090 |
@end smallexample |
7091 |
|
7092 |
The @option{--no-null} option can be used if you need to read both |
7093 |
@code{NUL}-terminated and newline-terminated files on the same command line. |
7094 |
For example, if @file{flist} is a newline-terminated file, then the |
7095 |
following command can be used to combine it with the above command: |
7096 |
|
7097 |
@smallexample |
7098 |
@group |
7099 |
$ @kbd{find . -size +800 -print0 | |
7100 |
tar -c -f big.tar --null -T - --no-null -T flist} |
7101 |
@end group |
7102 |
@end smallexample |
7103 |
|
7104 |
This example uses short options for typographic reasons, to avoid |
7105 |
very long lines. |
7106 |
|
7107 |
@GNUTAR is able to automatically detect @code{NUL}-terminated file lists, so |
7108 |
it is safe to use them even without the @option{--null} option. In |
7109 |
this case @command{tar} will print a warning and continue reading such |
7110 |
a file as if @option{--null} were actually given: |
7111 |
|
7112 |
@smallexample |
7113 |
@group |
7114 |
$ @kbd{find . -size +800 -print0 | tar -c -f big.tar -T -} |
7115 |
tar: -: file name read contains nul character |
7116 |
@end group |
7117 |
@end smallexample |
7118 |
|
7119 |
The null terminator, however, remains in effect only for this |
7120 |
particular file, any following @option{-T} options will assume |
7121 |
newline termination. Of course, the null autodetection applies |
7122 |
to these eventual surplus @option{-T} options as well. |
7123 |
|
7124 |
@node exclude |
7125 |
@section Excluding Some Files |
7126 |
|
7127 |
@cindex File names, excluding files by |
7128 |
@cindex Excluding files by name and pattern |
7129 |
@cindex Excluding files by file system |
7130 |
@opindex exclude |
7131 |
@opindex exclude-from |
7132 |
To avoid operating on files whose names match a particular pattern, |
7133 |
use the @option{--exclude} or @option{--exclude-from} options. |
7134 |
|
7135 |
@table @option |
7136 |
@opindex exclude |
7137 |
@item --exclude=@var{pattern} |
7138 |
Causes @command{tar} to ignore files that match the @var{pattern}. |
7139 |
@end table |
7140 |
|
7141 |
@findex exclude |
7142 |
The @option{--exclude=@var{pattern}} option prevents any file or |
7143 |
member whose name matches the shell wildcard (@var{pattern}) from |
7144 |
being operated on. |
7145 |
For example, to create an archive with all the contents of the directory |
7146 |
@file{src} except for files whose names end in @file{.o}, use the |
7147 |
command @samp{tar -cf src.tar --exclude='*.o' src}. |
7148 |
|
7149 |
You may give multiple @option{--exclude} options. |
7150 |
|
7151 |
@table @option |
7152 |
@opindex exclude-from |
7153 |
@item --exclude-from=@var{file} |
7154 |
@itemx -X @var{file} |
7155 |
Causes @command{tar} to ignore files that match the patterns listed in |
7156 |
@var{file}. |
7157 |
@end table |
7158 |
|
7159 |
@findex exclude-from |
7160 |
Use the @option{--exclude-from} option to read a |
7161 |
list of patterns, one per line, from @var{file}; @command{tar} will |
7162 |
ignore files matching those patterns. Thus if @command{tar} is |
7163 |
called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a |
7164 |
single line @file{*.o}, no files whose names end in @file{.o} will be |
7165 |
added to the archive. |
7166 |
|
7167 |
Notice, that lines from @var{file} are read verbatim. One of the |
7168 |
frequent errors is leaving some extra whitespace after a file name, |
7169 |
which is difficult to catch using text editors. |
7170 |
|
7171 |
However, empty lines are OK. |
7172 |
|
7173 |
@table @option |
7174 |
@cindex version control system, excluding files |
7175 |
@cindex VCS, excluding files |
7176 |
@cindex SCCS, excluding files |
7177 |
@cindex RCS, excluding files |
7178 |
@cindex CVS, excluding files |
7179 |
@cindex SVN, excluding files |
7180 |
@cindex git, excluding files |
7181 |
@cindex Bazaar, excluding files |
7182 |
@cindex Arch, excluding files |
7183 |
@cindex Mercurial, excluding files |
7184 |
@cindex Darcs, excluding files |
7185 |
@opindex exclude-vcs |
7186 |
@item --exclude-vcs |
7187 |
Exclude files and directories used by following version control |
7188 |
systems: @samp{CVS}, @samp{RCS}, @samp{SCCS}, @samp{SVN}, @samp{Arch}, |
7189 |
@samp{Bazaar}, @samp{Mercurial}, and @samp{Darcs}. |
7190 |
|
7191 |
As of version @value{VERSION}, the following files are excluded: |
7192 |
|
7193 |
@itemize @bullet |
7194 |
@item @file{CVS/}, and everything under it |
7195 |
@item @file{RCS/}, and everything under it |
7196 |
@item @file{SCCS/}, and everything under it |
7197 |
@item @file{.git/}, and everything under it |
7198 |
@item @file{.gitignore} |
7199 |
@item @file{.cvsignore} |
7200 |
@item @file{.svn/}, and everything under it |
7201 |
@item @file{.arch-ids/}, and everything under it |
7202 |
@item @file{@{arch@}/}, and everything under it |
7203 |
@item @file{=RELEASE-ID} |
7204 |
@item @file{=meta-update} |
7205 |
@item @file{=update} |
7206 |
@item @file{.bzr} |
7207 |
@item @file{.bzrignore} |
7208 |
@item @file{.bzrtags} |
7209 |
@item @file{.hg} |
7210 |
@item @file{.hgignore} |
7211 |
@item @file{.hgrags} |
7212 |
@item @file{_darcs} |
7213 |
@end itemize |
7214 |
|
7215 |
@opindex exclude-backups |
7216 |
@item --exclude-backups |
7217 |
Exclude backup and lock files. This option causes exclusion of files |
7218 |
that match the following shell globbing patterns: |
7219 |
|
7220 |
@table @asis |
7221 |
@item .#* |
7222 |
@item *~ |
7223 |
@item #*# |
7224 |
@end table |
7225 |
|
7226 |
@end table |
7227 |
|
7228 |
@findex exclude-caches |
7229 |
When creating an archive, the @option{--exclude-caches} option family |
7230 |
causes @command{tar} to exclude all directories that contain a @dfn{cache |
7231 |
directory tag}. A cache directory tag is a short file with the |
7232 |
well-known name @file{CACHEDIR.TAG} and having a standard header |
7233 |
specified in @url{http://www.brynosaurus.com/cachedir/spec.html}. |
7234 |
Various applications write cache directory tags into directories they |
7235 |
use to hold regenerable, non-precious data, so that such data can be |
7236 |
more easily excluded from backups. |
7237 |
|
7238 |
There are three @samp{exclude-caches} options, each providing a different |
7239 |
exclusion semantics: |
7240 |
|
7241 |
@table @option |
7242 |
@opindex exclude-caches |
7243 |
@item --exclude-caches |
7244 |
Do not archive the contents of the directory, but archive the |
7245 |
directory itself and the @file{CACHEDIR.TAG} file. |
7246 |
|
7247 |
@opindex exclude-caches-under |
7248 |
@item --exclude-caches-under |
7249 |
Do not archive the contents of the directory, nor the |
7250 |
@file{CACHEDIR.TAG} file, archive only the directory itself. |
7251 |
|
7252 |
@opindex exclude-caches-all |
7253 |
@item --exclude-caches-all |
7254 |
Omit directories containing @file{CACHEDIR.TAG} file entirely. |
7255 |
@end table |
7256 |
|
7257 |
@findex exclude-tag |
7258 |
Another option family, @option{--exclude-tag}, provides a generalization of |
7259 |
this concept. It takes a single argument, a file name to look for. |
7260 |
Any directory that contains this file will be excluded from the dump. |
7261 |
Similarly to @samp{exclude-caches}, there are three options in this |
7262 |
option family: |
7263 |
|
7264 |
@table @option |
7265 |
@opindex exclude-tag |
7266 |
@item --exclude-tag=@var{file} |
7267 |
Do not dump the contents of the directory, but dump the |
7268 |
directory itself and the @var{file}. |
7269 |
|
7270 |
@opindex exclude-tag-under |
7271 |
@item --exclude-tag-under=@var{file} |
7272 |
Do not dump the contents of the directory, nor the |
7273 |
@var{file}, archive only the directory itself. |
7274 |
|
7275 |
@opindex exclude-tag-all |
7276 |
@item --exclude-tag-all=@var{file} |
7277 |
Omit directories containing @var{file} file entirely. |
7278 |
@end table |
7279 |
|
7280 |
Multiple @option{--exclude-tag*} options can be given. |
7281 |
|
7282 |
For example, given this directory: |
7283 |
|
7284 |
@smallexample |
7285 |
@group |
7286 |
$ @kbd{find dir} |
7287 |
dir |
7288 |
dir/blues |
7289 |
dir/jazz |
7290 |
dir/folk |
7291 |
dir/folk/tagfile |
7292 |
dir/folk/sanjuan |
7293 |
dir/folk/trote |
7294 |
@end group |
7295 |
@end smallexample |
7296 |
|
7297 |
The @option{--exclude-tag} will produce the following: |
7298 |
|
7299 |
@smallexample |
7300 |
$ @kbd{tar -cf archive.tar --exclude-tag=tagfile -v dir} |
7301 |
dir/ |
7302 |
dir/blues |
7303 |
dir/jazz |
7304 |
dir/folk/ |
7305 |
tar: dir/folk/: contains a cache directory tag tagfile; |
7306 |
contents not dumped |
7307 |
dir/folk/tagfile |
7308 |
@end smallexample |
7309 |
|
7310 |
Both the @file{dir/folk} directory and its tagfile are preserved in |
7311 |
the archive, however the rest of files in this directory are not. |
7312 |
|
7313 |
Now, using the @option{--exclude-tag-under} option will exclude |
7314 |
@file{tagfile} from the dump, while still preserving the directory |
7315 |
itself, as shown in this example: |
7316 |
|
7317 |
@smallexample |
7318 |
$ @kbd{tar -cf archive.tar --exclude-tag-under=tagfile -v dir} |
7319 |
dir/ |
7320 |
dir/blues |
7321 |
dir/jazz |
7322 |
dir/folk/ |
7323 |
./tar: dir/folk/: contains a cache directory tag tagfile; |
7324 |
contents not dumped |
7325 |
@end smallexample |
7326 |
|
7327 |
Finally, using @option{--exclude-tag-all} omits the @file{dir/folk} |
7328 |
directory entirely: |
7329 |
|
7330 |
@smallexample |
7331 |
$ @kbd{tar -cf archive.tar --exclude-tag-all=tagfile -v dir} |
7332 |
dir/ |
7333 |
dir/blues |
7334 |
dir/jazz |
7335 |
./tar: dir/folk/: contains a cache directory tag tagfile; |
7336 |
directory not dumped |
7337 |
@end smallexample |
7338 |
|
7339 |
@menu |
7340 |
* problems with exclude:: |
7341 |
@end menu |
7342 |
|
7343 |
@node problems with exclude |
7344 |
@unnumberedsubsec Problems with Using the @code{exclude} Options |
7345 |
|
7346 |
@xopindex{exclude, potential problems with} |
7347 |
Some users find @samp{exclude} options confusing. Here are some common |
7348 |
pitfalls: |
7349 |
|
7350 |
@itemize @bullet |
7351 |
@item |
7352 |
The main operating mode of @command{tar} does not act on a file name |
7353 |
explicitly listed on the command line, if one of its file name |
7354 |
components is excluded. In the example above, if |
7355 |
you create an archive and exclude files that end with @samp{*.o}, but |
7356 |
explicitly name the file @samp{dir.o/foo} after all the options have been |
7357 |
listed, @samp{dir.o/foo} will be excluded from the archive. |
7358 |
|
7359 |
@item |
7360 |
You can sometimes confuse the meanings of @option{--exclude} and |
7361 |
@option{--exclude-from}. Be careful: use @option{--exclude} when files |
7362 |
to be excluded are given as a pattern on the command line. Use |
7363 |
@option{--exclude-from} to introduce the name of a file which contains |
7364 |
a list of patterns, one per line; each of these patterns can exclude |
7365 |
zero, one, or many files. |
7366 |
|
7367 |
@item |
7368 |
When you use @option{--exclude=@var{pattern}}, be sure to quote the |
7369 |
@var{pattern} parameter, so @GNUTAR{} sees wildcard characters |
7370 |
like @samp{*}. If you do not do this, the shell might expand the |
7371 |
@samp{*} itself using files at hand, so @command{tar} might receive a |
7372 |
list of files instead of one pattern, or none at all, making the |
7373 |
command somewhat illegal. This might not correspond to what you want. |
7374 |
|
7375 |
For example, write: |
7376 |
|
7377 |
@smallexample |
7378 |
$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}} |
7379 |
@end smallexample |
7380 |
|
7381 |
@noindent |
7382 |
rather than: |
7383 |
|
7384 |
@smallexample |
7385 |
# @emph{Wrong!} |
7386 |
$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}} |
7387 |
@end smallexample |
7388 |
|
7389 |
@item |
7390 |
You must use use shell syntax, or globbing, rather than @code{regexp} |
7391 |
syntax, when using exclude options in @command{tar}. If you try to use |
7392 |
@code{regexp} syntax to describe files to be excluded, your command |
7393 |
might fail. |
7394 |
|
7395 |
@item |
7396 |
@FIXME{The change in semantics must have occurred before 1.11, |
7397 |
so I doubt if it is worth mentioning at all. Anyway, should at |
7398 |
least specify in which version the semantics changed.} |
7399 |
In earlier versions of @command{tar}, what is now the |
7400 |
@option{--exclude-from} option was called @option{--exclude} instead. |
7401 |
Now, @option{--exclude} applies to patterns listed on the command |
7402 |
line and @option{--exclude-from} applies to patterns listed in a |
7403 |
file. |
7404 |
|
7405 |
@end itemize |
7406 |
|
7407 |
@node wildcards |
7408 |
@section Wildcards Patterns and Matching |
7409 |
|
7410 |
@dfn{Globbing} is the operation by which @dfn{wildcard} characters, |
7411 |
@samp{*} or @samp{?} for example, are replaced and expanded into all |
7412 |
existing files matching the given pattern. @GNUTAR{} can use wildcard |
7413 |
patterns for matching (or globbing) archive members when extracting |
7414 |
from or listing an archive. Wildcard patterns are also used for |
7415 |
verifying volume labels of @command{tar} archives. This section has the |
7416 |
purpose of explaining wildcard syntax for @command{tar}. |
7417 |
|
7418 |
@FIXME{the next few paragraphs need work.} |
7419 |
|
7420 |
A @var{pattern} should be written according to shell syntax, using wildcard |
7421 |
characters to effect globbing. Most characters in the pattern stand |
7422 |
for themselves in the matched string, and case is significant: @samp{a} |
7423 |
will match only @samp{a}, and not @samp{A}. The character @samp{?} in the |
7424 |
pattern matches any single character in the matched string. The character |
7425 |
@samp{*} in the pattern matches zero, one, or more single characters in |
7426 |
the matched string. The character @samp{\} says to take the following |
7427 |
character of the pattern @emph{literally}; it is useful when one needs to |
7428 |
match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves. |
7429 |
|
7430 |
The character @samp{[}, up to the matching @samp{]}, introduces a character |
7431 |
class. A @dfn{character class} is a list of acceptable characters |
7432 |
for the next single character of the matched string. For example, |
7433 |
@samp{[abcde]} would match any of the first five letters of the alphabet. |
7434 |
Note that within a character class, all of the ``special characters'' |
7435 |
listed above other than @samp{\} lose their special meaning; for example, |
7436 |
@samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\}, |
7437 |
@samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints, |
7438 |
the characters @samp{-} and @samp{]} must either come @emph{first} or |
7439 |
@emph{last} in a character class.) |
7440 |
|
7441 |
@cindex Excluding characters from a character class |
7442 |
@cindex Character class, excluding characters from |
7443 |
If the first character of the class after the opening @samp{[} |
7444 |
is @samp{!} or @samp{^}, then the meaning of the class is reversed. |
7445 |
Rather than listing character to match, it lists those characters which |
7446 |
are @emph{forbidden} as the next single character of the matched string. |
7447 |
|
7448 |
Other characters of the class stand for themselves. The special |
7449 |
construction @samp{[@var{a}-@var{e}]}, using an hyphen between two |
7450 |
letters, is meant to represent all characters between @var{a} and |
7451 |
@var{e}, inclusive. |
7452 |
|
7453 |
@FIXME{need to add a sentence or so here to make this clear for those |
7454 |
who don't have dan around.} |
7455 |
|
7456 |
Periods (@samp{.}) or forward slashes (@samp{/}) are not considered |
7457 |
special for wildcard matches. However, if a pattern completely matches |
7458 |
a directory prefix of a matched string, then it matches the full matched |
7459 |
string: thus, excluding a directory also excludes all the files beneath it. |
7460 |
|
7461 |
@menu |
7462 |
* controlling pattern-matching:: |
7463 |
@end menu |
7464 |
|
7465 |
@node controlling pattern-matching |
7466 |
@unnumberedsubsec Controlling Pattern-Matching |
7467 |
|
7468 |
For the purposes of this section, we call @dfn{exclusion members} all |
7469 |
member names obtained while processing @option{--exclude} and |
7470 |
@option{--exclude-from} options, and @dfn{inclusion members} those |
7471 |
member names that were given in the command line or read from the file |
7472 |
specified with @option{--files-from} option. |
7473 |
|
7474 |
These two pairs of member lists are used in the following operations: |
7475 |
@option{--diff}, @option{--extract}, @option{--list}, |
7476 |
@option{--update}. |
7477 |
|
7478 |
There are no inclusion members in create mode (@option{--create} and |
7479 |
@option{--append}), since in this mode the names obtained from the |
7480 |
command line refer to @emph{files}, not archive members. |
7481 |
|
7482 |
By default, inclusion members are compared with archive members |
7483 |
literally @footnote{Notice that earlier @GNUTAR{} versions used |
7484 |
globbing for inclusion members, which contradicted to UNIX98 |
7485 |
specification and was not documented. @xref{Changes}, for more |
7486 |
information on this and other changes.} and exclusion members are |
7487 |
treated as globbing patterns. For example: |
7488 |
|
7489 |
@smallexample |
7490 |
@group |
7491 |
$ @kbd{tar tf foo.tar} |
7492 |
a.c |
7493 |
b.c |
7494 |
a.txt |
7495 |
[remarks] |
7496 |
# @i{Member names are used verbatim:} |
7497 |
$ @kbd{tar -xf foo.tar -v '[remarks]'} |
7498 |
[remarks] |
7499 |
# @i{Exclude member names are globbed:} |
7500 |
$ @kbd{tar -xf foo.tar -v --exclude '*.c'} |
7501 |
a.txt |
7502 |
[remarks] |
7503 |
@end group |
7504 |
@end smallexample |
7505 |
|
7506 |
This behavior can be altered by using the following options: |
7507 |
|
7508 |
@table @option |
7509 |
@opindex wildcards |
7510 |
@item --wildcards |
7511 |
Treat all member names as wildcards. |
7512 |
|
7513 |
@opindex no-wildcards |
7514 |
@item --no-wildcards |
7515 |
Treat all member names as literal strings. |
7516 |
@end table |
7517 |
|
7518 |
Thus, to extract files whose names end in @samp{.c}, you can use: |
7519 |
|
7520 |
@smallexample |
7521 |
$ @kbd{tar -xf foo.tar -v --wildcards '*.c'} |
7522 |
a.c |
7523 |
b.c |
7524 |
@end smallexample |
7525 |
|
7526 |
@noindent |
7527 |
Notice quoting of the pattern to prevent the shell from interpreting |
7528 |
it. |
7529 |
|
7530 |
The effect of @option{--wildcards} option is canceled by |
7531 |
@option{--no-wildcards}. This can be used to pass part of |
7532 |
the command line arguments verbatim and other part as globbing |
7533 |
patterns. For example, the following invocation: |
7534 |
|
7535 |
@smallexample |
7536 |
$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'} |
7537 |
@end smallexample |
7538 |
|
7539 |
@noindent |
7540 |
instructs @command{tar} to extract from @file{foo.tar} all files whose |
7541 |
names end in @samp{.txt} and the file named @file{[remarks]}. |
7542 |
|
7543 |
Normally, a pattern matches a name if an initial subsequence of the |
7544 |
name's components matches the pattern, where @samp{*}, @samp{?}, and |
7545 |
@samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards, |
7546 |
and wildcards can match @samp{/}. |
7547 |
|
7548 |
Other than optionally stripping leading @samp{/} from names |
7549 |
(@pxref{absolute}), patterns and names are used as-is. For |
7550 |
example, trailing @samp{/} is not trimmed from a user-specified name |
7551 |
before deciding whether to exclude it. |
7552 |
|
7553 |
However, this matching procedure can be altered by the options listed |
7554 |
below. These options accumulate. For example: |
7555 |
|
7556 |
@smallexample |
7557 |
--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme' |
7558 |
@end smallexample |
7559 |
|
7560 |
@noindent |
7561 |
ignores case when excluding @samp{makefile}, but not when excluding |
7562 |
@samp{readme}. |
7563 |
|
7564 |
@table @option |
7565 |
@opindex anchored |
7566 |
@opindex no-anchored |
7567 |
@item --anchored |
7568 |
@itemx --no-anchored |
7569 |
If anchored, a pattern must match an initial subsequence |
7570 |
of the name's components. Otherwise, the pattern can match any |
7571 |
subsequence. Default is @option{--no-anchored} for exclusion members |
7572 |
and @option{--anchored} inclusion members. |
7573 |
|
7574 |
@opindex ignore-case |
7575 |
@opindex no-ignore-case |
7576 |
@item --ignore-case |
7577 |
@itemx --no-ignore-case |
7578 |
When ignoring case, upper-case patterns match lower-case names and vice versa. |
7579 |
When not ignoring case (the default), matching is case-sensitive. |
7580 |
|
7581 |
@opindex wildcards-match-slash |
7582 |
@opindex no-wildcards-match-slash |
7583 |
@item --wildcards-match-slash |
7584 |
@itemx --no-wildcards-match-slash |
7585 |
When wildcards match slash (the default for exclusion members), a |
7586 |
wildcard like @samp{*} in the pattern can match a @samp{/} in the |
7587 |
name. Otherwise, @samp{/} is matched only by @samp{/}. |
7588 |
|
7589 |
@end table |
7590 |
|
7591 |
The @option{--recursion} and @option{--no-recursion} options |
7592 |
(@pxref{recurse}) also affect how member patterns are interpreted. If |
7593 |
recursion is in effect, a pattern matches a name if it matches any of |
7594 |
the name's parent directories. |
7595 |
|
7596 |
The following table summarizes pattern-matching default values: |
7597 |
|
7598 |
@multitable @columnfractions .3 .7 |
7599 |
@headitem Members @tab Default settings |
7600 |
@item Inclusion @tab @option{--no-wildcards --anchored --no-wildcards-match-slash} |
7601 |
@item Exclusion @tab @option{--wildcards --no-anchored --wildcards-match-slash} |
7602 |
@end multitable |
7603 |
|
7604 |
@node quoting styles |
7605 |
@section Quoting Member Names |
7606 |
|
7607 |
When displaying member names, @command{tar} takes care to avoid |
7608 |
ambiguities caused by certain characters. This is called @dfn{name |
7609 |
quoting}. The characters in question are: |
7610 |
|
7611 |
@itemize @bullet |
7612 |
@item Non-printable control characters: |
7613 |
@anchor{escape sequences} |
7614 |
@multitable @columnfractions 0.20 0.10 0.60 |
7615 |
@headitem Character @tab @acronym{ASCII} @tab Character name |
7616 |
@item \a @tab 7 @tab Audible bell |
7617 |
@item \b @tab 8 @tab Backspace |
7618 |
@item \f @tab 12 @tab Form feed |
7619 |
@item \n @tab 10 @tab New line |
7620 |
@item \r @tab 13 @tab Carriage return |
7621 |
@item \t @tab 9 @tab Horizontal tabulation |
7622 |
@item \v @tab 11 @tab Vertical tabulation |
7623 |
@end multitable |
7624 |
|
7625 |
@item Space (@acronym{ASCII} 32) |
7626 |
|
7627 |
@item Single and double quotes (@samp{'} and @samp{"}) |
7628 |
|
7629 |
@item Backslash (@samp{\}) |
7630 |
@end itemize |
7631 |
|
7632 |
The exact way @command{tar} uses to quote these characters depends on |
7633 |
the @dfn{quoting style}. The default quoting style, called |
7634 |
@dfn{escape} (see below), uses backslash notation to represent control |
7635 |
characters, space and backslash. Using this quoting style, control |
7636 |
characters are represented as listed in column @samp{Character} in the |
7637 |
above table, a space is printed as @samp{\ } and a backslash as @samp{\\}. |
7638 |
|
7639 |
@GNUTAR{} offers seven distinct quoting styles, which can be selected |
7640 |
using @option{--quoting-style} option: |
7641 |
|
7642 |
@table @option |
7643 |
@item --quoting-style=@var{style} |
7644 |
@opindex quoting-style |
7645 |
|
7646 |
Sets quoting style. Valid values for @var{style} argument are: |
7647 |
literal, shell, shell-always, c, escape, locale, clocale. |
7648 |
@end table |
7649 |
|
7650 |
These styles are described in detail below. To illustrate their |
7651 |
effect, we will use an imaginary tar archive @file{arch.tar} |
7652 |
containing the following members: |
7653 |
|
7654 |
@smallexample |
7655 |
@group |
7656 |
# 1. Contains horizontal tabulation character. |
7657 |
a tab |
7658 |
# 2. Contains newline character |
7659 |
a |
7660 |
newline |
7661 |
# 3. Contains a space |
7662 |
a space |
7663 |
# 4. Contains double quotes |
7664 |
a"double"quote |
7665 |
# 5. Contains single quotes |
7666 |
a'single'quote |
7667 |
# 6. Contains a backslash character: |
7668 |
a\backslash |
7669 |
@end group |
7670 |
@end smallexample |
7671 |
|
7672 |
Here is how usual @command{ls} command would have listed them, if they |
7673 |
had existed in the current working directory: |
7674 |
|
7675 |
@smallexample |
7676 |
@group |
7677 |
$ @kbd{ls} |
7678 |
a\ttab |
7679 |
a\nnewline |
7680 |
a\ space |
7681 |
a"double"quote |
7682 |
a'single'quote |
7683 |
a\\backslash |
7684 |
@end group |
7685 |
@end smallexample |
7686 |
|
7687 |
Quoting styles: |
7688 |
|
7689 |
@table @samp |
7690 |
@item literal |
7691 |
No quoting, display each character as is: |
7692 |
|
7693 |
@smallexample |
7694 |
@group |
7695 |
$ @kbd{tar tf arch.tar --quoting-style=literal} |
7696 |
./ |
7697 |
./a space |
7698 |
./a'single'quote |
7699 |
./a"double"quote |
7700 |
./a\backslash |
7701 |
./a tab |
7702 |
./a |
7703 |
newline |
7704 |
@end group |
7705 |
@end smallexample |
7706 |
|
7707 |
@item shell |
7708 |
Display characters the same way Bourne shell does: |
7709 |
control characters, except @samp{\t} and @samp{\n}, are printed using |
7710 |
backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a |
7711 |
single quote is printed as @samp{\'}. If a name contains any quoted |
7712 |
characters, it is enclosed in single quotes. In particular, if a name |
7713 |
contains single quotes, it is printed as several single-quoted strings: |
7714 |
|
7715 |
@smallexample |
7716 |
@group |
7717 |
$ @kbd{tar tf arch.tar --quoting-style=shell} |
7718 |
./ |
7719 |
'./a space' |
7720 |
'./a'\''single'\''quote' |
7721 |
'./a"double"quote' |
7722 |
'./a\backslash' |
7723 |
'./a tab' |
7724 |
'./a |
7725 |
newline' |
7726 |
@end group |
7727 |
@end smallexample |
7728 |
|
7729 |
@item shell-always |
7730 |
Same as @samp{shell}, but the names are always enclosed in single |
7731 |
quotes: |
7732 |
|
7733 |
@smallexample |
7734 |
@group |
7735 |
$ @kbd{tar tf arch.tar --quoting-style=shell-always} |
7736 |
'./' |
7737 |
'./a space' |
7738 |
'./a'\''single'\''quote' |
7739 |
'./a"double"quote' |
7740 |
'./a\backslash' |
7741 |
'./a tab' |
7742 |
'./a |
7743 |
newline' |
7744 |
@end group |
7745 |
@end smallexample |
7746 |
|
7747 |
@item c |
7748 |
Use the notation of the C programming language. All names are |
7749 |
enclosed in double quotes. Control characters are quoted using |
7750 |
backslash notations, double quotes are represented as @samp{\"}, |
7751 |
backslash characters are represented as @samp{\\}. Single quotes and |
7752 |
spaces are not quoted: |
7753 |
|
7754 |
@smallexample |
7755 |
@group |
7756 |
$ @kbd{tar tf arch.tar --quoting-style=c} |
7757 |
"./" |
7758 |
"./a space" |
7759 |
"./a'single'quote" |
7760 |
"./a\"double\"quote" |
7761 |
"./a\\backslash" |
7762 |
"./a\ttab" |
7763 |
"./a\nnewline" |
7764 |
@end group |
7765 |
@end smallexample |
7766 |
|
7767 |
@item escape |
7768 |
Control characters are printed using backslash notation, a space is |
7769 |
printed as @samp{\ } and a backslash as @samp{\\}. This is the |
7770 |
default quoting style, unless it was changed when configured the |
7771 |
package. |
7772 |
|
7773 |
@smallexample |
7774 |
@group |
7775 |
$ @kbd{tar tf arch.tar --quoting-style=escape} |
7776 |
./ |
7777 |
./a space |
7778 |
./a'single'quote |
7779 |
./a"double"quote |
7780 |
./a\\backslash |
7781 |
./a\ttab |
7782 |
./a\nnewline |
7783 |
@end group |
7784 |
@end smallexample |
7785 |
|
7786 |
@item locale |
7787 |
Control characters, single quote and backslash are printed using |
7788 |
backslash notation. All names are quoted using left and right |
7789 |
quotation marks, appropriate to the current locale. If it does not |
7790 |
define quotation marks, use @samp{`} as left and @samp{'} as right |
7791 |
quotation marks. Any occurrences of the right quotation mark in a |
7792 |
name are escaped with @samp{\}, for example: |
7793 |
|
7794 |
For example: |
7795 |
|
7796 |
@smallexample |
7797 |
@group |
7798 |
$ @kbd{tar tf arch.tar --quoting-style=locale} |
7799 |
`./' |
7800 |
`./a space' |
7801 |
`./a\'single\'quote' |
7802 |
`./a"double"quote' |
7803 |
`./a\\backslash' |
7804 |
`./a\ttab' |
7805 |
`./a\nnewline' |
7806 |
@end group |
7807 |
@end smallexample |
7808 |
|
7809 |
@item clocale |
7810 |
Same as @samp{locale}, but @samp{"} is used for both left and right |
7811 |
quotation marks, if not provided by the currently selected locale: |
7812 |
|
7813 |
@smallexample |
7814 |
@group |
7815 |
$ @kbd{tar tf arch.tar --quoting-style=clocale} |
7816 |
"./" |
7817 |
"./a space" |
7818 |
"./a'single'quote" |
7819 |
"./a\"double\"quote" |
7820 |
"./a\\backslash" |
7821 |
"./a\ttab" |
7822 |
"./a\nnewline" |
7823 |
@end group |
7824 |
@end smallexample |
7825 |
@end table |
7826 |
|
7827 |
You can specify which characters should be quoted in addition to those |
7828 |
implied by the current quoting style: |
7829 |
|
7830 |
@table @option |
7831 |
@item --quote-chars=@var{string} |
7832 |
Always quote characters from @var{string}, even if the selected |
7833 |
quoting style would not quote them. |
7834 |
@end table |
7835 |
|
7836 |
For example, using @samp{escape} quoting (compare with the usual |
7837 |
escape listing above): |
7838 |
|
7839 |
@smallexample |
7840 |
@group |
7841 |
$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'} |
7842 |
./ |
7843 |
./a\ space |
7844 |
./a'single'quote |
7845 |
./a\"double\"quote |
7846 |
./a\\backslash |
7847 |
./a\ttab |
7848 |
./a\nnewline |
7849 |
@end group |
7850 |
@end smallexample |
7851 |
|
7852 |
To disable quoting of such additional characters, use the following |
7853 |
option: |
7854 |
|
7855 |
@table @option |
7856 |
@item --no-quote-chars=@var{string} |
7857 |
Remove characters listed in @var{string} from the list of quoted |
7858 |
characters set by the previous @option{--quote-chars} option. |
7859 |
@end table |
7860 |
|
7861 |
This option is particularly useful if you have added |
7862 |
@option{--quote-chars} to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS}) |
7863 |
and wish to disable it for the current invocation. |
7864 |
|
7865 |
Note, that @option{--no-quote-chars} does @emph{not} disable those |
7866 |
characters that are quoted by default in the selected quoting style. |
7867 |
|
7868 |
@node transform |
7869 |
@section Modifying File and Member Names |
7870 |
|
7871 |
@command{Tar} archives contain detailed information about files stored |
7872 |
in them and full file names are part of that information. When |
7873 |
storing a file to an archive, its file name is recorded in it, |
7874 |
along with the actual file contents. When restoring from an archive, |
7875 |
a file is created on disk with exactly the same name as that stored |
7876 |
in the archive. In the majority of cases this is the desired behavior |
7877 |
of a file archiver. However, there are some cases when it is not. |
7878 |
|
7879 |
First of all, it is often unsafe to extract archive members with |
7880 |
absolute file names or those that begin with a @file{../}. @GNUTAR{} |
7881 |
takes special precautions when extracting such names and provides a |
7882 |
special option for handling them, which is described in |
7883 |
@ref{absolute}. |
7884 |
|
7885 |
Secondly, you may wish to extract file names without some leading |
7886 |
directory components, or with otherwise modified names. In other |
7887 |
cases it is desirable to store files under differing names in the |
7888 |
archive. |
7889 |
|
7890 |
@GNUTAR{} provides several options for these needs. |
7891 |
|
7892 |
@table @option |
7893 |
@opindex strip-components |
7894 |
@item --strip-components=@var{number} |
7895 |
Strip given @var{number} of leading components from file names before |
7896 |
extraction. |
7897 |
@end table |
7898 |
|
7899 |
For example, suppose you have archived whole @file{/usr} hierarchy to |
7900 |
a tar archive named @file{usr.tar}. Among other files, this archive |
7901 |
contains @file{usr/include/stdlib.h}, which you wish to extract to |
7902 |
the current working directory. To do so, you type: |
7903 |
|
7904 |
@smallexample |
7905 |
$ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h} |
7906 |
@end smallexample |
7907 |
|
7908 |
The option @option{--strip=2} instructs @command{tar} to strip the |
7909 |
two leading components (@file{usr/} and @file{include/}) off the file |
7910 |
name. |
7911 |
|
7912 |
If you add the @option{--verbose} (@option{-v}) option to the invocation |
7913 |
above, you will note that the verbose listing still contains the |
7914 |
full file name, with the two removed components still in place. This |
7915 |
can be inconvenient, so @command{tar} provides a special option for |
7916 |
altering this behavior: |
7917 |
|
7918 |
@anchor{show-transformed-names} |
7919 |
@table @option |
7920 |
@opindex show-transformed-names |
7921 |
@item --show-transformed-names |
7922 |
Display file or member names with all requested transformations |
7923 |
applied. |
7924 |
@end table |
7925 |
|
7926 |
@noindent |
7927 |
For example: |
7928 |
|
7929 |
@smallexample |
7930 |
@group |
7931 |
$ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h} |
7932 |
usr/include/stdlib.h |
7933 |
$ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h} |
7934 |
stdlib.h |
7935 |
@end group |
7936 |
@end smallexample |
7937 |
|
7938 |
Notice that in both cases the file @file{stdlib.h} is extracted to the |
7939 |
current working directory, @option{--show-transformed-names} affects |
7940 |
only the way its name is displayed. |
7941 |
|
7942 |
This option is especially useful for verifying whether the invocation |
7943 |
will have the desired effect. Thus, before running |
7944 |
|
7945 |
@smallexample |
7946 |
$ @kbd{tar -x --strip=@var{n}} |
7947 |
@end smallexample |
7948 |
|
7949 |
@noindent |
7950 |
it is often advisable to run |
7951 |
|
7952 |
@smallexample |
7953 |
$ @kbd{tar -t -v --show-transformed --strip=@var{n}} |
7954 |
@end smallexample |
7955 |
|
7956 |
@noindent |
7957 |
to make sure the command will produce the intended results. |
7958 |
|
7959 |
In case you need to apply more complex modifications to the file name, |
7960 |
@GNUTAR{} provides a general-purpose transformation option: |
7961 |
|
7962 |
@table @option |
7963 |
@opindex transform |
7964 |
@opindex xform |
7965 |
@item --transform=@var{expression} |
7966 |
@itemx --xform=@var{expression} |
7967 |
Modify file names using supplied @var{expression}. |
7968 |
@end table |
7969 |
|
7970 |
@noindent |
7971 |
The @var{expression} is a @command{sed}-like replace expression of the |
7972 |
form: |
7973 |
|
7974 |
@smallexample |
7975 |
s/@var{regexp}/@var{replace}/[@var{flags}] |
7976 |
@end smallexample |
7977 |
|
7978 |
@noindent |
7979 |
where @var{regexp} is a @dfn{regular expression}, @var{replace} is a |
7980 |
replacement for each file name part that matches @var{regexp}. Both |
7981 |
@var{regexp} and @var{replace} are described in detail in |
7982 |
@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}. |
7983 |
|
7984 |
Any delimiter can be used in lieu of @samp{/}, the only requirement being |
7985 |
that it be used consistently throughout the expression. For example, |
7986 |
the following two expressions are equivalent: |
7987 |
|
7988 |
@smallexample |
7989 |
@group |
7990 |
s/one/two/ |
7991 |
s,one,two, |
7992 |
@end group |
7993 |
@end smallexample |
7994 |
|
7995 |
Changing delimiters is often useful when the @var{regex} contains |
7996 |
slashes. For example, it is more convenient to write @code{s,/,-,} than |
7997 |
@code{s/\//-/}. |
7998 |
|
7999 |
As in @command{sed}, you can give several replace expressions, |
8000 |
separated by a semicolon. |
8001 |
|
8002 |
Supported @var{flags} are: |
8003 |
|
8004 |
@table @samp |
8005 |
@item g |
8006 |
Apply the replacement to @emph{all} matches to the @var{regexp}, not |
8007 |
just the first. |
8008 |
|
8009 |
@item i |
8010 |
Use case-insensitive matching. |
8011 |
|
8012 |
@item x |
8013 |
@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended |
8014 |
regexps, Extended regular expressions, Extended regular expressions, |
8015 |
sed, GNU sed}). |
8016 |
|
8017 |
@item @var{number} |
8018 |
Only replace the @var{number}th match of the @var{regexp}. |
8019 |
|
8020 |
Note: the @acronym{POSIX} standard does not specify what should happen |
8021 |
when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{} |
8022 |
follows the GNU @command{sed} implementation in this regard, so |
8023 |
the interaction is defined to be: ignore matches before the |
8024 |
@var{number}th, and then match and replace all matches from the |
8025 |
@var{number}th on. |
8026 |
|
8027 |
@end table |
8028 |
|
8029 |
In addition, several @dfn{transformation scope} flags are supported, |
8030 |
that control to what files transformations apply. These are: |
8031 |
|
8032 |
@table @samp |
8033 |
@item r |
8034 |
Apply transformation to regular archive members. |
8035 |
|
8036 |
@item R |
8037 |
Do not apply transformation to regular archive members. |
8038 |
|
8039 |
@item s |
8040 |
Apply transformation to symbolic link targets. |
8041 |
|
8042 |
@item S |
8043 |
Do not apply transformation to symbolic link targets. |
8044 |
|
8045 |
@item h |
8046 |
Apply transformation to hard link targets. |
8047 |
|
8048 |
@item H |
8049 |
Do not apply transformation to hard link targets. |
8050 |
@end table |
8051 |
|
8052 |
Default is @samp{rsh}, which means to apply tranformations to both archive |
8053 |
members and targets of symbolic and hard links. |
8054 |
|
8055 |
Default scope flags can also be changed using @samp{flags=} statement |
8056 |
in the transform expression. The flags set this way remain in force |
8057 |
until next @samp{flags=} statement or end of expression, whichever |
8058 |
occurs first. For example: |
8059 |
|
8060 |
@smallexample |
8061 |
--transform 'flags=S;s|^|/usr/local/|' |
8062 |
@end smallexample |
8063 |
|
8064 |
Here are several examples of @option{--transform} usage: |
8065 |
|
8066 |
@enumerate |
8067 |
@item Extract @file{usr/} hierarchy into @file{usr/local/}: |
8068 |
|
8069 |
@smallexample |
8070 |
$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar} |
8071 |
@end smallexample |
8072 |
|
8073 |
@item Strip two leading directory components (equivalent to |
8074 |
@option{--strip-components=2}): |
8075 |
|
8076 |
@smallexample |
8077 |
$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar} |
8078 |
@end smallexample |
8079 |
|
8080 |
@item Convert each file name to lower case: |
8081 |
|
8082 |
@smallexample |
8083 |
$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar} |
8084 |
@end smallexample |
8085 |
|
8086 |
@item Prepend @file{/prefix/} to each file name: |
8087 |
|
8088 |
@smallexample |
8089 |
$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar} |
8090 |
@end smallexample |
8091 |
|
8092 |
@item Archive the @file{/lib} directory, prepending @samp{/usr/local} |
8093 |
to each archive member: |
8094 |
|
8095 |
@smallexample |
8096 |
$ @kbd{tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib} |
8097 |
@end smallexample |
8098 |
@end enumerate |
8099 |
|
8100 |
Notice the use of flags in the last example. The @file{/lib} |
8101 |
directory often contains many symbolic links to files within it. |
8102 |
It may look, for example, like this: |
8103 |
|
8104 |
@smallexample |
8105 |
$ @kbd{ls -l} |
8106 |
drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/ |
8107 |
-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so |
8108 |
lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so |
8109 |
... |
8110 |
@end smallexample |
8111 |
|
8112 |
Using the expression @samp{s,^,/usr/local/,} would mean adding |
8113 |
@samp{/usr/local} to both regular archive members and to link |
8114 |
targets. In this case, @file{/lib/libc.so.6} would become: |
8115 |
|
8116 |
@smallexample |
8117 |
/usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so |
8118 |
@end smallexample |
8119 |
|
8120 |
This is definitely not desired. To avoid this, the @samp{S} flag |
8121 |
is used, which excludes symbolic link targets from filename |
8122 |
transformations. The result is: |
8123 |
|
8124 |
@smallexample |
8125 |
$ @kbd{tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \ |
8126 |
--show-transformed /lib} |
8127 |
drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/ |
8128 |
-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so |
8129 |
lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \ |
8130 |
-> libc-2.3.2.so |
8131 |
@end smallexample |
8132 |
|
8133 |
Unlike @option{--strip-components}, @option{--transform} can be used |
8134 |
in any @GNUTAR{} operation mode. For example, the following command |
8135 |
adds files to the archive while replacing the leading @file{usr/} |
8136 |
component with @file{var/}: |
8137 |
|
8138 |
@smallexample |
8139 |
$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /} |
8140 |
@end smallexample |
8141 |
|
8142 |
To test @option{--transform} effect we suggest using |
8143 |
@option{--show-transformed-names} option: |
8144 |
|
8145 |
@smallexample |
8146 |
$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \ |
8147 |
--verbose --show-transformed-names /} |
8148 |
@end smallexample |
8149 |
|
8150 |
If both @option{--strip-components} and @option{--transform} are used |
8151 |
together, then @option{--transform} is applied first, and the required |
8152 |
number of components is then stripped from its result. |
8153 |
|
8154 |
You can use as many @option{--transform} options in a single command |
8155 |
line as you want. The specified expressions will then be applied in |
8156 |
order of their appearance. For example, the following two invocations |
8157 |
are equivalent: |
8158 |
|
8159 |
@smallexample |
8160 |
$ @kbd{tar -cf arch.tar --transform='s,/usr/var,/var/' \ |
8161 |
--transform='s,/usr/local,/usr/,'} |
8162 |
$ @kbd{tar -cf arch.tar \ |
8163 |
--transform='s,/usr/var,/var/;s,/usr/local,/usr/,'} |
8164 |
@end smallexample |
8165 |
|
8166 |
@node after |
8167 |
@section Operating Only on New Files |
8168 |
|
8169 |
@cindex Excluding file by age |
8170 |
@cindex Data Modification time, excluding files by |
8171 |
@cindex Modification time, excluding files by |
8172 |
@cindex Age, excluding files by |
8173 |
The @option{--after-date=@var{date}} (@option{--newer=@var{date}}, |
8174 |
@option{-N @var{date}}) option causes @command{tar} to only work on |
8175 |
files whose data modification or status change times are newer than |
8176 |
the @var{date} given. If @var{date} starts with @samp{/} or @samp{.}, |
8177 |
it is taken to be a file name; the data modification time of that file |
8178 |
is used as the date. If you use this option when creating or appending |
8179 |
to an archive, the archive will only include new files. If you use |
8180 |
@option{--after-date} when extracting an archive, @command{tar} will |
8181 |
only extract files newer than the @var{date} you specify. |
8182 |
|
8183 |
If you only want @command{tar} to make the date comparison based on |
8184 |
modification of the file's data (rather than status |
8185 |
changes), then use the @option{--newer-mtime=@var{date}} option. |
8186 |
|
8187 |
@cindex --after-date and --update compared |
8188 |
@cindex --newer-mtime and --update compared |
8189 |
You may use these options with any operation. Note that these options |
8190 |
differ from the @option{--update} (@option{-u}) operation in that they |
8191 |
allow you to specify a particular date against which @command{tar} can |
8192 |
compare when deciding whether or not to archive the files. |
8193 |
|
8194 |
@table @option |
8195 |
@opindex after-date |
8196 |
@opindex newer |
8197 |
@item --after-date=@var{date} |
8198 |
@itemx --newer=@var{date} |
8199 |
@itemx -N @var{date} |
8200 |
Only store files newer than @var{date}. |
8201 |
|
8202 |
Acts on files only if their data modification or status change times are |
8203 |
later than @var{date}. Use in conjunction with any operation. |
8204 |
|
8205 |
If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file |
8206 |
name; the data modification time of that file is used as the date. |
8207 |
|
8208 |
@opindex newer-mtime |
8209 |
@item --newer-mtime=@var{date} |
8210 |
Acts like @option{--after-date}, but only looks at data modification times. |
8211 |
@end table |
8212 |
|
8213 |
These options limit @command{tar} to operate only on files which have |
8214 |
been modified after the date specified. A file's status is considered to have |
8215 |
changed if its contents have been modified, or if its owner, |
8216 |
permissions, and so forth, have been changed. (For more information on |
8217 |
how to specify a date, see @ref{Date input formats}; remember that the |
8218 |
entire date argument must be quoted if it contains any spaces.) |
8219 |
|
8220 |
Gurus would say that @option{--after-date} tests both the data |
8221 |
modification time (@code{mtime}, the time the contents of the file |
8222 |
were last modified) and the status change time (@code{ctime}, the time |
8223 |
the file's status was last changed: owner, permissions, etc.@:) |
8224 |
fields, while @option{--newer-mtime} tests only the @code{mtime} |
8225 |
field. |
8226 |
|
8227 |
To be precise, @option{--after-date} checks @emph{both} @code{mtime} and |
8228 |
@code{ctime} and processes the file if either one is more recent than |
8229 |
@var{date}, while @option{--newer-mtime} only checks @code{mtime} and |
8230 |
disregards @code{ctime}. Neither does it use @code{atime} (the last time the |
8231 |
contents of the file were looked at). |
8232 |
|
8233 |
Date specifiers can have embedded spaces. Because of this, you may need |
8234 |
to quote date arguments to keep the shell from parsing them as separate |
8235 |
arguments. For example, the following command will add to the archive |
8236 |
all the files modified less than two days ago: |
8237 |
|
8238 |
@smallexample |
8239 |
$ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'} |
8240 |
@end smallexample |
8241 |
|
8242 |
When any of these options is used with the option @option{--verbose} |
8243 |
(@pxref{verbose tutorial}) @GNUTAR{} will try to convert the specified |
8244 |
date back to its textual representation and compare that with the |
8245 |
one given with the option. If the two dates differ, @command{tar} will |
8246 |
print a warning saying what date it will use. This is to help user |
8247 |
ensure he is using the right date. For example: |
8248 |
|
8249 |
@smallexample |
8250 |
@group |
8251 |
$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .} |
8252 |
tar: Option --after-date: Treating date `10 days ago' as 2006-06-11 |
8253 |
13:19:37.232434 |
8254 |
@end group |
8255 |
@end smallexample |
8256 |
|
8257 |
@quotation |
8258 |
@strong{Please Note:} @option{--after-date} and @option{--newer-mtime} |
8259 |
should not be used for incremental backups. @xref{Incremental Dumps}, |
8260 |
for proper way of creating incremental backups. |
8261 |
@end quotation |
8262 |
|
8263 |
@node recurse |
8264 |
@section Descending into Directories |
8265 |
@cindex Avoiding recursion in directories |
8266 |
@cindex Descending directories, avoiding |
8267 |
@cindex Directories, avoiding recursion |
8268 |
@cindex Recursion in directories, avoiding |
8269 |
|
8270 |
Usually, @command{tar} will recursively explore all directories (either |
8271 |
those given on the command line or through the @option{--files-from} |
8272 |
option) for the various files they contain. However, you may not always |
8273 |
want @command{tar} to act this way. |
8274 |
|
8275 |
@opindex no-recursion |
8276 |
@cindex @command{find}, using with @command{tar} |
8277 |
The @option{--no-recursion} option inhibits @command{tar}'s recursive descent |
8278 |
into specified directories. If you specify @option{--no-recursion}, you can |
8279 |
use the @command{find} (@pxref{Top,, find, find, GNU Find Manual}) |
8280 |
utility for hunting through levels of directories to |
8281 |
construct a list of file names which you could then pass to @command{tar}. |
8282 |
@command{find} allows you to be more selective when choosing which files to |
8283 |
archive; see @ref{files}, for more information on using @command{find} with |
8284 |
@command{tar}. |
8285 |
|
8286 |
@table @option |
8287 |
@item --no-recursion |
8288 |
Prevents @command{tar} from recursively descending directories. |
8289 |
|
8290 |
@opindex recursion |
8291 |
@item --recursion |
8292 |
Requires @command{tar} to recursively descend directories. |
8293 |
This is the default. |
8294 |
@end table |
8295 |
|
8296 |
When you use @option{--no-recursion}, @GNUTAR{} grabs |
8297 |
directory entries themselves, but does not descend on them |
8298 |
recursively. Many people use @command{find} for locating files they |
8299 |
want to back up, and since @command{tar} @emph{usually} recursively |
8300 |
descends on directories, they have to use the @samp{@w{-not -type d}} |
8301 |
test in their @command{find} invocation (@pxref{Type, Type, Type test, |
8302 |
find, Finding Files}), as they usually do not want all the files in a |
8303 |
directory. They then use the @option{--files-from} option to archive |
8304 |
the files located via @command{find}. |
8305 |
|
8306 |
The problem when restoring files archived in this manner is that the |
8307 |
directories themselves are not in the archive; so the |
8308 |
@option{--same-permissions} (@option{--preserve-permissions}, |
8309 |
@option{-p}) option does not affect them---while users might really |
8310 |
like it to. Specifying @option{--no-recursion} is a way to tell |
8311 |
@command{tar} to grab only the directory entries given to it, adding |
8312 |
no new files on its own. To summarize, if you use @command{find} to |
8313 |
create a list of files to be stored in an archive, use it as follows: |
8314 |
|
8315 |
@smallexample |
8316 |
@group |
8317 |
$ @kbd{find @var{dir} @var{tests} | \ |
8318 |
tar -cf @var{archive} -T - --no-recursion} |
8319 |
@end group |
8320 |
@end smallexample |
8321 |
|
8322 |
The @option{--no-recursion} option also applies when extracting: it |
8323 |
causes @command{tar} to extract only the matched directory entries, not |
8324 |
the files under those directories. |
8325 |
|
8326 |
The @option{--no-recursion} option also affects how globbing patterns |
8327 |
are interpreted (@pxref{controlling pattern-matching}). |
8328 |
|
8329 |
The @option{--no-recursion} and @option{--recursion} options apply to |
8330 |
later options and operands, and can be overridden by later occurrences |
8331 |
of @option{--no-recursion} and @option{--recursion}. For example: |
8332 |
|
8333 |
@smallexample |
8334 |
$ @kbd{tar -cf jams.tar --no-recursion grape --recursion grape/concord} |
8335 |
@end smallexample |
8336 |
|
8337 |
@noindent |
8338 |
creates an archive with one entry for @file{grape}, and the recursive |
8339 |
contents of @file{grape/concord}, but no entries under @file{grape} |
8340 |
other than @file{grape/concord}. |
8341 |
|
8342 |
@node one |
8343 |
@section Crossing File System Boundaries |
8344 |
@cindex File system boundaries, not crossing |
8345 |
|
8346 |
@command{tar} will normally automatically cross file system boundaries in |
8347 |
order to archive files which are part of a directory tree. You can |
8348 |
change this behavior by running @command{tar} and specifying |
8349 |
@option{--one-file-system}. This option only affects files that are |
8350 |
archived because they are in a directory that is being archived; |
8351 |
@command{tar} will still archive files explicitly named on the command line |
8352 |
or through @option{--files-from}, regardless of where they reside. |
8353 |
|
8354 |
@table @option |
8355 |
@opindex one-file-system |
8356 |
@item --one-file-system |
8357 |
Prevents @command{tar} from crossing file system boundaries when |
8358 |
archiving. Use in conjunction with any write operation. |
8359 |
@end table |
8360 |
|
8361 |
The @option{--one-file-system} option causes @command{tar} to modify its |
8362 |
normal behavior in archiving the contents of directories. If a file in |
8363 |
a directory is not on the same file system as the directory itself, then |
8364 |
@command{tar} will not archive that file. If the file is a directory |
8365 |
itself, @command{tar} will not archive anything beneath it; in other words, |
8366 |
@command{tar} will not cross mount points. |
8367 |
|
8368 |
This option is useful for making full or incremental archival backups of |
8369 |
a file system. If this option is used in conjunction with |
8370 |
@option{--verbose} (@option{-v}), files that are excluded are |
8371 |
mentioned by name on the standard error. |
8372 |
|
8373 |
@menu |
8374 |
* directory:: Changing Directory |
8375 |
* absolute:: Absolute File Names |
8376 |
@end menu |
8377 |
|
8378 |
@node directory |
8379 |
@subsection Changing the Working Directory |
8380 |
|
8381 |
@FIXME{need to read over this node now for continuity; i've switched |
8382 |
things around some.} |
8383 |
|
8384 |
@cindex Changing directory mid-stream |
8385 |
@cindex Directory, changing mid-stream |
8386 |
@cindex Working directory, specifying |
8387 |
To change the working directory in the middle of a list of file names, |
8388 |
either on the command line or in a file specified using |
8389 |
@option{--files-from} (@option{-T}), use @option{--directory} (@option{-C}). |
8390 |
This will change the working directory to the specified directory |
8391 |
after that point in the list. |
8392 |
|
8393 |
@table @option |
8394 |
@opindex directory |
8395 |
@item --directory=@var{directory} |
8396 |
@itemx -C @var{directory} |
8397 |
Changes the working directory in the middle of a command line. |
8398 |
@end table |
8399 |
|
8400 |
For example, |
8401 |
|
8402 |
@smallexample |
8403 |
$ @kbd{tar -c -f jams.tar grape prune -C food cherry} |
8404 |
@end smallexample |
8405 |
|
8406 |
@noindent |
8407 |
will place the files @file{grape} and @file{prune} from the current |
8408 |
directory into the archive @file{jams.tar}, followed by the file |
8409 |
@file{cherry} from the directory @file{food}. This option is especially |
8410 |
useful when you have several widely separated files that you want to |
8411 |
store in the same archive. |
8412 |
|
8413 |
Note that the file @file{cherry} is recorded in the archive under the |
8414 |
precise name @file{cherry}, @emph{not} @file{food/cherry}. Thus, the |
8415 |
archive will contain three files that all appear to have come from the |
8416 |
same directory; if the archive is extracted with plain @samp{tar |
8417 |
--extract}, all three files will be written in the current directory. |
8418 |
|
8419 |
Contrast this with the command, |
8420 |
|
8421 |
@smallexample |
8422 |
$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry} |
8423 |
@end smallexample |
8424 |
|
8425 |
@noindent |
8426 |
which records the third file in the archive under the name |
8427 |
@file{red/cherry} so that, if the archive is extracted using |
8428 |
@samp{tar --extract}, the third file will be written in a subdirectory |
8429 |
named @file{red}. |
8430 |
|
8431 |
You can use the @option{--directory} option to make the archive |
8432 |
independent of the original name of the directory holding the files. |
8433 |
The following command places the files @file{/etc/passwd}, |
8434 |
@file{/etc/hosts}, and @file{/lib/libc.a} into the archive |
8435 |
@file{foo.tar}: |
8436 |
|
8437 |
@smallexample |
8438 |
$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a} |
8439 |
@end smallexample |
8440 |
|
8441 |
@noindent |
8442 |
However, the names of the archive members will be exactly what they were |
8443 |
on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}. |
8444 |
They will not appear to be related by file name to the original |
8445 |
directories where those files were located. |
8446 |
|
8447 |
Note that @option{--directory} options are interpreted consecutively. If |
8448 |
@option{--directory} specifies a relative file name, it is interpreted |
8449 |
relative to the then current directory, which might not be the same as |
8450 |
the original current working directory of @command{tar}, due to a previous |
8451 |
@option{--directory} option. |
8452 |
|
8453 |
When using @option{--files-from} (@pxref{files}), you can put various |
8454 |
@command{tar} options (including @option{-C}) in the file list. Notice, |
8455 |
however, that in this case the option and its argument may not be |
8456 |
separated by whitespace. If you use short option, its argument must |
8457 |
either follow the option letter immediately, without any intervening |
8458 |
whitespace, or occupy the next line. Otherwise, if you use long |
8459 |
option, separate its argument by an equal sign. |
8460 |
|
8461 |
For instance, the file list for the above example will be: |
8462 |
|
8463 |
@smallexample |
8464 |
@group |
8465 |
-C/etc |
8466 |
passwd |
8467 |
hosts |
8468 |
--directory=/lib |
8469 |
libc.a |
8470 |
@end group |
8471 |
@end smallexample |
8472 |
|
8473 |
@noindent |
8474 |
To use it, you would invoke @command{tar} as follows: |
8475 |
|
8476 |
@smallexample |
8477 |
$ @kbd{tar -c -f foo.tar --files-from list} |
8478 |
@end smallexample |
8479 |
|
8480 |
The interpretation of @option{--directory} is disabled by |
8481 |
@option{--null} option. |
8482 |
|
8483 |
@node absolute |
8484 |
@subsection Absolute File Names |
8485 |
@cindex absolute file names |
8486 |
@cindex file names, absolute |
8487 |
|
8488 |
By default, @GNUTAR{} drops a leading @samp{/} on |
8489 |
input or output, and complains about file names containing a @file{..} |
8490 |
component. There is an option that turns off this behavior: |
8491 |
|
8492 |
@table @option |
8493 |
@opindex absolute-names |
8494 |
@item --absolute-names |
8495 |
@itemx -P |
8496 |
Do not strip leading slashes from file names, and permit file names |
8497 |
containing a @file{..} file name component. |
8498 |
@end table |
8499 |
|
8500 |
When @command{tar} extracts archive members from an archive, it strips any |
8501 |
leading slashes (@samp{/}) from the member name. This causes absolute |
8502 |
member names in the archive to be treated as relative file names. This |
8503 |
allows you to have such members extracted wherever you want, instead of |
8504 |
being restricted to extracting the member in the exact directory named |
8505 |
in the archive. For example, if the archive member has the name |
8506 |
@file{/etc/passwd}, @command{tar} will extract it as if the name were |
8507 |
really @file{etc/passwd}. |
8508 |
|
8509 |
File names containing @file{..} can cause problems when extracting, so |
8510 |
@command{tar} normally warns you about such files when creating an |
8511 |
archive, and rejects attempts to extracts such files. |
8512 |
|
8513 |
Other @command{tar} programs do not do this. As a result, if you |
8514 |
create an archive whose member names start with a slash, they will be |
8515 |
difficult for other people with a non-@GNUTAR{} |
8516 |
program to use. Therefore, @GNUTAR{} also strips |
8517 |
leading slashes from member names when putting members into the |
8518 |
archive. For example, if you ask @command{tar} to add the file |
8519 |
@file{/bin/ls} to an archive, it will do so, but the member name will |
8520 |
be @file{bin/ls}@footnote{A side effect of this is that when |
8521 |
@option{--create} is used with @option{--verbose} the resulting output |
8522 |
is not, generally speaking, the same as the one you'd get running |
8523 |
@kbd{tar --list} command. This may be important if you use some |
8524 |
scripts for comparing both outputs. @xref{listing member and file names}, |
8525 |
for the information on how to handle this case.}. |
8526 |
|
8527 |
If you use the @option{--absolute-names} (@option{-P}) option, |
8528 |
@command{tar} will do none of these transformations. |
8529 |
|
8530 |
To archive or extract files relative to the root directory, specify |
8531 |
the @option{--absolute-names} (@option{-P}) option. |
8532 |
|
8533 |
Normally, @command{tar} acts on files relative to the working |
8534 |
directory---ignoring superior directory names when archiving, and |
8535 |
ignoring leading slashes when extracting. |
8536 |
|
8537 |
When you specify @option{--absolute-names} (@option{-P}), |
8538 |
@command{tar} stores file names including all superior directory |
8539 |
names, and preserves leading slashes. If you only invoked |
8540 |
@command{tar} from the root directory you would never need the |
8541 |
@option{--absolute-names} option, but using this option |
8542 |
may be more convenient than switching to root. |
8543 |
|
8544 |
@FIXME{Should be an example in the tutorial/wizardry section using this |
8545 |
to transfer files between systems.} |
8546 |
|
8547 |
@table @option |
8548 |
@item --absolute-names |
8549 |
Preserves full file names (including superior directory names) when |
8550 |
archiving files. Preserves leading slash when extracting files. |
8551 |
|
8552 |
@end table |
8553 |
|
8554 |
@command{tar} prints out a message about removing the @samp{/} from |
8555 |
file names. This message appears once per @GNUTAR{} |
8556 |
invocation. It represents something which ought to be told; ignoring |
8557 |
what it means can cause very serious surprises, later. |
8558 |
|
8559 |
Some people, nevertheless, do not want to see this message. Wanting to |
8560 |
play really dangerously, one may of course redirect @command{tar} standard |
8561 |
error to the sink. For example, under @command{sh}: |
8562 |
|
8563 |
@smallexample |
8564 |
$ @kbd{tar -c -f archive.tar /home 2> /dev/null} |
8565 |
@end smallexample |
8566 |
|
8567 |
@noindent |
8568 |
Another solution, both nicer and simpler, would be to change to |
8569 |
the @file{/} directory first, and then avoid absolute notation. |
8570 |
For example: |
8571 |
|
8572 |
@smallexample |
8573 |
$ @kbd{tar -c -f archive.tar -C / home} |
8574 |
@end smallexample |
8575 |
|
8576 |
@xref{Integrity}, for some of the security-related implications |
8577 |
of using this option. |
8578 |
|
8579 |
@include parse-datetime.texi |
8580 |
|
8581 |
@node Formats |
8582 |
@chapter Controlling the Archive Format |
8583 |
|
8584 |
@cindex Tar archive formats |
8585 |
Due to historical reasons, there are several formats of tar archives. |
8586 |
All of them are based on the same principles, but have some subtle |
8587 |
differences that often make them incompatible with each other. |
8588 |
|
8589 |
GNU tar is able to create and handle archives in a variety of formats. |
8590 |
The most frequently used formats are (in alphabetical order): |
8591 |
|
8592 |
@table @asis |
8593 |
@item gnu |
8594 |
Format used by @GNUTAR{} versions up to 1.13.25. This format derived |
8595 |
from an early @acronym{POSIX} standard, adding some improvements such as |
8596 |
sparse file handling and incremental archives. Unfortunately these |
8597 |
features were implemented in a way incompatible with other archive |
8598 |
formats. |
8599 |
|
8600 |
Archives in @samp{gnu} format are able to hold file names of unlimited |
8601 |
length. |
8602 |
|
8603 |
@item oldgnu |
8604 |
Format used by @GNUTAR{} of versions prior to 1.12. |
8605 |
|
8606 |
@item v7 |
8607 |
Archive format, compatible with the V7 implementation of tar. This |
8608 |
format imposes a number of limitations. The most important of them |
8609 |
are: |
8610 |
|
8611 |
@enumerate |
8612 |
@item The maximum length of a file name is limited to 99 characters. |
8613 |
@item The maximum length of a symbolic link is limited to 99 characters. |
8614 |
@item It is impossible to store special files (block and character |
8615 |
devices, fifos etc.) |
8616 |
@item Maximum value of user or group @acronym{ID} is limited to 2097151 (7777777 |
8617 |
octal) |
8618 |
@item V7 archives do not contain symbolic ownership information (user |
8619 |
and group name of the file owner). |
8620 |
@end enumerate |
8621 |
|
8622 |
This format has traditionally been used by Automake when producing |
8623 |
Makefiles. This practice will change in the future, in the meantime, |
8624 |
however this means that projects containing file names more than 99 |
8625 |
characters long will not be able to use @GNUTAR{} @value{VERSION} and |
8626 |
Automake prior to 1.9. |
8627 |
|
8628 |
@item ustar |
8629 |
Archive format defined by @acronym{POSIX.1-1988} specification. It stores |
8630 |
symbolic ownership information. It is also able to store |
8631 |
special files. However, it imposes several restrictions as well: |
8632 |
|
8633 |
@enumerate |
8634 |
@item The maximum length of a file name is limited to 256 characters, |
8635 |
provided that the file name can be split at a directory separator in |
8636 |
two parts, first of them being at most 155 bytes long. So, in most |
8637 |
cases the maximum file name length will be shorter than 256 |
8638 |
characters. |
8639 |
@item The maximum length of a symbolic link name is limited to |
8640 |
100 characters. |
8641 |
@item Maximum size of a file the archive is able to accommodate |
8642 |
is 8GB |
8643 |
@item Maximum value of UID/GID is 2097151. |
8644 |
@item Maximum number of bits in device major and minor numbers is 21. |
8645 |
@end enumerate |
8646 |
|
8647 |
@item star |
8648 |
Format used by J@"org Schilling @command{star} |
8649 |
implementation. @GNUTAR{} is able to read @samp{star} archives but |
8650 |
currently does not produce them. |
8651 |
|
8652 |
@item posix |
8653 |
Archive format defined by @acronym{POSIX.1-2001} specification. This is the |
8654 |
most flexible and feature-rich format. It does not impose any |
8655 |
restrictions on file sizes or file name lengths. This format is quite |
8656 |
recent, so not all tar implementations are able to handle it properly. |
8657 |
However, this format is designed in such a way that any tar |
8658 |
implementation able to read @samp{ustar} archives will be able to read |
8659 |
most @samp{posix} archives as well, with the only exception that any |
8660 |
additional information (such as long file names etc.) will in such |
8661 |
case be extracted as plain text files along with the files it refers to. |
8662 |
|
8663 |
This archive format will be the default format for future versions |
8664 |
of @GNUTAR{}. |
8665 |
|
8666 |
@end table |
8667 |
|
8668 |
The following table summarizes the limitations of each of these |
8669 |
formats: |
8670 |
|
8671 |
@multitable @columnfractions .10 .20 .20 .20 .20 |
8672 |
@headitem Format @tab UID @tab File Size @tab File Name @tab Devn |
8673 |
@item gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63 |
8674 |
@item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63 |
8675 |
@item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a |
8676 |
@item ustar @tab 2097151 @tab 8GB @tab 256 @tab 21 |
8677 |
@item posix @tab Unlimited @tab Unlimited @tab Unlimited @tab Unlimited |
8678 |
@end multitable |
8679 |
|
8680 |
The default format for @GNUTAR{} is defined at compilation |
8681 |
time. You may check it by running @command{tar --help}, and examining |
8682 |
the last lines of its output. Usually, @GNUTAR{} is configured |
8683 |
to create archives in @samp{gnu} format, however, future version will |
8684 |
switch to @samp{posix}. |
8685 |
|
8686 |
@menu |
8687 |
* Compression:: Using Less Space through Compression |
8688 |
* Attributes:: Handling File Attributes |
8689 |
* Portability:: Making @command{tar} Archives More Portable |
8690 |
* cpio:: Comparison of @command{tar} and @command{cpio} |
8691 |
@end menu |
8692 |
|
8693 |
@node Compression |
8694 |
@section Using Less Space through Compression |
8695 |
|
8696 |
@menu |
8697 |
* gzip:: Creating and Reading Compressed Archives |
8698 |
* sparse:: Archiving Sparse Files |
8699 |
@end menu |
8700 |
|
8701 |
@node gzip |
8702 |
@subsection Creating and Reading Compressed Archives |
8703 |
@cindex Compressed archives |
8704 |
@cindex Storing archives in compressed format |
8705 |
|
8706 |
@cindex gzip |
8707 |
@cindex bzip2 |
8708 |
@cindex lzip |
8709 |
@cindex lzma |
8710 |
@cindex lzop |
8711 |
@cindex compress |
8712 |
@GNUTAR{} is able to create and read compressed archives. It supports |
8713 |
a wide variety of compression programs, namely: @command{gzip}, |
8714 |
@command{bzip2}, @command{lzip}, @command{lzma}, @command{lzop}, |
8715 |
@command{xz} and traditional @command{compress}. The latter is |
8716 |
supported mostly for backward compatibility, and we recommend |
8717 |
against using it, because it is by far less effective than the other |
8718 |
compression programs@footnote{It also had patent problems in the past.}. |
8719 |
|
8720 |
Creating a compressed archive is simple: you just specify a |
8721 |
@dfn{compression option} along with the usual archive creation |
8722 |
commands. The compression option is @option{-z} (@option{--gzip}) to |
8723 |
create a @command{gzip} compressed archive, @option{-j} |
8724 |
(@option{--bzip2}) to create a @command{bzip2} compressed archive, |
8725 |
@option{--lzip} to create an @asis{lzip} compressed archive, |
8726 |
@option{-J} (@option{--xz}) to create an @asis{XZ} archive, |
8727 |
@option{--lzma} to create an @asis{LZMA} compressed |
8728 |
archive, @option{--lzop} to create an @asis{LSOP} archive, and |
8729 |
@option{-Z} (@option{--compress}) to use @command{compress} program. |
8730 |
For example: |
8731 |
|
8732 |
@smallexample |
8733 |
$ @kbd{tar cfz archive.tar.gz .} |
8734 |
@end smallexample |
8735 |
|
8736 |
You can also let @GNUTAR{} select the compression program based on |
8737 |
the suffix of the archive file name. This is done using |
8738 |
@option{--auto-compress} (@option{-a}) command line option. For |
8739 |
example, the following invocation will use @command{bzip2} for |
8740 |
compression: |
8741 |
|
8742 |
@smallexample |
8743 |
$ @kbd{tar cfa archive.tar.bz2 .} |
8744 |
@end smallexample |
8745 |
|
8746 |
@noindent |
8747 |
whereas the following one will use @command{lzma}: |
8748 |
|
8749 |
@smallexample |
8750 |
$ @kbd{tar cfa archive.tar.lzma .} |
8751 |
@end smallexample |
8752 |
|
8753 |
For a complete list of file name suffixes recognized by @GNUTAR{}, |
8754 |
see @ref{auto-compress}. |
8755 |
|
8756 |
Reading compressed archive is even simpler: you don't need to specify |
8757 |
any additional options as @GNUTAR{} recognizes its format |
8758 |
automatically. Thus, the following commands will list and extract the |
8759 |
archive created in previous example: |
8760 |
|
8761 |
@smallexample |
8762 |
# List the compressed archive |
8763 |
$ @kbd{tar tf archive.tar.gz} |
8764 |
# Extract the compressed archive |
8765 |
$ @kbd{tar xf archive.tar.gz} |
8766 |
@end smallexample |
8767 |
|
8768 |
The format recognition algorithm is based on @dfn{signatures}, a |
8769 |
special byte sequences in the beginning of file, that are specific for |
8770 |
certain compression formats. If this approach fails, @command{tar} |
8771 |
falls back to using archive name suffix to determine its format |
8772 |
(@pxref{auto-compress}, for a list of recognized suffixes). |
8773 |
|
8774 |
@anchor{alternative decompression programs} |
8775 |
@cindex alternative decompression programs |
8776 |
Some compression programs are able to handle different compression |
8777 |
formats. @GNUTAR{} uses this, if the principal decompressor for the |
8778 |
given format is not available. For example, if @command{compress} is |
8779 |
not installed, @command{tar} will try to use @command{gzip}. As of |
8780 |
version @value{VERSION} the following alternatives are |
8781 |
tried@footnote{To verbosely trace the decompressor selection, use the |
8782 |
@option{--warning=decompress-program} option |
8783 |
(@pxref{warnings,decompress-program}).}: |
8784 |
|
8785 |
@multitable @columnfractions 0.3 0.3 0.3 |
8786 |
@headitem Format @tab Main decompressor @tab Alternatives |
8787 |
@item compress @tab compress @tab gzip |
8788 |
@item lzma @tab lzma @tab xz |
8789 |
@item bzip2 @tab bzip2 @tab lbzip2 |
8790 |
@end multitable |
8791 |
|
8792 |
The only case when you have to specify a decompression option while |
8793 |
reading the archive is when reading from a pipe or from a tape drive |
8794 |
that does not support random access. However, in this case @GNUTAR{} |
8795 |
will indicate which option you should use. For example: |
8796 |
|
8797 |
@smallexample |
8798 |
$ @kbd{cat archive.tar.gz | tar tf -} |
8799 |
tar: Archive is compressed. Use -z option |
8800 |
tar: Error is not recoverable: exiting now |
8801 |
@end smallexample |
8802 |
|
8803 |
If you see such diagnostics, just add the suggested option to the |
8804 |
invocation of @GNUTAR{}: |
8805 |
|
8806 |
@smallexample |
8807 |
$ @kbd{cat archive.tar.gz | tar tfz -} |
8808 |
@end smallexample |
8809 |
|
8810 |
Notice also, that there are several restrictions on operations on |
8811 |
compressed archives. First of all, compressed archives cannot be |
8812 |
modified, i.e., you cannot update (@option{--update}, alias @option{-u}) |
8813 |
them or delete (@option{--delete}) members from them or |
8814 |
add (@option{--append}, alias @option{-r}) members to them. Likewise, you |
8815 |
cannot append another @command{tar} archive to a compressed archive using |
8816 |
@option{--concatenate} (@option{-A}). Secondly, multi-volume |
8817 |
archives cannot be compressed. |
8818 |
|
8819 |
The following options allow to select a particular compressor program: |
8820 |
|
8821 |
@table @option |
8822 |
@opindex gzip |
8823 |
@opindex ungzip |
8824 |
@item -z |
8825 |
@itemx --gzip |
8826 |
@itemx --ungzip |
8827 |
Filter the archive through @command{gzip}. |
8828 |
|
8829 |
@opindex xz |
8830 |
@item -J |
8831 |
@itemx --xz |
8832 |
Filter the archive through @code{xz}. |
8833 |
|
8834 |
@item -j |
8835 |
@itemx --bzip2 |
8836 |
Filter the archive through @code{bzip2}. |
8837 |
|
8838 |
@opindex lzip |
8839 |
@item --lzip |
8840 |
Filter the archive through @command{lzip}. |
8841 |
|
8842 |
@opindex lzma |
8843 |
@item --lzma |
8844 |
Filter the archive through @command{lzma}. |
8845 |
|
8846 |
@opindex lzop |
8847 |
@item --lzop |
8848 |
Filter the archive through @command{lzop}. |
8849 |
|
8850 |
@opindex compress |
8851 |
@opindex uncompress |
8852 |
@item -Z |
8853 |
@itemx --compress |
8854 |
@itemx --uncompress |
8855 |
Filter the archive through @command{compress}. |
8856 |
@end table |
8857 |
|
8858 |
When any of these options is given, @GNUTAR{} searches the compressor |
8859 |
binary in the current path and invokes it. The name of the compressor |
8860 |
program is specified at compilation time using a corresponding |
8861 |
@option{--with-@var{compname}} option to @command{configure}, e.g. |
8862 |
@option{--with-bzip2} to select a specific @command{bzip2} binary. |
8863 |
@xref{lbzip2}, for a detailed discussion. |
8864 |
|
8865 |
The output produced by @command{tar --help} shows the actual |
8866 |
compressor names along with each of these options. |
8867 |
|
8868 |
You can use any of these options on physical devices (tape drives, |
8869 |
etc.) and remote files as well as on normal files; data to or from |
8870 |
such devices or remote files is reblocked by another copy of the |
8871 |
@command{tar} program to enforce the specified (or default) record |
8872 |
size. The default compression parameters are used. Most compression |
8873 |
programs allow to override these by setting a program-specific |
8874 |
environment variable. For example, when using @command{gzip} you can |
8875 |
use @env{GZIP} as in the example below: |
8876 |
|
8877 |
@smallexample |
8878 |
$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir} |
8879 |
@end smallexample |
8880 |
|
8881 |
@noindent |
8882 |
Another way would be to use the @option{-I} option instead (see |
8883 |
below), e.g.: |
8884 |
|
8885 |
@smallexample |
8886 |
$ @kbd{tar -cf archive.tar.gz -I 'gzip --best' subdir} |
8887 |
@end smallexample |
8888 |
|
8889 |
@noindent |
8890 |
Finally, the third, traditional, way to achieve the same result is to |
8891 |
use pipe: |
8892 |
|
8893 |
@smallexample |
8894 |
$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz} |
8895 |
@end smallexample |
8896 |
|
8897 |
@cindex corrupted archives |
8898 |
About corrupted compressed archives: compressed files have no |
8899 |
redundancy, for maximum compression. The adaptive nature of the |
8900 |
compression scheme means that the compression tables are implicitly |
8901 |
spread all over the archive. If you lose a few blocks, the dynamic |
8902 |
construction of the compression tables becomes unsynchronized, and there |
8903 |
is little chance that you could recover later in the archive. |
8904 |
|
8905 |
Another compression options provide a better control over creating |
8906 |
compressed archives. These are: |
8907 |
|
8908 |
@table @option |
8909 |
@anchor{auto-compress} |
8910 |
@opindex auto-compress |
8911 |
@item --auto-compress |
8912 |
@itemx -a |
8913 |
Select a compression program to use by the archive file name |
8914 |
suffix. The following suffixes are recognized: |
8915 |
|
8916 |
@multitable @columnfractions 0.3 0.6 |
8917 |
@headitem Suffix @tab Compression program |
8918 |
@item @samp{.gz} @tab @command{gzip} |
8919 |
@item @samp{.tgz} @tab @command{gzip} |
8920 |
@item @samp{.taz} @tab @command{gzip} |
8921 |
@item @samp{.Z} @tab @command{compress} |
8922 |
@item @samp{.taZ} @tab @command{compress} |
8923 |
@item @samp{.bz2} @tab @command{bzip2} |
8924 |
@item @samp{.tz2} @tab @command{bzip2} |
8925 |
@item @samp{.tbz2} @tab @command{bzip2} |
8926 |
@item @samp{.tbz} @tab @command{bzip2} |
8927 |
@item @samp{.lz} @tab @command{lzip} |
8928 |
@item @samp{.lzma} @tab @command{lzma} |
8929 |
@item @samp{.tlz} @tab @command{lzma} |
8930 |
@item @samp{.lzo} @tab @command{lzop} |
8931 |
@item @samp{.xz} @tab @command{xz} |
8932 |
@end multitable |
8933 |
|
8934 |
@opindex use-compress-program |
8935 |
@item --use-compress-program=@var{prog} |
8936 |
@itemx -I=@var{prog} |
8937 |
Use external compression program @var{prog}. Use this option if you |
8938 |
are not happy with the compression program associated with the suffix |
8939 |
at compile time or if you have a compression program that @GNUTAR{} |
8940 |
does not support. There are two requirements to which @var{prog} |
8941 |
should comply: |
8942 |
|
8943 |
First, when called without options, it should read data from standard |
8944 |
input, compress it and output it on standard output. |
8945 |
|
8946 |
Secondly, if called with @option{-d} argument, it should do exactly |
8947 |
the opposite, i.e., read the compressed data from the standard input |
8948 |
and produce uncompressed data on the standard output. |
8949 |
@end table |
8950 |
|
8951 |
@cindex gpg, using with tar |
8952 |
@cindex gnupg, using with tar |
8953 |
@cindex Using encrypted archives |
8954 |
The @option{--use-compress-program} option, in particular, lets you |
8955 |
implement your own filters, not necessarily dealing with |
8956 |
compression/decompression. For example, suppose you wish to implement |
8957 |
PGP encryption on top of compression, using @command{gpg} (@pxref{Top, |
8958 |
gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard |
8959 |
Manual}). The following script does that: |
8960 |
|
8961 |
@smallexample |
8962 |
@group |
8963 |
#! /bin/sh |
8964 |
case $1 in |
8965 |
-d) gpg --decrypt - | gzip -d -c;; |
8966 |
'') gzip -c | gpg -s;; |
8967 |
*) echo "Unknown option $1">&2; exit 1;; |
8968 |
esac |
8969 |
@end group |
8970 |
@end smallexample |
8971 |
|
8972 |
Suppose you name it @file{gpgz} and save it somewhere in your |
8973 |
@env{PATH}. Then the following command will create a compressed |
8974 |
archive signed with your private key: |
8975 |
|
8976 |
@smallexample |
8977 |
$ @kbd{tar -cf foo.tar.gpgz -Igpgz .} |
8978 |
@end smallexample |
8979 |
|
8980 |
@noindent |
8981 |
Likewise, the command below will list its contents: |
8982 |
|
8983 |
@smallexample |
8984 |
$ @kbd{tar -tf foo.tar.gpgz -Igpgz .} |
8985 |
@end smallexample |
8986 |
|
8987 |
@ignore |
8988 |
The above is based on the following discussion: |
8989 |
|
8990 |
I have one question, or maybe it's a suggestion if there isn't a way |
8991 |
to do it now. I would like to use @option{--gzip}, but I'd also like |
8992 |
the output to be fed through a program like @acronym{GNU} |
8993 |
@command{ecc} (actually, right now that's @samp{exactly} what I'd like |
8994 |
to use :-)), basically adding ECC protection on top of compression. |
8995 |
It seems as if this should be quite easy to do, but I can't work out |
8996 |
exactly how to go about it. Of course, I can pipe the standard output |
8997 |
of @command{tar} through @command{ecc}, but then I lose (though I |
8998 |
haven't started using it yet, I confess) the ability to have |
8999 |
@command{tar} use @command{rmt} for it's I/O (I think). |
9000 |
|
9001 |
I think the most straightforward thing would be to let me specify a |
9002 |
general set of filters outboard of compression (preferably ordered, |
9003 |
so the order can be automatically reversed on input operations, and |
9004 |
with the options they require specifiable), but beggars shouldn't be |
9005 |
choosers and anything you decide on would be fine with me. |
9006 |
|
9007 |
By the way, I like @command{ecc} but if (as the comments say) it can't |
9008 |
deal with loss of block sync, I'm tempted to throw some time at adding |
9009 |
that capability. Supposing I were to actually do such a thing and |
9010 |
get it (apparently) working, do you accept contributed changes to |
9011 |
utilities like that? (Leigh Clayton @file{loc@@soliton.com}, May 1995). |
9012 |
|
9013 |
Isn't that exactly the role of the |
9014 |
@option{--use-compress-prog=@var{program}} option? |
9015 |
I never tried it myself, but I suspect you may want to write a |
9016 |
@var{prog} script or program able to filter stdin to stdout to |
9017 |
way you want. It should recognize the @option{-d} option, for when |
9018 |
extraction is needed rather than creation. |
9019 |
|
9020 |
It has been reported that if one writes compressed data (through the |
9021 |
@option{--gzip} or @option{--compress} options) to a DLT and tries to use |
9022 |
the DLT compression mode, the data will actually get bigger and one will |
9023 |
end up with less space on the tape. |
9024 |
@end ignore |
9025 |
|
9026 |
@menu |
9027 |
* lbzip2:: Using lbzip2 with @GNUTAR{}. |
9028 |
@end menu |
9029 |
|
9030 |
@node lbzip2 |
9031 |
@subsubsection Using lbzip2 with @GNUTAR{}. |
9032 |
@cindex lbzip2 |
9033 |
@cindex Laszlo Ersek |
9034 |
@command{Lbzip2} is a multithreaded utility for handling |
9035 |
@samp{bzip2} compression, written by Laszlo Ersek. It makes use of |
9036 |
multiple processors to speed up its operation and in general works |
9037 |
considerably faster than @command{bzip2}. For a detailed description |
9038 |
of @command{lbzip2} see @uref{http://freshmeat.net/@/projects/@/lbzip2} and |
9039 |
@uref{http://www.linuxinsight.com/@/lbzip2-parallel-bzip2-utility.html, |
9040 |
lbzip2: parallel bzip2 utility}. |
9041 |
|
9042 |
Recent versions of @command{lbzip2} are mostly command line compatible |
9043 |
with @command{bzip2}, which makes it possible to automatically invoke |
9044 |
it via the @option{--bzip2} @GNUTAR{} command line option. To do so, |
9045 |
@GNUTAR{} must be configured with the @option{--with-bzip2} command |
9046 |
line option, like this: |
9047 |
|
9048 |
@smallexample |
9049 |
$ @kbd{./configure --with-bzip2=lbzip2 [@var{other-options}]} |
9050 |
@end smallexample |
9051 |
|
9052 |
Once configured and compiled this way, @command{tar --help} will show the |
9053 |
following: |
9054 |
|
9055 |
@smallexample |
9056 |
@group |
9057 |
$ @kbd{tar --help | grep -- --bzip2} |
9058 |
-j, --bzip2 filter the archive through lbzip2 |
9059 |
@end group |
9060 |
@end smallexample |
9061 |
|
9062 |
@noindent |
9063 |
which means that running @command{tar --bzip2} will invoke @command{lbzip2}. |
9064 |
|
9065 |
@node sparse |
9066 |
@subsection Archiving Sparse Files |
9067 |
@cindex Sparse Files |
9068 |
|
9069 |
Files in the file system occasionally have @dfn{holes}. A @dfn{hole} |
9070 |
in a file is a section of the file's contents which was never written. |
9071 |
The contents of a hole reads as all zeros. On many operating systems, |
9072 |
actual disk storage is not allocated for holes, but they are counted |
9073 |
in the length of the file. If you archive such a file, @command{tar} |
9074 |
could create an archive longer than the original. To have @command{tar} |
9075 |
attempt to recognize the holes in a file, use @option{--sparse} |
9076 |
(@option{-S}). When you use this option, then, for any file using |
9077 |
less disk space than would be expected from its length, @command{tar} |
9078 |
searches the file for consecutive stretches of zeros. It then records |
9079 |
in the archive for the file where the consecutive stretches of zeros |
9080 |
are, and only archives the ``real contents'' of the file. On |
9081 |
extraction (using @option{--sparse} is not needed on extraction) any |
9082 |
such files have holes created wherever the continuous stretches of zeros |
9083 |
were found. Thus, if you use @option{--sparse}, @command{tar} archives |
9084 |
won't take more space than the original. |
9085 |
|
9086 |
@table @option |
9087 |
@opindex sparse |
9088 |
@item -S |
9089 |
@itemx --sparse |
9090 |
This option instructs @command{tar} to test each file for sparseness |
9091 |
before attempting to archive it. If the file is found to be sparse it |
9092 |
is treated specially, thus allowing to decrease the amount of space |
9093 |
used by its image in the archive. |
9094 |
|
9095 |
This option is meaningful only when creating or updating archives. It |
9096 |
has no effect on extraction. |
9097 |
@end table |
9098 |
|
9099 |
Consider using @option{--sparse} when performing file system backups, |
9100 |
to avoid archiving the expanded forms of files stored sparsely in the |
9101 |
system. |
9102 |
|
9103 |
Even if your system has no sparse files currently, some may be |
9104 |
created in the future. If you use @option{--sparse} while making file |
9105 |
system backups as a matter of course, you can be assured the archive |
9106 |
will never take more space on the media than the files take on disk |
9107 |
(otherwise, archiving a disk filled with sparse files might take |
9108 |
hundreds of tapes). @xref{Incremental Dumps}. |
9109 |
|
9110 |
However, be aware that @option{--sparse} option presents a serious |
9111 |
drawback. Namely, in order to determine if the file is sparse |
9112 |
@command{tar} has to read it before trying to archive it, so in total |
9113 |
the file is read @strong{twice}. So, always bear in mind that the |
9114 |
time needed to process all files with this option is roughly twice |
9115 |
the time needed to archive them without it. |
9116 |
@FIXME{A technical note: |
9117 |
|
9118 |
Programs like @command{dump} do not have to read the entire file; by |
9119 |
examining the file system directly, they can determine in advance |
9120 |
exactly where the holes are and thus avoid reading through them. The |
9121 |
only data it need read are the actual allocated data blocks. |
9122 |
@GNUTAR{} uses a more portable and straightforward |
9123 |
archiving approach, it would be fairly difficult that it does |
9124 |
otherwise. Elizabeth Zwicky writes to @file{comp.unix.internals}, on |
9125 |
1990-12-10: |
9126 |
|
9127 |
@quotation |
9128 |
What I did say is that you cannot tell the difference between a hole and an |
9129 |
equivalent number of nulls without reading raw blocks. @code{st_blocks} at |
9130 |
best tells you how many holes there are; it doesn't tell you @emph{where}. |
9131 |
Just as programs may, conceivably, care what @code{st_blocks} is (care |
9132 |
to name one that does?), they may also care where the holes are (I have |
9133 |
no examples of this one either, but it's equally imaginable). |
9134 |
|
9135 |
I conclude from this that good archivers are not portable. One can |
9136 |
arguably conclude that if you want a portable program, you can in good |
9137 |
conscience restore files with as many holes as possible, since you can't |
9138 |
get it right. |
9139 |
@end quotation |
9140 |
} |
9141 |
|
9142 |
@cindex sparse formats, defined |
9143 |
When using @samp{POSIX} archive format, @GNUTAR{} is able to store |
9144 |
sparse files using in three distinct ways, called @dfn{sparse |
9145 |
formats}. A sparse format is identified by its @dfn{number}, |
9146 |
consisting, as usual of two decimal numbers, delimited by a dot. By |
9147 |
default, format @samp{1.0} is used. If, for some reason, you wish to |
9148 |
use an earlier format, you can select it using |
9149 |
@option{--sparse-version} option. |
9150 |
|
9151 |
@table @option |
9152 |
@opindex sparse-version |
9153 |
@item --sparse-version=@var{version} |
9154 |
|
9155 |
Select the format to store sparse files in. Valid @var{version} values |
9156 |
are: @samp{0.0}, @samp{0.1} and @samp{1.0}. @xref{Sparse Formats}, |
9157 |
for a detailed description of each format. |
9158 |
@end table |
9159 |
|
9160 |
Using @option{--sparse-format} option implies @option{--sparse}. |
9161 |
|
9162 |
@node Attributes |
9163 |
@section Handling File Attributes |
9164 |
@cindex atrributes, files |
9165 |
@cindex file attributes |
9166 |
|
9167 |
When @command{tar} reads files, it updates their access times. To |
9168 |
avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either |
9169 |
reset the access time retroactively or avoid changing it in the first |
9170 |
place. |
9171 |
|
9172 |
@table @option |
9173 |
@opindex atime-preserve |
9174 |
@item --atime-preserve |
9175 |
@itemx --atime-preserve=replace |
9176 |
@itemx --atime-preserve=system |
9177 |
Preserve the access times of files that are read. This works only for |
9178 |
files that you own, unless you have superuser privileges. |
9179 |
|
9180 |
@option{--atime-preserve=replace} works on most systems, but it also |
9181 |
restores the data modification time and updates the status change |
9182 |
time. Hence it doesn't interact with incremental dumps nicely |
9183 |
(@pxref{Incremental Dumps}), and it can set access or data modification times |
9184 |
incorrectly if other programs access the file while @command{tar} is |
9185 |
running. |
9186 |
|
9187 |
@option{--atime-preserve=system} avoids changing the access time in |
9188 |
the first place, if the operating system supports this. |
9189 |
Unfortunately, this may or may not work on any given operating system |
9190 |
or file system. If @command{tar} knows for sure it won't work, it |
9191 |
complains right away. |
9192 |
|
9193 |
Currently @option{--atime-preserve} with no operand defaults to |
9194 |
@option{--atime-preserve=replace}, but this is intended to change to |
9195 |
@option{--atime-preserve=system} when the latter is better-supported. |
9196 |
|
9197 |
@opindex touch |
9198 |
@item -m |
9199 |
@itemx --touch |
9200 |
Do not extract data modification time. |
9201 |
|
9202 |
When this option is used, @command{tar} leaves the data modification times |
9203 |
of the files it extracts as the times when the files were extracted, |
9204 |
instead of setting it to the times recorded in the archive. |
9205 |
|
9206 |
This option is meaningless with @option{--list} (@option{-t}). |
9207 |
|
9208 |
@opindex same-owner |
9209 |
@item --same-owner |
9210 |
Create extracted files with the same ownership they have in the |
9211 |
archive. |
9212 |
|
9213 |
This is the default behavior for the superuser, |
9214 |
so this option is meaningful only for non-root users, when @command{tar} |
9215 |
is executed on those systems able to give files away. This is |
9216 |
considered as a security flaw by many people, at least because it |
9217 |
makes quite difficult to correctly account users for the disk space |
9218 |
they occupy. Also, the @code{suid} or @code{sgid} attributes of |
9219 |
files are easily and silently lost when files are given away. |
9220 |
|
9221 |
When writing an archive, @command{tar} writes the user @acronym{ID} and user name |
9222 |
separately. If it can't find a user name (because the user @acronym{ID} is not |
9223 |
in @file{/etc/passwd}), then it does not write one. When restoring, |
9224 |
it tries to look the name (if one was written) up in |
9225 |
@file{/etc/passwd}. If it fails, then it uses the user @acronym{ID} stored in |
9226 |
the archive instead. |
9227 |
|
9228 |
@opindex no-same-owner |
9229 |
@item --no-same-owner |
9230 |
@itemx -o |
9231 |
Do not attempt to restore ownership when extracting. This is the |
9232 |
default behavior for ordinary users, so this option has an effect |
9233 |
only for the superuser. |
9234 |
|
9235 |
@opindex numeric-owner |
9236 |
@item --numeric-owner |
9237 |
The @option{--numeric-owner} option allows (ANSI) archives to be written |
9238 |
without user/group name information or such information to be ignored |
9239 |
when extracting. It effectively disables the generation and/or use |
9240 |
of user/group name information. This option forces extraction using |
9241 |
the numeric ids from the archive, ignoring the names. |
9242 |
|
9243 |
This is useful in certain circumstances, when restoring a backup from |
9244 |
an emergency floppy with different passwd/group files for example. |
9245 |
It is otherwise impossible to extract files with the right ownerships |
9246 |
if the password file in use during the extraction does not match the |
9247 |
one belonging to the file system(s) being extracted. This occurs, |
9248 |
for example, if you are restoring your files after a major crash and |
9249 |
had booted from an emergency floppy with no password file or put your |
9250 |
disk into another machine to do the restore. |
9251 |
|
9252 |
The numeric ids are @emph{always} saved into @command{tar} archives. |
9253 |
The identifying names are added at create time when provided by the |
9254 |
system, unless @option{--format=oldgnu} is used. Numeric ids could be |
9255 |
used when moving archives between a collection of machines using |
9256 |
a centralized management for attribution of numeric ids to users |
9257 |
and groups. This is often made through using the NIS capabilities. |
9258 |
|
9259 |
When making a @command{tar} file for distribution to other sites, it |
9260 |
is sometimes cleaner to use a single owner for all files in the |
9261 |
distribution, and nicer to specify the write permission bits of the |
9262 |
files as stored in the archive independently of their actual value on |
9263 |
the file system. The way to prepare a clean distribution is usually |
9264 |
to have some Makefile rule creating a directory, copying all needed |
9265 |
files in that directory, then setting ownership and permissions as |
9266 |
wanted (there are a lot of possible schemes), and only then making a |
9267 |
@command{tar} archive out of this directory, before cleaning |
9268 |
everything out. Of course, we could add a lot of options to |
9269 |
@GNUTAR{} for fine tuning permissions and ownership. |
9270 |
This is not the good way, I think. @GNUTAR{} is |
9271 |
already crowded with options and moreover, the approach just explained |
9272 |
gives you a great deal of control already. |
9273 |
|
9274 |
@xopindex{same-permissions, short description} |
9275 |
@xopindex{preserve-permissions, short description} |
9276 |
@item -p |
9277 |
@itemx --same-permissions |
9278 |
@itemx --preserve-permissions |
9279 |
Extract all protection information. |
9280 |
|
9281 |
This option causes @command{tar} to set the modes (access permissions) of |
9282 |
extracted files exactly as recorded in the archive. If this option |
9283 |
is not used, the current @code{umask} setting limits the permissions |
9284 |
on extracted files. This option is by default enabled when |
9285 |
@command{tar} is executed by a superuser. |
9286 |
|
9287 |
|
9288 |
This option is meaningless with @option{--list} (@option{-t}). |
9289 |
|
9290 |
@opindex preserve |
9291 |
@item --preserve |
9292 |
Same as both @option{--same-permissions} and @option{--same-order}. |
9293 |
|
9294 |
This option is deprecated, and will be removed in @GNUTAR{} version 1.23. |
9295 |
|
9296 |
@end table |
9297 |
|
9298 |
@node Portability |
9299 |
@section Making @command{tar} Archives More Portable |
9300 |
|
9301 |
Creating a @command{tar} archive on a particular system that is meant to be |
9302 |
useful later on many other machines and with other versions of @command{tar} |
9303 |
is more challenging than you might think. @command{tar} archive formats |
9304 |
have been evolving since the first versions of Unix. Many such formats |
9305 |
are around, and are not always compatible with each other. This section |
9306 |
discusses a few problems, and gives some advice about making @command{tar} |
9307 |
archives more portable. |
9308 |
|
9309 |
One golden rule is simplicity. For example, limit your @command{tar} |
9310 |
archives to contain only regular files and directories, avoiding |
9311 |
other kind of special files. Do not attempt to save sparse files or |
9312 |
contiguous files as such. Let's discuss a few more problems, in turn. |
9313 |
|
9314 |
@FIXME{Discuss GNU extensions (incremental backups, multi-volume |
9315 |
archives and archive labels) in GNU and PAX formats.} |
9316 |
|
9317 |
@menu |
9318 |
* Portable Names:: Portable Names |
9319 |
* dereference:: Symbolic Links |
9320 |
* hard links:: Hard Links |
9321 |
* old:: Old V7 Archives |
9322 |
* ustar:: Ustar Archives |
9323 |
* gnu:: GNU and old GNU format archives. |
9324 |
* posix:: @acronym{POSIX} archives |
9325 |
* Checksumming:: Checksumming Problems |
9326 |
* Large or Negative Values:: Large files, negative time stamps, etc. |
9327 |
* Other Tars:: How to Extract GNU-Specific Data Using |
9328 |
Other @command{tar} Implementations |
9329 |
@end menu |
9330 |
|
9331 |
@node Portable Names |
9332 |
@subsection Portable Names |
9333 |
|
9334 |
Use portable file and member names. A name is portable if it contains |
9335 |
only @acronym{ASCII} letters and digits, @samp{/}, @samp{.}, @samp{_}, and |
9336 |
@samp{-}; it cannot be empty, start with @samp{-} or @samp{//}, or |
9337 |
contain @samp{/-}. Avoid deep directory nesting. For portability to |
9338 |
old Unix hosts, limit your file name components to 14 characters or |
9339 |
less. |
9340 |
|
9341 |
If you intend to have your @command{tar} archives to be read under |
9342 |
MSDOS, you should not rely on case distinction for file names, and you |
9343 |
might use the @acronym{GNU} @command{doschk} program for helping you |
9344 |
further diagnosing illegal MSDOS names, which are even more limited |
9345 |
than System V's. |
9346 |
|
9347 |
@node dereference |
9348 |
@subsection Symbolic Links |
9349 |
@cindex File names, using symbolic links |
9350 |
@cindex Symbolic link as file name |
9351 |
|
9352 |
@opindex dereference |
9353 |
Normally, when @command{tar} archives a symbolic link, it writes a |
9354 |
block to the archive naming the target of the link. In that way, the |
9355 |
@command{tar} archive is a faithful record of the file system contents. |
9356 |
When @option{--dereference} (@option{-h}) is used with |
9357 |
@option{--create} (@option{-c}), @command{tar} archives the files |
9358 |
symbolic links point to, instead of |
9359 |
the links themselves. |
9360 |
|
9361 |
When creating portable archives, use @option{--dereference} |
9362 |
(@option{-h}): some systems do not support |
9363 |
symbolic links, and moreover, your distribution might be unusable if |
9364 |
it contains unresolved symbolic links. |
9365 |
|
9366 |
When reading from an archive, the @option{--dereference} (@option{-h}) |
9367 |
option causes @command{tar} to follow an already-existing symbolic |
9368 |
link when @command{tar} writes or reads a file named in the archive. |
9369 |
Ordinarily, @command{tar} does not follow such a link, though it may |
9370 |
remove the link before writing a new file. @xref{Dealing with Old |
9371 |
Files}. |
9372 |
|
9373 |
The @option{--dereference} option is unsafe if an untrusted user can |
9374 |
modify directories while @command{tar} is running. @xref{Security}. |
9375 |
|
9376 |
@node hard links |
9377 |
@subsection Hard Links |
9378 |
@cindex File names, using hard links |
9379 |
@cindex hard links, dereferencing |
9380 |
@cindex dereferencing hard links |
9381 |
|
9382 |
Normally, when @command{tar} archives a hard link, it writes a |
9383 |
block to the archive naming the target of the link (a @samp{1} type |
9384 |
block). In that way, the actual file contents is stored in file only |
9385 |
once. For example, consider the following two files: |
9386 |
|
9387 |
@smallexample |
9388 |
@group |
9389 |
$ ls -l |
9390 |
-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one |
9391 |
-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden |
9392 |
@end group |
9393 |
@end smallexample |
9394 |
|
9395 |
Here, @file{jeden} is a link to @file{one}. When archiving this |
9396 |
directory with a verbose level 2, you will get an output similar to |
9397 |
the following: |
9398 |
|
9399 |
@smallexample |
9400 |
$ tar cfvv ../archive.tar . |
9401 |
drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./ |
9402 |
-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden |
9403 |
hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden |
9404 |
@end smallexample |
9405 |
|
9406 |
The last line shows that, instead of storing two copies of the file, |
9407 |
@command{tar} stored it only once, under the name @file{jeden}, and |
9408 |
stored file @file{one} as a hard link to this file. |
9409 |
|
9410 |
It may be important to know that all hard links to the given file are |
9411 |
stored in the archive. For example, this may be necessary for exact |
9412 |
reproduction of the file system. The following option does that: |
9413 |
|
9414 |
@table @option |
9415 |
@xopindex{check-links, described} |
9416 |
@item --check-links |
9417 |
@itemx -l |
9418 |
Check the number of links dumped for each processed file. If this |
9419 |
number does not match the total number of hard links for the file, print |
9420 |
a warning message. |
9421 |
@end table |
9422 |
|
9423 |
For example, trying to archive only file @file{jeden} with this option |
9424 |
produces the following diagnostics: |
9425 |
|
9426 |
@smallexample |
9427 |
$ tar -c -f ../archive.tar -l jeden |
9428 |
tar: Missing links to `jeden'. |
9429 |
@end smallexample |
9430 |
|
9431 |
Although creating special records for hard links helps keep a faithful |
9432 |
record of the file system contents and makes archives more compact, it |
9433 |
may present some difficulties when extracting individual members from |
9434 |
the archive. For example, trying to extract file @file{one} from the |
9435 |
archive created in previous examples produces, in the absense of file |
9436 |
@file{jeden}: |
9437 |
|
9438 |
@smallexample |
9439 |
$ tar xf archive.tar ./one |
9440 |
tar: ./one: Cannot hard link to `./jeden': No such file or directory |
9441 |
tar: Error exit delayed from previous errors |
9442 |
@end smallexample |
9443 |
|
9444 |
The reason for this behavior is that @command{tar} cannot seek back in |
9445 |
the archive to the previous member (in this case, @file{one}), to |
9446 |
extract it@footnote{There are plans to fix this in future releases.}. |
9447 |
If you wish to avoid such problems at the cost of a bigger archive, |
9448 |
use the following option: |
9449 |
|
9450 |
@table @option |
9451 |
@xopindex{hard-dereference, described} |
9452 |
@item --hard-dereference |
9453 |
Dereference hard links and store the files they refer to. |
9454 |
@end table |
9455 |
|
9456 |
For example, trying this option on our two sample files, we get two |
9457 |
copies in the archive, each of which can then be extracted |
9458 |
independently of the other: |
9459 |
|
9460 |
@smallexample |
9461 |
@group |
9462 |
$ tar -c -vv -f ../archive.tar --hard-dereference . |
9463 |
drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./ |
9464 |
-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden |
9465 |
-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./one |
9466 |
@end group |
9467 |
@end smallexample |
9468 |
|
9469 |
@node old |
9470 |
@subsection Old V7 Archives |
9471 |
@cindex Format, old style |
9472 |
@cindex Old style format |
9473 |
@cindex Old style archives |
9474 |
@cindex v7 archive format |
9475 |
|
9476 |
Certain old versions of @command{tar} cannot handle additional |
9477 |
information recorded by newer @command{tar} programs. To create an |
9478 |
archive in V7 format (not ANSI), which can be read by these old |
9479 |
versions, specify the @option{--format=v7} option in |
9480 |
conjunction with the @option{--create} (@option{-c}) (@command{tar} also |
9481 |
accepts @option{--portability} or @option{--old-archive} for this |
9482 |
option). When you specify it, |
9483 |
@command{tar} leaves out information about directories, pipes, fifos, |
9484 |
contiguous files, and device files, and specifies file ownership by |
9485 |
group and user IDs instead of group and user names. |
9486 |
|
9487 |
When updating an archive, do not use @option{--format=v7} |
9488 |
unless the archive was created using this option. |
9489 |
|
9490 |
In most cases, a @emph{new} format archive can be read by an @emph{old} |
9491 |
@command{tar} program without serious trouble, so this option should |
9492 |
seldom be needed. On the other hand, most modern @command{tar}s are |
9493 |
able to read old format archives, so it might be safer for you to |
9494 |
always use @option{--format=v7} for your distributions. Notice, |
9495 |
however, that @samp{ustar} format is a better alternative, as it is |
9496 |
free from many of @samp{v7}'s drawbacks. |
9497 |
|
9498 |
@node ustar |
9499 |
@subsection Ustar Archive Format |
9500 |
|
9501 |
@cindex ustar archive format |
9502 |
Archive format defined by @acronym{POSIX}.1-1988 specification is called |
9503 |
@code{ustar}. Although it is more flexible than the V7 format, it |
9504 |
still has many restrictions (@pxref{Formats,ustar}, for the detailed |
9505 |
description of @code{ustar} format). Along with V7 format, |
9506 |
@code{ustar} format is a good choice for archives intended to be read |
9507 |
with other implementations of @command{tar}. |
9508 |
|
9509 |
To create archive in @code{ustar} format, use @option{--format=ustar} |
9510 |
option in conjunction with the @option{--create} (@option{-c}). |
9511 |
|
9512 |
@node gnu |
9513 |
@subsection @acronym{GNU} and old @GNUTAR{} format |
9514 |
|
9515 |
@cindex GNU archive format |
9516 |
@cindex Old GNU archive format |
9517 |
@GNUTAR{} was based on an early draft of the |
9518 |
@acronym{POSIX} 1003.1 @code{ustar} standard. @acronym{GNU} extensions to |
9519 |
@command{tar}, such as the support for file names longer than 100 |
9520 |
characters, use portions of the @command{tar} header record which were |
9521 |
specified in that @acronym{POSIX} draft as unused. Subsequent changes in |
9522 |
@acronym{POSIX} have allocated the same parts of the header record for |
9523 |
other purposes. As a result, @GNUTAR{} format is |
9524 |
incompatible with the current @acronym{POSIX} specification, and with |
9525 |
@command{tar} programs that follow it. |
9526 |
|
9527 |
In the majority of cases, @command{tar} will be configured to create |
9528 |
this format by default. This will change in future releases, since |
9529 |
we plan to make @samp{POSIX} format the default. |
9530 |
|
9531 |
To force creation a @GNUTAR{} archive, use option |
9532 |
@option{--format=gnu}. |
9533 |
|
9534 |
@node posix |
9535 |
@subsection @GNUTAR{} and @acronym{POSIX} @command{tar} |
9536 |
|
9537 |
@cindex POSIX archive format |
9538 |
@cindex PAX archive format |
9539 |
Starting from version 1.14 @GNUTAR{} features full support for |
9540 |
@acronym{POSIX.1-2001} archives. |
9541 |
|
9542 |
A @acronym{POSIX} conformant archive will be created if @command{tar} |
9543 |
was given @option{--format=posix} (@option{--format=pax}) option. No |
9544 |
special option is required to read and extract from a @acronym{POSIX} |
9545 |
archive. |
9546 |
|
9547 |
@menu |
9548 |
* PAX keywords:: Controlling Extended Header Keywords. |
9549 |
@end menu |
9550 |
|
9551 |
@node PAX keywords |
9552 |
@subsubsection Controlling Extended Header Keywords |
9553 |
|
9554 |
@table @option |
9555 |
@opindex pax-option |
9556 |
@item --pax-option=@var{keyword-list} |
9557 |
Handle keywords in @acronym{PAX} extended headers. This option is |
9558 |
equivalent to @option{-o} option of the @command{pax} utility. |
9559 |
@end table |
9560 |
|
9561 |
@var{Keyword-list} is a comma-separated |
9562 |
list of keyword options, each keyword option taking one of |
9563 |
the following forms: |
9564 |
|
9565 |
@table @code |
9566 |
@item delete=@var{pattern} |
9567 |
When used with one of archive-creation commands, |
9568 |
this option instructs @command{tar} to omit from extended header records |
9569 |
that it produces any keywords matching the string @var{pattern}. |
9570 |
|
9571 |
When used in extract or list mode, this option instructs tar |
9572 |
to ignore any keywords matching the given @var{pattern} in the extended |
9573 |
header records. In both cases, matching is performed using the pattern |
9574 |
matching notation described in @acronym{POSIX 1003.2}, 3.13 |
9575 |
(@pxref{wildcards}). For example: |
9576 |
|
9577 |
@smallexample |
9578 |
--pax-option delete=security.* |
9579 |
@end smallexample |
9580 |
|
9581 |
would suppress security-related information. |
9582 |
|
9583 |
@item exthdr.name=@var{string} |
9584 |
|
9585 |
This keyword allows user control over the name that is written into the |
9586 |
ustar header blocks for the extended headers. The name is obtained |
9587 |
from @var{string} after making the following substitutions: |
9588 |
|
9589 |
@multitable @columnfractions .25 .55 |
9590 |
@headitem Meta-character @tab Replaced By |
9591 |
@item %d @tab The directory name of the file, equivalent to the |
9592 |
result of the @command{dirname} utility on the translated file name. |
9593 |
@item %f @tab The name of the file with the directory information |
9594 |
stripped, equivalent to the result of the @command{basename} utility |
9595 |
on the translated file name. |
9596 |
@item %p @tab The process @acronym{ID} of the @command{tar} process. |
9597 |
@item %% @tab A @samp{%} character. |
9598 |
@end multitable |
9599 |
|
9600 |
Any other @samp{%} characters in @var{string} produce undefined |
9601 |
results. |
9602 |
|
9603 |
If no option @samp{exthdr.name=string} is specified, @command{tar} |
9604 |
will use the following default value: |
9605 |
|
9606 |
@smallexample |
9607 |
%d/PaxHeaders.%p/%f |
9608 |
@end smallexample |
9609 |
|
9610 |
@item exthdr.mtime=@var{value} |
9611 |
|
9612 |
This keyword defines the value of the @samp{mtime} field that |
9613 |
is written into the ustar header blocks for the extended headers. |
9614 |
By default, the @samp{mtime} field is set to the modification time |
9615 |
of the archive member described by that extended headers. |
9616 |
|
9617 |
@item globexthdr.name=@var{string} |
9618 |
This keyword allows user control over the name that is written into |
9619 |
the ustar header blocks for global extended header records. The name |
9620 |
is obtained from the contents of @var{string}, after making |
9621 |
the following substitutions: |
9622 |
|
9623 |
@multitable @columnfractions .25 .55 |
9624 |
@headitem Meta-character @tab Replaced By |
9625 |
@item %n @tab An integer that represents the |
9626 |
sequence number of the global extended header record in the archive, |
9627 |
starting at 1. |
9628 |
@item %p @tab The process @acronym{ID} of the @command{tar} process. |
9629 |
@item %% @tab A @samp{%} character. |
9630 |
@end multitable |
9631 |
|
9632 |
Any other @samp{%} characters in @var{string} produce undefined results. |
9633 |
|
9634 |
If no option @samp{globexthdr.name=string} is specified, @command{tar} |
9635 |
will use the following default value: |
9636 |
|
9637 |
@smallexample |
9638 |
$TMPDIR/GlobalHead.%p.%n |
9639 |
@end smallexample |
9640 |
|
9641 |
@noindent |
9642 |
where @samp{$TMPDIR} represents the value of the @var{TMPDIR} |
9643 |
environment variable. If @var{TMPDIR} is not set, @command{tar} |
9644 |
uses @samp{/tmp}. |
9645 |
|
9646 |
@item globexthdr.mtime=@var{value} |
9647 |
|
9648 |
This keyword defines the value of the @samp{mtime} field that |
9649 |
is written into the ustar header blocks for the global extended headers. |
9650 |
By default, the @samp{mtime} field is set to the time when |
9651 |
@command{tar} was invoked. |
9652 |
|
9653 |
@item @var{keyword}=@var{value} |
9654 |
When used with one of archive-creation commands, these keyword/value pairs |
9655 |
will be included at the beginning of the archive in a global extended |
9656 |
header record. When used with one of archive-reading commands, |
9657 |
@command{tar} will behave as if it has encountered these keyword/value |
9658 |
pairs at the beginning of the archive in a global extended header |
9659 |
record. |
9660 |
|
9661 |
@item @var{keyword}:=@var{value} |
9662 |
When used with one of archive-creation commands, these keyword/value pairs |
9663 |
will be included as records at the beginning of an extended header for |
9664 |
each file. This is effectively equivalent to @var{keyword}=@var{value} |
9665 |
form except that it creates no global extended header records. |
9666 |
|
9667 |
When used with one of archive-reading commands, @command{tar} will |
9668 |
behave as if these keyword/value pairs were included as records at the |
9669 |
end of each extended header; thus, they will override any global or |
9670 |
file-specific extended header record keywords of the same names. |
9671 |
For example, in the command: |
9672 |
|
9673 |
@smallexample |
9674 |
tar --format=posix --create \ |
9675 |
--file archive --pax-option gname:=user . |
9676 |
@end smallexample |
9677 |
|
9678 |
the group name will be forced to a new value for all files |
9679 |
stored in the archive. |
9680 |
@end table |
9681 |
|
9682 |
In any of the forms described above, the @var{value} may be |
9683 |
a string enclosed in curly braces. In that case, the string |
9684 |
between the braces is understood either as a textual time |
9685 |
representation, as described in @ref{Date input formats}, or a name of |
9686 |
the existing file, starting with @samp{/} or @samp{.}. In the latter |
9687 |
case, the modification time of that file is used. |
9688 |
|
9689 |
For example, to set all modification times to the current date, you |
9690 |
use the following option: |
9691 |
|
9692 |
@smallexample |
9693 |
--pax-option='mtime:=@{now@}' |
9694 |
@end smallexample |
9695 |
|
9696 |
Note quoting of the option's argument. |
9697 |
|
9698 |
@cindex archives, binary equivalent |
9699 |
@cindex binary equivalent archives, creating |
9700 |
As another example, here is the option that ensures that any two |
9701 |
archives created using it, will be binary equivalent if they have the |
9702 |
same contents: |
9703 |
|
9704 |
@smallexample |
9705 |
--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0 |
9706 |
@end smallexample |
9707 |
|
9708 |
@node Checksumming |
9709 |
@subsection Checksumming Problems |
9710 |
|
9711 |
SunOS and HP-UX @command{tar} fail to accept archives created using |
9712 |
@GNUTAR{} and containing non-@acronym{ASCII} file names, that |
9713 |
is, file names having characters with the eight bit set, because they |
9714 |
use signed checksums, while @GNUTAR{} uses unsigned |
9715 |
checksums while creating archives, as per @acronym{POSIX} standards. On |
9716 |
reading, @GNUTAR{} computes both checksums and |
9717 |
accepts any. It is somewhat worrying that a lot of people may go |
9718 |
around doing backup of their files using faulty (or at least |
9719 |
non-standard) software, not learning about it until it's time to |
9720 |
restore their missing files with an incompatible file extractor, or |
9721 |
vice versa. |
9722 |
|
9723 |
@GNUTAR{} computes checksums both ways, and accept |
9724 |
any on read, so @acronym{GNU} tar can read Sun tapes even with their |
9725 |
wrong checksums. @GNUTAR{} produces the standard |
9726 |
checksum, however, raising incompatibilities with Sun. That is to |
9727 |
say, @GNUTAR{} has not been modified to |
9728 |
@emph{produce} incorrect archives to be read by buggy @command{tar}'s. |
9729 |
I've been told that more recent Sun @command{tar} now read standard |
9730 |
archives, so maybe Sun did a similar patch, after all? |
9731 |
|
9732 |
The story seems to be that when Sun first imported @command{tar} |
9733 |
sources on their system, they recompiled it without realizing that |
9734 |
the checksums were computed differently, because of a change in |
9735 |
the default signing of @code{char}'s in their compiler. So they |
9736 |
started computing checksums wrongly. When they later realized their |
9737 |
mistake, they merely decided to stay compatible with it, and with |
9738 |
themselves afterwards. Presumably, but I do not really know, HP-UX |
9739 |
has chosen that their @command{tar} archives to be compatible with Sun's. |
9740 |
The current standards do not favor Sun @command{tar} format. In any |
9741 |
case, it now falls on the shoulders of SunOS and HP-UX users to get |
9742 |
a @command{tar} able to read the good archives they receive. |
9743 |
|
9744 |
@node Large or Negative Values |
9745 |
@subsection Large or Negative Values |
9746 |
@cindex large values |
9747 |
@cindex future time stamps |
9748 |
@cindex negative time stamps |
9749 |
@UNREVISED |
9750 |
|
9751 |
The above sections suggest to use @samp{oldest possible} archive |
9752 |
format if in doubt. However, sometimes it is not possible. If you |
9753 |
attempt to archive a file whose metadata cannot be represented using |
9754 |
required format, @GNUTAR{} will print error message and ignore such a |
9755 |
file. You will than have to switch to a format that is able to |
9756 |
handle such values. The format summary table (@pxref{Formats}) will |
9757 |
help you to do so. |
9758 |
|
9759 |
In particular, when trying to archive files larger than 8GB or with |
9760 |
timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16 |
9761 |
12:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and |
9762 |
@acronym{POSIX} archive formats. When considering which format to |
9763 |
choose, bear in mind that the @acronym{GNU} format uses |
9764 |
two's-complement base-256 notation to store values that do not fit |
9765 |
into standard @acronym{ustar} range. Such archives can generally be |
9766 |
read only by a @GNUTAR{} implementation. Moreover, they sometimes |
9767 |
cannot be correctly restored on another hosts even by @GNUTAR{}. For |
9768 |
example, using two's complement representation for negative time |
9769 |
stamps that assumes a signed 32-bit @code{time_t} generates archives |
9770 |
that are not portable to hosts with differing @code{time_t} |
9771 |
representations. |
9772 |
|
9773 |
On the other hand, @acronym{POSIX} archives, generally speaking, can |
9774 |
be extracted by any tar implementation that understands older |
9775 |
@acronym{ustar} format. The only exception are files larger than 8GB. |
9776 |
|
9777 |
@FIXME{Describe how @acronym{POSIX} archives are extracted by non |
9778 |
POSIX-aware tars.} |
9779 |
|
9780 |
@node Other Tars |
9781 |
@subsection How to Extract GNU-Specific Data Using Other @command{tar} Implementations |
9782 |
|
9783 |
In previous sections you became acquainted with various quirks |
9784 |
necessary to make your archives portable. Sometimes you may need to |
9785 |
extract archives containing GNU-specific members using some |
9786 |
third-party @command{tar} implementation or an older version of |
9787 |
@GNUTAR{}. Of course your best bet is to have @GNUTAR{} installed, |
9788 |
but if it is for some reason impossible, this section will explain |
9789 |
how to cope without it. |
9790 |
|
9791 |
When we speak about @dfn{GNU-specific} members we mean two classes of |
9792 |
them: members split between the volumes of a multi-volume archive and |
9793 |
sparse members. You will be able to always recover such members if |
9794 |
the archive is in PAX format. In addition split members can be |
9795 |
recovered from archives in old GNU format. The following subsections |
9796 |
describe the required procedures in detail. |
9797 |
|
9798 |
@menu |
9799 |
* Split Recovery:: Members Split Between Volumes |
9800 |
* Sparse Recovery:: Sparse Members |
9801 |
@end menu |
9802 |
|
9803 |
@node Split Recovery |
9804 |
@subsubsection Extracting Members Split Between Volumes |
9805 |
|
9806 |
@cindex Mutli-volume archives, extracting using non-GNU tars |
9807 |
If a member is split between several volumes of an old GNU format archive |
9808 |
most third party @command{tar} implementation will fail to extract |
9809 |
it. To extract it, use @command{tarcat} program (@pxref{Tarcat}). |
9810 |
This program is available from |
9811 |
@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html, @GNUTAR{} |
9812 |
home page}. It concatenates several archive volumes into a single |
9813 |
valid archive. For example, if you have three volumes named from |
9814 |
@file{vol-1.tar} to @file{vol-3.tar}, you can do the following to |
9815 |
extract them using a third-party @command{tar}: |
9816 |
|
9817 |
@smallexample |
9818 |
$ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -} |
9819 |
@end smallexample |
9820 |
|
9821 |
@cindex Mutli-volume archives in PAX format, extracting using non-GNU tars |
9822 |
You could use this approach for most (although not all) PAX |
9823 |
format archives as well. However, extracting split members from a PAX |
9824 |
archive is a much easier task, because PAX volumes are constructed in |
9825 |
such a way that each part of a split member is extracted to a |
9826 |
different file by @command{tar} implementations that are not aware of |
9827 |
GNU extensions. More specifically, the very first part retains its |
9828 |
original name, and all subsequent parts are named using the pattern: |
9829 |
|
9830 |
@smallexample |
9831 |
%d/GNUFileParts.%p/%f.%n |
9832 |
@end smallexample |
9833 |
|
9834 |
@noindent |
9835 |
where symbols preceeded by @samp{%} are @dfn{macro characters} that |
9836 |
have the following meaning: |
9837 |
|
9838 |
@multitable @columnfractions .25 .55 |
9839 |
@headitem Meta-character @tab Replaced By |
9840 |
@item %d @tab The directory name of the file, equivalent to the |
9841 |
result of the @command{dirname} utility on its full name. |
9842 |
@item %f @tab The file name of the file, equivalent to the result |
9843 |
of the @command{basename} utility on its full name. |
9844 |
@item %p @tab The process @acronym{ID} of the @command{tar} process that |
9845 |
created the archive. |
9846 |
@item %n @tab Ordinal number of this particular part. |
9847 |
@end multitable |
9848 |
|
9849 |
For example, if the file @file{var/longfile} was split during archive |
9850 |
creation between three volumes, and the creator @command{tar} process |
9851 |
had process @acronym{ID} @samp{27962}, then the member names will be: |
9852 |
|
9853 |
@smallexample |
9854 |
var/longfile |
9855 |
var/GNUFileParts.27962/longfile.1 |
9856 |
var/GNUFileParts.27962/longfile.2 |
9857 |
@end smallexample |
9858 |
|
9859 |
When you extract your archive using a third-party @command{tar}, these |
9860 |
files will be created on your disk, and the only thing you will need |
9861 |
to do to restore your file in its original form is concatenate them in |
9862 |
the proper order, for example: |
9863 |
|
9864 |
@smallexample |
9865 |
@group |
9866 |
$ @kbd{cd var} |
9867 |
$ @kbd{cat GNUFileParts.27962/longfile.1 \ |
9868 |
GNUFileParts.27962/longfile.2 >> longfile} |
9869 |
$ rm -f GNUFileParts.27962 |
9870 |
@end group |
9871 |
@end smallexample |
9872 |
|
9873 |
Notice, that if the @command{tar} implementation you use supports PAX |
9874 |
format archives, it will probably emit warnings about unknown keywords |
9875 |
during extraction. They will look like this: |
9876 |
|
9877 |
@smallexample |
9878 |
@group |
9879 |
Tar file too small |
9880 |
Unknown extended header keyword 'GNU.volume.filename' ignored. |
9881 |
Unknown extended header keyword 'GNU.volume.size' ignored. |
9882 |
Unknown extended header keyword 'GNU.volume.offset' ignored. |
9883 |
@end group |
9884 |
@end smallexample |
9885 |
|
9886 |
@noindent |
9887 |
You can safely ignore these warnings. |
9888 |
|
9889 |
If your @command{tar} implementation is not PAX-aware, you will get |
9890 |
more warnings and more files generated on your disk, e.g.: |
9891 |
|
9892 |
@smallexample |
9893 |
@group |
9894 |
$ @kbd{tar xf vol-1.tar} |
9895 |
var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as |
9896 |
normal file |
9897 |
Unexpected EOF in archive |
9898 |
$ @kbd{tar xf vol-2.tar} |
9899 |
tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file |
9900 |
GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type |
9901 |
'x', extracted as normal file |
9902 |
@end group |
9903 |
@end smallexample |
9904 |
|
9905 |
Ignore these warnings. The @file{PaxHeaders.*} directories created |
9906 |
will contain files with @dfn{extended header keywords} describing the |
9907 |
extracted files. You can delete them, unless they describe sparse |
9908 |
members. Read further to learn more about them. |
9909 |
|
9910 |
@node Sparse Recovery |
9911 |
@subsubsection Extracting Sparse Members |
9912 |
|
9913 |
@cindex sparse files, extracting with non-GNU tars |
9914 |
Any @command{tar} implementation will be able to extract sparse members from a |
9915 |
PAX archive. However, the extracted files will be @dfn{condensed}, |
9916 |
i.e., any zero blocks will be removed from them. When we restore such |
9917 |
a condensed file to its original form, by adding zero blocks (or |
9918 |
@dfn{holes}) back to their original locations, we call this process |
9919 |
@dfn{expanding} a compressed sparse file. |
9920 |
|
9921 |
@pindex xsparse |
9922 |
To expand a file, you will need a simple auxiliary program called |
9923 |
@command{xsparse}. It is available in source form from |
9924 |
@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html, @GNUTAR{} |
9925 |
home page}. |
9926 |
|
9927 |
@cindex sparse files v.1.0, extracting with non-GNU tars |
9928 |
Let's begin with archive members in @dfn{sparse format |
9929 |
version 1.0}@footnote{@xref{PAX 1}.}, which are the easiest to expand. |
9930 |
The condensed file will contain both file map and file data, so no |
9931 |
additional data will be needed to restore it. If the original file |
9932 |
name was @file{@var{dir}/@var{name}}, then the condensed file will be |
9933 |
named @file{@var{dir}/@/GNUSparseFile.@var{n}/@/@var{name}}, where |
9934 |
@var{n} is a decimal number@footnote{Technically speaking, @var{n} is a |
9935 |
@dfn{process @acronym{ID}} of the @command{tar} process which created the |
9936 |
archive (@pxref{PAX keywords}).}. |
9937 |
|
9938 |
To expand a version 1.0 file, run @command{xsparse} as follows: |
9939 |
|
9940 |
@smallexample |
9941 |
$ @kbd{xsparse @file{cond-file}} |
9942 |
@end smallexample |
9943 |
|
9944 |
@noindent |
9945 |
where @file{cond-file} is the name of the condensed file. The utility |
9946 |
will deduce the name for the resulting expanded file using the |
9947 |
following algorithm: |
9948 |
|
9949 |
@enumerate 1 |
9950 |
@item If @file{cond-file} does not contain any directories, |
9951 |
@file{../cond-file} will be used; |
9952 |
|
9953 |
@item If @file{cond-file} has the form |
9954 |
@file{@var{dir}/@var{t}/@var{name}}, where both @var{t} and @var{name} |
9955 |
are simple names, with no @samp{/} characters in them, the output file |
9956 |
name will be @file{@var{dir}/@var{name}}. |
9957 |
|
9958 |
@item Otherwise, if @file{cond-file} has the form |
9959 |
@file{@var{dir}/@var{name}}, the output file name will be |
9960 |
@file{@var{name}}. |
9961 |
@end enumerate |
9962 |
|
9963 |
In the unlikely case when this algorithm does not suit your needs, |
9964 |
you can explicitly specify output file name as a second argument to |
9965 |
the command: |
9966 |
|
9967 |
@smallexample |
9968 |
$ @kbd{xsparse @file{cond-file} @file{out-file}} |
9969 |
@end smallexample |
9970 |
|
9971 |
It is often a good idea to run @command{xsparse} in @dfn{dry run} mode |
9972 |
first. In this mode, the command does not actually expand the file, |
9973 |
but verbosely lists all actions it would be taking to do so. The dry |
9974 |
run mode is enabled by @option{-n} command line argument: |
9975 |
|
9976 |
@smallexample |
9977 |
@group |
9978 |
$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile} |
9979 |
Reading v.1.0 sparse map |
9980 |
Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to |
9981 |
`/home/gray/sparsefile' |
9982 |
Finished dry run |
9983 |
@end group |
9984 |
@end smallexample |
9985 |
|
9986 |
To actually expand the file, you would run: |
9987 |
|
9988 |
@smallexample |
9989 |
$ @kbd{xsparse /home/gray/GNUSparseFile.6058/sparsefile} |
9990 |
@end smallexample |
9991 |
|
9992 |
@noindent |
9993 |
The program behaves the same way all UNIX utilities do: it will keep |
9994 |
quiet unless it has simething important to tell you (e.g. an error |
9995 |
condition or something). If you wish it to produce verbose output, |
9996 |
similar to that from the dry run mode, use @option{-v} option: |
9997 |
|
9998 |
@smallexample |
9999 |
@group |
10000 |
$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile} |
10001 |
Reading v.1.0 sparse map |
10002 |
Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to |
10003 |
`/home/gray/sparsefile' |
10004 |
Done |
10005 |
@end group |
10006 |
@end smallexample |
10007 |
|
10008 |
Additionally, if your @command{tar} implementation has extracted the |
10009 |
@dfn{extended headers} for this file, you can instruct @command{xstar} |
10010 |
to use them in order to verify the integrity of the expanded file. |
10011 |
The option @option{-x} sets the name of the extended header file to |
10012 |
use. Continuing our example: |
10013 |
|
10014 |
@smallexample |
10015 |
@group |
10016 |
$ @kbd{xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \ |
10017 |
/home/gray/GNUSparseFile.6058/sparsefile} |
10018 |
Reading extended header file |
10019 |
Found variable GNU.sparse.major = 1 |
10020 |
Found variable GNU.sparse.minor = 0 |
10021 |
Found variable GNU.sparse.name = sparsefile |
10022 |
Found variable GNU.sparse.realsize = 217481216 |
10023 |
Reading v.1.0 sparse map |
10024 |
Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to |
10025 |
`/home/gray/sparsefile' |
10026 |
Done |
10027 |
@end group |
10028 |
@end smallexample |
10029 |
|
10030 |
@anchor{extracting sparse v.0.x} |
10031 |
@cindex sparse files v.0.1, extracting with non-GNU tars |
10032 |
@cindex sparse files v.0.0, extracting with non-GNU tars |
10033 |
An @dfn{extended header} is a special @command{tar} archive header |
10034 |
that precedes an archive member and contains a set of |
10035 |
@dfn{variables}, describing the member properties that cannot be |
10036 |
stored in the standard @code{ustar} header. While optional for |
10037 |
expanding sparse version 1.0 members, the use of extended headers is |
10038 |
mandatory when expanding sparse members in older sparse formats: v.0.0 |
10039 |
and v.0.1 (The sparse formats are described in detail in @ref{Sparse |
10040 |
Formats}.) So, for these formats, the question is: how to obtain |
10041 |
extended headers from the archive? |
10042 |
|
10043 |
If you use a @command{tar} implementation that does not support PAX |
10044 |
format, extended headers for each member will be extracted as a |
10045 |
separate file. If we represent the member name as |
10046 |
@file{@var{dir}/@var{name}}, then the extended header file will be |
10047 |
named @file{@var{dir}/@/PaxHeaders.@var{n}/@/@var{name}}, where |
10048 |
@var{n} is an integer number. |
10049 |
|
10050 |
Things become more difficult if your @command{tar} implementation |
10051 |
does support PAX headers, because in this case you will have to |
10052 |
manually extract the headers. We recommend the following algorithm: |
10053 |
|
10054 |
@enumerate 1 |
10055 |
@item |
10056 |
Consult the documentation of your @command{tar} implementation for an |
10057 |
option that prints @dfn{block numbers} along with the archive |
10058 |
listing (analogous to @GNUTAR{}'s @option{-R} option). For example, |
10059 |
@command{star} has @option{-block-number}. |
10060 |
|
10061 |
@item |
10062 |
Obtain verbose listing using the @samp{block number} option, and |
10063 |
find block numbers of the sparse member in question and the member |
10064 |
immediately following it. For example, running @command{star} on our |
10065 |
archive we obtain: |
10066 |
|
10067 |
@smallexample |
10068 |
@group |
10069 |
$ @kbd{star -t -v -block-number -f arc.tar} |
10070 |
@dots{} |
10071 |
star: Unknown extended header keyword 'GNU.sparse.size' ignored. |
10072 |
star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored. |
10073 |
star: Unknown extended header keyword 'GNU.sparse.name' ignored. |
10074 |
star: Unknown extended header keyword 'GNU.sparse.map' ignored. |
10075 |
block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile |
10076 |
block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README |
10077 |
@dots{} |
10078 |
@end group |
10079 |
@end smallexample |
10080 |
|
10081 |
@noindent |
10082 |
(as usual, ignore the warnings about unknown keywords.) |
10083 |
|
10084 |
@item |
10085 |
Let @var{size} be the size of the sparse member, @var{Bs} be its block number |
10086 |
and @var{Bn} be the block number of the next member. |
10087 |
Compute: |
10088 |
|
10089 |
@smallexample |
10090 |
@var{N} = @var{Bs} - @var{Bn} - @var{size}/512 - 2 |
10091 |
@end smallexample |
10092 |
|
10093 |
@noindent |
10094 |
This number gives the size of the extended header part in tar @dfn{blocks}. |
10095 |
In our example, this formula gives: @code{897 - 56 - 425984 / 512 - 2 |
10096 |
= 7}. |
10097 |
|
10098 |
@item |
10099 |
Use @command{dd} to extract the headers: |
10100 |
|
10101 |
@smallexample |
10102 |
@kbd{dd if=@var{archive} of=@var{hname} bs=512 skip=@var{Bs} count=@var{N}} |
10103 |
@end smallexample |
10104 |
|
10105 |
@noindent |
10106 |
where @var{archive} is the archive name, @var{hname} is a name of the |
10107 |
file to store the extended header in, @var{Bs} and @var{N} are |
10108 |
computed in previous steps. |
10109 |
|
10110 |
In our example, this command will be |
10111 |
|
10112 |
@smallexample |
10113 |
$ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56 count=7} |
10114 |
@end smallexample |
10115 |
@end enumerate |
10116 |
|
10117 |
Finally, you can expand the condensed file, using the obtained header: |
10118 |
|
10119 |
@smallexample |
10120 |
@group |
10121 |
$ @kbd{xsparse -v -x xhdr GNUSparseFile.6058/sparsefile} |
10122 |
Reading extended header file |
10123 |
Found variable GNU.sparse.size = 217481216 |
10124 |
Found variable GNU.sparse.numblocks = 208 |
10125 |
Found variable GNU.sparse.name = sparsefile |
10126 |
Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{} |
10127 |
Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile' |
10128 |
Done |
10129 |
@end group |
10130 |
@end smallexample |
10131 |
|
10132 |
@node cpio |
10133 |
@section Comparison of @command{tar} and @command{cpio} |
10134 |
@UNREVISED |
10135 |
|
10136 |
@FIXME{Reorganize the following material} |
10137 |
|
10138 |
The @command{cpio} archive formats, like @command{tar}, do have maximum |
10139 |
file name lengths. The binary and old @acronym{ASCII} formats have a maximum file |
10140 |
length of 256, and the new @acronym{ASCII} and @acronym{CRC ASCII} formats have a max |
10141 |
file length of 1024. @acronym{GNU} @command{cpio} can read and write archives |
10142 |
with arbitrary file name lengths, but other @command{cpio} implementations |
10143 |
may crash unexplainedly trying to read them. |
10144 |
|
10145 |
@command{tar} handles symbolic links in the form in which it comes in @acronym{BSD}; |
10146 |
@command{cpio} doesn't handle symbolic links in the form in which it comes |
10147 |
in System V prior to SVR4, and some vendors may have added symlinks |
10148 |
to their system without enhancing @command{cpio} to know about them. |
10149 |
Others may have enhanced it in a way other than the way I did it |
10150 |
at Sun, and which was adopted by AT&T (and which is, I think, also |
10151 |
present in the @command{cpio} that Berkeley picked up from AT&T and put |
10152 |
into a later @acronym{BSD} release---I think I gave them my changes). |
10153 |
|
10154 |
(SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio} |
10155 |
can handle @command{tar} format input, and write it on output, and it |
10156 |
probably handles symbolic links. They may not have bothered doing |
10157 |
anything to enhance @command{tar} as a result.) |
10158 |
|
10159 |
@command{cpio} handles special files; traditional @command{tar} doesn't. |
10160 |
|
10161 |
@command{tar} comes with V7, System III, System V, and @acronym{BSD} source; |
10162 |
@command{cpio} comes only with System III, System V, and later @acronym{BSD} |
10163 |
(4.3-tahoe and later). |
10164 |
|
10165 |
@command{tar}'s way of handling multiple hard links to a file can handle |
10166 |
file systems that support 32-bit i-numbers (e.g., the @acronym{BSD} file system); |
10167 |
@command{cpio}s way requires you to play some games (in its ``binary'' |
10168 |
format, i-numbers are only 16 bits, and in its ``portable @acronym{ASCII}'' format, |
10169 |
they're 18 bits---it would have to play games with the "file system @acronym{ID}" |
10170 |
field of the header to make sure that the file system @acronym{ID}/i-number pairs |
10171 |
of different files were always different), and I don't know which |
10172 |
@command{cpio}s, if any, play those games. Those that don't might get |
10173 |
confused and think two files are the same file when they're not, and |
10174 |
make hard links between them. |
10175 |
|
10176 |
@command{tar}s way of handling multiple hard links to a file places only |
10177 |
one copy of the link on the tape, but the name attached to that copy |
10178 |
is the @emph{only} one you can use to retrieve the file; @command{cpio}s |
10179 |
way puts one copy for every link, but you can retrieve it using any |
10180 |
of the names. |
10181 |
|
10182 |
@quotation |
10183 |
What type of check sum (if any) is used, and how is this calculated. |
10184 |
@end quotation |
10185 |
|
10186 |
See the attached manual pages for @command{tar} and @command{cpio} format. |
10187 |
@command{tar} uses a checksum which is the sum of all the bytes in the |
10188 |
@command{tar} header for a file; @command{cpio} uses no checksum. |
10189 |
|
10190 |
@quotation |
10191 |
If anyone knows why @command{cpio} was made when @command{tar} was present |
10192 |
at the unix scene, |
10193 |
@end quotation |
10194 |
|
10195 |
It wasn't. @command{cpio} first showed up in PWB/UNIX 1.0; no |
10196 |
generally-available version of UNIX had @command{tar} at the time. I don't |
10197 |
know whether any version that was generally available @emph{within AT&T} |
10198 |
had @command{tar}, or, if so, whether the people within AT&T who did |
10199 |
@command{cpio} knew about it. |
10200 |
|
10201 |
On restore, if there is a corruption on a tape @command{tar} will stop at |
10202 |
that point, while @command{cpio} will skip over it and try to restore the |
10203 |
rest of the files. |
10204 |
|
10205 |
The main difference is just in the command syntax and header format. |
10206 |
|
10207 |
@command{tar} is a little more tape-oriented in that everything is blocked |
10208 |
to start on a record boundary. |
10209 |
|
10210 |
@quotation |
10211 |
Is there any differences between the ability to recover crashed |
10212 |
archives between the two of them. (Is there any chance of recovering |
10213 |
crashed archives at all.) |
10214 |
@end quotation |
10215 |
|
10216 |
Theoretically it should be easier under @command{tar} since the blocking |
10217 |
lets you find a header with some variation of @samp{dd skip=@var{nn}}. |
10218 |
However, modern @command{cpio}'s and variations have an option to just |
10219 |
search for the next file header after an error with a reasonable chance |
10220 |
of resyncing. However, lots of tape driver software won't allow you to |
10221 |
continue past a media error which should be the only reason for getting |
10222 |
out of sync unless a file changed sizes while you were writing the |
10223 |
archive. |
10224 |
|
10225 |
@quotation |
10226 |
If anyone knows why @command{cpio} was made when @command{tar} was present |
10227 |
at the unix scene, please tell me about this too. |
10228 |
@end quotation |
10229 |
|
10230 |
Probably because it is more media efficient (by not blocking everything |
10231 |
and using only the space needed for the headers where @command{tar} |
10232 |
always uses 512 bytes per file header) and it knows how to archive |
10233 |
special files. |
10234 |
|
10235 |
You might want to look at the freely available alternatives. The |
10236 |
major ones are @command{afio}, @GNUTAR{}, and |
10237 |
@command{pax}, each of which have their own extensions with some |
10238 |
backwards compatibility. |
10239 |
|
10240 |
Sparse files were @command{tar}red as sparse files (which you can |
10241 |
easily test, because the resulting archive gets smaller, and |
10242 |
@acronym{GNU} @command{cpio} can no longer read it). |
10243 |
|
10244 |
@node Media |
10245 |
@chapter Tapes and Other Archive Media |
10246 |
@UNREVISED |
10247 |
|
10248 |
A few special cases about tape handling warrant more detailed |
10249 |
description. These special cases are discussed below. |
10250 |
|
10251 |
Many complexities surround the use of @command{tar} on tape drives. Since |
10252 |
the creation and manipulation of archives located on magnetic tape was |
10253 |
the original purpose of @command{tar}, it contains many features making |
10254 |
such manipulation easier. |
10255 |
|
10256 |
Archives are usually written on dismountable media---tape cartridges, |
10257 |
mag tapes, or floppy disks. |
10258 |
|
10259 |
The amount of data a tape or disk holds depends not only on its size, |
10260 |
but also on how it is formatted. A 2400 foot long reel of mag tape |
10261 |
holds 40 megabytes of data when formatted at 1600 bits per inch. The |
10262 |
physically smaller EXABYTE tape cartridge holds 2.3 gigabytes. |
10263 |
|
10264 |
Magnetic media are re-usable---once the archive on a tape is no longer |
10265 |
needed, the archive can be erased and the tape or disk used over. |
10266 |
Media quality does deteriorate with use, however. Most tapes or disks |
10267 |
should be discarded when they begin to produce data errors. EXABYTE |
10268 |
tape cartridges should be discarded when they generate an @dfn{error |
10269 |
count} (number of non-usable bits) of more than 10k. |
10270 |
|
10271 |
Magnetic media are written and erased using magnetic fields, and |
10272 |
should be protected from such fields to avoid damage to stored data. |
10273 |
Sticking a floppy disk to a filing cabinet using a magnet is probably |
10274 |
not a good idea. |
10275 |
|
10276 |
@menu |
10277 |
* Device:: Device selection and switching |
10278 |
* Remote Tape Server:: |
10279 |
* Common Problems and Solutions:: |
10280 |
* Blocking:: Blocking |
10281 |
* Many:: Many archives on one tape |
10282 |
* Using Multiple Tapes:: Using Multiple Tapes |
10283 |
* label:: Including a Label in the Archive |
10284 |
* verify:: |
10285 |
* Write Protection:: |
10286 |
@end menu |
10287 |
|
10288 |
@node Device |
10289 |
@section Device Selection and Switching |
10290 |
@UNREVISED |
10291 |
|
10292 |
@table @option |
10293 |
@item -f [@var{hostname}:]@var{file} |
10294 |
@itemx --file=[@var{hostname}:]@var{file} |
10295 |
Use archive file or device @var{file} on @var{hostname}. |
10296 |
@end table |
10297 |
|
10298 |
This option is used to specify the file name of the archive @command{tar} |
10299 |
works on. |
10300 |
|
10301 |
If the file name is @samp{-}, @command{tar} reads the archive from standard |
10302 |
input (when listing or extracting), or writes it to standard output |
10303 |
(when creating). If the @samp{-} file name is given when updating an |
10304 |
archive, @command{tar} will read the original archive from its standard |
10305 |
input, and will write the entire new archive to its standard output. |
10306 |
|
10307 |
If the file name contains a @samp{:}, it is interpreted as |
10308 |
@samp{hostname:file name}. If the @var{hostname} contains an @dfn{at} |
10309 |
sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}. In |
10310 |
either case, @command{tar} will invoke the command @command{rsh} (or |
10311 |
@command{remsh}) to start up an @command{/usr/libexec/rmt} on the remote |
10312 |
machine. If you give an alternate login name, it will be given to the |
10313 |
@command{rsh}. |
10314 |
Naturally, the remote machine must have an executable |
10315 |
@command{/usr/libexec/rmt}. This program is free software from the |
10316 |
University of California, and a copy of the source code can be found |
10317 |
with the sources for @command{tar}; it's compiled and installed by default. |
10318 |
The exact path to this utility is determined when configuring the package. |
10319 |
It is @file{@var{prefix}/libexec/rmt}, where @var{prefix} stands for |
10320 |
your installation prefix. This location may also be overridden at |
10321 |
runtime by using the @option{--rmt-command=@var{command}} option (@xref{Option Summary, |
10322 |
---rmt-command}, for detailed description of this option. @xref{Remote |
10323 |
Tape Server}, for the description of @command{rmt} command). |
10324 |
|
10325 |
If this option is not given, but the environment variable @env{TAPE} |
10326 |
is set, its value is used; otherwise, old versions of @command{tar} |
10327 |
used a default archive name (which was picked when @command{tar} was |
10328 |
compiled). The default is normally set up to be the @dfn{first} tape |
10329 |
drive or other transportable I/O medium on the system. |
10330 |
|
10331 |
Starting with version 1.11.5, @GNUTAR{} uses |
10332 |
standard input and standard output as the default device, and I will |
10333 |
not try anymore supporting automatic device detection at installation |
10334 |
time. This was failing really in too many cases, it was hopeless. |
10335 |
This is now completely left to the installer to override standard |
10336 |
input and standard output for default device, if this seems |
10337 |
preferable. Further, I think @emph{most} actual usages of |
10338 |
@command{tar} are done with pipes or disks, not really tapes, |
10339 |
cartridges or diskettes. |
10340 |
|
10341 |
Some users think that using standard input and output is running |
10342 |
after trouble. This could lead to a nasty surprise on your screen if |
10343 |
you forget to specify an output file name---especially if you are going |
10344 |
through a network or terminal server capable of buffering large amounts |
10345 |
of output. We had so many bug reports in that area of configuring |
10346 |
default tapes automatically, and so many contradicting requests, that |
10347 |
we finally consider the problem to be portably intractable. We could |
10348 |
of course use something like @samp{/dev/tape} as a default, but this |
10349 |
is @emph{also} running after various kind of trouble, going from hung |
10350 |
processes to accidental destruction of real tapes. After having seen |
10351 |
all this mess, using standard input and output as a default really |
10352 |
sounds like the only clean choice left, and a very useful one too. |
10353 |
|
10354 |
@GNUTAR{} reads and writes archive in records, I |
10355 |
suspect this is the main reason why block devices are preferred over |
10356 |
character devices. Most probably, block devices are more efficient |
10357 |
too. The installer could also check for @samp{DEFTAPE} in |
10358 |
@file{<sys/mtio.h>}. |
10359 |
|
10360 |
@table @option |
10361 |
@xopindex{force-local, short description} |
10362 |
@item --force-local |
10363 |
Archive file is local even if it contains a colon. |
10364 |
|
10365 |
@opindex rsh-command |
10366 |
@item --rsh-command=@var{command} |
10367 |
Use remote @var{command} instead of @command{rsh}. This option exists |
10368 |
so that people who use something other than the standard @command{rsh} |
10369 |
(e.g., a Kerberized @command{rsh}) can access a remote device. |
10370 |
|
10371 |
When this command is not used, the shell command found when |
10372 |
the @command{tar} program was installed is used instead. This is |
10373 |
the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh}, |
10374 |
@file{/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}. |
10375 |
The installer may have overridden this by defining the environment |
10376 |
variable @env{RSH} @emph{at installation time}. |
10377 |
|
10378 |
@item -[0-7][lmh] |
10379 |
Specify drive and density. |
10380 |
|
10381 |
@xopindex{multi-volume, short description} |
10382 |
@item -M |
10383 |
@itemx --multi-volume |
10384 |
Create/list/extract multi-volume archive. |
10385 |
|
10386 |
This option causes @command{tar} to write a @dfn{multi-volume} archive---one |
10387 |
that may be larger than will fit on the medium used to hold it. |
10388 |
@xref{Multi-Volume Archives}. |
10389 |
|
10390 |
@xopindex{tape-length, short description} |
10391 |
@item -L @var{num} |
10392 |
@itemx --tape-length=@var{size}[@var{suf}] |
10393 |
Change tape after writing @var{size} units of data. Unless @var{suf} is |
10394 |
given, @var{size} is treated as kilobytes, i.e. @samp{@var{size} x |
10395 |
1024} bytes. The following suffixes alter this behavior: |
10396 |
|
10397 |
@float Table, size-suffixes |
10398 |
@caption{Size Suffixes} |
10399 |
@multitable @columnfractions 0.2 0.3 0.3 |
10400 |
@headitem Suffix @tab Units @tab Byte Equivalent |
10401 |
@item b @tab Blocks @tab @var{size} x 512 |
10402 |
@item B @tab Kilobytes @tab @var{size} x 1024 |
10403 |
@item c @tab Bytes @tab @var{size} |
10404 |
@item G @tab Gigabytes @tab @var{size} x 1024^3 |
10405 |
@item K @tab Kilobytes @tab @var{size} x 1024 |
10406 |
@item k @tab Kilobytes @tab @var{size} x 1024 |
10407 |
@item M @tab Megabytes @tab @var{size} x 1024^2 |
10408 |
@item P @tab Petabytes @tab @var{size} x 1024^5 |
10409 |
@item T @tab Terabytes @tab @var{size} x 1024^4 |
10410 |
@item w @tab Words @tab @var{size} x 2 |
10411 |
@end multitable |
10412 |
@end float |
10413 |
|
10414 |
This option might be useful when your tape drivers do not properly |
10415 |
detect end of physical tapes. By being slightly conservative on the |
10416 |
maximum tape length, you might avoid the problem entirely. |
10417 |
|
10418 |
@xopindex{info-script, short description} |
10419 |
@xopindex{new-volume-script, short description} |
10420 |
@item -F @var{file} |
10421 |
@itemx --info-script=@var{file} |
10422 |
@itemx --new-volume-script=@var{file} |
10423 |
Execute @file{file} at end of each tape. This implies |
10424 |
@option{--multi-volume} (@option{-M}). @xref{info-script}, for a detailed |
10425 |
description of this option. |
10426 |
@end table |
10427 |
|
10428 |
@node Remote Tape Server |
10429 |
@section Remote Tape Server |
10430 |
|
10431 |
@cindex remote tape drive |
10432 |
@pindex rmt |
10433 |
In order to access the tape drive on a remote machine, @command{tar} |
10434 |
uses the remote tape server written at the University of California at |
10435 |
Berkeley. The remote tape server must be installed as |
10436 |
@file{@var{prefix}/libexec/rmt} on any machine whose tape drive you |
10437 |
want to use. @command{tar} calls @command{rmt} by running an |
10438 |
@command{rsh} or @command{remsh} to the remote machine, optionally |
10439 |
using a different login name if one is supplied. |
10440 |
|
10441 |
A copy of the source for the remote tape server is provided. It is |
10442 |
Copyright @copyright{} 1983 by the Regents of the University of |
10443 |
California, but can be freely distributed. It is compiled and |
10444 |
installed by default. |
10445 |
|
10446 |
@cindex absolute file names |
10447 |
Unless you use the @option{--absolute-names} (@option{-P}) option, |
10448 |
@GNUTAR{} will not allow you to create an archive that contains |
10449 |
absolute file names (a file name beginning with @samp{/}.) If you try, |
10450 |
@command{tar} will automatically remove the leading @samp{/} from the |
10451 |
file names it stores in the archive. It will also type a warning |
10452 |
message telling you what it is doing. |
10453 |
|
10454 |
When reading an archive that was created with a different |
10455 |
@command{tar} program, @GNUTAR{} automatically |
10456 |
extracts entries in the archive which have absolute file names as if |
10457 |
the file names were not absolute. This is an important feature. A |
10458 |
visitor here once gave a @command{tar} tape to an operator to restore; |
10459 |
the operator used Sun @command{tar} instead of @GNUTAR{}, |
10460 |
and the result was that it replaced large portions of |
10461 |
our @file{/bin} and friends with versions from the tape; needless to |
10462 |
say, we were unhappy about having to recover the file system from |
10463 |
backup tapes. |
10464 |
|
10465 |
For example, if the archive contained a file @file{/usr/bin/computoy}, |
10466 |
@GNUTAR{} would extract the file to @file{usr/bin/computoy}, |
10467 |
relative to the current directory. If you want to extract the files in |
10468 |
an archive to the same absolute names that they had when the archive |
10469 |
was created, you should do a @samp{cd /} before extracting the files |
10470 |
from the archive, or you should either use the @option{--absolute-names} |
10471 |
option, or use the command @samp{tar -C / @dots{}}. |
10472 |
|
10473 |
@cindex Ultrix 3.1 and write failure |
10474 |
Some versions of Unix (Ultrix 3.1 is known to have this problem), |
10475 |
can claim that a short write near the end of a tape succeeded, |
10476 |
when it actually failed. This will result in the -M option not |
10477 |
working correctly. The best workaround at the moment is to use a |
10478 |
significantly larger blocking factor than the default 20. |
10479 |
|
10480 |
In order to update an archive, @command{tar} must be able to backspace the |
10481 |
archive in order to reread or rewrite a record that was just read (or |
10482 |
written). This is currently possible only on two kinds of files: normal |
10483 |
disk files (or any other file that can be backspaced with @samp{lseek}), |
10484 |
and industry-standard 9-track magnetic tape (or any other kind of tape |
10485 |
that can be backspaced with the @code{MTIOCTOP} @code{ioctl}). |
10486 |
|
10487 |
This means that the @option{--append}, @option{--concatenate}, and |
10488 |
@option{--delete} commands will not work on any other kind of file. |
10489 |
Some media simply cannot be backspaced, which means these commands and |
10490 |
options will never be able to work on them. These non-backspacing |
10491 |
media include pipes and cartridge tape drives. |
10492 |
|
10493 |
Some other media can be backspaced, and @command{tar} will work on them |
10494 |
once @command{tar} is modified to do so. |
10495 |
|
10496 |
Archives created with the @option{--multi-volume}, @option{--label}, and |
10497 |
@option{--incremental} (@option{-G}) options may not be readable by other version |
10498 |
of @command{tar}. In particular, restoring a file that was split over |
10499 |
a volume boundary will require some careful work with @command{dd}, if |
10500 |
it can be done at all. Other versions of @command{tar} may also create |
10501 |
an empty file whose name is that of the volume header. Some versions |
10502 |
of @command{tar} may create normal files instead of directories archived |
10503 |
with the @option{--incremental} (@option{-G}) option. |
10504 |
|
10505 |
@node Common Problems and Solutions |
10506 |
@section Some Common Problems and their Solutions |
10507 |
|
10508 |
@ifclear PUBLISH |
10509 |
|
10510 |
@format |
10511 |
errors from system: |
10512 |
permission denied |
10513 |
no such file or directory |
10514 |
not owner |
10515 |
|
10516 |
errors from @command{tar}: |
10517 |
directory checksum error |
10518 |
header format error |
10519 |
|
10520 |
errors from media/system: |
10521 |
i/o error |
10522 |
device busy |
10523 |
@end format |
10524 |
|
10525 |
@end ifclear |
10526 |
|
10527 |
@node Blocking |
10528 |
@section Blocking |
10529 |
@cindex block |
10530 |
@cindex record |
10531 |
|
10532 |
@dfn{Block} and @dfn{record} terminology is rather confused, and it |
10533 |
is also confusing to the expert reader. On the other hand, readers |
10534 |
who are new to the field have a fresh mind, and they may safely skip |
10535 |
the next two paragraphs, as the remainder of this manual uses those |
10536 |
two terms in a quite consistent way. |
10537 |
|
10538 |
John Gilmore, the writer of the public domain @command{tar} from which |
10539 |
@GNUTAR{} was originally derived, wrote (June 1995): |
10540 |
|
10541 |
@quotation |
10542 |
The nomenclature of tape drives comes from IBM, where I believe |
10543 |
they were invented for the IBM 650 or so. On IBM mainframes, what |
10544 |
is recorded on tape are tape blocks. The logical organization of |
10545 |
data is into records. There are various ways of putting records into |
10546 |
blocks, including @code{F} (fixed sized records), @code{V} (variable |
10547 |
sized records), @code{FB} (fixed blocked: fixed size records, @var{n} |
10548 |
to a block), @code{VB} (variable size records, @var{n} to a block), |
10549 |
@code{VSB} (variable spanned blocked: variable sized records that can |
10550 |
occupy more than one block), etc. The @code{JCL} @samp{DD RECFORM=} |
10551 |
parameter specified this to the operating system. |
10552 |
|
10553 |
The Unix man page on @command{tar} was totally confused about this. |
10554 |
When I wrote @code{PD TAR}, I used the historically correct terminology |
10555 |
(@command{tar} writes data records, which are grouped into blocks). |
10556 |
It appears that the bogus terminology made it into @acronym{POSIX} (no surprise |
10557 |
here), and now Fran@,{c}ois has migrated that terminology back |
10558 |
into the source code too. |
10559 |
@end quotation |
10560 |
|
10561 |
The term @dfn{physical block} means the basic transfer chunk from or |
10562 |
to a device, after which reading or writing may stop without anything |
10563 |
being lost. In this manual, the term @dfn{block} usually refers to |
10564 |
a disk physical block, @emph{assuming} that each disk block is 512 |
10565 |
bytes in length. It is true that some disk devices have different |
10566 |
physical blocks, but @command{tar} ignore these differences in its own |
10567 |
format, which is meant to be portable, so a @command{tar} block is always |
10568 |
512 bytes in length, and @dfn{block} always mean a @command{tar} block. |
10569 |
The term @dfn{logical block} often represents the basic chunk of |
10570 |
allocation of many disk blocks as a single entity, which the operating |
10571 |
system treats somewhat atomically; this concept is only barely used |
10572 |
in @GNUTAR{}. |
10573 |
|
10574 |
The term @dfn{physical record} is another way to speak of a physical |
10575 |
block, those two terms are somewhat interchangeable. In this manual, |
10576 |
the term @dfn{record} usually refers to a tape physical block, |
10577 |
@emph{assuming} that the @command{tar} archive is kept on magnetic tape. |
10578 |
It is true that archives may be put on disk or used with pipes, |
10579 |
but nevertheless, @command{tar} tries to read and write the archive one |
10580 |
@dfn{record} at a time, whatever the medium in use. One record is made |
10581 |
up of an integral number of blocks, and this operation of putting many |
10582 |
disk blocks into a single tape block is called @dfn{reblocking}, or |
10583 |
more simply, @dfn{blocking}. The term @dfn{logical record} refers to |
10584 |
the logical organization of many characters into something meaningful |
10585 |
to the application. The term @dfn{unit record} describes a small set |
10586 |
of characters which are transmitted whole to or by the application, |
10587 |
and often refers to a line of text. Those two last terms are unrelated |
10588 |
to what we call a @dfn{record} in @GNUTAR{}. |
10589 |
|
10590 |
When writing to tapes, @command{tar} writes the contents of the archive |
10591 |
in chunks known as @dfn{records}. To change the default blocking |
10592 |
factor, use the @option{--blocking-factor=@var{512-size}} (@option{-b |
10593 |
@var{512-size}}) option. Each record will then be composed of |
10594 |
@var{512-size} blocks. (Each @command{tar} block is 512 bytes. |
10595 |
@xref{Standard}.) Each file written to the archive uses at least one |
10596 |
full record. As a result, using a larger record size can result in |
10597 |
more wasted space for small files. On the other hand, a larger record |
10598 |
size can often be read and written much more efficiently. |
10599 |
|
10600 |
Further complicating the problem is that some tape drives ignore the |
10601 |
blocking entirely. For these, a larger record size can still improve |
10602 |
performance (because the software layers above the tape drive still |
10603 |
honor the blocking), but not as dramatically as on tape drives that |
10604 |
honor blocking. |
10605 |
|
10606 |
When reading an archive, @command{tar} can usually figure out the |
10607 |
record size on itself. When this is the case, and a non-standard |
10608 |
record size was used when the archive was created, @command{tar} will |
10609 |
print a message about a non-standard blocking factor, and then operate |
10610 |
normally. On some tape devices, however, @command{tar} cannot figure |
10611 |
out the record size itself. On most of those, you can specify a |
10612 |
blocking factor (with @option{--blocking-factor}) larger than the |
10613 |
actual blocking factor, and then use the @option{--read-full-records} |
10614 |
(@option{-B}) option. (If you specify a blocking factor with |
10615 |
@option{--blocking-factor} and don't use the |
10616 |
@option{--read-full-records} option, then @command{tar} will not |
10617 |
attempt to figure out the recording size itself.) On some devices, |
10618 |
you must always specify the record size exactly with |
10619 |
@option{--blocking-factor} when reading, because @command{tar} cannot |
10620 |
figure it out. In any case, use @option{--list} (@option{-t}) before |
10621 |
doing any extractions to see whether @command{tar} is reading the archive |
10622 |
correctly. |
10623 |
|
10624 |
@command{tar} blocks are all fixed size (512 bytes), and its scheme for |
10625 |
putting them into records is to put a whole number of them (one or |
10626 |
more) into each record. @command{tar} records are all the same size; |
10627 |
at the end of the file there's a block containing all zeros, which |
10628 |
is how you tell that the remainder of the last record(s) are garbage. |
10629 |
|
10630 |
In a standard @command{tar} file (no options), the block size is 512 |
10631 |
and the record size is 10240, for a blocking factor of 20. What the |
10632 |
@option{--blocking-factor} option does is sets the blocking factor, |
10633 |
changing the record size while leaving the block size at 512 bytes. |
10634 |
20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives; |
10635 |
most tape drives these days prefer much bigger records in order to |
10636 |
stream and not waste tape. When writing tapes for myself, some tend |
10637 |
to use a factor of the order of 2048, say, giving a record size of |
10638 |
around one megabyte. |
10639 |
|
10640 |
If you use a blocking factor larger than 20, older @command{tar} |
10641 |
programs might not be able to read the archive, so we recommend this |
10642 |
as a limit to use in practice. @GNUTAR{}, however, |
10643 |
will support arbitrarily large record sizes, limited only by the |
10644 |
amount of virtual memory or the physical characteristics of the tape |
10645 |
device. |
10646 |
|
10647 |
@menu |
10648 |
* Format Variations:: Format Variations |
10649 |
* Blocking Factor:: The Blocking Factor of an Archive |
10650 |
@end menu |
10651 |
|
10652 |
@node Format Variations |
10653 |
@subsection Format Variations |
10654 |
@cindex Format Parameters |
10655 |
@cindex Format Options |
10656 |
@cindex Options, archive format specifying |
10657 |
@cindex Options, format specifying |
10658 |
@UNREVISED |
10659 |
|
10660 |
Format parameters specify how an archive is written on the archive |
10661 |
media. The best choice of format parameters will vary depending on |
10662 |
the type and number of files being archived, and on the media used to |
10663 |
store the archive. |
10664 |
|
10665 |
To specify format parameters when accessing or creating an archive, |
10666 |
you can use the options described in the following sections. |
10667 |
If you do not specify any format parameters, @command{tar} uses |
10668 |
default parameters. You cannot modify a compressed archive. |
10669 |
If you create an archive with the @option{--blocking-factor} option |
10670 |
specified (@pxref{Blocking Factor}), you must specify that |
10671 |
blocking-factor when operating on the archive. @xref{Formats}, for other |
10672 |
examples of format parameter considerations. |
10673 |
|
10674 |
@node Blocking Factor |
10675 |
@subsection The Blocking Factor of an Archive |
10676 |
@cindex Blocking Factor |
10677 |
@cindex Record Size |
10678 |
@cindex Number of blocks per record |
10679 |
@cindex Number of bytes per record |
10680 |
@cindex Bytes per record |
10681 |
@cindex Blocks per record |
10682 |
@UNREVISED |
10683 |
|
10684 |
@opindex blocking-factor |
10685 |
The data in an archive is grouped into blocks, which are 512 bytes. |
10686 |
Blocks are read and written in whole number multiples called |
10687 |
@dfn{records}. The number of blocks in a record (i.e., the size of a |
10688 |
record in units of 512 bytes) is called the @dfn{blocking factor}. |
10689 |
The @option{--blocking-factor=@var{512-size}} (@option{-b |
10690 |
@var{512-size}}) option specifies the blocking factor of an archive. |
10691 |
The default blocking factor is typically 20 (i.e., 10240 bytes), but |
10692 |
can be specified at installation. To find out the blocking factor of |
10693 |
an existing archive, use @samp{tar --list --file=@var{archive-name}}. |
10694 |
This may not work on some devices. |
10695 |
|
10696 |
Records are separated by gaps, which waste space on the archive media. |
10697 |
If you are archiving on magnetic tape, using a larger blocking factor |
10698 |
(and therefore larger records) provides faster throughput and allows you |
10699 |
to fit more data on a tape (because there are fewer gaps). If you are |
10700 |
archiving on cartridge, a very large blocking factor (say 126 or more) |
10701 |
greatly increases performance. A smaller blocking factor, on the other |
10702 |
hand, may be useful when archiving small files, to avoid archiving lots |
10703 |
of nulls as @command{tar} fills out the archive to the end of the record. |
10704 |
In general, the ideal record size depends on the size of the |
10705 |
inter-record gaps on the tape you are using, and the average size of the |
10706 |
files you are archiving. @xref{create}, for information on |
10707 |
writing archives. |
10708 |
|
10709 |
@FIXME{Need example of using a cartridge with blocking factor=126 or more.} |
10710 |
|
10711 |
Archives with blocking factors larger than 20 cannot be read |
10712 |
by very old versions of @command{tar}, or by some newer versions |
10713 |
of @command{tar} running on old machines with small address spaces. |
10714 |
With @GNUTAR{}, the blocking factor of an archive is limited |
10715 |
only by the maximum record size of the device containing the archive, |
10716 |
or by the amount of available virtual memory. |
10717 |
|
10718 |
Also, on some systems, not using adequate blocking factors, as sometimes |
10719 |
imposed by the device drivers, may yield unexpected diagnostics. For |
10720 |
example, this has been reported: |
10721 |
|
10722 |
@smallexample |
10723 |
Cannot write to /dev/dlt: Invalid argument |
10724 |
@end smallexample |
10725 |
|
10726 |
@noindent |
10727 |
In such cases, it sometimes happen that the @command{tar} bundled by |
10728 |
the system is aware of block size idiosyncrasies, while @GNUTAR{} |
10729 |
requires an explicit specification for the block size, |
10730 |
which it cannot guess. This yields some people to consider |
10731 |
@GNUTAR{} is misbehaving, because by comparison, |
10732 |
@cite{the bundle @command{tar} works OK}. Adding @w{@kbd{-b 256}}, |
10733 |
for example, might resolve the problem. |
10734 |
|
10735 |
If you use a non-default blocking factor when you create an archive, you |
10736 |
must specify the same blocking factor when you modify that archive. Some |
10737 |
archive devices will also require you to specify the blocking factor when |
10738 |
reading that archive, however this is not typically the case. Usually, you |
10739 |
can use @option{--list} (@option{-t}) without specifying a blocking factor---@command{tar} |
10740 |
reports a non-default record size and then lists the archive members as |
10741 |
it would normally. To extract files from an archive with a non-standard |
10742 |
blocking factor (particularly if you're not sure what the blocking factor |
10743 |
is), you can usually use the @option{--read-full-records} (@option{-B}) option while |
10744 |
specifying a blocking factor larger then the blocking factor of the archive |
10745 |
(i.e., @samp{tar --extract --read-full-records --blocking-factor=300}). |
10746 |
@xref{list}, for more information on the @option{--list} (@option{-t}) |
10747 |
operation. @xref{Reading}, for a more detailed explanation of that option. |
10748 |
|
10749 |
@table @option |
10750 |
@item --blocking-factor=@var{number} |
10751 |
@itemx -b @var{number} |
10752 |
Specifies the blocking factor of an archive. Can be used with any |
10753 |
operation, but is usually not necessary with @option{--list} (@option{-t}). |
10754 |
@end table |
10755 |
|
10756 |
Device blocking |
10757 |
|
10758 |
@table @option |
10759 |
@item -b @var{blocks} |
10760 |
@itemx --blocking-factor=@var{blocks} |
10761 |
Set record size to @math{@var{blocks}*512} bytes. |
10762 |
|
10763 |
This option is used to specify a @dfn{blocking factor} for the archive. |
10764 |
When reading or writing the archive, @command{tar}, will do reads and writes |
10765 |
of the archive in records of @math{@var{block}*512} bytes. This is true |
10766 |
even when the archive is compressed. Some devices requires that all |
10767 |
write operations be a multiple of a certain size, and so, @command{tar} |
10768 |
pads the archive out to the next record boundary. |
10769 |
|
10770 |
The default blocking factor is set when @command{tar} is compiled, and is |
10771 |
typically 20. Blocking factors larger than 20 cannot be read by very |
10772 |
old versions of @command{tar}, or by some newer versions of @command{tar} |
10773 |
running on old machines with small address spaces. |
10774 |
|
10775 |
With a magnetic tape, larger records give faster throughput and fit |
10776 |
more data on a tape (because there are fewer inter-record gaps). |
10777 |
If the archive is in a disk file or a pipe, you may want to specify |
10778 |
a smaller blocking factor, since a large one will result in a large |
10779 |
number of null bytes at the end of the archive. |
10780 |
|
10781 |
When writing cartridge or other streaming tapes, a much larger |
10782 |
blocking factor (say 126 or more) will greatly increase performance. |
10783 |
However, you must specify the same blocking factor when reading or |
10784 |
updating the archive. |
10785 |
|
10786 |
Apparently, Exabyte drives have a physical block size of 8K bytes. |
10787 |
If we choose our blocksize as a multiple of 8k bytes, then the problem |
10788 |
seems to disappear. Id est, we are using block size of 112 right |
10789 |
now, and we haven't had the problem since we switched@dots{} |
10790 |
|
10791 |
With @GNUTAR{} the blocking factor is limited only |
10792 |
by the maximum record size of the device containing the archive, or by |
10793 |
the amount of available virtual memory. |
10794 |
|
10795 |
However, deblocking or reblocking is virtually avoided in a special |
10796 |
case which often occurs in practice, but which requires all the |
10797 |
following conditions to be simultaneously true: |
10798 |
@itemize @bullet |
10799 |
@item |
10800 |
the archive is subject to a compression option, |
10801 |
@item |
10802 |
the archive is not handled through standard input or output, nor |
10803 |
redirected nor piped, |
10804 |
@item |
10805 |
the archive is directly handled to a local disk, instead of any special |
10806 |
device, |
10807 |
@item |
10808 |
@option{--blocking-factor} is not explicitly specified on the @command{tar} |
10809 |
invocation. |
10810 |
@end itemize |
10811 |
|
10812 |
If the output goes directly to a local disk, and not through |
10813 |
stdout, then the last write is not extended to a full record size. |
10814 |
Otherwise, reblocking occurs. Here are a few other remarks on this |
10815 |
topic: |
10816 |
|
10817 |
@itemize @bullet |
10818 |
|
10819 |
@item |
10820 |
@command{gzip} will complain about trailing garbage if asked to |
10821 |
uncompress a compressed archive on tape, there is an option to turn |
10822 |
the message off, but it breaks the regularity of simply having to use |
10823 |
@samp{@var{prog} -d} for decompression. It would be nice if gzip was |
10824 |
silently ignoring any number of trailing zeros. I'll ask Jean-loup |
10825 |
Gailly, by sending a copy of this message to him. |
10826 |
|
10827 |
@item |
10828 |
@command{compress} does not show this problem, but as Jean-loup pointed |
10829 |
out to Michael, @samp{compress -d} silently adds garbage after |
10830 |
the result of decompression, which tar ignores because it already |
10831 |
recognized its end-of-file indicator. So this bug may be safely |
10832 |
ignored. |
10833 |
|
10834 |
@item |
10835 |
@samp{gzip -d -q} will be silent about the trailing zeros indeed, |
10836 |
but will still return an exit status of 2 which tar reports in turn. |
10837 |
@command{tar} might ignore the exit status returned, but I hate doing |
10838 |
that, as it weakens the protection @command{tar} offers users against |
10839 |
other possible problems at decompression time. If @command{gzip} was |
10840 |
silently skipping trailing zeros @emph{and} also avoiding setting the |
10841 |
exit status in this innocuous case, that would solve this situation. |
10842 |
|
10843 |
@item |
10844 |
@command{tar} should become more solid at not stopping to read a pipe at |
10845 |
the first null block encountered. This inelegantly breaks the pipe. |
10846 |
@command{tar} should rather drain the pipe out before exiting itself. |
10847 |
@end itemize |
10848 |
|
10849 |
@xopindex{ignore-zeros, short description} |
10850 |
@item -i |
10851 |
@itemx --ignore-zeros |
10852 |
Ignore blocks of zeros in archive (means EOF). |
10853 |
|
10854 |
The @option{--ignore-zeros} (@option{-i}) option causes @command{tar} to ignore blocks |
10855 |
of zeros in the archive. Normally a block of zeros indicates the |
10856 |
end of the archive, but when reading a damaged archive, or one which |
10857 |
was created by concatenating several archives together, this option |
10858 |
allows @command{tar} to read the entire archive. This option is not on |
10859 |
by default because many versions of @command{tar} write garbage after |
10860 |
the zeroed blocks. |
10861 |
|
10862 |
Note that this option causes @command{tar} to read to the end of the |
10863 |
archive file, which may sometimes avoid problems when multiple files |
10864 |
are stored on a single physical tape. |
10865 |
|
10866 |
@xopindex{read-full-records, short description} |
10867 |
@item -B |
10868 |
@itemx --read-full-records |
10869 |
Reblock as we read (for reading 4.2@acronym{BSD} pipes). |
10870 |
|
10871 |
If @option{--read-full-records} is used, @command{tar} |
10872 |
will not panic if an attempt to read a record from the archive does |
10873 |
not return a full record. Instead, @command{tar} will keep reading |
10874 |
until it has obtained a full |
10875 |
record. |
10876 |
|
10877 |
This option is turned on by default when @command{tar} is reading |
10878 |
an archive from standard input, or from a remote machine. This is |
10879 |
because on @acronym{BSD} Unix systems, a read of a pipe will return however |
10880 |
much happens to be in the pipe, even if it is less than @command{tar} |
10881 |
requested. If this option was not used, @command{tar} would fail as |
10882 |
soon as it read an incomplete record from the pipe. |
10883 |
|
10884 |
This option is also useful with the commands for updating an archive. |
10885 |
|
10886 |
@end table |
10887 |
|
10888 |
Tape blocking |
10889 |
|
10890 |
@FIXME{Appropriate options should be moved here from elsewhere.} |
10891 |
|
10892 |
@cindex blocking factor |
10893 |
@cindex tape blocking |
10894 |
|
10895 |
When handling various tapes or cartridges, you have to take care of |
10896 |
selecting a proper blocking, that is, the number of disk blocks you |
10897 |
put together as a single tape block on the tape, without intervening |
10898 |
tape gaps. A @dfn{tape gap} is a small landing area on the tape |
10899 |
with no information on it, used for decelerating the tape to a |
10900 |
full stop, and for later regaining the reading or writing speed. |
10901 |
When the tape driver starts reading a record, the record has to |
10902 |
be read whole without stopping, as a tape gap is needed to stop the |
10903 |
tape motion without losing information. |
10904 |
|
10905 |
@cindex Exabyte blocking |
10906 |
@cindex DAT blocking |
10907 |
Using higher blocking (putting more disk blocks per tape block) will use |
10908 |
the tape more efficiently as there will be less tape gaps. But reading |
10909 |
such tapes may be more difficult for the system, as more memory will be |
10910 |
required to receive at once the whole record. Further, if there is a |
10911 |
reading error on a huge record, this is less likely that the system will |
10912 |
succeed in recovering the information. So, blocking should not be too |
10913 |
low, nor it should be too high. @command{tar} uses by default a blocking of |
10914 |
20 for historical reasons, and it does not really matter when reading or |
10915 |
writing to disk. Current tape technology would easily accommodate higher |
10916 |
blockings. Sun recommends a blocking of 126 for Exabytes and 96 for DATs. |
10917 |
We were told that for some DLT drives, the blocking should be a multiple |
10918 |
of 4Kb, preferably 64Kb (@w{@kbd{-b 128}}) or 256 for decent performance. |
10919 |
Other manufacturers may use different recommendations for the same tapes. |
10920 |
This might also depends of the buffering techniques used inside modern |
10921 |
tape controllers. Some imposes a minimum blocking, or a maximum blocking. |
10922 |
Others request blocking to be some exponent of two. |
10923 |
|
10924 |
So, there is no fixed rule for blocking. But blocking at read time |
10925 |
should ideally be the same as blocking used at write time. At one place |
10926 |
I know, with a wide variety of equipment, they found it best to use a |
10927 |
blocking of 32 to guarantee that their tapes are fully interchangeable. |
10928 |
|
10929 |
I was also told that, for recycled tapes, prior erasure (by the same |
10930 |
drive unit that will be used to create the archives) sometimes lowers |
10931 |
the error rates observed at rewriting time. |
10932 |
|
10933 |
I might also use @option{--number-blocks} instead of |
10934 |
@option{--block-number}, so @option{--block} will then expand to |
10935 |
@option{--blocking-factor} unambiguously. |
10936 |
|
10937 |
@node Many |
10938 |
@section Many Archives on One Tape |
10939 |
|
10940 |
@FIXME{Appropriate options should be moved here from elsewhere.} |
10941 |
|
10942 |
@findex ntape @r{device} |
10943 |
Most tape devices have two entries in the @file{/dev} directory, or |
10944 |
entries that come in pairs, which differ only in the minor number for |
10945 |
this device. Let's take for example @file{/dev/tape}, which often |
10946 |
points to the only or usual tape device of a given system. There might |
10947 |
be a corresponding @file{/dev/nrtape} or @file{/dev/ntape}. The simpler |
10948 |
name is the @emph{rewinding} version of the device, while the name |
10949 |
having @samp{nr} in it is the @emph{no rewinding} version of the same |
10950 |
device. |
10951 |
|
10952 |
A rewinding tape device will bring back the tape to its beginning point |
10953 |
automatically when this device is opened or closed. Since @command{tar} |
10954 |
opens the archive file before using it and closes it afterwards, this |
10955 |
means that a simple: |
10956 |
|
10957 |
@smallexample |
10958 |
$ @kbd{tar cf /dev/tape @var{directory}} |
10959 |
@end smallexample |
10960 |
|
10961 |
@noindent |
10962 |
will reposition the tape to its beginning both prior and after saving |
10963 |
@var{directory} contents to it, thus erasing prior tape contents and |
10964 |
making it so that any subsequent write operation will destroy what has |
10965 |
just been saved. |
10966 |
|
10967 |
@cindex tape positioning |
10968 |
So, a rewinding device is normally meant to hold one and only one file. |
10969 |
If you want to put more than one @command{tar} archive on a given tape, you |
10970 |
will need to avoid using the rewinding version of the tape device. You |
10971 |
will also have to pay special attention to tape positioning. Errors in |
10972 |
positioning may overwrite the valuable data already on your tape. Many |
10973 |
people, burnt by past experiences, will only use rewinding devices and |
10974 |
limit themselves to one file per tape, precisely to avoid the risk of |
10975 |
such errors. Be fully aware that writing at the wrong position on a |
10976 |
tape loses all information past this point and most probably until the |
10977 |
end of the tape, and this destroyed information @emph{cannot} be |
10978 |
recovered. |
10979 |
|
10980 |
To save @var{directory-1} as a first archive at the beginning of a |
10981 |
tape, and leave that tape ready for a second archive, you should use: |
10982 |
|
10983 |
@smallexample |
10984 |
$ @kbd{mt -f /dev/nrtape rewind} |
10985 |
$ @kbd{tar cf /dev/nrtape @var{directory-1}} |
10986 |
@end smallexample |
10987 |
|
10988 |
@cindex tape marks |
10989 |
@dfn{Tape marks} are special magnetic patterns written on the tape |
10990 |
media, which are later recognizable by the reading hardware. These |
10991 |
marks are used after each file, when there are many on a single tape. |
10992 |
An empty file (that is to say, two tape marks in a row) signal the |
10993 |
logical end of the tape, after which no file exist. Usually, |
10994 |
non-rewinding tape device drivers will react to the close request issued |
10995 |
by @command{tar} by first writing two tape marks after your archive, and by |
10996 |
backspacing over one of these. So, if you remove the tape at that time |
10997 |
from the tape drive, it is properly terminated. But if you write |
10998 |
another file at the current position, the second tape mark will be |
10999 |
erased by the new information, leaving only one tape mark between files. |
11000 |
|
11001 |
So, you may now save @var{directory-2} as a second archive after the |
11002 |
first on the same tape by issuing the command: |
11003 |
|
11004 |
@smallexample |
11005 |
$ @kbd{tar cf /dev/nrtape @var{directory-2}} |
11006 |
@end smallexample |
11007 |
|
11008 |
@noindent |
11009 |
and so on for all the archives you want to put on the same tape. |
11010 |
|
11011 |
Another usual case is that you do not write all the archives the same |
11012 |
day, and you need to remove and store the tape between two archive |
11013 |
sessions. In general, you must remember how many files are already |
11014 |
saved on your tape. Suppose your tape already has 16 files on it, and |
11015 |
that you are ready to write the 17th. You have to take care of skipping |
11016 |
the first 16 tape marks before saving @var{directory-17}, say, by using |
11017 |
these commands: |
11018 |
|
11019 |
@smallexample |
11020 |
$ @kbd{mt -f /dev/nrtape rewind} |
11021 |
$ @kbd{mt -f /dev/nrtape fsf 16} |
11022 |
$ @kbd{tar cf /dev/nrtape @var{directory-17}} |
11023 |
@end smallexample |
11024 |
|
11025 |
In all the previous examples, we put aside blocking considerations, but |
11026 |
you should do the proper things for that as well. @xref{Blocking}. |
11027 |
|
11028 |
@menu |
11029 |
* Tape Positioning:: Tape Positions and Tape Marks |
11030 |
* mt:: The @command{mt} Utility |
11031 |
@end menu |
11032 |
|
11033 |
@node Tape Positioning |
11034 |
@subsection Tape Positions and Tape Marks |
11035 |
@UNREVISED |
11036 |
|
11037 |
Just as archives can store more than one file from the file system, |
11038 |
tapes can store more than one archive file. To keep track of where |
11039 |
archive files (or any other type of file stored on tape) begin and |
11040 |
end, tape archive devices write magnetic @dfn{tape marks} on the |
11041 |
archive media. Tape drives write one tape mark between files, |
11042 |
two at the end of all the file entries. |
11043 |
|
11044 |
If you think of data as a series of records "rrrr"'s, and tape marks as |
11045 |
"*"'s, a tape might look like the following: |
11046 |
|
11047 |
@smallexample |
11048 |
rrrr*rrrrrr*rrrrr*rr*rrrrr**------------------------- |
11049 |
@end smallexample |
11050 |
|
11051 |
Tape devices read and write tapes using a read/write @dfn{tape |
11052 |
head}---a physical part of the device which can only access one |
11053 |
point on the tape at a time. When you use @command{tar} to read or |
11054 |
write archive data from a tape device, the device will begin reading |
11055 |
or writing from wherever on the tape the tape head happens to be, |
11056 |
regardless of which archive or what part of the archive the tape |
11057 |
head is on. Before writing an archive, you should make sure that no |
11058 |
data on the tape will be overwritten (unless it is no longer needed). |
11059 |
Before reading an archive, you should make sure the tape head is at |
11060 |
the beginning of the archive you want to read. You can do it manually |
11061 |
via @code{mt} utility (@pxref{mt}). The @code{restore} script does |
11062 |
that automatically (@pxref{Scripted Restoration}). |
11063 |
|
11064 |
If you want to add new archive file entries to a tape, you should |
11065 |
advance the tape to the end of the existing file entries, backspace |
11066 |
over the last tape mark, and write the new archive file. If you were |
11067 |
to add two archives to the example above, the tape might look like the |
11068 |
following: |
11069 |
|
11070 |
@smallexample |
11071 |
rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**---------------- |
11072 |
@end smallexample |
11073 |
|
11074 |
@node mt |
11075 |
@subsection The @command{mt} Utility |
11076 |
@UNREVISED |
11077 |
|
11078 |
@FIXME{Is it true that this only works on non-block devices? |
11079 |
should explain the difference, (fixed or variable).} |
11080 |
@xref{Blocking Factor}. |
11081 |
|
11082 |
You can use the @command{mt} utility to advance or rewind a tape past a |
11083 |
specified number of archive files on the tape. This will allow you |
11084 |
to move to the beginning of an archive before extracting or reading |
11085 |
it, or to the end of all the archives before writing a new one. |
11086 |
@FIXME{Why isn't there an "advance 'til you find two tape marks |
11087 |
together"?} |
11088 |
|
11089 |
The syntax of the @command{mt} command is: |
11090 |
|
11091 |
@smallexample |
11092 |
@kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]} |
11093 |
@end smallexample |
11094 |
|
11095 |
where @var{tapename} is the name of the tape device, @var{number} is |
11096 |
the number of times an operation is performed (with a default of one), |
11097 |
and @var{operation} is one of the following: |
11098 |
|
11099 |
@FIXME{is there any use for record operations?} |
11100 |
|
11101 |
@table @option |
11102 |
@item eof |
11103 |
@itemx weof |
11104 |
Writes @var{number} tape marks at the current position on the tape. |
11105 |
|
11106 |
@item fsf |
11107 |
Moves tape position forward @var{number} files. |
11108 |
|
11109 |
@item bsf |
11110 |
Moves tape position back @var{number} files. |
11111 |
|
11112 |
@item rewind |
11113 |
Rewinds the tape. (Ignores @var{number}.) |
11114 |
|
11115 |
@item offline |
11116 |
@itemx rewoff1 |
11117 |
Rewinds the tape and takes the tape device off-line. (Ignores @var{number}.) |
11118 |
|
11119 |
@item status |
11120 |
Prints status information about the tape unit. |
11121 |
|
11122 |
@end table |
11123 |
|
11124 |
If you don't specify a @var{tapename}, @command{mt} uses the environment |
11125 |
variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use |
11126 |
the default device specified in your @file{sys/mtio.h} file |
11127 |
(@code{DEFTAPE} variable). If this is not defined, the program will |
11128 |
display a descriptive error message and exit with code 1. |
11129 |
|
11130 |
@command{mt} returns a 0 exit status when the operation(s) were |
11131 |
successful, 1 if the command was unrecognized, and 2 if an operation |
11132 |
failed. |
11133 |
|
11134 |
@node Using Multiple Tapes |
11135 |
@section Using Multiple Tapes |
11136 |
|
11137 |
Often you might want to write a large archive, one larger than will fit |
11138 |
on the actual tape you are using. In such a case, you can run multiple |
11139 |
@command{tar} commands, but this can be inconvenient, particularly if you |
11140 |
are using options like @option{--exclude=@var{pattern}} or dumping entire file systems. |
11141 |
Therefore, @command{tar} provides a special mode for creating |
11142 |
multi-volume archives. |
11143 |
|
11144 |
@dfn{Multi-volume} archive is a single @command{tar} archive, stored |
11145 |
on several media volumes of fixed size. Although in this section we will |
11146 |
often call @samp{volume} a @dfn{tape}, there is absolutely no |
11147 |
requirement for multi-volume archives to be stored on tapes. Instead, |
11148 |
they can use whatever media type the user finds convenient, they can |
11149 |
even be located on files. |
11150 |
|
11151 |
When creating a multi-volume archive, @GNUTAR{} continues to fill |
11152 |
current volume until it runs out of space, then it switches to |
11153 |
next volume (usually the operator is queried to replace the tape on |
11154 |
this point), and continues working on the new volume. This operation |
11155 |
continues until all requested files are dumped. If @GNUTAR{} detects |
11156 |
end of media while dumping a file, such a file is archived in split |
11157 |
form. Some very big files can even be split across several volumes. |
11158 |
|
11159 |
Each volume is itself a valid @GNUTAR{} archive, so it can be read |
11160 |
without any special options. Consequently any file member residing |
11161 |
entirely on one volume can be extracted or otherwise operated upon |
11162 |
without needing the other volume. Sure enough, to extract a split |
11163 |
member you would need all volumes its parts reside on. |
11164 |
|
11165 |
Multi-volume archives suffer from several limitations. In particular, |
11166 |
they cannot be compressed. |
11167 |
|
11168 |
@GNUTAR{} is able to create multi-volume archives of two formats |
11169 |
(@pxref{Formats}): @samp{GNU} and @samp{POSIX}. |
11170 |
|
11171 |
@menu |
11172 |
* Multi-Volume Archives:: Archives Longer than One Tape or Disk |
11173 |
* Tape Files:: Tape Files |
11174 |
* Tarcat:: Concatenate Volumes into a Single Archive |
11175 |
|
11176 |
@end menu |
11177 |
|
11178 |
@node Multi-Volume Archives |
11179 |
@subsection Archives Longer than One Tape or Disk |
11180 |
@cindex Multi-volume archives |
11181 |
|
11182 |
@opindex multi-volume |
11183 |
To create an archive that is larger than will fit on a single unit of |
11184 |
the media, use the @option{--multi-volume} (@option{-M}) option in conjunction with |
11185 |
the @option{--create} option (@pxref{create}). A @dfn{multi-volume} |
11186 |
archive can be manipulated like any other archive (provided the |
11187 |
@option{--multi-volume} option is specified), but is stored on more |
11188 |
than one tape or file. |
11189 |
|
11190 |
When you specify @option{--multi-volume}, @command{tar} does not report an |
11191 |
error when it comes to the end of an archive volume (when reading), or |
11192 |
the end of the media (when writing). Instead, it prompts you to load |
11193 |
a new storage volume. If the archive is on a magnetic tape, you |
11194 |
should change tapes when you see the prompt; if the archive is on a |
11195 |
floppy disk, you should change disks; etc. |
11196 |
|
11197 |
@table @option |
11198 |
@item --multi-volume |
11199 |
@itemx -M |
11200 |
Creates a multi-volume archive, when used in conjunction with |
11201 |
@option{--create} (@option{-c}). To perform any other operation on a multi-volume |
11202 |
archive, specify @option{--multi-volume} in conjunction with that |
11203 |
operation. |
11204 |
For example: |
11205 |
|
11206 |
@smallexample |
11207 |
$ @kbd{tar --create --multi-volume --file=/dev/tape @var{files}} |
11208 |
@end smallexample |
11209 |
@end table |
11210 |
|
11211 |
The method @command{tar} uses to detect end of tape is not perfect, and |
11212 |
fails on some operating systems or on some devices. If @command{tar} |
11213 |
cannot detect the end of the tape itself, you can use |
11214 |
@option{--tape-length} option to inform it about the capacity of the |
11215 |
tape: |
11216 |
|
11217 |
@anchor{tape-length} |
11218 |
@table @option |
11219 |
@opindex tape-length |
11220 |
@item --tape-length=@var{size}[@var{suf}] |
11221 |
@itemx -L @var{size}[@var{suf}] |
11222 |
Set maximum length of a volume. The @var{suf}, if given, specifies |
11223 |
units in which @var{size} is expressed, e.g. @samp{2M} mean 2 |
11224 |
megabytes (@pxref{size-suffixes}, for a list of allowed size |
11225 |
suffixes). Without @var{suf}, units of 1024 bytes (kilobyte) are |
11226 |
assumed. |
11227 |
|
11228 |
This option selects @option{--multi-volume} automatically. For example: |
11229 |
|
11230 |
@smallexample |
11231 |
$ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}} |
11232 |
@end smallexample |
11233 |
|
11234 |
@noindent |
11235 |
or, which is equivalent: |
11236 |
|
11237 |
@smallexample |
11238 |
$ @kbd{tar --create --tape-length=4G --file=/dev/tape @var{files}} |
11239 |
@end smallexample |
11240 |
@end table |
11241 |
|
11242 |
@anchor{change volume prompt} |
11243 |
When @GNUTAR{} comes to the end of a storage media, it asks you to |
11244 |
change the volume. The built-in prompt for POSIX locale |
11245 |
is@footnote{If you run @GNUTAR{} under a different locale, the |
11246 |
translation to the locale's language will be used.}: |
11247 |
|
11248 |
@smallexample |
11249 |
Prepare volume #@var{n} for `@var{archive}' and hit return: |
11250 |
@end smallexample |
11251 |
|
11252 |
@noindent |
11253 |
where @var{n} is the ordinal number of the volume to be created and |
11254 |
@var{archive} is archive file or device name. |
11255 |
|
11256 |
When prompting for a new tape, @command{tar} accepts any of the following |
11257 |
responses: |
11258 |
|
11259 |
@table @kbd |
11260 |
@item ? |
11261 |
Request @command{tar} to explain possible responses. |
11262 |
@item q |
11263 |
Request @command{tar} to exit immediately. |
11264 |
@item n @var{file-name} |
11265 |
Request @command{tar} to write the next volume on the file @var{file-name}. |
11266 |
@item ! |
11267 |
Request @command{tar} to run a subshell. This option can be disabled |
11268 |
by giving @option{--restrict} command line option to |
11269 |
@command{tar}@footnote{@xref{--restrict}, for more information about |
11270 |
this option.}. |
11271 |
@item y |
11272 |
Request @command{tar} to begin writing the next volume. |
11273 |
@end table |
11274 |
|
11275 |
(You should only type @samp{y} after you have changed the tape; |
11276 |
otherwise @command{tar} will write over the volume it just finished.) |
11277 |
|
11278 |
@cindex Volume number file |
11279 |
@cindex volno file |
11280 |
@anchor{volno-file} |
11281 |
@opindex volno-file |
11282 |
The volume number used by @command{tar} in its tape-changing prompt |
11283 |
can be changed; if you give the |
11284 |
@option{--volno-file=@var{file-of-number}} option, then |
11285 |
@var{file-of-number} should be an non-existing file to be created, or |
11286 |
else, a file already containing a decimal number. That number will be |
11287 |
used as the volume number of the first volume written. When |
11288 |
@command{tar} is finished, it will rewrite the file with the |
11289 |
now-current volume number. (This does not change the volume number |
11290 |
written on a tape label, as per @ref{label}, it @emph{only} affects |
11291 |
the number used in the prompt.) |
11292 |
|
11293 |
@cindex End-of-archive info script |
11294 |
@cindex Info script |
11295 |
@anchor{info-script} |
11296 |
@opindex info-script |
11297 |
@opindex new-volume-script |
11298 |
If you want more elaborate behavior than this, you can write a special |
11299 |
@dfn{new volume script}, that will be responsible for changing the |
11300 |
volume, and instruct @command{tar} to use it instead of its normal |
11301 |
prompting procedure: |
11302 |
|
11303 |
@table @option |
11304 |
@item --info-script=@var{script-name} |
11305 |
@itemx --new-volume-script=@var{script-name} |
11306 |
@itemx -F @var{script-name} |
11307 |
Specify the full name of the volume script to use. The script can be |
11308 |
used to eject cassettes, or to broadcast messages such as |
11309 |
@samp{Someone please come change my tape} when performing unattended |
11310 |
backups. |
11311 |
@end table |
11312 |
|
11313 |
The @var{script-name} is executed without any command line |
11314 |
arguments. It inherits @command{tar}'s shell environment. |
11315 |
Additional data is passed to it via the following |
11316 |
environment variables: |
11317 |
|
11318 |
@table @env |
11319 |
@vrindex TAR_VERSION, info script environment variable |
11320 |
@item TAR_VERSION |
11321 |
@GNUTAR{} version number. |
11322 |
|
11323 |
@vrindex TAR_ARCHIVE, info script environment variable |
11324 |
@item TAR_ARCHIVE |
11325 |
The name of the archive @command{tar} is processing. |
11326 |
|
11327 |
@vrindex TAR_BLOCKING_FACTOR, info script environment variable |
11328 |
@item TAR_BLOCKING_FACTOR |
11329 |
Current blocking factor (@pxref{Blocking}). |
11330 |
|
11331 |
@vrindex TAR_VOLUME, info script environment variable |
11332 |
@item TAR_VOLUME |
11333 |
Ordinal number of the volume @command{tar} is about to start. |
11334 |
|
11335 |
@vrindex TAR_SUBCOMMAND, info script environment variable |
11336 |
@item TAR_SUBCOMMAND |
11337 |
A short option describing the operation @command{tar} is executing. |
11338 |
@xref{Operations}, for a complete list of subcommand options. |
11339 |
|
11340 |
@vrindex TAR_FORMAT, info script environment variable |
11341 |
@item TAR_FORMAT |
11342 |
Format of the archive being processed. @xref{Formats}, for a complete |
11343 |
list of archive format names. |
11344 |
|
11345 |
@vrindex TAR_FD, info script environment variable |
11346 |
@item TAR_FD |
11347 |
File descriptor which can be used to communicate the new volume |
11348 |
name to @command{tar}. |
11349 |
@end table |
11350 |
|
11351 |
The volume script can instruct @command{tar} to use new archive name, |
11352 |
by writing in to file descriptor @env{$TAR_FD} (see below for an example). |
11353 |
|
11354 |
If the info script fails, @command{tar} exits; otherwise, it begins |
11355 |
writing the next volume. |
11356 |
|
11357 |
If you want @command{tar} to cycle through a series of files or tape |
11358 |
drives, there are three approaches to choose from. First of all, you |
11359 |
can give @command{tar} multiple @option{--file} options. In this case |
11360 |
the specified files will be used, in sequence, as the successive |
11361 |
volumes of the archive. Only when the first one in the sequence needs |
11362 |
to be used again will @command{tar} prompt for a tape change (or run |
11363 |
the info script). For example, suppose someone has two tape drives on |
11364 |
a system named @file{/dev/tape0} and @file{/dev/tape1}. For having |
11365 |
@GNUTAR{} to switch to the second drive when it needs to write the |
11366 |
second tape, and then back to the first tape, etc., just do either of: |
11367 |
|
11368 |
@smallexample |
11369 |
$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}} |
11370 |
$ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}} |
11371 |
@end smallexample |
11372 |
|
11373 |
The second method is to use the @samp{n} response to the tape-change |
11374 |
prompt. |
11375 |
|
11376 |
Finally, the most flexible approach is to use a volume script, that |
11377 |
writes new archive name to the file descriptor @env{$TAR_FD}. For example, the |
11378 |
following volume script will create a series of archive files, named |
11379 |
@file{@var{archive}-@var{vol}}, where @var{archive} is the name of the |
11380 |
archive being created (as given by @option{--file} option) and |
11381 |
@var{vol} is the ordinal number of the archive being created: |
11382 |
|
11383 |
@smallexample |
11384 |
@group |
11385 |
#! /bin/sh |
11386 |
echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE. |
11387 |
|
11388 |
name=`expr $TAR_ARCHIVE : '\(.*\)-.*'` |
11389 |
case $TAR_SUBCOMMAND in |
11390 |
-c) ;; |
11391 |
-d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1 |
11392 |
;; |
11393 |
*) exit 1 |
11394 |
esac |
11395 |
|
11396 |
echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&$TAR_FD |
11397 |
@end group |
11398 |
@end smallexample |
11399 |
|
11400 |
The same script can be used while listing, comparing or extracting |
11401 |
from the created archive. For example: |
11402 |
|
11403 |
@smallexample |
11404 |
@group |
11405 |
# @r{Create a multi-volume archive:} |
11406 |
$ @kbd{tar -c -L1024 -f archive.tar -F new-volume .} |
11407 |
# @r{Extract from the created archive:} |
11408 |
$ @kbd{tar -x -f archive.tar -F new-volume .} |
11409 |
@end group |
11410 |
@end smallexample |
11411 |
|
11412 |
@noindent |
11413 |
Notice, that the first command had to use @option{-L} option, since |
11414 |
otherwise @GNUTAR{} will end up writing everything to file |
11415 |
@file{archive.tar}. |
11416 |
|
11417 |
You can read each individual volume of a multi-volume archive as if it |
11418 |
were an archive by itself. For example, to list the contents of one |
11419 |
volume, use @option{--list}, without @option{--multi-volume} specified. |
11420 |
To extract an archive member from one volume (assuming it is described |
11421 |
that volume), use @option{--extract}, again without |
11422 |
@option{--multi-volume}. |
11423 |
|
11424 |
If an archive member is split across volumes (i.e., its entry begins on |
11425 |
one volume of the media and ends on another), you need to specify |
11426 |
@option{--multi-volume} to extract it successfully. In this case, you |
11427 |
should load the volume where the archive member starts, and use |
11428 |
@samp{tar --extract --multi-volume}---@command{tar} will prompt for later |
11429 |
volumes as it needs them. @xref{extracting archives}, for more |
11430 |
information about extracting archives. |
11431 |
|
11432 |
Multi-volume archives can be modified like any other archive. To add |
11433 |
files to a multi-volume archive, you need to only mount the last |
11434 |
volume of the archive media (and new volumes, if needed). For all |
11435 |
other operations, you need to use the entire archive. |
11436 |
|
11437 |
If a multi-volume archive was labeled using |
11438 |
@option{--label=@var{archive-label}} (@pxref{label}) when it was |
11439 |
created, @command{tar} will not automatically label volumes which are |
11440 |
added later. To label subsequent volumes, specify |
11441 |
@option{--label=@var{archive-label}} again in conjunction with the |
11442 |
@option{--append}, @option{--update} or @option{--concatenate} operation. |
11443 |
|
11444 |
Notice that multi-volume support is a GNU extension and the archives |
11445 |
created in this mode should be read only using @GNUTAR{}. If you |
11446 |
absolutely have to process such archives using a third-party @command{tar} |
11447 |
implementation, read @ref{Split Recovery}. |
11448 |
|
11449 |
@node Tape Files |
11450 |
@subsection Tape Files |
11451 |
@cindex labeling archives |
11452 |
@opindex label |
11453 |
@UNREVISED |
11454 |
|
11455 |
To give the archive a name which will be recorded in it, use the |
11456 |
@option{--label=@var{volume-label}} (@option{-V @var{volume-label}}) |
11457 |
option. This will write a special block identifying |
11458 |
@var{volume-label} as the name of the archive to the front of the |
11459 |
archive which will be displayed when the archive is listed with |
11460 |
@option{--list}. If you are creating a multi-volume archive with |
11461 |
@option{--multi-volume} (@pxref{Using Multiple Tapes}), then the |
11462 |
volume label will have @samp{Volume @var{nnn}} appended to the name |
11463 |
you give, where @var{nnn} is the number of the volume of the archive. |
11464 |
If you use the @option{--label=@var{volume-label}} option when |
11465 |
reading an archive, it checks to make sure the label on the tape |
11466 |
matches the one you gave. @xref{label}. |
11467 |
|
11468 |
When @command{tar} writes an archive to tape, it creates a single |
11469 |
tape file. If multiple archives are written to the same tape, one |
11470 |
after the other, they each get written as separate tape files. When |
11471 |
extracting, it is necessary to position the tape at the right place |
11472 |
before running @command{tar}. To do this, use the @command{mt} command. |
11473 |
For more information on the @command{mt} command and on the organization |
11474 |
of tapes into a sequence of tape files, see @ref{mt}. |
11475 |
|
11476 |
People seem to often do: |
11477 |
|
11478 |
@smallexample |
11479 |
@kbd{--label="@var{some-prefix} `date +@var{some-format}`"} |
11480 |
@end smallexample |
11481 |
|
11482 |
or such, for pushing a common date in all volumes or an archive set. |
11483 |
|
11484 |
@node Tarcat |
11485 |
@subsection Concatenate Volumes into a Single Archive |
11486 |
|
11487 |
@pindex tarcat |
11488 |
Sometimes it is necessary to convert existing @GNUTAR{} multi-volume |
11489 |
archive to a single @command{tar} archive. Simply concatenating all |
11490 |
volumes into one will not work, since each volume carries an additional |
11491 |
information at the beginning. @GNUTAR{} is shipped with the shell |
11492 |
script @command{tarcat} designed for this purpose. |
11493 |
|
11494 |
The script takes a list of files comprising a multi-volume archive |
11495 |
and creates the resulting archive at the standard output. For example: |
11496 |
|
11497 |
@smallexample |
11498 |
@kbd{tarcat vol.1 vol.2 vol.3 | tar tf -} |
11499 |
@end smallexample |
11500 |
|
11501 |
The script implements a simple heuristics to determine the format of |
11502 |
the first volume file and to decide how to process the rest of the |
11503 |
files. However, it makes no attempt to verify whether the files are |
11504 |
given in order or even if they are valid @command{tar} archives. |
11505 |
It uses @command{dd} and does not filter its standard error, so you |
11506 |
will usually see lots of spurious messages. |
11507 |
|
11508 |
@FIXME{The script is not installed. Should we install it?} |
11509 |
|
11510 |
@node label |
11511 |
@section Including a Label in the Archive |
11512 |
@cindex Labeling an archive |
11513 |
@cindex Labels on the archive media |
11514 |
@cindex Labeling multi-volume archives |
11515 |
|
11516 |
@opindex label |
11517 |
To avoid problems caused by misplaced paper labels on the archive |
11518 |
media, you can include a @dfn{label} entry --- an archive member which |
11519 |
contains the name of the archive --- in the archive itself. Use the |
11520 |
@option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) |
11521 |
option@footnote{Until version 1.10, that option was called |
11522 |
@option{--volume}, but is not available under that name anymore.} in |
11523 |
conjunction with the @option{--create} operation to include a label |
11524 |
entry in the archive as it is being created. |
11525 |
|
11526 |
@table @option |
11527 |
@item --label=@var{archive-label} |
11528 |
@itemx -V @var{archive-label} |
11529 |
Includes an @dfn{archive-label} at the beginning of the archive when |
11530 |
the archive is being created, when used in conjunction with the |
11531 |
@option{--create} operation. Checks to make sure the archive label |
11532 |
matches the one specified (when used in conjunction with any other |
11533 |
operation). |
11534 |
@end table |
11535 |
|
11536 |
If you create an archive using both |
11537 |
@option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) |
11538 |
and @option{--multi-volume} (@option{-M}), each volume of the archive |
11539 |
will have an archive label of the form @samp{@var{archive-label} |
11540 |
Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the |
11541 |
next, and so on. @xref{Using Multiple Tapes}, for information on |
11542 |
creating multiple volume archives. |
11543 |
|
11544 |
@cindex Volume label, listing |
11545 |
@cindex Listing volume label |
11546 |
The volume label will be displayed by @option{--list} along with |
11547 |
the file contents. If verbose display is requested, it will also be |
11548 |
explicitly marked as in the example below: |
11549 |
|
11550 |
@smallexample |
11551 |
@group |
11552 |
$ @kbd{tar --verbose --list --file=iamanarchive} |
11553 |
V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header-- |
11554 |
-rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename |
11555 |
@end group |
11556 |
@end smallexample |
11557 |
|
11558 |
@opindex test-label |
11559 |
@anchor{--test-label option} |
11560 |
However, @option{--list} option will cause listing entire |
11561 |
contents of the archive, which may be undesirable (for example, if the |
11562 |
archive is stored on a tape). You can request checking only the volume |
11563 |
label by specifying @option{--test-label} option. This option reads only the |
11564 |
first block of an archive, so it can be used with slow storage |
11565 |
devices. For example: |
11566 |
|
11567 |
@smallexample |
11568 |
@group |
11569 |
$ @kbd{tar --test-label --file=iamanarchive} |
11570 |
iamalabel |
11571 |
@end group |
11572 |
@end smallexample |
11573 |
|
11574 |
If @option{--test-label} is used with one or more command line |
11575 |
arguments, @command{tar} compares the volume label with each |
11576 |
argument. It exits with code 0 if a match is found, and with code 1 |
11577 |
otherwise@footnote{Note that @GNUTAR{} versions up to 1.23 indicated |
11578 |
mismatch with an exit code 2 and printed a spurious diagnostics on |
11579 |
stderr.}. No output is displayed, unless you also used the |
11580 |
@option{--verbose} option. For example: |
11581 |
|
11582 |
@smallexample |
11583 |
@group |
11584 |
$ @kbd{tar --test-label --file=iamanarchive 'iamalabel'} |
11585 |
@result{} 0 |
11586 |
$ @kbd{tar --test-label --file=iamanarchive 'alabel'} |
11587 |
@result{} 1 |
11588 |
@end group |
11589 |
@end smallexample |
11590 |
|
11591 |
When used with the @option{--verbose} option, @command{tar} |
11592 |
prints the actual volume label (if any), and a verbose diagnostics in |
11593 |
case of a mismatch: |
11594 |
|
11595 |
@smallexample |
11596 |
@group |
11597 |
$ @kbd{tar --test-label --verbose --file=iamanarchive 'iamalabel'} |
11598 |
iamalabel |
11599 |
@result{} 0 |
11600 |
$ @kbd{tar --test-label --verbose --file=iamanarchive 'alabel'} |
11601 |
iamalabel |
11602 |
tar: Archive label mismatch |
11603 |
@result{} 1 |
11604 |
@end group |
11605 |
@end smallexample |
11606 |
|
11607 |
If you request any operation, other than @option{--create}, along |
11608 |
with using @option{--label} option, @command{tar} will first check if |
11609 |
the archive label matches the one specified and will refuse to proceed |
11610 |
if it does not. Use this as a safety precaution to avoid accidentally |
11611 |
overwriting existing archives. For example, if you wish to add files |
11612 |
to @file{archive}, presumably labeled with string @samp{My volume}, |
11613 |
you will get: |
11614 |
|
11615 |
@smallexample |
11616 |
@group |
11617 |
$ @kbd{tar -rf archive --label 'My volume' .} |
11618 |
tar: Archive not labeled to match `My volume' |
11619 |
@end group |
11620 |
@end smallexample |
11621 |
|
11622 |
@noindent |
11623 |
in case its label does not match. This will work even if |
11624 |
@file{archive} is not labeled at all. |
11625 |
|
11626 |
Similarly, @command{tar} will refuse to list or extract the |
11627 |
archive if its label doesn't match the @var{archive-label} |
11628 |
specified. In those cases, @var{archive-label} argument is interpreted |
11629 |
as a globbing-style pattern which must match the actual magnetic |
11630 |
volume label. @xref{exclude}, for a precise description of how match |
11631 |
is attempted@footnote{Previous versions of @command{tar} used full |
11632 |
regular expression matching, or before that, only exact string |
11633 |
matching, instead of wildcard matchers. We decided for the sake of |
11634 |
simplicity to use a uniform matching device through |
11635 |
@command{tar}.}. If the switch @option{--multi-volume} (@option{-M}) is being used, |
11636 |
the volume label matcher will also suffix @var{archive-label} by |
11637 |
@w{@samp{ Volume [1-9]*}} if the initial match fails, before giving |
11638 |
up. Since the volume numbering is automatically added in labels at |
11639 |
creation time, it sounded logical to equally help the user taking care |
11640 |
of it when the archive is being read. |
11641 |
|
11642 |
You can also use @option{--label} to get a common information on |
11643 |
all tapes of a series. For having this information different in each |
11644 |
series created through a single script used on a regular basis, just |
11645 |
manage to get some date string as part of the label. For example: |
11646 |
|
11647 |
@smallexample |
11648 |
@group |
11649 |
$ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"} |
11650 |
$ @kbd{tar --create --file=/dev/tape --multi-volume \ |
11651 |
--label="Daily backup for `date +%Y-%m-%d`"} |
11652 |
@end group |
11653 |
@end smallexample |
11654 |
|
11655 |
Some more notes about volume labels: |
11656 |
|
11657 |
@itemize @bullet |
11658 |
@item Each label has its own date and time, which corresponds |
11659 |
to the time when @GNUTAR{} initially attempted to write it, |
11660 |
often soon after the operator launches @command{tar} or types the |
11661 |
carriage return telling that the next tape is ready. |
11662 |
|
11663 |
@item Comparing date labels to get an idea of tape throughput is |
11664 |
unreliable. It gives correct results only if the delays for rewinding |
11665 |
tapes and the operator switching them were negligible, which is |
11666 |
usually not the case. |
11667 |
@end itemize |
11668 |
|
11669 |
@node verify |
11670 |
@section Verifying Data as It is Stored |
11671 |
@cindex Verifying a write operation |
11672 |
@cindex Double-checking a write operation |
11673 |
|
11674 |
@table @option |
11675 |
@item -W |
11676 |
@itemx --verify |
11677 |
@opindex verify, short description |
11678 |
Attempt to verify the archive after writing. |
11679 |
@end table |
11680 |
|
11681 |
This option causes @command{tar} to verify the archive after writing it. |
11682 |
Each volume is checked after it is written, and any discrepancies |
11683 |
are recorded on the standard error output. |
11684 |
|
11685 |
Verification requires that the archive be on a back-space-able medium. |
11686 |
This means pipes, some cartridge tape drives, and some other devices |
11687 |
cannot be verified. |
11688 |
|
11689 |
You can insure the accuracy of an archive by comparing files in the |
11690 |
system with archive members. @command{tar} can compare an archive to the |
11691 |
file system as the archive is being written, to verify a write |
11692 |
operation, or can compare a previously written archive, to insure that |
11693 |
it is up to date. |
11694 |
|
11695 |
@xopindex{verify, using with @option{--create}} |
11696 |
@xopindex{create, using with @option{--verify}} |
11697 |
To check for discrepancies in an archive immediately after it is |
11698 |
written, use the @option{--verify} (@option{-W}) option in conjunction with |
11699 |
the @option{--create} operation. When this option is |
11700 |
specified, @command{tar} checks archive members against their counterparts |
11701 |
in the file system, and reports discrepancies on the standard error. |
11702 |
|
11703 |
To verify an archive, you must be able to read it from before the end |
11704 |
of the last written entry. This option is useful for detecting data |
11705 |
errors on some tapes. Archives written to pipes, some cartridge tape |
11706 |
drives, and some other devices cannot be verified. |
11707 |
|
11708 |
One can explicitly compare an already made archive with the file |
11709 |
system by using the @option{--compare} (@option{--diff}, @option{-d}) |
11710 |
option, instead of using the more automatic @option{--verify} option. |
11711 |
@xref{compare}. |
11712 |
|
11713 |
Note that these two options have a slightly different intent. The |
11714 |
@option{--compare} option checks how identical are the logical contents of some |
11715 |
archive with what is on your disks, while the @option{--verify} option is |
11716 |
really for checking if the physical contents agree and if the recording |
11717 |
media itself is of dependable quality. So, for the @option{--verify} |
11718 |
operation, @command{tar} tries to defeat all in-memory cache pertaining to |
11719 |
the archive, while it lets the speed optimization undisturbed for the |
11720 |
@option{--compare} option. If you nevertheless use @option{--compare} for |
11721 |
media verification, you may have to defeat the in-memory cache yourself, |
11722 |
maybe by opening and reclosing the door latch of your recording unit, |
11723 |
forcing some doubt in your operating system about the fact this is really |
11724 |
the same volume as the one just written or read. |
11725 |
|
11726 |
The @option{--verify} option would not be necessary if drivers were indeed |
11727 |
able to detect dependably all write failures. This sometimes require many |
11728 |
magnetic heads, some able to read after the writes occurred. One would |
11729 |
not say that drivers unable to detect all cases are necessarily flawed, |
11730 |
as long as programming is concerned. |
11731 |
|
11732 |
The @option{--verify} (@option{-W}) option will not work in |
11733 |
conjunction with the @option{--multi-volume} (@option{-M}) option or |
11734 |
the @option{--append} (@option{-r}), @option{--update} (@option{-u}) |
11735 |
and @option{--delete} operations. @xref{Operations}, for more |
11736 |
information on these operations. |
11737 |
|
11738 |
Also, since @command{tar} normally strips leading @samp{/} from file |
11739 |
names (@pxref{absolute}), a command like @samp{tar --verify -cf |
11740 |
/tmp/foo.tar /etc} will work as desired only if the working directory is |
11741 |
@file{/}, as @command{tar} uses the archive's relative member names |
11742 |
(e.g., @file{etc/motd}) when verifying the archive. |
11743 |
|
11744 |
@node Write Protection |
11745 |
@section Write Protection |
11746 |
|
11747 |
Almost all tapes and diskettes, and in a few rare cases, even disks can |
11748 |
be @dfn{write protected}, to protect data on them from being changed. |
11749 |
Once an archive is written, you should write protect the media to prevent |
11750 |
the archive from being accidentally overwritten or deleted. (This will |
11751 |
protect the archive from being changed with a tape or floppy drive---it |
11752 |
will not protect it from magnet fields or other physical hazards.) |
11753 |
|
11754 |
The write protection device itself is usually an integral part of the |
11755 |
physical media, and can be a two position (write enabled/write |
11756 |
disabled) switch, a notch which can be popped out or covered, a ring |
11757 |
which can be removed from the center of a tape reel, or some other |
11758 |
changeable feature. |
11759 |
|
11760 |
@node Reliability and security |
11761 |
@chapter Reliability and Security |
11762 |
|
11763 |
The @command{tar} command reads and writes files as any other |
11764 |
application does, and is subject to the usual caveats about |
11765 |
reliability and security. This section contains some commonsense |
11766 |
advice on the topic. |
11767 |
|
11768 |
@menu |
11769 |
* Reliability:: |
11770 |
* Security:: |
11771 |
@end menu |
11772 |
|
11773 |
@node Reliability |
11774 |
@section Reliability |
11775 |
|
11776 |
Ideally, when @command{tar} is creating an archive, it reads from a |
11777 |
file system that is not being modified, and encounters no errors or |
11778 |
inconsistencies while reading and writing. If this is the case, the |
11779 |
archive should faithfully reflect what was read. Similarly, when |
11780 |
extracting from an archive, ideally @command{tar} ideally encounters |
11781 |
no errors and the extracted files faithfully reflect what was in the |
11782 |
archive. |
11783 |
|
11784 |
However, when reading or writing real-world file systems, several |
11785 |
things can go wrong; these include permissions problems, corruption of |
11786 |
data, and race conditions. |
11787 |
|
11788 |
@menu |
11789 |
* Permissions problems:: |
11790 |
* Data corruption and repair:: |
11791 |
* Race conditions:: |
11792 |
@end menu |
11793 |
|
11794 |
@node Permissions problems |
11795 |
@subsection Permissions Problems |
11796 |
|
11797 |
If @command{tar} encounters errors while reading or writing files, it |
11798 |
normally reports an error and exits with nonzero status. The work it |
11799 |
does may therefore be incomplete. For example, when creating an |
11800 |
archive, if @command{tar} cannot read a file then it cannot copy the |
11801 |
file into the archive. |
11802 |
|
11803 |
@node Data corruption and repair |
11804 |
@subsection Data Corruption and Repair |
11805 |
|
11806 |
If an archive becomes corrupted by an I/O error, this may corrupt the |
11807 |
data in an extracted file. Worse, it may corrupt the file's metadata, |
11808 |
which may cause later parts of the archive to become misinterpreted. |
11809 |
An tar-format archive contains a checksum that most likely will detect |
11810 |
errors in the metadata, but it will not detect errors in the data. |
11811 |
|
11812 |
If data corruption is a concern, you can compute and check your own |
11813 |
checksums of an archive by using other programs, such as |
11814 |
@command{cksum}. |
11815 |
|
11816 |
When attempting to recover from a read error or data corruption in an |
11817 |
archive, you may need to skip past the questionable data and read the |
11818 |
rest of the archive. This requires some expertise in the archive |
11819 |
format and in other software tools. |
11820 |
|
11821 |
@node Race conditions |
11822 |
@subsection Race conditions |
11823 |
|
11824 |
If some other process is modifying the file system while @command{tar} |
11825 |
is reading or writing files, the result may well be inconsistent due |
11826 |
to race conditions. For example, if another process creates some |
11827 |
files in a directory while @command{tar} is creating an archive |
11828 |
containing the directory's files, @command{tar} may see some of the |
11829 |
files but not others, or it may see a file that is in the process of |
11830 |
being created. The resulting archive may not be a snapshot of the |
11831 |
file system at any point in time. If an application such as a |
11832 |
database system depends on an accurate snapshot, restoring from the |
11833 |
@command{tar} archive of a live file system may therefore break that |
11834 |
consistency and may break the application. The simplest way to avoid |
11835 |
the consistency issues is to avoid making other changes to the file |
11836 |
system while tar is reading it or writing it. |
11837 |
|
11838 |
When creating an archive, several options are available to avoid race |
11839 |
conditions. Some hosts have a way of snapshotting a file system, or |
11840 |
of temporarily suspending all changes to a file system, by (say) |
11841 |
suspending the only virtual machine that can modify a file system; if |
11842 |
you use these facilities and have @command{tar -c} read from a |
11843 |
snapshot when creating an archive, you can avoid inconsistency |
11844 |
problems. More drastically, before starting @command{tar} you could |
11845 |
suspend or shut down all processes other than @command{tar} that have |
11846 |
access to the file system, or you could unmount the file system and |
11847 |
then mount it read-only. |
11848 |
|
11849 |
When extracting from an archive, one approach to avoid race conditions |
11850 |
is to create a directory that no other process can write to, and |
11851 |
extract into that. |
11852 |
|
11853 |
@node Security |
11854 |
@section Security |
11855 |
|
11856 |
In some cases @command{tar} may be used in an adversarial situation, |
11857 |
where an untrusted user is attempting to gain information about or |
11858 |
modify otherwise-inaccessible files. Dealing with untrusted data |
11859 |
(that is, data generated by an untrusted user) typically requires |
11860 |
extra care, because even the smallest mistake in the use of |
11861 |
@command{tar} is more likely to be exploited by an adversary than by a |
11862 |
race condition. |
11863 |
|
11864 |
@menu |
11865 |
* Privacy:: |
11866 |
* Integrity:: |
11867 |
* Live untrusted data:: |
11868 |
* Security rules of thumb:: |
11869 |
@end menu |
11870 |
|
11871 |
@node Privacy |
11872 |
@subsection Privacy |
11873 |
|
11874 |
Standard privacy concerns apply when using @command{tar}. For |
11875 |
example, suppose you are archiving your home directory into a file |
11876 |
@file{/archive/myhome.tar}. Any secret information in your home |
11877 |
directory, such as your SSH secret keys, are copied faithfully into |
11878 |
the archive. Therefore, if your home directory contains any file that |
11879 |
should not be read by some other user, the archive itself should be |
11880 |
not be readable by that user. And even if the archive's data are |
11881 |
inaccessible to untrusted users, its metadata (such as size or |
11882 |
last-modified date) may reveal some information about your home |
11883 |
directory; if the metadata are intended to be private, the archive's |
11884 |
parent directory should also be inaccessible to untrusted users. |
11885 |
|
11886 |
One precaution is to create @file{/archive} so that it is not |
11887 |
accessible to any user, unless that user also has permission to access |
11888 |
all the files in your home directory. |
11889 |
|
11890 |
Similarly, when extracting from an archive, take care that the |
11891 |
permissions of the extracted files are not more generous than what you |
11892 |
want. Even if the archive itself is readable only to you, files |
11893 |
extracted from it have their own permissions that may differ. |
11894 |
|
11895 |
@node Integrity |
11896 |
@subsection Integrity |
11897 |
|
11898 |
When creating archives, take care that they are not writable by a |
11899 |
untrusted user; otherwise, that user could modify the archive, and |
11900 |
when you later extract from the archive you will get incorrect data. |
11901 |
|
11902 |
When @command{tar} extracts from an archive, by default it writes into |
11903 |
files relative to the working directory. If the archive was generated |
11904 |
by an untrusted user, that user therefore can write into any file |
11905 |
under the working directory. If the working directory contains a |
11906 |
symbolic link to another directory, the untrusted user can also write |
11907 |
into any file under the referenced directory. When extracting from an |
11908 |
untrusted archive, it is therefore good practice to create an empty |
11909 |
directory and run @command{tar} in that directory. |
11910 |
|
11911 |
When extracting from two or more untrusted archives, each one should |
11912 |
be extracted independently, into different empty directories. |
11913 |
Otherwise, the first archive could create a symbolic link into an area |
11914 |
outside the working directory, and the second one could follow the |
11915 |
link and overwrite data that is not under the working directory. For |
11916 |
example, when restoring from a series of incremental dumps, the |
11917 |
archives should have been created by a trusted process, as otherwise |
11918 |
the incremental restores might alter data outside the working |
11919 |
directory. |
11920 |
|
11921 |
If you use the @option{--absolute-names} (@option{-P}) option when |
11922 |
extracting, @command{tar} respects any file names in the archive, even |
11923 |
file names that begin with @file{/} or contain @file{..}. As this |
11924 |
lets the archive overwrite any file in your system that you can write, |
11925 |
the @option{--absolute-names} (@option{-P}) option should be used only |
11926 |
for trusted archives. |
11927 |
|
11928 |
Conversely, with the @option{--keep-old-files} (@option{-k}) option, |
11929 |
@command{tar} refuses to replace existing files when extracting; and |
11930 |
with the @option{--no-overwrite-dir} option, @command{tar} refuses to |
11931 |
replace the permissions or ownership of already-existing directories. |
11932 |
These options may help when extracting from untrusted archives. |
11933 |
|
11934 |
@node Live untrusted data |
11935 |
@subsection Dealing with Live Untrusted Data |
11936 |
|
11937 |
Extra care is required when creating from or extracting into a file |
11938 |
system that is accessible to untrusted users. For example, superusers |
11939 |
who invoke @command{tar} must be wary about its actions being hijacked |
11940 |
by an adversary who is reading or writing the file system at the same |
11941 |
time that @command{tar} is operating. |
11942 |
|
11943 |
When creating an archive from a live file system, @command{tar} is |
11944 |
vulnerable to denial-of-service attacks. For example, an adversarial |
11945 |
user could create the illusion of an indefinitely-deep directory |
11946 |
hierarchy @file{d/e/f/g/...} by creating directories one step ahead of |
11947 |
@command{tar}, or the illusion of an indefinitely-long file by |
11948 |
creating a sparse file but arranging for blocks to be allocated just |
11949 |
before @command{tar} reads them. There is no easy way for |
11950 |
@command{tar} to distinguish these scenarios from legitimate uses, so |
11951 |
you may need to monitor @command{tar}, just as you'd need to monitor |
11952 |
any other system service, to detect such attacks. |
11953 |
|
11954 |
While a superuser is extracting from an archive into a live file |
11955 |
system, an untrusted user might replace a directory with a symbolic |
11956 |
link, in hopes that @command{tar} will follow the symbolic link and |
11957 |
extract data into files that the untrusted user does not have access |
11958 |
to. Even if the archive was generated by the superuser, it may |
11959 |
contain a file such as @file{d/etc/passwd} that the untrusted user |
11960 |
earlier created in order to break in; if the untrusted user replaces |
11961 |
the directory @file{d/etc} with a symbolic link to @file{/etc} while |
11962 |
@command{tar} is running, @command{tar} will overwrite |
11963 |
@file{/etc/passwd}. This attack can be prevented by extracting into a |
11964 |
directory that is inaccessible to untrusted users. |
11965 |
|
11966 |
Similar attacks via symbolic links are also possible when creating an |
11967 |
archive, if the untrusted user can modify an ancestor of a top-level |
11968 |
argument of @command{tar}. For example, an untrusted user that can |
11969 |
modify @file{/home/eve} can hijack a running instance of @samp{tar -cf |
11970 |
- /home/eve/Documents/yesterday} by replacing |
11971 |
@file{/home/eve/Documents} with a symbolic link to some other |
11972 |
location. Attacks like these can be prevented by making sure that |
11973 |
untrusted users cannot modify any files that are top-level arguments |
11974 |
to @command{tar}, or any ancestor directories of these files. |
11975 |
|
11976 |
@node Security rules of thumb |
11977 |
@subsection Security Rules of Thumb |
11978 |
|
11979 |
This section briefly summarizes rules of thumb for avoiding security |
11980 |
pitfalls. |
11981 |
|
11982 |
@itemize @bullet |
11983 |
|
11984 |
@item |
11985 |
Protect archives at least as much as you protect any of the files |
11986 |
being archived. |
11987 |
|
11988 |
@item |
11989 |
Extract from an untrusted archive only into an otherwise-empty |
11990 |
directory. This directory and its parent should be accessible only to |
11991 |
trusted users. For example: |
11992 |
|
11993 |
@example |
11994 |
@group |
11995 |
$ @kbd{chmod go-rwx .} |
11996 |
$ @kbd{mkdir -m go-rwx dir} |
11997 |
$ @kbd{cd dir} |
11998 |
$ @kbd{tar -xvf /archives/got-it-off-the-net.tar.gz} |
11999 |
@end group |
12000 |
@end example |
12001 |
|
12002 |
As a corollary, do not do an incremental restore from an untrusted archive. |
12003 |
|
12004 |
@item |
12005 |
Do not let untrusted users access files extracted from untrusted |
12006 |
archives without checking first for problems such as setuid programs. |
12007 |
|
12008 |
@item |
12009 |
Do not let untrusted users modify directories that are ancestors of |
12010 |
top-level arguments of @command{tar}. For example, while you are |
12011 |
executing @samp{tar -cf /archive/u-home.tar /u/home}, do not let an |
12012 |
untrusted user modify @file{/}, @file{/archive}, or @file{/u}. |
12013 |
|
12014 |
@item |
12015 |
Pay attention to the diagnostics and exit status of @command{tar}. |
12016 |
|
12017 |
@item |
12018 |
When archiving live file systems, monitor running instances of |
12019 |
@command{tar} to detect denial-of-service attacks. |
12020 |
|
12021 |
@item |
12022 |
Avoid unusual options such as @option{--absolute-names} (@option{-P}), |
12023 |
@option{--dereference} (@option{-h}), @option{--overwrite}, |
12024 |
@option{--recursive-unlink}, and @option{--remove-files} unless you |
12025 |
understand their security implications. |
12026 |
|
12027 |
@end itemize |
12028 |
|
12029 |
@node Changes |
12030 |
@appendix Changes |
12031 |
|
12032 |
This appendix lists some important user-visible changes between |
12033 |
version @GNUTAR{} @value{VERSION} and previous versions. An up-to-date |
12034 |
version of this document is available at |
12035 |
@uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the |
12036 |
@GNUTAR{} documentation page}. |
12037 |
|
12038 |
@table @asis |
12039 |
@item Use of globbing patterns when listing and extracting. |
12040 |
|
12041 |
Previous versions of GNU tar assumed shell-style globbing when |
12042 |
extracting from or listing an archive. For example: |
12043 |
|
12044 |
@smallexample |
12045 |
$ @kbd{tar xf foo.tar '*.c'} |
12046 |
@end smallexample |
12047 |
|
12048 |
would extract all files whose names end in @samp{.c}. This behavior |
12049 |
was not documented and was incompatible with traditional tar |
12050 |
implementations. Therefore, starting from version 1.15.91, GNU tar |
12051 |
no longer uses globbing by default. For example, the above invocation |
12052 |
is now interpreted as a request to extract from the archive the file |
12053 |
named @file{*.c}. |
12054 |
|
12055 |
To facilitate transition to the new behavior for those users who got |
12056 |
used to the previous incorrect one, @command{tar} will print a warning |
12057 |
if it finds out that a requested member was not found in the archive |
12058 |
and its name looks like a globbing pattern. For example: |
12059 |
|
12060 |
@smallexample |
12061 |
$ @kbd{tar xf foo.tar '*.c'} |
12062 |
tar: Pattern matching characters used in file names. Please, |
12063 |
tar: use --wildcards to enable pattern matching, or --no-wildcards to |
12064 |
tar: suppress this warning. |
12065 |
tar: *.c: Not found in archive |
12066 |
tar: Error exit delayed from previous errors |
12067 |
@end smallexample |
12068 |
|
12069 |
To treat member names as globbing patterns, use the @option{--wildcards} option. |
12070 |
If you want to tar to mimic the behavior of versions prior to 1.15.91, |
12071 |
add this option to your @env{TAR_OPTIONS} variable. |
12072 |
|
12073 |
@xref{wildcards}, for the detailed discussion of the use of globbing |
12074 |
patterns by @GNUTAR{}. |
12075 |
|
12076 |
@item Use of short option @option{-o}. |
12077 |
|
12078 |
Earlier versions of @GNUTAR{} understood @option{-o} command line |
12079 |
option as a synonym for @option{--old-archive}. |
12080 |
|
12081 |
@GNUTAR{} starting from version 1.13.90 understands this option as |
12082 |
a synonym for @option{--no-same-owner}. This is compatible with |
12083 |
UNIX98 @command{tar} implementations. |
12084 |
|
12085 |
However, to facilitate transition, @option{-o} option retains its |
12086 |
old semantics when it is used with one of archive-creation commands. |
12087 |
Users are encouraged to use @option{--format=oldgnu} instead. |
12088 |
|
12089 |
It is especially important, since versions of @acronym{GNU} Automake |
12090 |
up to and including 1.8.4 invoke tar with this option to produce |
12091 |
distribution tarballs. @xref{Formats,v7}, for the detailed discussion |
12092 |
of this issue and its implications. |
12093 |
|
12094 |
@xref{Options, tar-formats, Changing Automake's Behavior, |
12095 |
automake, GNU Automake}, for a description on how to use various |
12096 |
archive formats with @command{automake}. |
12097 |
|
12098 |
Future versions of @GNUTAR{} will understand @option{-o} only as a |
12099 |
synonym for @option{--no-same-owner}. |
12100 |
|
12101 |
@item Use of short option @option{-l} |
12102 |
|
12103 |
Earlier versions of @GNUTAR{} understood @option{-l} option as a |
12104 |
synonym for @option{--one-file-system}. Since such usage contradicted |
12105 |
to UNIX98 specification and harmed compatibility with other |
12106 |
implementations, it was declared deprecated in version 1.14. However, |
12107 |
to facilitate transition to its new semantics, it was supported by |
12108 |
versions 1.15 and 1.15.90. The present use of @option{-l} as a short |
12109 |
variant of @option{--check-links} was introduced in version 1.15.91. |
12110 |
|
12111 |
@item Use of options @option{--portability} and @option{--old-archive} |
12112 |
|
12113 |
These options are deprecated. Please use @option{--format=v7} instead. |
12114 |
|
12115 |
@item Use of option @option{--posix} |
12116 |
|
12117 |
This option is deprecated. Please use @option{--format=posix} instead. |
12118 |
@end table |
12119 |
|
12120 |
@node Configuring Help Summary |
12121 |
@appendix Configuring Help Summary |
12122 |
|
12123 |
Running @kbd{tar --help} displays the short @command{tar} option |
12124 |
summary (@pxref{help}). This summary is organized by @dfn{groups} of |
12125 |
semantically close options. The options within each group are printed |
12126 |
in the following order: a short option, eventually followed by a list |
12127 |
of corresponding long option names, followed by a short description of |
12128 |
the option. For example, here is an excerpt from the actual @kbd{tar |
12129 |
--help} output: |
12130 |
|
12131 |
@verbatim |
12132 |
Main operation mode: |
12133 |
|
12134 |
-A, --catenate, --concatenate append tar files to an archive |
12135 |
-c, --create create a new archive |
12136 |
-d, --diff, --compare find differences between archive and |
12137 |
file system |
12138 |
--delete delete from the archive |
12139 |
@end verbatim |
12140 |
|
12141 |
@vrindex ARGP_HELP_FMT, environment variable |
12142 |
The exact visual representation of the help output is configurable via |
12143 |
@env{ARGP_HELP_FMT} environment variable. The value of this variable |
12144 |
is a comma-separated list of @dfn{format variable} assignments. There |
12145 |
are two kinds of format variables. An @dfn{offset variable} keeps the |
12146 |
offset of some part of help output text from the leftmost column on |
12147 |
the screen. A @dfn{boolean} variable is a flag that toggles some |
12148 |
output feature on or off. Depending on the type of the corresponding |
12149 |
variable, there are two kinds of assignments: |
12150 |
|
12151 |
@table @asis |
12152 |
@item Offset assignment |
12153 |
|
12154 |
The assignment to an offset variable has the following syntax: |
12155 |
|
12156 |
@smallexample |
12157 |
@var{variable}=@var{value} |
12158 |
@end smallexample |
12159 |
|
12160 |
@noindent |
12161 |
where @var{variable} is the variable name, and @var{value} is a |
12162 |
numeric value to be assigned to the variable. |
12163 |
|
12164 |
@item Boolean assignment |
12165 |
|
12166 |
To assign @code{true} value to a variable, simply put this variable name. To |
12167 |
assign @code{false} value, prefix the variable name with @samp{no-}. For |
12168 |
example: |
12169 |
|
12170 |
@smallexample |
12171 |
@group |
12172 |
# Assign @code{true} value: |
12173 |
dup-args |
12174 |
# Assign @code{false} value: |
12175 |
no-dup-args |
12176 |
@end group |
12177 |
@end smallexample |
12178 |
@end table |
12179 |
|
12180 |
Following variables are declared: |
12181 |
|
12182 |
@deftypevr {Help Output} boolean dup-args |
12183 |
If true, arguments for an option are shown with both short and long |
12184 |
options, even when a given option has both forms, for example: |
12185 |
|
12186 |
@smallexample |
12187 |
-f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE |
12188 |
@end smallexample |
12189 |
|
12190 |
If false, then if an option has both short and long forms, the |
12191 |
argument is only shown with the long one, for example: |
12192 |
|
12193 |
@smallexample |
12194 |
-f, --file=ARCHIVE use archive file or device ARCHIVE |
12195 |
@end smallexample |
12196 |
|
12197 |
@noindent |
12198 |
and a message indicating that the argument is applicable to both |
12199 |
forms is printed below the options. This message can be disabled |
12200 |
using @code{dup-args-note} (see below). |
12201 |
|
12202 |
The default is false. |
12203 |
@end deftypevr |
12204 |
|
12205 |
@deftypevr {Help Output} boolean dup-args-note |
12206 |
If this variable is true, which is the default, the following notice |
12207 |
is displayed at the end of the help output: |
12208 |
|
12209 |
@quotation |
12210 |
Mandatory or optional arguments to long options are also mandatory or |
12211 |
optional for any corresponding short options. |
12212 |
@end quotation |
12213 |
|
12214 |
Setting @code{no-dup-args-note} inhibits this message. Normally, only one of |
12215 |
variables @code{dup-args} or @code{dup-args-note} should be set. |
12216 |
@end deftypevr |
12217 |
|
12218 |
@deftypevr {Help Output} offset short-opt-col |
12219 |
Column in which short options start. Default is 2. |
12220 |
|
12221 |
@smallexample |
12222 |
@group |
12223 |
$ @kbd{tar --help|grep ARCHIVE} |
12224 |
-f, --file=ARCHIVE use archive file or device ARCHIVE |
12225 |
$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE} |
12226 |
-f, --file=ARCHIVE use archive file or device ARCHIVE |
12227 |
@end group |
12228 |
@end smallexample |
12229 |
@end deftypevr |
12230 |
|
12231 |
@deftypevr {Help Output} offset long-opt-col |
12232 |
Column in which long options start. Default is 6. For example: |
12233 |
|
12234 |
@smallexample |
12235 |
@group |
12236 |
$ @kbd{tar --help|grep ARCHIVE} |
12237 |
-f, --file=ARCHIVE use archive file or device ARCHIVE |
12238 |
$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE} |
12239 |
-f, --file=ARCHIVE use archive file or device ARCHIVE |
12240 |
@end group |
12241 |
@end smallexample |
12242 |
@end deftypevr |
12243 |
|
12244 |
@deftypevr {Help Output} offset doc-opt-col |
12245 |
Column in which @dfn{doc options} start. A doc option isn't actually |
12246 |
an option, but rather an arbitrary piece of documentation that is |
12247 |
displayed in much the same manner as the options. For example, in |
12248 |
the description of @option{--format} option: |
12249 |
|
12250 |
@smallexample |
12251 |
@group |
12252 |
-H, --format=FORMAT create archive of the given format. |
12253 |
|
12254 |
FORMAT is one of the following: |
12255 |
|
12256 |
gnu GNU tar 1.13.x format |
12257 |
oldgnu GNU format as per tar <= 1.12 |
12258 |
pax POSIX 1003.1-2001 (pax) format |
12259 |
posix same as pax |
12260 |
ustar POSIX 1003.1-1988 (ustar) format |
12261 |
v7 old V7 tar format |
12262 |
@end group |
12263 |
@end smallexample |
12264 |
|
12265 |
@noindent |
12266 |
the format names are doc options. Thus, if you set |
12267 |
@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output |
12268 |
will look as follows: |
12269 |
|
12270 |
@smallexample |
12271 |
@group |
12272 |
-H, --format=FORMAT create archive of the given format. |
12273 |
|
12274 |
FORMAT is one of the following: |
12275 |
|
12276 |
gnu GNU tar 1.13.x format |
12277 |
oldgnu GNU format as per tar <= 1.12 |
12278 |
pax POSIX 1003.1-2001 (pax) format |
12279 |
posix same as pax |
12280 |
ustar POSIX 1003.1-1988 (ustar) format |
12281 |
v7 old V7 tar format |
12282 |
@end group |
12283 |
@end smallexample |
12284 |
@end deftypevr |
12285 |
|
12286 |
@deftypevr {Help Output} offset opt-doc-col |
12287 |
Column in which option description starts. Default is 29. |
12288 |
|
12289 |
@smallexample |
12290 |
@group |
12291 |
$ @kbd{tar --help|grep ARCHIVE} |
12292 |
-f, --file=ARCHIVE use archive file or device ARCHIVE |
12293 |
$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE} |
12294 |
-f, --file=ARCHIVE use archive file or device ARCHIVE |
12295 |
$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE} |
12296 |
-f, --file=ARCHIVE |
12297 |
use archive file or device ARCHIVE |
12298 |
@end group |
12299 |
@end smallexample |
12300 |
|
12301 |
@noindent |
12302 |
Notice, that the description starts on a separate line if |
12303 |
@code{opt-doc-col} value is too small. |
12304 |
@end deftypevr |
12305 |
|
12306 |
@deftypevr {Help Output} offset header-col |
12307 |
Column in which @dfn{group headers} are printed. A group header is a |
12308 |
descriptive text preceding an option group. For example, in the |
12309 |
following text: |
12310 |
|
12311 |
@verbatim |
12312 |
Main operation mode: |
12313 |
|
12314 |
-A, --catenate, --concatenate append tar files to |
12315 |
an archive |
12316 |
-c, --create create a new archive |
12317 |
@end verbatim |
12318 |
@noindent |
12319 |
@samp{Main operation mode:} is the group header. |
12320 |
|
12321 |
The default value is 1. |
12322 |
@end deftypevr |
12323 |
|
12324 |
@deftypevr {Help Output} offset usage-indent |
12325 |
Indentation of wrapped usage lines. Affects @option{--usage} |
12326 |
output. Default is 12. |
12327 |
@end deftypevr |
12328 |
|
12329 |
@deftypevr {Help Output} offset rmargin |
12330 |
Right margin of the text output. Used for wrapping. |
12331 |
@end deftypevr |
12332 |
|
12333 |
@node Fixing Snapshot Files |
12334 |
@appendix Fixing Snapshot Files |
12335 |
@include tar-snapshot-edit.texi |
12336 |
|
12337 |
@node Tar Internals |
12338 |
@appendix Tar Internals |
12339 |
@include intern.texi |
12340 |
|
12341 |
@node Genfile |
12342 |
@appendix Genfile |
12343 |
@include genfile.texi |
12344 |
|
12345 |
@node Free Software Needs Free Documentation |
12346 |
@appendix Free Software Needs Free Documentation |
12347 |
@include freemanuals.texi |
12348 |
|
12349 |
@node GNU Free Documentation License |
12350 |
@appendix GNU Free Documentation License |
12351 |
|
12352 |
@include fdl.texi |
12353 |
|
12354 |
@node Index of Command Line Options |
12355 |
@appendix Index of Command Line Options |
12356 |
|
12357 |
This appendix contains an index of all @GNUTAR{} long command line |
12358 |
options. The options are listed without the preceding double-dash. |
12359 |
For a cross-reference of short command line options, see |
12360 |
@ref{Short Option Summary}. |
12361 |
|
12362 |
@printindex op |
12363 |
|
12364 |
@node Index |
12365 |
@appendix Index |
12366 |
|
12367 |
@printindex cp |
12368 |
|
12369 |
@summarycontents |
12370 |
@contents |
12371 |
@bye |
12372 |
|
12373 |
@c Local variables: |
12374 |
@c texinfo-column-for-description: 32 |
12375 |
@c End: |