Provided by: star_1.5final-2ubuntu1_i386 bug

NAME

       star - unique standard tape archiver

SYNOPSIS

       star  command [options] [-find] file1 ... filen [find_expr]
       ustar command [options] [-find] file1 ... filen [find_expr]
       tar   command [options]         file1 ... filen
       star  -copy   [options] [-find] file1 ...  [f_expr] directory
       star  -copy   [options] -C from_directory . to_directory

DESCRIPTION

       Star   is   a  very  fast  tar(1)  like  tape  archiver  with  improved
       functionality.

       Star archives and extracts multiple files to and  from  a  single  file
       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 acts may be modified by additional options.

       Note that unpacking tar archives may be a security  risk  because  star
       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  POSIX.1-2001  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 stamps in
       sub-second resolution, 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  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
       processed.  This  gives  a  convenient  interface  for  archiving   and
       restoring complex lists of files. In conjunction with the -w flag it is
       easy to merge a tar archive into an existing file  tree.  See  also  -U
       option.  In create mode use the pat= option to specify either select or
       exclude patterns (depending on the -V flag). In extract  or  list  mode
       all  file  type  arguments are interpreted as select patterns while the
       patterns specified with the pat=  option  may  be  used  as  select  or
       exclude  patterns  (depending  on  the  -V  flag).   Have a look at the
       description of the -C option to learn how to fetch files from a list of
       directories  (in  create  mode)  or  to  distribute  files to a list of
       directories (in extract mode).  A substitute option allows  ed(1)  like
       pattern substitution in file names.

       Star  includes  an  enhanced  function  that  is similar to the find(1)
       command (see sfind(1)).  This allows to use find expressions,  even  in
       extract  or  list  mode,  directly  on  the content on an archive.  The
       extensions to find(1) allow to modify the file metadata.

       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 the
       archive format is either chosen from the star specific formats or is  a
       format that uses POSIX.1-2001 extended headers.  This is either done in
       second resolution by using  a  star  specific  POSIX.1-1988  compatible
       extension  or  in  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 is able to do backups
       without changing any of the 3 the times.

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

       Starβ€β€™s  default  format  (if  called  as star) is xstar and is as posix
       compliant 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 effect.
       All  other  files  will extract correctly.  See the description for the
       H=headertype option below for more information on archive  formats  and
       possible archive interchange problems.

       Star makes it easy to repair corrupted filesystems. After a fsck -y has
       been run on the filesystem, star is able to restore  only  the  missing
       files automatically.  Use then star -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
       their native mode, if it knows about the peculiarities of  the  archive
       type.   See the H=headertype option for more details.  To be able to do
       this, star adds hidden fingerprints to the archive header  that  allows
       to  recognise  all star 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  is  compatible to the command line syntax of a
       typical 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 expects commands and options to
       appear as one single string that does not start with a dash.  In  POSIX
       tar  compatibility  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 named files into it.  Writing
              starts  at  the  beginning  of  tarfile.   See  -v  option   for
              information  on  how  to increase verbosity while the archive is
              written.

       -copy  Copy named files to the target directory which is the last  file
              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  addition, star
              performs 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 I/O (such as Linux), it  may
              help  to  use  -no-fsync in addition, but then star is unable to
              detect all error conditions; so use with care.

              If the option -t has been specified in addition, the  last  file
              type argument is not a target directory and star is performing a
              one pass listing instead of copying files.  This makes sense  as
              the  listing  from  star  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 the best archive mode.  This
              implies that it defaults to  H=exustar  -dump.   When  in  -copy
              mode,  star  forks  into two processes and data exchange is done
              via the shared memory  from  the  FIFO.   This  gives  the  best
              possible  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
              archive in tarfile to the filesystem.  This may also be used  to
              compare  two  file trees in the filesystem.  If you use a set of
              diffopts that fits your needs, it will give - in many cases -  a
              more  readable  output  than  diff  -r.   If you use starβ€β€™s dump
              extensions for the tar archive, the -diff option allows to  find
              even  if the directory in the file tree contains more files than
              the archive. This way, it is possible to compare all  properties
              of  two  file  trees in 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 star is
              reading a tar archive that has been created in -dump mode.

       -n     No extraction. Show what star would do, in case the  -x  command
              had been specified.

       -r     Replace  files in a tarfile.  The named 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
              output.   With this option, the flags -a, -atime and -ctime have
              a different meaning if the archive is in  star,  xstar,  xustar,
              exustar,  or  pax  format.   The  option  -a or -atime lists the
              access time instead of the modification time, the option  -ctime
              lists  the  file creation time instead of the modification time.
              The option -tpath may be used in addition to modify  the  output
              so it may be used in shell scripts.

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

       -x     Extract  the  named  files  from  the  tarfile.   If no filename
              argument or pattern is specified,  the  entire  content  of  the
              tarfile  is restored.  If the -U flag is not used, star extracts
              no file which is older than the corresponding file on disk.

              On operating systems with slow file I/O (such as Linux), it  may
              help  to  use  -no-fsync in addition, but then star is unable to
              detect all error 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
       patterns and substitute commands apply to the create side.

