NAME
     tar - create tape archives, and add or extract files

SYNOPSIS
     tar [ - ] c|r|t|u|x [ bBefFhilmopvwX014578 ] [ tarfile ]
          [ blocksize ] [ exclude-file ] [ -I include-file ]
          filename1 filename2 ...  -C directory filenameN ...

DESCRIPTION
     tar archives and extracts multiple files onto a single  tar,
     file archive, called a tarfile.  A tarfile is usually a mag-
     netic tape, but it can be any file.  tar's actions are  con-
     trolled  by the first argument, the key, a string of charac-
     ters containing exactly one function  letter  from  the  set
     crtux,  and  one  or more of the optional function modifiers
     listed below.  Other arguments to tar are file or  directory
     names  that  specify  which files to archive or extract.  In
     all cases, the appearance of a directory name refers  recur-
     sively to the files and subdirectories of that directory.

FUNCTION LETTERS
     c    Create a new tarfile and write the named files onto it.

     r    Write the named files on the end of the tarfile.  Note:
          this  option  does  not  work with quarter-inch archive
          tapes.

     t    List the table of contents of the tarfile.

     u    Add the named files to the  tarfile  if  they  are  not
          there  or  if  they  have been modified since they were
          last archived.  Note: this option does  not  work  with
          quarter-inch archive tapes.

     x    Extract the named files from the tarfile.  If  a  named
          file matches a directory with contents written onto the
          tape, this directory is (recursively)  extracted.   The
          owner,  modification  time,  and  mode are restored (if
          possible).  If no filename  arguments  are  given,  all
          files  in the archive are extracted.  Note: if multiple
          entries specifying the same file are on the  tape,  the
          last one overwrites all earlier versions.

FUNCTION MODIFIERS
     b    Use the next argument as the blocking factor  for  tape
          records.   The  default  blocking  factor is 20 blocks.
          The block size is determined automatically when reading
          tapes (key letters x and t).  This determination of the
          blocking factor may be fooled when reading from a  pipe
          or  a socket (see the B key letter below).  The maximum
          blocking factor is determined only  by  the  amount  of
          memory  available  to  tar  when  it  is  run.   Larger
          blocking factors result in  better  throughput,  longer
          blocks  on  nine-track tapes, and better media utiliza-
          tion.

     B    Force tar to perform multiple reads (if  necessary)  so
          as  to read exactly enough bytes to fill a block.  This
          option exists so that tar can work across the Ethernet,
          since pipes and sockets return partial blocks even when
          more data is coming.

     e    If any unexpected errors occur tar  will  exit  immedi-
          ately with a positive exit status.

     f    Use the next argument as the name of the tarfile.  If f
          is  omitted,  use  the  device  indicated  by  the TAPE
          environment variable, if set.  Otherwise, use /dev/rmt8
          by  default.  If tarfile is given as `-', tar writes to
          the standard output or reads from the  standard  input,
          whichever is appropriate.  Thus, tar can be used as the
          head or tail of a filter chain.  tar can also  be  used
          to copy hierarchies with the command:

               example% cd fromdir; tar cf - . | (cd  todir;  tar
               xfBp -)

     F    With one F argument specified, exclude all  directories
          named  SCCS  from  tarfile.   With  two  arguments  FF,
          exclude all directories named SCCS, all files  with  .o
          as  their  suffix,  and all files named errs, core, and
          a.out.

     h    Follow symbolic links as if they were normal  files  or
          directories.   Normally,  tar  does not follow symbolic
          links.

     i    Ignore directory checksum errors.

     l    Display error messages if all links to  archived  files
          cannot  be  resolved.   If l is not used, no error mes-
          sages are printed.

     m    Do not extract modification times of  extracted  files.
          The modification time will be the time of extraction.

     o    Suppress information  specifying  owner  and  modes  of
          directories  which  tar normally places in the archive.
          Such information makes former versions of tar  generate
          an error message like:

               filename/: cannot create

          when they encounter it.

     p    Restore the named files to their original modes, ignor-
          ing  the present umask(2V).  SetUID and sticky informa-
          tion are also extracted  if  you  are  the  super-user.
          This option is only useful with the x key letter.

     v    Verbose.  Normally tar does  its  work  silently;  this
          option  displays the name of each file tar treats, pre-
          ceded by the function letter.  When  used  with  the  t
          function,  v  displays  the  tarfile  entries in a form
          similar to `ls -l'.

     w    Wait for user confirmation before taking the  specified
          action.   If  you  use w, tar displays the action to be
          taken followed by the file name, and then waits for a y
          response  to  proceed.  No action is taken on the named
          file if you type anything other than a  line  beginning
          with y.

     X    Use the next argument as a file containing  a  list  of
          named  files  (or  directories) to be excluded from the
          tarfile when using the key letters c, x, or t.   Multi-
          ple  X arguments may be used, with one exclude file per
          argument.

     014578
          Select an alternate drive on which the tape is mounted.
          The numbers 2, 3, 6, and 9 do not specify valid drives.
          The default is /dev/rmt8.

     If a file name is  preceded  by  -I  then  the  filename  is
     opened.   A  list  filenames, one per line, is treated as if
     each appeared separately on the command line.  Be careful of
     trailing white space in both include and exclude file lists.

     In the case where excluded files (see X option) also  exist,
     excluded files take precedence over all included files.  So,
     if a file is specified in both the include and exclude files
     (or on the command line), it will be excluded.

     If a file name is preceded by  -C  in  a  c  (create)  or  r
     (replace)  operation,  tar will perform a chdir (see csh(1))
     to that file name.  This  allows  multiple  directories  not
     related  by a close common parent to be archived using short
     relative path names. See EXAMPLES below.

     Note: the -C option only applies to one following  directory
     name and one following file name.

