tar(1)								       tar(1)



NAME

  tar - Manipulates tape archives

SYNOPSIS

  tar required_flag[bBfFhilLmpPsSvVwzn][n | o]
       [flag_argument ...] [-e exception] ...  [-C directory] ...  [file ...]

  tar -required_flag[optional_flag] [flag_argument] ...
       [n | o] [flag_argument ...] [-e exception] ...
       [-C directory] ...  [file ...]

  The tar command saves and restores multiple files on a single file (usually
  a magnetic tape, but it can be any file).

				     Note

  The syntax of the tar command has recently changed.  The minus sign (-) at
  the beginning of a flag set is no longer optional.  If tar sees a minus
  sign in front of a flag that requires an argument, tar expects the argument
  to follow the flag immediately.  In order to use the original tar syntax in
  existing scripts, you must remove the minus sign if more than one flag
  requiring an argument is given.  Consider this command in the old form:

       tar -xbfp 20 /dev/rmt1h

  Under the new implementation, this command becomes

       tar xbfp 20 /dev/rmt1h

  or

       tar -xb 20 -t /dev/rmt1h -p

DESCRIPTION

  The tar command is used to save and restore data from traditional format
  tar archives.

  The actions of the tar command are controlled by a string containing, at
  most, one required flag and possibly one or more optional flags.  Other
  arguments to tar are file or directory names specifying which files to dump
  or restore.  In all cases, appearance of a directory name refers to the
  files and (recursively) subdirectories of that directory.

  The LC_MESSAGES variable determines the locale's equivalent of y or n (for
  yes/no queries).