OPTIONS

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

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

       -/     Don’t  strip  leading slashes from file 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 extract mode.  As it may  be  impossible  to  create  an
              archive where leading slashes have been stripped while retaining
              correct path names, star  does  not  strip  leading  slashes  in
              create mode.

              See SECURITY NOTES for more information.

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

              See SECURITY NOTES for more information.

       -7z    run the input or output through a p7zip pipe  -  see  option  -z
              below.

              Note that the p7zip program currently does not operate on a pipe
              but on a /tmp file copy and  thus  limits  the  maximum  archive
              size.

       -0

       -1

       -2

       -3

       -4

       -5

       -6

       -7     Select  an archive entry from /etc/default/star.  The format for
              the  archive  entries   is   the   same   as   the   format   in
              /etc/default/tar in Solaris.

       -acl   Handle  Access  Control  List  (ACL)  information  in create and
              extract mode.  If -acl has been specified,  star  is  in  create
              mode  and  the  header  type  is  exustar,  star  will  add  ACL
              information to the archive using POSIX.1-2001 extended  headers.
              If  -acl  has  been  specified and star is in extract mode, star
              will try  to  restore  ACL  information.  If  there  is  no  ACL
              information for one or all files in the archive, star will clear
              the ACL information for the specific file.  Note  that  if  -acl
              has  not been specified, star 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
              assumes that the -p option has been specified too.

       artype=headertype
              Generate a tape archive in headertype format.  If this option is
              used  in  extract/list  mode  this  forces star to interpret the
              headers to be of type headertype.  As star even  in  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 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 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      Old star standard format. This is  an  upward/downward
                        compatible enhancement of the old (pre Posix) UNIX tar
                        format.  It has been introduced in 1985 and  therefore
                        is  not  Posix  compliant.   The star format allows to
                        archive  special  files  (even  sockets)  and  records
                        access time and creation time besides the modification
                        time. Newer versions of the old star format allow very
                        long  filenames (100+155 chars and above), linknames >
                        100 chars and sparse files (if -sparse is used).  This
                        format  is able to copy the device nodes on HP-UX that
                        have 24 bits in 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  the  space
                        between  the link name and the POSIX file name prefix.
                        As the star format does not use a POSIX magic  string,
                        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,  in  special  when  sparse  files are
                        archived using the -sparse option.  Using  the  gnutar
                        archive  format  causes a high risk that the resulting
                        archive may only be read by gnutar or  by  star.   The
                        implementation  of  the  gnutar  archive format within
                        star is not complete, but sufficient for  most  gnutar
                        archives.  See NOTES for more information.

              ustar     IEEE/Posix1003/IEC-9945-1-1988      Standard      Data
                        Interchange format.  With this option in effect,  star
                        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 is  called  as  ustar  the  default
                        archive format is ustar.

                        If  the  ustar format has been selected, star 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 will not use
                        enhancements  to  the  POSIX.1-2001  tar  format,  the
                        archive will be strictly  conforming.   File  size  is
                        unlimited,    uid/gid/uname/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 1994.   Star  uses  the  xstar  format  as  default
                        archive 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  time  and creation time.  Sparse files will be
                        archived correctly (if -sparse is used).

                        The access time and creation time are  stored  at  the
                        end  of  the  POSIX  file name prefix (this limits the
                        prefix  to  130  chars).   These  extensions  do   not
                        interfere  with  the  POSIX standard as the fields for
                        mtime and ctime field are always  separated  from  the
                        POSIX  file  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  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
                        otherwise  identical to the xstar format.  As some tar
                        implementations do not  follow  the  POSIX  rules  and
                        compute  the  checksum  for less than 512 bytes of the
                        tar header, this format may  help  to  avoid  problems
                        with these broken tar implementations.  The main other
                        difference to the xstar  format  is  that  the  xustar
                        format  uses POSIX.1-2001 extended headers to overcome
                        limitations of the historic tar format while the xstar
                        format uses proprietary extensions.  The xustar format
                        is the default format when star is called as tar.

                        File  size  is  unlimited,  uid/gid/uname/gidname   is
                        unlimited,  major/minor  is  unlimited.   Sparse files
                        will be archived correctly (if -sparse is used).

              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  records  Access
                        Control Lists (ACLs) in POSIX.1-2001 extended headers.

                        The exustar format allows to archive  all  file  types
                        but it does not archive more than the POSIX.1-1988 set
                        by default.  If the -dump option is used or if star is
                        otherwise  on  dump mode, star archives all file types
                        and in addition archives more meta data then usual.

                        File  size  is  unlimited,  uid/gid/uname/gidname   is
                        unlimited,  major/minor  is  unlimited.   Sparse files
                        will be archived correctly (if -sparse is used).

              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 addition uses ’X’ as the
                        typeflag  for  the  extended  headers  instead  of the
                        standard ’x’.

                        File  size  is  unlimited,  uid/gid/uname/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
                        format.  It is only present to make the scpio  command
                        SVr4 compliant.

              cpio      The  POSIX.1-1988  cpio format. This format uses octal
                        ascii 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  name  length  up  to  262142
                        characters and allows to archive nearly any file 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
                        format.

              odc       This archive format is similar to the The POSIX.1-1988
                        cpio format but the file name length is limited to 255
                        characters  and  the  socket file 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 the archive. Use this  format  whenever
                        you  are  not sure if 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 to create a cpio archive in the ascii 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 size to 4  GB  -  2
                        bytes although the format has been specified after the
                        POSIX.1-1988  cpio  format.   Try  to  avoid  the  asc
                        archive format because of its limited portability.

              crc       This  format  is similar to the asc cpio format but in
                        addition uses a simple byte based checksum called CRC.
                        Try  to  avoid  the  crc archive format because of its
                        limited portability.

              All tar archive formats  may  be  interchanged  if  the  archive
              contains  no files that may not be archived by using the old tar
              format.  Archives in the xstar format may be  extracted  by  any
              100% POSIX compliant tar implementation if they contain no files
              with pathnames > 100+130 chars and if  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 will not overwrite files  that  are  read  only.   If  this
              option  is  in  effect,  star  will ask whether it should remove
              these files to allow the extraction of a file in  the  following
              way:

                     remove β€β€™filenameβ€β€™ ? Y(es)/N(o) :

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

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

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

                   mt fsr blockno

              to skip to the tape block number of interest in a fast way if  a
              single file needs to be restored.

       blocks=#, b=#
              Set  the  blocking  factor  of  the tarfile to # times 512 bytes
              (unless a different multiplication factor has been  specified  -
              see  bs=  option for possible multiplication factors).  Changing
              the blocking factor 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  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),
              blocksize should not be more than 10 kBytes.   For  POSIX.1-1988
              compatibility,  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 any case is the size of the buffer
              RAM in the tape drive.  Make a test if you  want  to  make  sure
              that  the  target system will handle the intended blocksize.  If
              you use star for data exchange via tape, it is a  good  idea  to
              use  a  blocksize  of  10 kBytes  unless  you  are sure that the
              reading system will handle a larger blocksize.  If you use  star
              for backup purposes with recent hardware (e.g. DLT tape drives),
              a blocksize of 256 kBytes results in sufficient speed and  seems
              to  be  a good choice.  Star allows block sizes up to 2 GByte if
              the system does not impose a smaller  limit.   If  you  want  to
              determine  the  blocking  factor  when  reading  an  unknown tar
              archive on tape, specify a blocking factor that is  higher  than
              the  supposed  blocking  factor  of  the  tape.   Star then will
              determine the blocking factor by reading the first record of the
              tape and print a message:

                     star: Blocksize = # records.

              Where  #  is the blocking factor in 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
              dd(1) and sdd(1).  The number representing the size is taken  in
              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 β€˜*’,
              multiplication 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 is to stay in a working directory until  a  new
              C=  is seen.  With BSD tar, the C= option is only related to the
              next file type argument.

       -bz    run the input or output through a bzip2 pipe - 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 you are going to extract
              a compressed archive that is located inside a plain file as star
              will  auto detect compression and choose the right decompression
              option to extract.

       C=dir

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

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

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

              Β·      In  extract  mode  (with the -x, -n and -diff flag), star
                     builds  a  pattern  list  together   with   corresponding
                     directories  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 they were preceded by a -C .
                     option.  See EXAMPLES for more information.

       compress-program=name
              Set  a  named  compress program.  The program must compress in a
              pipe when called without parameters and decompress when run with
              the  -d  option  in 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
              creating  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 twice as
              star cannot copy files that appear in the archive later  than  a
              symlink pointing to them.

       -copysymlinks
              This  option  allows  to  copy  symlinked  targets  rather  than
              creating 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 twice  as
              star  cannot  copy files that appear in the archive later than a
              symlink pointing to them.

       -cpio-statistics
              Instead of the star flavor of the statistics,  print  statistics
              in cpio flavor.

       -ctime If  used  with  the  list  command, this lists ctime rather than
              mtime if the archive format is star, xstar, xustar, exustar,  or
              pax.

              If  star  is  run as root and if -ctime is used with the extract
              command and the same archive formats, this causes star to try to
              restore even the ctime of a file by generating time storms.  You
              should not do this when in multi  user  mode  because  this  may
              confuse  programs  like cron and the news system.  Although star
              tries to eliminate the accumulative effects of the  time  storm,
              there  is  a  tendency  for the system clock to slow down a bit.
              The clock typically lags about  one  millisecond  per  extracted
              file.  Use with care and check the system clock after using this
              feature.

              If used with the create command this changes the behavior of the
              newer=  option.   Star,  in  this case compares the ctime of all
              files to the mtime of the stamp file 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 descends  the  whole
              tree  if  it  encounters  a directory in in its file parameters.
              The option -D is in effect by default if the list=file option is
              used.  If you like star to descend directories found in the list
              file, 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 tar archives.  If a tar archive is generated
              without    directories    this    avoids   problems   with   tar
              implementations found on SYSVr3 and  earlier.   If  used  during
              extract, no intermediate missing directories are created.

       -data-change-warn
              If  the size of a file changes while the file is being archived,
              treat this condition as a warning only that does not cause a non
              zero  exit  code.   A  warning  message  is still written if the
              condition is not otherwise  ignored  by  another  rule  from  an
              errctl=  option.   The  -data-change-warn option works as if the
              last error control option was

                   errctl="WARN|GROW|SHRINK *"

              The -e option or an ABORT entry in a condition set up by errctl=
              has a higher precedence than the -data-change-warn option.  This
              option is ignored in extract or list mode.

       -debug Print debug messages.  Among  other  things,  this  gives  debug
              messages  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 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 the diffopts list
                        i.e.  exclude  all  present  options from an initially
                        complete set 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 permissions. With this option in  effect,
                        star  compares  the  low  order 12 bits of the st_mode
                        field.

              mode      Same as perm.

              symperm   Compare permissions even in case the  target  file  on
                        the  local filesystem is a symbolic link.  By default,
                        star will not compare the permission of symbolic links
                        as  most systems cannot set the permission of symbolic
                        links.  Star compares symperm only if perm is compared
                        also.

              type      Compare  file type.  Note that star cannot compare the
                        file type in case of a hard link.

              nlink     Compare link count on hardlinks.  This only  works  if
                        the  archive  is in exustar format and contains starβ€β€™s
                        dump extensions.

              uid       Compare numerical user id of file.

              gid       Compare numerical group id of file.

              uname     Compare ASCII version of user id of  file.   The  user
                        name is mapped via the file /etc/passwd.

              gname     Compare  ASCII version of group id of file.  The group
                        name is mapped via the file /etc/group.

              id        Shorthand  for:  uid,gid,uname,gname.    Compare   all
                        user/group  related info of file.  Note that this will
                        always find  differences  if  the  source  and  target
                        system use different user or group mappings.

              size      Compare  file size.  Note that star cannot compare the
                        file size in case of a hard link.

              data      Compare content of file.  If star already  found  that
                        the  size of the files differ, it will not compare the
                        content anymore.  If the size  of  the  files  differ,
                        star 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 paths
                        returned by the readlink(2) call.

                        Two symlinks are considered equal, it they either have
                        a characterwise identical link-name, or if they either
                        both use an absolute path name or both use a  relative
                        path  name  and  the  following is true: Both symlinks
                        point to  the  same  file  that  must  exist  or  both
                        pathnames look similar enough.

              sympath   Compare   the   target  pathnames  of  symlinks.  This
                        characterwise compares the strings returned  from  the
                        readlink(2) call.

              sparse    Compare  if  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 the archive format
                        is star, xstar, xustar, exustar, or gnutar.

              atime     Compare access time of file.  This only works with  if
                        the archive format is star, xstar, xustar, exustar, or
                        pax.

              mtime     Compare modification time of file.

              ctime     This only works with if the archive  format  is  star,
                        xstar, xustar, exustar, or pax.

              lmtime    Compare  the modification time even in case the target
                        file on the local filesystem is a symbolic  link.   By
                        default,  star  will not compare the modification time
                        of symbolic links  as  most  systems  cannot  set  the
                        modification  time  of  symbolic links.  Star compares
                        lmtime only if mtime is compared also.

              times     Shorthand for: atime,mtime,ctime.

              dir       Compare the content of directories.  This  only  works
                        if  the  archive  is  in  exustar  format and contains
                        starβ€β€™s  dump  extensions.   Together  with   increased
                        verbose  level  (-vv)  this will print a list of files
                        that are only in the archive and a list of files  that
                        are only on the current filesystem.

              xtimes    Shorthand for: atime,mtime,ctime,lmtime.

              acl       Compare  access control lists.  This only works if the
                        archive is in exustar format and has been created with
                        starβ€β€™s  -acl  option.   You  need  to specify the -acl
                        option in addition when running the diff.

              xattr     Compare extended file attributes.  This only works  if
                        the  archive is in exustar format and has been created
                        with starβ€β€™s -xattr option.  You need  to  specify  the
                        -xattr option in addition when running the diff.

              fflags    Compare  extended  file flags.  This only works if the
                        archive is in exustar format and has been created with
                        starβ€β€™s  -xfflags  option.   You  need  to  specify the
                        -xfflags option in addition when running the diff.

              If optlst starts with a ! the meaning of all members  in  optlst
              is  inverted as with the not optlist member.  In this case, star
              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 compares everything but  the
              access  time  of the files and the modification time of symbolic
              links.

       dir-group=group
              If star extracts archives as root, this option allows to control
              the group id of intermediate directories created by star.

       dir-owner=user
              If star extracts archives as root, this option allows to control
              the owner of intermediate directories created by

       -dirmode
              If in create mode (i.e. when storing  files  to  archive),  star
              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  the  archive  needs  to  be
              extracted  by  an  old  tar  implementation.  If star is used to
              extract an archive that  has  been  created  with  -dirmode  the
              directories  will not get an old time stamp unless the option -U
              is used while extracting the archive.

       -dodesc
              Force star to descend directories found  in  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 system and does not need to use a -C option.
              It has been originally introduced to make it easier to implement
              a  star  version that supports true incremental dumps, but it is
              kept as it gives additional benefits.  Star currently  sets  the
              archive  type  to  exustar  and, in 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 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
              content  of  a  previous  dump  with lower level. If incremental
              dumps  and  restores  are  going  to  be  used  to   synchronize
              filesystem  content,  every  successive  incremental  dump  will
              increase in size if -dump-cumulative is not used.   See  section
              SYNCHRONIZING FILESYSTEMS for more information.

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

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

       -e     Exit  immediately  with  exit  status -3 (253) if any unexpected
              error occurs.  The -e option works as if the last error  control
              option was

                   errctl="ABORT|ALL|DIFF   *"

              This  allows  to  use  the  errctl=  option together with the -e
              option and thus to ignore some error conditions  while  aborting
              on all other conditions.

       errctl= name

       errctl= error control spec
              Add  the content from file name to the error control definitions
              or add error control spec  to  the  error  control  definitions.
              More than one error control file and more than one error control
              spec as well as a mixture of both forms is possible.

              The reason for using error control is to make star  quiet  about
              error  conditions that are known to be irrelevant on the quality
              of the archive or restore run  or  to  tell  star  to  abort  on
              certain  error conditions instead of trying to continue with the
              archive.

              A typical reason to use error control is  to  suppress  warnings
              about  growing  log  files  while  doing a backup on a live file
              system.  Another typical reason to use error control is to  tell
              star  to  abort  if e.g. a file could not be archived instead of
              continuing to archive other files from a list.

              The error control file contains a set of  lines,  each  starting
              with  a list of error conditions to be ignored followed by white
              space followed by a file name pattern.  error control spec  uses
              the  same  syntax  as a single line from the error control file.
              If the file name pattern needs to start with white space, use  a
              backslash  to  escape  the  start  of  the  file name. It is not
              possible to have new line characters in the file  name  pattern.
              Whenever  an  error  situation  is  encountered, star checks the
              lines in the error control file starting from the top.   If  the
              current error condition is listed on a line in the error control
              file, then star checks whether the pattern on the  rest  of  the
              line  matches  the current file name.  If this is the case, star
              uses the current error  control  specification  to  control  the
              current error condition.

              The  list  of error conditions to be handled may use one or more
              (in this case separated by a ’|’ character) identifiers from the
              list below:

              ABORT       If  this  meta  condition  is  included  in an error
                          condition, star aborts (exits) as soon  as  possible
                          after  this error condition has been seen instead of
                          making star quiet about the condition.   This  error
                          condition  flag  may  only  be used together with at
                          another  error  condition  or  a   list   of   error
                          conditions (separated by a ’|’ character).

              WARN        If  this  meta  condition  is  included  in an error
                          condition, star prints the warning about  the  error
                          condition  but  the  error condition does not affect
                          the exit code  of  star  and  the  error  statistics
                          (which  is  printed to the end) does not include the
                          related errors.  This error condition flag may  only
                          be  used together with at another error condition or
                          a list of  error  conditions  (separated  by  a  ’|’
                          character).   The  WARN  meta  condition has a lower
                          precedence than ABORT.

              DIFF        Suppress  output  in  case  that  star   -diff   did
                          encounter any differences.

              ALL         This is a shortcut for all error conditions below.

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

              GETACL      Suppress warnings about  files  on  which  star  had
                          problems to retrieve the ACL information.

              OPEN        Suppress  warnings  about  files  that  could not be
                          opened.

              READ        Suppress warnings read errors on files.

              WRITE       Suppress warnings write errors on files.

              READLINK    Suppress warnings  readlink(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 was
                          unable to archive all hard links.

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

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

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

              GETXATTR    Suppress warnings about files on that star could not
                          retrieve the extended file attribute information.

              SETTIME     Suppress warnings about files on that star could not
                          set the time information during extraction.

              SETMODE     Suppress warnings about files on that star could not
                          set the access 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 names that start with  ’/’  or  have  a  ’/../’
                          sequence   inside   when   -secure-links   has  been
                          specified.  In this case, star tries  to  match  the
                          link  name  against the pattern in the error control
                          file.

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

              BADACL      Suppress warnings  access  control  list  conversion
                          problems.

              SETACL      Suppress warnings about files on that star could not
                          set the ACL information during extraction.

              SETXATTR    Suppress warnings about files on that star could not
                          set  the  extended file attribute information during
                          extraction.

       If a specific error condition is ignored, then the error  condition  is
       not  only  handled  in  a  silent  way but also excluded from the error
       statistics that are printed at the end of the star run.

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

       -exclude-from name
              Exclude from named file, this is an alias for the -X option. See
              -X option for more information.

       -F,-FF ...
              Fast  and  simple  exclude  option for create mode.  With one -F
              argument, star ignores all  directories  called  SCCS  and  RCS.
              With two -F arguments, star in addition ignores all files called
              core errs a.out all files ending with .o.  OBJ/.  With three  -F
              arguments,  star ignores all sub trees starting from a directory
              that includes a file .mirror or .exclude and  all  object  files
              and files called core errs a.out all files ending with .o.  With
              four -F arguments, star ignores all sub trees  starting  from  a
              directory  that  includes  a file .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  in  addition  again  excludes  all  directories
              called SCCS and RCS.

       -fifo  Use  a  fifo to optimize data flow from/to tarfile.  This option
              is in effect by default (it may be  changed  at  compile  time).
              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 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  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 units  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 run when the fifo has
              been in effect.  All options that start with the -f sequence are
              sensitive  to  typo  problems,  see  BUGS   section   for   more
              information.

       file=tarfilename, f=tarfilename
              Use tarfilename as the name for the tar archive. Currently up to
              100 file= options are possible. Specifying more then  one  file=
              option  make  sense in multi volume mode. In this case star will
              use the next name in the list  every  time  a  media  change  is
              needed.   To  make  star  behave consistent with the single file
              case, star loops over the list of  known  archive  files.   Note
              that  if  star is installed suid root and the first tarfile is a
              remote archive, only the connection  to  this  archive  will  be
              created  with  root  privileges.  After this connection has been
              established as root, star switches back to the id of the caller.
              If  any  of  the  other  archives  in  the  list is located on a
              different host, star will not be able to open 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 is in conjunction  with  pipes.   If
              star  is  installed  suid root or if it has been called by root,
              tarfilename may be in remote syntax:  user@host:filename  as  in
              rcp(1)  even  if  invoked by non root users.  See SUID NOTES for
              more information.

              To make a file local although  it  includes  a  colon  (:),  the
              filename must start with: ’€™, ’./’ or ’../’

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

              It is recommended to use the rmt server that  comes  with  star.
              It  is  the  only  rmt  server  that  gives platform independent
              compatibility with BSD, Sun and GNU rmt clients and it  includes
              security  features  that may be set up in /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.

              Note that if file=- has been specified, it is no longer possible
              to use the -find -exec primary.

       -find  This  option  acts a separator.  If it is used, all star options
              must be to the left of the -find option. To  the  right  of  the
              -find option, star accepts the find command line syntax only.

              The  find expression acts as a filter between the source of file
              names and the consumer, which may either be the archiving engine
              or  list/extract  engine.  If  the  find expression evaluated as
              TRUE,  then  the  related  file  is  selected  for   processing,
              otherwise it is omited.

              In  order  to  make  the  evaluation of the find expression more
              convenient, star implements additional find primaries that  have
              side  effects  on  the  file  meta  data.   Star  implements the
              following additional find primaries:

              -chgrp gname
                     The primary always evaluates as true; it sets  the  group
                     of the file to gname.

              -chmod mode
                     The  primary  always  evaluates  as  true;  it  sets  the
                     permissions of the file  to  mode.   Octal  and  symbolic
                     permissions are accepted for mode as with chmod(1).

              -chown uname
                     The  primary  always evaluates as true; it sets the owner
                     of the file to uname.

              -false The primary always evaluates as false; it allows to  make
                     the  result  of  the  full  expression different from the
                     result of a part of the expression.

              -true  The primary always evaluates as true; it allows  to  make
                     the  result  of  the  full  expression different from the
                     result of a part of the expression.

              The command line:

              star -c f=o.tar -find . ( -type d -ls -o false ) -o ! -type d

              lists all directories and archives all  non-directories  to  the
              archive o.tar.

              The command line:

              star -c f=o.tar -find . ( -type d -chown root -o true )

              archives  all  directories so they appear to be owned by root in
              the archive, all non-directories are archived as they are in the
              file system.

              Note  that  the -ls, -exec and the -ok primary cannot be used if
              stdin or stdout has been redirected by  the  list=-  of  by  the
              file=- options.

       -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 this case
              examines  the  content  of the files in 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
              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  will  not  overwrite  files  that  are read only.  If this
              option is in effect, star 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 the incremental dump is
              only  a  partial  dump.  See  -wtardumps,  level=  and   section
              INCREMENTAL 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 /etc/tardumps and
              when  comparing  against  information   in   /etc/tardumps   for
              incremental  backups.   This  makes  sense when backups are made
              using file system snapshots and  allows  /etc/tardumps  and  the
              archive  to  contain the real name of the file system instead of
              the temporary mount 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 option
              H=headertype option may go away in the future even  though  this
              option has been in use by cpio since 1989.

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

       -hardlinks
              In  extract  mode,  this  option  tells  star to try to create a
              hardlink whenever a symlink is encountered in the  archive.   In
              create mode, this option tells star to try to archive a hardlink
              whenever a symlink is encountered in the file 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 with HP-UX tar, this creates  tar  archives  which  violate
              POSIX.1-1988.   This  option is only needed if you like to use a
              POSIX.1-1988  based  archive  format  that  does   not   include
              extensions.   If  you use the xstar format, star will use a base
              256 extension that allows bigger major/minor numbers by default,
              if  you  use  the  xustar  or  the  exustar  format  there is no
              limitation at all as these  formats  use  POSIX.1-2001  extended
              headers to archive the major/minor numbers by default.

       -i     Ignore  checksum  errors  on  tar  headers.   If  this option is
              specified, star will not exit if a header with a bad checksum is
              found but search for the next valid header.

       -install
              Carefully  replace existing files when extracting files. This is
              done similar to install(1) by first extracting the files into  a
              temporary name and renaming the file to the final name after the
              extraction of that file was successful.

              As star by default does not  remove  non-empty  directories,  an
              install  that needs to remove existing non-empty directories may
              also need the options -force-remove and -remove-recursive.

       -j     run the input or output through a bzip2 pipe - 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 you are going to extract
              a compressed archive that is located inside a plain file as star
              will  auto detect compression and choose the right decompression
              option to extract.

       -keep-nonempty-dirs
              Do not complain about trying to remove nonempty  directories  in
              case that -remove-recursive has not been specified.

       -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 tarfile contains a
              more recent version of the corresponding file.

              See SECURITY NOTES for more information.

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

       -l     Do  not  print a warning message if not all links to hard linked
              files could be dumped. This option is evaluated in 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
              star into true incremental dump mode.

              In  true incremental dump mode, a -C option which is followed by
              the name a mount point and a dot  (’.’)  as  starting  directory
              name is required.  Only a single file system may be handled at a
              time.  If the directory following the -C option is not referring
              to  a  root  directory  of  a  file system, the dump is called a
              partial dump.  If the  directory  following  the  -C  option  is
              referring  to  a  root  directory  of a file 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-data
              In  create  mode, include the data for files even if these files
              are hard links. This feature in create mode  is  currently  only
              available  for  the  exustar  archive  format  and  only in case
              -sparse has not been specified.

              In extract mode, allow star to deal with  data  in  hard  linked
              files  even  if  the  standard would not allow this for the used
              archive format.

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

              If  you like to extract a cpio archive that contains hard linked
              directories, you also need to specify -link-dirs in  extract  or
              diff  mode.   This  is  needed because many cpio implementations
              create buggy archives with respect to hard links.  If star would
              look  for  hard linked directories in all cases, it would detect
              many pseudo hard links to directories.  Use -link-dirs with care
              if 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 order to be
              able  to  create  or remove hard links to directories.  For this
              reason its only  recommended  to  use  this  option  when  doing
              accurate   backups  and  when  hard  links  to  directories  are
              expected.

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

       list=filename
              Read filenames for store/create/list/diff command from filename.
              The  file  filename must contain a list of path names, each on a
              separate line.  This option implies the  -D  option.   To  force
              star  to  descend  directories,  use  the -dodesc option in this
              case.  See also the -X option.

              Note that if list=- has been specified, it is no longer possible
              to use the -find -exec primary.

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

       -lzo   run  the  input  or  output  through a lzop pipe - see option -z
              below.

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

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

       -match-tree
              If in 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 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
              systems or contain excessive bad blocks.

       maxsize=#
              Do not store files in tarfile if they are bigger  than  #.   See
              bs=  for  the  possible  syntax.   By  default,  the  number  is
              multiplied by 1024, so the value counts in units 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
              specified  and  not  multiplied by 1024.  See bs= option for all
              possible multipliers.

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

              Warning:  Do  not  try  to extract star archives containing meta
              files using other tar implementations if they are not  aware  of
              the  meta  file extensions of star.  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
              implementations 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 the  POSIX
              standard  that  tells  tar  implementations to treat all unknown
              file types as if 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  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 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 read mode, a hard  EOF  on  input  (if  not
              preceded by a logical EOF) triggers a medium change operation.

              Specifying -multivol tells star to split files across volumes if
              needed.  This way, a virtual archive is created that spans  more
              than one medium.  Multi volume mode is needed whenever it is not
              possible to split  the  archiving  or  extracting  into  several
              logically  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 is not in multi volume
              mode, files cannot be split across volumes.

              When -multivol has been specified in 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
              specified  in  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  advance  (e.g.  tapes   with   build   in
              compression);  it  does  not  work  if  the EOT condition is not
              returned in sync with the  related  write  operation.  For  this
              reason,  it  is  expected  that  data  buffering inside a device
              driver cannot be used.

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

              See tsize=# option for more information.

              Note that -multivol is an interactive option that prevents  star
              from being used in non-interactive environments.  If you like to
              use it in a non-interactive environment,  you  need  to  specify
              new-volume-script=script  in  addition  in order to automate the
              media change procedure.

       newer=filename
              Do not store files to tarfile if their modification time is  not
              newer than the modification time of filename.  See -ctime option
              for changing this behavior.

       -newest
              In conjunction with the list command this  lists  you  only  the
              newest file in tarfile.

       -newest_file
              obsoleted by -newest-file

       -newest-file
              In  conjunction  with  the  list command this lists you only the
              newest regular file in tarfile.

       new-volume-script=script
              Call script at end of each tape if in  multi  volume  mode.   If
              this  option is not in effect, star 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 name.

       -nodump
              If this option is set, star 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 increases by 10%)
              because of the unlucky kernel interface.

       -no-dirslash
              Do not add a slash to the end of directory names if  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
              archive  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 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.
              Currently  the  -fifo  option  is  used as default. (This may be
              changed at compile time.)

       -no-fsync
              Do not call fsync(2) for each file that has been extracted  from
              the  archive.   Using  -no-fsync  may  speed  up  extraction  on
              operating systems with  slow  file  I/O  (such  as  Linux),  but
              includes the risk that star may not be able to detect extraction
              problems that occur after the call to close(2).  A typical cause
              for  such problems is a NFS file system that fills up before the
              buffer cache is synced or a write error 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
              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
              permissions.   This  option  is needed only if star 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 run.

       -no-xheader
              Do not create or extract POSIX.1-2001  extended  headers.   This
              option  may  be  used if you like to read 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
              pattern=pattern  or  pat=pattern  option.  Patterns specified as
              file type arguments will not be affected.

       -notarg, -pax-c
              Match all file or archive members except those specified by  the
              pattern or file 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 the archive then on the
              filesystem).

       -numeric
              Use the numeric user/group fields in the listing rather than the
              default.   The  default  allows  to  list  the  ASCII version of
              user/group of the file 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 is  invoked  with
              this  option, star generates archives which are fully compatible
              with old UNIX tar archives. If in extract mode, star ignores any
              additional  info  in  the  headers.   This  implies neither that
              archives generated  with  this  option  are  binary  equal  with
              archives  generated  by old tar versions nor that star is trying
              to comprehend all bugs that are found in old tar versions.   The
              bug  in  old tar versions that cause a reversal of a space and a
              NULL byte in 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 order
              to  be compatible to very old historic tar archives, you need to
              specify 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
              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 to the archive but  compute  and  add  the
              sizes.   This  is useful when trying to figure out if 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  to  write  a  partial  record  as  the last record.
              Normally, star 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  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 extract mode - star will read up to
              the end of file marker on the tape and the  next  call  to  star
              will read 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
              the  archive and the present umask(2).  If star is called by the
              super user, star behaves as if it has been called  with  the  -p
              option.  See  also -no-p option.  If the archive contains Access
              Control Lists (ACLs) in POSIX.1-2001 extended headers, star will
              restore  the  access control lists from the archive for files if
              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
              length, this is no real limitation.  If more than one pattern is
              specified, a file  matches  if  any  of  the  specified  pattern
              matches.   Patterns  may  be  used  in  create mode to select or
              exclude files from the list of file type arguments or the  files
              located  in  a  sub  tree of a file type argument directory.  By
              default, star  scans  the  whole  directory  tree  underneath  a
              directory  that is in the argument list. This may be modified by
              using the -match-tree option.  In extract or list mode, all file
              type  arguments  are  interpreted  to  be select pattern and all
              option type patterns may be either select  or  exclude  patterns
              depending on the presence or absence of the -not option.  If you
              use file type select patterns, they work exactly like the method
              used  by other (non pattern aware) tar(1) implementations.  File
              type select patterns do not offer pattern matching but allow  to
              restore  subtrees.   To  extract  a  complete  sub tree from the
              directory dir with star using the pattern= option, use  pattern=
              dir/\*  if  you  like  to select a subtree by using the historic
              method, use dir as file type argument.   If  you  only  like  to
              extract  the  directory  itself, use dir/ as file 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 patterns, use the -not or the -V option.

       pkglist=file
              This is (for now) an internal interface for  the  Schily  Source
              Package  System (sps).  It only works in create mode and behaves
              similar to the list= option, but  it  allows  to  overwrite  the
              permissions,  the  uid  and  gid  values from the content of the
              pkglist= file.  Each line from the pkglist= file contains a file
              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 or archive members except those specified by the
              pattern or file operands.

       -pax-H Follow symbolic links that have been encountered on the  command
              line.    If  the  referenced  file  does  not  exist,  the  file
              information and type will be for the link itself.  If  the  link
              is  referencing  a  file  type  that cannot be archived with the
              current archive format, the file information and  type  will  be
              for the link itself.

       -pax-i Do interactive renaming in 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 is skipped.  If
              you type ’.’, then the original file name is retained.   If  you
              type anything else, then this is taken as the new file name.

              Note  that  -pax-i  is  an interactive option that prevents star
              from being used in non-interactive environments.

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

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

       -pax-match
              Allow   file   type   arguments  to  be  recognised  as  regular
              expressions in 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
              PAX  style  privileges string.  Several characters (each has its
              own meaning). The following characters are defined:

              a      Do not  preserve  file  access  times.   This  option  is
                     currently ignored.

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

              m      Do  not  preserve  file  modification  times.   This   is
                     currently equivalent to calling star -m.

              o      Preserve  the  user ID and group ID.  This is the default
                     for star if called as root.

              p      Preserve the file  mode  bits.   This  is  equivalent  to
                     calling star -p.

       -prinodes
              Print inode numbers in verbose list mode if the archive contains
              inode numbers.

       -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 names from the file 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 either newer versions are present in
              the archive or if 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  effect,
              star  will  remove  files  before  extracting  a  file  from the
              archive.  This is needed if you want to change the file type  or
              if  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 is permitted,
              star will only remove files, specials and empty directories.  If
              this  option  is  in effect, star will be allowed to recursively
              removes non empty directories too.

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

              Note: Do not use the -restore option if you only like to restore
              a single file or a list of selected files.

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

       -s replstr
              Modify file or archive member names named 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
              may  contain  the  special  character  ’&’. The character ’&’ is
              substituted by the string 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
              substitute  option  has  been specified, star will loop over all
              substitute patterns until one matches.

              If the name  substitutes  to  the  empty  string,  the  file  is
              skipped.

       -secure-links
              Do  not  extract  hard  links or symbolic links if the link name
              (the target of the link) starts with a slash (/) or if  /../  is
              contained  in the link 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
              -secure-links checking would be done by default, star makes link
              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 run, all files
              and links have been extracted.  If you get a warning, you should
              unpack  the archive a second time and specify the options -k, -w
              and -nowarn in 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 is compiled
              to use mapped /dev/zero pages for the  fifo,  if  the  operating
              system supports this.  If star is compiled to have both code for
              mapped pages and for System  V  shared  memory,  star  will  use
              shared memory instead of the default.  If the -help menu doesn’t
              show the -shm flag you have no  choice.   When  using  System  V
              shared memory, you may have to raise the system’s internal limit
              for shared memory resources to  get  enough  shared  memory  for
              star.

       -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 this way.  Note: Only filenames and
              linknames containing chars with the most significant bit set 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 the archive format
              is tar, ustar, suntar, pax, or any cpio variant.  On Solaris-2.3
              ...  Solaris-2.5.1 there is a special ioctl() called _FIOAI that
              allows root to get the allocation  info  more  efficiently.   On
              Solaris  11  there  is an enhanced lseek(2) call with addidional
              whence values SEEK_HOLE and SEEK_DATA that allow to  find  holes
              in  an  efficient  way.  Other operating systems lack support to
              get the real allocation list and force star to scan the files to
              look  for  blocks  that  only contain null characters.  This may
              star cause to assume more holes to be present  than  the  number
              that the file really contains.

       -symlinks
              This  option  tells  star  in  extract  mode  to try to create a
              symlink whenever a hardlink is encountered in the archive.

       -T     If the option file= or f=  is  omitted  and  the  -T  option  is
              present,  star  will  use  the  device  indicated  by  the  TAPE
              environment variable, if set.

       tardumps=name
              Set the file name for tar dump  dates  database  to  name.   The
              default  name  is  /etc/tardumps.   Use  in combination with the
              level= option  to  create  true  incremental  dumps.   See  also
              -wtardumps  option  and  section  INCREMENTAL  BACKUPS  for more
              information.

       -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  the
              archive.   This  may be used in shell scripts to generate a name
              list.  If used together with the -diff option,  star  will  only
              print  the names of the files that differ.  A second run of star
              may then be used to restore all files that  had  differences  to
              the  archive.   Use  the list= option to specify the namelist in
              this case.

       tsize=#
              Set tape volume size to # to enable multi volume  tape  support.
              The  value  refers to the archive size without compression.  See
              bs=  for  the  possible  syntax.   By  default,  the  number  is
              multiplied  by  512,  so  the  value counts in units 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  effect, star is able to archive filesystems that are
              bigger then the  tape  size.   If  the  option  tsize=#  without
              -multivol  then  no  file  will be split across volumes and each
              volume may in theory be read back separately.  Files that do not
              fit  on  a  single  tape  may  not  be  stored in this mode.  If
              -multivol has been specified in addition, star will split  files
              when  the  maximum  allowed  tape size has been reached.  If the
              tape volume size is not a multiple 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  from
              the archive will not replace a corresponding newer file on disk.

       umask=mask
              Set  starβ€β€™s  umask  to  mask.   This  allows  to   control   the
              permissions  for  intermediate  directories  that are created by
              star in extract mode.  See also -p option.

       -v     Increment verbose level by one.  This normally results  in  more
              output during operation.  See also in the description for the -t
              flag.  Normally, star does its work silently.   If  the  verbose
              level  is  2  or more and star is in create or update mode, star
              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
              pattern=pattern  or  pat=pattern  option.  Patterns specified as
              file type arguments will not be affected.

       -version
              Print version information and exit.

       VOLHDR=name
              Use name to generate a volume header.

       -w     Do interactive creation, extraction or renaming.  For every file
              that  matches  the  list  of patterns and that has a more recent
              modification time in the tar archive (if in extract mode and the
              -U option is not specified) star 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 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 star  is
              in  extract  mode  or  for the archive name if star is in create
              mode.

       See SECURITY NOTES for more information.

       Note that -w is an interactive option that  prevents  star  from  being
       used in non-interactive environments.

       -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  the
              SunOS/Solaris  st  device  driver.  This  driver has problems to
              sense  the  loading  time  with  Exabyte  drives  with   factory
              settings.  It also makes sense to use -wready if multiple remote
              backups are made. In this case, the remote connection is  closed
              while  the  remote tape server is still writing a file mark.  If
              another remote backup is initiated before the old remote  server
              did  finish  to  write  the file mark, it would be impossible to
              open the tape driver unless -wready is specified to tell star to
              wait for the drive to become ready again.

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

       -X filename
              Use  the file filename as a file containing a list of path names
              to be excluded from the store/create/list/diff  operation.   The
              file  filename  must  contain  a  list  of path names, each on a
              separate line.  Be careful with white space and note  that  path
              names  in  the  list  may  not  contain  new lines.  Multiple -X
              options may  be  used.  Each  argument  must  refer  to  a  file
              containing  path  names.   The  -X  option has precedence before
              other options that select files to be included in the operation.
              See also list= option.

       -xattr

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

              The method used in the current implementation could be  used  to
              store  and  extract extended file attributes from BSD too.  Note
              that the current implementation is not generic enough  to  cover
              more general extended file attribute implementations as found on
              Solaris.  If star starts  to  implement  a  method  that  covers
              extended file 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 the future.

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

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

       -xdir  Extract directories even if 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
              in  any  case.   As  the  classical  UNIX  cpio program does not
              implement delayed directory permission and time  stamp  setting,
              cpio  users  often create archives in reverse order (directories
              past their content). For this reason,  it  makes  sense  to  use
              -xdir while extracting cpio archives.

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

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

       -xmeta Extract meta files  as  if  they  were  files.   Meta  files  in
              archives are plain files that do not contain any content data in
              the archive.  They may be created by using the -meta  option  in
              starβ€β€™s  create  mode.   Existing files are not overwritten. In a
              file is missing, a zero sized files is created.

       -Z     run the input or output through a compress pipe - 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 it is a file.  No reblocking
              will be done, so this option will currently only make  sense  on
              plain files.  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 you are going to extract a
              compressed archive that is located inside a plain file  as  star
              will  auto detect compression and choose the right decompression
              option to extract.  The environment variable  STAR_COMPRESS_FLAG
              may  be  used  to  specify  one option for gzip.  If you want to
              write write compressed archives to tape, you should use
              star -c . | gzip | sdd ibs=4k obs=32k -fill of=/dev/rmt/1bn
              or
              star  -c  .  |  gzip  |  sdd  ibs=4k  obs=32k  -fill  ovsize=60m
              of=/dev/rmt/1bn
              if the tape can hold 60 MB.

