


tar(1)                    User Commands                    tar(1)



NAME
     tar - create tape archives and add or extract files

SYNOPSIS
     tar c [bBefFhiloPvwX [ 0-7 ]] [ _b_l_o_c_k ] [ _t_a_r_f_i_l_e ]
          [ _e_x_c_l_u_d_e-_f_i_l_e ] { -I _i_n_c_l_u_d_e-_f_i_l_e |
          -C _d_i_r_e_c_t_o_r_y _f_i_l_e | _f_i_l_e } ...

     tar r [ bBefFhilvw [ 0-7 ]] [ _b_l_o_c_k ]
          { -I _i_n_c_l_u_d_e-_f_i_l_e | -C _d_i_r_e_c_t_o_r_y _f_i_l_e | _f_i_l_e } ...

     tar t [ BefFhilvX [ 0-7 ]] [ _t_a_r_f_i_l_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 } ...

     tar u [ bBefFhilvw [ 0-7 ]] [ _b_l_o_c_k ] [ _t_a_r_f_i_l_e ] _f_i_l_e ...

     tar x [ BefFhilmopvwX [ 0-7 ]] [ _t_a_r_f_i_l_e ]
          [ _e_x_c_l_u_d_e-_f_i_l_e ] [ _f_i_l_e ... ]

AVAILABILITY
     SUNWcsu

