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