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

FreeBSD Manual Pages

  
 
  

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  ex-
       tract  or list mode, directly on	the content on an archive.  The	exten-
       sions 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  ex-
       tension	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  us-
       ing 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 re-
	      sult 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  im-
	      plies  that it defaults to H=exustar -dump.  When	in -copy mode,
	      star forks into two processes and	data exchange is done via  the
	      shared  memory from the FIFO.  This gives	the best possible per-
	      formance.	 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 ex-
	      tensions 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 ac-
	      cess 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 be-
	      low.

	      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/lo-
	      cal/etc/tar in Solaris.

       -acl   Handle  Access  Control List (ACL) information in	create and ex-
	      tract mode.  If -acl has been specified, star is in create  mode
	      and the header type is exustar, star will	add ACL	information to
	      the archive using	POSIX.1-2001 extended headers.	 If  -acl  has
	      been specified and star is in extract mode, star will try	to re-
	      store 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	speci-
	      fied,  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.

	      Star currently supports the withdrawn POSIX.1e  ACLs  and	 NFSv4
	      ACLs.   To  check	which ACL flavors are supported	on the current
	      platform,	call star -version.  Whether POSIX.1e ACLs can be con-
	      verted into NFSv4	ACLs depends on	the local ACL support library.

       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 de-
			fined  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  un-
			limited, uid/gid/uname/gidname is unlimited, major/mi-
			nor 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 im-
			plementations 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  un-
			limited,  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 un-
			limited, 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 un-
			limited, 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  de-
			pendent.

			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  op-
	      tion  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  re-
	      setting the atime	of the files.  If the -atime option is used in
	      conjunction with the list	command, star lists  access  time  in-
	      stead of modification time. (This	works only in conjunction with
	      the star,	xstar, xustar, exustar,	and with the pax format.)  An-
	      other  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 be-
	      ginning  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 (un-
	      less 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 re-
	      mote tape	protocol (see f= option	below).	 The default is	to use
	      a	 blocking factor of 20 i.e.  10	kBytes.	 Increasing the	block-
	      size will	speed up the backup.  For portability  with  very  old
	      tar  implementations  (pre  BSD 4.2 or pre AT&T SVR4), blocksize
	      should not be more than 10 kBytes.  For POSIX.1-1988 compatibil-
	      ity,   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 in-
	      terface 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 di-
	      rectly 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 in-
	      terface 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 op-
		     tions.

	      +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 op-
		     tion 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  in-
	      stead 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 when in create	mode.  Normally,  star
	      descends	the  whole tree	if it encounters a directory in	in its
	      file parameters.	The option -D is in effect by default  if  the
	      list=file	 option	is used.  If you like star to descend directo-
	      ries 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 op-
			tion 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 -xf-
			flags 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  ex-
	      tracted by an old	tar implementation. If star is used to extract
	      an archive that has been created with -dirmode  the  directories
	      will  not	 get  an  old  time stamp unless the option -U is used
	      while extracting the archive.

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

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

	      The resultant archive may	be seen	as a level-less	dump which in-
	      cludes  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  be-
	      tween  two incrementals and set to an old	date in	st_mtime (e.g.
	      as a result from a tar extract) will not be archived  with  full
	      content.	 Using	-dumpmeta thus may result in incomplete	incre-
	      mental dumps, use	with extreme care.

       -e     Exit immediately with exit status	-3 (253) if any	unexpected er-
	      ror  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  op-
	      tion  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  af-
			  ter  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 an-
			  other	error condition	or a list of error  conditions
			  (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 er-
			  rors.	 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  en-
			  counter 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 un-
			  able 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 '/../'  se-
			  quence inside	when -secure-links has been specified.
			  In this case,	star tries  to	match  the  link  name
			  against the pattern in the error control file.

	      SAMEFILE	  Suppress warnings about links	that have been skipped
			  on extraction	because	source and target of the  link
			  are  pointing	 to  the same file.  If	star would not
			  skip these files, it would end up with removing  the
			  file	completely.  In	this case, star	tries to match
			  the link name	against	the pattern in the error  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 ar-
	      gument,  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 argu-
	      ments, 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  ma-
	      chine.   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  es-
	      tablished	 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 se-
	      curity 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  re-
		     sult 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  re-
		     sult of a part of the expression.

	      The command line:

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

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

	      The command line:

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

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

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

       -force_hole
	      obsoleted	by -force-hole

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

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

	      This  option  should be used with	extreme	care because you some-
	      times get	in trouble when	files get unattended holes.   All  op-
	      tions  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 op-
	      tion is in effect, star will silently remove these files to  al-
	      low  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 de-
	      fault 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 in-
	      stall 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 di-
	      rectories.  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.

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

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

       -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  ex-
	      cluded  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 al-
	      lows  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  re-
	      lated 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 al-
	      lows to verify the correct volume	after  a  change  during  read
	      back.   It is recommended	to use the exustar format for best re-
	      sults.  In create	mode, -multivol	is only	supported for archives
	      types  that allow	to write reliable multi	volume header informa-
	      tion.

	      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 pa-
	      rameter 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%) be-
	      cause 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 di-
	      rectory, -no-dirslash may	not be used if archives	should be com-
	      patible 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 su-
	      per user and the permissions should not be restored from the ar-
	      chive.   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  op-
	      tion  also  applies  when	 ACLs  are going to be archived	or ex-
	      tracted.

       -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 -signed-checksum	option
	      too.  If you want	directories not	to be archived in order	to  be
	      compatible  to very old historic tar archives, you need to 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 ex-
	      clude files from the list	of file	type arguments	or  the	 files
	      located in a sub tree of a file type argument directory.	By de-
	      fault, 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 se-
	      lect 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	direc-
	      tory  itself,  use  dir/ as file type argument.  See manual page
	      for match(1) for more details of the pattern matcher.  All  pat-
	      terns  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 re-
	      ply.  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 -re-
	      fresh-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  IN-
	      CREMENTAL	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  op-
	      tional  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 to-
	      gether with a lot	of other files,	this may not even be noticed.

	      As  the  usability  of  a	 tar archiver would be limited if -se-
	      cure-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 So-
	      laris 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 de-
	      fault name is /etc/tardumps.  Use	in combination with the	level=
	      option  to  create  true incremental dumps.  See also -wtardumps
	      option and section INCREMENTAL BACKUPS for more information.

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

       -to_stdout
	      obsoleted	by -to-stdout

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

       -tpath Use this option together with the	-t option or with -cv (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  ef-
	      fect,  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.

       -uncond-rename
	      When in interactive restore mode or when the -s option was spec-
	      ified, unconditionally ask for a new name	or apply  a  substitu-
	      tion.   This  happens  even  when	the current path name would be
	      skipped otherwise	because	the file in the	archive	is  not	 newer
	      than the file with the original name on disk.

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

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

       -version
	      Print version information	and exit.

       VOLHDR=name
	      Use name to generate a volume header.

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

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

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

       See SECURITY NOTES for more information.

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

       -xcopy An alias for -copy -sparse -acl

       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  op-
	      tion),  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.	 If  a
	      file  is	missing,  a zero sized file is created.	 If the	option
	      -meta is used together  with  the	 option	 -force-hole,  missing
	      plain  files  are	 created as sparse empty files of the original
	      size.

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

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

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

INCREMENTAL BACKUPS
       Star  is	 able to back up file system in	full and incremental mode.  To
       allow incremental backups, the file system must implement POSIX	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 ex-
       cluded parts to included	parts, partial backups may be taken also. Par-
       tial backups only make sense if a complete directory sub	 tree  is  ex-
       cluded (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 in-
       consistent 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 re-
       move files with link count 1 that have been removed between incremental
       dumps. These files are moved to the directory star-tmpdir.  Before  you
       start  to extract the next incremental, you need	to remove all files in
       star-tmpdir.

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

       To create an initial copy of a filesystem call:

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

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

       To copy incremental content of a	filesystem call:

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

       Note that like with backups in general, copies from a  live  filesystem
       should be avoided.  On operating	systems	that support file system 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 re-
		 ceipt 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  re-
		 ceipt 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  ex-
       ists 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@re-
	      motehost:/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), in-
       stead 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/lo-
	      cal/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  ma-
		     chines 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 en-
		     tries.   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  re-
	      store.   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 re-
       quires 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 be-
       fore 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 lo-
       cal 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 ex-
       tended headers which are	extensible to include any feature without  fu-
       ture  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 ex-
       pects 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 xs-
       tar  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 im-
       plementations 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.  Un-
       packing	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 be-
       fore 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 re-
       mote 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 af-
       ter setting up the remote connection to the rmt server and before open-
       ing 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 op-
       tions -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 ac-
       cepted 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	   jo-
       erg@schily.isdn.cs.tu-berlin.de

Joerg Schilling			   13/11/08			       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:
<https://www.freebsd.org/cgi/man.cgi?query=star&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help