Star

NAME

star - unique standard tape archiver

SYNOPSIS

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

DESCRIPTION

      Star  is a very fast tar(1) like tape archiver with improved function-
      ality.
      Star archives and extracts multiple files to and from  a  single  file
      called a tarfile.  A tarfile is usually a magnetic tape, but it can be
      any file.  In all cases, appearance of a directory name refers to  the
      files and (recursively) subdirectories of that directory.
      Star’s  actions are controlled by the mandatory command flags from the
      list below.  The way star acts may be modified by additional  options.
      Note  that  unpacking tar archives may be a security risk because star
      may overwrite existing files.  See SECURITY NOTES  for  more  informa-
      tion.

FEATURES

      Star  includes  the first free implementation of POSIX.1-2001 extended
      tar headers. The POSIX.1-2001 extended tar headers define a new  stan-
      dard  way for going beyond the limitations of the historic tar format.
      They allow (among others) to archive all UNIX time stamps in  sub-sec-
      ond  resolution,  files of arbitrary size and filenames without length
      limitation using UNICODE UTF-8 coding for best exchange compatibility.
      Star  by  default uses a fifo to optimize data flow from/to tape. This
      results in a normally streaming tape during  the  whole  backup.   See
      -fifo  and  fs= option to get information on how to find the best fifo
      size.
      Star includes a pattern matcher to control the list  of  files  to  be
      processed. This gives a convenient interface for archiving and restor-
      ing 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 to fetch files from a list of directories
      (in create mode) or to distribute files to a list of  directories  (in
      extract  mode).  A substitute option allows ed(1) like pattern substi-
      tution in file names.
      Star includes an enhanced function that is similar to the find(1) com-
      mand  (see  sfind(1)).   This  allows to use find expressions, even in
      extract or list mode, directly on the  content  on  an  archive.   The
      extensions to find(1) allow to modify the file metadata.
      Star includes a sophisticated diff command. Several diff options allow
      user tailorable functionality.  Star won’t show  you  differences  you
      are not interested in.  Check the diffopts= option for more details.
      Star  has no limitation on filename length. Pathnames and linknames up
      to PATH_MAX (1023 bytes with  old  OS  versions  and  4095 bytes  with
      POSIX.1-2001) may be archived. Later versions may be able to deal with
      longer pathnames.
      Star deals with all 3 times, available for files on  UNIX  systems  if
      the  archive format is either chosen from the star specific formats or
      is a format that uses POSIX.1-2001 extended headers.  This  is  either
      done  in  second resolution by using a star specific POSIX.1-1988 com-
      patible extension or in sub second resolution  by  using  POSIX.1-2001
      extended  headers.   Star  is  able  to  store and restore all 3 times
      (mtime, atime and even ctime). On Solaris 2.x systems, star is able to
      do backups without changing any of the 3 the times.
      If  used  with  the H=ustar option, or if called as ustar or tar while
      the H=headertype option is not used, star is 100% POSIX compliant.
      Star’s default format (if called as star) is xstar  and  is  as  posix
      compliant  as possible. Enhancements to the standard that prevent cor-
      rect extraction of single files when using a different tar implementa-
      tion  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 miss-
      ing files automatically.  Use then star -diff to check for differences
      (see EXAMPLES for more information).
      Star automatically recognizes the type of the archive.  Star therefore
      is able to handle features and properties of different  archive  types
      in  their  native  mode,  if  it  knows about the peculiarities of the
      archive type.  See the H=headertype option for more  details.   To  be
      able  to  do this, star adds hidden fingerprints to the archive header
      that allows to recognise all star specific archive  formats.  The  GNU
      tar format is recognised by the way it deviates from the standard.
      Star automatically recognizes and handles byte swapped archives. There
      is no option to manually control byte swapping.
      Star automatically recognizes and handles compressed  archives  inside
      plain files.
      Star  is  able  to  archive and restore Access Control Lists for files
      using POSIX.1-2001 extended headers.

