star



STAR(1)                     Schily´s USER COMMANDS                     STAR(1)




NAME

       star - unique standard tape archiver


SYNOPSIS

       star  command [ options ] file1 ... filen
       ustar command [ options ] file1 ... filen
       tar   command [ options ] file1 ... filen
       star  -copy   [ options ] file1 ... directory


DESCRIPTION

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

       Star archives and extracts multiple files to and  from  a  single  file
       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.

       Stars  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  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 resolu-
       tion, files of arbitrary size and filenames without  length  limitation
       using UNICODE UTF-8 coding for best exchange compatibility.

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

       Star includes a pattern matcher to control the list of files to be pro-
       cessed.  This  gives a convenient interface for archiving and restoring
       complex lists of files. In conjunction with the -w flag it is  easy  to
       merge 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 pat-
       terns (depending on the -V flag).  Have a look at  the  description  of
       the  -C  option to learn how 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 substitu-
       tion in file names.

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

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

       Star deals with all 3 times, available for files on UNIX systems if 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.

       Stars default format (if called as star) is xstar and is as posix com-
       pliant as possible. Enhancements to the standard that  prevent  correct
       extraction  of  single  files when using a different tar implementation
       that is only POSIX.1-1988 compliant may occur,  but  they  only  affect
       single  files with a pathname that is longer than 100+130 chars or when
       archiving sparse files with the -sparse option in  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 typ-
       ical POSIX command and for this reason expects commands and options  to
       start with a single dash (-). In this case, commands and options may be
       specified separately, all boolean or  increment  type  options  may  be
       specified  either  separately  or combined.  For compatibility with GNU
       programs, long options may alternatively start with a double dash.   In
       compatibility  mode  to POSIX tar, star expects commands and options to
       appear as one single string that does not start with a dash.  In  POSIX
       tar  compatibilitx  mode, additional non POSIX options may be specified
       but must appear after the POSIX options and  their  args  and  need  to
       start with a dash.

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

       -copy  Copy named 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 per-
              forms a one pass  directory  tree  compare  instead  of  copying
              files.   The  shorthand  -c -diff instead of -copy -diff is also
              allowed.

              On operating systems with slow file 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 possi-
              ble performance.  Without FIFO, the -copy mode will not work.

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

       -diff  Compare the content and the attributes of  the  files  from  the
              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  stars  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  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 out-
              put.  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  argu-
              ment  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 pat-
       terns 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 cre-
              ate 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 sys-
              tem. 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.

       -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 informa-
              tion 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.  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.   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  Inter-
                        change  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.

                        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  inter-
                        fere  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  other-
                        wise  identical  to  the  xstar  format.   As some tar
                        implementations do not follow the POSIX rules and com-
                        pute  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 dif-
                        ference to the xstar format is that the xustar  format
                        uses POSIX.1-2001 extended headers to overcome limita-
                        tions of the historic tar format while the xstar  for-
                        mat uses proprietary extensions.  The xustar format is
                        the default format when star is called as tar.

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

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

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

              suntar    The extended header format  found  on  Solaris  7/8/9.
                        This  format is similar to the pax format but does not
                        handle atime and ctime and in addition uses ’X’ as the
                        typeflag for the extended headers instead of the stan-
                        dard ’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 for-
                        mat.  It is only present to  make  the  scpio  command
                        SVr4 compliant.

              cpio      The  POSIX.1-1988  cpio format. This format uses octal
                        ascii 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 charac-
                        ters 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  for-
                        mat.

              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 2  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 it’s 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 it’s
                        limited portability.


              All tar archive formats may be interchanged if the archive  con-
              tains  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 Eth-
              ernet, 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 posible 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), block-
              size should not be more than 10 kBytes.  For  POSIX.1-1988  com-
              patibility,  blocksize  should  be  no more than 10 kBytes.  For
              POSIX.1-2001 compatibility, blocksize should  be  no  more  than
              32 kBytes.  Most systems also have a hardware limitation for the
              blocksize, 32 kBytes and 63 kBytes are  common  limits  on  many
              systems.   The upper limit in 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 read-
              ing 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  deter-
              mine  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 ‘*’, multi-
              plication of the two numbers is performed.   Thus  bs=7x8k  will
              specify  a blocksize of 56 kBytes.  Blocksize must be a multiple
              of 512 bytes.  See also the description of  the  blocks=  option
              for  more details on blocksizes.  The option bs= is preferred by
              people who like to use an option that  behaves  similar  to  the
              interface used by dd(1) and sdd(1).

       -bsdchdir
              Switch  the behavior of the C= option to BSD style.  The default
              behavior of star 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  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  cur-
                     rent  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 creat-
              ing  the link.  It helps to extract tar files on systems that do
              not implement hardlinks (e.g. BeOS).

       -copylinks
              This option allows to copy both,  hard-  and  symlinked  targets
              rather  than  creating a link.  It helps to extract tar files on
              systems that do not implement links (e.g. OS/2).  To extract and
              copy  all symlinks correctly, you may need to call star 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 creat-
              ing a symbolic link.  It helps to extract tar files  on  systems
              that  do  not  implement links (e.g. OS/2).  To extract and copy
              all symlinks correctly, you may need to call star twice as  star
              cannot  copy  files that appear in the archive later than a sym-
              link pointing to them.

       -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 used with the extract command and the same archive for-
              mats, this tries to restore even the ctime of a file by generat-
              ing time storms.  You should not do this when in multi user mode
              because this may confuse programs like cron and the news system.
              If used with the create command this changes the behavior of the
              newer=  option.   Star,  in  this case compares the ctime of all
              files to the mtime of the stamp file rather then  comparing  the
              mtimes of both files.

       -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  implementa-
              tions found on SYSVr3 and earlier.

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

       diffopts=optlst
              Comma separated list of diffopts.  Valid members in 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.

              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 stars
                        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  sys-
                        tem 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 value
                        returned by 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 of symbolic  links.   By
                        default,  star  will not compare the modification time
                        of symbolic links as most systems cannot set the modi-
                        fication time of symbolic links.

              times     Shorthand for: atime,mtime,ctime.

              dir       Compare  the  content of directories.  This only works
                        if the archive  is  in  exustar  format  and  contains
                        stars  dump extensions.  Together with increased ver-
                        bose 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.

              acl       Compare access control lists.  This only works if  the
                        archive is in exustar format and has been created with
                        stars -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  stars  -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
                        stars -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.

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

       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.

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

              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  (see  match(1)  or  pat-
              match(3)  for more information).  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 ignores the current error con-
              dition.

              The list of error conditions to be ignored may use one  or  more
              (in this case separated by a ’|’ character) identifiers from the
              list 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  speci-
                          fied.   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  con-
                          trol 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.

       -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  informa-
              tion.

       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 cre-
              ated  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 differ-
              ent 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 file-
              name 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 com-
              patibility 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.

       -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 INCRE-
              MENTAL BACKUPS for more information.

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


       fs-name=mount_point
              Use mount_point when recording information in /etc/tardumps  and
              when  comparing  against information in /etc/tardumps for incre-
              mental 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  tem-
              porary 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  exten-
              sions.   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 speci-
              fied, star will not exit if a header  with  a  bad  checksum  is
              found but search for the next valid header.

       -j     run  the input or output through a bzip2 pipe - 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_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 followed by the -C option is not  refer-
              ring  to a root directory of a file system, the dump is called a
              partial dump.  If the directory followed by  the  -C  option  is
              referring  to  a  root  directory  of a file system and no other
              restrictions apply that exclude certain files from the dump, the
              dump is called a full dump.

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

       -link-dirs
              When in 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 accu-
              rate backups and when hard links to directories are expected.

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

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

       -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 sup-
              port telldir(3)/seekdir(3), star will fail.

       -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 implemen-
              tations unable to find a  valid  filename.  However  when  other
              POSIX.1-2001  aware  tar  implementations come up and don’t know
              about meta files, they will destroy files on disk.

              The problems result from the only current fallback in 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 pre-
              ceded 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 logi-
              cally  independent  tasks.  This  is  true  for e.g. incremental
              dump/restore operations where inode numbers need  to  be  traced
              for the whole task.

              When tsize=# has been specified, but star 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  speci-
              fied 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.

       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.  Cur-
              rently the -fifo option is used as default. (This may be changed
              at compile time.)

       -no-fsync
              Do  not call fsync(2) for each file that has been extracted from
              the archive.  Using -no-fsync may speed up extraction on operat-
              ing 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 permis-
              sions.  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 pat-
              tern=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.   Nor-
              mally,  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 direc-
              tory 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.  See manual page for
              match(1) for more details of the pattern matcher.  All  patterns
              are  selection  patterns  by  default. To make them exclude pat-
              terns, use the -not or the -V option.

       -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  informa-
              tion  and type will be for the link itself.  If the link is ref-
              erencing 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.

       -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 expres-
              sions 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 it’s
              own meaning). The following characters are defined:

              a      Do not preserve file access times.  This option  is  cur-
                     rently 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  cur-
                     rently 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 call-
                     ing star -p.

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

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

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

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

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

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

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

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

       -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 sub-
              stituted 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  sub-
              stitute  option has been specified, star will loop over all sub-
              stitute 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, pax, or suntar.  On Solaris-2.3 ... Solaris-2.5.1
              there is a special ioctl() called _FIOAI that allows root to get
              the allocation info more efficiently.  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 charac-
              ters.  This may star 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  sym-
              link 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 environ-
              ment 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 -wtar-
              dumps option and section INCREMENTAL BACKUPS for  more  informa-
              tion.

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

       -to_stdout
              obsoleted by -to-stdout

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

       -tpath Use this option together with the -t option or with -cv (verbose
              create)  to get only a list of the pathnames of the files in 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.
              See bs= for the possible syntax.  By default, the number is mul-
              tiplied 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 multi-
              ple of the tape block size, the tape  volume  size  is  silently
              rounded  down  to  a  value that is a multiple of the tape block
              size.

              See -multivol option for more information.

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

       -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  pat-
              tern=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.

       -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  tar-
              dumps=name and -C option or INCREMENTAL BACKUPS section for more
              information.

       -xattr

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

              The  method  used in 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.

       -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 extract-
              ing exustar archives as it is based on POSIX.1-2001 extended tar
              headers.  See NOTES section for problems with -xfflags on  Linux
              systems.

       -Z     run  the input or output through a compress pipe - 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.  The environment variable As the -bz the -j the  -Z
              and  the  -z option are non standard, it makes sense to omit the
              -bz the -j the -Z and the -z options inside shell scripts if 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.  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 seman-
       tics.

       The 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 inode numbers.

       Detecting renamed files only works if star 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 .

       Backups  from life 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 cre-
       ated between setting up a snapshot and starting an  incremental  backup
       may  be  missing  from  all  backups unless the dumpdate=name option is
       used.

       Star includes options that help to deal  with  file  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 life file system, it may be  unre-
       liable.  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 con-
       trol file (see erctl= 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 inter-
       vals.  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 9 dumps made between Monday and Friday accumulate all changes
       made within the week. If you don’t like this, use the following  backup
       schedule:

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

       Note that in this case, 7 dumps need to be restored if the a crash hap-
       pens at the worst case date (after 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  incre-
       mental 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 9 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 incremen-
       tal dumps. These files are moved to the directory star-tmpdir.   Before
       you start to extract the next incremental, you need to remove all files
       in star-tmpdir.



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.



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

       To  copy  a file tree including the Access Control List entries for all
       files use:

              example% star -c -Hexustar -acl -C /home/someuser . | star -xp -acl -C /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

       To compare all properties of two file trees, use:

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

       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  per-
       mission because this is a common case on still corrupted files, use:

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



ENVIRONMENT

       STAR_COMPRESS_FLAG
              If you like star to always create compressed files that use max-
              imum compression, you may set the environment variable STAR_COM-
              PRESS_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 incre-
              mental 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) pro-
              gram and disallows star to directly access the network socket to
              the  remote  server.  This makes it impossible to set up perfor-
              mance parameters and slows down the  connection  compared  to  a
              root initiated rcmd(3) connection.

              See BUGS section for more information.

       RMT    If  the  RMT environment is present, the remote tape server will
              not be the program /etc/rmt but the program pointed to  by  RMT.
              Note that the remote tape server program name will be ignored if
              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=

              archive2=

              archive3=

              archive4=

              archive5=

              archive6=

              archive7=

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

                     A  correct  archive?=  line  has  3..4  space   separated
                     entries.    The   first   is   the   device  entry  (e.g.
                     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.
                     It if 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 deci-
              mal dump level, a space and the dump time.

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

              The dump time 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 repre-
              sentation is for informational use by humans only and not evalu-
              ated by star.

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

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

       /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(1),
       rmt(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 com-
       mand.  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  char-
       acters  (  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  pre-
              fix  field  (155  chars)  produce the pathname of the file. When
              recreating the original filename, name and prefix  are  concate-
              nated, using a slash character in 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 impos-
       sible  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  back-
       ground 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 cur-
       rent version of star.

       Some tar implementations violate the standard in using only  the  first
       500 Bytes of the header for checksum computation. These tar implementa-
       tions 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 com-
       pression 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.  As many other commands, star usu-
       ally 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 cre-
       ated 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 han-
       dle  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 com-
       patible with old  tar  implementations  gives  several  problems.   The
       options -fifostats, -force-hole, -force-remove and -fifo interfere with
       the -f option and the fact that they exist prevents  users  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  simi-
       lar 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  exten-
       sions 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



Joerg Schilling                    04/11/01                            STAR(1)

Man(1) output converted with man2html