unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

TAR(1)                      General Commands Manual                     TAR(1)



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 ar-
       chive, called a tarfile.  A tarfile is usually a magnetic tape, but  it
       can  be  any file.  tar's actions are controlled by the first argument,
       the key, a string of characters 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 appear-
       ance of a directory name refers recursively to the files and  subdirec-
       tories 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 argu-
              ments 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 block-
              ing  factors result in better throughput, longer blocks on nine-
              track tapes, and better media utilization.

       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 immediately with a
              positive exit status.

       f      Use the next argument as the name of the tarfile.  If f is omit-
              ted,  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 directo-
              ries 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 directo-
              ries.  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 messages are printed.

       m      Do not extract modification times of extracted files.  The modi-
              fication 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,  ignoring  the
              present  umask(2V).   SetUID  and  sticky  information  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 dis-
              plays the name of each file tar treats, preceded 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.  Multiple 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 speci-
       fied 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) opera-
       tion, 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 specifi-
       cally  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 ar-
       chive.  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 Eth-
       ernet.   First,  here  is  how  to archive files from the local machine
       (example) to a tape on a remote system (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 specify-
       ing the blocksize (20) with the b option.  If you want  to  change  the
       blocksize, you must change the blocksize arguments both on the tar com-
       mand and on the dd command.

       Now, here is how to use tar to get files from a tape on the remote sys-
       tem 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 ar-
       chive 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 modi-
       fication times may not be set correctly.

       Files with names longer than 100 characters cannot be processed.

       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 'pattern'`



                               16 February 1988                         TAR(1)