DESCRIPTION
     The tar command archives and extracts files to  and  from  a
     single  file  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 _k_e_y argument.  The _k_e_y is a string of charac-
     ters containing exactly one function letter (c, r, t , u, or
     x)  and zero or more function modifiers (letters or digits),
     depending on the function letter used.  The _k_e_y string  con-
     tains  no  SPACE characters. Function modifier arguments are
     listed on the command  line  in  the  same  order  as  their
     corresponding function modifiers appear in the _k_e_y string.

     The -I _i_n_c_l_u_d_e-_f_i_l_e, -C _d_i_r_e_c_t_o_r_y _f_i_l_e, and  _f_i_l_e  arguments
     specify  which  files  or  directories are to be archived or
     extracted.  In all cases, appearance  of  a  directory  name
     refers to the files and (recursively) subdirectories of that
     directory.  Arguments appearing within  braces  ({  indicate
     that one of the arguments must be specified.

OPTIONS
     The following options are supported:

     -I _i_n_c_l_u_d_e-_f_i_l_e
          Open _i_n_c_l_u_d_e-_f_i_l_e containing a list of files,  one  per
          line,  and treat as if each file appeared separately on
          the command line.  Be careful of trailing white spaces.
          In the case where excluded files (see X function modif-
          ier) are also specified, they take precedence over  all
          included  files.   If  a  file is specified in both the
          _e_x_c_l_u_d_e-_f_i_l_e and the _i_n_c_l_u_d_e-_f_i_l_e (or  on  the  command



SunOS 5.5.1         Last change: 20 Feb 1996                    1






tar(1)                    User Commands                    tar(1)



          line), it will be excluded.

     -C _d_i_r_e_c_t_o_r_y _f_i_l_e
          Perform a chdir (see cd(1)) operation on _d_i_r_e_c_t_o_r_y  and
          perform  the  c  (create)  or  r (replace) operation on
          _f_i_l_e.  Use short relative path names for _f_i_l_e.  If _f_i_l_e
          is  `.',  archive  all files in _d_i_r_e_c_t_o_r_y.  This option
          enables archiving files from multiple  directories  not
          related by a close common parent.

OPERANDS
     The following operands are supported:

     _f_i_l_e A path name of  a  regular  file  or  directory  to  be
          archived  (when the c, r or u functions are specified),
          extracted (x) or listed (t).  When  _f_i_l_e  is  the  path
          name  of  a directory, the action applies to all of the
          files and (recursively) subdirectories of  that  direc-
          tory.   The  directory portion of _f_i_l_e (see dirname(1))
          cannot exceed 155 characters.  The  file  name  portion
          (see basename(1)) cannot exceed 100 characters.

  Function Letters
     The function portion of the key is specified by one  of  the
     following letters:

     c    Create. Writing begins at the beginning of the tarfile,
          instead of at the end.

     r    Replace.  The named _f_i_l_es are written at the end of the
          tarfile.

     t    Table of Contents.  The names of  the  specified  files
          are  listed each time they occur in the tarfile.  If no
          _f_i_l_e argument is given, the names of all files  in  the
          tarfile  are  listed.   With  the  v function modifier,
          additional  information  for  the  specified  files  is
          displayed.

     u    Update.  The named _f_i_l_es are written at the end of  the
          tarfile  if  they are not already in the tarfile, or if
          they have been modified since last written to that tar-
          file.  An update can be rather slow.  A tarfile created
          on a 5.x system cannot be updated on a 4.x system.

     x    Extract or restore.  The named _f_i_l_es are extracted from
          the  tarfile  and written to the directory specified in
          the tarfile, relative to the  current  directory.   Use
          the  relative path names of files and directories to be
          extracted.  If a named file matches a  directory  whose
          contents  has  been written to the tarfile, this direc-
          tory is recursively extracted.  The owner, modification



SunOS 5.5.1         Last change: 20 Feb 1996                    2






tar(1)                    User Commands                    tar(1)



          time,  and  mode are restored (if possible); otherwise,
          to  restore  owner,  you  must   be   the   super-user.
          Character-special and block-special devices (created by
          mknod(1M)) can only be extracted by the super-user.  If
          no  _f_i_l_e  argument  is given, the entire content of the
          tarfile is extracted.  If the tarfile contains  several
          files  with  the same name, each file is written to the
          appropriate directory, overwriting  the  previous  one.
          Filename  substitution  wildcards  cannot  be  used for
          extracting files from the archive; rather, use  a  com-
          mand of the form:

                  tar xvf... /dev/rmt/0 `tar tf...  /dev/rmt/0  |
                  grep '_p_a_t_t_e_r_n'`

     When extracting tapes created with the  r  or  u  functions,
     directory  modification  times  may  not  be  set correctly.
     These same functions cannot be used with  many  tape  drives
     due  to  tape drive limitations such as the absence of back-
     space or append capabilities.

     When using the r, u, or x functions or the X function modif-
     ier,  the  named  files must match exactly the corresponding
     files in the _t_a_r_f_i_l_e.  For example, to  extract  ./_t_h_i_s_f_i_l_e,
     you  must specify ./_t_h_i_s_f_i_l_e, and not _t_h_i_s_f_i_l_e.  The t func-
     tion displays how each file was archived.

  Function Modifiers
     The characters below may be used  in  conjunction  with  the
     letter that selects the desired function.

     b    Blocking Factor.  Use when reading or  writing  to  raw
          magnetic  archives  (see  f below).  The _b_l_o_c_k argument
          specifies the number of  512-byte  tape  blocks  to  be
          included  in  each read or write operation performed on
          the tarfile.  The minimum is 1, the default is 20.  The
          maximum  value  is  a  function of the amount of memory
          available and the blocking requirements of the specific
          tape device involved (see mtio(7I) for details.)

          When a tape archive is being read, its actual  blocking
          factor will be automatically detected, provided that it
          is less than or equal to the  nominal  blocking  factor
          (the  value of the _b_l_o_c_k argument, or the default value
          if the b modifier is not  specified).   If  the  actual
          blocking  factor  is  greater than the nominal blocking
          factor, a read error will result.   See  Example  5  in
          EXAMPLES below.

          The automatic determination of the actual blocking fac-
          tor  may be fooled when reading from a pipe or a socket
          (see the B function modifier below).



SunOS 5.5.1         Last change: 20 Feb 1996                    3






tar(1)                    User Commands                    tar(1)



          1/4" streaming tape has an inherent blocking factor  of
          one  512-byte  block.   It can be read or written using
          any blocking factor.

          This function modifier works for archives on disk files
          and   block  special  devices,  among  others,  but  is
          intended principally for tape devices.

     B    Block.  Force tar to perform multiple reads (if  neces-
          sary)  to  read  exactly  enough bytes to fill a block.
          This function modifier enables tar to work  across  the
          Ethernet, since pipes and sockets return partial blocks
          even when more data is coming.  When reading from stan-
          dard  input, '-', this function modifier is selected by
          default to ensure  that  tar  can  recover  from  short
          reads.

     e    Error. Exit immediately with a positive exit status  if
          any unexpected errors occur.

     f    File. Use the _t_a_r_f_i_l_e argument as the name of the  tar-
          file.   If  f  is  specified,  /etc/default/tar  is not
          searched.  If f is omitted, tar  will  use  the  device
          indicated  by  the  TAPE  environment variable, if set;
          otherwise, it will use the default  values  defined  in
          /etc/default/tar.   If  the name of the tarfile is '-',
          tar writes to the standard output  or  reads  from  the
          standard  input,  whichever is appropriate.  tar can be
          used as the head or tail of a pipeline.  tar  can  also
          be used to move hierarchies with the command:

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

     F    With one F argument, tar excludes all directories named
          SCCS and RCS from the tarfile.  With two arguments, FF,
          tar excludes all directories named SCCS  and  RCS,  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    Link.  Output error message if unable  to  resolve  all
          links  to the files being archived.  If l is not speci-
          fied, no error messages are printed.

     m    Modify.  The modification time of the file is the  time
          of  extraction.   This  function modifier is valid only



SunOS 5.5.1         Last change: 20 Feb 1996                    4






tar(1)                    User Commands                    tar(1)



          with the x function.

     o    Ownership.  Assign to  extracted  files  the  user  and
          group  identifiers  of  the  user  running the program,
          rather than those on  tarfile.   This  is  the  default
          behavior  for users other than root.  If the o function
          modifier is not set and the user is root, the extracted
          files  will  take  on the group and user identifiers of
          the files on tarfile (see chown(1)  for  more  informa-
          tion).   The o function modifier is only valid with the
          x function.

     p    Restore the named files to their  original  modes,  and
          ACLs  if  applicable,  ignoring  the  present umask(1).
          SETUID and sticky information are  also  extracted  for
          the  super-user.   When  this function modifier is used
          with the c function, ACLs are created  in  the  tarfile
          along with other information.  Errors will occur when a
          tarfile with ACLs is extracted by previous versions  of
          tar.

     P    Suppress the addition of a trailing  "/"  on  directory
          entries in the archive.

     v    Verbose.  Output the name of each file preceded by  the
          function letter.  With the t function, v provides addi-
          tional information  about  the  tarfile  entries.   The
          listing  is  similar  to  the format produced by the -l
          option of the ls(1) command.

     w    What.  Output the action to be taken and  the  name  of
          the  file,  then await the user's confirmation.  If the
          first keystroke is y, the action is  performed;  other-
          wise,  the  action  is  not  performed.   This function
          modifier cannot be used with the t function.

     X    Exclude.  Use the _e_x_c_l_u_d_e-_f_i_l_e argument as a file  con-
          taining  a  list  of  relative path names for files (or
          directories) to be excluded from the tarfile when using
          the functions c, x, or t.  Be careful of trailing white
          spaces.  Multiple X arguments may  be  used,  with  one
          _e_x_c_l_u_d_e-_f_i_l_e  per  argument. In the case where included
          files (see -I _i_n_c_l_u_d_e-_f_i_l_e option) are also  specified,
          the  excluded  files  take precedence over all included
          files.  If a file is specified in both the _e_x_c_l_u_d_e-_f_i_l_e
          and  the _i_n_c_l_u_d_e-_f_i_l_e (or on the command line), it will
          be excluded.

     [0-7]
          Select an  alternative  drive  on  which  the  tape  is
          mounted.    The   default   entries  are  specified  in
          /etc/default/tar.  If no digit or f  function  modifier



SunOS 5.5.1         Last change: 20 Feb 1996                    5






tar(1)                    User Commands                    tar(1)



          is  specified, the entry in /etc/default/tar with digit
          "0" is the default.

EXAMPLES
     1. The following is  an  example  using  tar  to  create  an
        archive of your home directory on a tape mounted on drive
        /dev/rmt/0:

             example% cd
             example% tar cvf /dev/rmt/0 .
             _m_e_s_s_a_g_e_s _f_r_o_m tar

        The c function letter means create  the  archive;  the  v
        function modifier outputs messages explaining what tar is
        doing; the f function modifier indicates that the tarfile
        is being specified ( /dev/rmt/0 in this example). The dot
        (.) at the end of the command line indicates the  current
        directory and is the argument of the f function modifier.

        Display the table of contents of  the  tarfile  with  the
        following command:

             example% tar tvf /dev/rmt/0

        The output will be similar to the following:

             rw-r--r-- 1677/40 2123  Nov  7 18:15 1985     ./test.c
             ...
             example%

        The columns have the following meanings:

             +o column 1 is the access permissions to ./test.c
             +o column 2 is the _u_s_e_r-_i_d/_g_r_o_u_p-_i_d of ./test.c
             +o column 3 is the size of ./test.c in bytes
             +o column 4 is the modification date of ./test.c
             +o column 5 is the name of ./test.c

        To extract files from the archive:

             example% tar xvf /dev/rmt/0
             _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.  To
        have tar read the first and second archives from  a  tape
        with  multiple  archives on it, the _n_o_n-_r_e_w_i_n_d_i_n_g version
        of the tape device name must be used with the f  function
        modifier, as follows:

             example% tar xvfp /dev/rmt/0n   _r_e_a_d _f_i_r_s_t _a_r_c_h_i_v_e _f_r_o_m _t_a_p_e



SunOS 5.5.1         Last change: 20 Feb 1996                    6






tar(1)                    User Commands                    tar(1)



             _m_e_s_s_a_g_e_s _f_r_o_m tar
             example% tar xvfp /dev/rmt/0n   _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%

        Note that in some earlier releases,  the  above  scenario
        did  not  work  correctly,  and  intervention  with mt(1)
        between tar invocations was necessary.   To  emulate  the
        old  behavior,  use the non-rewind device name containing
        the letter b for BSD behavior.  See the Close  Operations
        section of the mtio(7I) manual page.

     2. To archive files  from  /usr/include  and  from  /etc  to
        default tape drive 0:

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

        The table of contents from the  resulting  tarfile  would
        produce output like the following:

             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

        To extract all files in the include directory:

             example% tar xv include
             x include/, 0 bytes, 0 tape blocks
             _a_n_d _a_l_l _f_i_l_e_s _u_n_d_e_r include...

     3. The following 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
        system (host):

             example% tar cvfb  -  20 _f_i_l_e_s |
                   rsh _h_o_s_t dd of=/dev/rmt/0  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 function modifier, specifying the name  of  the  output
        _t_a_r_f_i_l_e  using the f function modifier (the standard out-
        put is where the _t_a_r_f_i_l_e appears, as indicated by the `-'
        sign), and specifying the blocksize (20) with the b func-
        tion modifier.  If you want to change the blocksize,  you
        must  change the blocksize arguments both on the tar com-
        mand _a_n_d on the dd command.




SunOS 5.5.1         Last change: 20 Feb 1996                    7






tar(1)                    User Commands                    tar(1)



     4. The following is an example that  uses  tar  to  retrieve
        files  from a tape on the remote system back to the local
        system:

             example% rsh -n host dd if=/dev/rmt/0 bs=20b |
                  tar xvBfb - 20 _f_i_l_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 function modifier, telling tar it  is  reading
        from  a pipe with the B function modifier, specifying the
        name of the input _t_a_r_f_i_l_e using the f  function  modifier
        (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 function modifier.

     5. The following example creates  an  archive  of  the  home
        directory on /dev/rmt/0 with an actual blocking factor of
        19.

             example% tar cvfb /dev/rmt/0 19 $HOME

        To  recognize  this  archive's  actual  blocking   factor
        without using the b function modifier:

             example% tar tvf /dev/rmt/0
             tar: blocksize = 19
             ...

        To recognize this archive's actual blocking factor  using
        a larger nominal blocking factor:

             example% tar tvf /dev/rmt/0 30
             tar: blocksize = 19
             ...

        Attempt to recognize this archive's actual blocking  fac-
        tor using a nominal blocking factor that is too small:

             example% tar tvf /dev/rmt/0 10
             tar: tape read error

ENVIRONMENT
     See environ(5) for descriptions of the following environment
     variables  that  affect  the  execution of tar:  LC_COLLATE,
     LC_CTYPE, LC_MESSAGES, LC_TIME, TZ, and NLSPATH.

EXIT STATUS
     The following exit values are returned:
     0         Successful completion.



SunOS 5.5.1         Last change: 20 Feb 1996                    8






tar(1)                    User Commands                    tar(1)



     >0        An error occurred.

FILES
     /dev/rmt/[0-7][b][n]
     /dev/rmt/[0-7]l[b][n]
     /dev/rmt/[0-7]m[b][n]
     /dev/rmt/[0-7]h[b][n]
     /dev/rmt/[0-7]u[b][n]
     /dev/rmt/[0-7]c[b][n]
     /etc/default/tar    Settings may look like this:
                         archive0=/dev/rmt/0
                         archive1=/dev/rmt/0n
                         archive2=/dev/rmt/1
                         archive3=/dev/rmt/1n
                         archive4=/dev/rmt/0
                         archive5=/dev/rmt/0n
                         archive6=/dev/rmt/1
                         archive7=/dev/rmt/1n
     /tmp/tar*

SEE ALSO
     ar(1), basename(1), cd(1), chown(1), cpio(1),  csh(1),  dir-
     name(1),   ls(1),   mt(1),   pax(1),  setfacl(1),  umask(1),
     mknod(1M), vold(1M), environ(5), mtio(7I)

DIAGNOSTICS
     Diagnostic messages are output for bad  key  characters  and
     tape  read/write errors, and for insufficient memory to hold
     the link tables.

NOTES
     There is no way to access for the _n-th occurrence of a file.

     Tape errors are handled ungracefully.

     When the Volume Management daemon is  running,  accesses  to
     floppy  devices  through  the conventional device names (for
     example, /dev/rdiskette) may not succeed.  See vold(1M)  for
     further details.

     The tar archive format allows UIDs and GIDs up to 2097151 to
     be  stored  in the archive header.  Files with UIDs and GIDs
     greater than this value will be archived with  the  UID  and
     GID of 60001.











SunOS 5.5.1         Last change: 20 Feb 1996                    9



