ABCDEFGHIJKLMNOPQRSTUVWXYZ

star

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



NAME
       star - unique standard tape archiver

SYNOPSIS
       star  command [ options ] file1 ... filen
       ustar command [ options ] file1 ... filen
       tar   command [ options ] file1 ... filen

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       Star automatically recognizes and handles  compressed  archives  inside
       plain files.

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

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

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

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

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

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

       -t     Table of contents.  List the contents of the tarfile.  If the -v
              flag is used, the listing is similar to the format of ls -l out-
              put.  With this option, the flags -a, -atime and -ctime  have  a
              different  meaning  if  the  archive  is in star, xstar, xustar,
              exustar, or pax format.  The  option  -a  or  -atime  lists  the
              access  time instead of the modification time, the option -ctime
              lists the file creation time instead of the modification time.

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

       Exactly one of the commands above must be specified.

       If  one or more pattern are specified, they apply to any of the command
       listed above.


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

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

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

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

       -ask_remove
              obsoleted by -ask-remove

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

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

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

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

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

                   mt fsr blockno

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

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

                     star: Blocksize = # records.

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

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

       -bz    run  the  input  or  output through a bzip2 pipe - see option -z
              below.  As both the -bz and the -z option are non  standard,  it
              makes  sense  to omit the -bz and the -z inside shell scripts if
              you are going to extract a compressed archive  that  is  located
              inside  a  plain  file  as star will auto detect compression and
              choose the right decompression option to extract.

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

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

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

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

       -copylinks
              This  option  allows  to  copy hard/symlinks 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 can-
              not  copy  files that appear in the archive later than a symlink
              pointing to them.

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

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

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

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

       diffopts=optlst
              Comma separated list of diffopts.  Valid members in optlst are:

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

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

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

              perm      Compare  file permissions. With this option in effect,
                        star compares the low order 12  bits  of  the  st_mode
                        field.

              mode      Same as perm.

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

              nlink     Compare link count on hardlinks.  This only  works  if
                        the  archive  is in exustar format and contains 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.

              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.

              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.

              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.

              If  optlst  starts with a ! the meaning of all members in optlst
              is inverted as with the not optlist member.

              If diffopts are not specified, star compares everything but  the
              access time of the files.

       -dirmode
              If  in  create  mode  (i.e. when storing files to archive), star
              stores directories past the corresponding files. This guarantees
              that even old tar implementations without a directory cache will
              be able to restore the correct times of directories.

       -dodesc
              Force star to descend directories found  in  a  list=file.   See
              also the -D option above.

       -dump  This  currently  is  an experimental option to make it easier to
              implement a star version that supports true  incremental  dumps.
              Star  currently  sets  the  archive type to exustar and archives
              more inode meta data inside POSIX.1-2001 extended headers.

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

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

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

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

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

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

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

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

       -force_hole
              obsoleted by -force-hole

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

       -force_remove
              obsoleted by -force-remove

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

       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.

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

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

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

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

              gnutar    This is a commonly used, but unfortunately  not  Posix
                        compliant  (although  designed after 1987) enhancement
                        to the old tar format.  Do not use the gnutar  archive
                        format unless you want to create an archive for a tar-
                        get system that is known to have only the gnutar  pro-
                        gram  available.   The  gnutar archive format violates
                        basic rules for any (even the  historic)  tar  archive
                        format.  Using the gnutar archive format causes a high
                        risk that the resulting archive may only  be  read  by
                        gnutar  or  by star.  The implementation of the gnutar
                        archive format within star is not complete, but suffi-
                        cient  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,  the
                        POSIX-1003.1-2001 Standard Data Interchange 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     Extended  standard  tar  format.   Star uses the xstar
                        format  as  default  archive  format.   This   is   an
                        upward/downward    compatible   enhancement   of   the
                        IEEE/Posix1003/IEC-9945-1  Standard  Data  Interchange
                        format.   It  allows  among others very long filenames
                        (100+130 chars and above) and records access time  and
                        creation time.  The xstar format is the default format
                        when star is neither  called  as  tar  nor  called  as
                        ustar.

              xustar    New  format introduced 1998, that omits the tar signa-
                        ture at the end of the tar  header.  It  is  otherwise
                        identical  to the xstar format.  As some tar implemen-
                        tations 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  tar
                        implementations.   The  main  other  difference to the
                        xstar format is  that  the  format  uses  POSIX.1-2001
                        extended  headers  to overcome limitations of the his-
                        toric tar format while the xstar format  uses  propri-
                        etary  extensions.   The  xustar format is the default
                        format when star is called as tar.

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

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

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

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

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


              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.

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

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

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

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

       -I     Obsolete option, otherwise identical to -w.

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

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

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

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

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

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

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

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

       -m     Do not restore access an 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.


       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 spec-
              ified and not multiplied by 1024.  See bs= option for all possi-
              ble multipliers.

       -meta  This  currently  is  an  experimental option. In create mode, it
              causes star to archive all meta data of the file (e.g. uid, per-
              missions,  ...)  bit  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 in future star
              versions that support incremental backups.

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

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

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

       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.

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

       -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_statistics
              obsoleted by -no-statistics

       -no-statistics
              Do not print statistic messages at the end of a star run.

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

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

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

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

              This option is superseeded by the H=headertype option.

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

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

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

       -p     Restore filemodes of directories. Without this  option  directo-
              ries  are created using the present umask(2).  If in create mode
              (i.e. when storing files to archive),  star  stores  directories
              past  the corresponding files. This guarantees that even old tar
              implementations will be able to restore  the  correct  times  of
              directories.   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.  In
              extract or list mode, all file type arguments are interpreted to
              be  select  pattern  and  all option type patterns may be either
              select or exclude patterns depending on the presence or  absence
              of  the -not option.  If you use file type select patterns, they
              work exactly like the method used by other (non  pattern  aware)
              tar(1)  implementations.  File type select patterns do not offer
              pattern matching but allow to restore subtrees.   To  extract  a
              complete  sub  tree  from  the directory dir with star using the
              pattern= option, use pattern= dir/\* if you  like  to  select  a
              subtree  by  using  the  historic  method, use dir/ as file type
              argument.  See manual page for match(1) for more details of  the
              pattern   matcher.   All  patterns  are  selection  patterns  by
              default. To make them exclude patterns, use the -not or  the  -V
              option.

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

       -refresh_old_files
              obsoleted by -refresh-old-files

       -refresh-old-files

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

       -remove_first
              obsoleted by -remove-first

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

       -remove_recursive
              obsoleted by -remove-recursive

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

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

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

       -signed_checksum
              obsoleted by -signed-checksum

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

       -silent
              Suppress informational messages like foobar is sparse.

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

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

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

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

       tsize=#
              Set  tape  volume size to # to enable multi volume tape support.
              See bs= for the possible syntax.  By default, the number is mul-
              tiplied by 512, so the value counts in units of 512 byte blocks.
              If the size specifier ends with a valid multiplication character
              (e.g  '.' for bytes or 'M' for MB) the specified size is used as
              specified and not  multiplied  by  512.   With  this  option  in
              effect, star is able to archive filesystems that are bigger then
              the tape size.  Files that do not fit on a single tape  may  not
              be stored with the current version of star.

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

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

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

       -version
              Print version information and exit.

       VOLHDR=name
              Use name to generate a volume header.

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

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

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

       Star   waits  up  to  one  minute for the drive to become ready if this
              option is specified.  -wready This option tells Star waits up to
              two minutes for the drive to become ready.  It has been added as
              a hack for a bug in the SunOS/Solaris  st  device  driver.  This
              driver  has  problems  to  sense  the  loading time with Exabyte
              drives with factory  settings.   It  also  makes  sense  to  use
              -wready  if  multiple remote backups are made. In this case, the
              remote connection is closed while  the  remote  tape  server  is
              still  writing  a file mark.  If another remote backup is initi-
              ated 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.

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

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

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


