Seth Woolley's Man Viewer

Manual for star - man star

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

STAR(1)                     Schilys USER COMMANDS                     STAR(1)



NAME
       star(1,4) - unique standard tape archiver

SYNOPSIS
       star(1,4)  command [ options ] file1 ... filen
       ustar command [ options ] file1 ... filen
       tar   command [ options ] file1 ... filen
       star(1,4)  -copy   [ options ] file1 ... directory

DESCRIPTION
       Star is a very fast tar(1) like tape archiver with improved functional-
       ity.

       Star archives and extracts multiple files to and  from  a  single  file(1,n)
       called  a tarfile.  A tarfile is usually a magnetic tape, but it can be
       any file.  In all cases, appearance of a directory name refers  to  the
       files and (recursively) subdirectories of that directory.

       Star's  actions  are controlled by the mandatory command flags from the
       list below.  The way star(1,4) acts may be modified by additional options.

       Note that unpacking tar archives may be a security  risk  because  star(1,4)
       may overwrite existing files.  See SECURITY NOTES for more information.

FEATURES
       Star includes the first free implementation  of  POSIX.1-2001  extended
       tar  headers.  The  extended  tar headers define a new standard way for
       going beyond the limitations of the historic tar  format.   They  allow
       (among  others)  to  archive all UNIX time(1,2,n) stamps in(1,8) sub-second resolu-
       tion, files of arbitrary size and filenames without  length  limitation
       using UNICODE UTF-8 coding for best exchange compatibility.

       Star  by  default  uses a fifo to optimize data flow from/to tape. This
       results in(1,8) a normally streaming tape  during  the  whole  backup.   See
       -fifo  and  fs=  option to get information on how to find the best fifo
       size.

       Star includes a pattern matcher to control the list of files to be pro-
       cessed.  This  gives a convenient interface for archiving and restoring
       complex lists of files. In conjunction with the -w flag it is  easy  to
       merge(1,8) a tar archive into an existing file(1,n) tree. See also -U option.  In
       create mode use the pat= option to specify  either  select(2,7,2 select_tut)  or  exclude
       patterns  (depending  on the -V flag). In extract or list mode all file(1,n)
       type arguments are interpreted as select(2,7,2 select_tut) patterns  while  the  patterns
       specified  with  the  pat= option may be used as select(2,7,2 select_tut) or exclude pat-
       terns (depending on the -V flag).  Have a look(1,8,3 Search::Dict) at  the  description  of
       the  -C  option to learn how fetch files from a list of directories (in(1,8)
       create mode) or to distribute  files  to  a  list  of  directories  (in(1,8)
       extract mode).  A substitute option allows ed(1) like pattern substitu-
       tion in(1,8) file(1,n) names.

       Star includes a sophisticated diff command. Several diff options  allow
       user tailorable functionality.  Star won't show you differences you are
       not interested in.  Check the diffopts= option for more details.

       Star has no limitation on filename length. Pathnames and  linknames  up
       to  PATH_MAX  (1023 bytes  with  old  OS  versions  and 4095 bytes with
       POSIX.1-2001) may be archived. Later versions may be able to deal  with
       longer pathnames.

       Star deals with all 3 times, available for files on UNIX systems if(3,n) the
       archive format is either chosen from the star(1,4) specific formats or is  a
       format that uses POSIX.1-2001 extended headers.  This is either done in(1,8)
       second resolution by using  a  star(1,4)  specific  POSIX.1-1988  compatible
       extension  or  in(1,8)  sub second resolution by using POSIX.1-2001 extended
       headers.  Star is able to store and restore all 3 times  (mtime,  atime
       and  even  ctime).  On  Solaris 2.x systems, star(1,4) is able to do backups
       without changing any of the 3 the times.

       If used with the H=ustar option, or if(3,n) called as ustar or tar while the
       H=headertype option is not used, star(1,4) is 100% POSIX compliant.

       Star's default format (if(3,n) called as star(1,4)) is xstar and is as posix com-
       pliant as possible. Enhancements to the standard that  prevent  correct
       extraction  of  single  files when using a different tar implementation
       that is only POSIX.1-1988 compliant may occur,  but  they  only  affect
       single  files with a pathname that is longer than 100+130 chars or when
       archiving sparse files with the -sparse option in(1,8)  effect.   All  other
       files will extract correctly.  See the description for the H=headertype
       option below for more information on archive formats and  possible  ar-
       chive interchange problems.

       Star makes it easy to repair corrupted filesystems. After a fsck -y has
       been run on the filesystem, star(1,4) is able to restore  only  the  missing
       files automatically.  Use then star(1,4) -diff to check for differences (see
       EXAMPLES for more information).

       Star automatically recognizes the type of the archive.  Star  therefore
       is able to handle features and properties of different archive types in(1,8)
       their native mode, if(3,n) it knows about the peculiarities of  the  archive
       type.   See the H=headertype option for more details.  To be able to do
       this, star(1,4) adds hidden fingerprints to the archive header  that  allows
       to  recognise  all star(1,4) specific archive formats. The GNU tar format is
       recognised by the way it deviates from the standard.

       Star automatically recognizes and handles byte swapped archives.  There
       is no option to manually control byte swapping.

       Star  automatically  recognizes  and handles compressed archives inside
       plain files.

       Star is able to archive and restore  Access  Control  Lists  for  files
       using POSIX.1-2001 extended headers.

COMMAND
       In native mode, star(1,4) is compatible to the command line syntax of a typ-
       ical POSIX command and for this reason expects commands and options  to
       start with a single dash (-). In this case, commands and options may be
       specified separately, all boolean or  increment  type  options  may  be
       specified  either  separately  or combined.  For compatibility with GNU
       programs, long options may alternatively start with a double dash.   In
       compatibility  mode  to POSIX tar, star(1,4) expects commands and options to
       appear as one single string(3,n) that does not start with a dash.  In  POSIX
       tar  compatibilitx  mode, additional non POSIX options may be specified
       but must appear after the POSIX options and  their  args  and  need  to
       start with a dash.

       -c     Create  a  new  tarfile  and write(1,2) named(5,8) files into it.  Writing
              starts at the beginning of tarfile.  See -v option for  informa-
              tion  on how to increase verbosity while the archive is written.

       -copy  Copy named(5,8) files to the target directory which is the last  file(1,n)
              type  argument.  The target directory must exist.  The shorthand
              -cx instead of -copy is not allowed  because  this  could  be  a
              result of a typo.

              If  the  option  -diff has been specified in(1,8) addition, star(1,4) per-
              forms a one pass  directory  tree  compare  instead  of  copying
              files.   The  shorthand  -c -diff instead of -copy -diff is also
              allowed.

              On operating systems with slow file(1,n) I/O (such as Linux), it  may
              help  to  use  -no-fsync in(1,8) addition, but then star(1,4) is unable to
              detect all error(8,n) conditions; so use with care.

              If the option -t has been specified in(1,8) addition, the  last  file(1,n)
              type argument is not a target directory and star(1,4) is performing a
              one pass listing instead of copying files.  This makes sense  as
              the  listing  from  star(1,4)  may be better readable than the output
              from ls -lR.  The shorthand -c -t or -ct instead of -copy -t  is
              also allowed.

              The  job  is  by  default  done  in(1,8) the best archive mode.  This
              implies that it defaults to  H=exustar  -dump.   When  in(1,8)  -copy
              mode,  star(1,4)  forks  into two processes and data exchange is done
              via the shared memory from the FIFO.  This gives the best possi-
              ble performance.  Without FIFO, the -copy mode will not work.

              The  list=  option, patterns and substitutions apply only to the
              create side of the copy command.

       -diff  Compare the content and the attributes of the files from the ar-
              chive  in(1,8)  tarfile  to the filesystem.  This may also be used to
              compare two file(1,n) trees in(1,8) the filesystem.  If you use a  set(7,n,1 builtins)  of
              diffopts  that fits your needs, it will give - in(1,8) many cases - a
              more readable output than diff  -r.   If  you  use  star(1,4)'s  dump
              extensions  for the tar archive, the -diff option allows to find
              even if(3,n) the directory in(1,8) the file(1,n) tree contains more files  than
              the  archive. This way, it is possible to compare all properties
              of two file(1,n) trees in(1,8) one run.  See diffopts  for  more  details.
              Adding  one or more -v options increases the verbosity. With -vv
              and above, the directory content is compared also  if(3,n)  in(1,8)  -dump
              mode.

       -n     No  extraction.  Show what star(1,4) would do, in(1,8) case the -x command
              had been specified.

       -r     Replace files in(1,8) a tarfile.  The named(5,8) files are written to  the
              end  of tarfile.  This implies that later, the appropriate files
              will be found more than once on the tarfile.

       -t     Table of contents.  List the contents of the tarfile.  If the -v
              flag is used, the listing is similar to the format of ls -l out-
              put.  With this option, the flags -a, -atime and -ctime  have  a
              different  meaning  if(3,n)  the  archive  is in(1,8) star(1,4), xstar, xustar,
              exustar, or pax format.  The  option  -a  or  -atime  lists  the
              access(2,5)  time(1,2,n) instead of the modification time(1,2,n), the option -ctime
              lists the file(1,n) creation time(1,2,n) instead of the  modification  time.
              The  option  -tpath may be used in(1,8) addition to modify the output
              so it may be used in(1,8) shell scripts.

       -u     Update a tarfile.  The named(5,8) files are written  to  the  end  of
              tarfile  if(3,n) they are not already there or if(3,n) the files are newer
              than the files of the same name found in(1,8) the  archive.   The  -r
              and  -u  command only work if(3,n) the tar archives is a regular file(1,n)
              or if(3,n) the tar archive is an unblocked tape that may backspace.

       -x     Extract the named(5,8) files from the tarfile.  If no filename  argu-
              ment  or pattern is specified, the entire content of the tarfile
              is restored.  If the -U flag is not used, star(1,4) extracts no  file(1,n)
              which is older than the corresponding file(1,n) on disk.

              On  operating systems with slow file(1,n) I/O (such as Linux), it may
              help to use -no-fsync in(1,8) addition, but then star(1,4)  is  unable  to
              detect all error(8,n) conditions; so use with care.

       Except for the shorthands documented above, exactly one of the commands
       above must be specified.

       If one or more patterns or substitution commands have  been  specified,
       they  apply to any of the command listed above.  In copy mode, all pat-
       terns and substitute commands apply to the create side.


