Unix/Linux Go Back    


CentOS 7.0 - man page for star (centos section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

NAME
       star - unique standard tape archiver

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

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

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

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

       Note that unpacking tar archives may be a security risk because star may overwrite  exist-
       ing files.  See SECURITY NOTES for more information.

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

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

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

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

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

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

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

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

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

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

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

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

       Star automatically recognizes and handles compressed archives inside plain files.

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

COMMAND
       In native mode, star is compatible to the command line syntax of a typical  POSIX  command
       and  for this reason expects commands and options to start with a single dash (-). In this
       case, commands and options may be specified separately,	all  boolean  or  increment  type
       options	may  be specified either separately or combined.  For compatibility with GNU pro-
       grams, 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  begin-
	      ning  of tarfile.  See -v option for information on how to increase verbosity while
	      the archive is written.

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

	      If the option -diff has been specified in addition, star performs a one pass direc-
	      tory  tree  compare  instead  of	copying files.	The shorthand -c -diff instead of
	      -copy -diff is also allowed.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	      See SECURITY NOTES for more information.

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

	      See SECURITY NOTES for more information.

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

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

       -0

       -1

       -2

       -3

       -4

       -5

       -6

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

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

       artype=headertype
	      Generate	a  tape  archive  in  headertype  format.   If	this  option  is  used in
	      extract/list mode this forces star to interpret the headers to be of  type  header-
	      type.   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 enhance-
			ment 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 ar-
			chive special files (even sockets) and records access time  and  creation
			time besides the modification time. Newer versions of the old star format
			allow very long filenames (100+155 chars  and  above),	linknames  >  100
			chars and sparse files (if -sparse is used).  This format is able to copy
			the device nodes on HP-UX that have 24 bits in the minor  device  number,
			which	is   more   then   the	 21  bits  that  are  possible	with  the
			POSIX-1003.1-1988 archive format.

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

	      gnutar	This  is a commonly used, but unfortunately not Posix compliant (although
			designed after 1987) enhancement to the old tar format.  The gnutar  for-
			mat  has  been	defined between 1989 and 1994.	Do not use the gnutar ar-
			chive format unless you want to create an archive  for	a  target  system
			that  is known to have only the gnutar program available.  The gnutar ar-
			chive 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 implementa-
			tion 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	Interchange format.  With
			this option in effect, star will generate 100% POSIX.1-1988 compliant tar
			archives.   Files  with  pathnames longer than 100+155 chars or linknames
			longer than 100 chars may not be archived.  If star is	called	as  ustar
			the default archive format is ustar.

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

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

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

	      xstar	The extended standard tar format has been introduced in 1994.  Star  uses
			the  xstar  format as default archive format.  This is an upward/downward
			compatible enhancement of  the	IEEE/Posix1003/IEC-9945-1  Standard  Data
			Interchange   format.	 It  allows  among  others  very  long	filenames
			(100+130 chars and above) and records  access  time  and  creation  time.
			Sparse files will be archived correctly (if -sparse is used).

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

			The xstar format is the default format when star is neither called as tar
			nor called as ustar.

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

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

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

			The  exustar  format allows to archive all file types but it does not ar-
			chive 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 interoperabil-
			ity  problems.	Try to avoid this format.  It is only present to make the
			scpio command SVr4 compliant.

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

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

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

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

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

	      crc	This format is similar to the asc cpio format but in addition uses a sim-
			ple  byte  based  checksum  called here as CRC.  This algorithm is simple
			Sum32 -- not a polynomial CRC.	Try  to  avoid	the  crc  archive  format
			because of its limited portability.

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

       -ask_remove
	      obsoleted by -ask-remove

       -ask-remove
	      Ask  to  remove  non writable files on extraction.  By default, star will not over-
	      write 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 modi-
	      fication time. (This works only in conjunction with the star, xstar, xustar,  exus-
	      tar,  and  with  the pax format.)  Another option to retain the access time for the
	      the files that are going to be archives is to readonly mount a UFS snapshot and  to
	      archive files from the mount point of the UFS snapshot.

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

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

		   mt fsr blockno

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

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

		     star: Blocksize = # records.

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

       bs=#   Set output block size to #.  You may use the same method as in  dd(1)  and  sdd(1).
	      The  number representing the size is taken in bytes unless otherwise specified.  If
	      a number is followed directly by the letter `.', `w', `b', `k', `m', `g',  `t',  or
	      `p',  the  size  is  multiplied  by  1,  2,  512,  1024, 1024*1024, 1024*1024*1024,
	      1024*1024*1024*1024 or 1024*1024*1024*1024*1024.	If the size consists  of  numbers
	      separated  by  `x'  or  `*',  multiplication of the two numbers is performed.  Thus
	      bs=7x8k will specify a blocksize of 56 kBytes.  Blocksize must be a multiple of 512
	      bytes.   See  also the description of the blocks= option for more details on 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 decompression option to extract.

       C=dir

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

	      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 current working directory after storing one file argument
		     that immediately follows the -C option, star changes the directory only if a
		     new -C option follows.  To emulate the behavior of a BSD derived tar(1), add
		     a -C .  option after the file argument.

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

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

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

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

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

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

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

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

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

	      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 when in create mode.	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 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  condi-
	      tion as a warning only that does not cause a non zero exit code.	A warning message
	      is still written if the condition is not otherwise ignored by another rule from  an
	      errctl=  option.	 The  -data-change-warn option works as if the last error control
	      option was

		   errctl="WARN|GROW|SHRINK *"

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

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

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

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

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

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

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

	      mode	Same as perm.

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

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

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

	      uid	Compare numerical user id of file.

	      gid	Compare numerical group id of file.

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

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

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

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

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

	      cont	Same as data.

	      rdev	Compare major/minor numbers for device nodes.

	      hardlink	Compare target of hardlinks.

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

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

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

	      sparse	Compare if either both files are sparse or not. If only one of both files
			is sparse, then a difference is flagged.  This only works with if the ar-
			chive format is star, xstar, xustar, exustar, or gnutar.

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

	      mtime	Compare modification time of file.

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

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

	      times	Shorthand for: atime,mtime,ctime.

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

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

	      acl	Compare access control lists.  This only works if the archive is in exus-
			tar 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 exus-
			tar format and has been created with star's -xfflags option.  You need to
			specify the -xfflags option in addition when running the diff.

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

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

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

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

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

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

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

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

       -dump-cumulative
	      instructs star to perform incremental dumps relatively to the last incremental dump
	      of the same level.  Incremental dumps with a level higher than 0 are normally  done
	      relatively to the content of a previous dump with lower level. If incremental dumps
	      and restores are going to be used to synchronize filesystem content, every  succes-
	      sive  incremental  dump will increase in size if -dump-cumulative is not used.  See
	      section SYNCHRONIZING FILESYSTEMS for more information.

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

       -dumpmeta
	      changes the behavior of star in incremental dump mode.  If -dumpmeta  is	used  and
	      only  the  inode	change	time (st_ctime) of a file has been updated since the last
	      incremental dump, star will archive only the meta data of the file (e.g. uid,  per-
	      missions,  ...)  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  incre-
	      mental 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 con-
	      trol spec to the error control definitions.  More than one error control	file  and
	      more than one error control spec as well as a mixture of both forms is possible.

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

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

	      The  error control file contains a set of lines, each starting with a list of error
	      conditions to be ignored followed by white space followed by a  file  name  pattern
	      (see  match(1)  or  patmatch(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 possible to have new line characters in the file name pattern.
	      Whenever an error situation is encountered, star checks the lines in the error con-
	      trol file starting from the top.	If the current error condition	is  listed  on	a
	      line in the error control file, then star checks whether the pattern on the rest of
	      the line matches the current file name.  If this is the case, star uses the current
	      error control specification to control the current error condition.

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

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

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

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

	      ALL	  This is a shortcut for all error conditions below.

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

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

	      OPEN	  Suppress warnings about files that could not be opened.

	      READ	  Suppress warnings read errors on files.

	      WRITE	  Suppress warnings write errors on files.

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

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

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

	      MISSLINK	  Suppress  warnings about files for which star was unable to archive all
			  hard links.

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

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

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

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

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

	      SETMODE	  Suppress  warnings  about  files  on that star could not set the access
			  modes during extraction.

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

	      LSECURITY   Suppress  warnings  about  links  that  have been skipped on extraction
			  because they have been considered to be a  security  risk.   This  cur-
			  rently  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 con-
			  trol 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 infor-
			  mation during extraction.

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

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

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

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

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

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

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

       file=tarfilename, f=tarfilename
	      Use  tarfilename as the name for the tar archive. Currently up to 100 file= options
	      are possible. Specifying more then one file= option  make  sense	in  multi  volume
	      mode.  In  this  case  star  will  use the next name in the list every time a media
	      change is needed.  To make star behave consistent with the single file  case,  star
	      loops  over  the	list of known archive files.  Note that if star is installed suid
	      root and the first tarfile is a remote archive, only the connection to this archive
	      will  be	created with root privileges.  After this connection has been established
	      as root, star switches back to the id of the caller.  If any of the other  archives
	      in  the list is located on a different host, star will not be able to open this ar-
	      chive 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 sym-
	      bolic open modes, it does not open a remote tape with the O_CREAT open flag because
	      this would be extremely dangerous.  If the rmt server on the other side is the  rmt
	      server  that  comes with star or the GNU rmt server, star may use the symbolic mode
	      for the open flags.  Only the symbolic open modes allow to send all  possible  open
	      modes in a portable way to remote tape servers.

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

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

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

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

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

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

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

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

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

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

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

	      The command line:

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

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

	      The command line:

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

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

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

       -force_hole
	      obsoleted by -force-hole

       -force-hole
	      Try to extract all files with holes. This even works with files  that  are  created
	      without  the  -sparse option.  Star, in this case examines the content of the files
	      in the archive and replaces writes to parts containing binary zeroes with seeks.

	      If used together with the -sparse option in create mode, star assumes all files  to
	      be sparse and archives files with blocks of nulls as sparse files.

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

       -force-restore
	      Force  an  incremental restore even if the incremental dump is only a partial dump.
	      See -wtardumps, level= and section INCREMENTAL BACKUPS for more information.

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

       fs-name=mount_point
	      Use  mount_point	when  recording  information  in /etc/tardumps and when comparing
	      against information in /etc/tardumps for incremental  backups.   This  makes  sense
	      when  backups are made using file system snapshots and allows /etc/tardumps and the
	      archive to contain the real name of the file system instead of the temporary  mount
	      point that is used for the snapshot device.

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

       -h, -L Follow symbolic links as if they were files.  Normally star will	not  follow  sym-
	      bolic 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 sym-
	      link is encountered in the archive.  In create mode, this option tells star to  try
	      to archive a hardlink whenever a symlink is encountered in the file system.

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

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

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

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

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

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

       -keep_old_files
	      obsoleted by -keep-old-files

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

	      See SECURITY NOTES for more information.

       -L, -h Follow symbolic links as if they were files.  Normally star will	not  follow  sym-
	      bolic 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) implementa-
	      tions 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.  The dumplevel may be in the range between 0..99.

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

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

       -link-data
	      In create mode, include the data for files even if these files are hard links. This
	      feature  in  create mode is currently only available for the exustar archive format
	      and only in case -sparse has not been specified.

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

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

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

	      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 directo-
	      ries, all known operating systems require the extraction to  be  done  as  root  in
	      order  to  be  able to create or remove hard links to directories.  For this reason
	      its only recommended to use this option when doing accurate backups and  when  hard
	      links to directories are expected.

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

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

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

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

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

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

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

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

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

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

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

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

	      The problems result from the only current fallback in the POSIX standard that tells
	      tar implementations to treat all unknown file types as if they were plain files. As
	      meta  files  are needed for incremental backups, I am looking for people and compa-
	      nies 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  implementa-
	      tions insist in reading such nonstandard archives.

       -multivol
	      Switch  to  multi  volume mode.  In multi volume mode, there will be no logical EOF
	      marker written to the end of a single tape. If -multivol is used in  read  mode,	a
	      hard EOF on input (if not preceded by a logical EOF) triggers a medium change oper-
	      ation.

	      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. incremental dump/restore
	      operations where inode numbers need to be traced for the whole task.

	      When tsize=# has been specified, but star is not in multi volume mode, files cannot
	      be split across volumes.

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

	      Depending on the selected archive format, star writes a volume header at the begin-
	      ning  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 environ-
	      ment, 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 mod-
	      ification 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.   His-
	      toric  tar  archive  formats  did only allow to specify plain files and hard links.
	      Around 1980, BSD added a feature to specify a directory on tape by adding  a  slash
	      to  the end of the name. POSIX.1-1988 defined the first official tar archive format
	      that had a clean method to specify the type of a directory.   As	old  tar  formats
	      need  the  slash to recognize a directory, -no-dirslash may not be used if archives
	      should be compatible with the old tar format.

       -no_fifo
	      obsoleted by -no-fifo

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

       -no-fsync
	      Do not call fsync(2) for each file that has been extracted from the archive.  Using
	      -no-fsync may speed up extraction on operating systems with slow file I/O (such  as
	      Linux),  but includes the risk that star may not be able to detect extraction 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 permissions.  This option is
	      needed only if star is called by the super user and the permissions should  not  be
	      restored	from  the  archive.   See also the -p option. The -p options has a higher
	      precedence than the -no-p option.

       -no_statistics
	      obsoleted by -no-statistics

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

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

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

       -notarg, -pax-c
	      Match all file or archive members except those specified by the pattern or file op-
	      erands.

       -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 nei-
	      ther that archives generated with this option are binary equal with archives gener-
	      ated  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 -signed-checksum option too.  If you  want
	      directories  not	to be archived in order to be compatible to very old historic tar
	      archives, you need to specify the -d option too.

	      This option is superseeded by the H=headertype option.

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

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

       -P     Allow star to write a partial record as the last	record.   Normally,  star  writes
	      each record with the same size.  This option is useful on unblocked tapes i.e. car-
	      tridge 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 spec-
	      ified.   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 argu-
	      ment  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 inter-
	      preted 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 pat-
	      tern 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  argu-
	      ment.   If  you  only  like  to extract the directory itself, use dir/ as file type
	      argument.  See manual page for match(1) for more details of  the	pattern  matcher.
	      All  patterns are selection patterns by default. To make them exclude patterns, use
	      the -not or the -V option.

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

       -pax-c, -notarg
	      Match all file or archive members except those specified by the pattern or file op-
	      erands.

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

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

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

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

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

       -pax-match
	      Allow file type arguments to be recognised as regular expressions in a way that has
	      been defined for POSIX pax.

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

       -pax-p string
	      PAX style privileges string.  Several characters (each has its  own  meaning).  The
	      following characters are defined:

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

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

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

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

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

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

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

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

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

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

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

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

       -read0 Read null terminated file names from the file specified with the list= option.

       -refresh_old_files
	      obsoleted by -refresh-old-files

       -refresh-old-files

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

       -remove_first
	      obsoleted by -remove-first

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

       -remove_recursive
	      obsoleted by -remove-recursive

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

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

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

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

       -s replstr
	      Modify file or archive member names named by a pattern according to  the	substitu-
	      tion 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 spe-
	      cial character '&'. The character '&' is substituted by the string that matches the
	      old  pattern.   The  optional trailing 'g' means global substitution. If 'g' is not
	      used, a substitution pattern is only used once on a name.  If the optional trailing
	      'p' is used, the substitution is printed to standard error.

	      Up  to  100  substitute options may be used. If more than one substitute option has
	      been specified, star will loop over all substitute patterns until one matches.

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

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

	      As the usability of a tar archiver would be limited if -secure-links checking would
	      be done by default, star makes link checking optional.

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

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

       -signed_checksum
	      obsoleted by -signed-checksum

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

       -silent
	      Suppress informational messages like foobar is sparse.

       -sparse
	      Handle files with holes effectively on store/create.  Note that  sparse  files  may
	      not  be  archived this way if the archive format is tar, ustar, suntar, pax, or any
	      cpio variant.  On Solaris-2.3 ... Solaris-2.5.1 there is a special  ioctl()  called
	      _FIOAI that allows root to get the allocation info more efficiently.  On Solaris 11
	      there is an enhanced lseek(2) call with  addidional  whence  values  SEEK_HOLE  and
	      SEEK_DATA  that  allow  to find holes in an efficient way.  Other operating systems
	      lack support to get the real allocation list and force star to scan  the	files  to
	      look  for  blocks that only contain null characters.  This may star cause to assume
	      more holes to be present than the number that the file really contains.

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

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

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

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

       -to_stdout
	      obsoleted by -to-stdout

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

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

       tsize=#
	      Set tape volume size to # to enable multi volume tape support.  The value refers to
	      the archive size without	compression.   See  bs=  for  the  possible  syntax.   By
	      default,	the number is multiplied by 512, so the value counts in units of 512 byte
	      blocks.  If the size specifier ends with a valid multiplication character (e.g  '.'
	      for bytes or 'M' for MB) the specified size is used as specified and not multiplied
	      by 512.  With this option in effect, star is able to archive filesystems	that  are
	      bigger  then  the  tape size.  If the option tsize=# without -multivol then no file
	      will be split across volumes and each volume may in theory be read back separately.
	      Files  that do not fit on a single tape may not be stored in this mode.  If -multi-
	      vol 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 mul-
	      tiple of the tape block size.

	      See -multivol option for more information.

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

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

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

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

       -version
	      Print version information and exit.

       VOLHDR=name
	      Use name to generate a volume header.

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

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

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

       See SECURITY NOTES for more information.

       Note  that  -w is an interactive option that prevents star from being used in non-interac-
       tive 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 tardumps=name and -C option or INCREMENTAL BACKUPS  section  for
	      more information.

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

       -xattr

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

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

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

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

       -xdir  Extract directories even if the corresponding directories on the	archive  are  not
	      newer.   This  is  useful  when for some reason, the directories are recorded after
	      their content (see -dirmode option), or when the permissions  of	some  directories
	      must  be	set  in  any case.  As the classical UNIX cpio program does not implement
	      delayed directory permission and time stamp setting, cpio users  often  create  ar-
	      chives in reverse order (directories past their content). For this reason, it makes
	      sense to use -xdir while extracting cpio archives.

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

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

       -xmeta Extract meta files as if they were files.  Meta files in archives are  plain  files
	      that  do not contain any content data in the archive.  They may be created by using
	      the -meta option in star's create mode.  Existing files are not overwritten.  If	a
	      file  is	missing,  a  zero  sized  file	is  created.  If the option -meta is used
	      together with the option -force-hole, missing plain files  are  created  as  sparse
	      empty files of the original size.

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

       -Z     run the input or output through a compress pipe - see option -z below.

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

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

       To be more verbose:

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

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

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

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

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

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

       To create a level 0 dump call:

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

       To create a level 1 dump call:

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

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

       Backups	from  live filesystems should be avoided.  On operating systems that support file
       system snapshots, backups should be made from a read-only mount of a snapshot. Be  careful
       that all files that have been created between setting up a snapshot and starting an incre-
       mental 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 cre-
       ated  and  mounted on /mnt.  The following star command then creates a level 0 backup from
       the file system using the time the snapshot was created and the original  mount	point  of
       the file system for /etc/tardumps and the archive header.

       Note  that  if  the  backup is done on a live file system, it may be unreliable. A typical
       problem problem in this context is caused by growing log files.	As growing files are  not
       a  real	problem  with  backups, the best way of dealing with growing files is to set up a
       star error control file (see errctl= option) and to tell star to ignore growing files.

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

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

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

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

       Note that in this case, 7 dumps need to be restored if the a crash happens  at  the  worst
       case date (just before the Friday dump in week 2 or later).

INCREMENTAL RESTORES
       Incremental  restores  should  be  made to an empty file system (except for the lost+found
       directory).  Star is currently unable to perform incremental restores  to  a  file  system
       that contains active mount points.

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

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

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

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

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

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

       To extract a level 0 dump call:

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

       This creates the directory star-tmpdir and the database star-symtable in the  root  direc-
       tory  of  the  new  file  system.  Subsequent restores with higher level backups depend on
       these files.

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

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

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

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

       To create an initial copy of a filesystem call:

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

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

       To copy incremental content of a filesystem call:

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

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

       See  section INCREMENTAL BACKUPS to learn how to modify the command line in case file sys-
       tem snapshots are used.

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

       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  ar-
		 chive,  star  finishes  with  the current file to ensure that no partial file is
		 written to the archive, write an eof record and then exits.

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

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

EXIT STATUS
       The following exit values are returned:

       0      All files were processed successfully.

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

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

       -1 / 255
	      Command line parsing error.

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

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

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

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

	      example% star tvf /dev/rmt/1mbn

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

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

       or by using the change directory option of star:

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

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

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

       To  copy  a  file tree including the Access Control List entries for all files and to cor-
       rectly 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@remote-
	      host:/dev/rmt/1bn .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	      Note that this forces star to create a pipe to the  rsh(1)  program  and	disallows
	      star  to	directly  access  the network socket to the remote server.  This makes it
	      impossible to set up performance parameters and slows down the connection  compared
	      to a root initiated rcmd(3) connection.

	      See BUGS section for more information.

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

FILES
       /etc/default/star
	      Default values can be set for the  following  options  in  /etc/default/star.   For
	      example: CDR_FIFOSIZE=64m

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

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

	      archive0=

	      archive1=

	      archive2=

	      archive3=

	      archive4=

	      archive5=

	      archive6=

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

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

		     Examples:

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

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

		     Example:

		     archive0=/dev/tape 256k 40G y

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

	      The  file  holds	one or more lines, each specifying a dump level entry.	Each dump
	      level entry starts with a mount point name followed by a TAB and one or  more  spa-
	      ces, followed by the decimal dump level, a space and the dump time.

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

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

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

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

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

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

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

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

SEE ALSO
       spax(1),  tar(1), cpio(1), pax(1), rcp(1), mt(1), rmt(8), match(1), dd(1), sdd(1), rsh(1),
       ssh(1), star(4), 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 syn-
       tax requests all options to start with a dash (-) and allows to either write options sepa-
       rately  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 compati-
       bility mode that allows to specify a command line syntax as documented for the UNIX-98 tar
       command.   If  you  believe  that you found a bug in the way star parses the command line,
       please first check your command line for correctness before you	make  a  bug  report  for
       star.

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

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

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

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

       The star, xstar, xustar, exustar, pax, and gnutar archive formats don't have these limita-
       tions. While gnutar uses a method that makes it impossible for other  tar  implementations
       (except	star)  to  restore  filenames  that are longer than 100 chars, the xstar, xustar,
       exustar and pax archive format uses a method that allows an POSIX.1-1988 compliant way  of
       storing	filenames, if the POSIX method would allow this.  When the archive format is xus-
       tar, 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 opera-
       tion 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 dif-
       ferent 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 exten-
       sible 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 exus-
       tar format however is higher.

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

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

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

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

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

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

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

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

       If  gnutar archives sparse files with more than four holes, it produces archives that vio-
       late 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  imple-
       ments  compression via a temporary file.  Using compression thus is limited by the maximum
       file size and the available disk space.

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

SECURITY NOTES
       If you unpack a tar archive in a non empty directory, any file in that  directory  may  be
       overwritten  unless  you specify the -k option.	If the archive contains symbolic links or
       hard links, star may even overwrite files outside the current directory.  If the directory
       where  the  archive  is been unpacked is not empty and contains contains symbolic links or
       hard links to directories outside that directory, star may also	overwrite  files  outside
       the  current directory.	As many other commands, star usually has all possible permissions
       when run as root.  Unpacking archives as root thus may have fatal results to any  file  on
       your system.  Be very careful when you try to extract an archive that has not been created
       by you. It is possible to create hand crafted tar archives  that  may  overwrite  critical
       files (like /etc/passwd) on your system.  In addition all tar archives that have been cre-
       ated 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(8) 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 spe-
       cific extension, up to 95 bits may be used to code the filesize.  This will  handle  files
       up  to  200,000,000  TB.   With	the new POSIX.1-2001 extended headers used by the xustar,
       exustar and pax format, any filesize may be archived.

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

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

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

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

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

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

       rsh    on SunOS-5.0...SunOS-5.9

       ssh    from ssh.com

       ssh    from openssh.org

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

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

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

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

AUTHOR
       Joerg Schilling
       Seestr. 110
       D-13353 Berlin
       Germany

       Mail bugs and suggestions to:

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

Joerg Schilling 			     11/04/12					  STAR(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:15 AM.