COMMAND

      In native mode, star is compatible to the command  line  syntax  of  a
      typical POSIX command and for this reason expects commands and options
      to start with a single dash (-). In this case,  commands  and  options
      may be specified separately, all boolean or increment type options may
      be specified either separately or combined.   For  compatibility  with
      GNU programs, long options may alternatively start with a double dash.
      In compatibility mode to POSIX tar, star expects commands and  options
      to  appear  as  one single string that does not start with a dash.  In
      POSIX tar compatibility mode, additional  non  POSIX  options  may  be
      specified  but  must appear after the POSIX options and their args and
      need to start with a dash.
      -c     Create a new tarfile and write named files  into  it.   Writing
             starts at the beginning of tarfile.  See -v option for 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 pos-
             sible performance.  Without FIFO, the -copy mode will not work.
             The  list= option, patterns and substitutions apply only to the
             create side of the copy command.
      -diff  Compare the content and the attributes of the  files  from  the
             archive in tarfile to the filesystem.  This may also be used to
             compare two file trees in the filesystem.  If you use a set  of
             diffopts that fits your needs, it will give - in many cases - a
             more readable output than diff -r.   If  you  use  star’s  dump
             extensions for the tar archive, the -diff option allows to find
             even if the directory in the file tree contains more files than
             the archive. This way, it is possible to compare all properties
             of two file trees in one run.  See diffopts for  more  details.
             Adding one or more -v options increases the verbosity. With -vv
             and above, the directory content is compared also if  in  -dump
             mode.
      -n     No  extraction. Show what star would do, in case the -x command
             had been specified.
      -r     Replace files in a tarfile.  The named files are written to the
             end of tarfile.  This implies that later, the appropriate files
             will be found more than once on the tarfile.
      -t     Table of contents.  List the contents of the tarfile.   If  the
             -v  flag is used, the listing is similar to the format of ls -l
             output.  With this option, the flags -a, -atime and -ctime have
             a  different  meaning if the archive is in star, xstar, xustar,
             exustar, or pax format.  The option  -a  or  -atime  lists  the
             access time instead of the modification time, the option -ctime
             lists the file creation time instead of the modification  time.
             The  option -tpath may be used in addition to modify the output
             so it may be used in shell scripts.
      -u     Update a tarfile.  The named files are written to  the  end  of
             tarfile if they are not already there or if the files are newer
             than the files of the same name found in the archive.   The  -r
             and  -u command only work if the tar archives is a regular file
             or if the tar archive is an unblocked tape that may  backspace.
      -x     Extract the named files from the tarfile.  If no filename 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  com-
      mands 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  usu-
             ally a bad idea.  With other tar implementations, they may pos-
             sibly never be extracted  without  clobbering  existing  files.
             Star  for  that  reason, by default strips leading slashes from
             filenames when in extract mode.  As it  may  be  impossible  to
             create  an  archive  where  leading  slashes have been stripped
             while retaining correct path names, star does not strip leading
             slashes in create mode.
             See SECURITY NOTES for more information.
      -..    Don’t  skip  files  that contain /../ in the name. Tar archives
             containing names with /../ could be used to compromise the 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  (if
                       -sparse  is  used).   This format is able to copy the
                       device nodes on HP-UX that have 24 bits in the  minor
                       device  number,  which  is more then the 21 bits that
                       are possible with the POSIX-1003.1-1988 archive  for-
                       mat.
                       The  nonstandard  extensions are located in the space
                       between the link name and the POSIX file name prefix.
                       As the star format does not use a POSIX magic string,
                       the extensions do not interfere with  the  POSIX  tar
                       formats.   The last 4 bytes of the tar header contain
                       a ’tar\0’ signature.
             gnutar    This is a commonly used, but unfortunately not  Posix
                       compliant  (although designed after 1987) enhancement
                       to the old tar format.  The gnutar  format  has  been
                       defined between 1989 and 1994.  Do not use the gnutar
                       archive format unless you want to create  an  archive
                       for  a  target  system that is known to have only the
                       gnutar program available.  The gnutar archive  format
                       violates  basic rules for any (even the historic) tar
                       archive format, in  special  when  sparse  files  are
                       archived  using the -sparse option.  Using the gnutar
                       archive format causes a high risk that the  resulting
                       archive  may  only be read by gnutar or by star.  The
                       implementation of the gnutar  archive  format  within
                       star  is not complete, but sufficient for most gnutar
                       archives.  See NOTES for more information.
             ustar     IEEE/Posix1003/IEC-9945-1-1988 Standard  Data  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  compati-
                       ble   enhancement  of  the  IEEE/Posix1003/IEC-9945-1
                       Standard Data Interchange format.   It  allows  among
                       others  very long filenames (100+130 chars and above)
                       and records access time and  creation  time.   Sparse
                       files  will  be  archived  correctly  (if  -sparse is
                       used).
                       The access time and creation time are stored  at  the
                       end  of  the  POSIX file name prefix (this limits the
                       prefix to 130 chars).  These extensions do not 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
                       compute  the  checksum for less than 512 bytes of the
                       tar header, this format may help  to  avoid  problems
                       with  these  broken  tar  implementations.   The main
                       other difference to the xstar format is that the xus-
                       tar  format  uses  POSIX.1-2001  extended  headers to
                       overcome limitations of the historic tar format while
                       the  xstar  format  uses proprietary extensions.  The
                       xustar format is the  default  format  when  star  is
                       called as tar.
                       File  size  is  unlimited,  uid/gid/uname/gidname  is
                       unlimited, major/minor is  unlimited.   Sparse  files
                       will be archived correctly (if -sparse is used).
             exustar   A format similar to the xustar format but with forced
                       POSIX.1-2001 extended headers.   If  this  format  is
                       used  together  with  the  -acl  option, star records
                       Access Control Lists (ACLs) in POSIX.1-2001  extended
                       headers.
                       The  exustar  format allows to archive all file types
                       but it does not archive more  than  the  POSIX.1-1988
                       set  by  default.   If the -dump option is used or if
                       star is otherwise on dump  mode,  star  archives  all
                       file  types  and  in addition archives more meta data
                       then usual.
                       File  size  is  unlimited,  uid/gid/uname/gidname  is
                       unlimited,  major/minor  is  unlimited.  Sparse files
                       will be archived correctly (if -sparse is used).
             suntar    The extended header format found  on  Solaris  7/8/9.
                       This format is similar to the pax format but does not
                       handle atime and ctime and in addition  uses  ’X’  as
                       the  typeflag for the extended headers instead of the
                       standard ’x’.
                       File  size  is  unlimited,  uid/gid/uname/gidname  is
                       unlimited,  major/minor  is  unlimited.  Sparse files
                       will be filled up with zeroes.
             bin       The cpio UNIX V7 binary format.   This  is  a  format
                       with big interoperability problems. Try to avoid this
                       format.  It is only present to make the scpio command
                       SVr4 compliant.
             cpio      The  POSIX.1-1988 cpio format. This format uses octal
                       ascii headers. A similar format is created by calling
                       cpio  -o -c on pre SYSVr4 systems and by calling cpio
                       -o -Hodc on SYSVr4 systems.   The  POSIX.1-1988  cpio
                       format allows a file name length up to 262142 charac-
                       ters and allows to  archive  nearly  any  file  type.
                       File  size is limited to 8 GB, uid/gid/st_dev is lim-
                       ited to 262143.  The way major and minor device  num-
                       bers  are stored inside the st_dev field is implemen-
                       tation dependent.
                       Even though this archive format  is  covered  by  the
                       POSIX.1-1988  standard,  it  has  a lower portability
                       than the ustar format. Try to avoid the cpio  archive
                       format.
             odc       This   archive   format   is   similar   to  the  The
                       POSIX.1-1988 cpio format but the file name length  is
                       limited to 255 characters and the socket file type is
                       not allowed.  This archive format has been introduced
                       to  allow  non POSIX cpio implementations such as the
                       cpio program on SYSV to accept the archive. Use  this
                       format whenever you are not sure if the target system
                       offers a fully POSIX compliant cpio program.
                       Even though this archive format  is  covered  by  the
                       POSIX.1-1988  standard,  it  has  a lower portability
                       than the ustar format. Try to avoid the  odc  archive
                       format.
             asc       Tell  star to create a cpio archive in the ascii for-
                       mat that is created with cpio -o -c  on  SYSVr4  sys-
                       tems.   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 portabil-
                       ity.
             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 conjunc-
             tion  with  the  star, xstar, xustar, exustar, and with the pax
             format.)  Another option to retain the access time for the  the
             files  that are going to be archives is to readonly mount a UFS
             snapshot and to archive files from the mount point of  the  UFS
             snapshot.
      -B     Force  star  to perform multiple reads (if necessary) to fill a
             block.  This option exists so that star  can  work  across  the
             Ethernet,  since  pipes  and sockets return partial blocks even
             when more data is coming.  If star uses stdin as archive  file,
             star  behaves as if it has been called with the -B option.  For
             this reason, the option -B in practice is rarely needed.
      -block-number
             Print the archive block number (archive offset /  512)  at  the
             beginning  of  each  line  when in verbose mode. This allows to
             write backup scripts that archive the  offsets  for  files  and
             that use
                  mt fsr blockno
             to skip to the tape block number of interest in a fast way if a
             single file needs to be restored.
      blocks=#, b=#
             Set the blocking factor of the  tarfile  to  # times  512 bytes
             (unless  a different multiplication factor has been specified -
             see bs= option for 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 porta-
             bility with very old tar implementations (pre  BSD 4.2  or  pre
             AT&T SVR4),  blocksize  should not be more than 10 kBytes.  For
             POSIX.1-1988 compatibility, blocksize should be  no  more  than
             10 kBytes.  For POSIX.1-2001 compatibility, blocksize should be
             no more than 32 kBytes.  Most systems also have a hardware lim-
             itation  for  the blocksize, 32 kBytes and 63 kBytes are common
             limits on many systems.  The upper limit in  any  case  is  the
             size  of  the buffer RAM in the tape drive.  Make a test if you
             want to make sure  that  the  target  system  will  handle  the
             intended  blocksize.   If  you  use  star for data exchange via
             tape, it is a good idea to use a blocksize of 10 kBytes  unless
             you  are  sure  that  the  reading  system will handle a larger
             blocksize.  If you use star for  backup  purposes  with  recent
             hardware  (e.g.  DLT  tape  drives),  a blocksize of 256 kBytes
             results in sufficient speed and seems  to  be  a  good  choice.
             Star  allows  block  sizes up to 2 GByte if the system does not
             impose a smaller limit.  If you want to determine the  blocking
             factor  when  reading an unknown tar archive on tape, specify a
             blocking factor that is higher than the supposed blocking  fac-
             tor  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 sep-
             arated by ‘x’ or ‘*’, multiplication of the two numbers is per-
             formed.  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  block-
             sizes.   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 decom-
             pression option to extract.
      C=dir
      -C dir Perform a chdir(2) operation to dir before storing or  extract-
             ing  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 direc-
                    tories  from  previous  C=dir  options  and  performs  a
                    chdir(2) to the corresponding directory  of  a  matching
                    pattern.   All  pat=  options that do not follow a C=dir
                    option are interpreted as if 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  cre-
             ating  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 star is run as root and if -ctime is used with  the  extract
             command  and  the same archive formats, this causes star to try
             to restore even the ctime of a file by generating time  storms.
             You should not do this when in multi user mode because this may
             confuse programs like cron and the news system.  Although  star
             tries  to eliminate the accumulative effects of the time storm,
             there is a tendency for the system clock to slow  down  a  bit.
             The  clock  typically  lags about one millisecond per extracted
             file.  Use with care and check the  system  clock  after  using
             this feature.
             If  used  with  the create command this changes the behavior of
             the newer= option.  Star, in this case compares  the  ctime  of
             all  files to the mtime of the stamp file rather then comparing
             the mtimes of both files.
      -cumulative
             A shorthand for  -dump-cumulative.   See  -dump-cumulative  for
             more information.
      -D     Do  not descend directories.  Normally, star descends the whole
             tree if it encounters a directory in in  its  file  parameters.
             The  option  -D is in effect by default if the list=file option
             is used.  If you like star to descend directories found in  the
             list file, use the -dodesc option (see below).
      -d     Do  not  store/create directories.  Old versions of tar such as
             published with the seventh edition of UNIX are not able to deal
             with  directories  in tar archives.  If a tar archive is gener-
             ated without directories this avoids problems with  tar  imple-
             mentations  found  on  SYSVr3  and  earlier.   If  used  during
             extract, no intermediate missing directories are created.
      -data-change-warn
             If the size of a file changes while the file is being archived,
             treat  this  condition  as a warning only that does not cause a
             non zero exit code.  A warning message is still written if  the
             condition  is  not  otherwise  ignored  by another rule from an
             errctl= option.  The -data-change-warn option works as  if  the
             last error control option was
                  errctl="WARN|GROW|SHRINK *"
             The  -e  option  or  an  ABORT  entry  in a condition set up by
             errctl= has a  higher  precedence  than  the  -data-change-warn
             option.  This option is ignored in extract or list mode.
      -debug Print debug messages. Among other things, this gives debug 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 ini-
                       tially 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  star’s
                       dump extensions.
             uid       Compare numerical user id of file.
             gid       Compare numerical group id of file.
             uname     Compare  ASCII  version of user id of file.  The user
                       name is mapped via the file /etc/passwd.
             gname     Compare ASCII version of group id of file.  The group
                       name is mapped via the file /etc/group.
             id        Shorthand   for:  uid,gid,uname,gname.   Compare  all
                       user/group related info of file.  Note that this will
                       always find differences if the source and target 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 for-
                       mat 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 mod-
                       ification time  of  symbolic  links.   Star  compares
                       lmtime only if mtime is compared also.
             times     Shorthand for: atime,mtime,ctime.
             dir       Compare  the content of directories.  This only works
                       if the archive is  in  exustar  format  and  contains
                       star’s dump extensions.  Together with increased 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.
             xtimes    Shorthand for: atime,mtime,ctime,lmtime.
             acl       Compare access control lists.  This only works if the
                       archive  is  in  exustar  format and has been created
                       with star’s -acl option.  You  need  to  specify  the
                       -acl option in addition when running the diff.
             xattr     Compare extended file attributes.  This only works if
                       the archive is in exustar format and has been created
                       with  star’s  -xattr option.  You need to specify the
                       -xattr option in addition when running the diff.
             fflags    Compare extended file flags.  This only works if  the
                       archive  is  in  exustar  format and has been created
                       with star’s -xfflags option.  You need to specify the
                       -xfflags option in addition when running the diff.
             If  optlst starts with a ! the meaning of all members in optlst
             is inverted as with the not optlist member.  In this case, star
             starts  with  a  complete  list that includes atime and lmtime.
             Reasonable diff options to use when comparing against a copy of
             a directory tree are diffopts=!atime,ctime,lmtime.
             If diffopts are not specified, star compares everything but the
             access time of the files and the modification time of  symbolic
             links.
      dir-group=group
             If  star  extracts archives as root, this option allows to con-
             trol the group id of intermediate directories created by  star.
      dir-owner=user
             If  star  extracts archives as root, this option allows to con-
             trol the owner of intermediate directories created by
      -dirmode
             If in create mode (i.e. when storing files  to  archive),  star
             stores  directories  past the corresponding files. This guaran-
             tees 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  imple-
             ment  a  star version that supports true incremental dumps, but
             it is kept as it gives  additional  benefits.   Star  currently
             sets the archive type to exustar and, in addition archives more
             inode meta data inside POSIX.1-2001 extended headers.  See also
             level=  option  and  the  section  INCREMENTAL BACKUPS for more
             information on true incremental dumps.
      -dump-cumulative
             instructs star to perform incremental dumps relatively  to  the
             last  incremental  dump  of  the same level.  Incremental dumps
             with a level higher than 0 are normally done relatively to  the
             content  of  a  previous  dump with lower level. If incremental
             dumps and restores are going to be used to synchronize filesys-
             tem content, every successive incremental dump will increase in
             size if -dump-cumulative is not used.  See section  SYNCHRONIZ-
             ING FILESYSTEMS for more information.
      dumpdate=name
             Tells star to use the mtime of the time stamp file name instead
             of using the start time of star.  This is needed when  star  is
             run  on file system snapshots.  If star would use the the start
             time with snapshots, all files that have been modified  between
             the  setup of the snapshot and the start of star would be miss-
             ing 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, permis-
             sions, ...) but not the file  content.   Using  -dumpmeta  will
             result  in  smaller incremental dumps, but files that have been
             created between two incrementals and set  to  an  old  date  in
             st_mtime  (e.g.  as  a  result  from a tar extract) will not be
             archived with full content.  Using -dumpmeta thus may result in
             incomplete incremental dumps, use with extreme care.
      -e     Exit  immediately  with  exit status -3 (253) if any unexpected
             error occurs.  The -e option works as if the last error control
             option was
                  errctl="ABORT|ALL|DIFF   *"
             This  allows  to  use  the  errctl= option together with the -e
             option and thus to ignore some error conditions while  aborting
             on all other conditions.
      errctl= name
      errctl= error control spec
             Add the content from file name to the error control definitions
             or add error control spec to  the  error  control  definitions.
             More  than  one error control file and more than one error con-
             trol spec as well as a mixture of both forms is possible.
             The reason for using error control is to make star quiet  about
             error conditions that are known to be irrelevant on the quality
             of the archive or restore run or to tell star to abort on  cer-
             tain  error  conditions  instead of trying to continue with the
             archive.
             A typical reason to use error control is to  suppress  warnings
             about  growing  log  files  while doing a backup on a live file
             system.  Another typical reason to use error control is to tell
             star  to  abort if e.g. a file could not be archived instead of
             continuing to archive other files from a list.
             The error control file contains a set of lines,  each  starting
             with a list of error conditions to be ignored followed by white
             space followed by a file name pattern  (see  match(1)  or  pat-
             match(3)  for  more  information).  The error control spec uses
             the same syntax as a single line from the error  control  file.
             If the file name pattern needs to start with white space, use a
             backslash to escape the start of the file name. It is not  pos-
             sible  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  con-
             trol  file, then star checks whether the pattern on the rest of
             the line matches the current file name.  If this is  the  case,
             star  uses  the  current error control specification to control
             the current error condition.
             The list of error conditions to be handled may use one or  more
             (in  this  case  separated by a ’|’ character) identifiers from
             the list below:
             ABORT       If this meta condition is included in an error con-
                         dition,  star  aborts  (exits)  as soon as possible
                         after this error condition has been seen instead of
                         making  star quiet about the condition.  This error
                         condition flag may only be used  together  with  at
                         another  error  condition or a list of error condi-
                         tions (separated by a ’|’ character).
             WARN        If this meta condition is included in an error con-
                         dition,  star  prints  the  warning about the error
                         condition but the error condition does  not  affect
                         the  exit  code  of  star  and the error statistics
                         (which is printed to the end) does not include  the
                         related errors.  This error condition flag may only
                         be used together with at another error condition or
                         a  list  of  error  conditions  (separated by a ’|’
                         character).  The WARN meta contition  has  a  lower
                         precedence than ABORT.
             DIFF        Suppress   output  in  case  that  star  -diff  did
                         encounter any differences.
             ALL         This is a shortcut for all error conditions  below.
             STAT        Suppress  warnings  that  star  could not stat(2) a
                         file.
             GETACL      Suppress warnings about files  on  which  star  had
                         problems to retrieve the ACL information.
             OPEN        Suppress  warnings  about  files  that could not be
                         opened.
             READ        Suppress warnings read errors on files.
             WRITE       Suppress warnings write errors on files.
             READLINK    Suppress warnings readlink(2)  errors  on  symbolic
                         links.
             GROW        Suppress  warnings  about files that did grow while
                         they have been archived.
             SHRINK      Suppress warnings about files that did shrink while
                         they have been archived.
             MISSLINK    Suppress  warnings  about  files for which star was
                         unable to archive all hard links.
             NAMETOOLONG Suppress warnings about files  that  could  not  be
                         archived  because  the name of the file is too long
                         for the archive format.
             FILETOOBIG  Suppress warnings about files  that  could  not  be
                         archived  because  the  size of the file is too big
                         for the archive format.
             SPECIALFILE Suppress warnings about files  that  could  not  be
                         archived  because the file type is not supported by
                         the archive format.
             GETXATTR    Suppress warnings about files on  that  star  could
                         not  retrieve  the extended file attribute informa-
                         tion.
             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 con-
                         sidered 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 con-
                         sidered to be  a  security  risk.   This  currently
                         applies  to  all  link names that start with ’/’ or
                         have a ’/../’ sequence  inside  when  -secure-links
                         has  been  specified.   In this case, star tries to
                         match the link name  against  the  pattern  in  the
                         error control file.
             SAMEFILE    Suppress   warnings  about  links  that  have  been
                         skipped on extraction because source and target  of
                         the  link  are  pointing to the same file.  If star
                         would not skip these files, it would  end  up  with
                         removing  the  file completely.  In this case, star
                         tries to match the link name against the pattern in
                         the error control file.
             BADACL      Suppress  warnings  access  control list conversion
                         problems.
             SETACL      Suppress warnings about files on  that  star  could
                         not set the ACL information during extraction.
             SETXATTR    Suppress  warnings  about  files on that star could
                         not set the  extended  file  attribute  information
                         during extraction.
      If  a specific error condition is ignored, then the error condition is
      not only handled in a silent way but  also  excluded  from  the  error
      statistics that are printed at the end of the star run.
      Be  very  careful when using error control as you may ignore any error
      condition.  If you ignore the wrong error conditions, you may  not  be
      able to see real problems anymore.
      -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 trans-
             fer 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  sec-
             tion for more information.
      -fifostats
             Print  fifo  statistics  at the end of a star run when the fifo
             has been in  effect.   All  options  that  start  with  the  -f
             sequence  are  sensitive to typo problems, see BUGS section for
             more information.
      file=tarfilename, f=tarfilename
             Use tarfilename as the name for the tar archive.  Currently  up
             to  100  file=  options  are possible. Specifying more then one
             file= option make sense in multi volume mode. In this case star
             will use the next name in the list every time a media change is
             needed.  To make star behave consistent with  the  single  file
             case,  star  loops  over the list of known archive files.  Note
             that if star is installed suid root and the first tarfile is  a
             remote  archive,  only  the  connection to this archive will be
             created with root privileges.  After this connection  has  been
             established  as  root,  star  switches  back  to  the id of the
             caller.  If any of the other archives in the list is located on
             a  different  host,  star will not be able to open this archive
             later on, unless run by root.
             Star normally uses stdin/stdout for the tar archive because the
             most  common  way to use star is in conjunction with pipes.  If
             star is installed suid root or if it has been called  by  root,
             tarfilename  may  be in remote syntax: user@host:filename as in
             rcp(1) even if invoked by non root users.  See SUID  NOTES  for
             more information.
             To  make  a  file  local  although it includes a colon (:), the
             filename must start with: ’/’, ’./’ or ’../’
             Note that if star talks to an old rmt remote tape  server  that
             does not support symbolic open modes, it does not open a remote
             tape with the O_CREAT open flag because this would be extremely
             dangerous.   If  the  rmt  server  on the other side is the rmt
             server that comes with star or the GNU rmt server, star may use
             the  symbolic  mode for the open flags.  Only the symbolic open
             modes allow to send all possible open modes in a  portable  way
             to remote tape servers.
             It  is  recommended to use the rmt server that comes with star.
             It is the only rmt server that gives platform independent  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.
      -find  This  option acts a separator.  If it is used, all star options
             must be to the left of the -find option. To the  right  of  the
             -find option, star accepts the find command line syntax only.
             The find expression acts as a filter between the source of file
             names and the consumer,  which  may  either  be  the  archiving
             engine or list/extract engine. If the find expression evaluated
             as TRUE, then the related file is selected for processing, oth-
             erwise it is omited.
             In  order  to  make  the evaluation of the find expression more
             convenient, star implements additional find primaries that have
             side  effects  on the file meta data.  Star implements the fol-
             lowing additional find primaries:
             -chgrp gname
                    The primary always evaluates as true; it sets the  group
                    of the file to gname.
             -chmod mode
                    The  primary  always evaluates as true; it sets the per-
                    missions of the file to mode.  Octal and  symbolic  per-
                    missions are accepted for mode as with chmod(1).
             -chown uname
                    The  primary always evaluates as true; it sets the owner
                    of the file to uname.
             -false The primary always evaluates as false; it allows to make
                    the  result  of  the  full expression different from the
                    result of a part of the expression.
             -true  The primary always evaluates as true; it allows to  make
                    the  result  of  the  full expression different from the
                    result of a part of the expression.
             The command line:
             star -c f=o.tar -find . ( -type d -ls -o false ) -o ! -type d
             lists all directories and archives all non-directories  to  the
             archive o.tar.
             The command line:
             star -c f=o.tar -find . ( -type d -chown root -o true )
             archives  all directories so they appear to be owned by root in
             the archive, all non-directories are archived as  they  are  in
             the file system.
      -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 some-
             times 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  sec-
             tion 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 encoun-
             tered 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 spec-
             ified, 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  decom-
             pression 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 following 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  following  the  -C  option  is
             referring  to  a  root  directory of a file system and no other
             restrictions apply that exclude certain files  from  the  dump,
             the dump is called a full dump.
             By default, the tardumps database is not written.  See also the
             tardumps=name and -wtardumps options and the section  INCREMEN-
             TAL 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  directo-
             ries  that  will go into the archive and thus causes a lot more
             memory to be allocated than in the default case.
             If you like to extract a cpio archive that contains hard linked
             directories,  you also need to specify -link-dirs in extract or
             diff mode.  This is needed because  many  cpio  implementations
             create  buggy  archives  with  respect  to hard links.  If star
             would look for hard linked directories in all cases,  it  would
             detect  many  pseudo hard links to directories.  Use -link-dirs
             with care if you extract cpio archives.
             Note that not all filesystem allow  to  create  hard  links  to
             directories.   Also  note  that  even though a non-root user is
             able detect and archive  hard  linked  directories,  all  known
             operating  systems require the extraction to be done as root in
             order to be able to create or remove hard links to directories.
             For  this  reason  its only recommended to use this option when
             doing accurate backups and when hard links to  directories  are
             expected.
             When the option -link-dirs is not used and hard links to 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
             separate  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  mem-
             ory  to hold the directory content and reading the directory at
             once, star reads the directory name by  name.  This  may  cause
             star  to close the directory if it rans out of file descriptors
             because of deeply nested directories. If a directory then  does
             not support telldir(3)/seekdir(3), star will fail.
      -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  multi-
             plied  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 read-
             ing such nonstandard archives.
      -multivol
             Switch  to multi volume mode.  In multi volume mode, there will
             be no logical EOF marker written to the end of a  single  tape.
             If  -multivol is used in read mode, a hard EOF on input (if not
             preceded by a logical EOF) triggers a medium change  operation.
             Specifying  -multivol  tells star to split files across volumes
             if needed.  This way, a virtual archive is created  that  spans
             more  than one medium.  Multi volume mode is needed whenever it
             is not possible to split the archiving or extracting into  sev-
             eral  logically independent tasks. This is true for e.g. incre-
             mental 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 vol-
             ume mode, files cannot be split across volumes.
             When -multivol has been specified in create mode together  with
             tsize=#  then  a  media  change  is  initiated exactly after an
             amount of tsize data has been written.  When -multivol has been
             specified  in  create  mode and tsize=# has not been specified,
             then the medium change is triggered by  a  EOT  condition  from
             writing  the  medium.  This  allows to use media where the size
             cannot be known in advance (e.g. tapes with build  in  compres-
             sion); it does not work if the EOT condition is not returned in
             sync with the related write operation. For this reason,  it  is
             expected  that  data buffering inside a device driver cannot be
             used.
             Depending on the selected archive format, star writes a  volume
             header  at  the  beginning  of a new medium. This medium header
             allows to verify the correct volume after a change during  read
             back.   It  is  recommended  to use the exustar format for best
             results.  In create  mode,  -multivol  is  only  supported  for
             archives types that allow to write reliable multi volume header
             information.
             See tsize=# option for more information.
             Note that -multivol is an interactive option that prevents star
             from  being  used in non-interactive environments.  If you like
             to use it in a non-interactive environment, you need to specify
             new-volume-script=script  in  addition in order to automate the
             media change procedure.
      newer=filename
             Do not store files to tarfile if their modification time is not
             newer  than  the  modification  time  of  filename.  See -ctime
             option for changing this behavior.
      -newest
             In conjunction with the list command this lists  you  only  the
             newest file in tarfile.
      -newest_file
             obsoleted by -newest-file
      -newest-file
             In  conjunction  with  the list command this lists you only the
             newest regular file in tarfile.
      new-volume-script=script
             Call script at end of each tape if in multi  volume  mode.   If
             this option is not in effect, star will ask the user to confirm
             the volume change.  The script is called with  two  parameters.
             The  first  parameter  is the next volume number and the second
             parameter is the next archive file name.
      -nodump
             If this option is set, star will not dump files that  have  the
             nodump flag set. Note that this currently only works on BSD-4.4
             derivates and on Linux.  On Linux, using this option will cause
             a  performance  degradation  (the system time increases by 10%)
             because of the unlucky kernel interface.
      -no-dirslash
             Do not add a slash to the end of directory names if writing  to
             an  archive.   Historic  tar  archive formats did only allow to
             specify plain files and hard links.  Around 1980, BSD  added  a
             feature to specify a directory on tape by adding a slash to the
             end of the name. POSIX.1-1988 defined the  first  official  tar
             archive format that had a clean method to specify the type of a
             directory.  As old tar formats need the slash  to  recognize  a
             directory,  -no-dirslash  may not be used if archives should be
             compatible with the old tar format.
      -no_fifo
             obsoleted by -no-fifo
      -no-fifo
             Don’t use a fifo to optimize data flow from/to  tarfile.   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 oper-
             ating systems with slow file I/O (such as Linux), but  includes
             the  risk  that star may not be able to detect extraction prob-
             lems 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-check-
             sum  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
             directory that is in the argument list. This may be modified by
             using the -match-tree option.  In extract  or  list  mode,  all
             file  type  arguments  are interpreted to be select pattern and
             all option type patterns may be either select or  exclude  pat-
             terns  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) implementa-
             tions.  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 patterns, use the -not or the -V option.
      pkglist=file
             This  is  (for now) an internal interface for the Schily Source
             Package System (sps).  It only works in create mode and behaves
             similar  to  the  list=  option, but it allows to overwrite the
             permissions, the uid and gid values from  the  content  of  the
             pkglist=  file.   Each  line  from the pkglist= file contains a
             file name followed by the permission, a user name and  a  group
             name.  The permission is an octal character string.  Each value
             that is not used  to  overwrite  the  original  values  may  be
             replaced  by a ’?’.  The fields are separated by spaces, so the
             pkglist= option does not allow files that  contain  newline  or
             space characters.
      -pax-c, -notarg
             Match all file or archive members except those specified by the
             pattern or file operands.
      -pax-H Follow symbolic links that have been encountered on the command
             line.  If the referenced file does not exist, the file 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.
             Note that -pax-i is an interactive option  that  prevents  star
             from being used in non-interactive environments.
      -pax-L Follow  symbolic links.  If the referenced file does not exist,
             the file information and type will be for the link itself.   If
             the  link  is  referencing  a file type that cannot be archived
             with the current archive format, the file information and  type
             will be for the link itself.
      -pax-ls
             Switch  listing  format to the format defined for POSIX pax and
             ls.
      -pax-match
             Allow file type arguments to be recognised as  regular  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
                    calling star -p.
      -prinodes
             Print inode numbers in verbose list mode if  the  archive  con-
             tains inode nubers.
      -print-artype
             Check  the  type of the archive, print the archive and compres-
             sion type on a single line and exit.
      -qic24 Set tape volume size to 61440 kBytes.  See tsize=#  option  for
             more information.
      -qic120
             Set  tape volume size to 128000 kBytes.  See tsize=# option for
             more information.
      -qic150
             Set tape volume size to 153600 kBytes.  See tsize=# option  for
             more information.
      -qic250
             Set  tape volume size to 256000 kBytes.  See tsize=# option for
             more information.
      -qic525
             Set tape volume size to 512500 kBytes.  See tsize=# option  for
             more information.
      -read0 Read  null  terminated  file names from the file specified with
             the list= option.
      -refresh_old_files
             obsoleted by -refresh-old-files
      -refresh-old-files
      -refresh
             Do not create new files. Only already  existing  files  may  be
             overwritten  from  tarfile if either newer versions are present
             in the archive or if the -U flag is used.  This allows to over-
             write  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  recur-
             sively removes non empty directories too.
      -restore
             switches star into true incremental restore mode.  A file named
             star-symtable and a directory named star-tmpdir is  created  in
             the  root  directory  of  the  file system where the extraction
             takes place.  If -restore has been specified, star  behaves  as
             if  -xdot  has  been specified too.  See also level= option and
             section INCREMENTAL BACKUPS for more information.
             Note: Do not use the  -restore  option  if  you  only  like  to
             restore a single file or a list of selected files.
      -S     Do not store/create special files.  A special files is any file
             except plain files, symbolic links and directories.   You  need
             to be super user to extract special files.
      -s replstr
             Modify  file or archive member names named by a pattern accord-
             ing to the substitution  expression  replstr.   The  format  of
             replstr is:
                  -s /old/new/[gp]
             The  old pattern may use regular expressions and the new string
             may contain the special character ’&’.  The  character  ’&’  is
             substituted  by  the  string that matches the old pattern.  The
             optional trailing ’g’ means global substitution. If ’g’ is  not
             used,  a  substitution pattern is only used once on a name.  If
             the optional trailing ’p’ is used, the substitution is  printed
             to standard error.
             Up to 100 substitute options may be used. If more than one 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 Sys-
             tem V shared memory, you may have to raise the system’s  inter-
             nal limit for shared memory resources to get enough shared mem-
             ory for star.
      -signed_checksum
             obsoleted by -signed-checksum
      -signed-checksum
             Use signed chars to calculate checksums. This violates the  tar
             specs  but old versions of tar derived from the seventh edition
             of UNIX are implemented in this way.  Note: Only filenames  and
             linknames  containing  chars  with the most significant bit set
             may trigger this problem because all other fields only  contain
             7 bit ASCII characters, octal digits or binary zeroes.
      -silent
             Suppress informational messages like foobar is sparse.
      -sparse
             Handle files with holes effectively on store/create.  Note that
             sparse files may not be archived this way if the archive format
             is   tar,   ustar,  suntar,  pax,  or  any  cpio  variant.   On
             Solaris-2.3 ... Solaris-2.5.1 there is a special ioctl() called
             _FIOAI  that  allows root to get the allocation info more effi-
             ciently.  On Solaris 11 there is an enhanced lseek(2) call with
             addidional  whence values SEEK_HOLE and SEEK_DATA that allow to
             find holes in an efficient way.  Other operating  systems  lack
             support  to get the real allocation list and force star to scan
             the files to look for blocks that only contain null characters.
             This may star cause to assume more holes to be present than the
             number that the file really contains.
      -symlinks
             This option tells star in extract mode to try to create a  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  envi-
             ronment variable, if set.
      tardumps=name
             Set  the  file  name  for tar dump dates database to name.  The
             default name is /etc/tardumps.  Use  in  combination  with  the
             level=  option  to  create  true  incremental  dumps.  See also
             -wtardumps option and  section  INCREMENTAL  BACKUPS  for  more
             information.
      -time  Print timing info.  See DIAGNOSTICS for more information.
      -to_stdout
             obsoleted by -to-stdout
      -to-stdout
             Extract  files  to  stdout.  This option may be used to extract
             tarfiles containing tarfiles (see examples below).
      -tpath Use this option together with the -t option or with  -cv  (ver-
             bose  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
             multiplied  by  512,  so  the value counts in units of 512 byte
             blocks.  If the size specifier ends with a valid multiplication
             character  (e.g ’.’ for bytes or ’M’ for MB) the specified size
             is used as specified and not  multiplied  by  512.   With  this
             option  in effect, star is able to archive filesystems that are
             bigger then the tape size.  If the option tsize=# without -mul-
             tivol then no file will be split across volumes and each volume
             may in theory be read back separately.  Files that do  not  fit
             on  a single tape may not be stored in this mode.  If -multivol
             has been specified in addition, star will split files when  the
             maximum allowed tape size has been reached.  If the tape volume
             size is not a multiple of the tape block size, the tape  volume
             size  is silently rounded down to a value that is a multiple of
             the tape block size.
             See -multivol option for more information.
      -U     Restore files unconditionally.  By default, an older file  from
             the  archive  will  not  replace  a corresponding newer file on
             disk.
      umask=mask
             Set star’s umask to mask.  This allows to control  the  permis-
             sions  for intermediate directories that are created by star in
             extract mode.  See also -p option.
      -v     Increment verbose level by one.  This normally results in  more
             output  during  operation.  See also in the description for the
             -t flag.  Normally, star does its work silently.  If  the  ver-
             bose  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.
      Note that -w is an interactive option that prevents  star  from  being
      used in non-interactive environments.
      -wready
             This  option tells Star to wait up to two minutes for the drive
             to become ready.  It has been added as a hack for a bug in  the
             SunOS/Solaris  st  device  driver.  This driver has problems to
             sense the loading time with Exabyte drives  with  factory  set-
             tings.   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
             extracting  exustar  archives  as  it  is based on POSIX.1-2001
             extended tar headers.
             The method used in the current implementation could be used  to
             store  and extract extended file attributes from BSD too.  Note
             that the current implementation is not generic enough to  cover
             more  general  extended file attribute implementations as found
             on Solaris.  If star starts to implement a method  that  covers
             extended  file  attributes  on  Solaris, the new method will be
             used then -xattr has been specified and -xattr-linux will refer
             to  the  old  method.  The method used with -xattr-linux may go
             away in the future.
      xdebug=#, xd=#
             Set extended debug level to #.
      -xdev, -M
             Do not descend mount points.  This is useful when doing backups
             of complete file systems.  See NOTES for more information.
      -xdir  Extract  directories  even  if the corresponding directories on
             the archive are not newer.  This is useful when for  some  rea-
             son,  the  directories  are  recorded  after their content (see
             -dirmode option), or when the permissions of  some  directories
             must  be  set  in any case.  As the classical UNIX cpio program
             does not implement delayed directory permission and time  stamp
             setting,  cpio  users  often  create  archives in reverse order
             (directories past their content). For  this  reason,  it  makes
             sense to use -xdir while extracting cpio archives.
      -xdot  Unconditionally  extract  the first directory in the archive if
             the name of this directory is either ’.’ or ’./’.   This  helps
             to  extract archives in an expected way if the target directory
             is a newly created empty directory. As this directory is  newer
             than the top level directory in the archive, star would usually
             skip this directory during  extraction.   The  effect  of  this
             directory is as if -xdir has been specified but is switched off
             after the first directory has been found.
      -xfflags
             Store and extract extended file flags as found on BSD and Linux
             systems.   This  option  only  makes  sense  when  creating  or
             extracting exustar archives as  it  is  based  on  POSIX.1-2001
             extended  tar  headers.   See  NOTES  section for problems with
             -xfflags on Linux systems.
      -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 reblock-
             ing will be done, so this option will currently only make sense
             on plain files.  As the -bz the -j the -Z and the -z option are
             non standard, it makes sense to omit the -bz the -j the -Z  and
             the -z options inside shell scripts if you are going to extract
             a compressed archive that is located inside  a  plain  file  as
             star  will  auto detect compression and choose the right decom-
             pression option to extract.  The environment variable STAR_COM-
             PRESS_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.
      To be more verbose:
      ·      The filesystem needs to uniquely identify files by the two num-
             bers  st_dev  (The device ID of the device containing the file)
             and st_ino (The file serial number).  If  a  file  is  renamed,
             these  numbers  need to be retained.  Both numbers need to be a
             cardinal scalar that is expressible in a decimal number.
      ·      The filesystem needs to implement at  least  two  time  stamps,
             st_mtime  the  file’s  last  modification time and st_ctime the
             file’s last status change time.  Both time stamps  need  to  be
             dealt  with  as  documented by te POSIX standard.  Both numbers
             need to be a cardinal scalar that is expressible in  a  decimal
             number.
      ·      The  filesystem  needs to allow to rename files and directories
             by either calling rename(2), or link(2) and unlink(2).
      ·      The filesystem needs to honor and preserve  the  case  of  file
             names.
      The  incremental  backup  method used by star depends on comparing the
      time stamps of all files against the time of  the  last  backup.  Note
      that  this  method  only works correctly if the level 0 backup and all
      higher level incrementals include the  whole  file  system.   As  star
      archives  all inode meta data, star is able to detect renamed files by
      comparing 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  direc-
      tory 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 live filesystems should be avoided.  On operating systems
      that support file system snapshots, backups  should  be  made  from  a
      read-only  mount  of  a  snapshot. Be careful that all files that have
      been created between setting up a snapshot and starting an incremental
      backup may be missing from all backups unless the dumpdate=name option
      is used.
      If the system that is going to be backed up is not acting  as  a  file
      server,  it  makes  sense to shut down all services that may result in
      inconsistent file states before setting up  the  filesystem  snapshot.
      After  the  filesystem  snapshot  has been set up, the services may be
      restarted.
      If the the system that is going to be backed up is acting  as  a  file
      server,  it  may be that services on remote clients cause inconsistent
      file states unless all such services that remotely  access  files  are
      shut down before the snapshot is set up.
      Star  includes  options  that help to deal with file system snapshots.
      The following example backs up a file system on Solaris using  a  file
      system snapshot:
      echo > /tmp/snapstamp
      mount -r ‘fssnap -F ufs -o \
          backing-store=/var/tmp/EXPORT-NFS.snap /export/nfs‘ /mnt
      star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
          f=archive-name dumpdate=/tmp/snapstamp \
          fs-name=/export/nfs -C /mnt .
      First a file with a current time stamp is created, then a snapshot for
      /export/nfs is created and mounted on /mnt.  The following  star  com-
      mand 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 sys-
      tem for /etc/tardumps and the archive header.
      Note that if the backup is done on a live 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  errctl=  option)  and to tell star to ignore growing
      files.

