Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
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]
       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 functional-
       ity.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       Star automatically recognizes and handles  compressed  archives	inside
       plain files.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	      See SECURITY NOTES for more information.

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

	      See SECURITY NOTES for more information.

       -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 /usr/local/etc/star.  The	format
	      for  the	archive	 entries  is  the  same	 as  the   format   in
	      /usr/local/etc/tar in Solaris.

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

       artype=headertype
	      Generate a tape archive in headertype format.  If	this option is
	      used  in	extract/list  mode  this  forces star to interpret the
	      headers to be of type headertype.	 As star even  in  case	 of  a
	      user  selected  extract  archive format does format checking, it
	      may be that you will not be able to unpack  a  specific  archive
	      with  all	possible forced	archive	formats. Selecting the old tar
	      format for extraction will always	work though.  Valid  parameter
	      for headertype are:

	      help	Print a	help message about possible header types.

	      v7tar	Old  UNIX V7 tar format.  This archive format may only
			store plain files.  Pathnames or linknames longer than
			99 chars may not be archived.

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

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

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

	      star	Old star standard format. This is  an  upward/downward
			compatible enhancement of the old (pre Posix) UNIX tar
			format.	 It has	been introduced	in 1985	and  therefore
			is not Posix compliant.	 The star format allows	to 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 format has been
			defined	between	1989 and 1994.	Do not use the	gnutar
			archive	 format	 unless	 you want to create an archive
			for a target system that is known  to  have  only  the
			gnutar	program	 available.  The gnutar	archive	format
			violates basic rules for any (even the	historic)  tar
			archive	 format,  in  special  when  sparse  files are
			archived using the -sparse option.  Using  the	gnutar
			archive	 format	 causes	a high risk that the resulting
			archive	may only be read by gnutar or  by  star.   The
			implementation	of  the	 gnutar	 archive format	within
			star is	not complete, but sufficient for  most	gnutar
			archives.  See NOTES for more information.

	      ustar	IEEE/Posix1003/IEC-9945-1-1988	Standard  Data	Inter-
			change format.	With this option in effect, star  will
			generate  100%	POSIX.1-1988  compliant	 tar archives.
			Files with pathnames  longer  than  100+155  chars  or
			linknames  longer  than	100 chars may not be archived.
			If star	is called as ustar the default archive	format
			is ustar.

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

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

			If the pax format has been selected, star will not use
			enhancements  to  the POSIX.1-2001 tar format, the ar-
			chive 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  ar-
			chive  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	inter-
			fere  with  the	POSIX standard as the fields for mtime
			and ctime field	are always separated  from  the	 POSIX
			file  name prefix by a null byte.  The last 4 bytes of
			the tar	header contain a 'tar\0' signature.

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

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

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

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

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

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

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

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

	      bin	The cpio UNIX V7 binary	format.	 This is a format with
			big  interoperability problems.	Try to avoid this for-
			mat.  It is only present to  make  the	scpio  command
			SVr4 compliant.

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

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

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

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

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

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

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

       -ask_remove
	      obsoleted	by -ask-remove

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

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

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

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

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

		   mt fsr blockno

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

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

		     star: Blocksize = # records.

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

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

       -bsdchdir
	      Switch  the behavior of the C= option to BSD style.  The default
	      behavior of star is to stay in a working directory until	a  new
	      C=  is seen.  With BSD tar, the C= option	is only	related	to the
	      next file	type argument.

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

       C=dir

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

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

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

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

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

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

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

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

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

       -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 con-
	      fuse  programs  like  cron  and  the news	system.	 Although star
	      tries to eliminate the accumulative effects of the  time	storm,
	      there  is	 a  tendency  for the system clock to slow down	a bit.
	      The clock	typically lags about  one  millisecond	per  extracted
	      file.  Use with care and check the system	clock after using this
	      feature.

	      If used with the create command this changes the behavior	of the
	      newer=  option.	Star,  in  this	case compares the ctime	of all
	      files to the mtime of the	stamp file rather then	comparing  the
	      mtimes of	both files.

       -cumulative
	      A	shorthand for -dump-cumulative.	 See -dump-cumulative for more
	      information.

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

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

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

		   errctl="WARN|GROW|SHRINK *"

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

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

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

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

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

	      not	Invert the meaning of all members in the diffopts list
			i.e.  exclude  all  present  options from an 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  sys-
			tem use	different user or group	mappings.

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

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

	      cont	Same as	data.

	      rdev	Compare	major/minor numbers for	device nodes.

	      hardlink	Compare	target of hardlinks.

	      symlink	Compare	 target	 of symlinks. This evaluates the 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	 path-
			names look similar enough.

	      sympath	Compare	the target pathnames of	symlinks. This charac-
			terwise	compares the strings returned from  the	 read-
			link(2)	call.

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

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

	      mtime	Compare	modification time of file.

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

	      lmtime	Compare	 the modification time even in case the	target
			file on	the local filesystem is	a symbolic  link.   By
			default,  star	will not compare the modification time
			of symbolic links as most systems cannot set the 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  ver-
			bose  level (-vv) this will print a list of files that
			are only in the	archive	and a list of files  that  are
			only on	the current filesystem.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

		   errctl="ABORT|ALL|DIFF   *"

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

       errctl= name

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

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

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

	      The error	control	file contains a	set of	lines,	each  starting
	      with  a list of error conditions to be ignored followed by white
	      space followed by	a file name  pattern  (see  match(1)  or  pat-
	      match(3) for more	information).  The error control spec uses the
	      same syntax as a single line from	the error  control  file.   If
	      the  file	 name  pattern	needs to start with white space, use a
	      backslash	to escape the start of the file	name. It is not	possi-
	      ble to have new line characters in the file name pattern.	 When-
	      ever an error situation is encountered, star checks the lines in
	      the  error  control  file	starting from the top.	If the current
	      error condition is listed	on a line in the error	control	 file,
	      then  star  checks  whether  the pattern on the rest of the line
	      matches the current file name.  If this is the case,  star  uses
	      the  current  error control specification	to control the current
	      error condition.

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

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

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

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

	      ALL	  This is a shortcut for all error conditions below.

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

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

	      OPEN	  Suppress warnings about  files  that	could  not  be
			  opened.

	      READ	  Suppress warnings read errors	on files.

	      WRITE	  Suppress warnings write errors on files.

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

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

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

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

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

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

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

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

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

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

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

	      LSECURITY	  Suppress warnings about links	that have been skipped
			  on  extraction  because they have been considered to
			  be a security	risk.  This currently applies  to  all
			  link	names  that  start  with  '/' or have a	'/../'
			  sequence inside when -secure-links has  been	speci-
			  fied.	  In  this  case, star tries to	match the link
			  name against the pattern in the error	control	 file.

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

	      BADACL	  Suppress  warnings  access  control  list conversion
			  problems.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	      In order to make the evaluation of the find expression more con-
	      venient,	star  implements  additional  find primaries that have
	      side effects on the file meta data.  Star	implements the follow-
	      ing 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 permis-
		     sions  of	the  file to mode.  Octal and symbolic permis-
		     sions are accepted	for mode as with chmod(1).

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

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

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

	      The command line:

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

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

	      The command line:

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

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

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

       -force_hole
	      obsoleted	by -force-hole

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

       -force_remove
	      obsoleted	by -force-remove

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

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

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

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

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

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

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

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

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

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

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

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

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

       -keep_old_files
	      obsoleted	by -keep-old-files

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

	      See SECURITY NOTES for more information.

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

       -l     Do  not  print a warning message if not all links	to hard	linked
	      files could be dumped. This option is evaluated in the  opposite
	      way  to historic tar(1) implementations and to POSIX.1.  POSIX.1
	      requests that by default no warning messages will	be printed and
	      -l  will	enable	warning	 messages  when	not all	links could be
	      archived.

       level=dumplevel
	      Set level	for incremental	dumps.	This option is used to	switch
	      star  into  true incremental dump	mode.  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  par-
	      tial  dump.   If the directory following the -C option is	refer-
	      ring to a	root directory of a file system	and no other  restric-
	      tions  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 ar-
	      chive format.

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

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

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

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

       list=filename
	      Read filenames for store/create/list/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 sup-
	      port telldir(3)/seekdir(3), star will fail.

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

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

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

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

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

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

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

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

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

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

	      Specifying -multivol tells star to split files across volumes if
	      needed.	This way, a virtual archive is created that spans more
	      than one medium.	Multi volume mode is needed whenever it	is not
	      possible to split	the archiving or extracting into several logi-
	      cally independent	tasks.	This  is  true	for  e.g.  incremental
	      dump/restore  operations	where  inode numbers need to be	traced
	      for the whole task.

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

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

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

	      See tsize=# option for more information.

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

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

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

       -newest_file
	      obsoleted	by -newest-file

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

       new-volume-script=script
	      Call script at end of each tape if in  multi  volume  mode.   If
	      this  option is not in effect, star will ask the user to confirm
	      the volume change.  The script is	called	with  two  parameters.
	      The  first  parameter  is	 the next volume number	and the	second
	      parameter	is the next archive file name.

       -nodump
	      If this option is	set, star will not dump	files  that  have  the
	      nodump  flag set.	Note that this currently only works on BSD-4.4
	      derivates	and on Linux.  On Linux, using this option will	 cause
	      a	 performance  degradation  (the	 system	time increases by 10%)
	      because of the unlucky kernel interface.

       -no-dirslash
	      Do not add a slash to the	end of directory names if  writing  to
	      an  archive.   Historic  tar  archive  formats did only allow to
	      specify plain files and hard links.  Around 1980,	 BSD  added  a
	      feature  to specify a directory on tape by adding	a slash	to the
	      end of the name. POSIX.1-1988 defined the	first official tar ar-
	      chive  format  that  had a clean method to specify the type of a
	      directory.  As old tar formats need the  slash  to  recognize  a
	      directory,  -no-dirslash	may  not be used if archives should be
	      compatible with the old tar format.

       -no_fifo
	      obsoleted	by -no-fifo

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

       -no-fsync
	      Do not call fsync(2) for each file that has been extracted  from
	      the archive.  Using -no-fsync may	speed up extraction on operat-
	      ing systems with slow file I/O (such as Linux), but includes the
	      risk  that  star	may  not be able to detect extraction problems
	      that occur after the call	to close(2).  A	typical	cause for such
	      problems	is  a  NFS file	system that fills up before the	buffer
	      cache is synced or a write error that occurs  while  the	buffer
	      cache  is	synced.	 There may be other reasons.  Use with extreme
	      care.

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

       -no-p  Do not restore files and directories to their  original  permis-
	      sions.   This  option  is	 needed	 only if star is called	by the
	      super user and the permissions should not	be restored  from  the
	      archive.	 See  also  the	-p option. The -p options has a	higher
	      precedence than the -no-p	option.

       -no_statistics
	      obsoleted	by -no-statistics

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

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

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

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

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

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

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

	      This option is superseeded by the	H=headertype option.

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

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

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

       -p     Restore  files  and  directories	to their original permissions.
	      Without this option, they	are created using the  permissions  in
	      the  archive and the present umask(2).  If star is called	by the
	      super user, star behaves as if it	has been called	 with  the  -p
	      option.  See  also -no-p option.	If the archive contains	Access
	      Control Lists (ACLs) in POSIX.1-2001 extended headers, star will
	      restore  the  access control lists from the archive for files if
	      the -acl option is specified.  If	the option -acl	has  not  been
	      specified, ACLs are not restored at all.

       pattern=pattern,	pat=pattern
	      Set  matching  pattern to	pattern.  A maximum of 100 pattern=pat
	      options may be specified.	  As  each  pattern  is	 unlimited  in
	      length, this is no real limitation.  If more than	one pattern is
	      specified, a file	 matches  if  any  of  the  specified  pattern
	      matches.	 Patterns  may	be  used  in  create mode to select or
	      exclude files from the list of file type arguments or the	 files
	      located  in  a  sub  tree	of a file type argument	directory.  By
	      default, star scans the whole directory tree underneath a	direc-
	      tory that	is in the argument list. This may be modified by using
	      the -match-tree option.  In extract or list mode,	all file  type
	      arguments	 are  interpreted  to be select	pattern	and all	option
	      type patterns may	be either select or exclude patterns depending
	      on  the presence or absence of the -not option.  If you use file
	      type select patterns, they work exactly like the method used  by
	      other  (non  pattern  aware)  tar(1) implementations.  File type
	      select patterns do not  offer  pattern  matching	but  allow  to
	      restore  subtrees.   To  extract	a  complete  sub tree from the
	      directory	dir with star using the	pattern= option, use  pattern=
	      dir/\*  if  you  like  to	select a subtree by using the historic
	      method, use dir as file type argument.   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 per-
	      missions,	 the  uid  and	gid  values  from  the	content	of the
	      pkglist= file.  Each line	from the pkglist= file contains	a file
	      name  followed  by the permission, a user	name and a group name.
	      The permission is	an octal character string.  Each value that is
	      not  used	 to overwrite the original values may be replaced by a
	      '?'.  The	fields are separated by	spaces,	so the pkglist=	option
	      does not allow files that	contain	newline	or space characters.

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

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

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

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

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

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

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

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

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

	      a	     Do	not preserve file access times.	 This option  is  cur-
		     rently ignored.

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

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

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

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

       -prinodes
	      Print inode numbers in verbose list mode if the archive contains
	      inode 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 ar-
	      chive.  This is needed if	you want to change the file type or if
	      you  need	 to  break  a  hard  link.   If	 you do	not use	either
	      -ask-remove or -force-remove together with  -remove-first,  this
	      option is	useless	and no files will be removed.

       -remove_recursive
	      obsoleted	by -remove-recursive

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

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

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

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

       -s replstr
	      Modify file or archive member names named	by a pattern according
	      to  the  substitution expression replstr.	 The format of replstr
	      is:

		   -s /old/new/[gp]

	      The old pattern may use regular expressions and the  new	string
	      may contain the special character	'&'. The character '&' is sub-
	      stituted by the  string  that  matches  the  old	pattern.   The
	      optional	trailing  'g' means global substitution. If 'g'	is not
	      used, a substitution pattern is only used	once on	 a  name.   If
	      the  optional  trailing 'p' is used, the substitution is printed
	      to standard error.

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

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

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

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

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

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

       -signed_checksum
	      obsoleted	by -signed-checksum

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

       -silent
	      Suppress informational messages like foobar is sparse.

       -sparse
	      Handle files with	holes effectively on store/create.  Note  that
	      sparse  files may	not be archived	this way if the	archive	format
	      is tar, ustar, 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 sym-
	      link whenever a hardlink is encountered in the archive.

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

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

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

       -to_stdout
	      obsoleted	by -to-stdout

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

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

       tsize=#
	      Set tape volume size to #	to enable multi	volume	tape  support.
	      The  value  refers to the	archive	size without compression.  See
	      bs= for the possible syntax.  By default,	the number  is	multi-
	      plied  by	 512, so the value counts in units of 512 byte blocks.
	      If the size specifier ends with a	valid multiplication character
	      (e.g  '.'	for bytes or 'M' for MB) the specified size is used as
	      specified	and not	 multiplied  by	 512.	With  this  option  in
	      effect, star is able to archive filesystems that are bigger then
	      the tape size.  If the option tsize=# without -multivol then  no
	      file  will be split across volumes and each volume may in	theory
	      be read back separately.	Files that do not fit on a single tape
	      may not be stored	in this	mode.  If -multivol has	been specified
	      in addition, star	will split files when the maximum allowed tape
	      size  has	been reached.  If the tape volume size is not a	multi-
	      ple of the tape block size, the tape  volume  size  is  silently
	      rounded  down  to	 a  value that is a multiple of	the tape block
	      size.

	      See -multivol option for more information.

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

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

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

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

       -version
	      Print version information	and exit.

       VOLHDR=name
	      Use name to generate a volume header.

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

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

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

       See SECURITY NOTES for more information.

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

       -wready
	      This  option  tells Star to wait up to two minutes for the drive
	      to become	ready.	It has been added as a hack for	a bug  in  the
	      SunOS/Solaris  st	 device	 driver.  This	driver has problems to
	      sense the	loading	time with Exabyte  drives  with	 factory  set-
	      tings.   It  also	 makes sense to	use -wready if multiple	remote
	      backups are made.	In this	case, the remote connection is	closed
	      while  the  remote tape server is	still writing a	file mark.  If
	      another remote backup is initiated before	the old	remote	server
	      did  finish  to  write  the file mark, it	would be impossible to
	      open the tape driver unless -wready is specified to tell star to
	      wait for the drive to become ready again.

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

       -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 sepa-
	      rate line.  Be careful with white	space and note that path names
	      in  the list may not contain new lines.  Multiple	-X options may
	      be used. Each argument must refer	 to  a	file  containing  path
	      names.   The  -X option has precedence before other options that
	      select files to be included in the operation.   See  also	 list=
	      option.

       -xattr

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

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

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

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

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

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

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

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

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

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

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

       To be more verbose:

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

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

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

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

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

       echo > /tmp/snapstamp

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

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

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

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

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

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

       The level 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 hap-
       pens  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	incre-
       mental restores to a file system	that contains active mount points.

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

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

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

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

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

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

       To extract a level 0 dump call:

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

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

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

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

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

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 snap-
       shots,  copies  should be made from a read-only mount of	a snapshot. Be
       careful that all	files that have	been  created  between	setting	 up  a
       snapshot	 and  starting	an  incremental	 copy  may be missing from all
       copies unless the dumpdate=name option is used.

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

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

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

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

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

