unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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

tar(1)                           User Commands                          tar(1)



NAME
       tar - create tape archives and add or extract files

SYNOPSIS
       tar  c[BDeEFhilnopPqvw@[0-7]][bfk][X...]  [blocksize]  [tarfile] [size]
       [exclude-file...] {file | -I include-file | -C directory file} ...

       tar r[BDeEFhilnqvw@[0-7]][bfk] [blocksize]  [tarfile]  [size]  {file  |
       -I include-file | -C directory file} ...

       tar   t[BeFhilnqv[0-7]][fk][X...]  [tarfile]  [size]  [exclude-file...]
       {file | -I include-file} ...

       tar u[BDeEFhilnqvw@[0-7]][bfk] [blocksize] [tarfile] [size] file...

       tar x[BeFhilmnopqvw[0-7]][fk][X...] [tarfile] [size]  [exclude-file...]
       [file...]

DESCRIPTION
       The  tar  command archives and extracts files to and from a single file
       called a tarfile. A tarfile is usually a magnetic tape, but it  can  be
       any  file. tar's actions are controlled by the key argument. The key is
       a string of characters 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 key string contains no SPACE
       characters.  Function modifier arguments are listed on the command line
       in the same order as their corresponding function modifiers  appear  in
       the key string.

       The  -I  include-file,  -C  directory  file, and file 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 (recur-
       sively) subdirectories of that directory.  Arguments  appearing  within
       braces ({ }) indicate that one of the arguments must be specified.

