


TAR(1)                   USER COMMANDS                     TAR(1)



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

SYNOPSIS
     tar [ - ] c|r|t|u|x [ bBefFhilmopvwX014578 ] [ _t_a_r_f_i_l_e ]
          [ _b_l_o_c_k_s_i_z_e ] [ _e_x_c_l_u_d_e-_f_i_l_e ] [ -I _i_n_c_l_u_d_e-_f_i_l_e ]
          _f_i_l_e_n_a_m_e_1 _f_i_l_e_n_a_m_e_2 ...  -C _d_i_r_e_c_t_o_r_y _f_i_l_e_n_a_m_e_N ...

DESCRIPTION
     tar archives and extracts multiple files onto a single  tar,
     file archive, called a _t_a_r_f_i_l_e.  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 _k_e_y, 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 _t_a_r_f_i_l_e and write the named files onto it.

     r    Write the named files on the end of the _t_a_r_f_i_l_e.  Note:
          this  option  _d_o_e_s  _n_o_t  _w_o_r_k with quarter-inch archive
          tapes.

     t    List the table of contents of the _t_a_r_f_i_l_e.

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

     x    Extract the named files from the _t_a_r_f_i_l_e.  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 _f_i_l_e_n_a_m_e  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



Sun Release 4.1   Last change: 16 February 1988                 1






TAR(1)                   USER COMMANDS                     TAR(1)



          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 _t_a_r_f_i_l_e.  If f
          is  omitted,  use  the  device  indicated  by  the TAPE
          environment variable, if set.  Otherwise, use /dev/rmt8
          by  default.  If _t_a_r_f_i_l_e 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  _t_a_r_f_i_l_e.   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/: _c_a_n_n_o_t _c_r_e_a_t_e

          when they encounter it.



Sun Release 4.1   Last change: 16 February 1988                 2






TAR(1)                   USER COMMANDS                     TAR(1)



     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  _t_a_r_f_i_l_e  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
          _t_a_r_f_i_l_e when using the key letters c, x, or t.   Multi-
          ple  X arguments may be used, with one _e_x_c_l_u_d_e _f_i_l_e 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 _o_n_e following  directory
     name and _o_n_e following file name.

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




Sun Release 4.1   Last change: 16 February 1988                 3






TAR(1)                   USER COMMANDS                     TAR(1)



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

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

          include/
          include/a.out.h
          _a_n_d _a_l_l _t_h_e _o_t_h_e_r _f_i_l_e_s _i_n /usr/include ...
          /chown
          _a_n_d _a_l_l _t_h_e _o_t_h_e_r _f_i_l_e_s _i_n /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 .
          _m_e_s_s_a_g_e_s _f_r_o_m 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                _d_i_s_p_l_a_y _t_a_b_l_e _o_f _c_o_n_t_e_n_t_s _o_f _t_h_e _a_r_c_h_i_v_e
          (_a_c_c_e_s_s  _u_s_e_r-_i_d/_g_r_o_u_p-_i_d   _s_i_z_e    _m_o_d. _d_a_t_e   _f_i_l_e_n_a_m_e)
          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                _e_x_t_r_a_c_t _f_i_l_e_s _f_r_o_m _t_h_e _a_r_c_h_i_v_e
          _m_e_s_s_a_g_e_s _f_r_o_m 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



Sun Release 4.1   Last change: 16 February 1988                 4






TAR(1)                   USER COMMANDS                     TAR(1)



     from /dev/nrmt0.

          example% tar xvfp /dev/nrmt0                _r_e_a_d _f_i_r_s_t _a_r_c_h_i_v_e _f_r_o_m _t_a_p_e
          _m_e_s_s_a_g_e_s _f_r_o_m tar
          example% mt fsf 1                           _s_k_i_p _o_v_e_r _t_h_e _e_n_d-_o_f-_f_i_l_e _m_a_r_k_e_r
          example% tar xvfp /dev/nrmt0                _r_e_a_d _s_e_c_o_n_d _a_r_c_h_i_v_e _f_r_o_m _t_a_p_e
          _m_e_s_s_a_g_e_s _f_r_o_m 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 _f_i_l_e_n_a_m_e_s | rsh _h_o_s_t dd of=/dev/rmt0  obs=20b
          _m_e_s_s_a_g_e_s _f_r_o_m tar
          example%

     In the example above, we are _c_r_e_a_t_i_n_g a _t_a_r_f_i_l_e with  the  c
     key  letter,  asking  for _v_e_r_b_o_s_e output from tar with the v
     option, specifying the name of the output _t_a_r_f_i_l_e using  the
     f  option (the standard output is where the _t_a_r_f_i_l_e 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 _a_n_d 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 _f_i_l_e_n_a_m_e_s
          _m_e_s_s_a_g_e_s _f_r_o_m tar
          example%

     In the example above, we are  _e_x_t_r_a_c_t_i_n_g  from  the  _t_a_r_f_i_l_e
     with  the  x  key letter, asking for _v_e_r_b_o_s_e _o_u_t_p_u_t _f_r_o_m tar
     with the v option, telling tar it is  reading  from  a  pipe
     with  the B option, specifying the name of the input _t_a_r_f_i_l_e
     using the f option (the standard input is where the  _t_a_r_f_i_l_e
     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),



Sun Release 4.1   Last change: 16 February 1988                 5






TAR(1)                   USER COMMANDS                     TAR(1)



     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  '_p_a_t_-
          _t_e_r_n'`




























Sun Release 4.1   Last change: 16 February 1988                 6



