(tar.info.gz) Synopsis

Info Catalog

(tar.info.gz) tar invocation

(tar.info.gz) using tar options

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

Info Catalog

(tar.info.gz) tar invocation

(tar.info.gz) using tar options