EXIT STATUS
       The following exit values are returned:

       0      All files	were processed successfully.

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

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

       -1 / 255
	      Command line parsing error.

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

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

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

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

	      example% star tvf	/dev/rmt/1mbn

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

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

       or by using the change directory	option of star:

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

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

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

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

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

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

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

       To compare two directory	trees one might	use:

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

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

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

       To compare all properties of two	file trees, use:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	      example#	 env   RSH=/usr/bin/ssh	  star	 -cM   fs=128m	bs=63k
	      f=tape@remotehost:/dev/rmt/1bn .

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

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

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

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

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

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

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

       If you like to archive all directories only that	are part of the	direc-
       tory 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 max-
	      imum compression,	you may	set the	environment variable STAR_COM-
	      PRESS_FLAG to -9.

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

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

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

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

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

	      See BUGS section for more	information.

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

FILES
       /usr/local/etc/star
	      Default  values  can  be	set  for  the  following  options   in
	      /usr/local/etc/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 /usr/local/etc/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.   ar-
		     chive0=/dev/tape).	  The second is	the blocking factor in
		     512 byte units.  The third	is the maximum media  size  in
		     1024  byte	 units.	  If this entry	contains a 0, then the
		     media size	is unlimited.  The fourth entry	 is  optional.
		     If	it contains a 'n' or a 'N', then the archive device is
		     not a tape.

		     Examples:

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

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

		     Example:

		     archive0=/dev/tape	256k 40G y

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

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

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

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

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

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

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

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

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

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