INCREMENTAL BACKUPS

       Star  is  able to back up file system in full and incremental mode.  To
       allow  incremental  backups,  the  file  system  must  implement  POSIX
       semantics.

       To be more verbose:

       Β·      The  filesystem  needs  to  uniquely  identify  files by the two
              numbers st_dev (The device ID of the device containing the file)
              and  st_ino  (The  file  serial  number).  If a file is renamed,
              these numbers need to be retained.  Both numbers need  to  be  a
              cardinal scalar that is expressible in a decimal number.

       Β·      The  filesystem  needs  to  implement  at least two time stamps,
              st_mtime the file’s last  modification  time  and  st_ctime  the
              file’s  last  status  change  time.  Both time stamps need to be
              dealt with as documented by the POSIX  standard.   Both  numbers
              need  to  be  a cardinal scalar that is expressible in a decimal
              number.

       Β·      The filesystem needs to allow to rename files and directories by
              either calling rename(2), or link(2) and unlink(2).

       Β·      The  filesystem  needs  to  honor  and preserve the case of file
              names.

       The incremental backup method used by star  depends  on  comparing  the
       time stamps of all files against the time of the last backup. Note that
       this method only works correctly if the level 0 backup and  all  higher
       level incrementals include the whole file system.  As star archives all
       inode meta data, star is able to detect renamed files by comparing  the
       inode numbers of all files while in incremental restore mode.

       Detecting renamed files only works if star, while in backup mode, scans
       the whole file system tree for each full and incremental backup.   This
       will work in case no files are excluded and the dump starts at the root
       directory of a file 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 a complete  directory  sub  tree  is
       excluded  (e.g. by using the pat= option) or if a partial backup starts
       at a sub directory that is not the root directory of the file system.

       To create a level 0 dump call:

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

       To create a level 1 dump call:

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

       Do not forget the dot at the end of the command line that specifies the
       directory to start the operation.

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

       If the system that is going to be backed up is not  acting  as  a  file
       server,  it  makes  sense  to shut down all services that may result in
       inconsistent file states before setting  up  the  filesystem  snapshot.
       After  the  filesystem  snapshot  has  been set up, the services may be
       restarted.

       If the the system that is going to be backed up is  acting  as  a  file
       server,  it  may  be that services on remote clients cause inconsistent
       file states unless all such services that  remotely  access  files  are
       shut down before the snapshot is set up.

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

       echo > /tmp/snapstamp

       mount -r β€β€˜fssnap -F ufs -o \
           backing-store=/var/tmp/EXPORT-NFS.snap /export/nfsβ€β€˜ /mnt

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

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

       Note  that  if  the  backup  is  done  on a live file system, it may be
       unreliable. A typical problem problem in  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 up a star
       error  control  file  (see  errctl=  option) and to tell star 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 and takes a lot of tape,
       it is  wise  to  make  higher  level  incremental  dumps  with  shorter
       intervals.   The next table shows a dump level list that may be used if
       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 10 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 this case, 7 dumps need to be  restored  if  the  a  crash
       happens  at  the worst case date (just before the Friday dump in week 2
       or later).

