/[tar]/tar/doc/tar.texi
ViewVC logotype

Diff of /tar/doc/tar.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.38 by eggert, Mon Sep 22 18:26:50 2003 UTC revision 1.39 by gray, Sun Oct 19 19:05:45 2003 UTC
# Line 100  Line 100 
100  @c @value{\entry\}  @c @value{\entry\}
101  @c @end macro  @c @end macro
102    
103    @macro GNUTAR
104    @acronym{GNU} @command{tar}
105    @end macro
106    
107  @set op-absolute-names @kbd{--absolute-names} (@kbd{-P})  @set op-absolute-names @kbd{--absolute-names} (@kbd{-P})
108  @set ref-absolute-names @ref{absolute}  @set ref-absolute-names @ref{absolute}
109  @set xref-absolute-names @xref{absolute}  @set xref-absolute-names @xref{absolute}
# Line 140  Line 144 
144  @set xref-bzip2 @xref{gzip}  @set xref-bzip2 @xref{gzip}
145  @set pxref-bzip2 @pxref{gzip}  @set pxref-bzip2 @pxref{gzip}
146    
147    @set op-check-links @kbd{--check-links} (@kbd{-l})
148    @set ref-check-links @ref{--check-links}
149    @set xref-check-links @xref{--check-links}
150    @set pxref-check-links @pxref{--check-links}
151    
152  @set op-checkpoint @kbd{--checkpoint}  @set op-checkpoint @kbd{--checkpoint}
153  @set ref-checkpoint @ref{verbose}  @set ref-checkpoint @ref{verbose}
154  @set xref-checkpoint @xref{verbose}  @set xref-checkpoint @xref{verbose}
# Line 292  Line 301 
301  @set xref-no-recursion @xref{recurse}  @set xref-no-recursion @xref{recurse}
302  @set pxref-no-recursion @pxref{recurse}  @set pxref-no-recursion @pxref{recurse}
303    
304  @set op-no-same-owner @kbd{--no-same-owner}  @set op-no-same-owner @kbd{--no-same-owner} (@kbd{-o})
305  @set ref-no-same-owner @ref{Attributes}  @set ref-no-same-owner @ref{Attributes}
306  @set xref-no-same-owner @xref{Attributes}  @set xref-no-same-owner @xref{Attributes}
307  @set pxref-no-same-owner @pxref{Attributes}  @set pxref-no-same-owner @pxref{Attributes}
# Line 312  Line 321 
321  @set xref-numeric-owner @xref{Attributes}  @set xref-numeric-owner @xref{Attributes}
322  @set pxref-numeric-owner @pxref{Attributes}  @set pxref-numeric-owner @pxref{Attributes}
323    
324    @set op-occurrence @kbd{--occurrence}
325    @set ref-occurrence @ref{--occurrence}
326    @set xref-occurrence @xref{--occurrence}
327    @set pxref-occurrence @pxref{--occurrence}
328    
329  @set op-old-archive @kbd{--old-archive} (@kbd{-o})  @set op-old-archive @kbd{--old-archive} (@kbd{-o})
330  @set ref-old-archive @ref{old}  @set ref-old-archive @ref{old}
331  @set xref-old-archive @xref{old}  @set xref-old-archive @xref{old}
# Line 332  Line 346 
346  @set xref-owner @xref{Option Summary}  @set xref-owner @xref{Option Summary}
347  @set pxref-owner @pxref{Option Summary}  @set pxref-owner @pxref{Option Summary}
348    
349    @set op-format @kbd{--format}
350    @set ref-format @ref{format}
351    @set xref-format @xref{format}
352    @set pxref-format @pxref{format}
353    
354    @set op-format-v7 @kbd{--format=v7}
355    @set op-format-gnu @kbd{--format=gnu}
356    @set op-format-oldgnu @kbd{--format=oldgnu}
357    @set op-format-posix @kbd{--format=posix}
358    
359  @set op-posix @kbd{--posix}  @set op-posix @kbd{--posix}
360  @set ref-posix @ref{posix}  @set ref-posix @ref{posix}
361  @set xref-posix @xref{posix}  @set xref-posix @xref{posix}
# Line 397  Line 421 
421  @set xref-starting-file @xref{Scarce}  @set xref-starting-file @xref{Scarce}
422  @set pxref-starting-file @pxref{Scarce}  @set pxref-starting-file @pxref{Scarce}
423    
424    @set op-strip-path @kbd{--strip-path}
425    @set ref-strip-path @ref{--strip-path}
426    @set xref-strip-path @xref{--strip-path}
427    @set pxref-strip-path @pxref{--strip-path}
428    
429  @set op-suffix @kbd{--suffix=@var{suffix}}  @set op-suffix @kbd{--suffix=@var{suffix}}
430  @set ref-suffix @ref{Backup options}  @set ref-suffix @ref{Backup options}
431  @set xref-suffix @xref{Backup options}  @set xref-suffix @xref{Backup options}
# Line 468  Line 497 
497    
498  @copying  @copying
499    
500  This manual is for @acronym{GNU} @command{tar} (version  This manual is for @GNUTAR{} (version
501  @value{VERSION}, @value{UPDATED}), which creates and extracts files  @value{VERSION}, @value{UPDATED}), which creates and extracts files
502  from archives.  from archives.
503    
# Line 497  developing GNU and promoting software fr Line 526  developing GNU and promoting software fr
526    
527  @dircategory Individual utilities  @dircategory Individual utilities
528  @direntry  @direntry
529  * tar: (tar)tar invocation.                     Invoking @acronym{GNU} @command{tar}  * tar: (tar)tar invocation.                     Invoking @GNUTAR{}
530  @end direntry  @end direntry
531    
532  @shorttitlepage @acronym{GNU} @command{tar}  @shorttitlepage @GNUTAR{}
533    
534  @titlepage  @titlepage
535  @title @acronym{GNU} tar: an archiver tool  @title @acronym{GNU} tar: an archiver tool
# Line 555  Introduction Line 584  Introduction
584  * What tar Does::               What @command{tar} Does  * What tar Does::               What @command{tar} Does
585  * Naming tar Archives::         How @command{tar} Archives are Named  * Naming tar Archives::         How @command{tar} Archives are Named
586  * posix compliance::  * posix compliance::
587  * Authors::                     @acronym{GNU} @command{tar} Authors  * Current status::              Current development status of @GNUTAR{}
588    * Authors::                     @GNUTAR{} Authors
589  * Reports::                     Reporting bugs or suggestions  * Reports::                     Reporting bugs or suggestions
590    
591  Tutorial Introduction to @command{tar}  Tutorial Introduction to @command{tar}
# Line 595  How to Extract Members from an Archive Line 625  How to Extract Members from an Archive
625  * extract dir::  * extract dir::
626  * failing commands::  * failing commands::
627    
628  Invoking @acronym{GNU} @command{tar}  Invoking @GNUTAR{}
629    
630  * Synopsis::  * Synopsis::
631  * using tar options::  * using tar options::
# Line 618  All @command{tar} Options Line 648  All @command{tar} Options
648  * Option Summary::  * Option Summary::
649  * Short Option Summary::  * Short Option Summary::
650    
651  @acronym{GNU} @command{tar} Operations  @GNUTAR{} Operations
652    
653  * Basic tar::  * Basic tar::
654  * Advanced tar::  * Advanced tar::
# Line 628  All @command{tar} Options Line 658  All @command{tar} Options
658  * Applications::  * Applications::
659  * looking ahead::  * looking ahead::
660    
661  Advanced @acronym{GNU} @command{tar} Operations  Advanced @GNUTAR{} Operations
662    
663  * Operations::  * Operations::
664  * append::  * append::
# Line 789  Copying This Manual Line 819  Copying This Manual
819  @node Introduction  @node Introduction
820  @chapter Introduction  @chapter Introduction
821    
822  @acronym{GNU} @command{tar} creates  @GNUTAR{} creates
823  and manipulates (@dfn{archives}) which are actually collections of  and manipulates (@dfn{archives}) which are actually collections of
824  many other files; the program provides users with an organized and  many other files; the program provides users with an organized and
825  systematic method for controlling a large amount of data.  systematic method for controlling a large amount of data.
# Line 802  archives need not (and these days, typic Line 832  archives need not (and these days, typic
832  * What tar Does::               What @command{tar} Does  * What tar Does::               What @command{tar} Does
833  * Naming tar Archives::         How @command{tar} Archives are Named  * Naming tar Archives::         How @command{tar} Archives are Named
834  * posix compliance::  * posix compliance::
835  * Authors::                     @acronym{GNU} @command{tar} Authors  * Current status::              Current development status of @GNUTAR{}
836    * Authors::                     @GNUTAR{} Authors
837  * Reports::                     Reporting bugs or suggestions  * Reports::                     Reporting bugs or suggestions
838  @end menu  @end menu
839    
# Line 810  archives need not (and these days, typic Line 841  archives need not (and these days, typic
841  @section What this Book Contains  @section What this Book Contains
842    
843  The first part of this chapter introduces you to various terms that will  The first part of this chapter introduces you to various terms that will
844  recur throughout the book.  It also tells you who has worked on @acronym{GNU}  recur throughout the book.  It also tells you who has worked on @GNUTAR{}
845  @command{tar} and its documentation, and where you should send bug reports  and its documentation, and where you should send bug reports
846  or comments.  or comments.
847    
848  The second chapter is a tutorial (@pxref{Tutorial}) which provides a  The second chapter is a tutorial (@pxref{Tutorial}) which provides a
# Line 942  used for performing full and incremental Line 973  used for performing full and incremental
973  puts a collection of files (possibly pertaining to many users and  puts a collection of files (possibly pertaining to many users and
974  projects) together on a disk or a tape.  This guards against  projects) together on a disk or a tape.  This guards against
975  accidental destruction of the information in those files.  accidental destruction of the information in those files.
976  @acronym{GNU} @command{tar} has special features that allow it to be  @GNUTAR{} has special features that allow it to be
977  used to make incremental and full dumps of all the files in a  used to make incremental and full dumps of all the files in a
978  filesystem.  filesystem.
979    
# Line 977  members'' to make learning to use @comma Line 1008  members'' to make learning to use @comma
1008  be an issue, but we're not really sure at this time.  dan just tried a  be an issue, but we're not really sure at this time.  dan just tried a
1009  test case of mixing up options' orders while the variable was set, and  test case of mixing up options' orders while the variable was set, and
1010  there was no problem...}  there was no problem...}
1011    @FIXME{I did not notice any problems either. Besides, the only piece
1012    of code that really uses POSIXLY_CORRECT is the one that forces
1013    creation of POSIX archives. I guess this paragraph should be removed.
1014    
1015    --gray}
1016    
1017    
1018  We make some of our recommendations throughout this book for one  We make some of our recommendations throughout this book for one
1019  reason in addition to what we think of as ``good sense''.  The main  reason in addition to what we think of as ``good sense''.  The main
1020  additional reason for a recommendation is to be compliant with the  additional reason for a recommendation is to be compliant with the
1021  @sc{posix} standards.  If you set the shell environment variable  @sc{posix} standards.  If you set the shell environment variable
1022  @env{POSIXLY_CORRECT}, @acronym{GNU} @command{tar} will force you to  @env{POSIXLY_CORRECT}, @GNUTAR{} will force you to
1023  adhere to these standards.  Therefore, if this variable is set and you  adhere to these standards.  Therefore, if this variable is set and you
1024  violate one of the @sc{posix} standards in the way you phrase a  violate one of the @sc{posix} standards in the way you phrase a
1025  command, for example, @acronym{GNU} @command{tar} will not allow the  command, for example, @GNUTAR{} will not allow the
1026  command and will signal an error message.  You would then have to  command and will signal an error message.  You would then have to
1027  reorder the options or rephrase the command to comply with the  reorder the options or rephrase the command to comply with the
1028  @sc{posix} standards.  @sc{posix} standards.
1029    
1030  There is a chance in the future that, if you set this environment  Notice also, that if this environment variable is set, @GNUTAR{}
1031  variable, your archives will be forced to comply with @sc{posix} standards,  will create @acronym{POSIX} archives. Currently this means that
1032  also.  No @acronym{GNU} @command{tar} extensions will be allowed.  no @acronym{GNU} extensions will be allowed (@pxref{posix}).
1033    
1034    @node Current status
1035    @section Current development status of @GNUTAR{}
1036    
1037    @GNUTAR{} is currently in the process of active development, whose
1038    primary aims are:
1039    
1040    @itemize @bullet
1041    @item Improve compatibility between @GNUTAR{} and other @command{tar}
1042    implementations.
1043    @item Switch to using @acronym{POSIX} archives.
1044    @item Revise sparse file handling.
1045    @item Revise multiple volume processing.
1046    @end itemize
1047    
1048    The following issues need mentioning:
1049    
1050    @table @asis
1051    @item Use of short option @option{-o}.
1052    Earlier versions of @GNUTAR{} understood @option{-o} command line
1053    option as a synonim for @option{--old-archive}.
1054    
1055    @GNUTAR{} starting from version 1.13.90 understands this option as
1056    a synonim for @option{--no-same-owner}. This is compatible with
1057    UNIX98 @command{tar} implementations.
1058    
1059    However, to facilitate transition, @option{-o} option retains its
1060    old semantics when it is used with one of archive-creation commands.
1061    Users are encouraged to use @value{op-format-oldgnu} instead.
1062    
1063    Future versions of @GNUTAR{} will understand @option{-o} only as a
1064    synonim for @option{--no-same-owner}.
1065    
1066    @item Use of short option @option{-l}
1067    Earlier versions of @GNUTAR{} understood @option{-l} option as a
1068    synonim for @samp{--one-file-system}. Such usage is deprecated.
1069    For compatiblity with other implementations future versions of
1070    @GNUTAR{} will understand this option as a synonim for
1071    @option{--check-links}.
1072    
1073    @item Use of options @option{--portability} and @option{--old-archive}
1074    These options are deprecated. Please use @option{--format=v7} instead.
1075    
1076    @item Use of option @option{--posix}
1077    This option is deprecated. Please use @option{--format=posix} instead.
1078    @end table
1079    
1080  @node Authors  @node Authors
1081  @section @acronym{GNU} @command{tar} Authors  @section @GNUTAR{} Authors
1082    
1083  @acronym{GNU} @command{tar} was originally written by John Gilmore,  @GNUTAR{} was originally written by John Gilmore,
1084  and modified by many people.  The @acronym{GNU} enhancements were  and modified by many people.  The @acronym{GNU} enhancements were
1085  written by Jay Fenlason, then Joy Kendall, and the whole package has  written by Jay Fenlason, then Joy Kendall, and the whole package has
1086  been further maintained by Thomas Bushnell, n/BSG, and finally  been further maintained by Thomas Bushnell, n/BSG, and finally
# Line 1007  We wish to stress that @command{tar} is Line 1090  We wish to stress that @command{tar} is
1090  all those people who reported problems, offered solutions and other  all those people who reported problems, offered solutions and other
1091  insights, or shared their thoughts and suggestions.  An impressive, yet  insights, or shared their thoughts and suggestions.  An impressive, yet
1092  partial list of those contributors can be found in the @file{THANKS}  partial list of those contributors can be found in the @file{THANKS}
1093  file from the @acronym{GNU} @command{tar} distribution.  file from the @GNUTAR{} distribution.
1094    
1095  @FIXME{i want all of these names mentioned, Absolutely.  BUT, i'm not  @FIXME{i want all of these names mentioned, Absolutely.  BUT, i'm not
1096  sure i want to spell out the history in this detail, at least not for  sure i want to spell out the history in this detail, at least not for
# Line 1017  i'll think about it.} Line 1100  i'll think about it.}
1100  @FIXME{History is more important, and surely more interesting, than  @FIXME{History is more important, and surely more interesting, than
1101  actual names.  Quoting names without history would be meaningless.  FP}  actual names.  Quoting names without history would be meaningless.  FP}
1102    
1103  Jay Fenlason put together a draft of a @acronym{GNU} @command{tar}  Jay Fenlason put together a draft of a @GNUTAR{}
1104  manual, borrowing notes from the original man page from John Gilmore.  manual, borrowing notes from the original man page from John Gilmore.
1105  This was withdrawn in version 1.11.  Thomas Bushnell, n/BSG and Amy  This was withdrawn in version 1.11.  Thomas Bushnell, n/BSG and Amy
1106  Gorin worked on a tutorial and manual for @acronym{GNU} @command{tar}.  Gorin worked on a tutorial and manual for @GNUTAR{}.
1107  Fran@,{c}ois Pinard put version 1.11.8 of the manual together by  Fran@,{c}ois Pinard put version 1.11.8 of the manual together by
1108  taking information from all these sources and merging them.  Melissa  taking information from all these sources and merging them.  Melissa
1109  Weisshaus finally edited and redesigned the book to create version  Weisshaus finally edited and redesigned the book to create version
# Line 1032  thing.} Line 1115  thing.}
1115  For version 1.12, Daniel Hagerty contributed a great deal of technical  For version 1.12, Daniel Hagerty contributed a great deal of technical
1116  consulting.  In particular, he is the primary author of @ref{Backups}.  consulting.  In particular, he is the primary author of @ref{Backups}.
1117    
1118    In July, 2003 @GNUTAR{} was put on CVS at @url{savannah.gnu.org}, and
1119    an active development and maintainance work has started
1120    again. Currently @GNUTAR{} is being maintained by Paul Eggert, Sergey
1121    Poznyakoff and Jeff Bailey.
1122    
1123    Support for @acronym{POSIX} archives was added by Sergey Poznyakoff.
1124    
1125  @node Reports  @node Reports
1126  @section Reporting bugs or suggestions  @section Reporting bugs or suggestions
1127    
# Line 1154  the operations and options which we will Line 1244  the operations and options which we will
1244  corresponding abbreviations.  @FIXME{make sure this is still the case,  corresponding abbreviations.  @FIXME{make sure this is still the case,
1245  at the end}We will indicate those abbreviations appropriately to get  at the end}We will indicate those abbreviations appropriately to get
1246  you used to seeing them.  (Note that the ``old style'' option forms  you used to seeing them.  (Note that the ``old style'' option forms
1247  exist in @acronym{GNU} @command{tar} for compatibility with Unix  exist in @GNUTAR{} for compatibility with Unix
1248  @command{tar}.  We present a full discussion of this way of writing  @command{tar}.  We present a full discussion of this way of writing
1249  options and operations appears in @ref{Old Options}, and we discuss  options and operations appears in @ref{Old Options}, and we discuss
1250  the other two styles of writing options in @ref{Mnemonic Options} and  the other two styles of writing options in @ref{Mnemonic Options} and
# Line 1165  long forms of operations and options; bu Line 1255  long forms of operations and options; bu
1255  the same result and can make typing long @command{tar} commands easier.  the same result and can make typing long @command{tar} commands easier.
1256  For example, instead of typing  For example, instead of typing
1257    
1258  @example  @smallexample
1259  @kbd{tar --create --verbose --file=afiles.tar apple angst aspic}  @kbd{tar --create --verbose --file=afiles.tar apple angst aspic}
1260  @end example  @end smallexample
1261    
1262  @noindent  @noindent
1263  you can type  you can type
1264  @example  @smallexample
1265  @kbd{tar -c -v -f afiles.tar apple angst aspic}  @kbd{tar -c -v -f afiles.tar apple angst aspic}
1266  @end example  @end smallexample
1267    
1268  @noindent  @noindent
1269  or even  or even
1270  @example  @smallexample
1271  @kbd{tar -cvf afiles.tar apple angst aspic}  @kbd{tar -cvf afiles.tar apple angst aspic}
1272  @end example  @end smallexample
1273    
1274  @noindent  @noindent
1275  For more information on option syntax, see @ref{Advanced tar}.  In  For more information on option syntax, see @ref{Advanced tar}.  In
# Line 1260  If there is no tape drive attached, or t Line 1350  If there is no tape drive attached, or t
1350  then @command{tar} will print an error message.  The error message might  then @command{tar} will print an error message.  The error message might
1351  look roughly like one of the following:  look roughly like one of the following:
1352    
1353  @example  @smallexample
1354  tar: can't open /dev/rmt8 : No such device or address  tar: can't open /dev/rmt8 : No such device or address
1355  tar: can't open /dev/rsmt0 : I/O error  tar: can't open /dev/rsmt0 : I/O error
1356  @end example  @end smallexample
1357    
1358  @noindent  @noindent
1359  To avoid confusion, we recommend that you always specify an archive file  To avoid confusion, we recommend that you always specify an archive file
# Line 1300  operation is operating on at the time. Line 1390  operation is operating on at the time.
1390  use @samp{--verbose} twice in a command to get a listing such as that  use @samp{--verbose} twice in a command to get a listing such as that
1391  in the former case.  For example, instead of saying  in the former case.  For example, instead of saying
1392    
1393  @example  @smallexample
1394  @kbd{tar -cvf afiles.tar apple angst aspic}  @kbd{tar -cvf afiles.tar apple angst aspic}
1395  @end example  @end smallexample
1396    
1397  @noindent  @noindent
1398  above, you might say  above, you might say
1399    
1400  @example  @smallexample
1401  @kbd{tar -cvvf afiles.tar apple angst aspic}  @kbd{tar -cvvf afiles.tar apple angst aspic}
1402  @end example  @end smallexample
1403    
1404  @noindent  @noindent
1405  This works equally well using short or long forms of options.  Using  This works equally well using short or long forms of options.  Using
1406  long forms, you would simply write out the mnemonic form of the option  long forms, you would simply write out the mnemonic form of the option
1407  twice, like this:  twice, like this:
1408    
1409  @example  @smallexample
1410  $ @kbd{tar --create --verbose --verbose @dots{}}  $ @kbd{tar --create --verbose --verbose @dots{}}
1411  @end example  @end smallexample
1412    
1413  @noindent  @noindent
1414  Note that you must double the hyphens properly each time.  Note that you must double the hyphens properly each time.
# Line 1412  information on how to do this. Line 1502  information on how to do this.
1502  To place the files @file{blues}, @file{folk}, and @file{jazz} into an  To place the files @file{blues}, @file{folk}, and @file{jazz} into an
1503  archive named @file{collection.tar}, use the following command:  archive named @file{collection.tar}, use the following command:
1504    
1505  @example  @smallexample
1506  $ @kbd{tar --create --file=collection.tar blues folk jazz}  $ @kbd{tar --create --file=collection.tar blues folk jazz}
1507  @end example  @end smallexample
1508    
1509  The order of the arguments is not very important, @emph{when using long  The order of the arguments is not very important, @emph{when using long
1510  option forms}.  You could also say:  option forms}.  You could also say:
1511    
1512  @example  @smallexample
1513  $ @kbd{tar blues --create folk --file=collection.tar jazz}  $ @kbd{tar blues --create folk --file=collection.tar jazz}
1514  @end example  @end smallexample
1515    
1516  @noindent  @noindent
1517  However, you can see that this order is harder to understand; this is  However, you can see that this order is harder to understand; this is
# Line 1454  in the archive, they are called @emph{ar Line 1544  in the archive, they are called @emph{ar
1544    
1545  When you create an archive, you @emph{must} specify which files you  When you create an archive, you @emph{must} specify which files you
1546  want placed in the archive.  If you do not specify any archive  want placed in the archive.  If you do not specify any archive
1547  members, @acronym{GNU} @command{tar} will complain.  members, @GNUTAR{} will complain.
1548    
1549  If you now list the contents of the working directory (@kbd{ls}), you will  If you now list the contents of the working directory (@kbd{ls}), you will
1550  find the archive file listed as well as the files you saw previously:  find the archive file listed as well as the files you saw previously:
1551    
1552  @example  @smallexample
1553  blues   folk   jazz   collection.tar  blues   folk   jazz   collection.tar
1554  @end example  @end smallexample
1555    
1556  @noindent  @noindent
1557  Creating the archive @samp{collection.tar} did not destroy the copies of  Creating the archive @samp{collection.tar} did not destroy the copies of
# Line 1483  If you include the @value{op-verbose} op Line 1573  If you include the @value{op-verbose} op
1573  @command{tar} will list the files it is acting on as it is working.  In  @command{tar} will list the files it is acting on as it is working.  In
1574  verbose mode, the @code{create} example above would appear as:  verbose mode, the @code{create} example above would appear as:
1575    
1576  @example  @smallexample
1577  $ @kbd{tar --create --verbose --file=collection.tar blues folk jazz}  $ @kbd{tar --create --verbose --file=collection.tar blues folk jazz}
1578  blues  blues
1579  folk  folk
1580  jazz  jazz
1581  @end example  @end smallexample
1582    
1583  This example is just like the example we showed which did not use  This example is just like the example we showed which did not use
1584  @samp{--verbose}, except that @command{tar} generated the remaining lines  @samp{--verbose}, except that @command{tar} generated the remaining lines
# Line 1515  options can take appears in @ref{Styles} Line 1605  options can take appears in @ref{Styles}
1605  previous example (including the @value{op-verbose} option) looks like  previous example (including the @value{op-verbose} option) looks like
1606  using short option forms:  using short option forms:
1607    
1608  @example  @smallexample
1609  $ @kbd{tar -cvf collection.tar blues folk jazz}  $ @kbd{tar -cvf collection.tar blues folk jazz}
1610  blues  blues
1611  folk  folk
1612  jazz  jazz
1613  @end example  @end smallexample
1614    
1615  @noindent  @noindent
1616  As you can see, the system responds the same no matter whether you use  As you can see, the system responds the same no matter whether you use
# Line 1533  it is easier to become confused and make Line 1623  it is easier to become confused and make
1623  forms.  For example, suppose you attempted the above example in the  forms.  For example, suppose you attempted the above example in the
1624  following way:  following way:
1625    
1626  @example  @smallexample
1627  $ @kbd{tar -cfv collection.tar blues folk jazz}  $ @kbd{tar -cfv collection.tar blues folk jazz}
1628  @end example  @end smallexample
1629    
1630  @noindent  @noindent
1631  In this case, @command{tar} will make an archive file called @file{v},  In this case, @command{tar} will make an archive file called @file{v},
# Line 1556  you how an example we showed previously Line 1646  you how an example we showed previously
1646    
1647  This example,  This example,
1648    
1649  @example  @smallexample
1650  $ @kbd{tar blues --create folk --file=collection.tar jazz}  $ @kbd{tar blues --create folk --file=collection.tar jazz}
1651  @end example  @end smallexample
1652    
1653  @noindent  @noindent
1654  is confusing as it is.  When shown using short forms, however, it  is confusing as it is.  When shown using short forms, however, it
1655  becomes much more so:  becomes much more so:
1656    
1657  @example  @smallexample
1658  $ @kbd{tar blues -c folk -f collection.tar jazz}  $ @kbd{tar blues -c folk -f collection.tar jazz}
1659  @end example  @end smallexample
1660    
1661  @noindent  @noindent
1662  It would be very easy to put the wrong string of characters  It would be very easy to put the wrong string of characters
# Line 1597  To archive a directory, first move to it Line 1687  To archive a directory, first move to it
1687  have followed the previous instructions in this tutorial, you should  have followed the previous instructions in this tutorial, you should
1688  type:  type:
1689    
1690  @example  @smallexample
1691  $ @kbd{cd ..}  $ @kbd{cd ..}
1692  $  $
1693  @end example  @end smallexample
1694    
1695  @noindent  @noindent
1696  This will put you into the directory which contains @file{practice},  This will put you into the directory which contains @file{practice},
# Line 1608  i.e. your home directory.  Once in the s Line 1698  i.e. your home directory.  Once in the s
1698  specify the subdirectory, @file{practice}, as a file name argument.  To  specify the subdirectory, @file{practice}, as a file name argument.  To
1699  store @file{practice} in the new archive file @file{music.tar}, type:  store @file{practice} in the new archive file @file{music.tar}, type:
1700    
1701  @example  @smallexample
1702  $ @kbd{tar --create --verbose --file=music.tar practice}  $ @kbd{tar --create --verbose --file=music.tar practice}
1703  @end example  @end smallexample
1704    
1705  @noindent  @noindent
1706  @command{tar} should output:  @command{tar} should output:
1707    
1708  @example  @smallexample
1709  practice/  practice/
1710  practice/blues  practice/blues
1711  practice/folk  practice/folk
1712  practice/jazz  practice/jazz
1713  practice/collection.tar  practice/collection.tar
1714  @end example  @end smallexample
1715    
1716  Note that the archive thus created is not in the subdirectory  Note that the archive thus created is not in the subdirectory
1717  @file{practice}, but rather in the current working directory---the  @file{practice}, but rather in the current working directory---the
# Line 1639  into the file system). Line 1729  into the file system).
1729    
1730  If you give @command{tar} a command such as  If you give @command{tar} a command such as
1731    
1732  @example  @smallexample
1733  $ @kbd{tar --create --file=foo.tar .}  $ @kbd{tar --create --file=foo.tar .}
1734  @end example  @end smallexample
1735    
1736  @noindent  @noindent
1737  @command{tar} will report @samp{tar: ./foo.tar is the archive; not  @command{tar} will report @samp{tar: ./foo.tar is the archive; not
# Line 1650  dumped}.  This happens because @command{ Line 1740  dumped}.  This happens because @command{
1740  it.  Then, when @command{tar} attempts to add all the files in the  it.  Then, when @command{tar} attempts to add all the files in the
1741  directory @file{.} to the archive, it notices that the file  directory @file{.} to the archive, it notices that the file
1742  @file{./foo.tar} is the same as the archive @file{foo.tar}, and skips  @file{./foo.tar} is the same as the archive @file{foo.tar}, and skips
1743  it.  (It makes no sense to put an archive into itself.)  @acronym{GNU}  it.  (It makes no sense to put an archive into itself.)  @GNUTAR{}
1744  @command{tar} will continue in this case, and create the archive  will continue in this case, and create the archive
1745  normally, except for the exclusion of that one file.  (@emph{Please  normally, except for the exclusion of that one file.  (@emph{Please
1746  note:} Other versions of @command{tar} are not so clever; they will  note:} Other versions of @command{tar} are not so clever; they will
1747  enter an infinite loop when this happens, so you should not depend on  enter an infinite loop when this happens, so you should not depend on
1748  this behavior unless you are certain you are running @acronym{GNU}  this behavior unless you are certain you are running @GNUTAR{}.)
1749  @command{tar}.)  @FIXME{bob doesn't like this sentence, since he does    @FIXME{bob doesn't like this sentence, since he does
1750  it all the time, and we've been doing it in the editing passes for  it all the time, and we've been doing it in the editing passes for
1751  this manual: In general, make sure that the archive is not inside a  this manual: In general, make sure that the archive is not inside a
1752  directory being dumped.}  directory being dumped.}
# Line 1671  as various attributes of the files at th Line 1761  as various attributes of the files at th
1761  example, you can examine the archive @file{collection.tar} that you  example, you can examine the archive @file{collection.tar} that you
1762  created in the last section with the command,  created in the last section with the command,
1763    
1764  @example  @smallexample
1765  $ @kbd{tar --list --file=collection.tar}  $ @kbd{tar --list --file=collection.tar}
1766  @end example  @end smallexample
1767    
1768  @noindent  @noindent
1769  The output of @command{tar} would then be:  The output of @command{tar} would then be:
1770    
1771  @example  @smallexample
1772  blues  blues
1773  folk  folk
1774  jazz  jazz
1775  @end example  @end smallexample
1776    
1777  @FIXME{we hope this will change.  if it doesn't, need to show the  @FIXME{we hope this will change.  if it doesn't, need to show the
1778  creation of bfiles somewhere above!!! : }  creation of bfiles somewhere above!!! : }
# Line 1690  creation of bfiles somewhere above!!! : Line 1780  creation of bfiles somewhere above!!! :
1780  @noindent  @noindent
1781  The archive @file{bfiles.tar} would list as follows:  The archive @file{bfiles.tar} would list as follows:
1782    
1783  @example  @smallexample
1784  ./birds  ./birds
1785  baboon  baboon
1786  ./box  ./box
1787  @end example  @end smallexample
1788    
1789  @noindent  @noindent
1790  Be sure to use a @value{op-file} option just as with @value{op-create}  Be sure to use a @value{op-file} option just as with @value{op-create}
# Line 1707  showing owner, file size, and so forth. Line 1797  showing owner, file size, and so forth.
1797  If you had used @value{op-verbose} mode, the example above would look  If you had used @value{op-verbose} mode, the example above would look
1798  like:  like:
1799    
1800  @example  @smallexample
1801  $ @kbd{tar --list --verbose --file=collection.tar folk}  $ @kbd{tar --list --verbose --file=collection.tar folk}
1802  -rw-rw-rw- myself user 62 1990-05-23 10:55 folk  -rw-rw-rw- myself user 62 1990-05-23 10:55 folk
1803  @end example  @end smallexample
1804    
1805  @cindex File name arguments, using @code{--list} with  @cindex File name arguments, using @code{--list} with
1806  @cindex @code{--list} with file name arguments  @cindex @code{--list} with file name arguments
# Line 1760  use the directory name as a file name ar Line 1850  use the directory name as a file name ar
1850  For example, to find out about files in the directory @file{practice}, in  For example, to find out about files in the directory @file{practice}, in
1851  the archive file @file{music.tar}, type:  the archive file @file{music.tar}, type:
1852    
1853  @example  @smallexample
1854  $ @kbd{tar --list --verbose --file=music.tar practice}  $ @kbd{tar --list --verbose --file=music.tar practice}
1855  @end example  @end smallexample
1856    
1857  @command{tar} responds:  @command{tar} responds:
1858    
1859  @example  @smallexample
1860  drwxrwxrwx myself user 0 1990-05-31 21:49 practice/  drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
1861  -rw-rw-rw- myself user 42 1990-05-21 13:29 practice/blues  -rw-rw-rw- myself user 42 1990-05-21 13:29 practice/blues
1862  -rw-rw-rw- myself user 62 1990-05-23 10:55 practice/folk  -rw-rw-rw- myself user 62 1990-05-23 10:55 practice/folk
1863  -rw-rw-rw- myself user 40 1990-05-21 13:30 practice/jazz  -rw-rw-rw- myself user 40 1990-05-21 13:30 practice/jazz
1864  -rw-rw-rw- myself user 10240 1990-05-31 21:49 practice/collection.tar  -rw-rw-rw- myself user 10240 1990-05-31 21:49 practice/collection.tar
1865  @end example  @end smallexample
1866    
1867  When you use a directory name as a file name argument, @command{tar} acts on  When you use a directory name as a file name argument, @command{tar} acts on
1868  all the files (including sub-directories) in that directory.  all the files (including sub-directories) in that directory.
# Line 1812  long form of the operation without affec Line 1902  long form of the operation without affec
1902  To extract an entire archive, specify the archive file name only, with  To extract an entire archive, specify the archive file name only, with
1903  no individual file names as arguments.  For example,  no individual file names as arguments.  For example,
1904    
1905  @example  @smallexample
1906  $ @kbd{tar -xvf collection.tar}  $ @kbd{tar -xvf collection.tar}
1907  @end example  @end smallexample
1908    
1909  @noindent  @noindent
1910  produces this:  produces this:
1911    
1912  @example  @smallexample
1913  -rw-rw-rw- me user     28 1996-10-18 16:31 jazz  -rw-rw-rw- me user     28 1996-10-18 16:31 jazz
1914  -rw-rw-rw- me user     21 1996-09-23 16:44 blues  -rw-rw-rw- me user     21 1996-09-23 16:44 blues
1915  -rw-rw-rw- me user     20 1996-09-23 16:44 folk  -rw-rw-rw- me user     20 1996-09-23 16:44 folk
1916  @end example  @end smallexample
1917    
1918  @node extracting files  @node extracting files
1919  @subsection Extracting Specific Files  @subsection Extracting Specific Files
# Line 1843  the files in the directory again. Line 1933  the files in the directory again.
1933  You can now extract the member @file{blues} from the archive file  You can now extract the member @file{blues} from the archive file
1934  @file{collection.tar} like this:  @file{collection.tar} like this:
1935    
1936  @example  @smallexample
1937  $ @kbd{tar --extract --file=collection.tar blues}  $ @kbd{tar --extract --file=collection.tar blues}
1938  @end example  @end smallexample
1939    
1940  @noindent  @noindent
1941  If you list the files in the directory again, you will see that the file  If you list the files in the directory again, you will see that the file
# Line 1906  don't give any file names as arguments a Line 1996  don't give any file names as arguments a
1996  @file{music.tar}.  To extract only the files you deleted, use the  @file{music.tar}.  To extract only the files you deleted, use the
1997  following command:  following command:
1998    
1999  @example  @smallexample
2000  $ @kbd{tar -xvf music.tar practice/folk practice/jazz}  $ @kbd{tar -xvf music.tar practice/folk practice/jazz}
2001  @end example  @end smallexample
2002    
2003  @FIXME{need to show tar's response; used verbose above.  also, here's a  @FIXME{need to show tar's response; used verbose above.  also, here's a
2004  good place to demonstrate the -v -v thing.  have to write that up  good place to demonstrate the -v -v thing.  have to write that up
# Line 1934  For example, if @file{untrusted.tar} cam Line 2024  For example, if @file{untrusted.tar} cam
2024  Internet, and you don't necessarily trust its contents, you can  Internet, and you don't necessarily trust its contents, you can
2025  extract it as follows:  extract it as follows:
2026    
2027  @example  @smallexample
2028  $ @kbd{mkdir newdir}  $ @kbd{mkdir newdir}
2029  $ @kbd{cd newdir}  $ @kbd{cd newdir}
2030  $ @kbd{tar -xvf ../untrusted.tar}  $ @kbd{tar -xvf ../untrusted.tar}
2031  @end example  @end smallexample
2032    
2033  @node failing commands  @node failing commands
2034  @subsection Commands That Will Fail  @subsection Commands That Will Fail
# Line 1948  they won't work. Line 2038  they won't work.
2038    
2039  If you try to use this command,  If you try to use this command,
2040    
2041  @example  @smallexample
2042  $ @kbd{tar -xvf music.tar folk jazz}  $ @kbd{tar -xvf music.tar folk jazz}
2043  @end example  @end smallexample
2044    
2045  @noindent  @noindent
2046  you will get the following response:  you will get the following response:
2047    
2048  @example  @smallexample
2049  tar: folk: Not found in archive  tar: folk: Not found in archive
2050  tar: jazz: Not found in archive  tar: jazz: Not found in archive
2051  $  $
2052  @end example  @end smallexample
2053    
2054  @noindent  @noindent
2055  This is because these files were not originally @emph{in} the parent  This is because these files were not originally @emph{in} the parent
2056  directory @file{..}, where the archive is located; they were in the  directory @file{..}, where the archive is located; they were in the
2057  @file{practice} directory, and their file names reflect this:  @file{practice} directory, and their file names reflect this:
2058    
2059  @example  @smallexample
2060  $ @kbd{tar -tvf music.tar}  $ @kbd{tar -tvf music.tar}
2061  practice/folk  practice/folk
2062  practice/jazz  practice/jazz
2063  practice/rock  practice/rock
2064  @end example  @end smallexample
2065    
2066  @FIXME{make sure the above works when going through the examples in  @FIXME{make sure the above works when going through the examples in
2067  order...}  order...}
# Line 1979  order...} Line 2069  order...}
2069  @noindent  @noindent
2070  Likewise, if you try to use this command,  Likewise, if you try to use this command,
2071    
2072  @example  @smallexample
2073  $ @kbd{tar -tvf music.tar folk jazz}  $ @kbd{tar -tvf music.tar folk jazz}
2074  @end example  @end smallexample
2075    
2076  @noindent  @noindent
2077  you would get a similar response.  Members with those names are not in the  you would get a similar response.  Members with those names are not in the
# Line 2000  use @w{@kbd{tar --list --verbose}} to li Line 2090  use @w{@kbd{tar --list --verbose}} to li
2090  be in the rest of the manual.}  be in the rest of the manual.}
2091    
2092  @node tar invocation  @node tar invocation
2093  @chapter Invoking @acronym{GNU} @command{tar}  @chapter Invoking @GNUTAR{}
2094  @UNREVISED  @UNREVISED
2095    
2096  This chapter is about how one invokes the @acronym{GNU} @command{tar}  This chapter is about how one invokes the @GNUTAR{}
2097  command, from the command synopsis (@pxref{Synopsis}).  There are  command, from the command synopsis (@pxref{Synopsis}).  There are
2098  numerous options, and many styles for writing them.  One mandatory  numerous options, and many styles for writing them.  One mandatory
2099  option specifies the operation @command{tar} should perform  option specifies the operation @command{tar} should perform
# Line 2038  and @value{op-interactive} options (@pxr Line 2128  and @value{op-interactive} options (@pxr
2128  @node Synopsis  @node Synopsis
2129  @section General Synopsis of @command{tar}  @section General Synopsis of @command{tar}
2130    
2131  The @acronym{GNU} @command{tar} program is invoked as either one of:  The @GNUTAR{} program is invoked as either one of:
2132    
2133  @example  @smallexample
2134  @kbd{tar @var{option}@dots{} [@var{name}]@dots{}}  @kbd{tar @var{option}@dots{} [@var{name}]@dots{}}
2135  @kbd{tar @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}}  @kbd{tar @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}}
2136  @end example  @end smallexample
2137    
2138  The second form is for when old options are being used.  The second form is for when old options are being used.
2139    
# Line 2105  on the entire contents of the archive. Line 2195  on the entire contents of the archive.
2195    
2196  @cindex exit status  @cindex exit status
2197  @cindex return status  @cindex return status
2198  Besides successful exits, @acronym{GNU} @command{tar} may fail for  Besides successful exits, @GNUTAR{} may fail for
2199  many reasons.  Some reasons correspond to bad usage, that is, when the  many reasons.  Some reasons correspond to bad usage, that is, when the
2200  @command{tar} command is improperly written.  Errors may be  @command{tar} command is improperly written.  Errors may be
2201  encountered later, while encountering an error processing the archive  encountered later, while encountering an error processing the archive
# Line 2117  All abnormal exits, whether immediate or Line 2207  All abnormal exits, whether immediate or
2207  clearly diagnosed on @code{stderr}, after a line stating the nature of  clearly diagnosed on @code{stderr}, after a line stating the nature of
2208  the error.  the error.
2209    
2210  @acronym{GNU} @command{tar} returns only a few exit statuses.  I'm really  @GNUTAR{} returns only a few exit statuses.  I'm really
2211  aiming simplicity in that area, for now.  If you are not using the  aiming simplicity in that area, for now.  If you are not using the
2212  @value{op-compare} option, zero means that everything went well, besides  @value{op-compare} option, zero means that everything went well, besides
2213  maybe innocuous warnings.  Nonzero means that something went wrong.  maybe innocuous warnings.  Nonzero means that something went wrong.
# Line 2127  remote operations, where it may be 128. Line 2217  remote operations, where it may be 128.
2217  @node using tar options  @node using tar options
2218  @section Using @command{tar} Options  @section Using @command{tar} Options
2219    
2220  @acronym{GNU} @command{tar} has a total of eight operating modes which  @GNUTAR{} has a total of eight operating modes which
2221  allow you to perform a variety of tasks.  You are required to choose  allow you to perform a variety of tasks.  You are required to choose
2222  one operating mode each time you employ the @command{tar} program by  one operating mode each time you employ the @command{tar} program by
2223  specifying one, and only one operation as an argument to the  specifying one, and only one operation as an argument to the
# Line 2232  Mnemonic options are meant to be obvious Line 2322  Mnemonic options are meant to be obvious
2322  meanings are generally easier to discern than those of their  meanings are generally easier to discern than those of their
2323  corresponding short options (see below).  For example:  corresponding short options (see below).  For example:
2324    
2325  @example  @smallexample
2326  $ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0}  $ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0}
2327  @end example  @end smallexample
2328    
2329  @noindent  @noindent
2330  gives a fairly good set of hints about what the command does, even  gives a fairly good set of hints about what the command does, even
# Line 2279  When the options are separated, the argu Line 2369  When the options are separated, the argu
2369  an argument directly follows that option, as is usual for Unix programs.  an argument directly follows that option, as is usual for Unix programs.
2370  For example:  For example:
2371    
2372  @example  @smallexample
2373  $ @kbd{tar -c -v -b 20 -f /dev/rmt0}  $ @kbd{tar -c -v -b 20 -f /dev/rmt0}
2374  @end example  @end smallexample
2375    
2376  If you reorder short options' locations, be sure to move any arguments  If you reorder short options' locations, be sure to move any arguments
2377  that belong to them.  If you do not move the arguments properly, you may  that belong to them.  If you do not move the arguments properly, you may
# Line 2311  all the associated arguments follow, in Line 2401  all the associated arguments follow, in
2401  Thus, the example given previously could also be written in the old  Thus, the example given previously could also be written in the old
2402  style as follows:  style as follows:
2403    
2404  @example  @smallexample
2405  $ @kbd{tar cvbf 20 /dev/rmt0}  $ @kbd{tar cvbf 20 /dev/rmt0}
2406  @end example  @end smallexample
2407    
2408  @noindent  @noindent
2409  Here, @samp{20} is the argument of @samp{-b} and @samp{/dev/rmt0} is  Here, @samp{20} is the argument of @samp{-b} and @samp{/dev/rmt0} is
# Line 2334  sure to reorder any corresponding argume Line 2424  sure to reorder any corresponding argume
2424  This old way of writing @command{tar} options can surprise even experienced  This old way of writing @command{tar} options can surprise even experienced
2425  users.  For example, the two commands:  users.  For example, the two commands:
2426    
2427  @example  @smallexample
2428  @kbd{tar cfz archive.tar.gz file}  @kbd{tar cfz archive.tar.gz file}
2429  @kbd{tar -cfz archive.tar.gz file}  @kbd{tar -cfz archive.tar.gz file}
2430  @end example  @end smallexample
2431    
2432  @noindent  @noindent
2433  are quite different.  The first example uses @file{archive.tar.gz} as  are quite different.  The first example uses @file{archive.tar.gz} as
# Line 2350  Old options are kept for compatibility w Line 2440  Old options are kept for compatibility w
2440  This second example could be corrected in many ways, among which the  This second example could be corrected in many ways, among which the
2441  following are equivalent:  following are equivalent:
2442    
2443  @example  @smallexample
2444  @kbd{tar -czf archive.tar.gz file}  @kbd{tar -czf archive.tar.gz file}
2445  @kbd{tar -cf archive.tar.gz -z file}  @kbd{tar -cf archive.tar.gz -z file}
2446  @kbd{tar cf archive.tar.gz -z file}  @kbd{tar cf archive.tar.gz -z file}
2447  @end example  @end smallexample
2448    
2449  @FIXME{still could explain this better; it's redundant:}  @FIXME{still could explain this better; it's redundant:}
2450    
2451  @cindex option syntax, traditional  @cindex option syntax, traditional
2452  As far as we know, all @command{tar} programs, @acronym{GNU} and  As far as we know, all @command{tar} programs, @acronym{GNU} and
2453  non-@acronym{GNU}, support old options.  @acronym{GNU} @command{tar}  non-@acronym{GNU}, support old options.  @GNUTAR{}
2454  supports them not only for historical reasons, but also because many  supports them not only for historical reasons, but also because many
2455  people are used to them.  For compatibility with Unix @command{tar},  people are used to them.  For compatibility with Unix @command{tar},
2456  the first argument is always treated as containing command and option  the first argument is always treated as containing command and option
# Line 2373  equivalent to @w{@samp{tar -c}:} both of Line 2463  equivalent to @w{@samp{tar -c}:} both of
2463    
2464  All three styles may be intermixed in a single @command{tar} command,  All three styles may be intermixed in a single @command{tar} command,
2465  so long as the rules for each style are fully  so long as the rules for each style are fully
2466  respected@footnote{Before @acronym{GNU} @command{tar} version 1.11.6,  respected@footnote{Before @GNUTAR{} version 1.11.6,
2467  a bug prevented intermixing old style options with mnemonic options in  a bug prevented intermixing old style options with mnemonic options in
2468  some cases.}.  Old style options and either of the modern styles of  some cases.}.  Old style options and either of the modern styles of
2469  options may be mixed within a single @command{tar} command.  However,  options may be mixed within a single @command{tar} command.  However,
# Line 2388  style options. Line 2478  style options.
2478  For example, all the following commands are wholly equivalent, and  For example, all the following commands are wholly equivalent, and
2479  illustrate the many combinations and orderings of option styles.  illustrate the many combinations and orderings of option styles.
2480    
2481  @example  @smallexample
2482  @kbd{tar --create --file=archive.tar}  @kbd{tar --create --file=archive.tar}
2483  @kbd{tar --create -f archive.tar}  @kbd{tar --create -f archive.tar}
2484  @kbd{tar --create -farchive.tar}  @kbd{tar --create -farchive.tar}
# Line 2410  illustrate the many combinations and ord Line 2500  illustrate the many combinations and ord
2500  @kbd{tar f archive.tar --create}  @kbd{tar f archive.tar --create}
2501  @kbd{tar f archive.tar -c}  @kbd{tar f archive.tar -c}
2502  @kbd{tar fc archive.tar}  @kbd{tar fc archive.tar}
2503  @end example  @end smallexample
2504    
2505  On the other hand, the following commands are @emph{not} equivalent to  On the other hand, the following commands are @emph{not} equivalent to
2506  the previous set:  the previous set:
2507    
2508  @example  @smallexample
2509  @kbd{tar -f -c archive.tar}  @kbd{tar -f -c archive.tar}
2510  @kbd{tar -fc archive.tar}  @kbd{tar -fc archive.tar}
2511  @kbd{tar -fcarchive.tar}  @kbd{tar -fcarchive.tar}
2512  @kbd{tar -farchive.tarc}  @kbd{tar -farchive.tarc}
2513  @kbd{tar cfarchive.tar}  @kbd{tar cfarchive.tar}
2514  @end example  @end smallexample
2515    
2516  @noindent  @noindent
2517  These last examples mean something completely different from what the  These last examples mean something completely different from what the
# Line 2587  indication that @command{tar} is still r Line 2677  indication that @command{tar} is still r
2677  @samp{--verbose} output.  @FIXME-xref{}  @samp{--verbose} output.  @FIXME-xref{}
2678    
2679  @item --check-links  @item --check-links
2680    @itemx -l
2681  If this option was given, @command{tar} will check the number of links  If this option was given, @command{tar} will check the number of links
2682  dumped for each processed file. If this number does not match the  dumped for each processed file. If this number does not match the
2683  total number of hard links for the file, a warning message will be  total number of hard links for the file, a warning message will be
2684  output.  output.
2685    
2686    Future versions will take @option{-l} as a short version of
2687    @option{--check-links}. However, current release still retains the old
2688    semantics for @option{-l}.
2689    
2690    @xref{Current status}, for more information.
2691    
2692  @item --compress  @item --compress
2693  @itemx --uncompress  @itemx --uncompress
2694  @itemx -Z  @itemx -Z
# Line 2650  Forces @command{tar} to interpret the fi Line 2746  Forces @command{tar} to interpret the fi
2746  as a local file, even if it looks like a remote tape drive name.  as a local file, even if it looks like a remote tape drive name.
2747  @FIXME-xref{}  @FIXME-xref{}
2748    
2749    @item --format=@var{format}
2750    
2751    Selects output archive format. @var{Format} may be one of the
2752    following:
2753    
2754    @table @samp
2755    @item v7
2756    Tells @command{tar} to create an archive that is compatible with Unix V7
2757    @command{tar}.
2758    
2759    @item oldgnu
2760    Tells @command{tar} to create an archive that is compatible with GNU
2761    @command{tar} version 1.12 or earlier.
2762    
2763    @item posix
2764    Tells @command{tar} to create POSIX.1-2001 archive.
2765    
2766    @item gnu
2767    Tells @command{tar} to create archive in GNU format.
2768    @end table
2769    
2770  @item --group=@var{group}  @item --group=@var{group}
2771    
2772  Files added to the @command{tar} archive will have a group id of @var{group},  Files added to the @command{tar} archive will have a group id of @var{group},
# Line 2659  a decimal numeric group ID.  @FIXME-xref Line 2776  a decimal numeric group ID.  @FIXME-xref
2776    
2777  Also see the comments for the @value{op-owner} option.  Also see the comments for the @value{op-owner} option.
2778    
 @item --gunzip  
   
 (See @samp{--gzip}.) @FIXME-pxref{}  
   