FLAGS

  The function performed by tar is specified by one of the following required
  flags:

  c   Creates a new archive; writing begins on the beginning of the tape
      instead of after the last file.

  r   Writes the named files on the end of the tape.

  t   The names of the specified files are listed each time they occur on the
      tape.  If no file argument is given, all of the names on the tape are
      listed.

  u   Adds the named files to the tape, if the files are not already there or
      if they were modified since last copied to the tape.

  x   Extracts the named files from the tape.  If the named file matches a
      directory whose contents were written onto the tape, this directory is
      (recursively) extracted.	The owner, modification time, and mode are
      restored (if possible).  If no file argument is given, the entire con-
      tent of the tape is extracted.  Note that if multiple entries specify-
      ing the same file are on the tape, the last one overwrites all earlier
      ones.

  The following flags can be used with the required flag:

  b   The tar command uses the next argument as the blocking factor for tape
      records. The default is 20 (larger values can be specified at the risk
      of creating a tape archive that some systems' tape drives might not be
      able to restore).	 Use this flag only with raw magnetic tape archives.
      The block size is determined automatically when reading tapes (key
      letters x and t).

  B   Forces input and output blocking to the blocking factor (see the b
      flag).  This flag exists so that tar can work across a communications
      channel where the blocking cannot be maintained.

  f   The tar command uses the next argument as the name of the archive
      instead of /dev/rmtnh. If the name of the file is - (dash), tar writes
      to standard output or reads from standard input, whichever is appropri-
      ate.  Thus, tar can be used as the head or tail of a filter chain.  The
      tar command can also be used to move hierarchies with the command:
	   cd fromdir; tar cf - . | (cd todir; tar xf -)


  F   Checks certain filenames before archiving.  Source Code Control System
      (SCCS), Revision Control System (RCS), files named core, errs, a.out,
      and files ending in .o are not archived.

  h   Forces tar to follow symbolic links as if they were normal files or
      directories.  Normally, tar does not follow symbolic links, but instead
      saves the link text in the archive.

  i   Ignores checksum errors.	The tar command writes a file header contain-
      ing a checksum for each file in the archive.  When this flag is not
      specified, the system verifies the contents of the header blocks by
      recomputing the checksum and stops with a directory checksum error when
      a mismatch occurs.  When this flag is specified, tar logs the error and
      then scans forward until it finds a valid header block.  This permits
      restoring files from later volumes of a multivolume archive without
      reading earlier volumes.

  l   Tells tar to complain if it cannot resolve all of the links to the
      files dumped.  If this is not specified, no error messages are printed.

  L   Tries to create a symbolic link if tar is unsuccessful in its attempt
      to link (hard link) two files.

  m   Tells tar not to restore the modification times.	The modification time
      is the time of extraction.  This is always the case with symbolic
      links.

  n   Allows tar headers to be created with filenames that cannot be null-
      terminated if they are exactly the maximum length (as specified in
      POSIX).  This flag is mutually exclusive with the o flag (that is, new
      vs. old).	 When specified, each of these flags turns off the other;
      neither flag is turned on by default, however.

  o   The o flag is provided for backward compatibility.  Specify this flag
      if the archive s to be restored on a system with an older version of
      tar.  On output, tar normally places information specifying owner and
      modes of directories in the archive.  Former versions of tar, when
      encountering this information will give an error message of the form
	   name/: cannot create


      This modifier suppresses the directory information.  It also prevents
      archiving special files and FIFOs that earlier versions of tar would
      not be able to extract properly.	(Note that although anyone can
      archive special files, only a user who has superuser authority can
      extract them from the archives.)

      When o is used for reading, it causes the extracted file to take on the
      User and Group ID (UID and GID) of the user running the program, rather
      than those of the tape.  This is the default for the ordinary user.

      This flag is mutually exclusive with the n flag (that is, new vs. old).
      When specified, each of these flags turns off the other; neither flag
      is turned on by default, however.



  p   Restores files to their original modes, ignoring the present umask.
      Set-user-ID and sticky information will also be restored if the user is
      superuser.

  P   Specifies the prefix that is to be stripped off of the filenames
      archived to or extracted from tape.  (See also the s flag.)

  s   Tells tar to strip off any leading slashes from pathnames during
      extraction.  This is useful when restoring a tape that was created on a
      system with a different file system structure.  (See also the P flag.)

  R   The named file immediatedly following this flag contains a list of file
      names separated by newlines.  This list is added to (c function key, r
      function key) or extracted from (x function key) the archive.  Note,
      the -R flag is incompatible with the -C flag.

  S blocksb | feet[@density]
      Specifies the number of 512-byte blocks per volume (first form),
      independent of the tape blocking factor.	You can also specify the size
      of the tape in feet, and optionally density, by using the second form.
      Feet are assumed to be 11 inches long to be conservative.	 This flag
      lets you deal more easily with multivolume tape archives, where tar
      must be able to determine how many blocks fit on each volume.

      Note that tape drives vary in density capabilities.  The density argu-
      ment is used in the amount of data that tar can fit on a tape.

  v   Normally tar does its work silently.  The v (verbose) option makes tar
      print the name of each file it treats preceded by the function letter.
      With the t function, the verbose option gives more information about
      the tape entries than just their names.

  V   Prevents any extended attributes from being archived with associated
      files.  This option is particularly useful for archiving files that are
      to be restored with previous versions of tar and cpio.

  w   Causes tar to print the action to be taken followed by the name of the
      file, and then to wait for the user's confirmation. If a word beginning
      with y, or the locale's equivalent of a y, is given, the action is
      performed.  If any other input is given, the action is not performed.

  z   Positions the tape after the EOF marker on extraction or listing.	 The
      z option allows the user to extract or list tapes that have multiple
      archives on them one after the other without error as a result of the
      tape not being positioned correctly for the next extraction or listing.

  n   Selects /dev/rmtnh (the variable n means 0-9) as the tape drive on
      which the tape is mounted.  The default is drive 0 (/dev/rmt0h).

  \   Adds the following argument to a list of exception strings that prevent
      files whose names match exactly from being archived.

  C   If a filename is preceded by -C, tar performs a chdir() to that
      filename.	 This allows multiple directories not related by a close com-
      mon parent to be archived using short relative pathnames.	 For example,
      to archive files from /usr/include and from /etc, one might use the
      following command line:
	   tar c -C /usr/include . -C /etc .


      Therefore, if you do not specify an absolute filename, the filename is
      considered relative to the previous -C directory.	 When you specify
      this flag multiple times on the command line, make sure to specify sub-
      sequent -C directories relative to the preceding -C directories.

      If an error occurs while trying to change to the requested directory,
      subsequent filenames on the command line that are not absolute (that
      is, have no leading / (slash)) are skipped until the next -C flag is
      specified.

  Only the -e and -C flags must be preceded by a - (dash) and can be speci-
  fied more than once on a single command line or interspersed within the
  list of filenames.  All other flags must be specified together (with no
  separating spaces) before -e, -C, and the file list.	For all flags that
  require arguments, the arguments must follow the string of flags and be
  ordered in the same way as the specified flags.

  Previous restrictions on the tar command's ability to properly handle
  blocked archives have been lifted.

NOTES

   1.  There is no way to ask for the nth occurrence of a file.

   2.  Tape errors are handled ungracefully.

   3.  The u option can be slow.

   4.  The current limit on filename length is 256 bytes.  The current limit
       on file links (hard or soft) is 100 bytes.

   5.  There is no way selectively to follow symbolic links.

   6.  When extracting tapes created with the r or u options, directory
       modification times might not be set correctly.

   7.  After encountering tape write errors, tar queries the operator about
       performing a rewrite.  If the operator requests a rewrite, a rewind is
       performed, followed by an attempt to rewrite the data.  In the event
       the no-rewind device is used, the user should always load a new tape
       to avoid the possibility of overwriting previously written archives.




EXAMPLES

  To create a tar archive to device /dev/rmt12, enter:

       tar cvfb /dev/rmt12 20 -e ./foo -C /usr/glenn . \
       -e ./bar -e ./logs/logfile -C /usr/gaston .


  The preceding command line specifies a blocking factor of 20.	 The result-
  ing archive contains all files and directories in /usr/glenn except for
  file ./foo and all files and directories in /usr/gaston except for ./foo
  and ./bar and ./logs/logfile.

FILES

  /dev/rmtnh
	 Device name used with the n flag.

  /tmp/tar*
	 Temporary file used with the u function.

RELATED INFORMATION

  Functions:  chdir(2), umask(2).

  Files:  tar(4).