INCREMENTAL RESTORES

       Incremental restores should be made to an empty file system (except for
       the  lost+found  directory).   Star  is  currently  unable  to  perform
       incremental restores to  a  file  system  that  contains  active  mount
       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 week 2 is restored.

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

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

       To extract a level 0 dump call:

       cd /filestem-mount-point
       star -xpU -restore f=archive-name

       This creates the directory star-tmpdir and the  database  star-symtable
       in the root directory of the new file 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 -xpU -restore f=archive-name

       Note that the environment variable STAR_DEBUG  exists,  star  does  not
       remove  files  with  link  count  1  that  have  been  removed  between
       incremental 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 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 -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
           -C /filestem-mount-point . | \
           star -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 -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
           -cumulative -C /filestem-mount-point . | \
           star -xpU -restore -C /extract-target-dir

       Note that like with backups in general, copies from a  live  filesystem
       should  be  avoided.   On  operating  systems  that support file system
       snapshots, copies should be made from a read-only mount 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 case file system snapshots are used.

SIGNALS

       If star handles a signal, 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 prints statistics and exits.  If in
                 create mode i.e. storing files to archive, star finishes with
                 the current file to ensure that no partial file is written to
                 the archive, write 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 prints statistics and continues
                 with the current operation.  This  is  useful  to  watch  the
                 progress of the current operation.