BACKUP SCHEDULES

      Full (level 0) dumps should be made on a regular  base  (e.g.  once  a
      month).   As a full dump may take a long time and takes a lot of tape,
      it is wise to make higher level incremental dumps with shorter  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 follow-
      ing backup schedule:
                         Sun   Mon   Tue   Wed   Thu   Fri
             Week 1:     0     20    30    40    50    5
             Week 2:     10    20    30    40    50    5
             Week 3:     10    20    30    40    50    5
             Week 4:     10    20    30    40    50    5
      Note that in this case, 7 dumps need to be restored  if  the  a  crash
      happens  at  the  worst  case date (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
      incremental restores to a  file  system  that  contains  active  mount
      points.
      The  incremental restore procedure starts with restoring the last full
      (level 0) dump. Then the latest incremental dump of  each  dump  level
      (with ascending order of dump levels) need to be restored.
      Let  us assume the first example from the section BACKUP SCHEDULES for
      the backup schedule. If a disk crash happens before the Thursday  dump
      of  week  3 has been made, the following restore procedure needs to be
      applied:
      level 0
             starting with an empty disk, the full (level 0) dump from  week
             1 is restored.
      level 5
             after  the  level 0 restore has been finished, the level 5 dump
             from Friday in week 2 is restored.
      level 10
             after the level 5 restore has been finished, the level 10  dump
             from Wednesday in week 3 is restored.
      The  disk  now contains the same files as it did when the level 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 incre-
      mental dumps. These files are  moved  to  the  directory  star-tmpdir.
      Before  you  start to extract the next incremental, you need to remove
      all files in star-tmpdir.

SYNCHRONIZING FILESYSTEMS

      Star may be used to synchronize filesystem content.  To  do  this,  an
      initial  copy of the current content of the source filesystem needs to
      be performed first.
      To create an initial copy of a filesystem call:
      star -c -xdev -sparse -acl -link-dirs level=0 -wtardumps \
          -C /filestem-mount-point . | \
          star -xpU -restore -C /extract-target-dir
      In order to perform subsequent synchronization of the target  filesys-
      tem  with the content of the source filesystem, a modified incremental
      dump/restore procedure may be used.
      To copy incremental content of a filesystem call:
      star -c -xdev -sparse -acl -link-dirs level=1 -wtardumps \
          -cumulative -C /filestem-mount-point . | \
          star -xpU -restore -C /extract-target-dir
      Note that like with backups in general, copies from a live  filesystem
      should  be  avoided.   On  operating  systems that support file system
      snapshots, copies should be made from a read-only mount of a snapshot.
      Be  careful that all files that have been created between setting up a
      snapshot and starting an incremental copy  may  be  missing  from  all
      copies unless the dumpdate=name option is used.
      See  section  INCREMENTAL  BACKUPS  to learn how to modify the command
      line in case file system snapshots are used.

SIGNALS

      If star handles a signal, it first prints the statistics.   Star  han-
      dles the following signals:
      SIGINT    usually  generated  by  ^C  from  the controlling tty.  Upon
                receipt of a SIGINT, star prints statistics and  exits.   If
                in  create mode i.e. storing files to archive, star finishes
                with the current file to ensure  that  no  partial  file  is
                written  to the archive, write an eof record and then exits.
      SIGHUP    not to be generated from a tty. The actions are the same  as
                upon receipt of a SIGINT.
      SIGQUIT   usually  generated  by  ^\  from  the controlling tty.  Upon
                receipt of a SIGQUIT, star prints statistics  and  continues
                with  the  current  operation.  This  is useful to watch the
                progress of the current operation.

EXIT STATUS

      The following exit values are returned:
      0      All files were processed successfully.
      -3 / 253
             Star has been called with the option -e, or the errctl=  option
             has been used to mark the current error fatal.
      -2 / 254
             One or more files could not be processed successfully.
      -1 / 255
             Command line parsing error.
      >0     Other  positive  exit  codes: The errno of the call that caused
             the fatal error.

EXAMPLES

      To get a listing in a way similar to ls -l one might use:
             example% star -tv f=/dev/rmt/1bn
      The same command as listed above in a POSIX tar  command  line  syntax
      compliant way is:
             example% star tvf /dev/rmt/1mbn
      To copy the directory tree in /home/someuser to the directory /home/fs
      use:
             example% (cd /home/someuser; star -c .) | (cd /home/fs ; star -xp)
      or by using the change directory option of star:
             example% star -c -C /home/someuser . | star -xp -C /home/fs
      Note that both examples above are not the optimum way to copy a direc-
      tory tree. A more efficient way to copy a directory tree is to use the
      -copy option.
             example% star -copy -p -xdot -C /home/someuser . /home/fs
      To copy a file tree including the Access Control List entries for  all
      files and to correctly copy sparse (holey) files use:
             example% star -copy -p -xdot -acl -sparse -C /home/someuser . /home/fs
      To compare the content of a tape to the filesystem one might use:
             example% star -diff -v f=/dev/rmt/1bn
      To compare two directory trees one might use:
             example% star -c . | star -C todir -diff -v diffopts=!times
      or better by using a method similar to the -copy method above:
             example% star -c -diff -v diffopts=!times -C fromdir . todir
      To compare all properties of two file trees, use:
             example% star -c -diff -vv -dump -acl -sparse -C fromdir . todir
      To  extract a backup of the /usr tree without all files residing below
      /usr/openwin one might use:
             example% star -xp -V pat=openwin/\* f=/dev/rmt/1bn
      To extract all .c files to src, all .o files  to  obj  and  all  other
      files to /tmp one might use:
             example% star -xp -C src ’*.c’ -C obj ’*.o’ -C /tmp ’*’ f=/dev/rmt/1bn
      To  extract  files from a zipped tar archive that is located on a read
      only filesystem e.g. a CD while having the shell’s  working  directory
      on the CD one might use:
             example% star -zxp -C /tmp f=star-1.1.tar.gz
      to extract the files from the tar archive to the /tmp directory.
      To backup a list of files generated by the find(1) command:
             example% find . find_options -print | star -c list=- f=/dev/rmt/1bn
      Note that this does not work if the file names from output of the find
      command include new line characters.
      To extract a tarfile that contains a tarfile one might use:
             example% star -x -to-stdout f=/dev/rmt/1bn pat=pat | star -xp
      Pat, in this case should match the tarfile in the tarfile on tape that
      should be extracted.
      To make a backup of the root filesystem to a tape drive connected to a
      remote machine, one might use:
             example# cd /
             example# star -cM fs=128m bs=63k f=tape@remotehost:/dev/rmt/1bn .
      You need a line in /etc/passwd like the following to enable this:
             tape:NP:60001:60001:Tape:/etc/tapehome:/opt/schily/sbin/rmt
      And a .rhosts file in /etc/tapehome to allow remote  connections  from
      the  appropriate  hosts.   Make  sure  that  the file /etc/default/rmt
      exists and allows remote access to the requested tape drive.
      To use a ssh(1) connection for a backup to a remote tape  server,  one
      might use:
             example#   env   RSH=/usr/bin/ssh   star   -cM  fs=128m  bs=63k
             f=tape@remotehost:/dev/rmt/1bn .
      To repair a corrupted filesystem for which no recent backup exists, do
      the following:
             example# fsck -y /filesys
             example# mount /filesys
             example# cd /filesys
             example# star -xpk f=/dev/rmt/1bn
             example# mt -f /dev/rmt/1bn rewind
             example# star -diff -v diffopts=!times f=/dev/rmt/1bn
      Now  check  the  differences  and decide whether to restore additional
      files. This may be done by generating a  list  containing  the  needed
      filenames  and using the list= option or by using the interactive mode
      (see -w option).
      If you want a list that only contains all filenames  from  files  with
      differences you may use:
             example# star -diff -tpath diffopts=!times f=/dev/rmt/1bn
      If  you are looking for files that changed the type or the access per-
      mission because this is a common case on still corrupted files, use:
             example# star -diff -tpath diffopts=type,perm f=/dev/rmt/1bn
      If you like to archive all directories  only  that  are  part  of  the
      directory tree under ".", use:
             example# star -c f=archive-name -find . -type d
      If you like to archive all files as owner root and group root and make
      all files world readable in the archive, use:
             example# star -c f=archive-name -find . -chown root -chgrp root
             -chmod o+r
      If  you  like  to list all files in an archive in a way like sfind(1),
      instead of the way used by star, use:
             example# star -t f=archive-name -find . -ls -false

ENVIRONMENT

      STAR_COMPRESS_FLAG
             If you like star to always create  compressed  files  that  use
             maximum  compression,  you  may  set  the  environment variable
             STAR_COMPRESS_FLAG to -9.
      STAR_DEBUG
             If this environment variable is present, star will  not  remove
             temporary  files  from ./star-tmpdir.  The files in this direc-
             tory are files that have been removed by users before the  last
             incremental dump did take place on the master filesystem.
      STAR_FIFOSIZE
             If  you  like to by default let star use a different fifo size,
             set this environment variable to the desired size.
      TAPE   Unlike other  tar(1)  implementations,  star  defaults  to  use
             stdin/stdout for the archive.  If you like star to use the file
             name from the TAPE environment instead, you need to specify the
             -T option too.
      RSH    If  the  RSH environment is present, the remote connection will
             not be created via rcmd(3) but by calling the  program  pointed
             to by RSH.  Use e.g.  RSH=/usr/bin/ssh to create a secure shell
             connection.
             Note that this forces star to create a pipe to the rsh(1)  pro-
             gram  and  disallows star to directly access the network socket
             to the remote server.  This makes it impossible to set up  per-
             formance 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.  If  it  contains  a  ’n’  or  a ’N’, then the
                    archive device is not a tape.
                    Examples:
                    archive0=/dev/tape 512 0 y
                    archive1=/dev/fd0 1 1440 n
                    archive2=/dev/rmt/0mbn 512 0
                    If the default file does not need to be shared with  the
                    tar  program from Solaris, any number may be used like a
                    generic size option like bs=.
                    Example:
                    archive0=/dev/tape 256k 40G y
      /etc/tardumps
             The default name for the dump level archive. The  default  name
             is  used  whenever the tardumps=name option has not been speci-
             fied.  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 eval-
             uated by star.
      ./star-symtable
             Contains a database that is needed in incremental restore mode.
      ./star-symdump
             Contains an intermediate dump of restore database after a fatal
             error  condition  was  met during an incremental restore opera-
             tion.
      ./star-tmpdir
             Is the temporary directory that is used  as  intermediate  file
             storage by star if in incremental restore mode.
      ./star-lock
             Is  a  lock  file  created  by  star  when doing an incremental
             restore.  If this file is present, it prevents star  from  run-
             ning another incremental restore operation. This helps to avoid
             more than one restore operation at a time  (e.g.  from  a  cron
             script).
      /dev/tty
             Is used for the intercative user interface.

SEE ALSO

      spax(1),  suntar(1), scpio(1), tar(1), cpio(1), pax(1), rcp(1), mt(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
      command.  If you believe that you found a bug in the way  star  parses
      the command line, please first check your command line for correctness
      before you make a bug report for star.
      If you like to write portable shell scripts that  call  tar,  use  the
      UNIX-98  tar  command  line syntax (i.e. a single option string and no
      dash), choose the commands and options from the following set of 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
      impossible  for  other  tar  implementations  (except star) to restore
      filenames that are longer than 100 chars, the xstar,  xustar,  exustar
      and  pax archive format uses a method that allows an POSIX.1-1988 com-
      pliant 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  dur-
      ing 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 fea-
      ture  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  how-
      ever is higher.
      There is no way to ask for the n-th occurrence of a file.
      The  way EOF is handled by star differs, whether the fifo is in effect
      or not.  If the fifo is not used, star stops reading the archive if it
      encounters  a logical EOF record in the archive.  If the fifo is used,
      star may read until the fifo is full or until the  real  EOF  mark  on
      tape  is  reached.   How  much data star actually reads depends on the
      time when the star foreground process sends a fifo shutdown signal  to
      the background fifo read process.
      Gnu  tar  often creates tar archives with incorrect logical EOF marks.
      The standard requires two blocks that are completely  zeroed,  whereas
      gnutar often only adds one of them.
      Old  versions  of  tar  found  on  SYSVr3  and earlier cannot read tar
      archives with a blocksize greater than 10 kBytes.
      The method of storing sparse files currently used with  the  star  and
      xstar  format  is not guaranteed to be used in later versions of star.
      If the author decides to change this method, later  versions  of  star
      may  not be able to restore sparse files from tar archives made by the
      current version of star.
      Some tar implementations violate the standard in using only the  first
      500  Bytes of the header for checksum computation. These tar implemen-
      tations 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.   If  the directory where the
      archive is been unpacked is not empty and contains  contains  symbolic
      links  or  hard  links to directories outside that directory, star may
      also overwrite files outside the current  directory.   As  many  other
      commands,  star usually has all possible permissions when run as root.
      Unpacking archives as root thus may have fatal results to any file  on
      your  system.  Be very careful when you try to extract an archive that
      has not been created by you. It is possible to create hand crafted tar
      archives  that may overwrite critical files (like /etc/passwd) on your
      system.  In addition all tar archives that have been created with  the
      list=  option  and  tar archives where the C= option was not specified
      before all file type arguments may be critical.
      A good advise is to extract all doubtful archives as non  root  in  an
      empty directory and to specify the -secure-links option.  If you get a
      warning, you should unpack the archive a second time and  specify  the
      options  -k,  -w  and  -nowarn in addition to the options used for the
      first run.

SUID NOTES

      If star is installed suid root, star is able to  make  connections  to
      remote archives for non root users.  This is done by using the rcmd(3)
      interface to get a connection to a rmt(1) server.
      Star resets its effective uid back to the  real  user  id  immediately
      after  setting  up  the remote connection to the rmt server and before
      opening any other file.
      If star has not been installed suid root and not called  by  root,  it
      will try to create the remote connection via rsh(1) or ssh(1) (in case
      the environment RSH has been set to ssh).  Note that in this case, the
      throughput  to  the  remote tape server will be much lower than with a
      connection that has been initiated via rcmd(3).

LIMITATIONS

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

BUGS

      The fact that the -f option has to be implemented in  a  way  that  is
      compatible  with  old tar implementations gives several problems.  The
      options -fifostats, -force-hole,  -force-remove  and  -fifo  interfere
      with  the  -f  option and the fact that they exist prevents users from
      using filenames like e.g.  ifo using the  traditional  way  where  the
      filename  directly follows the string -f without any space between the
      option name and the file name.  However, there is no problem to use  a
      file  named  ifo  by  by calling -f ifo, f=ifo, -f=ifo or -f= ifo.  Be
      careful not to make typos with the above options. The result could  be
      that a file is created as a result of the mistyped option.
      There  is  currently  no  way  to  set the fifo lowwater and highwater
      marks.
      There is currently no way to automatically delete files in the  target
      file tree if they are obsolete.  Star should implement something simi-
      lar to gnutar’s dumpdirs.
      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:
      [email protected]      or      [email protected]       or
      [email protected]