OPTIONS
       -help  Print a summary of the most important options for star(1,4)(1).

       -xhelp Print a summary of the less(1,3) important options for star(1,4)(1).

       -/     Don't strip leading slashes from file(1,n) names when  extracting  an
              archive.  Tar archives containing absolute pathnames are usually
              a bad idea.  With other tar implementations, they  may  possibly
              never  be extracted without clobbering existing files.  Star for
              that reason, by default strips leading  slashes  from  filenames
              when  in(1,8) extract mode.  As it may be impossible to create an ar-
              chive where leading slashes have been stripped  while  retaining
              correct  path names, star(1,4) does not strip leading slashes in(1,8) cre-
              ate mode.

              See SECURITY NOTES for more information.

       -..    Don't skip files that contain /../ in(1,8)  the  name.  Tar  archives
              containing  names with /../ could be used to compromise the sys-
              tem. If they are unpacked together with a lot  of  other  files,
              this  would  in(1,8) most cases not even be noticed. For this reason,
              star(1,4) by default does not extract files that contain /../ in(1,8)  the
              name if(3,n) star(1,4) is not in(1,8) interactive mode (see -w option).

              See SECURITY NOTES for more information.

       -0

       -1

       -2

       -3

       -4

       -5

       -6

       -7     Select  an archive entry from /etc/default/star(1,4).  The format for
              the  archive  entries   is   the   same   as   the   format   in(1,8)
              /etc/default/tar in(1,8) Solaris.

       -acl   Handle  Access  Control  List  (ACL)  information  in(1,8) create and
              extract mode.  If -acl has been specified,  star(1,4)  is  in(1,8)  create
              mode  and the header type is exustar, star(1,4) will add ACL informa-
              tion to the archive using  POSIX.1-2001  extended  headers.   If
              -acl  has  been specified and star(1,4) is in(1,8) extract mode, star(1,4) will
              try to restore ACL information. If there is no  ACL  information
              for  one  or  all  files in(1,8) the archive, star(1,4) will clear(1,3x,3x clrtobot) the ACL
              information for the specific file.  Note that if(3,n)  -acl  has  not
              been  specified, star(1,4) will not handle ACL information at all and
              files may inherit ACL information from the  parent  directories.
              If  the -acl option has been specified, star(1,4) assumes that the -p
              option has been specified too.

       artype=headertype
              Generate a tape archive in(1,8) headertype format.  If this option is
              used  in(1,8)  extract/list  mode  this  forces star(1,4) to interpret the
              headers to be of type headertype.  As star(1,4) even  in(1,8)  case  of  a
              user  selected  extract  archive format does format checking, it
              may be that you will not be able to unpack  a  specific  archive
              with  all possible forced archive formats. Selecting the old tar
              format for extraction will always work though.  Valid  parameter
              for headertype are:

              help      Print a help message about possible header types.

              v7tar     Old  UNIX V7 tar format.  This archive format may only
                        store plain files.  Pathnames or linknames longer than
                        99 chars may not be archived.

                        If  the  v7tar format has been selected, star(1,4) will not
                        use enhancements to the historic UNIX V7  tar  format.
                        File  size  is  limited  to 2 GB - 2 bytes, uid/gid is
                        limited to 262143.  Sparse files  will  be  filled  up
                        with zeroes.

              tar       Old BSD UNIX tar format.  This archive format may only
                        store plain files,  directories  and  symbolic  links.
                        Pathnames or linknames longer than 99 chars may not be
                        archived.  See also the -d option as a  note  to  some
                        even older tar implementations.

                        If the tar format has been selected, star(1,4) will not use
                        enhancements to the historic tar format.  File size is
                        limited  to  2  GB  -  2  bytes, uid/gid is limited to
                        262143.  Sparse files will be filled up with zeroes.

              star(1,4)      Old star(1,4) standard format. This is  an  upward/downward
                        compatible enhancement of the old (pre Posix) UNIX tar
                        format.  It has been introduced in(1,8) 1985 and  therefore
                        is not Posix compliant.  The star(1,4) format allows to ar-
                        chive special files (even sockets) and records  access(2,5)
                        time(1,2,n)  and creation time(1,2,n) besides the modification time.
                        Newer versions of the old star(1,4) format allow very  long
                        filenames  (100+155 chars  and above), linknames > 100
                        chars and sparse files.  This format is able  to  copy
                        the  device  nodes  on  HP-UX that have 24 bits in(1,8) the
                        minor device number, which is more then  the  21  bits
                        that  are  possible with the POSIX-1003.1-1988 archive
                        format.

                        The nonstandard extensions are located  in(1,8)  the  space
                        between  the link(1,2) name and the POSIX file(1,n) name prefix.
                        As the star(1,4) format does not use a POSIX magic(4,5)  string(3,n),
                        the  extensions  do  not  interfere with the POSIX tar
                        formats.  The last 4 bytes of the tar header contain a
                        'tar\0' signature.

              gnutar    This  is  a commonly used, but unfortunately not Posix
                        compliant (although designed after  1987)  enhancement
                        to  the  old  tar  format.  The gnutar format has been
                        defined between 1989 and 1994.  Do not use the  gnutar
                        archive  format  unless  you want to create an archive
                        for a target system that is known  to  have  only  the
                        gnutar  program  available.  The gnutar archive format
                        violates basic rules for any (even the  historic)  tar
                        archive  format.   Using  the  gnutar  archive  format
                        causes a high risk that the resulting archive may only
                        be  read(2,n,1 builtins)  by gnutar or by star(1,4).  The implementation of
                        the gnutar archive format within star(1,4) is not complete,
                        but  sufficient  for  most gnutar archives.  See NOTES
                        for more information.

              ustar     IEEE/Posix1003/IEC-9945-1-1988  Standard  Data  Inter-
                        change  format.  With this option in(1,8) effect, star(1,4) will
                        generate 100%  POSIX.1-1988  compliant  tar  archives.
                        Files  with  pathnames  longer  than  100+155 chars or
                        linknames longer than 100 chars may not  be  archived.
                        If  star(1,4) is called as ustar the default archive format
                        is ustar.

                        If the ustar format has been selected, star(1,4)  will  not
                        use  enhancements  to the POSIX.1-1988 tar format, the
                        archive will be strictly  conforming.   File  size  is
                        limited  to  8  GB,  uid/gid/major/minor is limited to
                        2097151.  Sparse files will be filled up with  zeroes.

              pax       The  IEEE/Posix1003/IEC-9945-1-1988  successor  is the
                        POSIX-1003.1-2001 Standard  Data  Interchange  format.
                        It is called the pax archive format.

                        If the pax format has been selected, star(1,4) will not use
                        enhancements to the POSIX.1-2001 tar format,  the  ar-
                        chive  will  be  strictly  conforming.   File  size is
                        unlimited,   uid/gid/uname(1,2)/gidname    is    unlimited,
                        major/minor  is limited to 2097151.  Sparse files will
                        be filled up with zeroes.

              xstar     The extended standard tar format has  been  introduced
                        in(1,8)  1994.   Star  uses the xstar format as default ar-
                        chive format.  This is an  upward/downward  compatible
                        enhancement  of the IEEE/Posix1003/IEC-9945-1 Standard
                        Data Interchange format.  It allows among others  very
                        long  filenames  (100+130 chars and above) and records
                        access(2,5) time(1,2,n) and creation time.

                        The access(2,5) time(1,2,n) and creation time(1,2,n) are  stored  at  the
                        end  of  the  POSIX  file(1,n) name prefix (this limits the
                        prefix to 130 chars).  These extensions do not  inter-
                        fere  with  the POSIX standard as the fields for mtime
                        and ctime field are always separated  from  the  POSIX
                        file(1,n)  name prefix by a null byte.  The last 4 bytes of
                        the tar header contain a 'tar\0' signature.

                        The xstar format is the default format  when  star(1,4)  is
                        neither called as tar nor called as ustar.

              xustar    A  new  format introduced 1998, that omits the 'tar\0'
                        signature at the end of the tar header. It  is  other-
                        wise  identical  to  the  xstar  format.   As some tar
                        implementations do not follow the POSIX rules and com-
                        pute  the  checksum for less(1,3) than 512 bytes of the tar
                        header, this format may help to  avoid  problems  with
                        these broken tar implementations.  The main other dif-
                        ference to the xstar format is that the xustar  format
                        uses POSIX.1-2001 extended headers to overcome limita-
                        tions of the historic tar format while the xstar  for-
                        mat uses proprietary extensions.  The xustar format is
                        the default format when star(1,4) is called as tar.

                        File  size  is  unlimited,  uid/gid/uname(1,2)/gidname   is
                        unlimited,  major/minor  is  unlimited.   Sparse files
                        will be archived correctly.

              exustar   A format similar to the xustar format but with  forced
                        POSIX.1-2001 extended headers.  If this format is used
                        together with the -acl  option,  star(1,4)  records  Access
                        Control Lists (ACLs) in(1,8) POSIX.1-2001 extended headers.

                        File  size  is  unlimited,  uid/gid/uname(1,2)/gidname   is
                        unlimited,  major/minor  is  unlimited.   Sparse files
                        will be archived correctly.

              suntar    The extended header format  found  on  Solaris  7/8/9.
                        This  format is similar to the pax format but does not
                        handle atime and ctime and in(1,8) addition uses 'X' as the
                        typeflag for the extended headers instead of the stan-
                        dard 'x'.

                        File  size  is  unlimited,  uid/gid/uname(1,2)/gidname   is
                        unlimited,  major/minor  is  unlimited.   Sparse files
                        will be filled up with zeroes.

              bin       The cpio UNIX V7 binary format.  This is a format with
                        big  interoperability problems. Try to avoid this for-
                        mat.  It is only present to  make  the  scpio  command
                        SVr4 compliant.

              cpio      The  POSIX.1-1988  cpio format. This format uses octal
                        ascii(1,7) headers. A similar format is created by  calling
                        cpio  -o  -c on pre SYSVr4 systems and by calling cpio
                        -o -Hodc on SYSVr4  systems.   The  POSIX.1-1988  cpio
                        format  allows a file(1,n) name length up to 262142 charac-
                        ters and allows to archive nearly any file(1,n) type.  File
                        size  is limited to 8 GB, uid/gid/st_dev is limited to
                        262143.  The way major and minor  device  numbers  are
                        stored  inside  the  st_dev  field  is  implementation
                        dependent.

                        Even though this archive  format  is  covered  by  the
                        POSIX.1-1988 standard, it has a lower portability than
                        the ustar format. Try to avoid the cpio  archive  for-
                        mat.

              odc       This archive format is similar to the The POSIX.1-1988
                        cpio format but the file(1,n) name length is limited to 255
                        characters  and  the  socket(2,7,n) file(1,n) type is not allowed.
                        This archive format has been introduced to  allow  non
                        POSIX cpio implementations such as the cpio program on
                        SYSV to accept(2,8) the archive. Use this  format  whenever
                        you  are  not sure if(3,n) the target system offers a fully
                        POSIX compliant cpio program.

                        Even though this archive  format  is  covered  by  the
                        POSIX.1-1988 standard, it has a lower portability than
                        the ustar format. Try to avoid the odc archive format.

              asc       Tell star(1,4) to create a cpio archive in(1,8) the ascii(1,7) format
                        that is created with cpio -o -c on SYSVr4 systems.  It
                        uses  extended  (32  bit) numbers for uid's, gid's and
                        device numbers but limits the file(1,n) size to 2  GB  -  2
                        bytes although the format has been specified after the
                        POSIX.1-1988 cpio format.  Try to avoid  the  asc  ar-
                        chive format because of it's limited portability.

              crc       This  format  is similar to the asc cpio format but in(1,8)
                        addition uses a simple byte based checksum called CRC.
                        Try  to  avoid  the crc archive format because of it's
                        limited portability.


              All tar archive formats may be interchanged if(3,n) the archive  con-
              tains  no  files  that  may not be archived by using the old tar
              format.  Archives in(1,8) the xstar format may be  extracted  by  any
              100% POSIX compliant tar implementation if(3,n) they contain no files
              with pathnames > 100+130 chars and if(3,n)  they  contain  no  sparse
              files that have been archived by using the -sparse option.


       -ask_remove
              obsoleted by -ask-remove

       -ask-remove
              Ask  to  remove  non  writable files on extraction.  By default,
              star(1,4) will not overwrite files  that  are  read(2,n,1 builtins)  only.   If  this
              option  is  in(1,8)  effect,  star(1,4)  will ask whether it should remove
              these files to allow the extraction of a file(1,n) in(1,8)  the  following
              way:

                     remove 'filename' ? Y(es)/N(o) :

       -atime, -a
              Reset  access(2,5)  time(1,2,n)  of files after storing them to tarfile.  On
              Solaris 2.x, (if(3,n) invoked by root) star(1,4) uses the _FIOSATIME ioctl
              to  do  this.  This  enables  star(1,4)  not to trash the ctime while
              resetting the atime of the files.  If the -atime option is  used
              in(1,8)  conjunction  with  the  list command, star(1,4) lists access(2,5) time(1,2,n)
              instead of modification time. (This works  only  in(1,8)  conjunction
              with the star(1,4), xstar, xustar, exustar, and with the pax format.)
              Another option to retain the access(2,5) time(1,2,n) for the the files  that
              are going to be archives is to readonly mount(2,8) a UFS snapshot and
              to archive files from the mount(2,8) point of the UFS snapshot.

       -B     Force star(1,4) to perform multiple reads (if(3,n) necessary)  to  fill  a
              block.  This option exists so that star(1,4) can work across the Eth-
              ernet, since pipes and sockets return partial blocks  even  when
              more  data  is coming.  If star(1,4) uses stdin as archive file(1,n), star(1,4)
              behaves as if(3,n) it has been called with the -B option.   For  this
              reason, the option -B in(1,8) practice is rarely needed.

       -block-number
              Print  the  archive  block  number (archive offset / 512) at the
              beginning of each line when in(1,8)  verbose  mode.  This  allows  to
              write(1,2) backup scripts that archive the offsets for files and that
              use

                   mt fsr blockno

              to skip to the tape block number of interest in(1,8) a fast way if(3,n)  a
              single file(1,n) needs to be restored.

       blocks=#, b=#
              Set  the  blocking  factor(1,6)  of  the tarfile to # times 512 bytes
              (unless a different multiplication factor(1,6) has been  specified  -
              see  bs=  option  for posible multiplication factors).  Changing
              the blocking factor(1,6) only makes sense when the archive is located
              on  a  real  tape device or when the archive is accessed via the
              remote tape protocol (see f= option below).  The default  is  to
              use  a  blocking  factor(1,6)  of 20 i.e.  10 kBytes.  Increasing the
              blocksize will speed up the backup.  For portability  with  very
              old  tar  implementations (pre BSD 4.2 or pre AT&T SVR4), block-
              size should not be more than 10 kBytes.  For  POSIX.1-1988  com-
              patibility,  blocksize  should  be  no more than 10 kBytes.  For
              POSIX.1-2001 compatibility, blocksize should  be  no  more  than
              32 kBytes.  Most systems also have a hardware limitation for the
              blocksize, 32 kBytes and 63 kBytes are  common  limits  on  many
              systems.   The upper limit in(1,8) any case is the size of the buffer
              RAM in(1,8) the tape drive.  Make a test if(3,n) you  want  to  make  sure
              that  the  target system will handle the intended blocksize.  If
              you use star(1,4) for data exchange via tape, it is a  good  idea  to
              use  a blocksize of 10 kBytes unless you are sure that the read-
              ing system will handle a larger blocksize.  If you use star(1,4)  for
              backup  purposes  with recent hardware (e.g. DLT tape drives), a
              blocksize of 256 kBytes results in(1,8) sufficient speed and seems to
              be  a good choice.  Star allows block sizes up to 2 GByte if(3,n) the
              system does not impose a smaller limit.  If you want  to  deter-
              mine  the blocking factor(1,6) when reading an unknown tar archive on
              tape, specify a blocking factor(1,6) that is higher than the supposed
              blocking  factor(1,6)  of  the  tape.   Star  then will determine the
              blocking factor(1,6) by reading the first  record  of  the  tape  and
              print a message:

                     star: Blocksize = # records.

              Where  #  is the blocking factor(1,6) in(1,8) multiples of 512 bytes.  The
              blocks= option and the bs=  option  are  equivalent  methods  to
              specify the tape block size.  The blocks= option is preferred by
              people who like to use an option that  behaves  similar  to  the
              interface of the historic tar(1) implementations.

       bs=#   Set  output  block size to #.  You may use the same method as in(1,8)
              dd(1) and sdd(1).  The number representing the size is taken  in(1,8)
              bytes  unless  otherwise  specified.   If  a  number is followed
              directly by the letter `.', `w', `b', `k',  `m',  `g',  `t',  or
              `p',  the  size  is  multiplied  by  1, 2, 512, 1024, 1024*1024,
              1024*1024*1024, 1024*1024*1024*1024 or 1024*1024*1024*1024*1024.
              If  the size consists of numbers separated by `x' or `*', multi-
              plication of the two numbers is performed.   Thus  bs=7x8k  will
              specify  a blocksize of 56 kBytes.  Blocksize must be a multiple
              of 512 bytes.  See also the description of  the  blocks=  option
              for  more details on blocksizes.  The option bs= is preferred by
              people who like to use an option that  behaves  similar  to  the
              interface used by dd(1) and sdd(1).

       -bsdchdir
              Switch  the behavior of the C= option to BSD style.  The default
              behavior of star(1,4) is to stay in(1,8) a working directory until  a  new
              C=  is seen.  With BSD tar, the C= option is only related to the
              next file(1,n) type argument.

       -bz    run the input or output through a bzip2 pipe(2,8) - see option -z  -Z
              and  -j  below.   As the -bz the -j the -Z and the -z option are
              non standard, it makes sense to omit the -bz the -j the  -Z  and
              the  -z options inside shell scripts if(3,n) you are going to extract
              a compressed archive that is located inside a plain file(1,n) as star(1,4)
              will  auto(5,8) detect compression and choose the right decompression
              option to extract.

       C=dir  Perform a chdir(2) operation to dir before storing or extracting
              the  next  files.   In all cases, star(1,4) will perform the chdir(2)
              operation relative to  the  current  working  directory  of  the
              shell.

                    In  list  mode  (with  the  -t flag), star(1,4) ignores all -C
                     options.

                    In create mode (with the -c, -r and -u flag), star(1,4)  walks
                     through  all -C options and file(1,n) type arguments.  While a
                     BSD derived tar(1) implementation goes back to  the  cur-
                     rent  working  directory  after storing one file(1,n) argument
                     that immediately follows the -C option, star(1,4) changes  the
                     directory  only  if(3,n)  a new -C option follows.  To emulate
                     the behavior of a BSD derived tar(1), add a -C .   option
                     after the file(1,n) argument.

                    In  extract  mode  (with the -x, -n and -diff flag), star(1,4)
                     builds a pattern list together with corresponding  direc-
                     tories   from  previous  C=dir  options  and  performs  a
                     chdir(2) to the corresponding  directory  of  a  matching
                     pattern.   All  pat=  options  that do not follow a C=dir
                     option are interpreted as if(3,n) they were preceded by a -C .
                     option.  See EXAMPLES for more information.

       compress-program=name
              Set  a  named(5,8)  compress program.  The program must compress in(1,8) a
              pipe(2,8) when called without parameters and decompress when run with
              the  -d  option  in(1,8) a pipe.  This option is otherwise similar to
              the -z the -j the -Z and the -bz option.

       -copydlinks
              Try to  recursively  copy  the  content  of  linked  directories
              instead  of  creating  the link. This is an experimental feature
              that may help to unpack archives on DOS.

       -copyhardlinks
              This option allows to copy hardlinked targets rather than creat-
              ing  the link.  It helps to extract tar files on systems that do
              not implement hardlinks (e.g. BeOS).

       -copylinks
              This option allows to copy both,  hard-  and  symlinked  targets
              rather  than  creating a link.  It helps to extract tar files on
              systems that do not implement links (e.g. OS/2).  To extract and
              copy  all symlinks correctly, you may need to call star(1,4) twice as
              star(1,4) cannot copy files that appear in(1,8) the archive later  than  a
              symlink pointing to them.

       -copysymlinks
              This  option allows to copy symlinked targets rather than creat-
              ing a symbolic link.  It helps to extract tar files  on  systems
              that  do  not  implement links (e.g. OS/2).  To extract and copy
              all symlinks correctly, you may need to call star(1,4) twice as  star(1,4)
              cannot  copy  files that appear in(1,8) the archive later than a sym-
              link(1,2) pointing to them.

       -ctime If used with the list command,  this  lists  ctime  rather  than
              mtime  if(3,n) the archive format is star(1,4), xstar, xustar, exustar, or
              pax.  If used with the extract command and the same archive for-
              mats, this tries to restore even the ctime of a file(1,n) by generat-
              ing time(1,2,n) storms.  You should not do this when in(1,8) multi user mode
              because this may confuse programs like cron and the news system.
              If used with the create command this changes the behavior of the
              newer=  option.   Star,  in(1,8)  this case compares the ctime of all
              files to the mtime of the stamp file(1,n) rather then  comparing  the
              mtimes of both files.

       -cumulative
              A shorthand for -dump-cumulative.  See -dump-cumulative for more
              information.

       -D     Do not descend directories.  Normally, star(1,4) descends  the  whole
              tree  if(3,n)  it  encounters  a directory in(1,8) in(1,8) its file(1,n) parameters.
              The option -D is in(1,8) effect by default if(3,n) the list=file(1,n) option is
              used.  If you like star(1,4) to descend directories found in(1,8) the list
              file(1,n), use the -dodesc option (see below).

       -d     Do not store/create directories.  Old versions of  tar  such  as
              published  with the seventh edition of UNIX are not able to deal
              with directories in(1,8) tar archives.  If a tar archive is generated
              without  directories  this  avoids problems with tar implementa-
              tions found on SYSVr3 and earlier.

       -debug Print debug messages. Among other things, this gives debug  mes-
              sages  for  header  type  recognition,  tar type properties, EOF
              recognition, opening of remote archives and fifo internals.

       diffopts=optlst
              Comma separated list of diffopts.  Valid members in(1,8) optlst are:

              help      Print a summary of possible members  of  the  diffopts
                        list.

              !         Invert  the  meaning of the following string. No comma
                        is needed after the exclamation mark.

              not       Invert the meaning of all members in(1,8) the diffopts list
                        i.e.  exclude  all  present  options from an initially
                        complete set(7,n,1 builtins) compare  list.   When  using  csh(1)  you
                        might  have  problems  to  use  !   due to its strange
                        parser.  This is why the not alias exists.

              perm      Compare file(1,n) permissions. With this option in(1,8)  effect,
                        star(1,4)  compares  the  low  order 12 bits of the st_mode
                        field.

              mode      Same as perm.

              type      Compare file(1,n) type.  Note that star(1,4) cannot compare  the
                        file(1,n) type in(1,8) case of a hard link.

              nlink     Compare  link(1,2)  count on hardlinks.  This only works if(3,n)
                        the archive is in(1,8) exustar format and  contains  star(1,4)'s
                        dump extensions.

              uid       Compare numerical user id of file.

              gid       Compare numerical group id of file.

              uname(1,2)     Compare  ASCII  version(1,3,5)  of user id of file.  The user
                        name is mapped via the file(1,n) /etc/passwd.

              gname     Compare ASCII version(1,3,5) of group id of file.  The  group
                        name is mapped via the file(1,n) /etc/group.

              id        Shorthand   for:   uid,gid,uname(1,2),gname.   Compare  all
                        user/group related info(1,5,n) of file.  Note that this  will
                        always  find differences if(3,n) the source and target sys-
                        tem use different user or group mappings.

              size      Compare file(1,n) size.  Note that star(1,4) cannot compare  the
                        file(1,n) size in(1,8) case of a hard link.

              data      Compare  content  of file.  If star(1,4) already found that
                        the size of the files differ, it will not compare  the
                        content  anymore.   If  the  size of the files differ,
                        star(1,4) will always report different data.

              cont      Same as data.

              rdev      Compare major/minor numbers for device nodes.

              hardlink  Compare target of hardlinks.

              symlink   Compare target of symlinks. This evaluates  the  value
                        returned by the readlink(1,2)(2) call.

              sparse    Compare  if(3,n)  either  both  files are sparse or not. If
                        only one of both files is sparse, then a difference is
                        flagged.   This  only works with if(3,n) the archive format
                        is star(1,4), xstar, xustar, exustar, or gnutar.

              atime     Compare access(2,5) time(1,2,n) of file.  This only works with  if(3,n)
                        the archive format is star(1,4), xstar, xustar, exustar, or
                        pax.

              mtime     Compare modification time(1,2,n) of file.

              ctime     This only works with if(3,n) the archive  format  is  star(1,4),
                        xstar, xustar, exustar, or pax.

              lmtime    Compare  the  modification time(1,2,n) of symbolic links.  By
                        default, star(1,4) will not compare the  modification  time(1,2,n)
                        of symbolic links as most systems cannot set(7,n,1 builtins) the modi-
                        fication time(1,2,n) of symbolic links.

              times     Shorthand for: atime,mtime,ctime.

              dir       Compare the content of directories.  This  only  works
                        if(3,n)  the  archive  is  in(1,8)  exustar  format and contains
                        star(1,4)'s dump extensions.  Together with increased  ver-
                        bose  level (-vv) this will print a list of files that
                        are only in(1,8) the archive and a list of files  that  are
                        only on the current filesystem.

              acl       Compare  access(2,5) control lists.  This only works if(3,n) the
                        archive is in(1,8) exustar format and has been created with
                        star(1,4)'s  -acl  option.   You  need  to specify the -acl
                        option in(1,8) addition when running the diff.

              xattr     Compare extended file(1,n) attributes.  This only works  if(3,n)
                        the  archive is in(1,8) exustar format and has been created
                        with star(1,4)'s -xattr option.  You need  to  specify  the
                        -xattr option in(1,8) addition when running the diff.

              fflags    Compare  extended  file(1,n) flags.  This only works if(3,n) the
                        archive is in(1,8) exustar format and has been created with
                        star(1,4)'s  -xfflags  option.   You  need  to  specify the
                        -xfflags option in(1,8) addition when running the diff.

              If optlst starts with a ! the meaning of all members  in(1,8)  optlst
              is  inverted as with the not optlist member.  In this case, star(1,4)
              starts with a complete list  that  includes  atime  and  lmtime.
              Reasonable  diff options to use when comparing against a copy of
              a directory tree are diffopts=!atime,ctime,lmtime.

              If diffopts are not specified, star(1,4) compares everything but  the
              access(2,5)  time(1,2,n)  of the files and the modification time(1,2,n) of symbolic
              links.

       -dirmode
              If in(1,8) create mode (i.e. when storing  files  to  archive),  star(1,4)
              stores directories past the corresponding files. This guarantees
              that even old tar implementations without a directory cache will
              be able to restore the correct times of directories.  The option
              -dirmode should  only  be  used  if(3,n)  the  archive  needs  to  be
              extracted  by  an  old  tar  implementation.  If star(1,4) is used to
              extract an archive that  has  been  created  with  -dirmode  the
              directories  will not get an old time(1,2,n) stamp unless the option -U
              is used while extracting the archive.

       -dodesc
              Force star(1,4) to descend directories found  in(1,8)  a  list=file.   See
              also the -D option above.

       -dump  Allows  to create archives with the same number of attributes as
              an archive that has been created  with  the  level=  option  but
              without the restrictions that apply to a true dump.

              The  resultant  archive  may  be seen as a level-less dump which
              includes similar attributes as a level 0 dump but may span  more
              than  a single file(1,n) system and does not need to use a -C option.
              It has been originally introduced to make it easier to implement
              a  star(1,4)  version(1,3,5) that supports true incremental dumps, but it is
              kept as it gives additional benefits.  Star currently  sets  the
              archive  type  to  exustar  and, in(1,8) addition archives more inode
              meta data inside POSIX.1-2001 extended headers.  See also level=
              option  and the section INCREMENTAL BACKUPS for more information
              on true incremental dumps.

       -dump-cumulative
              instructs star(1,4) to perform incremental dumps  relatively  to  the
              last incremental dump of the same level.  Incremental dumps with
              a level higher than 0 are normally done relatively to  the  con-
              tent  of  a previous dump with lower level. If incremental dumps
              and restores are going to be used to synchronize filesystem con-
              tent, every successive incremental dump will increase in(1,8) size if(3,n)
              -dump-cumulative  is  not  used.   See   section   SYNCHRONIZING
              FILESYSTEMS for more information.


       dumpdate=name
              Tells  star(1,4) to use the mtime of the time(1,2,n) stamp file(1,n) name instead
              of using the start time(1,2,n) of star(1,4).  This is needed  when  star(1,4)  is
              run  on  file(1,n) system snapshots.  If star(1,4) would use the the start
              time(1,2,n) with snapshots, all files that have been  modified  between
              the setup(2,8) of the snapshot and the start of star(1,4) would be missing
              on the backup.

       -dumpmeta
              changes the behavior of  star(1,4)  in(1,8)  incremental  dump  mode.   If
              -dumpmeta is used and only the inode change time(1,2,n) (st_ctime) of a
              file(1,n) has been updated since the last incremental dump, star(1,4) will
              archive  only  the meta data of the file(1,n) (e.g. uid, permissions,
              ...) but not the file(1,n) content.  Using -dumpmeta will  result  in(1,8)
              smaller  incremental  dumps,  but  files  that have been created
              between two incrementals and set(7,n,1 builtins) to  an  old  date  in(1,8)  st_mtime
              (e.g.  as a result from a tar extract) will not be archived with
              full content.  Using -dumpmeta thus  may  result  in(1,8)  incomplete
              incremental dumps, use with extreme care.

       errctl= name
              Use  the  file(1,n) name as error(8,n) control file.  The reason for using
              an error(8,n) control file(1,n) is to make star(1,4) quiet about  error(8,n)  condi-
              tions  that are known to be irrelevant on the quality of the ar-
              chive or restore run. A typical reason to use error(8,n)  control  is
              to  suppress  warnings  about  growing  log  files while doing a
              backup on a life file(1,n) system.

              The error(8,n) control file(1,n) contains a set(7,n,1 builtins) of  lines,  each  starting
              with  a list of error(8,n) conditions to be ignored followed by white
              space followed by a file(1,n) name  pattern  (see  match(1)  or  pat-
              match(3)  for more information).  If the file(1,n) name pattern needs
              to start with white space, use a backslash to escape  the  start
              of the file(1,n) name. It is not possible to have new line characters
              in(1,8) the file(1,n)  name  pattern.   Whenever  an  error(8,n)  situation  is
              encountered,  star(1,4)  checks  the  lines in(1,8) the error(8,n) control file(1,n)
              starting from the top.  If the current error(8,n) condition is listed
              on  a  line  in(1,8) the error(8,n) control file(1,n), then star(1,4) checks whether
              the pattern on the rest of the line  matches  the  current  file(1,n)
              name.   If this is the case, star(1,4) ignores the current error(8,n) con-
              dition.

              The list of error(8,n) conditions to be ignored may use one  or  more
              (in(1,8) this case separated by a '|' character) identifiers from the
              list below:

              STAT        Suppress warnings that  star(1,4)  could  not  stat(1,2)(2)  a
                          file.

              GETACL      Suppress  warnings  about  files  on  which star(1,4) had
                          problems to retrieve the ACL information.

              OPEN        Suppress warnings about  files  that  could  not  be
                          opened.

              READ        Suppress warnings read(2,n,1 builtins) errors on files.

              WRITE       Suppress warnings write(1,2) errors on files.

              READLINK    Suppress  warnings  readlink(1,2)(2)  errors  on symbolic
                          links.

              GROW        Suppress warnings about files that  did  grow  while
                          they have been archived.

              SHRINK      Suppress  warnings about files that did shrink while
                          they have been archived.

              MISSLINK    Suppress warnings about files  for  which  star(1,4)  was
                          unable to archive all hard links.

              NAMETOOLONG Suppress  warnings  about  files  that  could not be
                          archived because the name of the file(1,n)  is  too  long
                          for the archive format.

              FILETOOBIG  Suppress  warnings  about  files  that  could not be
                          archived because the size of the file(1,n) is too big for
                          the archive format.

              SPECIALFILE Suppress  warnings  about  files  that  could not be
                          archived because the file(1,n) type is not  supported  by
                          the archive format.

              GETXATTR    Suppress warnings about files on that star(1,4) could not
                          retrieve the extended file(1,n) attribute information.

              SETTIME     Suppress warnings about files on that star(1,4) could not
                          set(7,n,1 builtins) the time(1,2,n) information during extraction.

              SETMODE     Suppress warnings about files on that star(1,4) could not
                          set(7,n,1 builtins) the access(2,5) modes during extraction.

              SECURITY    Suppress warnings about files that have been skipped
                          on  extraction  because they have been considered to
                          be a security risk.  This currently applies  to  all
                          files  that  have  a '/../' sequence inside when -..
                          has not been specified.

              LSECURITY   Suppress warnings about links that have been skipped
                          on  extraction  because they have been considered to
                          be a security risk.  This currently applies  to  all
                          link(1,2)  names  that  start  with  '/' or have a '/../'
                          sequence inside when -secure-links has  been  speci-
                          fied.   In  this  case, star(1,4) tries to match the link(1,2)
                          name against the pattern in(1,8) the error(8,n) control  file.

              SAMEFILE    Suppress warnings about links that have been skipped
                          on extraction because source and target of the  link(1,2)
                          are  pointing  to  the same file.  If star(1,4) would not
                          skip these files, it would end up with removing  the
                          file(1,n)  completely.  In this case, star(1,4) tries to match
                          the link(1,2) name against the pattern in(1,8) the error(8,n)  con-
                          trol file.

              BADACL      Suppress  warnings  access(2,5)  control  list conversion
                          problems.

              SETACL      Suppress warnings about files on that star(1,4) could not
                          set(7,n,1 builtins) the ACL information during extraction.

              SETXATTR    Suppress warnings about files on that star(1,4) could not
                          set(7,n,1 builtins) the extended file(1,n) attribute  information  during
                          extraction.

       If  a  specific error(8,n) condition is ignored, then the error(8,n) condition is
       not only handled in(1,8) a silent way but also excluded from the error(8,n)  sta-
       tistics that are printed at the end of the star(1,4) run.

       Be  very  careful  when using error(8,n) control as you may ignore any error(8,n)
       condition.  If you ignore the wrong error(8,n) conditions, you  may  not  be
       able to see real problems anymore.

       -F,-FF ...
              Fast  and  simple  exclude  option for create mode.  With one -F
              argument, star(1,4) ignores all  directories  called  SCCS  and  RCS.
              With two -F arguments, star(1,4) in(1,8) addition ignores all files called
              core errs a.out all files ending with .o.  OBJ/.  With three  -F
              arguments,  star(1,4) ignores all sub trees starting from a directory
              that includes a file(1,n) .mirror or .exclude and  all  object  files
              and files called core errs a.out all files ending with .o.  With
              four -F arguments, star(1,4) ignores all sub trees  starting  from  a
              directory  that  includes  a file(1,n) .mirror or .exclude the latter
              files are excluded too as well as and all object files and files
              called  core  errs a.out all files ending with .o.  With five -F
              arguments, star(1,4)  in(1,8)  addition  again  excludes  all  directories
              called SCCS and RCS.

       -fifo  Use  a  fifo to optimize data flow from/to tarfile.  This option
              is in(1,8) effect by default (it may be  changed  at  compile  time(1,2,n)).
              The  default fifo size is 8 MBytes on all platforms except Linux
              versions that do not support mmap() (4 MB because kernels before
              2.4  did  not handle big shared memory areas) and Sun/mc68000 (1
              MB).  This will star(1,4) make even work on a tiny machine like a Sun
              3/50.  The fifo size may be modified with the fs= option. A rule
              of dumb for the fifo size is to use more than the buffer size of
              the  tape  drive  and  less(1,3)  then half of the real memory of the
              machine.  A good choice would be to use a fifo  size  between  8
              and 256 MB.  This may increase backup speed up to 5% compared to
              the speed achieved with the default fifo size. Note that with  a
              DLT drive that gives 12MB/s transfer rate, a fifo of 256 MB size
              will keep the tape at least streaming in(1,8) units(1,7)  of  20  seconds.
              All  options  that  start  with the -f sequence are sensitive to
              typo problems, see BUGS section for more information.

       -fifostats
              Print fifo statistics at the end of a star(1,4) run when the fifo has
              been in(1,8) effect.  All options that start with the -f sequence are
              sensitive to typo problems, see BUGS section for  more  informa-
              tion.

       file(1,n)=tarfilename, f=tarfilename
              Use tarfilename as the name for the tar archive. Currently up to
              100 file(1,n)= options are possible. Specifying more then  one  file(1,n)=
              option  make  sense in(1,8) multi volume mode. In this case star(1,4) will
              use the next name in(1,8) the list  every  time(1,2,n)  a  media  change  is
              needed.   To  make  star(1,4)  behave consistent with the single file(1,n)
              case, star(1,4) loops over the list of  known  archive  files.   Note
              that  if(3,n)  star(1,4) is installed suid root and the first tarfile is a
              remote archive, only the connection to this archive will be cre-
              ated  with  root  privileges.   After  this  connection has been
              established as root, star(1,4) switches back to the id of the caller.
              If any of the other archives in(1,8) the list is located on a differ-
              ent host(1,5), star(1,4) will not be able to open(2,3,n) this archive  later  on,
              unless run by root.

              Star  normally uses stdin/stdout for the tar archive because the
              most common way to use star(1,4) is in(1,8) conjunction  with  pipes.   If
              star(1,4)  is  installed  suid root or if(3,n) it has been called by root,
              tarfilename may be in(1,8) remote syntax:  user@host:filename  as  in(1,8)
              rcp(1)  even  if(3,n)  invoked by non root users.  See SUID NOTES for
              more information.

              To make a file(1,n) local although it includes a colon (:), the file-
              name must start with: '/', './' or '../'

              Note  that  if(3,n)  star(1,4) talks to an old rmt remote tape server that
              does not support symbolic open(2,3,n) modes, it does not open(2,3,n) a  remote
              tape  with the O_CREAT open(2,3,n) flag because this would be extremely
              dangerous.  If the rmt server on  the  other  side  is  the  rmt
              server  that comes with star(1,4) or the GNU rmt server, star(1,4) may use
              the symbolic mode for the open(2,3,n) flags.  Only  the  symbolic  open(2,3,n)
              modes allow to send(2,n) all possible open(2,3,n) modes in(1,8) a portable way to
              remote tape servers.

              It is recommended to use the rmt server that  comes  with  star(1,4).
              It  is  the only rmt server that gives platform independent com-
              patibility with BSD, Sun and GNU rmt  clients  and  it  includes
              security  features  that may be set(7,n,1 builtins) up in(1,8) /etc/default/rmt.  All
              options that start with the -f sequence are  sensitive  to  typo
              problems, see BUGS section for more information.

              See  ENVIRONMENT section for information on how to use ssh(1) to
              create a remote tape server connection.

       -force_hole
              obsoleted by -force-hole

       -force-hole
              Try to extract all files with holes. This even works with  files
              that are created without the -sparse option.  Star, in(1,8) this case
              examines the content of the files in(1,8) the  archive  and  replaces
              writes to parts containing binary zeroes with seeks. This option
              should be used with extreme care because you  sometimes  get  in(1,8)
              trouble when files get unattended holes.  All options that start
              with the -f sequence are sensitive to typo  problems,  see  BUGS
              section for more information.

       -force_remove
              obsoleted by -force-remove

       -force-remove
              Force  to  remove non writable files on extraction.  By default,
              star(1,4) will not overwrite files  that  are  read(2,n,1 builtins)  only.   If  this
              option  is  in(1,8)  effect, star(1,4) will silently remove these files to
              allow the extraction of a file.  All options that start with the
              -f sequence are sensitive to typo problems, see BUGS section for
              more information.

       -force-restore
              Force an incremental restore even if(3,n)  the  incremental  dump  is
              only  a  partial dump. See -wtardumps, level= and section INCRE-
              MENTAL BACKUPS for more information.

       fs=#   Set fifo size to #.  See  bs=  for  the  possible  syntax.   The
              default  size  of  the fifo is 1 Mbyte on Sun mc68000 systems, 4
              Mbytes on non mmap() aware Linux systems and  8  Mbytes  on  all
              other  systems.   See  -fifo option for hints on using the right
              fifo size.


       fs-name=mount_point
              Use mount_point when recording information in(1,8) /etc/tardumps  and
              when  comparing  against information in(1,8) /etc/tardumps for incre-
              mental backups.  This makes sense when backups  are  made  using
              file(1,n)  system  snapshots and allows /etc/tardumps and the archive
              to contain the real name of the file(1,n) system instead of the  tem-
              porary mount(2,8) point that is used for the snapshot device.


       H=headertype
              See artype=headertype option.  Note that POSIX.1-2001 defines an
              option -H that follows symbolic links that have been encountered
              on  the  command  line.   For  this  reason, the old star(1,4) option
              H=headertype option may go away in(1,8) the future even  though  this
              option has been in(1,8) use by cpio since 1989.

       -h, -L Follow symbolic links as if(3,n) they were files.  Normally star(1,4) will
              not follow symbolic links but stores their  values  in(1,8)  tarfile.
              See also the -L option.

       -hardlinks
              In  extract  mode,  this  option  tells  star(1,4) to try to create a
              hardlink whenever a symlink is encountered in(1,8) the  archive.   In
              create mode, this option tells star(1,4) to try to archive a hardlink
              whenever a symlink is encountered in(1,8) the file(1,n) system.

       -hpdev Allow 24 bits for the minor device number using 8 octal  digits.
              Note  that although it allows to create tar archives that can be
              read(2,n,1 builtins) with HP-UX tar, this creates  tar  archives  which  violate
              POSIX.1-1988.   This  option is only needed if(3,n) you like to use a
              POSIX.1-1988 based archive format that does not  include  exten-
              sions.   If  you  use the xstar format, star(1,4) will use a base 256
              extension that allows bigger major/minor numbers by default,  if(3,n)
              you  use the xustar or the exustar format there is no limitation
              at all as these formats use POSIX.1-2001 extended headers to ar-
              chive the major/minor numbers by default.

       -i     Ignore checksum errors on tar headers.  If this option is speci-
              fied, star(1,4) will not exit(3,n,1 builtins) if(3,n) a header  with  a  bad  checksum  is
              found but search for the next valid header.

       -j     run  the input or output through a bzip2 pipe(2,8) - see option -z -Z
              and -bz below.  As the -bz the -j the -Z and the -z  option  are
              non  standard,  it makes sense to omit the -bz the -j the -Z and
              the -z options inside shell scripts if(3,n) you are going to  extract
              a compressed archive that is located inside a plain file(1,n) as star(1,4)
              will auto(5,8) detect compression and choose the right  decompression
              option to extract.

       -keep_old_files
              obsoleted by -keep-old-files

       -keep-old-files, -k
              Keep  existing  files  rather  than restoring them from tarfile.
              This saves files from being clobbered even if(3,n) tarfile contains a
              more recent version(1,3,5) of the corresponding file.

              See SECURITY NOTES for more information.

       -L, -h Follow symbolic links as if(3,n) they were files.  Normally star(1,4) will
              not follow symbolic links but stores their  values  in(1,8)  tarfile.
              See also the -h option.

       -l     Do  not  print a warning message if(3,n) not all links to hard linked
              files could be dumped. This option is evaluated in(1,8) the  opposite
              way  to historic tar(1) implementations and to POSIX.1.  POSIX.1
              requests that by default no warning messages will be printed and
              -l  will  enable  warning  messages  when not all links could be
              archived.

       level=dumplevel
              Set level for incremental dumps.  This option is used to  switch(1,n)
              star(1,4) into true incremental dump mode.

              In  true incremental dump mode, a -C option which is followed by
              the name a mount(2,8) point and a dot  ('.')  as  starting  directory
              name is required.  Only a single file(1,n) system may be handled at a
              time.  If the directory followed by the -C option is not  refer-
              ring  to a root directory of a file(1,n) system, the dump is called a
              partial dump.  If the directory followed by  the  -C  option  is
              referring  to  a  root  directory  of a file(1,n) system and no other
              restrictions apply that exclude certain files from the dump, the
              dump is called a full dump.

              By  default, the tardumps database is not written.  See also the
              tardumps=name and -wtardumps options and the section INCREMENTAL
              BACKUPS for more information.

       -link-dirs
              When in(1,8) create mode, try to find hard linked directories.  Using
              -link-dirs will force star(1,4) to keep track of all directories that
              will go into the archive and thus causes a lot more memory to be
              allocated than in(1,8) the default case.

              If you like to extract a cpio archive that contains hard  linked
              directories,  you  also need to specify -link-dirs in(1,8) extract or
              diff mode.  This is needed  because  many  cpio  implementations
              create buggy archives with respect to hard links.  If star(1,4) would
              look(1,8,3 Search::Dict) for hard linked directories in(1,8) all cases, it  would  detect
              many pseudo hard links to directories.  Use -link-dirs with care
              if(3,n) you extract cpio archives.

              Note that not all filesystem  allow  to  create  hard  links  to
              directories.  Also note that even though a non-root user is able
              detect and archive hard linked directories, all known  operating
              systems require the extraction to be done as root in(1,8) order to be
              able to create or remove hard links to  directories.   For  this
              reason  its only recommended to use this option when doing accu-
              rate backups and when hard links to directories are expected.

              When the option -link-dirs is not used and hard links to  direc-
              tories are present, the appendant sub-tree will appear more than
              once on the archive and star(1,4) will  print  Linkcount  below  zero
              warnings for non directory hard links inside the sub-tree.

       list=filename
              Read filenames for store/create/list command from filename.  The
              file(1,n) filename must contain a list of filenames, each on a  sepa-
              rate line.  This option implies the -D option.  To force star(1,4) to
              descend directories, use the -dodesc option in(1,8) this case.

       -lowmem
              Try to run with reduced memory requirements.  This  causes  star(1,4)
              to default to 1 MB of FIFO memory.  Instead of allocating memory
              to hold the directory content and reading the directory at once,
              star(1,4)  reads  the  directory name by name. This may cause star(1,4) to
              close(2,7,n) the directory if(3,n) it rans out of file(1,n)  descriptors  because
              of  deeply nested directories. If a directory then does not sup-
              port telldir(3)/seekdir(3), star(1,4) will fail.

       -M, -xdev
              Do not descend mount(2,8) points.  This is useful when doing  backups
              of complete file(1,n) systems.  See NOTES for more information.

       -m     Do  not  restore  access(2,5) and modification time.  (Access time(1,2,n) is
              only available if(3,n) star(1,4) is reading star(1,4), xstar, xustar,  exustar,
              or  pax  archives). If star(1,4) extracts other archive types, the -m
              flag only refers to the modification time.


       -match-tree
              If in(1,8) create mode a pattern does  not  match  a  directory,  and
              -match-tree  has  been  specified,  the  whole directory tree is
              excluded from the archive and from further directory scans.   By
              default, star(1,4) excludes the directory but still recursively scans
              the content of this directory as complex  patterns  could  allow
              files  inside  the  directory  tree to match.  Using -match-tree
              allows to efficiently exclude whole trees  from  scanning.  This
              helps to avoid scannings directory trees that are on remote file(1,n)
              systems or contain excessive bad blocks.

       maxsize=#
              Do not store files in(1,8) tarfile if(3,n) they are bigger  than  #.   See
              bs=  for  the possible syntax.  By default, the number is multi-
              plied by 1024, so the value counts in(1,8) units(1,7) of kBytes.   If  the
              size  specifier  ends with a valid multiplication character (e.g
              '.' for bytes or 'M' for MB) the specified size is used as spec-
              ified and not multiplied by 1024.  See bs= option for all possi-
              ble multipliers.

       -meta  In create mode, -meta causes star(1,4) to archive all  meta  data  of
              the  file(1,n) (e.g. uid, permissions, ...) but not the file(1,n) content.
              In extract mode, it causes star(1,4) to restore all meta data but not
              the  file(1,n)  content.  In addition, in(1,8) extract mode no plain file(1,n),
              special file(1,n) or directory  will  be  created.   Meta  files  are
              needed to support incremental backups.

              Warning:  Do  not  try  to extract star(1,4) archives containing meta
              files using other tar implementations if(3,n) they are not  aware  of
              the  meta  file(1,n) extensions of star(1,4).  Star tries to force all tar
              implementations that are not standard compliant to abort.   Star
              also  tries to make all non POSIX.1-2001 compliant tar implemen-
              tations unable to find a  valid  filename.  However  when  other
              POSIX.1-2001  aware  tar  implementations come up and don't know
              about meta files, they will destroy files on disk.

              The problems result from the only current fallback in(1,8) the  POSIX
              standard  that  tells  tar  implementations to treat all unknown
              file(1,n) types as if(3,n) they were plain files. As meta files are needed
              for  incremental  backups, I am looking for people and companies
              who like to support me to be able to add the meta  file(1,n)  concept
              to the POSIX.1-2005 standard.

       -modebits
              This options allows you to create tar archives that include more
              than 12 bits from st_mode. Note this create  tar  archives  that
              violate  POSIX  but  some  tar implementations insist in(1,8) reading
              such nonstandard archives.

       -multivol
              Switch to multi volume mode.  In multi volume mode,  there  will
              be no logical EOF marker written to the end of a single tape. If
              -multivol is used in(1,8) read(2,n,1 builtins) mode, a hard EOF on input (if(3,n) not pre-
              ceded by a logical EOF) triggers a medium change operation.

              Specifying -multivol tells star(1,4) to split(1,n) files across volumes if(3,n)
              needed.  This way, a virtual(5,8) archive is created that spans  more
              than one medium.  Multi volume mode is needed whenever it is not
              possible to split(1,n) the archiving or extracting into several logi-
              cally  independent  tasks.  This  is  true  for e.g. incremental
              dump/restore operations where inode numbers need  to  be  traced
              for the whole task.

              When tsize=# has been specified, but star(1,4) is not in(1,8) multi volume
              mode, files cannot be split(1,n) across volumes.

              When -multivol has been specified in(1,8) create mode  together  with
              tsize=# then a media change is initiated exactly after an amount
              of tsize data has been written.  When -multivol has been  speci-
              fied in(1,8) create mode and tsize=# has not been specified, then the
              medium change is triggered by a EOT condition from  writing  the
              medium.  This allows to use media where the size cannot be known
              in(1,8) advance (e.g. tapes with build in(1,8) compression); it  does  not
              work  if(3,n)  the  EOT  condition  is  not returned in(1,8) sync(1,2,8) with the
              related write(1,2) operation. For this reason, it  is  expected  that
              data buffering inside a device driver cannot be used.

              Depending  on  the selected archive format, star(1,4) writes a volume
              header at the beginning of a  new  medium.  This  medium  header
              allows  to  verify(1,8) the correct volume after a change during read(2,n,1 builtins)
              back.  It is recommended to use  the  exustar  format  for  best
              results.   In  create  mode, -multivol is only supported for ar-
              chives types that allow to write(1,2) reliable  multi  volume  header
              information.

              See tsize=# option for more information.

       newer=filename
              Do  not store files to tarfile if(3,n) their modification time(1,2,n) is not
              newer than the modification time(1,2,n) of filename.  See -ctime option
              for changing this behavior.

       -newest
              In  conjunction  with  the  list command this lists you only the
              newest file(1,n) in(1,8) tarfile.

       -newest_file
              obsoleted by -newest-file

       -newest-file
              In conjunction with the list command this  lists  you  only  the
              newest regular file(1,n) in(1,8) tarfile.

       new-volume-script=script
              Call  script  at  end  of each tape if(3,n) in(1,8) multi volume mode.  If
              this option is not in(1,8) effect, star(1,4) will ask the user to  confirm
              the  volume  change.   The script is called with two parameters.
              The first parameter is the next volume  number  and  the  second
              parameter is the next archive file(1,n) name.

       -nodump
              If  this  option  is set(7,n,1 builtins), star(1,4) will not dump files that have the
              nodump flag set. Note that this currently only works on  BSD-4.4
              derivates  and on Linux.  On Linux, using this option will cause
              a performance degradation (the system  time(1,2,n)  increases  by  10%)
              because of the unlucky kernel interface.

       -no-dirslash
              Do  not  add a slash to the end of directory names if(3,n) writing to
              an archive.  Historic tar archive  formats  did  only  allow  to
              specify  plain  files  and hard links.  Around 1980, BSD added a
              feature to specify a directory on tape by adding a slash to  the
              end of the name. POSIX.1-1988 defined the first official tar ar-
              chive format that had a clean method to specify the  type  of  a
              directory.   As  old  tar  formats need the slash to recognize a
              directory, -no-dirslash may not be used if(3,n)  archives  should  be
              compatible with the old tar format.

       -no_fifo
              obsoleted by -no-fifo

       -no-fifo
              Don't  use  a  fifo to optimize data flow from/to tarfile.  Cur-
              rently the -fifo option is used as default. (This may be changed
              at compile time.)

       -no-fsync
              Do  not call fsync(2) for each file(1,n) that has been extracted from
              the archive.  Using -no-fsync may speed up extraction on operat-
              ing systems with slow file(1,n) I/O (such as Linux), but includes the
              risk that star(1,4) may not be able  to  detect  extraction  problems
              that occur after the call to close(2,7,n)(2).  A typical cause for such
              problems is a NFS file(1,n) system that fills up  before  the  buffer
              cache  is  synced  or a write(1,2) error(8,n) that occurs while the buffer
              cache is synced.  There may be other reasons.  Use with  extreme
              care.

       -nochown, -o
              Do  not  restore  owner and group of files.  This may be used if(3,n)
              super user privileges are needed to overwrite existing files but
              the local ownership of the existing files should not change.

       -no-p  Do  not  restore files and directories to their original permis-
              sions.  This option is needed only if(3,n)  star(1,4)  is  called  by  the
              super  user  and the permissions should not be restored from the
              archive.  See also the -p option. The -p options  has  a  higher
              precedence than the -no-p option.

       -no_statistics
              obsoleted by -no-statistics

       -no-statistics
              Do not print statistic messages at the end of a star(1,4) run.

       -no-xheader
              Do  not  create  or extract POSIX.1-2001 extended headers.  This
              option may be used if(3,n) you like to read(2,n,1 builtins) an  archive  with  broken
              extended headers.

       -not, -V
              Invert  the  meaning  of  the pattern list. i.e. use those files
              which do not match any of the pattern.  Note  that  this  option
              only  applies  to patterns that have been specified via the pat-
              tern=pattern or pat=pattern option. Patterns specified  as  file(1,n)
              type arguments will not be affected.

       -notarg, -pax-c
              Match  all file(1,n) or archive members except those specified by the
              pattern or file(1,n) operands.

       -nowarn
              Do not print warning messages.  This sometimes is useful to make
              the  output  more readable (e.g. when hundreds of files that are
              going to be extracted are not newer in(1,8) the archive then  on  the
              filesystem).

       -numeric
              Use the numeric user/group fields in(1,8) the listing rather than the
              default.  The default  allows  to  list  the  ASCII  version(1,3,5)  of
              user/group  of  the  file(1,n) and to extract the owners of the files
              based on numeric values rather than the names.  In create  mode,
              no  user/groups  names  are  put  on  the archive.  The -numeric
              option also applies when  ACLs  are  going  to  be  archived  or
              extracted.

       -O     Be  compatible  to old versions of tar.  If star(1,4) is invoked with
              this option, star(1,4) generates archives which are fully  compatible
              with old UNIX tar archives. If in(1,8) extract mode, star(1,4) ignores any
              additional info(1,5,n) in(1,8) the headers.  This implies neither  that  ar-
              chives generated with this option are binary equal with archives
              generated by old tar versions nor that star(1,4) is trying to compre-
              hend  all  bugs  that are found in(1,8) old tar versions.  The bug in(1,8)
              old tar versions that cause a reversal of a  space  and  a  NULL
              byte in(1,8) the checksum field is not repeated.  If you want to have
              signed checksums you have to specify the -singed-checksum option
              too.   If you want directories not to be archived in(1,8) order to be
              compatible to very old historic tar archives, you need to  spec-
              ify the -d option too.

              This option is superseeded by the H=headertype option.

       -o, -nochown
              Do  not  restore  owner and group of files.  This may be used if(3,n)
              super user privileges are needed to overwrite existing files but
              the local ownership of the existing files should not change.

       -onull, -nullout
              Do  not  actually  write(1,2)  to the archive but compute and add the
              sizes.  This is useful when trying to figure out if(3,n) a  tape  may
              hold  the  current backup.  Please only use the -onull option as
              it is a similar option as used by the sdd(1) command.

       -P     Allow star(1,4) to write(1,2) a partial record as the last  record.   Nor-
              mally,  star(1,4) writes each record with the same size.  This option
              is useful on unblocked tapes i.e. cartridge tapes like QIC tapes
              as  well as with archives that are located in(1,8) files.  If you use
              this option on local files, the size  of  the  archive  will  be
              smaller.   If  you  use this option on cartridge tapes, is makes
              sure that later - in(1,8) extract mode - star(1,4) will read(2,n,1 builtins) up to the end
              of  file(1,n)  marker on the tape and the next call to star(1,4) will read(2,n,1 builtins)
              from the next archive on the same tape.

       -p     Restore files and directories  to  their  original  permissions.
              Without  this  option, they are created using the permissions in(1,8)
              the archive and the present umask(2).  If star(1,4) is called by  the
              super  user,  star(1,4)  behaves as if(3,n) it has been called with the -p
              option. See also -no-p option.  If the archive  contains  Access
              Control Lists (ACLs) in(1,8) POSIX.1-2001 extended headers, star(1,4) will
              restore the access(2,5) control lists from the archive for  files  if(3,n)
              the  -acl  option is specified.  If the option -acl has not been
              specified, ACLs are not restored at all.

       pattern=pattern, pat=pattern
              Set matching pattern to pattern.  A maximum of  100  pattern=pat
              options  may  be  specified.   As  each  pattern is unlimited in(1,8)
              length, this is no real limitation.  If more than one pattern is
              specified,  a  file(1,n)  matches  if(3,n)  any  of  the specified pattern
              matches.  Patterns may be used  in(1,8)  create  mode  to  select(2,7,2 select_tut)  or
              exclude  files from the list of file(1,n) type arguments or the files
              located in(1,8) a sub tree of a file(1,n)  type  argument  directory.   By
              default, star(1,4) scans the whole directory tree underneath a direc-
              tory that is in(1,8) the argument list. This may be modified by using
              the  -match-tree option.  In extract or list mode, all file(1,n) type
              arguments are interpreted to be select(2,7,2 select_tut) pattern  and  all  option
              type patterns may be either select(2,7,2 select_tut) or exclude patterns depending
              on the presence or absence of the -not option.  If you use  file(1,n)
              type  select(2,7,2 select_tut) patterns, they work exactly like the method used by
              other (non pattern aware)  tar(1)  implementations.   File  type
              select(2,7,2 select_tut)  patterns  do  not  offer  pattern  matching but allow to
              restore subtrees.  To extract  a  complete  sub  tree  from  the
              directory  dir with star(1,4) using the pattern= option, use pattern=
              dir/\* if(3,n) you like to select(2,7,2 select_tut) a subtree  by  using  the  historic
              method,  use  dir/  as  file(1,n) type argument.  See manual page for
              match(1) for more details of the pattern matcher.  All  patterns
              are  selection  patterns  by  default. To make them exclude pat-
              terns, use the -not or the -V option.

       pkglist=file(1,n)
              This is (for now) an internal interface for  the  Schily  Source
              Package  System (sps).  It only works in(1,8) create mode and behaves
              similar to the list= option, but it allows to overwrite the per-
              missions,  the  uid  and  gid  values  from  the  content of the
              pkglist= file.  Each line from the pkglist= file(1,n) contains a file(1,n)
              name  followed  by the permission, a user name and a group name.
              The permission is an octal character string.  Each value that is
              not  used  to overwrite the original values may be replaced by a
              '?'.  The fields are separated by spaces, so the pkglist= option
              does not allow files that contain newline or space characters.

       -pax-c, -notarg
              Match  all file(1,n) or archive members except those specified by the
              pattern or file(1,n) operands.

       -pax-H Follow symbolic links that have been encountered on the  command
              line.   If the referenced file(1,n) does not exist, the file(1,n) informa-
              tion and type will be for the link(1,2) itself.  If the link(1,2) is  ref-
              erencing  a  file(1,n)  type that cannot be archived with the current
              archive format, the file(1,n) information and type will  be  for  the
              link(1,2) itself.

       -pax-i Do interactive renaming in(1,8) a way that has been defined for POSIX
              pax.  Star will print the original filename  and  prompt  for  a
              reply.   If  you type just RETURN, than the file(1,n) is skipped.  If
              you type '.', then the original file(1,n) name is retained.   If  you
              type anything else, then this is taken as the new file(1,n) name.

       -pax-L Follow  symbolic  links.  If the referenced file(1,n) does not exist,
              the file(1,n) information and type will be for the link(1,2)  itself.   If
              the link(1,2) is referencing a file(1,n) type that cannot be archived with
              the current archive format, the file(1,n) information and  type  will
              be for the link(1,2) itself.

       -pax-ls
              Switch  listing  format  to the format defined for POSIX pax and
              ls.

       -pax-match
              Allow file(1,n) type arguments to be recognised  as  regular  expres-
              sions in(1,8) a way that has been defined for POSIX pax.

       -pax-n Allow  each  pattern to match only once.  If a pattern matches a
              directors, then the whole sub tree matches the pattern.

       -pax-p string(3,n)
              PAX style privileges string.  Several characters (each has  it's
              own meaning). The following characters are defined:

              a      Do  not  preserve file(1,n) access(2,5) times.  This option is cur-
                     rently ignored.

              e      Preserve the user ID, group ID, file(1,n) mode bits.  This  is
                     equivalent to calling star(1,4) -p -acl -xfflags.

              m      Do  not  preserve  file(1,n) modification times.  This is cur-
                     rently equivalent to calling star(1,4) -m.

              o      Preserve the user ID and group ID.  This is  the  default
                     for star(1,4) if(3,n) called as root.

              p      Preserve the file(1,n) mode bits.  This is equivalent to call-
                     ing star(1,4) -p.

       -prinodes
              Print inode numbers in(1,8) verbose list mode if(3,n) the archive contains
              inode nubers.

       -print-artype
              Check the type of the archive, print the archive and compression
              type on a single line and exit.

       -qic24 Set tape volume size to 61440 kBytes.  See  tsize=#  option  for
              more information.

       -qic120
              Set  tape  volume size to 128000 kBytes.  See tsize=# option for
              more information.

       -qic150
              Set tape volume size to 153600 kBytes.  See tsize=#  option  for
              more information.

       -qic250
              Set  tape  volume size to 256000 kBytes.  See tsize=# option for
              more information.

       -qic525
              Set tape volume size to 512500 kBytes.  See tsize=#  option  for
              more information.

       -read0 Read null terminated file(1,n) names from the file(1,n) specified with the
              list= option.

       -refresh_old_files
              obsoleted by -refresh-old-files

       -refresh-old-files

       -refresh
              Do not create new files. Only  already  existing  files  may  be
              overwritten from tarfile if(3,n) either newer versions are present in(1,8)
              the archive or if(3,n) the -U flag is used.  This allows to overwrite
              files  by  more  recent files from an archive that contains more
              files than the target  directory  should  contain.   The  option
              -refresh-old-files is the same as the -refresh option.

       -remove_first
              obsoleted by -remove-first

       -remove-first
              Remove  files  before  extraction.  If this option is in(1,8) effect,
              star(1,4) will remove files before extracting a  file(1,n)  from  the  ar-
              chive.  This is needed if(3,n) you want to change the file(1,n) type or if(3,n)
              you need to break a  hard  link.   If  you  do  not  use  either
              -ask-remove  or  -force-remove together with -remove-first, this
              option is useless and no files will be removed.

       -remove_recursive
              obsoleted by -remove-recursive

       -remove-recursive
              Remove files recursive.  If removing of  a  file(1,n)  is  permitted,
              star(1,4) will only remove files, specials and empty directories.  If
              this option is in(1,8) effect, star(1,4) will be  allowed  to  recursively
              removes non empty directories too.

       -restore
              switches  star(1,4)  into true incremental retore mode.  A file(1,n) named(5,8)
              star-symtable and a directory named(5,8) star-tmpdir  is  created  in(1,8)
              the root directory of the file(1,n) system where the extraction takes
              place.  If -restore has been specified, star(1,4) behaves as if(3,n) -xdot
              has  been  specified  too.   See  also level= option and section
              INCREMENTAL BACKUPS for more information.

       -S     Do not store/create special files.  A special files is any  file(1,n)
              except plain files, symbolic links and directories.  You need to
              be super user to extract special files.

       -s replstr
              Modify file(1,n) or archive member names named(5,8) by a pattern according
              to  the  substitution expression replstr.  The format of replstr
              is:

                   -s /old/new/[gp]

              The old pattern may use regular expressions and the  new  string(3,n)
              may contain the special character '&'. The character '&' is sub-
              stituted by the  string(3,n)  that  matches  the  old  pattern.   The
              optional  trailing  'g' means global substitution. If 'g' is not
              used, a substitution pattern is only used once on  a  name.   If
              the  optional  trailing 'p' is used, the substitution is printed
              to standard error.

              Up to 100 substitute options may be used. If more than one  sub-
              stitute  option has been specified, star(1,4) will loop over all sub-
              stitute patterns until one matches.

              If the name  substitutes  to  the  empty  string(3,n),  the  file(1,n)  is
              skipped.

       -secure-links
              Do  not  extract  hard  links or symbolic links if(3,n) the link(1,2) name
              (the target of the link(1,2)) starts with a slash (/) or if(3,n)  /../  is
              contained  in(1,8) the link(1,2) name.  Tar archives containing such links
              could be used to compromise the system.  If  they  are  unpacked
              together  with  a  lot  of  other  files,  this  may not even be
              noticed.

              As  the  usability  of  a  tar  archiver  would  be  limited  if(3,n)
              -secure-links checking would be done by default, star(1,4) makes link(1,2)
              checking optional.

              If you unpacked a tar archive using the  -secure-links  and  did
              not get a security warning at the end of the star(1,4) run, all files
              and links have been extracted.  If you get a warning, you should
              unpack  the archive a second time(1,2,n) and specify the options -k, -w
              and -nowarn in(1,8) addition to the options used for the  first  run.
              See SECURITY NOTES for more information.

       -shm   Use  System V shared memory for fifo.  Normally star(1,4) is compiled
              to use mapped /dev/zero pages for the  fifo,  if(3,n)  the  operating
              system supports this.  If star(1,4) is compiled to have both code for
              mapped pages and for System  V  shared  memory,  star(1,4)  will  use
              shared memory instead of the default.  If the -help menu(3x,n,n tk_menuSetFocus) doesn't
              show the -shm flag you have no  choice.   When  using  System  V
              shared memory, you may have to raise(3,n) the system's internal limit
              for shared memory resources to  get  enough  shared  memory  for
              star(1,4).

       -signed_checksum
              obsoleted by -signed-checksum

       -signed-checksum
              Use  signed  chars to calculate checksums. This violates the tar
              specs but old versions of tar derived from the  seventh  edition
              of  UNIX  are implemented in(1,8) this way.  Note: Only filenames and
              linknames containing chars with the most significant bit set(7,n,1 builtins) may
              trigger this problem because all other fields only contain 7 bit
              ASCII characters, octal digits or binary zeroes.

       -silent
              Suppress informational messages like foobar is sparse.

       -sparse
              Handle files with holes effectively on store/create.  Note  that
              sparse  files may not be archived this way if(3,n) the archive format
              is tar, ustar, pax, or suntar.  On Solaris-2.3 ... Solaris-2.5.1
              there is a special ioctl() called _FIOAI that allows root to get
              the allocation info(1,5,n) more efficiently.  Other  operating  systems
              lack  support  to get the real allocation list and force star(1,4) to
              scan the files to look(1,8,3 Search::Dict) for blocks that only contain null charac-
              ters.  This may star(1,4) to assume more holes to be present than the
              number that the file(1,n) really contains.

       -symlinks
              This option tells star(1,4) in(1,8) extract mode to try to create  a  sym-
              link(1,2) whenever a hardlink is encountered in(1,8) the archive.

       -T     If  the  option  file(1,n)=  or  f=  is  omitted and the -T option is
              present, star(1,4) will use the device indicated by the TAPE environ-
              ment variable, if(3,n) set.

       tardumps=name
              Set  the  file(1,n)  name  for  tar dump dates database to name.  The
              default name is /etc/tardumps.   Use  in(1,8)  combination  with  the
              level= option to create true incremental dumps.  See also -wtar-
              dumps option and section INCREMENTAL BACKUPS for  more  informa-
              tion.

       -time  Print timing info.  See DIAGNOSTICS for more information.

       -to_stdout
              obsoleted by -to-stdout

       -to-stdout
              Extract  files  to  stdout.  This  option may be used to extract
              tarfiles containing tarfiles (see examples below).

       -tpath Use this option together with the -t option or with -cv (verbose
              create)  to get only a list of the pathnames of the files in(1,8) the
              archive.  This may be used in(1,8) shell scripts to generate  a  name
              list.   If  used  together with the -diff option, star(1,4) will only
              print the names of the files that differ.  A second run of  star(1,4)
              may  then  be  used to restore all files that had differences to
              the archive.  Use the list= option to specify  the  namelist  in(1,8)
              this case.

       tsize=#
              Set  tape  volume size to # to enable multi volume tape support.
              See bs= for the possible syntax.  By default, the number is mul-
              tiplied by 512, so the value counts in(1,8) units(1,7) of 512 byte blocks.
              If the size specifier ends with a valid multiplication character
              (e.g  '.' for bytes or 'M' for MB) the specified size is used as
              specified and not  multiplied  by  512.   With  this  option  in(1,8)
              effect, star(1,4) is able to archive filesystems that are bigger then
              the tape size.  If the option tsize=# without -multivol then  no
              file(1,n)  will be split(1,n) across volumes and each volume may in(1,8) theory
              be read(2,n,1 builtins) back separately.  Files that do not fit on a single tape
              may not be stored in(1,8) this mode.  If -multivol has been specified
              in(1,8) addition, star(1,4) will split(1,n) files when the maximum allowed tape
              size  has been reached.  If the tape volume size is not a multi-
              ple of the tape block size, the tape  volume  size  is  silently
              rounded  down  to  a  value that is a multiple of the tape block
              size.

              See -multivol option for more information.

       -U     Restore files unconditionally.  By default, an older  file(1,n)  from
              the archive will not replace a corresponding newer file(1,n) on disk.

       -v     Increment verbose level by one.  This normally results  in(1,8)  more
              output during operation.  See also in(1,8) the description for the -t
              flag.  Normally, star(1,4) does its work silently.   If  the  verbose
              level  is  2  or more and star(1,4) is in(1,8) create or update(7,n) mode, star(1,4)
              will produce a listing to the format of the ls -l output.

       -V, -not
              Invert the meaning of the pattern list.  i.e.  use  those  files
              which  do  not  match any of the pattern.  Note that this option
              only applies to patterns that have been specified via  the  pat-
              tern=pattern  or  pat=pattern option. Patterns specified as file(1,n)
              type arguments will not be affected.

       -version
              Print version(1,3,5) information and exit.

       VOLHDR=name
              Use name to generate a volume header.

       -w     Do interactive creation, extraction or renaming.  For every file(1,n)
              that  matches  the  list  of patterns and that has a more recent
              modification time(1,2,n) in(1,8) the tar archive (if(3,n) in(1,8) extract mode and the
              -U option is not specified) star(1,4) prints its name and asks:

                     get/put ? Y(es)/N(o)/C(hange name) :

              You  may answer either `N' for No or <Return> to skip this file.
              If you answer `Y' the file(1,n) is extracted or archived on tape with
              its  original  name.   If you answer `C', you are prompted for a
              new name. This name is used for the filename on disk if(3,n) star(1,4)  is
              in(1,8)  extract  mode  or  for the archive name if(3,n) star(1,4) is in(1,8) create
              mode.

       See SECURITY NOTES for more information.

       -wready
              This option tells Star to wait up to two minutes for  the  drive
              to  become  ready.  It has been added as a hack for a bug in(1,8) the
              SunOS/Solaris st device driver.  This  driver  has  problems  to
              sense  the  loading  time(1,2,n)  with Exabyte drives with factory set-
              tings.  It also makes sense to use -wready  if(3,n)  multiple  remote
              backups  are made. In this case, the remote connection is closed
              while the remote tape server is still writing a file(1,n)  mark.   If
              another  remote backup is initiated before the old remote server
              did finish to write(1,2) the file(1,n) mark, it  would  be  impossible  to
              open(2,3,n) the tape driver unless -wready is specified to tell star(1,4) to
              wait for the drive to become ready again.

       -wtardumps
              Tell star(1,4) to update(7,n) the file(1,n) that contains the  tar  dump  dates
              data  base if(3,n) in(1,8) dump mode.  If the dump is not a full dump, the
              tar dump dates data base file(1,n) is not  written.   See  also  tar-
              dumps=name and -C option or INCREMENTAL BACKUPS section for more
              information.

       -xattr

       -xattr-linux
              Store and extract extended file(1,n) attributes  as  found  on  Linux
              systems.  This option only makes sense when creating or extract-
              ing exustar archives as it is based on POSIX.1-2001 extended tar
              headers.

              The  method  used in(1,8) the current implementation could be used to
              store and extract extended file(1,n) attributes from BSD  too.   Note
              that  the  current implementation is not generic enough to cover
              more general extended file(1,n) attribute implementations as found on
              Solaris.   If  star(1,4)  starts  to  implement  a method that covers
              extended file(1,n) attributes on Solaris, the new method will be used
              then  -xattr  has  been specified and -xattr-linux will refer to
              the old method.  The method used with -xattr-linux may  go  away
              in(1,8) the future.

       xdebug=#, xd=#
              Set extended debug level to #.

       -xdev, -M
              Do  not descend mount(2,8) points.  This is useful when doing backups
              of complete file(1,n) systems.  See NOTES for more information.

       -xdir  Extract directories even if(3,n) the corresponding directories on the
              archive are not newer.  This is useful when for some reason, the
              directories are  recorded  after  their  content  (see  -dirmode
              option), or when the permissions of some directories must be set(7,n,1 builtins)
              in(1,8) any case.

       -xdot  Unconditionally extract the first directory in(1,8)  the  archive  if(3,n)
              the name of this directory is either '.' or './'.  This helps to
              extract archives in(1,8) an expected way if(3,n) the target directory is a
              newly  created  empty directory. As this directory is newer than
              the top level directory in(1,8) the archive, star(1,4) would usually  skip
              this  directory during extraction.  The effect of this directory
              is as if(3,n) -xdir has been specified but is switched off after  the
              first directory has been found.

       -xfflags
              Store  and extract extended file(1,n) flags as found on BSD and Linux
              systems.  This option only makes sense when creating or extract-
              ing exustar archives as it is based on POSIX.1-2001 extended tar
              headers.  See NOTES section for problems with -xfflags on  Linux
              systems.

       -Z     run  the input or output through a compress pipe(2,8) - see option -z
              below.

       -z     run the input or output through a gzip pipe.  This is  currently
              a  quick  and dirty hack, that mainly will cover the most common
              usage to compress the tar output if(3,n) it is a file.  No reblocking
              will  be  done, so this option will currently only make sense on
              plain files.  The environment variable As the -bz the -j the  -Z
              and  the  -z option are non standard, it makes sense to omit the
              -bz the -j the -Z and the -z options inside shell scripts if(3,n) you
              are going to extract a compressed archive that is located inside
              a plain file(1,n) as star(1,4) will auto(5,8) detect compression and choose the
              right  decompression  option to extract.  STAR_COMPRESS_FLAG may
              be used to specify one option for gzip.  If you  want  to  write(1,2)
              write(1,2) compressed archives to tape, you should use
              star(1,4) -c . | gzip | sdd ibs=4k obs=32k -fill of=/dev/rmt/1bn
              or
              star(1,4)  -c  .  |  gzip  |  sdd  ibs=4k  obs=32k  -fill  ovsize=60m
              of=/dev/rmt/1bn
              if(3,n) the tape can hold 60 MB.

INCREMENTAL BACKUPS
       Star is able to back up file(1,n) system in(1,8) full and incremental  mode.   To
       allow  incremental backups, the file(1,n) system must implement POSIX seman-
       tics.

       The method used by star(1,4) depends on comparing the  time(1,2,n)  stamps  of  all
       files  against  the time(1,2,n) of the last backup. Note that this method only
       works correctly if(3,n) the level 0 backup and all higher level incrementals
       include  the  whole file(1,n) system.  As star(1,4) archives all inode meta data,
       star(1,4) is able to detect renamed files by comparing inode numbers.

       Detecting renamed files only works if(3,n) star(1,4) scans the whole file(1,n)  system
       tree  for  each full and incremental backup.  This will work in(1,8) case no
       files are excluded and the dump starts at the root directory of a  file(1,n)
       system.   In  case  that  no  files  are renamed from excluded parts to
       included parts, partial backups may be taken also. Partial backups only
       make  sense if(3,n) a complete directory sub tree is excluded (e.g. by using
       the pat= option) or if(3,n) a partial backup starts at a sub directory  that
       is not the root directory of the file(1,n) system.

       To create a level 0 dump call:

       star(1,4) -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
           f=archive-name -C /filestem-mount-point .

       To create a level 1 dump call:

       star(1,4) -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
           f=archive-name -C /filestem-mount-point .

       Backups  from life filesystems should be avoided.  On operating systems
       that support file(1,n) system snapshots, backups should be made from a read-
       only mount(2,8) of a snapshot. Be careful that all files that have been cre-
       ated between setting up a snapshot and starting an  incremental  backup
       may  be  missing  from  all  backups unless the dumpdate=name option is
       used.

       Star includes options that help to deal  with  file(1,n)  system  snapshots.
       The  following  example  backs up a file(1,n) system on Solaris using a file(1,n)
       system snapshot:

       echo(1,3x,1 builtins) > /tmp/snapstamp

       mount(2,8) -r `fssnap -F ufs -o \
           backing-store=/var/tmp/EXPORT-NFS.snap /export/nfs` /mnt

       star(1,4) -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
           f=archive-name dumpdate=/tmp/snapstamp \
           fs-name=/export/nfs -C /mnt .

       First a file(1,n) with a current time(1,2,n) stamp is created, then a snapshot  for
       /export/nfs is created and mounted on /mnt.  The following star(1,4) command
       then creates a level 0 backup from the file(1,n) system using the  time(1,2,n)  the
       snapshot  was  created  and the original mount(2,8) point of the file(1,n) system
       for /etc/tardumps and the archive header.

       Note that if(3,n) the backup is done on a life file(1,n) system, it may be  unre-
       liable.  A typical problem problem in(1,8) this context is caused by growing
       log files.  As growing files are not a real problem with  backups,  the
       best  way  of dealing with growing files is to set(7,n,1 builtins) up a star(1,4) error(8,n) con-
       trol file(1,n) (see errctl= option) and  to  tell  star(1,4)  to  ignore  growing
       files.

BACKUP SCHEDULES
       Full  (level  0)  dumps  should  be made on a regular base (e.g. once a
       month).  As a full dump may take a long time(1,2,n) and takes a lot  of  tape,
       it  is  wise to make higher level incremental dumps with shorter inter-
       vals.  The next table shows a dump level  list  that  may  be  used  if(3,n)
       monthly full dumps take place:

                          Sun   Mon   Tue   Wed   Thu   Fri
              Week 1:     0     10    10    10    10    5
              Week 2:     10    10    10    10    10    5
              Week 3:     10    10    10    10    10    5
              Week 4:     10    10    10    10    10    5

       The level 9 dumps made between Monday and Friday accumulate all changes
       made within the week. If you don't like this, use the following  backup
       schedule:

                          Sun   Mon   Tue   Wed   Thu   Fri
              Week 1:     0     20    30    40    50    5
              Week 2:     10    20    30    40    50    5
              Week 3:     10    20    30    40    50    5
              Week 4:     10    20    30    40    50    5

       Note that in(1,8) this case, 7 dumps need to be restored if(3,n) the a crash hap-
       pens at the worst case date (after the Friday dump in(1,8) week 2 or later).


INCREMENTAL RESTORES
       Incremental restores should be made to an empty file(1,n) system (except for
       the lost+found directory).  Star is currently unable to perform  incre-
       mental restores to a file(1,n) system that contains active mount(2,8) points.

       The  incremental  restore procedure starts with restoring the last full
       (level 0) dump. Then the latest incremental dump  of  each  dump  level
       (with ascending order of dump levels) need to be restored.

       Let  us  assume the first example from the section BACKUP SCHEDULES for
       the backup schedule. If a disk crash happens before the  Thursday  dump
       of  week  3  has been made, the following restore procedure needs to be
       applied:

       level 0
              starting with an empty disk, the full (level 0) dump from week 1
              is restored.

       level 5
              after  the  level  0 restore has been finished, the level 5 dump
              from Friday in(1,8) week 2 is restored.

       level 10
              after the level 5 restore has been finished, the level  10  dump
              from Wednesday in(1,8) week 3 is restored.

       The  disk  now  contains the same files as it did when the level 9 dump
       has been made on Wednesday of week 3.

       To extract a level 0 dump call:

       cd /filestem-mount-point
       star(1,4) -xpU -restore f=archive-name

       This creates the directory star-tmpdir and the  database  star-symtable
       in(1,8) the root directory of the new file(1,n) system.  Subsequent restores with
       higher level backups depend on these files.

       To extract a level 1 (or higher) dump call:

       cd /filestem-mount-point
       star(1,4) -xpU -restore f=archive-name

       Note that the environment variable STAR_DEBUG  exists,  star(1,4)  does  not
       remove files with link(1,2) count 1 that have been removed between incremen-
       tal dumps. These files are moved to the directory star-tmpdir.   Before
       you start to extract the next incremental, you need to remove all files
       in(1,8) star-tmpdir.


SYNCHRONIZING FILESYSTEMS
       Star may be used to synchronize filesystem content.   To  do  this,  an
       initial  copy  of the current content of the source filesystem needs to
       be performed first.

       To create an initial copy of a filesystem call:

       star(1,4) -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
           -C /filestem-mount-point . | \
           star(1,4) -xpU -restore -C /extract-target-dir

       In order to perform subsequent synchronization of the target filesystem
       with  the  content  of  the  source  filesystem, a modified incremental
       dump/restore procedure may be used.

       To copy incremental content of a filesystem call:

       star(1,4) -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
           -cumulative -C /filestem-mount-point . | \
           star(1,4) -xpU -restore -C /extract-target-dir

       Note that like with backups in(1,8) general, copies from a  life  filesystem
       should be avoided.  On operating systems that support file(1,n) system snap-
       shots, copies should be made from a read-only mount(2,8) of a  snapshot.  Be
       careful  that  all  files  that  have been created between setting up a
       snapshot and starting an incremental  copy  may  be  missing  from  all
       copies unless the dumpdate=name option is used.

       See section INCREMENTAL BACKUPS to learn how to modify the command line
       in(1,8) case file(1,n) system snapshots are used.

SIGNALS
       If star(1,4) handles a signal(2,7), it first prints the statistics.  Star handles
       the following signals:

       SIGINT    usually  generated  by  ^C  from  the  controlling tty.  Upon
                 receipt of a SIGINT, star(1,4) prints statistics and exits.  If in(1,8)
                 create mode i.e. storing files to archive, star(1,4) finishes with
                 the current file(1,n) to ensure that no partial file(1,n) is written to
                 the archive, write(1,2) an eof record and then exits.

       SIGHUP    not  to  be generated from a tty. The actions are the same as
                 upon receipt of a SIGINT.

       SIGQUIT   usually generated by  ^\  from  the  controlling  tty.   Upon
                 receipt  of  a  SIGQUIT, star(1,4) prints statistics and continues
                 with the current operation.  This  is  useful  to  watch  the
                 progress of the current operation.


EXAMPLES
       To get a listing in(1,8) a way similar to ls -l one might use:

              example% star(1,4) -tv f=/dev/rmt/1bn

       The  same  command  as  listed above in(1,8) a POSIX tar command line syntax
       compliant way is:

              example% star(1,4) tvf /dev/rmt/1mbn

       To copy the directory tree in(1,8) /home/someuser to the directory  /home/fs
       use:

              example% (cd /home/someuser; star(1,4) -c .) | (cd /home/fs ; star(1,4) -xp)

       or by using the change directory option of star(1,4):

              example% star(1,4) -c -C /home/someuser . | star(1,4) -xp -C /home/fs

       To  copy  a file(1,n) tree including the Access Control List entries for all
       files use:

              example% star(1,4) -c -Hexustar -acl -C /home/someuser . | star(1,4) -xp -acl -C /home/fs

       To compare the content of a tape to the filesystem one might use:

              example% star(1,4) -diff -v f=/dev/rmt/1bn

       To compare two directory trees one might use:

              example% star(1,4) -c . | star(1,4) -C todir -diff -v diffopts=!times

       To compare all properties of two file(1,n) trees, use:

              example% star(1,4) -c -dump -C fromdir . | star(1,4) -C todir -diff -vv

       To extract a backup of the /usr tree without all files  residing  below
       /usr/openwin one might use:

              example% star(1,4) -xp -V pat=openwin/\* f=/dev/rmt/1bn

       To extract all .c files to src, all .o files to obj and all other files
       to /tmp one might use:

              example% star(1,4) -xp -C src '*.c' -C obj '*.o' -C /tmp '*' f=/dev/rmt/1bn

       To extract files from a zipped tar archive that is located  on  a  read(2,n,1 builtins)
       only filesystem e.g. a CD while having the shell's working directory on
       the CD one might use:

              example% star(1,4) -zxp -C /tmp f=star-1.1.tar.gz

       to extract the files from the tar archive to the /tmp directory.

       To backup a list of files generated by the find(1) command:

              example% find . find_options -print | star(1,4) -c list=- f=/dev/rmt/1bn

       Note that this does not work if(3,n) the file(1,n) names from output of the  find
       command include new line characters.

       To extract a tarfile that contains a tarfile one might use:

              example% star(1,4) -x -to-stdout f=/dev/rmt/1bn pat=pat | star(1,4) -xp

       Pat,  in(1,8) this case should match the tarfile in(1,8) the tarfile on tape that
       should be extracted.

       To make a backup of the root filesystem to a tape drive connected to  a
       remote machine, one might use:

              example# cd /
              example# star(1,4) -cM fs=128m bs=63k f=tape@remotehost:/dev/rmt/1bn .

       You need a line in(1,8) /etc/passwd(1,5) like the following to enable this:

              tape:NP:60001:60001:Tape:/etc/tapehome:/opt/schily/sbin/rmt

       And  a  .rhosts  file(1,n) in(1,8) /etc/tapehome to allow remote connections from
       the appropriate hosts.  Make sure that the file(1,n) /etc/default/rmt exists
       and allows remote access(2,5) to the requested tape drive.

       To  use  a  ssh(1) connection for a backup to a remote tape server, one
       might use:

              example#  env(1,3)   RSH=/usr/bin/ssh   star(1,4)   -cM   fs=128m   bs=63k
              f=tape@remotehost:/dev/rmt/1bn .


       To  repair a corrupted filesystem for which no recent backup exists, do
       the following:

              example# fsck -y /filesys
              example# mount(2,8) /filesys
              example# cd /filesys
              example# star(1,4) -xpk f=/dev/rmt/1bn
              example# mt -f /dev/rmt/1bn rewind
              example# star(1,4) -diff -v diffopts=!times f=/dev/rmt/1bn

       Now check the differences and  decide  whether  to  restore  additional
       files.  This  may  be  done  by generating a list containing the needed
       filenames and using the list= option or by using the  interactive  mode
       (see -w option).

       If  you  want  a  list that only contains all filenames from files with
       differences you may use:

              example# star(1,4) -diff -tpath diffopts=!times f=/dev/rmt/1bn

       If you are looking for files that changed the type or the  access(2,5)  per-
       mission because this is a common case on still corrupted files, use:

              example# star(1,4) -diff -tpath diffopts=type,perm f=/dev/rmt/1bn


ENVIRONMENT
       STAR_COMPRESS_FLAG
              If you like star(1,4) to always create compressed files that use max-
              imum compression, you may set(7,n,1 builtins) the environment variable STAR_COM-
              PRESS_FLAG to -9.

       STAR_DEBUG
              If  this  environment  variable is present, star(1,4) will not remove
              temporary files from ./star-tmpdir.  The files in(1,8) this directory
              are files that have been removed by users(1,5) before the last incre-
              mental dump did take place on the master(5,8) filesystem.

       STAR_FIFOSIZE
              If you like to by default let star(1,4) use a  different  fifo  size,
              set(7,n,1 builtins) this environment variable to the desired size.

       TAPE   Unlike  other  tar(1)  implementations,  star(1,4)  defaults  to  use
              stdin/stdout for the archive.  If you like star(1,4) to use the  file(1,n)
              name  from the TAPE environment instead, you need to specify the
              -T option too.

       RSH    If the RSH environment is present, the  remote  connection  will
              not be created via rcmd(3) but by calling the program pointed to
              by RSH.  Use e.g.  RSH=/usr/bin/ssh to  create  a  secure  shell
              connection.

              Note  that  this forces star(1,4) to create a pipe(2,8) to the rsh(1) pro-
              gram and disallows star(1,4) to directly access(2,5) the network socket(2,7,n) to
              the  remote  server.  This makes it impossible to set(7,n,1 builtins) up perfor-
              mance parameters and slows down the  connection  compared  to  a
              root initiated rcmd(3) connection.

              See BUGS section for more information.

       RMT    If  the  RMT environment is present, the remote tape server will
              not be the program /etc/rmt but the program pointed to  by  RMT.
              Note that the remote tape server program name will be ignored if(3,n)
              you log in(1,8) using an account that has been created with a  remote
              tape server program as login(1,3,5) shell.

FILES
       /etc/default/star(1,4)
              Default   values  can  be  set(7,n,1 builtins)  for  the  following  options  in(1,8)
              /etc/default/star.  For example: CDR_FIFOSIZE=64m

              STAR_FIFOSIZE
                     Sets the default size of the FIFO (see also fs=# option).

              STAR_FIFOSIZE_MAX
                     Sets the maximum size of the FIFO (see also fs=# option).
                     Setting STAR_FIFOSIZE_MAX in(1,8) /etc/default/star(1,4) allows  to
                     overwrite  global values from backup scripts for machines
                     with less(1,3) memory.

              archive0=

              archive2=

              archive3=

              archive4=

              archive5=

              archive6=

              archive7=

              archive0=
                     Archive entries for the -[0..7] option.

                     A  correct  archive?=  line  has  3..4  space   separated
                     entries.   The  first  is  the  device  entry  (e.g.  ar-
                     chive0=/dev/tape).  The second is the blocking factor(1,6)  in(1,8)
                     512  byte  units.  The third is the maximum media size in(1,8)
                     1024 byte units.  If this entry contains a  0,  then  the
                     media  size  is unlimited.  The fourth entry is optional.
                     It if(3,n) contains a 'n' or a 'N', then the archive device is
                     not a tape.

                     Examples:

                     archive0=/dev/tape 512 0 y
                     archive1=/dev/fd0 1 1440 n
                     archive2=/dev/rmt/0mbn 512 0

                     If  the  default file(1,n) does not need to be shared with the
                     tar program from Solaris, any number may be used  like  a
                     generic size option like bs=.

                     Example:

                     archive0=/dev/tape 256k 40G y

       /etc/tardumps
              The default name for the dump level archive. The default name is
              used whenever the tardumps=name option has not  been  specified.
              The file(1,n) is written or updated when -wtardumps is used.

              The  file(1,n)  holds one or more lines, each specifying a dump level
              entry.  Each dump level entry starts with  a  mount(2,8)  point  name
              followed  by a TAB and one or more spaces, followed by the deci-
              mal dump level, a space and the dump time.

              If the dump level is directly followed by a 'P', then  the  dump
              refers to a partial dump (a dump that does not include the whole
              filesystem).

              The dump time(1,2,n) itself includes the decimal representation of  the
              UTC  seconds  since  Jan  01 1970, a space and the textual local
              time(1,2,n) representation of the dump time.

              The numerical decimal dump time(1,2,n) representation may  be  followed
              by  a dot and a sub second value.  The textual local time(1,2,n) repre-
              sentation is for informational use by humans only and not evalu-
              ated by star(1,4).

       ./star-symtable
              Contains  a database that is needed in(1,8) incremental restore mode.

       ./star-tmpdir
              Is the temporary directory that is  used  as  intermediate  file(1,n)
              storage by star(1,4) if(3,n) in(1,8) incremental restore mode.

       /dev/tty(1,4)
              Is used for the intercative user interface.

SEE ALSO
       spax(1),  suntar(1),  scpio(1), tar(1), cpio(1), pax(1), rcp(1), mt(1),
       rmt(1), match(1), dd(1), sdd(1), rsh(1),  ssh(1),  star(1,4)(4/5),  rcmd(3),
       fssnap(1m)

DIAGNOSTICS
       star: f records + p bytes (total of x bytes = d.nnk).

       The  number of full records, the number of bytes in(1,8) partial records and
       the total amount of data in(1,8) KBytes.

       star: Total time(1,2,n) x.yyysec (z kBytes/sec)

       The time(1,2,n) used and the transfer speed from/to the archive.

       If there have been non fatal errors during the archive processing, star(1,4)
       will display a delayed error(8,n) summary before exiting.


NOTES
       The  command  line  syntax  for  the tar command (as defined in(1,8) SUSv2 -
       UNIX-98) deviates from the command line syntax defined  for  all  other
       commands.  While  the POSIX command line syntax requests all options to
       start with a dash (-) and allows to either write(1,2) options separately  or
       combined  (in(1,8)  case  of  boolean  flags),  the  tar command line syntax
       requires all options to be combined into a single string(3,n) that does  not
       start  with a dash.  Star by default assumes a command line syntax like
       a typical POSIX command and includes a compatibility mode  that  allows
       to specify a command line syntax as documented for the UNIX-98 tar com-
       mand.  If you believe that you found a bug in(1,8) the way star(1,4)  parses  the
       command  line,  please  first  check  your command line for correctness
       before you make a bug report for star(1,4).

       If you like to write(1,2) portable shell scripts  that  call  tar,  use  the
       UNIX-98  tar  command  line  syntax (i.e. a single option string(3,n) and no
       dash), choose the commands and options from the following set(7,n,1 builtins) of  char-
       acters  (  rxtuc  vxfblmo  ) and check the shell script with both, your
       local tar and star(1,4) for correct behavior. It you expect  the  script  to
       call  gnutar,  do  not  include the -o option as gnutar implements this
       option in(1,8) a way that violates UNIX-98.

       Star strips leading ./ sequences from pathnames. This lets star(1,4) in(1,8) many
       cases store longer pathnames than other implementations.

       The  POSIX.1-1988 method (ustar format) of storing files with pathnames
       that are longer than 100 chars has some limitations:

              The name field (100 chars) an inserted slash (`/') and the  pre-
              fix  field  (155  chars)  produce the pathname of the file. When
              recreating the original filename, name and prefix  are  concate-
              nated, using a slash character in(1,8) the middle. If a pathname does
              not fit in(1,8) the space provided or may not be  split(1,n)  at  a  slash
              character  so  that the parts will fit into 100 + 155 chars, the
              file(1,n) may not be archived.  Linknames longer than 100  chars  may
              not be archived too.

       The star(1,4), xstar, xustar, exustar, pax, and gnutar archive formats don't
       have these limitations. While gnutar uses a method that makes it impos-
       sible  for other tar implementations (except star(1,4)) to restore filenames
       that are longer than 100 chars, the xstar, xustar, exustar and pax  ar-
       chive format uses a method that allows an POSIX.1-1988 compliant way of
       storing filenames, if(3,n) the POSIX method would allow this.  When the  ar-
       chive  format  is xustar, exustar or pax very long filenames are stored
       using extended headers from the POSIX.1-2001 standard.

       Some buggy tar implementations will generate incorrect filenames during
       a  restore  operation if(3,n) the archive contains pathnames or linknames of
       exactly 100 chars length.

       Star adds a tar signature in(1,8) the last four bytes of each tar header  if(3,n)
       the  archive format is star(1,4) or xstar.  This is no problem with the star(1,4)
       archive format as it is an extension of the old  pre  POSIX.1-1988  tar
       format.   On  the  other side, the xstar archive format claims to be as
       POSIX.1-1988 compliant as possible.  Inserting this tar signature is  a
       minor  deviation  from  the standard that has the last 12 bytes of each
       header reserved for future use. On the other side, tar  implementations
       such  as  some  pax  implementations that only compute checksums on the
       first 500 bytes of the header are violating the standard that  requests
       the checksum to be computed on all 512 bytes of the tar header. All tar
       implementations that are 100% Posix compliant will be able  to  extract
       xstar  archives  as  long as no new standard is defined that claims the
       last 12 bytes of the header for a different use.  But  then  the  ustar
       version(1,3,5)  number  should  be  changed  from `00' to `01'.  Now, that the
       POSIX-2001 standard has been accepted, it is even predictable that  all
       extensions  to  the  standard  tar format will go into the POSIX.1-2001
       extended headers which are extensible to include  any  feature  without
       future  limitation.   The  only known tar implementation that also uses
       the last 12 bytes of the tar header is Sun's tar which  uses  these  12
       bytes  for  files  that  are split(1,n) over several archives. Such archives
       created by Sun's tar are not readable by the buggy  pax  implementation
       too.  The  Sun  extension  is  not  incompatible  to the star(1,4) signature
       because Sun expects an octal number at the beginning  of  the  12  byte
       field which is a null character in(1,8) the star(1,4) case.

       Star  uses these four bytes since 1985 without problems.  If you need a
       100% POSIX.1-1988 and 100% POSIX.1-2001 compliant tar archive, you  may
       use  the xustar, exustar or the pax archive format.  The probability of
       falsely detecting other tar formats as xustar or exustar format however
       is higher.

       There is no way to ask for the n-th occurrence of a file.

       The  way  EOF is handled by star(1,4) differs, whether the fifo is in(1,8) effect
       or not.  If the fifo is not used, star(1,4) stops reading the archive if(3,n)  it
       encounters  a  logical EOF record in(1,8) the archive.  If the fifo is used,
       star(1,4) may read(2,n,1 builtins) until the fifo is full or until the real EOF mark on tape
       is reached.  How much data star(1,4) actually reads depends on the time(1,2,n) when
       the star(1,4) foreground process sends a fifo shutdown(2,8) signal(2,7) to  the  back-
       ground fifo read(2,n,1 builtins) process.

       Gnu  tar  often  creates tar archives with incorrect logical EOF marks.
       The standard requires two blocks that are  completely  zeroed,  whereas
       gnutar often only adds one of them.

       Old  versions  of  tar  found on SYSVr3 and earlier cannot read(2,n,1 builtins) tar ar-
       chives with a blocksize greater than 10 kBytes.

       The method of storing sparse files currently used  with  the  star(1,4)  and
       xstar  format  is  not guaranteed to be used in(1,8) later versions of star(1,4).
       If the author decides to change this method, later versions of star(1,4) may
       not  be able to restore sparse files from tar archives made by the cur-
       rent version(1,3,5) of star(1,4).

       Some tar implementations violate the standard in(1,8) using only  the  first
       500 Bytes of the header for checksum computation. These tar implementa-
       tions will not accept(2,8) star(1,4) and xstar type tar archives.

       Sun's Solaris 2.x tar implementation violates the Posix  standard.  Tar
       archives  generated  by  star(1,4)  cause Sun's tar to print tar: impossible
       file(1,n) type messages. You may ignore these messages.

       Gnutar's dumpdirs are non standard and are currently not implemented.

       If gnutar archives sparse files with more than four holes, it  produces
       archives  that  violate  the  standard in(1,8) a way that prevents other tar
       implementations to read(2,n,1 builtins) these archives.  Star knows about that  and  is
       able to handle these gnutar archives.

       The  filetype  N  (LF_NAMES) from gnutar (an obsolete method of storing
       long names) will never be implemented.

       Note that on operating systems (like DOS) that do  not  implement  real
       pipes,  star(1,4)  implements  compression via a temporary file.  Using com-
       pression thus is limited by the maximum file(1,n)  size  and  the  available
       disk space.

       The  extended  file(1,n) flags implementation (see -xfflags option) on Linux
       is buggy by design.  In order to retrieve the needed information, every
       file(1,n)  needs  to be opened.  If the /dev directory is included in(1,8) create
       mode, every possible driver will be loaded which may  hang  the  system
       for  a long time. In the worst case, unwanted side effects from opening
       devices (such as causing tape  drives  to  rewind  the  media)  may  be
       caused.