2779  @item --gzip  @item --gzip
2780  @itemx --gunzip  @itemx --gunzip
2781  @itemx --ungzip  @itemx --ungzip
# Line 2798  With this option, @command{tar} will not Line 2911  With this option, @command{tar} will not
2911  @FIXME-xref{}  @FIXME-xref{}
2912    
2913  @item --no-same-owner  @item --no-same-owner
2914    @itemx -o
2915    
2916  When extracting an archive, do not attempt to preserve the owner  When extracting an archive, do not attempt to preserve the owner
2917  specified in the @command{tar} archive.  This the default behavior  specified in the @command{tar} archive.  This the default behavior
# Line 2830  This option will notify @command{tar} th Line 2944  This option will notify @command{tar} th
2944  and group IDs when creating a @command{tar} file, rather than names.  and group IDs when creating a @command{tar} file, rather than names.
2945  @FIXME-xref{}  @FIXME-xref{}
2946    
2947  @item --old-archive  @item -o
2948    When extracting files, this option is a synonim for
2949    @option{--no-same-owner}, i.e. it prevents @command{tar} from
2950    restoring ownership of files being extracted.
2951    
2952    When creating an archive, @option{-o} is a synonim for
2953    @option{--old-archive}. This behavior is for compatibility
2954    with previous versions of @GNUTAR{}, and will be
2955    removed in the future releases.
2956    
2957    @xref{Current status}, for more information.
2958    
2959    @item --occurrence[=@var{number}]
2960    
2961    This option can be used in conjunction with one of the subcommands
2962    @option{--delete}, @option{--diff}, @option{--extract} or
2963    @option{--list} when a list of files is given either on the command
2964    line or via @option{-T} option.
2965    
2966  (See @samp{--portability}.) @FIXME-pxref{}  This option instructs @command{tar} to process only the @var{number}th
2967    occurrence of each named file. @var{Number} defaults to 1, so
2968    
2969    @smallexample
2970    tar -x -f archive.tar --occurrence filename
2971    @end smallexample
2972    
2973    @noindent
2974    will extract the first occurrence of @file{filename} from @file{archive.tar}
2975    and will terminate without scanning to the end of the archive.
2976    
2977    @item --old-archive
2978    Synonim for @option{--format=v7}.
2979    
2980  @item --one-file-system  @item --one-file-system
2981  @itemx -l  @itemx -l
   