EXIT STATUS

       The following exit values are returned:

       0      All files were processed successfully.

       -3 / 253
              Star  has  been called with the option -e, or the errctl= option
              has been used to mark the current error fatal.

       -2 / 254
              One or more files could not be processed successfully.

       -1 / 255
              Command line parsing error.

       >0     Other positive exit codes: The errno of the call that caused the
              fatal error.

EXAMPLES

       To get a listing in a way similar to ls -l one might use:

              example% star -tv f=/dev/rmt/1bn

       The  same  command  as  listed above in a POSIX tar command line syntax
       compliant way is:

              example% star tvf /dev/rmt/1mbn

       To copy the directory tree in /home/someuser to the directory  /home/fs
       use:

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

       or by using the change directory option of star:

              example% star -c -C /home/someuser . | star -xp -C /home/fs

       Note  that  both  examples  above  are  not  the  optimum way to copy a
       directory tree. A more efficient way to copy a directory tree is to use
       the -copy option.

              example% star -copy -p -xdot -C /home/someuser . /home/fs

       To  copy  a file tree including the Access Control List entries for all
       files and to correctly copy sparse (holey) files use:

              example% star -copy -p -xdot -acl -sparse -C /home/someuser . /home/fs

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

              example% star -diff -v f=/dev/rmt/1bn

       To compare two directory trees one might use:

              example% star -c . | star -C todir -diff -v diffopts=!times

       or better by using a method similar to the -copy method above:

              example% star -c -diff -v diffopts=!times -C fromdir . todir

       To compare all properties of two file trees, use:

              example% star -c -diff -vv -dump -acl -sparse -C fromdir . todir

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

              example% star -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 -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
       only filesystem e.g. a CD while having the shell’s working directory on
       the CD one might use:

              example% star -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 -c list=- f=/dev/rmt/1bn

       Note that this does not work if the file names from output of the  find
       command include new line characters.

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

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

       Pat,  in this case should match the tarfile in 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 -cM fs=128m bs=63k f=tape@remotehost:/dev/rmt/1bn .

       You need a line in /etc/passwd like the following to enable this:

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

       And  a  .rhosts  file in /etc/tapehome to allow remote connections from
       the appropriate hosts.  Make sure that the file /etc/default/rmt exists
       and allows remote access to the requested tape drive.

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

              example#  env   RSH=/usr/bin/ssh   star   -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 /filesys
              example# cd /filesys
              example# star -xpk f=/dev/rmt/1bn
              example# mt -f /dev/rmt/1bn rewind
              example# star -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 -diff -tpath diffopts=!times f=/dev/rmt/1bn

       If you are looking for files  that  changed  the  type  or  the  access
       permission because this is a common case on still corrupted files, use:

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

       If you like to archive all  directories  only  that  are  part  of  the
       directory tree under ".", use:

              example# star -c f=archive-name -find . -type d

       If  you like to archive all files as owner root and group root and make
       all files world readable in the archive, use:

              example# star -c f=archive-name -find . -chown root -chgrp  root
              -chmod o+r

       If  you  like  to  list all files in an archive in a way like sfind(1),
       instead of the way used by star, use:

              example# star -t f=archive-name -find . -ls -false