SIGNALS
       If star handles a signal, it first prints the statistics.  Star handles
       the following signals:

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

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

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


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

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

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

              example% star tvf /dev/rmt/1mbn

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

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

       or by using the change directory option of star:

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

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

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

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

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

       To compare two directory trees one might use:

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

       To compare all properties of two file trees, use:

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

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

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

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

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

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

              example% star -zxp -C /tmp f=star-1.1.tar.gz

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

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

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

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

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

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

       Pat,  in this case should match the tarfile in the tarfile on tape that
       should be extracted.

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

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

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

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

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

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

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

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

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

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

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

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


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

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

FILES
       Currently  none except the files implied be the command line from star.

       In future, star may use /etc/default/star to set up global defaults.

SEE ALSO
       tar(1),  cpio(1),  rcp(1),  mt(1),  rmt(1),  match(1),  dd(1),  sdd(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  POSIX  command  line  syntax for the tar command 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 POSIX 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 com-
       mand and includes a compatibility mode that allows to specify a command
       line  syntax  as  documented for the POSIX 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
       POSIX  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 POSIX.

       Star strips leading ./ sequences from pathnames. This lets star in many
       cases store longer pathnames than other implementations.

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

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

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

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

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

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

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

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

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

       Old  versions  of  tar  found  on  SYSVr3  and  earlier cannot read tar
       archives with a blocksize greater than 10 kBytes.

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

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

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

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

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

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

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.

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

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

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

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

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

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


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

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


AUTHOR
       Joerg Schilling
       Seestr. 110
       D-13353 Berlin
       Germany

       Mail bugs and suggestions to:

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



Joerg Schilling                    02/08/10                            STAR(1)