SECURITY NOTES
       If  you unpack a tar archive in(1,8) a non empty directory, any file(1,n) in(1,8) that
       directory may be overwritten unless you specify the -k option.  If  the
       archive  contains symbolic links or hard links, star(1,4) may even overwrite
       files outside the current directory.  As many other commands, star(1,4) usu-
       ally has all possible permissions when run as root.  Unpacking archives
       as root thus may have fatal results to any file(1,n)  on  your  system.   Be
       very  careful when you try to extract an archive that has not been cre-
       ated by you. It is possible to create hand crafted  tar  archives  that
       may  overwrite  critical  files  (like /etc/passwd(1,5)) on your system.  In
       addition all tar archives that have been created with the list=  option
       and  tar archives where the C= option was not specified before all file(1,n)
       type arguments may be critical.

       A good advise is to extract all doubtful archives as  non  root  in(1,8)  an
       empty  directory and to specify the -secure-links option.  If you get a
       warning, you should unpack the archive a second time(1,2,n)  and  specify  the
       options  -k,  -w  and  -nowarn  in(1,8) addition to the options used for the
       first run.

SUID NOTES
       If star(1,4) is installed suid root, star(1,4) is able  to  make  connections  to
       remote  archives for non root users.  This is done by using the rcmd(3)
       interface to get a connection to a rmt(1) server.

       Star resets its effective uid back to  the  real  user  id  immediately
       after  setting  up  the  remote connection to the rmt server and before
       opening any other file.

       If star(1,4) has not been installed suid root and not  called  by  root,  it
       will  try to create the remote connection via rsh(1) or ssh(1) (in(1,8) case
       the environment RSH has been set(7,n,1 builtins) to ssh).  Note that in(1,8) this case,  the
       throughput  to  the  remote  tape server will be much lower than with a
       connection that has been initiated via rcmd(3).