ENVIRONMENT

       STAR_COMPRESS_FLAG
              If you like star to always  create  compressed  files  that  use
              maximum  compression,  you  may  set  the  environment  variable
              STAR_COMPRESS_FLAG to -9.

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

       STAR_FIFOSIZE
              If  you  like  to by default let star use a different fifo size,
              set this environment variable to the desired size.

       TAPE   Unlike  other  tar(1)  implementations,  star  defaults  to  use
              stdin/stdout  for the archive.  If you like star to use the file
              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  to  create  a  pipe  to  the  rsh(1)
              program and disallows star to directly access the network socket
              to the remote server.   This  makes  it  impossible  to  set  up
              performance 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
              you  log in using an account that has been created with a remote
              tape server program as login shell.

FILES

       /etc/default/star
              Default  values  can  be  set  for  the  following  options   in
              /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 /etc/default/star allows to
                     overwrite global values from backup scripts for  machines
                     with less memory.

              archive0=

              archive1=

              archive2=

              archive3=

              archive4=

              archive5=

              archive6=

              archive7=
                     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.
                     archive0=/dev/tape).   The  second is the blocking factor
                     in 512 byte units.  The third is the maximum  media  size
                     in 1024 byte units.  If this entry contains a 0, then the
                     media size is unlimited.  The fourth entry  is  optional.
                     If it 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 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 is written or updated when -wtardumps is used.

              The file holds one or more lines, each specifying a  dump  level
              entry.   Each  dump  level  entry starts with a mount point name
              followed by a TAB and  one  or  more  spaces,  followed  by  the
              decimal 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 itself includes the decimal representation of the
              UTC seconds since Jan 01 1970, a space  and  the  textual  local
              time representation of the dump time.

              The  numerical  decimal dump time representation may be followed
              by a dot and  a  sub  second  value.   The  textual  local  time
              representation  is  for informational use by humans only and not
              evaluated by star.

       ./star-symtable
              Contains a database that is needed in incremental restore  mode.

       ./star-symdump
              Contains  an intermediate dump of restore database after a fatal
              error condition was met during an incremental restore operation.

       ./star-tmpdir
              Is  the  temporary  directory  that is used as intermediate file
              storage by star if in incremental restore mode.

       ./star-lock
              Is a lock  file  created  by  star  when  doing  an  incremental
              restore.  If this file is present, it prevents star from running
              another incremental restore operation. This helps to avoid  more
              than  one restore operation at a time (e.g. from a cron script).

       /dev/tty
              Is used for the intercative user interface.