SEE ALSO
       spax(1),	suntar(1), scpio(1), tar(1), cpio(1), pax(1),  rcp(1),	mt(1),
       rmt(1),	match(1),  dd(1),  sdd(1), rsh(1), ssh(1), star(4/5), rcmd(3),
       fssnap(1m)

DIAGNOSTICS
       star: f records + p bytes (total	of x bytes = d.nnk).

       The number of full records, the number of bytes in partial records  and
       the total amount	of data	in KBytes.

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

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

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

NOTES
       The command line	syntax for the tar command  (as	 defined  in  SUSv2  -
       UNIX-98)	 deviates  from	 the command line syntax defined for all other
       commands. While the POSIX command line syntax requests all  options  to
       start  with a dash (-) and allows to either write options separately or
       combined	(in case of  boolean  flags),  the  tar	 command  line	syntax
       requires	 all options to	be combined into a single string that does not
       start with a dash.  Star	by default assumes a command line syntax  like
       a  typical  POSIX command and includes a	compatibility mode that	allows
       to specify a command line syntax	as documented for the UNIX-98 tar com-
       mand.   If  you believe that you	found a	bug in the way star parses the
       command line, please first check	 your  command	line  for  correctness
       before you make a bug report for	star.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       Note  that  on  operating systems (like DOS) that do not	implement real
       pipes, star implements compression via a	temporary  file.   Using  com-
       pression	 thus  is  limited  by the maximum file	size and the available
       disk space.

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