2982  Used when creating an archive.  Prevents @command{tar} from recursing into  Used when creating an archive.  Prevents @command{tar} from recursing into
2983  directories that are on different file systems from the current  directories that are on different file systems from the current
2984  directory.  @FIXME-xref{}  directory.
2985    
2986    Earlier versions of @GNUTAR{} understood @option{-l} as a
2987    synonim for @option{--one-file-system}. Although such usage is still
2988    allowed in the present version, it is @emph{strongly discouraged}.
2989    The future versions of @GNUTAR{} will use @option{-l} as
2990    a synonim for @option{--check-links}.
2991    
2992    @xref{Current status}, for more information.
2993    
2994  @item --overwrite  @item --overwrite
2995    
# Line 2868  This option does not affect extraction f Line 3018  This option does not affect extraction f
3018    
3019  @item --portability  @item --portability
3020  @itemx --old-archive  @itemx --old-archive
3021  @itemx -o  Synonim for @option{--format=v7}.
   
 Tells @command{tar} to create an archive that is compatible with Unix V7  
 @command{tar}.  @FIXME-xref{}  
3022    
3023  @item --posix  @item --posix
3024    Same as @option{--format=posix}.
 Instructs @command{tar} to create a @sc{posix} compliant @command{tar}  
 archive.  @FIXME-xref{}  
