tar: Synopsis

1 
1 3.1 General Synopsis of 'tar'
1 =============================
1 
1 The GNU 'tar' program is invoked as either one of:
1 
1      tar OPTION... [NAME]...
1      tar LETTER... [ARGUMENT]... [OPTION]... [NAME]...
1 
1    The second form is for when old options are being used.
1 
1    You can use 'tar' to store files in an archive, to extract them from
1 an archive, and to do other types of archive manipulation.  The primary
1 argument to 'tar', which is called the "operation", specifies which
1 action to take.  The other arguments to 'tar' are either "options",
1 which change the way 'tar' performs an operation, or file names or
1 archive members, which specify the files or members 'tar' is to act on.
1 
1    You can actually type in arguments in any order, even if in this
1 manual the options always precede the other arguments, to make examples
1 easier to understand.  Further, the option stating the main operation
1 mode (the 'tar' main command) is usually given first.
1 
1    Each NAME in the synopsis above is interpreted as an archive member
1 name when the main command is one of '--compare' ('--diff', '-d'),
1 '--delete', '--extract' ('--get', '-x'), '--list' ('-t') or '--update'
1 ('-u').  When naming archive members, you must give the exact name of
1 the member in the archive, as it is printed by '--list'.  For '--append'
1 ('-r') and '--create' ('-c'), these NAME arguments specify the names of
1 either files or directory hierarchies to place in the archive.  These
1 files or hierarchies should already exist in the file system, prior to
1 the execution of the 'tar' command.
1 
1    'tar' interprets relative file names as being relative to the working
1 directory.  'tar' will make all file names relative (by removing leading
1 slashes when archiving or restoring files), unless you specify otherwise
1 (using the '--absolute-names' option).  ⇒absolute, for more
1 information about '--absolute-names'.
1 
1    If you give the name of a directory as either a file name or a member
1 name, then 'tar' acts recursively on all the files and directories
1 beneath that directory.  For example, the name '/' identifies all the
1 files in the file system to 'tar'.
1 
1    The distinction between file names and archive member names is
1 especially important when shell globbing is used, and sometimes a source
1 of confusion for newcomers.  ⇒wildcards, for more information
1 about globbing.  The problem is that shells may only glob using existing
1 files in the file system.  Only 'tar' itself may glob on archive
1 members, so when needed, you must ensure that wildcard characters reach
1 'tar' without being interpreted by the shell first.  Using a backslash
1 before '*' or '?', or putting the whole argument between quotes, is
1 usually sufficient for this.
1 
1    Even if NAMEs are often specified on the command line, they can also
1 be read from a text file in the file system, using the
1 '--files-from=FILE-OF-NAMES' ('-T FILE-OF-NAMES') option.
1 
1    If you don't use any file name arguments, '--append' ('-r'),
1 '--delete' and '--concatenate' ('--catenate', '-A') will do nothing,
1 while '--create' ('-c') will usually yield a diagnostic and inhibit
1 'tar' execution.  The other operations of 'tar' ('--list', '--extract',
1 '--compare', and '--update') will act on the entire contents of the
1 archive.
1 
1    Besides successful exits, GNU 'tar' may fail for many reasons.  Some
1 reasons correspond to bad usage, that is, when the 'tar' command line is
1 improperly written.  Errors may be encountered later, while processing
1 the archive or the files.  Some errors are recoverable, in which case
1 the failure is delayed until 'tar' has completed all its work.  Some
1 errors are such that it would be not meaningful, or at least risky, to
1 continue processing: 'tar' then aborts processing immediately.  All
1 abnormal exits, whether immediate or delayed, should always be clearly
1 diagnosed on 'stderr', after a line stating the nature of the error.
1 
1    Possible exit codes of GNU 'tar' are summarized in the following
1 table:
1 
1 0
1      'Successful termination'.
1 
1 1
1      'Some files differ'.  If tar was invoked with '--compare'
1      ('--diff', '-d') command line option, this means that some files in
1      the archive differ from their disk counterparts (⇒compare).
1      If tar was given '--create', '--append' or '--update' option, this
1      exit code means that some files were changed while being archived
1      and so the resulting archive does not contain the exact copy of the
1      file set.
1 
1 2
1      'Fatal error'.  This means that some fatal, unrecoverable error
1      occurred.
1 
1    If 'tar' has invoked a subprocess and that subprocess exited with a
1 nonzero exit code, 'tar' exits with that code as well.  This can happen,
1 for example, if 'tar' was given some compression option (⇒gzip)
1 and the external compressor program failed.  Another example is 'rmt'
1 failure during backup to the remote device (⇒Remote Tape Server).
1