SECURITY NOTES
       If you unpack a tar archive in a	non empty directory, any file in  that
       directory  may be overwritten unless you	specify	the -k option.	If the
       archive contains	symbolic links or hard links, star may even  overwrite
       files  outside  the  current directory.	If the directory where the ar-
       chive 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 com-
       mands,  star  usually  has  all	possible permissions when run as root.
       Unpacking archives as root thus may have	fatal results to any  file  on
       your  system.   Be very careful when you	try to extract an archive that
       has not been created by you. It is possible to create hand crafted  tar
       archives	 that  may overwrite critical files (like /etc/passwd) on your
       system.	In addition all	tar archives that have been created  with  the
       list=  option  and  tar	archives where the C= option was not specified
       before all file type arguments may be critical.

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

SUID NOTES
       If star is installed suid root, star is able  to	 make  connections  to
       remote  archives	for non	root users.  This is done by using the rcmd(3)
       interface to get	a connection to	a rmt(1) server.

       Star resets its effective uid back to  the  real	 user  id  immediately
       after  setting  up  the	remote connection to the rmt server and	before
       opening any other file.

       If star has not been installed suid root	and not	 called	 by  root,  it
       will  try to create the remote connection via rsh(1) or ssh(1) (in case
       the environment RSH has been set	to ssh).  Note that in this case,  the
       throughput  to  the  remote  tape server	will be	much lower than	with a
       connection that has been	initiated via rcmd(3).

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

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

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

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

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

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

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

       rsh    on SunOS-5.0...SunOS-5.9

       ssh    from ssh.com

       ssh    from openssh.org

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

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

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

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

AUTHOR
       Joerg Schilling
       Seestr. 110
       D-13353 Berlin
       Germany

       Mail bugs and suggestions to:

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

Joerg Schilling			   09/06/02			       STAR(1)

NAME | SYNOPSIS | DESCRIPTION | FEATURES | COMMAND | OPTIONS | INCREMENTAL BACKUPS | BACKUP SCHEDULES | INCREMENTAL RESTORES | SYNCHRONIZING FILESYSTEMS | SIGNALS | EXIT STATUS | EXAMPLES | ENVIRONMENT | FILES | SEE ALSO | DIAGNOSTICS | NOTES | SECURITY NOTES | SUID NOTES | LIMITATIONS | BUGS | HISTORY | AUTHOR

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=star&sektion=1&manpath=FreeBSD+Ports>

home | help