OPERANDS
       The following operands are supported:

       -C directory file       Performs  a  chdir  (see  cd(1))  operation  on
                               directory and performs  the  c  (create)  or  r
                               (replace) operation on file. Use short relative
                               path names for file.  If file is  ".",  archive
                               all  files  in  directory. This operand enables
                               archiving files from multiple  directories  not
                               related by a close common parent.



       -I include-file         Opens  include-file containing a list of files,
                               one per line, and treats it  as  if  each  file
                               appeared  separately  on  the  command line. Be
                               careful of trailing white spaces.  Also  beware
                               of  leading  white spaces, since, for each line
                               in the included file, the  entire  line  (apart
                               from the newline) will be used to match against
                               the initial string of files to include.  In the
                               case where excluded files (see X function modi-
                               fier) are also specified, they take  precedence
                               over all included files. If a file is specified
                               in both the exclude-file and  the  include-file
                               (or on the command line), it will be excluded.



       file                    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
                               file is the  path  name  of  a  directory,  the
                               action  applies to all of the files and (recur-
                               sively) subdirectories of that directory.

                               When a file is archived, and the  E  flag  (see
                               Function Modifiers) is not specified, the file-
                               name cannot exceed 256 characters. In addition,
                               it  must  be possible to split the name between
                               parent directory names so that the prefix is no
                               longer  than  155 characters and the name is no
                               longer than 100 characters. If E is  specified,
                               a  name  of  up  to  PATH_MAX characters may be
                               specified.

                               For example, a file whose  basename  is  longer
                               than 100 characters could not be archived with-
                               out using the E flag. A  file  whose  directory
                               portion is 200 characters and whose basename is
                               50 characters could be archived (without  using
                               E)  if  a  slash  appears in the directory name
                               somewhere in character positions 151-156.



   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  files  are  written  at  the  end  of  the
                tarfile.  A file created with extended headers must be updated
                with extended headers (see E flag under Function Modifiers). A
                file  created without extended headers cannot be modified with
                extended headers.



       t        Table of Contents. The names of the specified files are listed
                each  time  they occur in the tarfile.  If no file argument is
                given, the names of all  files  and  any  associated  extended
                attributes in the tarfile are listed. With the v function mod-
                ifier, additional information for the specified files is  dis-
                played.



       u        Update.  The named files 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 tarfile. An update can be
                rather slow. A tarfile created  on  a  5.x  system  cannot  be
                updated  on a 4.x system. A file created with extended headers
                must be updated with extended headers (see E flag under  Func-
                tion Modifiers).  A file created without extended headers can-
                not be modified with extended headers.



       x        Extract or restore. The named files  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.

                Absolute  path names contained in the tar archive are unpacked
                using the absolute path names, that is,  the  leading  forward
                slash (/) is not stripped off.

                If  a  named  file matches a directory whose contents has been
                written  to  the  tarfile,  this  directory   is   recursively
                extracted. The owner, modification time, and mode are restored
                (if possible); otherwise, to restore owner, you  must  be  the
                super-user.  Character-special and block-special devices (cre-
                ated by mknod(1M)) can only be extracted  by  the  super-user.
                If  no  file  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 ar-
                chive. Rather, use a command of the form:


                tar xvf ... /dev/rmt/0 `tar tf ... /dev/rmt/0 | \
                     grep 'pattern' `



       When extracting tapes created with the r or u functions, directory mod-
       ification  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 backspace or append capabilities.

       When  using  the  r,  u, or x functions or the X function modifier, the
       named files must match exactly the corresponding files in the  tarfile.
       For  example,  to  extract ./thisfile, you must specify ./thisfile, and
       not thisfile. The t function 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 blocksize     Blocking  Factor.  Use  when  reading or writing to raw
                       magnetic archives (see f below). The blocksize 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.)  The
                       maximum cannot exceed INT_MAX/512 (4194303).

                       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 blocksize 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.



       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.



       D               Data  change  warnings.  Used  with c, r, or u function
                       letters. Ignored with t or x function letters.  If  the
                       size  of  a   file  changes  while  the  file  is being
                       archived, treat this condition as a warning instead  of
                       as  an  error. A warning message will still be written,
                       but the exit status is not affected.



       e               Error. Exit immediately with a positive exit status  if
                       any  unexpected  errors  occur.  The  SYSV3 environment
                       variable overrides the default behavior. (See  ENVIRON-
                       MENT VARIABLES section below.)



       E               Write a tarfile with extended headers. (Used with c, r,
                       or u function letters. Ignored with  t  or  x  function
                       letters.) When a tarfile is written with extended head-
                       ers, the modification time is maintained with a  granu-
                       larity  of  microseconds  rather than seconds. In addi-
                       tion, filenames no longer than PATH_MAX characters that
                       could not be archived without E, and file sizes greater
                       than 8GB, are supported. The E flag is  required  when-
                       ever  the  larger files and/or files with longer names,
                       or whose UID/GID exceed 2097151, are to be archived, or
                       if time granularity of microseconds is desired.



       f               File.  Use  the  tarfile  argument  as  the name of the
                       tarfile. 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,  tar  will use the default values defined in
                       /etc/default/tar.  The  number  matching  the  archiveN
                       string  is  used as the output device with the blocking
                       and size specifications from the file. For example,


                       tar -c 2/tmp/*

                       writes the output to the device specified  as  archive2
                       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. The SYSV3 environment variable
                       overrides the default behavior. (See ENVIRONMENT  VARI-
                       ABLES section below.)



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



       i               Ignore directory checksum errors.



       k size          Requires tar to use the size argument as the size of an
                       archive in kilobytes. This is useful when  the  archive
                       is  intended  for  a  fixed  size device such as floppy
                       disks. Large files are then  split  across  volumes  if
                       they do not fit in the specified size.



       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
                       with the x function.



       n               The  file  being  read is a non-tape device. Reading of
                       the archive is  faster  since  tar  can  randomly  seek
                       around the archive.



       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  information). 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). This
                       is the default behavior if invoked as  super-user  with
                       the x function letter specified. If super-user, SETUID,
                       and sticky information are also  extracted,  and  files
                       are  restored  with  their  original owners and permis-
                       sions, rather than owned by root.  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.



       q               Stop after extracting the first occurrence of the named
                       file. tar will normally continue  reading  the  archive
                       after finding an occurrence of a file.



       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 list-
                       ing 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
                       response  is affirmative, the action is performed; oth-
                       erwise, the action is not performed. This function mod-
                       ifier cannot be used with the t function.



       X               Exclude.  Use  the exclude-file 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. Also beware of leading white spaces, since, for
                       each line in the excluded file, the entire line  (apart
                       from  the  newline)  will  be used to match against the
                       initial string  of  files  to  exclude.  Lines  in  the
                       exclude  file  are  matched  exactly,  so an entry like
                       "/var" will not exclude the /var directory  if  tar  is
                       backing  up  relative  pathnames. The entry should read
                       "./var" under these circumstances. The tar command does
                       not expand shell metacharacters in the exclude file, so
                       specifying entries like "*.o" will not have the  effect
                       of  excluding  all files with names suffixed with ".o".
                       If a complex list of  files  is  to  be  excluded,  the
                       exclude  file should be generated by some means such as
                       the find(1) command with appropriate conditions.

                       Multiple X arguments may be used, with one exclude-file
                       per  argument. In the case where included files (see -I
                       include-file operand) are also specified, the  excluded
                       files  take  precedence  over  all included files. If a
                       file is specified in  both  the  exclude-file  and  the
                       include-file  (or  on  the  command  line),  it will be
                       excluded.



       @               Include extended attributes in archive. By default, tar
                       does not place extended attributes in the archive. With
                       this flag, tar will look for extended attributes on the
                       files  to  be placed in the archive and add them to the
                       archive. Extended attributes go in the archive as  spe-
                       cial  files  with a special type label. When this modi-
                       fier is used with the x function,  extended  attributes
                       are  extracted from the tape along with the normal file
                       data. Extended attribute files can  only  be  extracted
                       from  an  archive  as  part  of  a normal file extract.
                       Attempts to explicitly extract  attribute  records  are
                       ignored.



       [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 is
                       specified, the entry in /etc/default/tar with digit "0"
                       is the default.



USAGE
       See  largefile(5)  for  the  description  of  the  behavior of tar when
       encountering files greater than or equal to 2 Gbyte ( 2**31 bytes).

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

       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 spe-
       cial devices, among  others,  but  is  intended  principally  for  tape
       devices.

       For information on tar header format, see archives(4).

EXAMPLES
       Example 1: Creating an archive of your home directory

       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 .
       messages from 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 exam-
       ple).  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  com-
       mand:

       example% tar tvf /dev/rmt/0

       The output will be similar to the following for the POSIX locale:

       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 user-id/group-id of ./test.c

         o  column 3 is the size of ./test.c in bytes

         o  column  4  is  the modification date of ./test.c. When the LC_TIME
            category is not set to the POSIX locale, a  different  format  and
            date order field may be used.

         o  column 5 is the name of ./test.c


       To extract files from the archive:

       example% tar xvf /dev/rmt/0
       messages from 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 sec-
       ond  archives from a tape with multiple archives on it, the non-rewind-
       ing version of the tape device name must be used with  the  f  function
       modifier, as follows:

       example% tar xvfp /dev/rmt/0n read first archive from tape
       messages from tar
       example% tar xvfp /dev/rmt/0n read second archive from tape
       messages from tar
       example%

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

       Example  2:  Archiving files from /usr/include and from /etc to default
       tape drive 0

       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
       and all the other files in /usr/include ...
       ./chown and all the other files in /etc

       To extract all files in the include directory:

       example% tar xv include
       x include/, 0 bytes, 0 tape blocks \
           and all files under include ...

       Example 3: Transferring files across the network

       The following is an example using tar to transfer files across the net-
       work. First, here is how to archive files from the local machine (exam-
       ple) to a tape on a remote system (host):

       example% tar cvfb - 20 files | \
           rsh host dd of=/dev/rmt/0  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 function modifier, speci-
       fying the name of the output tarfile using the f function modifier (the
       standard  output  is where the tarfile appears, as indicated by the `-'
       sign), and specifying the blocksize (20) with the b function  modifier.
       If  you  want  to  change  the blocksize, you must change the blocksize
       arguments both on the tar command and on the dd command.

       Example 4: Retrieving files from a tape on the remote  system  back  to
       the local system

       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 files
       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 function modi-
       fier, telling tar it is reading from a pipe with the B  function  modi-
       fier,  specifying  the  name  of the input tarfile using the f function
       modifier (the standard input is where the tarfile appears, as indicated
       by the "-" sign), and specifying the blocksize (20) with the b function
       modifier.

       Example 5: Creating an archive of the home directory

       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 nomi-
       nal blocking factor:

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

       Attempt to recognize this archive's actual blocking factor using a nom-
       inal blocking factor that is too small:

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

ENVIRONMENT VARIABLES
       SYSV3           This variable is used to override the default  behavior
                       of  tar,  provide  compatibility  with INTERACTIVE UNIX
                       Systems and SCO UNIX installation scripts,  and  should
                       not be used in new scripts. (It is intended for compat-
                       ibility purposes only.) When set, the  following  func-
                       tion modifiers behave differently:

                       F filename      Uses  filename to obtain a list of com-
                                       mand line switches and files  on  which
                                       to operate.




                       e               Prevents  files from being split across
                                       volumes. If there is insufficient  room
                                       on  one  volume,  tar prompts for a new
                                       volume. If the file will not fit on the
                                       new volume, tar exits with an error.




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

EXIT STATUS
       The following exit values are returned:

       0        Successful completion.



       >>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*



ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE  TYPEATTRIBUTE   VALUE   AvailabilitySUNWcsu
       CSIEnabled Interface StabilityStable


SEE ALSO
       ar(1),  basename(1),  cd(1),  chown(1),  cpio(1),  csh(1),  dirname(1),
       find(1),  ls(1),  mt(1),  pax(1),  setfacl(1),   umask(1),   mknod(1M),
       vold(1M),  archives(4),  attributes(5),  environ(5),  fsattr(5), large-
       file(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 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.

       If  an  archive is created that contains files whose names were created
       by processes running in multiple locales, a single locale that  uses  a
       full  8-bit codeset (for example, the en_US locale) should be used both
       to create the archive and to extract files from the archive.

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

       Since tar has no options, the standard "--" argument that  is  normally
       used  in  other  utilities  to  terminate recognition of options is not
       needed. If used, it is recognized only as the  first  argument  and  is
       ignored.

       Since  -C  directory  file and -I include-file are multi-argument oper-
       ands, any of the following methods can be used to archive or extract  a
       file named -C or -I:

       1.  Specify  them  using  file operands containing a / character on the
           command line (such as /home/joe/-C or ./-I).


       2.  Include them in an include file with -I include-file.


       3.  Specify the directory in which the file resides:


           -C directory -C

           or


           -C directory -I


       4.  Specify the entire directory in which the file resides:


           -C directory .




SunOS 5.10                        13 Feb 2004                           tar(1)