3025    
3026  @item --preserve  @item --preserve
3027    
# Line 2967  This option affects extraction only; @co Line 3112  This option affects extraction only; @co
3112  files in the archive until it finds one that matches @var{name}.  files in the archive until it finds one that matches @var{name}.
3113  @xref{Scarce}.  @xref{Scarce}.
3114    
3115    @item --strip-path=@var{number}
3116    Strip given @var{number} of leading components from file names before
3117    extraction. For example, if archive @file{archive.tar} contained
3118    @file{/some/file/name}, then running
3119    
3120    @smallexample
3121    tar --extract --file archive.tar --strip-path=2
3122    @end smallexample
3123    
3124    @noindent
3125    would extracted this file to file @file{name}.
3126    
3127  @item --suffix=@var{suffix}  @item --suffix=@var{suffix}
3128    
3129  Alters the suffix @command{tar} uses when backing up files from the default  Alters the suffix @command{tar} uses when backing up files from the default
# Line 3171  them with the equivalent long option. Line 3328  them with the equivalent long option.
3328    
3329  @item -l  @item -l
3330    
3331  @samp{--one-file-system}  @samp{--one-file-system}. Use of this short option is deprecated. It
3332    is retained for compatibility with the earlier versions of GNU
3333    @command{tar}, and will be changed in future releases.
3334    
3335    @xref{Current status}, for more information.
3336    
3337  @item -m  @item -m
3338    
# Line 3179  them with the equivalent long option. Line 3340  them with the equivalent long option.
3340    
3341  @item -o  @item -o
3342    
3343  @samp{--portability}  When creating --- @samp{--no-same-owner}, when extracting ---
3344    @samp{--portability}.
3345    
3346    The later usage is deprecated. It is retained for compatibility with
3347    the earlier versions of @GNUTAR{}. In the future releases
3348    @option{-o} will be equivalent to @samp{--no-same-owner} only.
3349    
3350  @item -p  @item -p
3351    
# Line 3220  them with the equivalent long option. Line 3386  them with the equivalent long option.
3386  @end table  @end table
3387    
3388  @node help  @node help
3389  @section @acronym{GNU} @command{tar} documentation  @section @GNUTAR{} documentation
3390    
3391  Being careful, the first thing is really checking that you are using  Being careful, the first thing is really checking that you are using
3392  @acronym{GNU} @command{tar}, indeed.  The @value{op-version} option  @GNUTAR{}, indeed.  The @value{op-version} option
3393  will generate a message giving confirmation that you are using  will generate a message giving confirmation that you are using
3394  @acronym{GNU} @command{tar}, with the precise version of @acronym{GNU}  @GNUTAR{}, with the precise version of @GNUTAR{}
3395  @command{tar} you are using.  @command{tar} identifies itself and  you are using.  @command{tar} identifies itself and
3396  prints the version number to the standard output, then immediately  prints the version number to the standard output, then immediately
3397  exits successfully, without doing anything else, ignoring all other  exits successfully, without doing anything else, ignoring all other
3398  options.  For example, @w{@samp{tar --version}} might return:  options.  For example, @w{@samp{tar --version}} might return:
3399    
3400  @example  @smallexample
3401  tar (@acronym{GNU} tar) @value{VERSION}  tar (@acronym{GNU} tar) @value{VERSION}
3402  @end example  @end smallexample
3403    
3404  @noindent  @noindent
3405  The first occurrence of @samp{tar} in the result above is the program  The first occurrence of @samp{tar} in the result above is the program
# Line 3249  paxutils) 3.2}}}. Line 3415  paxutils) 3.2}}}.
3415    
3416  Another thing you might want to do is checking the spelling or meaning  Another thing you might want to do is checking the spelling or meaning
3417  of some particular @command{tar} option, without resorting to this  of some particular @command{tar} option, without resorting to this
3418  manual, for once you have carefully read it.  @acronym{GNU}  manual, for once you have carefully read it.  @GNUTAR{}
3419  @command{tar} has a short help feature, triggerable through the  has a short help feature, triggerable through the
3420  @value{op-help} option.  By using this option, @command{tar} will  @value{op-help} option.  By using this option, @command{tar} will
3421  print a usage message listing all available options on standard  print a usage message listing all available options on standard
3422  output, then exit successfully, without doing anything else and  output, then exit successfully, without doing anything else and
# Line 3258  ignoring all other options.  Even if thi Line 3424  ignoring all other options.  Even if thi
3424  may be several screens long.  So, if you are not using some kind of  may be several screens long.  So, if you are not using some kind of
3425  scrollable window, you might prefer to use something like:  scrollable window, you might prefer to use something like:
3426    
3427  @example  @smallexample
3428  $ @kbd{tar --help | less}  $ @kbd{tar --help | less}
3429  @end example  @end smallexample
3430    
3431  @noindent  @noindent
3432  presuming, here, that you like using @command{less} for a pager.  Other  presuming, here, that you like using @command{less} for a pager.  Other
# Line 3268  popular pagers are @command{more} and @c Line 3434  popular pagers are @command{more} and @c
3434  @var{keyword} which interests you and do not want to read all the  @var{keyword} which interests you and do not want to read all the
3435  @value{op-help} output, another common idiom is doing:  @value{op-help} output, another common idiom is doing:
3436    
3437  @example  @smallexample
3438  tar --help | grep @var{keyword}  tar --help | grep @var{keyword}
3439  @end example  @end smallexample
3440    
3441  @noindent  @noindent
3442  for getting only the pertinent lines.  for getting only the pertinent lines.
# Line 3285  The short help output is quite succinct, Line 3451  The short help output is quite succinct,
3451  back to the full documentation for precise points.  If you are reading  back to the full documentation for precise points.  If you are reading
3452  this paragraph, you already have the @command{tar} manual in some  this paragraph, you already have the @command{tar} manual in some
3453  form.  This manual is available in printed form, as a kind of small  form.  This manual is available in printed form, as a kind of small
3454  book.  It may printed out of the @acronym{GNU} @command{tar}  book.  It may printed out of the @GNUTAR{}
3455  distribution, provided you have @TeX{} already installed somewhere,  distribution, provided you have @TeX{} already installed somewhere,
3456  and a laser printer around.  Just configure the distribution, execute  and a laser printer around.  Just configure the distribution, execute
3457  the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the  the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the
3458  usual way (contact your local guru to know how).  If @acronym{GNU}  usual way (contact your local guru to know how).  If @GNUTAR{}
3459  @command{tar} has been conveniently installed at your place, this  has been conveniently installed at your place, this
3460  manual is also available in interactive, hypertextual form as an Info  manual is also available in interactive, hypertextual form as an Info
3461  file.  Just call @w{@samp{info tar}} or, if you do not have the  file.  Just call @w{@samp{info tar}} or, if you do not have the
3462  @command{info} program handy, use the Info reader provided within  @command{info} program handy, use the Info reader provided within
3463  @acronym{GNU} Emacs, calling @samp{tar} from the main Info menu.  @acronym{GNU} Emacs, calling @samp{tar} from the main Info menu.
3464    
3465  There is currently no @code{man} page for @acronym{GNU} @command{tar}.  There is currently no @code{man} page for @GNUTAR{}.
3466  If you observe such a @code{man} page on the system you are running,  If you observe such a @code{man} page on the system you are running,
3467  either it does not long to @acronym{GNU} @command{tar}, or it has not  either it does not long to @GNUTAR{}, or it has not
3468  been produced by @acronym{GNU}.  Currently, @acronym{GNU}  been produced by @acronym{GNU}.  Currently, @GNUTAR{}
3469  @command{tar} documentation is provided in Texinfo format only, if we  documentation is provided in Texinfo format only, if we
3470  except, of course, the short result of @kbd{tar --help}.  except, of course, the short result of @kbd{tar --help}.
3471    
3472  @node verbose  @node verbose
# Line 3347  causes @command{tar} to print an @samp{l Line 3513  causes @command{tar} to print an @samp{l
3513  in the archive.  The following examples both extract members with  in the archive.  The following examples both extract members with
3514  long list output:  long list output:
3515    
3516  @example  @smallexample
3517  $ @kbd{tar --extract --file=archive.tar --verbose --verbose}  $ @kbd{tar --extract --file=archive.tar --verbose --verbose}
3518  $ @kbd{tar xvv archive.tar}  $ @kbd{tar xvv archive.tar}
3519  @end example  @end smallexample
3520    
3521  Verbose output appears on the standard output except when an archive is  Verbose output appears on the standard output except when an archive is
3522  being written to the standard output, as with @samp{tar --create  being written to the standard output, as with @samp{tar --create
# Line 3391  are triggered when reading blocks full o Line 3557  are triggered when reading blocks full o
3557  file on the archive.  As of now, if the archive if properly terminated  file on the archive.  As of now, if the archive if properly terminated
3558  with a NUL block, the reading of the file may stop before end of file  with a NUL block, the reading of the file may stop before end of file
3559  is met, so the position of end of file will not usually show when  is met, so the position of end of file will not usually show when
3560  @value{op-block-number} is used.  Note that @acronym{GNU}  @value{op-block-number} is used.  Note that @GNUTAR{}
3561  @command{tar} drains the archive before exiting when reading the  drains the archive before exiting when reading the
3562  archive from a pipe.  archive from a pipe.
3563    
3564  This option is especially useful when reading damaged archives, since  This option is especially useful when reading damaged archives, since
# Line 3442  read from that named pipe.  This has the Line 3608  read from that named pipe.  This has the
3608  output free to receive verbose output, all separate from errors.  output free to receive verbose output, all separate from errors.
3609    
3610  @node operations  @node operations
3611  @chapter @acronym{GNU} @command{tar} Operations  @chapter @GNUTAR{} Operations
3612    
3613  @menu  @menu
3614  * Basic tar::  * Basic tar::
# Line 3455  output free to receive verbose output, a Line 3621  output free to receive verbose output, a
3621  @end menu  @end menu
3622    
3623  @node Basic tar  @node Basic tar
3624  @section Basic @acronym{GNU} @command{tar} Operations  @section Basic @GNUTAR{} Operations
3625    
3626  The basic @command{tar} operations, @value{op-create}, @value{op-list} and  The basic @command{tar} operations, @value{op-create}, @value{op-list} and
3627  @value{op-extract}, are currently presented and described in the tutorial  @value{op-extract}, are currently presented and described in the tutorial
# Line 3494  file, which was meant to be saved, is ra Line 3660  file, which was meant to be saved, is ra
3660  @end enumerate  @end enumerate
3661    
3662  So, recognizing the likelihood and the catastrophical nature of these  So, recognizing the likelihood and the catastrophical nature of these
3663  errors, @acronym{GNU} @command{tar} now takes some distance from elegance, and  errors, @GNUTAR{} now takes some distance from elegance, and
3664  cowardly refuses to create an archive when @value{op-create} option is  cowardly refuses to create an archive when @value{op-create} option is
3665  given, there are no arguments besides options, and @value{op-files-from}  given, there are no arguments besides options, and @value{op-files-from}
3666  option is @emph{not} used.  To get around the cautiousness of @acronym{GNU}  option is @emph{not} used.  To get around the cautiousness of @GNUTAR{}
3667  @command{tar} and nevertheless create an archive with nothing in it,  and nevertheless create an archive with nothing in it,
3668  one may still use, as the value for the @value{op-files-from} option,  one may still use, as the value for the @value{op-files-from} option,
3669  a file with no names in it, as shown in the following commands:  a file with no names in it, as shown in the following commands:
3670    
3671  @example  @smallexample
3672  @kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}  @kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
3673  @kbd{tar cfT empty-archive.tar /dev/null}  @kbd{tar cfT empty-archive.tar /dev/null}
3674  @end example  @end smallexample
3675    
3676  @item @value{op-extract}  @item @value{op-extract}
3677    
3678  A socket is stored, within a @acronym{GNU} @command{tar} archive, as a pipe.  A socket is stored, within a @GNUTAR{} archive, as a pipe.
3679    
3680  @item @value{op-list}  @item @value{op-list}
3681    
3682  @acronym{GNU} @command{tar} now shows dates as @samp{1996-08-30},  @GNUTAR{} now shows dates as @samp{1996-08-30},
3683  while it used to show them as @samp{Aug 30 1996}.  (One can revert to  while it used to show them as @samp{Aug 30 1996}.  (One can revert to
3684  the old behavior by defining @code{USE_OLD_CTIME} in @file{src/list.c}  the old behavior by defining @code{USE_OLD_CTIME} in @file{src/list.c}
3685  before reinstalling.)  But preferably, people should get used to ISO  before reinstalling.)  But preferably, people should get used to ISO
# Line 3528  are curious, it contains a detailed expl Line 3694  are curious, it contains a detailed expl
3694  @end table  @end table
3695    
3696  @node Advanced tar  @node Advanced tar
3697  @section Advanced @acronym{GNU} @command{tar} Operations  @section Advanced @GNUTAR{} Operations
3698    
3699  Now that you have learned the basics of using @acronym{GNU}  Now that you have learned the basics of using @GNUTAR{}, you may want
3700  @command{tar}, you may want to learn about further ways in which  to learn about further ways in which @command{tar} can help you.
 @command{tar} can help you.  
3701    
3702  This chapter presents five, more advanced operations which you probably  This chapter presents five, more advanced operations which you probably
3703  won't use on a daily basis, but which serve more specialized functions.  won't use on a daily basis, but which serve more specialized functions.
# Line 3691  Make sure you are in the @file{practice} Line 3856  Make sure you are in the @file{practice}
3856  following @command{tar} command to add @file{rock} to  following @command{tar} command to add @file{rock} to
3857  @file{collection.tar}:  @file{collection.tar}:
3858    
3859  @example  @smallexample
3860  $ @kbd{tar --append --file=collection.tar rock}  $ @kbd{tar --append --file=collection.tar rock}
3861  @end example  @end smallexample
3862    
3863  @noindent  @noindent
3864  If you now use the @value{op-list} operation, you will see that  If you now use the @value{op-list} operation, you will see that
3865  @file{rock} has been added to the archive:  @file{rock} has been added to the archive:
3866    
3867  @example  @smallexample
3868  $ @kbd{tar --list --file=collection.tar}  $ @kbd{tar --list --file=collection.tar}
3869  -rw-rw-rw- me user     28 1996-10-18 16:31 jazz  -rw-rw-rw- me user     28 1996-10-18 16:31 jazz
3870  -rw-rw-rw- me user     21 1996-09-23 16:44 blues  -rw-rw-rw- me user     21 1996-09-23 16:44 blues
3871  -rw-rw-rw- me user     20 1996-09-23 16:44 folk  -rw-rw-rw- me user     20 1996-09-23 16:44 folk
3872  -rw-rw-rw- me user     20 1996-09-23 16:44 rock  -rw-rw-rw- me user     20 1996-09-23 16:44 rock
3873  @end example  @end smallexample
3874    
3875  @FIXME{in theory, dan will (soon) try to turn this node into what it's  @FIXME{in theory, dan will (soon) try to turn this node into what it's
3876  title claims it will become...}  title claims it will become...}
# Line 3743  newer version when it is extracted. Line 3908  newer version when it is extracted.
3908  You can append the new, changed copy of the file @file{blues} to the  You can append the new, changed copy of the file @file{blues} to the
3909  archive in this way:  archive in this way:
3910    
3911  @example  @smallexample
3912  $ @kbd{tar --append --verbose --file=collection.tar blues}  $ @kbd{tar --append --verbose --file=collection.tar blues}
3913  blues  blues
3914  @end example  @end smallexample
3915    
3916  @noindent  @noindent
3917  Because you specified the @samp{--verbose} option, @command{tar} has  Because you specified the @samp{--verbose} option, @command{tar} has
3918  printed the name of the file being appended as it was acted on.  Now  printed the name of the file being appended as it was acted on.  Now
3919  list the contents of the archive:  list the contents of the archive:
3920    
3921  @example  @smallexample
3922  $ @kbd{tar --list --verbose --file=collection.tar}  $ @kbd{tar --list --verbose --file=collection.tar}
3923  -rw-rw-rw- me user     28 1996-10-18 16:31 jazz  -rw-rw-rw- me user     28 1996-10-18 16:31 jazz
3924  -rw-rw-rw- me user     21 1996-09-23 16:44 blues  -rw-rw-rw- me user     21 1996-09-23 16:44 blues
3925  -rw-rw-rw- me user     20 1996-09-23 16:44 folk  -rw-rw-rw- me user     20 1996-09-23 16:44 folk
3926  -rw-rw-rw- me user     20 1996-09-23 16:44 rock  -rw-rw-rw- me user     20 1996-09-23 16:44 rock
3927  -rw-rw-rw- me user     58 1996-10-24 18:30 blues  -rw-rw-rw- me user     58 1996-10-24 18:30 blues
3928  @end example  @end smallexample
3929    
3930  @noindent  @noindent
3931  The newest version of @file{blues} is now at the end of the archive  The newest version of @file{blues} is now at the end of the archive
# Line 3819  the @samp{update} operation and the @val Line 3984  the @samp{update} operation and the @val
3984  using the names of all the files in the practice directory as file name  using the names of all the files in the practice directory as file name
3985  arguments:  arguments:
3986    
3987  @example  @smallexample
3988  $ @kbd{tar --update -v -f collection.tar blues folk rock classical}  $ @kbd{tar --update -v -f collection.tar blues folk rock classical}
3989  blues  blues
3990  classical  classical
3991  $  $
3992  @end example  @end smallexample
3993    
3994  @noindent  @noindent
3995  Because we have specified verbose mode, @command{tar} prints out the names  Because we have specified verbose mode, @command{tar} prints out the names
# Line 3842  information about tapes. Line 4007  information about tapes.
4007    
4008  @value{op-update} is not suitable for performing backups for two  @value{op-update} is not suitable for performing backups for two
4009  reasons: it does not change directory content entries, and it  reasons: it does not change directory content entries, and it
4010  lengthens the archive every time it is used.  The @acronym{GNU}  lengthens the archive every time it is used.  The @GNUTAR{}
4011  @command{tar} options intended specifically for backups are more  options intended specifically for backups are more
4012  efficient.  If you need to run backups, please consult @ref{Backups}.  efficient.  If you need to run backups, please consult @ref{Backups}.
4013    
4014  @node concatenate  @node concatenate
# Line 3868  To demonstrate how @samp{--concatenate} Line 4033  To demonstrate how @samp{--concatenate}
4033  called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant  called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
4034  files from @file{practice}:  files from @file{practice}:
4035    
4036  @example  @smallexample
4037  $ @kbd{tar -cvf bluesrock.tar blues rock}  $ @kbd{tar -cvf bluesrock.tar blues rock}
4038  blues  blues
4039  classical  classical
4040  $ @kbd{tar -cvf folkjazz.tar folk jazz}  $ @kbd{tar -cvf folkjazz.tar folk jazz}
4041  folk  folk
4042  jazz  jazz
4043  @end example  @end smallexample
4044    
4045  @noindent  @noindent
4046  If you like, You can run @samp{tar --list} to make sure the archives  If you like, You can run @samp{tar --list} to make sure the archives
4047  contain what they are supposed to:  contain what they are supposed to:
4048    
4049  @example  @smallexample
4050  $ @kbd{tar -tvf bluesrock.tar}  $ @kbd{tar -tvf bluesrock.tar}
4051  -rw-rw-rw- melissa user    105 1997-01-21 19:42 blues  -rw-rw-rw- melissa user    105 1997-01-21 19:42 blues
4052  -rw-rw-rw- melissa user     33 1997-01-20 15:34 rock  -rw-rw-rw- melissa user     33 1997-01-20 15:34 rock
4053  $ @kbd{tar -tvf folkjazz.tar}  $ @kbd{tar -tvf folkjazz.tar}
4054  -rw-rw-rw- melissa user     20 1996-09-23 16:44 folk  -rw-rw-rw- melissa user     20 1996-09-23 16:44 folk
4055  -rw-rw-rw- melissa user     65 1997-01-30 14:15 jazz  -rw-rw-rw- melissa user     65 1997-01-30 14:15 jazz
4056  @end example  @end smallexample
4057    
4058  We can concatenate these two archives with @command{tar}:  We can concatenate these two archives with @command{tar}:
4059    
4060  @example  @smallexample
4061  $ @kbd{cd ..}  $ @kbd{cd ..}
4062  $ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}  $ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
4063  @end example  @end smallexample
4064    
4065  If you now list the contents of the @file{bluesclass.tar}, you will see  If you now list the contents of the @file{bluesclass.tar}, you will see
4066  that now it also contains the archive members of @file{jazzfolk.tar}:  that now it also contains the archive members of @file{jazzfolk.tar}:
4067    
4068  @example  @smallexample
4069  $ @kbd{tar --list --file=bluesrock.tar}  $ @kbd{tar --list --file=bluesrock.tar}
4070  blues  blues
4071  rock  rock
4072  jazz  jazz
4073  folk  folk
4074  @end example  @end smallexample
4075    
4076  When you use @samp{--concatenate}, the source and target archives must  When you use @samp{--concatenate}, the source and target archives must
4077  already exist and must have been created using compatible format  already exist and must have been created using compatible format
# Line 3974  To delete all versions of the file @file Line 4139  To delete all versions of the file @file
4139  @file{collection.tar} in the @file{practice} directory, make sure you  @file{collection.tar} in the @file{practice} directory, make sure you
4140  are in that directory, and then,  are in that directory, and then,
4141    
4142  @example  @smallexample
4143  $ @kbd{tar --list --file=collection.tar}  $ @kbd{tar --list --file=collection.tar}
4144  blues  blues
4145  folk  folk
# Line 3991  folk Line 4156  folk
4156  jazz  jazz
4157  rock  rock
4158  $  $
4159  @end example  @end smallexample
4160    
4161  @FIXME{I changed the order of these nodes around and haven't had a chance  @FIXME{I changed the order of these nodes around and haven't had a chance
4162  to fix the above example's results, yet.  I have to play with this and  to fix the above example's results, yet.  I have to play with this and
# Line 4024  The following example compares the archi Line 4189  The following example compares the archi
4189  files of the same name in the file system.  (Note that there is no file,  files of the same name in the file system.  (Note that there is no file,
4190  @file{funk}; @command{tar} will report an error message.)  @file{funk}; @command{tar} will report an error message.)
4191    
4192  @example  @smallexample
4193  $ @kbd{tar --compare --file=bluesrock.tar rock blues funk}  $ @kbd{tar --compare --file=bluesrock.tar rock blues funk}
4194  rock  rock
4195  blues  blues
4196  tar: funk not found in archive  tar: funk not found in archive
4197  @end example  @end smallexample
4198    
4199  @noindent  @noindent
4200  @FIXME{what does this actually depend on?  i'm making a guess,  @FIXME{what does this actually depend on?  i'm making a guess,
# Line 4037  here.}Depending on the system where you Line 4202  here.}Depending on the system where you
4202  version you are running, @command{tar} may have a different error message,  version you are running, @command{tar} may have a different error message,
4203  such as:  such as:
4204    
4205  @example  @smallexample
4206  funk: does not exist  funk: does not exist
4207  @end example  @end smallexample
4208    
4209  @FIXME-xref{somewhere, for more information about format parameters.  @FIXME-xref{somewhere, for more information about format parameters.
4210  Melissa says: such as "format variations"?  But why?  Clearly I don't  Melissa says: such as "format variations"?  But why?  Clearly I don't
# Line 4156  together). Line 4321  together).
4321    
4322  The @value{op-ignore-zeros} option is turned off by default because many  The @value{op-ignore-zeros} option is turned off by default because many
4323  versions of @command{tar} write garbage after the end-of-archive entry,  versions of @command{tar} write garbage after the end-of-archive entry,
4324  since that part of the media is never supposed to be read.  @acronym{GNU}  since that part of the media is never supposed to be read.  @GNUTAR{}
4325  @command{tar} does not write after the end of an archive, but seeks to  does not write after the end of an archive, but seeks to
4326  maintain compatiblity among archiving utilities.  maintain compatiblity among archiving utilities.
4327    
4328  @table @kbd  @table @kbd
# Line 4216  To be more aggressive about altering exi Line 4381  To be more aggressive about altering exi
4381  @value{op-overwrite} option.  It causes @command{tar} to overwrite  @value{op-overwrite} option.  It causes @command{tar} to overwrite
4382  existing files and to follow existing symbolic links when extracting.  existing files and to follow existing symbolic links when extracting.
4383    
4384  Some people argue that @acronym{GNU} @command{tar} should not hesitate  Some people argue that @GNUTAR{} should not hesitate
4385  to overwrite files with other files when extracting.  When extracting  to overwrite files with other files when extracting.  When extracting
4386  a @command{tar} archive, they expect to see a faithful copy of the  a @command{tar} archive, they expect to see a faithful copy of the
4387  state of the filesystem when the archive was created.  It is debatable  state of the filesystem when the archive was created.  It is debatable
# Line 4225  has an archive in which @file{usr/local} Line 4390  has an archive in which @file{usr/local}
4390  @file{usr/local2}.  Since then, maybe the site removed the link and  @file{usr/local2}.  Since then, maybe the site removed the link and
4391  renamed the whole hierarchy from @file{/usr/local2} to  renamed the whole hierarchy from @file{/usr/local2} to
4392  @file{/usr/local}.  Such things happen all the time.  I guess it would  @file{/usr/local}.  Such things happen all the time.  I guess it would
4393  not be welcome at all that @acronym{GNU} @command{tar} removes the  not be welcome at all that @GNUTAR{} removes the
4394  whole hierarchy just to make room for the link to be reinstated  whole hierarchy just to make room for the link to be reinstated
4395  (unless it @emph{also} simultaneously restores the full  (unless it @emph{also} simultaneously restores the full
4396  @file{/usr/local2}, of course!  @acronym{GNU} @command{tar} is indeed  @file{/usr/local2}, of course!  @GNUTAR{} is indeed
4397  able to remove a whole hierarchy to reestablish a symbolic link, for  able to remove a whole hierarchy to reestablish a symbolic link, for
4398  example, but @emph{only if} @value{op-recursive-unlink} is specified  example, but @emph{only if} @value{op-recursive-unlink} is specified
4399  to allow this behavior.  In any case, single files are silently  to allow this behavior.  In any case, single files are silently
# Line 4377  This can be useful, for example, if you Line 4542  This can be useful, for example, if you
4542  a big file and don't want to store the file on disk before processing  a big file and don't want to store the file on disk before processing
4543  it.  You can use a command like this:  it.  You can use a command like this:
4544    
4545  @example  @smallexample
4546  tar -xOzf foo.tgz bigfile | process  tar -xOzf foo.tgz bigfile | process
4547  @end example  @end smallexample
4548    
4549  or even like this if you want to process the concatenation of the files:  or even like this if you want to process the concatenation of the files:
4550    
4551  @example  @smallexample
4552  tar -xOzf foo.tgz bigfile1 bigfile2 | process  tar -xOzf foo.tgz bigfile1 bigfile2 | process
4553  @end example  @end smallexample
4554    
4555  @node remove files  @node remove files
4556  @unnumberedsubsubsec Removing Files  @unnumberedsubsubsec Removing Files
# Line 4465  This option is probably never needed on Line 4630  This option is probably never needed on
4630    
4631  @cindex backup options  @cindex backup options
4632    
4633  @acronym{GNU} @command{tar} offers options for making backups of files  @GNUTAR{} offers options for making backups of files
4634  before writing new versions.  These options control the details of  before writing new versions.  These options control the details of
4635  these backups.  They may apply to the archive itself before it is  these backups.  They may apply to the archive itself before it is
4636  created or rewritten, as well as individual extracted members.  Other  created or rewritten, as well as individual extracted members.  Other
# Line 4555  and consume arguments a bit unpredictabl Line 4720  and consume arguments a bit unpredictabl
4720  if you are ready to give up using old style options, you may resort to  if you are ready to give up using old style options, you may resort to
4721  using something like (a Bourne shell function here):  using something like (a Bourne shell function here):
4722    
4723  @example  @smallexample
4724  tar () @{ /usr/local/bin/tar --backup $*; @}  tar () @{ /usr/local/bin/tar --backup $*; @}
4725  @end example  @end smallexample
4726    
4727  @node Applications  @node Applications
4728  @section Notable @command{tar} Usages  @section Notable @command{tar} Usages
# Line 4624  and not archive them.  @xref{Choosing}. Line 4789  and not archive them.  @xref{Choosing}.
4789  @chapter Performing Backups and Restoring Files  @chapter Performing Backups and Restoring Files
4790  @UNREVISED  @UNREVISED
4791    
4792  @acronym{GNU} @command{tar} is distributed along with the scripts  @GNUTAR{} is distributed along with the scripts
4793  which the Free Software Foundation uses for performing backups.  There  which the Free Software Foundation uses for performing backups.  There
4794  is no corresponding scripts available yet for doing restoration of  is no corresponding scripts available yet for doing restoration of
4795  files.  Even if there is a good chance those scripts may be satisfying  files.  Even if there is a good chance those scripts may be satisfying
# Line 4637  Automatic Network Disk Archiver), a back Line 4802  Automatic Network Disk Archiver), a back
4802  da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.  da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
4803  This is free software, and it is available at these places:  This is free software, and it is available at these places:
4804    
4805  @example  @smallexample
4806  http://www.cs.umd.edu/projects/amanda/amanda.html  http://www.cs.umd.edu/projects/amanda/amanda.html
4807  ftp://ftp.cs.umd.edu/pub/amanda  ftp://ftp.cs.umd.edu/pub/amanda
4808  @end example  @end smallexample
4809    
4810  @ifclear PUBLISH  @ifclear PUBLISH
4811    
4812  Here is a possible plan for a future documentation about the backuping  Here is a possible plan for a future documentation about the backuping
4813  scripts which are provided within the @acronym{GNU} @command{tar}  scripts which are provided within the @GNUTAR{}
4814  distribution.  distribution.
4815    
4816  @example  @smallexample
4817  .* dumps  .* dumps
4818  . + what are dumps  . + what are dumps
4819    
# Line 4681  distribution. Line 4846  distribution.
4846  .  - positioning the tape  .  - positioning the tape
4847       MT writes two at end of write,       MT writes two at end of write,
4848         backspaces over one when writing again.         backspaces over one when writing again.
4849  @end example  @end smallexample
4850    
4851  @end ifclear  @end ifclear
4852    
# Line 4832  monthly) dump. Line 4997  monthly) dump.
4997  Here is a sample script to dump the directory hierarchies @samp{/usr}  Here is a sample script to dump the directory hierarchies @samp{/usr}
4998  and @samp{/var}.  and @samp{/var}.
4999    
5000  @example  @smallexample
5001  #! /bin/sh  #! /bin/sh
5002  tar --create \  tar --create \
5003   --blocking-factor=126 \   --blocking-factor=126 \
# Line 4841  tar --create \ Line 5006  tar --create \
5006   --listed-incremental=/var/log/usr-var.snar \   --listed-incremental=/var/log/usr-var.snar \
5007   --verbose \   --verbose \
5008   /usr /var   /usr /var
5009  @end example  @end smallexample
5010    
5011  This script uses the file @file{/var/log/usr-var.snar} as a snapshot to  This script uses the file @file{/var/log/usr-var.snar} as a snapshot to
5012  store information about the previous tar dump.  store information about the previous tar dump.
# Line 4959  last daily (level one) dump.  The only i Line 5124  last daily (level one) dump.  The only i
5124  files changed or created since the last daily backup.  (Doing dumps  files changed or created since the last daily backup.  (Doing dumps
5125  more than once a day is usually not worth the trouble).  more than once a day is usually not worth the trouble).
5126    
5127  @acronym{GNU} @command{tar} comes with scripts you can use to do full  @GNUTAR{} comes with scripts you can use to do full
5128  and level-one dumps.  Using scripts (shell programs) to perform  and level-one dumps.  Using scripts (shell programs) to perform
5129  backups and restoration is a convenient and reliable alternative to  backups and restoration is a convenient and reliable alternative to
5130  typing out file name lists and @command{tar} commands by hand.  typing out file name lists and @command{tar} commands by hand.
# Line 5040  Subdirectories on other file systems wil Line 5205  Subdirectories on other file systems wil
5205    
5206  The host name specifies which host to run @command{tar} on, and should  The host name specifies which host to run @command{tar} on, and should
5207  normally be the host that actually contains the file system.  However,  normally be the host that actually contains the file system.  However,
5208  the host machine must have @acronym{GNU} @command{tar} installed, and  the host machine must have @GNUTAR{} installed, and
5209  must be able to access the directory containing the backup scripts and  must be able to access the directory containing the backup scripts and
5210  their support files using the same file name that is used on the  their support files using the same file name that is used on the
5211  machine where the scripts are run (ie. what @command{pwd} will print  machine where the scripts are run (ie. what @command{pwd} will print
# Line 5067  from the machine on which the backup scr Line 5232  from the machine on which the backup scr
5232    
5233  The following is the text of @file{backup-specs} as it appears at FSF:  The following is the text of @file{backup-specs} as it appears at FSF:
5234    
5235  @example  @smallexample
5236  # site-specific parameters for file system backup.  # site-specific parameters for file system backup.
5237    
5238  ADMINISTRATOR=friedman  ADMINISTRATOR=friedman
# Line 5093  BACKUP_DIRS=" Line 5258  BACKUP_DIRS="
5258    
5259  BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"  BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
5260    
5261  @end example  @end smallexample
5262    
5263  @node Script Syntax  @node Script Syntax
5264  @subsection Syntax for @file{Backup-specs}  @subsection Syntax for @file{Backup-specs}
# Line 5118  BACKUP_FILES can contain wildcards. Line 5283  BACKUP_FILES can contain wildcards.
5283    
5284  The syntax for running a backup script is:  The syntax for running a backup script is:
5285    
5286  @example  @smallexample
5287  @file{script-name} [@var{time-to-be-run}]  @file{script-name} [@var{time-to-be-run}]
5288  @end example  @end smallexample
5289    
5290  where @var{time-to-be-run} can be a specific system time, or can be  where @var{time-to-be-run} can be a specific system time, or can be
5291  @kbd{now}.  If you do not specify a time, the script runs at the time  @kbd{now}.  If you do not specify a time, the script runs at the time
# Line 5168  The @command{tar} distribution does not Line 5333  The @command{tar} distribution does not
5333  @ifclear PUBLISH  @ifclear PUBLISH
5334    
5335  @quotation  @quotation
5336  @strong{Warning:} The @acronym{GNU} @command{tar} distribution does @emph{not}  @strong{Warning:} The @GNUTAR{} distribution does @emph{not}
5337  provide any such @code{restore} script yet.  This section is only  provide any such @code{restore} script yet.  This section is only
5338  listed here for documentation maintenance purposes.  In any case,  listed here for documentation maintenance purposes.  In any case,
5339  all contents is subject to change as things develop.  all contents is subject to change as things develop.
# Line 5261  any operation. Line 5426  any operation.
5426    
5427  For example, in this @command{tar} command,  For example, in this @command{tar} command,
5428    
5429  @example  @smallexample
5430  $ @kbd{tar -cvf collection.tar blues folk jazz}  $ @kbd{tar -cvf collection.tar blues folk jazz}
5431  @end example  @end smallexample
5432    
5433  @noindent  @noindent
5434  @file{collection.tar} is the name of the archive.  It must directly  @file{collection.tar} is the name of the archive.  It must directly
# Line 5295  writes the entire new archive to its sta Line 5460  writes the entire new archive to its sta
5460  @FIXME{might want a different example here; this is already used in  @FIXME{might want a different example here; this is already used in
5461  "notable tar usages".}  "notable tar usages".}
5462    
5463  @example  @smallexample
5464  $ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}  $ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
5465  @end example  @end smallexample
5466    
5467  @FIXME{help!}  @FIXME{help!}
5468    
# Line 5306  $ @kbd{cd sourcedir; tar -cf - . | (cd t Line 5471  $ @kbd{cd sourcedir; tar -cf - . | (cd t
5471  To specify an archive file on a device attached to a remote machine,  To specify an archive file on a device attached to a remote machine,
5472  use the following:  use the following:
5473    
5474  @example  @smallexample
5475  @kbd{--file=@var{hostname}:/@var{dev}/@var{file name}}  @kbd{--file=@var{hostname}:/@var{dev}/@var{file name}}
5476  @end example  @end smallexample
5477    
5478  @noindent  @noindent
5479  @command{tar} will complete the remote connection, if possible, and  @command{tar} will complete the remote connection, if possible, and
# Line 5335  into what came before it well enough <<i Line 5500  into what came before it well enough <<i
5500  here?>>.  bob also comments that if Amanda isn't free software, we  here?>>.  bob also comments that if Amanda isn't free software, we
5501  shouldn't mention it..}  shouldn't mention it..}
5502    
5503  When the archive is being created to @file{/dev/null}, @acronym{GNU}  When the archive is being created to @file{/dev/null}, @GNUTAR{}
5504  @command{tar} tries to minimize input and output operations.  The  tries to minimize input and output operations.  The
5505  Amanda backup system, when used with @acronym{GNU} @command{tar}, has  Amanda backup system, when used with @GNUTAR{}, has
5506  an initial sizing pass which uses this feature.  an initial sizing pass which uses this feature.
5507    
5508  @node Selecting Archive Members  @node Selecting Archive Members
# Line 5411  create the archive @file{little.tgz}.  ( Line 5576  create the archive @file{little.tgz}.  (
5576  @command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for  @command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for
5577  more information.)  more information.)
5578    
5579  @example  @smallexample
5580  $ @kbd{find . -size -400 -print > small-files}  $ @kbd{find . -size -400 -print > small-files}
5581  $ @kbd{tar -c -v -z -T small-files -f little.tgz}  $ @kbd{tar -c -v -z -T small-files -f little.tgz}
5582  @end example  @end smallexample
5583    
5584  @noindent  @noindent
5585  @FIXME{say more here to conclude the example/section?}  @FIXME{say more here to conclude the example/section?}
# Line 5455  files from that file, @file{long-files}, Line 5620  files from that file, @file{long-files},
5620  @file{big.tgz}.  The @samp{--null} option to @command{tar} will cause  @file{big.tgz}.  The @samp{--null} option to @command{tar} will cause
5621  @command{tar} to recognize the @kbd{NUL} separator between files.  @command{tar} to recognize the @kbd{NUL} separator between files.
5622    
5623  @example  @smallexample
5624  $ @kbd{find . -size +800 -print0 > long-files}  $ @kbd{find . -size +800 -print0 > long-files}
5625  $ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}  $ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
5626  @end example  @end smallexample
5627    
5628  @FIXME{say anything else here to conclude the section?}  @FIXME{say anything else here to conclude the section?}
5629    
# Line 5525  before deciding whether to exclude it. Line 5690  before deciding whether to exclude it.
5690  However, this matching procedure can be altered by the options listed  However, this matching procedure can be altered by the options listed
5691  below.  These options accumulate.  For example:  below.  These options accumulate.  For example:
5692    
5693  @example  @smallexample
5694  --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'  --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
5695  @end example  @end smallexample
5696    
5697  ignores case when excluding @samp{makefile}, but not when excluding  ignores case when excluding @samp{makefile}, but not when excluding
5698  @samp{readme}.  @samp{readme}.
# Line 5588  patterns can exclude zero, one, or many Line 5753  patterns can exclude zero, one, or many
5753    
5754  @item  @item
5755  When you use @value{op-exclude}, be sure to quote the @var{pattern}  When you use @value{op-exclude}, be sure to quote the @var{pattern}
5756  parameter, so @acronym{GNU} @command{tar} sees wildcard characters  parameter, so @GNUTAR{} sees wildcard characters
5757  like @samp{*}.  If you do not do this, the shell might expand the  like @samp{*}.  If you do not do this, the shell might expand the
5758  @samp{*} itself using files at hand, so @command{tar} might receive a  @samp{*} itself using files at hand, so @command{tar} might receive a
5759  list of files instead of one pattern, or none at all, making the  list of files instead of one pattern, or none at all, making the
# Line 5596  command somewhat illegal.  This might no Line 5761  command somewhat illegal.  This might no
5761    
5762  For example, write:  For example, write:
5763    
5764  @example  @smallexample
5765  $ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}  $ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
5766  @end example  @end smallexample
5767    
5768  @noindent  @noindent
5769  rather than:  rather than:
5770    
5771  @example  @smallexample
5772  $ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}  $ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
5773  @end example  @end smallexample
5774    
5775  @item  @item
5776  You must use use shell syntax, or globbing, rather than @code{regexp}  You must use use shell syntax, or globbing, rather than @code{regexp}
# Line 5786  Requires @command{tar} to recursively de Line 5951  Requires @command{tar} to recursively de
5951  This is the default.  This is the default.
5952  @end table  @end table
5953    
5954  When you use @samp{--no-recursion}, @acronym{GNU} @command{tar} grabs  When you use @samp{--no-recursion}, @GNUTAR{} grabs
5955  directory entries themselves, but does not descend on them  directory entries themselves, but does not descend on them
5956  recursively.  Many people use @command{find} for locating files they  recursively.  Many people use @command{find} for locating files they
5957  want to back up, and since @command{tar} @emph{usually} recursively  want to back up, and since @command{tar} @emph{usually} recursively
# Line 5814  The @option{--no-recursion} and @option{ Line 5979  The @option{--no-recursion} and @option{
5979  later options and operands, and can be overridden by later occurrences  later options and operands, and can be overridden by later occurrences
5980  of @option{--no-recursion} and @option{--recursion}.  For example:  of @option{--no-recursion} and @option{--recursion}.  For example:
5981    
5982  @example  @smallexample
5983  $ @kbd{tar -cf jams.tar --norecursion grape --recursion grape/concord}  $ @kbd{tar -cf jams.tar --norecursion grape --recursion grape/concord}
5984  @end example  @end smallexample
5985    
5986  @noindent  @noindent
5987  creates an archive with one entry for @file{grape}, and the recursive  creates an archive with one entry for @file{grape}, and the recursive
# Line 5888  Changes the working directory in the mid Line 6053  Changes the working directory in the mid
6053    
6054  For example,  For example,
6055    
6056  @example  @smallexample
6057  $ @kbd{tar -c -f jams.tar grape prune -C food cherry}  $ @kbd{tar -c -f jams.tar grape prune -C food cherry}
6058  @end example  @end smallexample
6059    
6060  @noindent  @noindent
6061  will place the files @file{grape} and @file{prune} from the current  will place the files @file{grape} and @file{prune} from the current
# Line 5907  same directory; if the archive is extrac Line 6072  same directory; if the archive is extrac
6072    
6073  Contrast this with the command,  Contrast this with the command,
6074    
6075  @example  @smallexample
6076  $ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}  $ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}
6077  @end example  @end smallexample
6078    
6079  @noindent  @noindent
6080  which records the third file in the archive under the name  which records the third file in the archive under the name
# Line 5923  The following command places the files @ Line 6088  The following command places the files @
6088  @file{/etc/hosts}, and @file{/lib/libc.a} into the archive  @file{/etc/hosts}, and @file{/lib/libc.a} into the archive
6089  @file{foo.tar}:  @file{foo.tar}:
6090    
6091  @example  @smallexample
6092  $ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}  $ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}
6093  @end example  @end smallexample
6094    
6095  @noindent  @noindent
6096  However, the names of the archive members will be exactly what they were  However, the names of the archive members will be exactly what they were
# Line 5959  Do not strip leading slashes from file n Line 6124  Do not strip leading slashes from file n
6124  containing a @file{..} file name component.  containing a @file{..} file name component.
6125  @end table  @end table
6126    
6127  By default, @acronym{GNU} @command{tar} drops a leading @samp{/} on  By default, @GNUTAR{} drops a leading @samp{/} on
6128  input or output, and complains about file names containing a @file{..}  input or output, and complains about file names containing a @file{..}
6129  component.  This option turns off this behavior.  component.  This option turns off this behavior.
6130    
# Line 5978  archive, and rejects attempts to extract Line 6143  archive, and rejects attempts to extract
6143    
6144  Other @command{tar} programs do not do this.  As a result, if you  Other @command{tar} programs do not do this.  As a result, if you
6145  create an archive whose member names start with a slash, they will be  create an archive whose member names start with a slash, they will be
6146  difficult for other people with a non-@acronym{GNU} @command{tar}  difficult for other people with a non-@GNUTAR{}
6147  program to use.  Therefore, @acronym{GNU} @command{tar} also strips  program to use.  Therefore, @GNUTAR{} also strips
6148  leading slashes from member names when putting members into the  leading slashes from member names when putting members into the
6149  archive.  For example, if you ask @command{tar} to add the file  archive.  For example, if you ask @command{tar} to add the file
6150  @file{/bin/ls} to an archive, it will do so, but the member name will  @file{/bin/ls} to an archive, it will do so, but the member name will
# Line 6016  archiving files.  Preserves leading slas Line 6181  archiving files.  Preserves leading slas
6181  @FIXME{this is still horrible; need to talk with dan on monday.}  @FIXME{this is still horrible; need to talk with dan on monday.}
6182    
6183  @command{tar} prints out a message about removing the @samp{/} from  @command{tar} prints out a message about removing the @samp{/} from
6184  file names.  This message appears once per @acronym{GNU} @command{tar}  file names.  This message appears once per @GNUTAR{}
6185  invocation.  It represents something which ought to be told; ignoring  invocation.  It represents something which ought to be told; ignoring
6186  what it means can cause very serious surprises, later.  what it means can cause very serious surprises, later.
6187    
# Line 6024  Some people, nevertheless, do not want t Line 6189  Some people, nevertheless, do not want t
6189  play really dangerously, one may of course redirect @command{tar} standard  play really dangerously, one may of course redirect @command{tar} standard
6190  error to the sink.  For example, under @command{sh}:  error to the sink.  For example, under @command{sh}:
6191    
6192  @example  @smallexample
6193  $ @kbd{tar -c -f archive.tar /home 2> /dev/null}  $ @kbd{tar -c -f archive.tar /home 2> /dev/null}
6194  @end example  @end smallexample
6195    
6196  @noindent  @noindent
6197  Another solution, both nicer and simpler, would be to change to  Another solution, both nicer and simpler, would be to change to
6198  the @file{/} directory first, and then avoid absolute notation.  the @file{/} directory first, and then avoid absolute notation.
6199  For example:  For example:
6200    
6201  @example  @smallexample
6202  $ @kbd{(cd / && tar -c -f archive.tar home)}  $ @kbd{(cd / && tar -c -f archive.tar home)}
6203  $ @kbd{tar -c -f archive.tar -C  / home}  $ @kbd{tar -c -f archive.tar -C  / home}
6204  @end example  @end smallexample
6205    
6206  @include getdate.texi  @include getdate.texi
6207    
6208  @node Formats  @node Formats
6209  @chapter Controlling the Archive Format  @chapter Controlling the Archive Format
6210    
6211  @FIXME{need an intro here}  Due to historical reasons, there are several formats of tar archives.
6212    All of them are based on the same principles, but have some subtle
6213    differences that often make them incompatible with each other.
6214    
6215    GNU tar is able to create and handle archives in a variety of formats.
6216    The most frequently used formats are (in alphabetical order):
6217    
6218    @table @asis
6219    @item gnu
6220    Format used by @GNUTAR{}.
6221    
6222    @item v7
6223    Archive format, compatible with the V7 implementation of tar.
6224    
6225    @item oldgnu
6226    Format used by @GNUTAR{} of versions prior to 1.12.
6227    
6228    @item posix
6229    Archive format defined by POSIX.1-2001 specification.
6230    
6231    @item star
6232    Format used by J@"org Schilling @command{star} implementation.
6233    @end table
6234    
6235    @GNUTAR{} is able to create archives in any of these formats,
6236    except @samp{star}. It is able to read archives in any of these
6237    formats.
6238    
6239    The default format for @GNUTAR{} is defined at compilation
6240    time. You may check it by running @command{tar --help}, and examining
6241    the last lines of its output. Usually, @GNUTAR{} is configured
6242    to create archives in @samp{gnu} format, however, future version will
6243    switch to @samp{posix}.
6244    
6245  @menu  @menu
6246  * Portability::                 Making @command{tar} Archives More Portable  * Portability::                 Making @command{tar} Archives More Portable
# Line 6074  contiguous files as such.  Let's discuss Line 6271  contiguous files as such.  Let's discuss
6271  * Portable Names::              Portable Names  * Portable Names::              Portable Names
6272  * dereference::                 Symbolic Links  * dereference::                 Symbolic Links
6273  * old::                         Old V7 Archives  * old::                         Old V7 Archives
6274    * gnu::                         GNU and old GNU format archives.
6275  * posix::                       @sc{posix} archives  * posix::                       @sc{posix} archives
6276  * Checksumming::                Checksumming Problems  * Checksumming::                Checksumming Problems
6277  * Large or Negative Values::    Large files, negative time stamps, etc.  * Large or Negative Values::    Large files, negative time stamps, etc.
# Line 6134  it contains unresolved symbolic links. Line 6332  it contains unresolved symbolic links.
6332  Certain old versions of @command{tar} cannot handle additional  Certain old versions of @command{tar} cannot handle additional
6333  information recorded by newer @command{tar} programs.  To create an  information recorded by newer @command{tar} programs.  To create an
6334  archive in V7 format (not ANSI), which can be read by these old  archive in V7 format (not ANSI), which can be read by these old
6335  versions, specify the @value{op-old-archive} option in  versions, specify the @value{op-format-v7} option in
6336  conjunction with the @value{op-create}.  @command{tar} also  conjunction with the @value{op-create} (@command{tar} also
6337  accepts @samp{--portability} for this option.  When you specify it,  accepts @samp{--portability} or @samp{op-old-archive} for this
6338    option). When you specify it,
6339  @command{tar} leaves out information about directories, pipes, fifos,  @command{tar} leaves out information about directories, pipes, fifos,
6340  contiguous files, and device files, and specifies file ownership by  contiguous files, and device files, and specifies file ownership by
6341  group and user IDs instead of group and user names.  group and user IDs instead of group and user names.
6342    
6343  When updating an archive, do not use @value{op-old-archive}  When updating an archive, do not use @value{op-format-v7}
6344  unless the archive was created with using this option.  unless the archive was created with using this option.
6345    
6346  In most cases, a @emph{new} format archive can be read by an @emph{old}  In most cases, a @emph{new} format archive can be read by an @emph{old}
6347  @command{tar} program without serious trouble, so this option should  @command{tar} program without serious trouble, so this option should
6348  seldom be needed.  On the other hand, most modern @command{tar}s are  seldom be needed.  On the other hand, most modern @command{tar}s are
6349  able to read old format archives, so it might be safer for you to  able to read old format archives, so it might be safer for you to
6350  always use @value{op-old-archive} for your distributions.  always use @value{op-format-v7} for your distributions.
6351    
6352  @node posix  @node gnu
6353  @subsection @acronym{GNU} @command{tar} and @sc{posix} @command{tar}  @subsection @acronym{GNU} and old @GNUTAR{} format
6354    
6355  @acronym{GNU} @command{tar} was based on an early draft of the  @GNUTAR{} was based on an early draft of the
6356  @sc{posix} 1003.1 @code{ustar} standard.  @acronym{GNU} extensions to  @sc{posix} 1003.1 @code{ustar} standard.  @acronym{GNU} extensions to
6357  @command{tar}, such as the support for file names longer than 100  @command{tar}, such as the support for file names longer than 100
6358  characters, use portions of the @command{tar} header record which were  characters, use portions of the @command{tar} header record which were
6359  specified in that @sc{posix} draft as unused.  Subsequent changes in  specified in that @sc{posix} draft as unused.  Subsequent changes in
6360  @sc{posix} have allocated the same parts of the header record for  @sc{posix} have allocated the same parts of the header record for
6361  other purposes.  As a result, @acronym{GNU} @command{tar} is  other purposes.  As a result, @GNUTAR{} format is
6362  incompatible with the current @sc{posix} spec, and with @command{tar}  incompatible with the current @sc{posix} specification, and with
6363  programs that follow it.  @command{tar} programs that follow it.
6364    
6365  We plan to reimplement these @acronym{GNU} extensions in a new way which is  In the majority of cases, @command{tar} will be configured to create
6366  upward compatible with the latest @sc{posix} @command{tar} format, but we  this format by default. This may change in the future, since we plan
6367  don't know when this will be done.  to make @samp{posix} format the default.
6368    
6369  In the mean time, there is simply no telling what might happen if you  To force creation a @GNUTAR{} archive, use option
6370  read a @acronym{GNU} @command{tar} archive, which uses the  @value{op-format-gnu}.
6371  @acronym{GNU} extensions, using some other @command{tar} program.  So  
6372  if you want to read the archive with another @command{tar} program, be  Some @command{tar} options are currently basing on @GNUTAR{}
6373  sure to write it using the @samp{--old-archive} option (@samp{-o}).  format, and can therefore be used only with @samp{gnu}
6374    or @samp{oldgnu} archive formats. The list of such options follows:
6375  @FIXME{is there a way to tell which flavor of tar was used to write a  
6376  particular archive before you try to read it?}  @itemize @bullet
6377    @item @value{op-label}, when used with @value{op-create}.
6378  Traditionally, old @command{tar}s have a limit of 100 characters.  @item @value{op-incremental}
6379  @acronym{GNU} @command{tar} attempted two different approaches to  @item @value{op-multi-volume}
6380  overcome this limit, using and extending a format specified by a draft  @item @value{op-sparse}
6381  of some P1003.1.  The first way was not that successful, and involved  @end itemize
6382  @file{@@MaNgLeD@@} file names, or such; while a second approach used  
6383  @file{././@@LongLink} and other tricks, yielding better success.  In  These options will be re-implemented for the @samp{posix} archive
6384  theory, @acronym{GNU} @command{tar} should be able to handle file  format in the future.
6385  names of practically unlimited length.  So, if @acronym{GNU}  
6386  @command{tar} fails to dump and retrieve files having more than 100  @node posix
6387  characters, then there is a bug in @acronym{GNU} @command{tar},  @subsection @GNUTAR{} and @sc{posix} @command{tar}
6388  indeed.  
6389    The version @value{VERSION} of @GNUTAR{} is able
6390  But, being strictly @sc{posix}, the limit was still 100 characters.  to read and create archives conforming to @sc{posix.1-2001} standard.
6391  For various other purposes, @acronym{GNU} @command{tar} used areas  
6392  left unassigned in the @sc{posix} draft.  @sc{posix} later revised  A @sc{posix} conformant archive will be created if @command{tar}
6393  P1003.1 @code{ustar} format by assigning previously unused header  was given @value{op-format-posix} option, or if it was given
6394  fields, in such a way that the upper limit for file name length was  @value{op-format-gnu} option and the environment variable
6395  raised to 256 characters.  However, the actual @sc{posix} limit  @env{POSIXLY_CORRECT} is set. The later usage is retained for
6396  oscillates between 100 and 256, depending on the precise location of  compatibility with previous versions of @GNUTAR{}
6397  slashes in full file name (this is rather ugly).  Since @acronym{GNU}  and is discouraged.
6398  @command{tar} use the same fields for quite other purposes, it became  
6399  incompatible with the latest @sc{posix} standards.  Notice, that currently @acronym{GNU} extensions are not
6400    alowed with this format. Following is the list of options that
6401  For longer or non-fitting file names, we plan to use yet another set  cannot be used with @value{op-format-posix}:
6402  of @acronym{GNU} extensions, but this time, complying with the  
6403  provisions @sc{posix} offers for extending the format, rather than  @itemize @bullet
6404  conflicting with it.  Whenever an archive uses old @acronym{GNU}  @item @value{op-label}, when used with @value{op-create}.
6405  @command{tar} extension format or @sc{posix} extensions, would it be  @item @value{op-incremental}
6406  for very long file names or other specialities, this archive becomes  @item @value{op-multi-volume}
6407  non-portable to other @command{tar} implementations.  In fact,  @item @value{op-sparse}
6408  anything can happen.  The most forgiving @command{tar}s will merely  @end itemize
6409  unpack the file using a wrong name, and maybe create another file  
6410  named something like @file{@@LongName}, with the true file name in it.  This restriction will disappear in the future versions.
 @command{tar}s not protecting themselves may segment violate!  
   
 Compatibility concerns make all this thing more difficult, as we will  
 have to support @emph{all} these things together, for a while.  
 @acronym{GNU} @command{tar} should be able to produce and read true  
 @sc{posix} format files, while being able to detect old @acronym{GNU}  
 @command{tar} formats, besides old V7 format, and process them  
 conveniently.  It would take years before this whole area  
 stabilizes@dots{}  
   
 There are plans to raise this 100 limit to 256, and yet produce  
 @sc{posix} conforming archives.  Past 256, I do not know yet if  
 @acronym{GNU} @command{tar} will go non-@sc{posix} again, or merely  
 refuse to archive the file.  
   
 There are plans so @acronym{GNU} @command{tar} support more fully the  
 latest @sc{posix} format, while being able to read old V7 format,  
 @acronym{GNU} (semi-@sc{posix} plus extension), as well as full  
 @sc{posix}.  One may ask if there is part of the @sc{posix} format  
 that we still cannot support.  This simple question has a complex  
 answer.  Maybe that, on intimate look, some strong limitations will  
 pop up, but until now, nothing sounds too difficult (but see below).  
 I only have these few pages of @sc{posix} telling about ``Extended tar  
 Format'' (P1003.1-1990 -- section 10.1.1), and there are references to  
 other parts of the standard I do not have, which should normally  
 enforce limitations on stored file names (I suspect things like fixing  
 what @kbd{/} and @kbd{@key{NUL}} means).  There are also some points  
 which the standard does not make clear, Existing practice will then  
 drive what I should do.  
   
 @sc{posix} mandates that, when a file name cannot fit within 100 to  
 256 characters (the variance comes from the fact a @kbd{/} is ideally  
 needed as the 156'th character), or a link name cannot fit within 100  
 characters, a warning should be issued and the file @emph{not} be  
 stored.  Unless some @value{op-posix} option is given (or  
 @env{POSIXLY_CORRECT} is set), I suspect that @acronym{GNU}  
 @command{tar} should disobey this specification, and automatically  
 switch to using @acronym{GNU} extensions to overcome file name or link  
 name length limitations.  
   
 There is a problem, however, which I did not intimately studied yet.  
 Given a truly @sc{posix} archive with names having more than 100  
 characters, I guess that @acronym{GNU} @command{tar} up to 1.11.8 will  
 process it as if it were an old V7 archive, and be fooled by some  
 fields which are coded differently.  So, the question is to decide if  
 the next generation of @acronym{GNU} @command{tar} should produce  
 @sc{posix} format by default, whenever possible, producing archives  
 older versions of @acronym{GNU} @command{tar} might not be able to  
 read correctly.  I fear that we will have to suffer such a choice one  
 of these days, if we want @acronym{GNU} @command{tar} to go closer to  
 @sc{posix}.  We can rush it.  Another possibility is to produce the  
 current @acronym{GNU} @command{tar} format by default for a few years,  
 but have @acronym{GNU} @command{tar} versions from some 1.@var{POSIX}  
 and up able to recognize all three formats, and let older  
 @acronym{GNU} @command{tar} fade out slowly.  Then, we could switch to  
 producing @sc{posix} format by default, with not much harm to those  
 still having (very old at that time) @acronym{GNU} @command{tar}  
 versions prior to 1.@var{POSIX}.  
   
 @sc{posix} format cannot represent very long names, volume headers,  
 splitting of files in multi-volumes, sparse files, and incremental  
 dumps; these would be all disallowed if @value{op-posix} or  
 @env{POSIXLY_CORRECT}.  Otherwise, if @command{tar} is given long  
 names, or @samp{-[VMSgG]}, then it should automatically go non-@sc{posix}.  
 I think this is easily granted without much discussion.  
   
 Another point is that only @code{mtime} is stored in @sc{posix}  
 archives, while @acronym{GNU} @command{tar} currently also store  
 @code{atime} and @code{ctime}.  If we want @acronym{GNU} @command{tar}  
 to go closer to @sc{posix}, my choice would be to drop @code{atime}  
 and @code{ctime} support on average.  On the other hand, I perceive  
 that full dumps or incremental dumps need @code{atime} and  
 @code{ctime} support, so for those special applications, @sc{posix}  
 has to be avoided altogether.  
   
 A few users requested that @value{op-sparse} be always active by  
 default, I think that before replying to them, we have to decide if we  
 want @acronym{GNU} @command{tar} to go closer to @sc{posix} on  
 average, while producing files.  My choice would be to go closer to  
 @sc{posix} in the long run.  Besides possible double reading, I do not  
 see any point of not trying to save files as sparse when creating  
 archives which are neither @sc{posix} nor old-V7, so the actual  
 @value{op-sparse} would become selected by default when producing such  
 archives, whatever the reason is.  So, @value{op-sparse} alone might  
 be redefined to force @acronym{GNU}-format archives, and recover its  
 previous meaning from this fact.  
   
 @acronym{GNU}-format as it exists now can easily fool other @sc{posix}  
 @command{tar}, as it uses fields which @sc{posix} considers to be part  
 of the file name prefix.  I wonder if it would not be a good idea, in  
 the long run, to try changing @acronym{GNU}-format so any added field  
 (like @code{ctime}, @code{atime}, file offset in subsequent volumes,  
 or sparse file descriptions) be wholly and always pushed into an  
 extension block, instead of using space in the @sc{posix} header  
 block.  I could manage to do that portably between future  
 @acronym{GNU} @command{tar}s.  So other @sc{posix} @command{tar}s  
 might be at least able to provide kind of correct listings for the  
 archives produced by @acronym{GNU} @command{tar}, if not able to  
 process them otherwise.  
   
 Using these projected extensions might induce older @command{tar}s to  
 fail.  We would use the same approach as for @sc{posix}.  I'll put out  
 a @command{tar} capable of reading @sc{posix}ier, yet extended  
 archives, but will not produce this format by default, in  
 @acronym{GNU} mode.  In a few years, when newer @acronym{GNU}  
 @command{tar}s will have flooded out @command{tar} 1.11.X and  
 previous, we could switch to producing @sc{posix}ier extended  
 archives, with no real harm to users, as almost all existing  
 @acronym{GNU} @command{tar}s will be ready to read @sc{posix}ier  
 format.  In fact, I'll do both changes at the same time, in a few  
 years, and just prepare @command{tar} for both changes, without  
 effecting them, from 1.@var{POSIX}.  (Both changes: 1---using  
 @sc{posix} convention for getting over 100 characters; 2---avoiding  
 mangling @sc{posix} headers for @acronym{GNU} extensions, using only  
 @sc{posix} mandated extension techniques).  
   
 So, a future @command{tar} will have a @value{op-posix} flag forcing  
 the usage of truly @sc{posix} headers, and so, producing archives  
 previous @acronym{GNU} @command{tar} will not be able to read.  So,  
 @emph{once} pretest will announce that feature, it would be  
 particularly useful that users test how exchangeable will be archives  
 between @acronym{GNU} @command{tar} with @value{op-posix} and other  
 @sc{posix} @command{tar}.  
   
 In a few years, when @acronym{GNU} @command{tar} will produce  
 @sc{posix} headers by default, @value{op-posix} will have a strong  
 meaning and will disallow @acronym{GNU} extensions.  But in the  
 meantime, for a long while, @value{op-posix} in @acronym{GNU} tar will  
 not disallow @acronym{GNU} extensions like @value{op-label},  
 @value{op-multi-volume}, @value{op-sparse}, or very long file or link  
 names.  However, @value{op-posix} with @acronym{GNU} extensions will  
 use @sc{posix} headers with reserved-for-users extensions to headers,  
 and I will be curious to know how well or bad @sc{posix}  
 @command{tar}s will react to these.  
   
 @acronym{GNU} @command{tar} prior to 1.@var{POSIX}, and after  
 1.@var{POSIX} without @value{op-posix}, generates and checks  
 @samp{ustar@w{ }@w{ }}, with two suffixed spaces.  This is sufficient  
 for older @acronym{GNU} @command{tar} not to recognize @sc{posix}  
 archives, and consequently, wrongly decide those archives are in old  
 V7 format.  It is a useful bug for me, because @acronym{GNU}  
 @command{tar} has other @sc{posix} incompatibilities, and I need to  
 segregate @acronym{GNU} @command{tar} semi-@sc{posix} archives from  
 truly @sc{posix} archives, for @acronym{GNU} @command{tar} should be  
 somewhat compatible with itself, while migrating closer to latest  
 @sc{posix} standards.  So, I'll be very careful about how and when I  
 will do the correction.  
6411    
6412  @node Checksumming  @node Checksumming
6413  @subsection Checksumming Problems  @subsection Checksumming Problems
6414    
6415  SunOS and HP-UX @command{tar} fail to accept archives created using  SunOS and HP-UX @command{tar} fail to accept archives created using
6416  @acronym{GNU} @command{tar} and containing non-ASCII file names, that  @GNUTAR{} and containing non-ASCII file names, that
6417  is, file names having characters with the eight bit set, because they  is, file names having characters with the eight bit set, because they
6418  use signed checksums, while @acronym{GNU} @command{tar} uses unsigned  use signed checksums, while @GNUTAR{} uses unsigned
6419  checksums while creating archives, as per @sc{posix} standards.  On  checksums while creating archives, as per @sc{posix} standards.  On
6420  reading, @acronym{GNU} @command{tar} computes both checksums and  reading, @GNUTAR{} computes both checksums and
6421  accept any.  It is somewhat worrying that a lot of people may go  accept any.  It is somewhat worrying that a lot of people may go
6422  around doing backup of their files using faulty (or at least  around doing backup of their files using faulty (or at least
6423  non-standard) software, not learning about it until it's time to  non-standard) software, not learning about it until it's time to
6424  restore their missing files with an incompatible file extractor, or  restore their missing files with an incompatible file extractor, or
6425  vice versa.  vice versa.
6426    
6427  @acronym{GNU} @command{tar} compute checksums both ways, and accept  @GNUTAR{} compute checksums both ways, and accept
6428  any on read, so @acronym{GNU} tar can read Sun tapes even with their  any on read, so @acronym{GNU} tar can read Sun tapes even with their
6429  wrong checksums.  @acronym{GNU} @command{tar} produces the standard  wrong checksums.  @GNUTAR{} produces the standard
6430  checksum, however, raising incompatibilities with Sun.  That is to  checksum, however, raising incompatibilities with Sun.  That is to
6431  say, @acronym{GNU} @command{tar} has not been modified to  say, @GNUTAR{} has not been modified to
6432  @emph{produce} incorrect archives to be read by buggy @command{tar}'s.  @emph{produce} incorrect archives to be read by buggy @command{tar}'s.
6433  I've been told that more recent Sun @command{tar} now read standard  I've been told that more recent Sun @command{tar} now read standard
6434  archives, so maybe Sun did a similar patch, after all?  archives, so maybe Sun did a similar patch, after all?
# Line 6402  a @command{tar} able to read the good ar Line 6454  a @command{tar} able to read the good ar
6454  @sc{posix} @command{tar} format uses fixed-sized unsigned octal strings  @sc{posix} @command{tar} format uses fixed-sized unsigned octal strings
6455  to represent numeric values.  User and group IDs and device major and  to represent numeric values.  User and group IDs and device major and
6456  minor numbers have unsigned 21-bit representations, and file sizes and  minor numbers have unsigned 21-bit representations, and file sizes and
6457  times have unsigned 33-bit representations.  @acronym{GNU} @command{tar}  times have unsigned 33-bit representations.  @GNUTAR{}
6458  generates @sc{posix} representations when possible, but for values  generates @sc{posix} representations when possible, but for values
6459  outside the @sc{posix} range it generates two's-complement base-256  outside the @sc{posix} range it generates two's-complement base-256
6460  strings: uids, gids, and device numbers have signed 57-bit  strings: uids, gids, and device numbers have signed 57-bit
# Line 6429  representations are negative.  Many trad Line 6481  representations are negative.  Many trad
6481  implementations generate a two's complement representation for negative  implementations generate a two's complement representation for negative
6482  time stamps that assumes a signed 32-bit @code{time_t}; hence they  time stamps that assumes a signed 32-bit @code{time_t}; hence they
6483  generate archives that are not portable to hosts with differing  generate archives that are not portable to hosts with differing
6484  @code{time_t} representations.  @acronym{GNU} @command{tar} recognizes this  @code{time_t} representations.  @GNUTAR{} recognizes this
6485  situation when it is run on host with a signed 32-bit @code{time_t}, but  situation when it is run on host with a signed 32-bit @code{time_t}, but
6486  it issues a warning, as these time stamps are nonstandard and unportable.  it issues a warning, as these time stamps are nonstandard and unportable.
6487    
# Line 6470  The @value{op-gzip} option does not work Line 6522  The @value{op-gzip} option does not work
6522  option, or with the @value{op-update}, @value{op-append},  option, or with the @value{op-update}, @value{op-append},
6523  @value{op-concatenate}, or @value{op-delete} operations.  @value{op-concatenate}, or @value{op-delete} operations.
6524    
6525  It is not exact to say that @acronym{GNU} @command{tar} is to work in concert  It is not exact to say that @GNUTAR{} is to work in concert
6526  with @command{gzip} in a way similar to @command{zip}, say.  Surely, it is  with @command{gzip} in a way similar to @command{zip}, say.  Surely, it is
6527  possible that @command{tar} and @command{gzip} be done with a single call,  possible that @command{tar} and @command{gzip} be done with a single call,
6528  like in:  like in:
6529    
6530  @example  @smallexample
6531  $ @kbd{tar cfz archive.tar.gz subdir}  $ @kbd{tar cfz archive.tar.gz subdir}
6532  @end example  @end smallexample
6533    
6534  @noindent  @noindent
6535  to save all of @samp{subdir} into a @code{gzip}'ed archive.  Later you  to save all of @samp{subdir} into a @code{gzip}'ed archive.  Later you
6536  can do:  can do:
6537    
6538  @example  @smallexample
6539  $ @kbd{tar xfz archive.tar.gz}  $ @kbd{tar xfz archive.tar.gz}
6540  @end example  @end smallexample
6541    
6542  @noindent  @noindent
6543  to explode and unpack.  to explode and unpack.
# Line 6498  for the @command{tar} and @command{gzip} Line 6550  for the @command{tar} and @command{gzip}
6550  archive to see its contents.  However, this may be done without needing  archive to see its contents.  However, this may be done without needing
6551  disk space, by using pipes internally:  disk space, by using pipes internally:
6552    
6553  @example  @smallexample
6554  $ @kbd{tar tfz archive.tar.gz}  $ @kbd{tar tfz archive.tar.gz}
6555  @end example  @end smallexample
6556    
6557  @cindex corrupted archives  @cindex corrupted archives
6558  About corrupted compressed archives: @command{gzip}'ed files have no  About corrupted compressed archives: @command{gzip}'ed files have no
# Line 6511  construction of the compression tables b Line 6563  construction of the compression tables b
6563  is little chance that you could recover later in the archive.  is little chance that you could recover later in the archive.
6564    
6565  There are pending suggestions for having a per-volume or per-file  There are pending suggestions for having a per-volume or per-file
6566  compression in @acronym{GNU} @command{tar}.  This would allow for viewing the  compression in @GNUTAR{}.  This would allow for viewing the
6567  contents without decompression, and for resynchronizing decompression at  contents without decompression, and for resynchronizing decompression at
6568  every volume or file, in case of corrupted archives.  Doing so, we might  every volume or file, in case of corrupted archives.  Doing so, we might
6569  lose some compressibility.  But this would have make recovering easier.  lose some compressibility.  But this would have make recovering easier.
# Line 6687  the archive.  Use in conjunction with wr Line 6739  the archive.  Use in conjunction with wr
6739  @end table  @end table
6740    
6741  However, users should be well aware that at archive creation time,  However, users should be well aware that at archive creation time,
6742  @acronym{GNU} @command{tar} still has to read whole disk file to  @GNUTAR{} still has to read whole disk file to
6743  locate the @dfn{holes}, and so, even if sparse files use little space  locate the @dfn{holes}, and so, even if sparse files use little space
6744  on disk and in the archive, they may sometimes require inordinate  on disk and in the archive, they may sometimes require inordinate
6745  amount of time for reading and examining all-zero blocks of a file.  amount of time for reading and examining all-zero blocks of a file.
# Line 6709  Programs like @command{dump} do not have Line 6761  Programs like @command{dump} do not have
6761  examining the file system directly, they can determine in advance  examining the file system directly, they can determine in advance
6762  exactly where the holes are and thus avoid reading through them.  The  exactly where the holes are and thus avoid reading through them.  The
6763  only data it need read are the actual allocated data blocks.  only data it need read are the actual allocated data blocks.
6764  @acronym{GNU} @command{tar} uses a more portable and straightforward  @GNUTAR{} uses a more portable and straightforward
6765  archiving approach, it would be fairly difficult that it does  archiving approach, it would be fairly difficult that it does
6766  otherwise.  Elizabeth Zwicky writes to @file{comp.unix.internals}, on  otherwise.  Elizabeth Zwicky writes to @file{comp.unix.internals}, on
6767  1990-12-10:  1990-12-10:
# Line 6779  up in @file{/etc/passwd}.  If it fails, Line 6831  up in @file{/etc/passwd}.  If it fails,
6831  stored in the archive instead.  stored in the archive instead.
6832    
6833  @item --no-same-owner  @item --no-same-owner
6834    @itemx -o
6835  Do not attempt to restore ownership when extracting.  This is the  Do not attempt to restore ownership when extracting.  This is the
6836  default behavior for ordinary users, so this option has an effect  default behavior for ordinary users, so this option has an effect
6837  only for the superuser.  only for the superuser.
# Line 6816  files in that directory, then setting ow Line 6869  files in that directory, then setting ow
6869  wanted (there are a lot of possible schemes), and only then making a  wanted (there are a lot of possible schemes), and only then making a
6870  @command{tar} archive out of this directory, before cleaning  @command{tar} archive out of this directory, before cleaning
6871  everything out.  Of course, we could add a lot of options to  everything out.  Of course, we could add a lot of options to
6872  @acronym{GNU} @command{tar} for fine tuning permissions and ownership.  @GNUTAR{} for fine tuning permissions and ownership.
6873  This is not the good way, I think.  @acronym{GNU} @command{tar} is  This is not the good way, I think.  @GNUTAR{} is
6874  already crowded with options and moreover, the approach just explained  already crowded with options and moreover, the approach just explained
6875  gives you a great deal of control already.  gives you a great deal of control already.
6876    
# Line 6896  an archive, a reasonable system should p Line 6949  an archive, a reasonable system should p
6949  whose last record is shorter than the rest, or which contains garbage  whose last record is shorter than the rest, or which contains garbage
6950  records after a zero block.  records after a zero block.
6951    
6952  The header block is defined in C as follows.  In the @acronym{GNU}  The header block is defined in C as follows.  In the @GNUTAR{}
6953  @command{tar} distribution, this is part of file @file{src/tar.h}:  distribution, this is part of file @file{src/tar.h}:
6954    
6955  @example  @smallexample
6956  @include header.texi  @include header.texi
6957  @end example  @end smallexample
6958    
6959  All characters in header blocks are represented by using 8-bit  All characters in header blocks are represented by using 8-bit
6960  characters in the local variant of ASCII.  Each field within the  characters in the local variant of ASCII.  Each field within the
# Line 7255  always uses 512 bytes per file header) a Line 7308  always uses 512 bytes per file header) a
7308  special files.  special files.
7309    
7310  You might want to look at the freely available alternatives.  The  You might want to look at the freely available alternatives.  The
7311  major ones are @command{afio}, @acronym{GNU} @command{tar}, and  major ones are @command{afio}, @GNUTAR{}, and
7312  @command{pax}, each of which have their own extensions with some  @command{pax}, each of which have their own extensions with some
7313  backwards compatibility.  backwards compatibility.
7314    
# Line 7343  used a default archive name (which was p Line 7396  used a default archive name (which was p
7396  compiled).  The default is normally set up to be the @dfn{first} tape  compiled).  The default is normally set up to be the @dfn{first} tape
7397  drive or other transportable I/O medium on the system.  drive or other transportable I/O medium on the system.
7398    
7399  Starting with version 1.11.5, @acronym{GNU} @command{tar} uses  Starting with version 1.11.5, @GNUTAR{} uses
7400  standard input and standard output as the default device, and I will  standard input and standard output as the default device, and I will
7401  not try anymore supporting automatic device detection at installation  not try anymore supporting automatic device detection at installation
7402  time.  This was failing really in too many cases, it was hopeless.  time.  This was failing really in too many cases, it was hopeless.
# Line 7366  processes to accidental destruction of r Line 7419  processes to accidental destruction of r
7419  all this mess, using standard input and output as a default really  all this mess, using standard input and output as a default really
7420  sounds like the only clean choice left, and a very useful one too.  sounds like the only clean choice left, and a very useful one too.
7421    
7422  @acronym{GNU} @command{tar} reads and writes archive in records, I  @GNUTAR{} reads and writes archive in records, I
7423  suspect this is the main reason why block devices are preferred over  suspect this is the main reason why block devices are preferred over
7424  character devices.  Most probably, block devices are more efficient  character devices.  Most probably, block devices are more efficient
7425  too.  The installer could also check for @samp{DEFTAPE} in  too.  The installer could also check for @samp{DEFTAPE} in
# Line 7432  California, but can be freely distribute Line 7485  California, but can be freely distribute
7485  and installing it are included in the @file{Makefile}.  and installing it are included in the @file{Makefile}.
7486    
7487  @cindex absolute file names  @cindex absolute file names
7488  Unless you use the @value{op-absolute-names} option, @acronym{GNU}  Unless you use the @value{op-absolute-names} option, @GNUTAR{}
7489  @command{tar} will not allow you to create an archive that contains  will not allow you to create an archive that contains
7490  absolute file names (a file name beginning with @samp{/}.) If you try,  absolute file names (a file name beginning with @samp{/}.) If you try,
7491  @command{tar} will automatically remove the leading @samp{/} from the  @command{tar} will automatically remove the leading @samp{/} from the
7492  file names it stores in the archive.  It will also type a warning  file names it stores in the archive.  It will also type a warning
7493  message telling you what it is doing.  message telling you what it is doing.
7494    
7495  When reading an archive that was created with a different  When reading an archive that was created with a different
7496  @command{tar} program, @acronym{GNU} @command{tar} automatically  @command{tar} program, @GNUTAR{} automatically
7497  extracts entries in the archive which have absolute file names as if  extracts entries in the archive which have absolute file names as if
7498  the file names were not absolute.  This is an important feature.  A  the file names were not absolute.  This is an important feature.  A
7499  visitor here once gave a @command{tar} tape to an operator to restore;  visitor here once gave a @command{tar} tape to an operator to restore;
7500  the operator used Sun @command{tar} instead of @acronym{GNU}  the operator used Sun @command{tar} instead of @GNUTAR{},
7501  @command{tar}, and the result was that it replaced large portions of  and the result was that it replaced large portions of
7502  our @file{/bin} and friends with versions from the tape; needless to  our @file{/bin} and friends with versions from the tape; needless to
7503  say, we were unhappy about having to recover the file system from  say, we were unhappy about having to recover the file system from
7504  backup tapes.  backup tapes.
7505    
7506  For example, if the archive contained a file @file{/usr/bin/computoy},  For example, if the archive contained a file @file{/usr/bin/computoy},
7507  @acronym{GNU} @command{tar} would extract the file to @file{usr/bin/computoy},  @GNUTAR{} would extract the file to @file{usr/bin/computoy},
7508  relative to the current directory.  If you want to extract the files in  relative to the current directory.  If you want to extract the files in
7509  an archive to the same absolute names that they had when the archive  an archive to the same absolute names that they had when the archive
7510  was created, you should do a @samp{cd /} before extracting the files  was created, you should do a @samp{cd /} before extracting the files
# Line 7523  the next two paragraphs, as the remainde Line 7576  the next two paragraphs, as the remainde
7576  two terms in a quite consistent way.  two terms in a quite consistent way.
7577    
7578  John Gilmore, the writer of the public domain @command{tar} from which  John Gilmore, the writer of the public domain @command{tar} from which
7579  @acronym{GNU} @command{tar} was originally derived, wrote (June 1995):  @GNUTAR{} was originally derived, wrote (June 1995):
7580    
7581  @quotation  @quotation
7582  The nomenclature of tape drives comes from IBM, where I believe  The nomenclature of tape drives comes from IBM, where I believe
# Line 7556  format, which is meant to be portable, s Line 7609  format, which is meant to be portable, s
7609  The term @dfn{logical block} often represents the basic chunk of  The term @dfn{logical block} often represents the basic chunk of
7610  allocation of many disk blocks as a single entity, which the operating  allocation of many disk blocks as a single entity, which the operating
7611  system treats somewhat atomically; this concept is only barely used  system treats somewhat atomically; this concept is only barely used
7612  in @acronym{GNU} @command{tar}.  in @GNUTAR{}.
7613    
7614  The term @dfn{physical record} is another way to speak of a physical  The term @dfn{physical record} is another way to speak of a physical
7615  block, those two terms are somewhat interchangeable.  In this manual,  block, those two terms are somewhat interchangeable.  In this manual,
# Line 7572  the logical organization of many charact Line 7625  the logical organization of many charact
7625  to the application.  The term @dfn{unit record} describes a small set  to the application.  The term @dfn{unit record} describes a small set
7626  of characters which are transmitted whole to or by the application,  of characters which are transmitted whole to or by the application,
7627  and often refers to a line of text.  Those two last terms are unrelated  and often refers to a line of text.  Those two last terms are unrelated
7628  to what we call a @dfn{record} in @acronym{GNU} @command{tar}.  to what we call a @dfn{record} in @GNUTAR{}.
7629    
7630  When writing to tapes, @command{tar} writes the contents of the archive  When writing to tapes, @command{tar} writes the contents of the archive
7631  in chunks known as @dfn{records}.  To change the default blocking  in chunks known as @dfn{records}.  To change the default blocking
# Line 7625  around one megabyte. Line 7678  around one megabyte.
7678    
7679  If you use a blocking factor larger than 20, older @command{tar}  If you use a blocking factor larger than 20, older @command{tar}
7680  programs might not be able to read the archive, so we recommend this  programs might not be able to read the archive, so we recommend this
7681  as a limit to use in practice.  @acronym{GNU} @command{tar}, however,  as a limit to use in practice.  @GNUTAR{}, however,
7682  will support arbitrarily large record sizes, limited only by the  will support arbitrarily large record sizes, limited only by the
7683  amount of virtual memory or the physical characteristics of the tape  amount of virtual memory or the physical characteristics of the tape
7684  device.  device.
# Line 7695  writing archives. Line 7748  writing archives.
7748  Archives with blocking factors larger than 20 cannot be read  Archives with blocking factors larger than 20 cannot be read
7749  by very old versions of @command{tar}, or by some newer versions  by very old versions of @command{tar}, or by some newer versions
7750  of @command{tar} running on old machines with small address spaces.  of @command{tar} running on old machines with small address spaces.
7751  With @acronym{GNU} @command{tar}, the blocking factor of an archive is limited  With @GNUTAR{}, the blocking factor of an archive is limited
7752  only by the maximum record size of the device containing the archive,  only by the maximum record size of the device containing the archive,
7753  or by the amount of available virtual memory.  or by the amount of available virtual memory.
7754    
# Line 7703  Also, on some systems, not using adequat Line 7756  Also, on some systems, not using adequat
7756  imposed by the device drivers, may yield unexpected diagnostics.  For  imposed by the device drivers, may yield unexpected diagnostics.  For
7757  example, this has been reported:  example, this has been reported:
7758    
7759  @example  @smallexample
7760  Cannot write to /dev/dlt: Invalid argument  Cannot write to /dev/dlt: Invalid argument
7761  @end example  @end smallexample
7762    
7763  @noindent  @noindent
7764  In such cases, it sometimes happen that the @command{tar} bundled by  In such cases, it sometimes happen that the @command{tar} bundled by
7765  the system is aware of block size idiosyncrasies, while @acronym{GNU}  the system is aware of block size idiosyncrasies, while @GNUTAR{}
7766  @command{tar} requires an explicit specification for the block size,  requires an explicit specification for the block size,
7767  which it cannot guess.  This yields some people to consider  which it cannot guess.  This yields some people to consider
7768  @acronym{GNU} @command{tar} is misbehaving, because by comparison,  @GNUTAR{} is misbehaving, because by comparison,
7769  @cite{the bundle @command{tar} works OK}.  Adding @w{@kbd{-b 256}},  @cite{the bundle @command{tar} works OK}.  Adding @w{@kbd{-b 256}},
7770  for example, might resolve the problem.  for example, might resolve the problem.
7771    
# Line 7772  If we choose our blocksize as a multiple Line 7825  If we choose our blocksize as a multiple
7825  seems to dissapper.  Id est, we are using block size of 112 right  seems to dissapper.  Id est, we are using block size of 112 right
7826  now, and we haven't had the problem since we switched@dots{}  now, and we haven't had the problem since we switched@dots{}
7827    
7828  With @acronym{GNU} @command{tar} the blocking factor is limited only  With @GNUTAR{} the blocking factor is limited only
7829  by the maximum record size of the device containing the archive, or by  by the maximum record size of the device containing the archive, or by
7830  the amount of available virtual memory.  the amount of available virtual memory.
7831    
# Line 7935  automatically when this device is opened Line 7988  automatically when this device is opened
7988  opens the archive file before using it and closes it afterwards, this  opens the archive file before using it and closes it afterwards, this
7989  means that a simple:  means that a simple:
7990    
7991  @example  @smallexample
7992  $ @kbd{tar cf /dev/tape @var{directory}}  $ @kbd{tar cf /dev/tape @var{directory}}
7993  @end example  @end smallexample
7994    
7995  @noindent  @noindent
7996  will reposition the tape to its beginning both prior and after saving  will reposition the tape to its beginning both prior and after saving
# Line 7961  recovered. Line 8014  recovered.
8014  To save @var{directory-1} as a first archive at the beginning of a  To save @var{directory-1} as a first archive at the beginning of a
8015  tape, and leave that tape ready for a second archive, you should use:  tape, and leave that tape ready for a second archive, you should use:
8016    
8017  @example  @smallexample
8018  $ @kbd{mt -f /dev/nrtape rewind}  $ @kbd{mt -f /dev/nrtape rewind}
8019  $ @kbd{tar cf /dev/nrtape @var{directory-1}}  $ @kbd{tar cf /dev/nrtape @var{directory-1}}
8020  @end example  @end smallexample
8021    
8022  @cindex tape marks  @cindex tape marks
8023  @dfn{Tape marks} are special magnetic patterns written on the tape  @dfn{Tape marks} are special magnetic patterns written on the tape
# Line 7982  erased by the new information, leaving o Line 8035  erased by the new information, leaving o
8035  So, you may now save @var{directory-2} as a second archive after the  So, you may now save @var{directory-2} as a second archive after the
8036  first on the same tape by issuing the command:  first on the same tape by issuing the command:
8037    
8038  @example  @smallexample
8039  $ @kbd{tar cf /dev/nrtape @var{directory-2}}  $ @kbd{tar cf /dev/nrtape @var{directory-2}}
8040  @end example  @end smallexample
8041    
8042  @noindent  @noindent
8043  and so on for all the archives you want to put on the same tape.  and so on for all the archives you want to put on the same tape.
# Line 7997  that you are ready to write the 17th.  Y Line 8050  that you are ready to write the 17th.  Y
8050  the first 16 tape marks before saving @var{directory-17}, say, by using  the first 16 tape marks before saving @var{directory-17}, say, by using
8051  these commands:  these commands:
8052    
8053  @example  @smallexample
8054  $ @kbd{mt -f /dev/nrtape rewind}  $ @kbd{mt -f /dev/nrtape rewind}
8055  $ @kbd{mt -f /dev/nrtape fsf 16}  $ @kbd{mt -f /dev/nrtape fsf 16}
8056  $ @kbd{tar cf /dev/nrtape @var{directory-17}}  $ @kbd{tar cf /dev/nrtape @var{directory-17}}
8057  @end example  @end smallexample
8058    
8059  In all the previous examples, we put aside blocking considerations, but  In all the previous examples, we put aside blocking considerations, but
8060  you should do the proper things for that as well.  @xref{Blocking}.  you should do the proper things for that as well.  @xref{Blocking}.
# Line 8025  two at the end of all the file entries. Line 8078  two at the end of all the file entries.
8078  If you think of data as a series of records "rrrr"'s, and tape marks as  If you think of data as a series of records "rrrr"'s, and tape marks as
8079  "*"'s, a tape might look like the following:  "*"'s, a tape might look like the following:
8080    
8081  @example  @smallexample
8082  rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------  rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
8083  @end example  @end smallexample
8084    
8085  Tape devices read and write tapes using a read/write @dfn{tape  Tape devices read and write tapes using a read/write @dfn{tape
8086  head}---a physical part of the device which can only access one  head}---a physical part of the device which can only access one
# Line 8049  over the last tape mark, and write the n Line 8102  over the last tape mark, and write the n
8102  to add two archives to the example above, the tape might look like the  to add two archives to the example above, the tape might look like the
8103  following:  following:
8104    
8105  @example  @smallexample
8106  rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------  rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
8107  @end example  @end smallexample
8108    
8109  @node mt  @node mt
8110  @subsection The @command{mt} Utility  @subsection The @command{mt} Utility
# Line 8070  together"?} Line 8123  together"?}
8123    
8124  The syntax of the @command{mt} command is:  The syntax of the @command{mt} command is:
8125    
8126  @example  @smallexample
8127  @kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]}  @kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]}
8128  @end example  @end smallexample
8129    
8130  where @var{tapename} is the name of the tape device, @var{number} is  where @var{tapename} is the name of the tape device, @var{number} is
8131  the number of times an operation is performed (with a default of one),  the number of times an operation is performed (with a default of one),
# Line 8147  the first archive, using @value{op-multi Line 8200  the first archive, using @value{op-multi
8200  second tape when prompted, so @command{tar} can restore both halves of the  second tape when prompted, so @command{tar} can restore both halves of the
8201  file.)  file.)
8202    
8203  @acronym{GNU} @command{tar} multi-volume archives do not use a truly  @GNUTAR{} multi-volume archives do not use a truly
8204  portable format.  You need @acronym{GNU} @command{tar} at both end to  portable format.  You need @GNUTAR{} at both end to
8205  process them properly.  process them properly.
8206    
8207  When prompting for a new tape, @command{tar} accepts any of the following  When prompting for a new tape, @command{tar} accepts any of the following
# Line 8222  it successfully is with a multi-volume e Line 8275  it successfully is with a multi-volume e
8275  the file begins.  the file begins.
8276    
8277  For example, let's presume someone has two tape drives on a system  For example, let's presume someone has two tape drives on a system
8278  named @file{/dev/tape0} and @file{/dev/tape1}.  For having @acronym{GNU}  named @file{/dev/tape0} and @file{/dev/tape1}.  For having @GNUTAR{}
8279  @command{tar} to switch to the second drive when it needs to write the  to switch to the second drive when it needs to write the
8280  second tape, and then back to the first tape, etc., just do either of:  second tape, and then back to the first tape, etc., just do either of:
8281    
8282  @smallexample  @smallexample
# Line 8312  Creates a multi-volume archive via a scr Line 8365  Creates a multi-volume archive via a scr
8365  Beware that there is @emph{no} real standard about the proper way, for  Beware that there is @emph{no} real standard about the proper way, for
8366  a @command{tar} archive, to span volume boundaries.  If you have a  a @command{tar} archive, to span volume boundaries.  If you have a
8367  multi-volume created by some vendor's @command{tar}, there is almost  multi-volume created by some vendor's @command{tar}, there is almost
8368  no chance you could read all the volumes with @acronym{GNU}  no chance you could read all the volumes with @GNUTAR{}.
8369  @command{tar}.  The converse is also true: you may not expect  The converse is also true: you may not expect
8370  multi-volume archives created by @acronym{GNU} @command{tar} to be  multi-volume archives created by @GNUTAR{} to be
8371  fully recovered by vendor's @command{tar}.  Since there is little  fully recovered by vendor's @command{tar}.  Since there is little
8372  chance that, in mixed system configurations, some vendor's  chance that, in mixed system configurations, some vendor's
8373  @command{tar} will work on another vendor's machine, and there is a  @command{tar} will work on another vendor's machine, and there is a
8374  great chance that @acronym{GNU} @command{tar} will work on most of  great chance that @GNUTAR{} will work on most of
8375  them, your best bet is to install @acronym{GNU} @command{tar} on all  them, your best bet is to install @GNUTAR{} on all
8376  machines between which you know exchange of files is possible.  machines between which you know exchange of files is possible.
8377    
8378  @node Tape Files  @node Tape Files
# Line 8348  of tapes into a sequence of tape files, Line 8401  of tapes into a sequence of tape files,
8401    
8402  People seem to often do:  People seem to often do:
8403    
8404  @example  @smallexample
8405  @kbd{--label="@var{some-prefix} `date +@var{some-format}`"}  @kbd{--label="@var{some-prefix} `date +@var{some-format}`"}
8406  @end example  @end smallexample
8407    
8408  or such, for pushing a common date in all volumes or an archive set.  or such, for pushing a common date in all volumes or an archive set.
8409    
# Line 8410  a label at all), use @samp{tar --list -- Line 8463  a label at all), use @samp{tar --list --
8463  print the label first, and then print archive member information, as  print the label first, and then print archive member information, as
8464  in the example below:  in the example below:
8465    
8466  @example  @smallexample
8467  $ @kbd{tar --verbose --list --file=iamanarchive}  $ @kbd{tar --verbose --list --file=iamanarchive}
8468  V--------- 0 0        0 1992-03-07 12:01 iamalabel--Volume Header--  V--------- 0 0        0 1992-03-07 12:01 iamalabel--Volume Header--
8469  -rw-rw-rw- ringo user 40 1990-05-21 13:30 iamafilename  -rw-rw-rw- ringo user 40 1990-05-21 13:30 iamafilename
8470  @end example  @end smallexample
8471    
8472  @table @kbd  @table @kbd
8473  @item --label=@var{archive-label}  @item --label=@var{archive-label}
# Line 8431  To get a common information on all tapes Line 8484  To get a common information on all tapes
8484  series created through a single script used on a regular basis, just  series created through a single script used on a regular basis, just
8485  manage to get some date string as part of the label.  For example:  manage to get some date string as part of the label.  For example:
8486    
8487  @example  @smallexample
8488  $ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}  $ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
8489  $ @kbd{tar --create --file=/dev/tape --multi-volume \  $ @kbd{tar --create --file=/dev/tape --multi-volume \
8490       --volume="Daily backup for `date +%Y-%m-%d`"}       --volume="Daily backup for `date +%Y-%m-%d`"}
8491  @end example  @end smallexample
8492    
8493  Also note that each label has its own date and time, which corresponds  Also note that each label has its own date and time, which corresponds
8494  to when @acronym{GNU} @command{tar} initially attempted to write it,  to when @GNUTAR{} initially attempted to write it,
8495  often soon after the operator launches @command{tar} or types the  often soon after the operator launches @command{tar} or types the
8496  carriage return telling that the next tape is ready.  Comparing date  carriage return telling that the next tape is ready.  Comparing date
8497  labels does give an idea of tape throughput only if the delays for  labels does give an idea of tape throughput only if the delays for

Legend:
Removed from v.1.38  
changed lines
  Added in v.1.39

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26