EXAMPLES
     To archive files from /usr/include and from /etc, one  might
     use:

          example% tar c -C /usr  include -C /etc  .

     If you get a table of contents from the  resulting  tarfile,
     you will see something like:

          include/
          include/a.out.h
          and all the other files in /usr/include ...
          /chown
          and all the other files in /etc

     Here is a simple example using tar to create an  archive  of
     your home directory on a tape mounted on drive /dev/rmt0:
          example% cd
          example% tar cvf /dev/rmt0 .
          messages from tar

     The c option means create the archive; the  v  option  makes
     tar  tell  you  what  it is doing as it works;  the f option
     means that you are specifically naming the file  onto  which
     the archive should be placed (/dev/rmt0 in this example).

     Now you can read the table of contents from the archive like
     this:

          example% tar  tvf  /dev/rmt0                display table of contents of the archive
          (access  user-id/group-id   size    mod. date   filename)
          rw-r--r-- 1677/40           2123    Nov  7 18:15:1985./archive/test.c
          ...
          example%

     You can extract files from the archive like this:
          example% tar  xvf  /dev/rmt0                extract files from the archive
          messages from tar
          example%

     If there are multiple archive  files  on  a  tape,  each  is
     separated from the following one by an EOF marker.  tar does
     not read the EOF mark on the tape after it finishes  reading
     an  archive  file  because tar looks for a special header to
     decide when it has reached the end of the archive.   Now  if
     you  try  to  use tar to read the next archive file from the
     tape, tar does not know enough to skip over the EOF mark and
     tries  to  read  the  EOF  mark  as an archive instead.  The
     result of this is an error message from tar to the effect:

          tar: blocksize=0

     This means that to read another archive from the  tape,  you
     must  skip  over  the EOF marker before starting another tar
     command.  You can accomplish this using the  mt(1)  command,
     as  shown in the example below.  Assume that you are reading
     from /dev/nrmt0.

          example% tar xvfp /dev/nrmt0                read first archive from tape
          messages from tar
          example% mt fsf 1                           skip over the end-of-file marker
          example% tar xvfp /dev/nrmt0                read second archive from tape
          messages from tar
          example%

     Finally, here is an example  using  tar  to  transfer  files
     across  the  Ethernet.   First, here is how to archive files
     from the local machine (example) to a tape on a remote  sys-
     tem (host):
          example% tar cvfb  -  20 filenames | rsh host dd of=/dev/rmt0  obs=20b
          messages from tar
          example%

     In the example above, we are creating a tarfile with  the  c
     key  letter,  asking  for verbose output from tar with the v
     option, specifying the name of the output tarfile using  the
     f  option (the standard output is where the tarfile appears,
     as indicated by the `-' sign), and specifying the  blocksize
     (20)  with  the  b option.  If you want to change the block-
     size, you must change the blocksize arguments  both  on  the
     tar command and on the dd command.

     Now, here is how to use tar to get files from a tape on  the
     remote system back to the local system:
          example% rsh -n host  dd  if=/dev/rmt0   bs=20b  |  tar
          xvBfb  - 20 filenames
          messages from tar
          example%

     In the example above, we are  extracting  from  the  tarfile
     with  the  x  key letter, asking for verbose output from tar
     with the v option, telling tar it is  reading  from  a  pipe
     with  the B option, specifying the name of the input tarfile
     using the f option (the standard input is where the  tarfile
     appears,  as  indicated by the `-' sign), and specifying the
     blocksize (20) with the b option.

FILES
     /dev/rmt?           half-inch magnetic tape interface
     /dev/rst?           SCSI tape interface
     /tmp/tar*

ENVIRONMENT
     TAPE      If specified, in the  environment,  the  value  of
               TAPE indicates the default tape device.

SEE ALSO
     cpio(1),  csh(1),   mt(1),   umask(2V),   tar(5),   dump(8),
     restore(8)

BUGS
     Neither the r option nor the  u  option  can  be  used  with
     quarter-inch  archive  tapes, since these tape drives cannot
     backspace.

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

     Tape errors are handled ungracefully.

     The u option can be slow.

     There is no way selectively to follow symbolic links.

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

     Files with names longer than 100 characters cannot  be  pro-
     cessed.

     Filename substitution wildcards do not work  for  extracting
     files  from  the archive.  To get around this, use a command
     of the form:

          tar xvf... /dev/rst0 `tar tf... /dev/rst0 | grep  'pat-
          tern'`