LIMITATIONS
       If star(1,4) is running on a large file(1,n) aware platform, star(1,4) is able to han-
       dle  files  up  to 8 GB in(1,8) a mode that is compliant to the POSIX.1-1988
       ustar format. With a nonstandard star(1,4) specific extension, up to 95 bits
       may  be  used  to  code  the  filesize.   This  will handle files up to
       200,000,000 TB.  With the new POSIX.1-2001 extended headers used by the
       xustar, exustar and pax format, any filesize may be archived.

BUGS
       The fact that the -f option has to be implemented in(1,8) a way that is com-
       patible with old  tar  implementations  gives  several  problems.   The
       options -fifostats, -force-hole, -force-remove and -fifo interfere with
       the -f option and the fact that they exist prevents  users(1,5)  from  using
       filenames  like  e.g.  ifo using the traditional way where the filename
       directly follows the string(3,n) -f without any  space  between  the  option
       name  and  the  file(1,n)  name.  However, there is no problem to use a file(1,n)
       named(5,8) ifo by by calling -f ifo, f=ifo, -f=ifo or -f= ifo.   Be  careful
       not  to  make  typos with the above options. The result could be that a
       file(1,n) is created as a result of the mistyped option.

       There is currently no way to set(7,n,1 builtins) the fifo lowwater and highwater marks.

       There  is  currently no way to automatically delete files in(1,8) the target
       file(1,n) tree if(3,n) they are obsolete.  Star should implement something  simi-
       lar to gnutar's dumpdirs.

       If  not invoked by the super user star(1,4) may not be able to extract files
       if(3,n) they reside in(1,8) read(2,n,1 builtins) only directories.

       Star is not able to make a complete backup of a filesystem if(3,n) files are
       hidden  by a mount(2,8) that is in(1,8) effect on a directory of this filesystem.
       This may be avoided in(1,8) case of the ufs filesystem if(3,n) the backup is made
       off a ufs snapshot (see the man(1,5,7) page for fssnap(1m) It could be avoided
       for any filesystem if(3,n) the loopback filesystem had an option that  tells
       lofs not to traverse mountpoints.

       For now (late 2002), we know that the following programs are broken and
       do not implement signal(2,7) handling correctly:

       rsh    on SunOS-5.0...SunOS-5.9

       ssh    from ssh.com

       ssh    from openssh.org

       Sun already did accept(2,8) a bug  report  for  rsh(1)/ssh(1).   Openssh.org
       accepted and fixed a bug for their implementation of ssh(1).

       If  you use star(1,4) to create a remote connection via an unfixed rsh(1) or
       ssh(1), be prepared that terminal generated signals may  interrupt  the
       remote connection.


HISTORY
       Star  was  first  created in(1,8) 1982 to extract tapes on a UNIX clone that
       had no tar command.  In 1985 the first  fully  functional  version(1,3,5)  has
       been released as mtar.

       When  the  old  star(1,4) format extensions have been introduced in(1,8) 1985, it
       was renamed to star(1,4) (Schily tar).  In 1994,  Posix  1003.1-1988  exten-
       sions were added and star(1,4) was renamed to star(1,4) (Standard tar).


AUTHOR
       Joerg Schilling
       Seestr. 110
       D-13353 Berlin
       Germany

       Mail bugs and suggestions to:

       schilling@fokus.fraunhofer.de       or       js@cs.tu-berlin.de      or
       joerg@schily.isdn.cs.tu-berlin.de



Joerg Schilling                    05/07/10                            STAR(1)

References for this manual (incoming links)