SEE ALSO

       spax(1), suntar(1), scpio(1),  tar(1),  cpio(1),  pax(1),  rcp(1),  mt-
       star(1),   rmt-star(1),   match(1),   dd(1),  sdd(1),  rsh(1),  ssh(1),
       star(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 partial records  and
       the total amount of data in KBytes.

       star: Total time x.yyysec (z kBytes/sec)

       The time used and the transfer speed from/to the archive.

       If there have been non fatal errors during the archive processing, star
       will display a delayed error summary before exiting.

NOTES

       The command line syntax for the tar command  (as  defined  in  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 options separately or
       combined (in case of  boolean  flags),  the  tar  command  line  syntax
       requires  all options to be combined into a single string 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
       command.   If  you  believe that you found a bug in the way star parses
       the command line, please first check your command line for  correctness
       before you make a bug report for star.

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

       Star strips leading ./ sequences from pathnames. This lets star in 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
              prefix field (155 chars) produce the pathname of the file.  When
              recreating   the   original   filename,   name  and  prefix  are
              concatenated, using a  slash  character  in  the  middle.  If  a
              pathname  does not fit in the space provided or may not be split
              at a slash character so that the parts will fit into 100  +  155
              chars,  the file may not be archived.  Linknames longer than 100
              chars may not be archived too.

       The star, xstar, xustar, exustar, pax, and gnutar archive formats don’t
       have  these  limitations.  While  gnutar  uses  a  method that makes it
       impossible for other  tar  implementations  (except  star)  to  restore
       filenames  that  are  longer than 100 chars, the xstar, xustar, exustar
       and pax archive format  uses  a  method  that  allows  an  POSIX.1-1988
       compliant  way  of  storing  filenames, if the POSIX method would allow
       this.  When the archive 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 the archive contains pathnames or linknames of
       exactly 100 chars length.

       Star adds a tar signature in the last four bytes of each tar header  if
       the  archive format is star or xstar.  This is no problem with the star
       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  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 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 signature
       because Sun expects an octal number at the beginning  of  the  12  byte
       field which is a null character in the star 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 differs, whether the fifo is in effect
       or not.  If the fifo is not used, star stops reading the archive if  it
       encounters  a  logical EOF record in the archive.  If the fifo is used,
       star may read until the fifo is full or until the real EOF mark on tape
       is reached.  How much data star actually reads depends on the time when
       the star foreground  process  sends  a  fifo  shutdown  signal  to  the
       background fifo read 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 tar
       archives with a blocksize greater than 10 kBytes.

       The method of storing sparse files currently used  with  the  star  and
       xstar  format  is  not guaranteed to be used in later versions of star.
       If the author decides to change this method, later versions of star may
       not  be  able  to  restore  sparse  files from tar archives made by the
       current version of star.

       Some tar implementations violate the standard in using only  the  first
       500   Bytes   of   the  header  for  checksum  computation.  These  tar
       implementations will not accept star and xstar type tar archives.

       Sun’s Solaris 2.x tar implementation violates the Posix  standard.  Tar
       archives  generated  by  star  cause Sun’s tar to print tar: impossible
       file 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 a way that prevents other tar
       implementations to read 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  implements  compression  via  a  temporary  file.   Using
       compression thus is limited by the maximum file size and the  available
       disk space.

       The  extended  file flags implementation (see -xfflags option) on Linux
       is buggy by design.  In order to retrieve the needed information, every
       file  needs  to be opened.  If the /dev directory is included in 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 a non empty directory, any file in that
       directory may be overwritten unless you specify the -k option.  If  the
       archive  contains symbolic links or hard links, star may even overwrite
       files outside the  current  directory.   If  the  directory  where  the
       archive  is  been  unpacked is not empty and contains contains symbolic
       links or hard links to directories outside  that  directory,  star  may
       also  overwrite  files  outside  the  current directory.  As many other
       commands, star usually has all possible permissions when run  as  root.
       Unpacking  archives  as root thus may have fatal results to any file on
       your system.  Be very careful when you try to extract an  archive  that
       has  not been created by you. It is possible to create hand crafted tar
       archives that may overwrite critical files (like /etc/passwd)  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 type arguments may be critical.

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

SUID NOTES

       If  star  is  installed  suid root, star 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  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  case
       the  environment RSH has been set to ssh).  Note that in 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  is  running  on  a large file aware platform, star is able to
       handle files up to 8 GB in a mode that is compliant to the POSIX.1-1988
       ustar format. With a nonstandard star 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  a  way  that  is
       compatible  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 from using
       filenames like e.g.  ifo using the traditional way where  the  filename
       directly  follows  the  string  -f without any space between the option
       name and the file name.  However, there is no problem  to  use  a  file
       named  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 is created as a result of the mistyped option.

       There is currently no way to set the fifo lowwater and highwater marks.

       There is currently no way to automatically delete files in  the  target
       file  tree  if  they  are  obsolete.   Star  should implement something
       similar to gnutar’s dumpdirs.

       If not invoked by the super user star may not be able to extract  files
       if they reside in read only directories.

       Star is not able to make a complete backup of a filesystem if files are
       hidden by a mount that is in effect on a directory of this  filesystem.
       This may be avoided in case of the ufs filesystem if the backup is made
       off a ufs snapshot (see the man page for fssnap(1m) It could be avoided
       for  any filesystem if 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 handling correctly:

       rsh    on SunOS-5.0...SunOS-5.9

       ssh    from ssh.com

       ssh    from openssh.org

       Sun  already  did  accept  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 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 1982 to extract tapes on a  UNIX  clone  that
       had  no  tar  command.   In 1985 the first fully functional version has
       been released as mtar.

       When the old star format extensions have been introduced  in  1985,  it
       was   renamed  to  star  (Schily  tar).   In  1994,  Posix  1003.1-1988
       extensions were added and star was renamed to star (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