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
       star  cli=name	...

DESCRIPTION
       Star is a very fast tar(1) like tape archiver with improved functional-
       ity.  It	supports unlimited path	name lengths (up to 8 GB) in all cases
       that use	suitable archive types.

       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.

       If the first argument is	in the form cli=name, the command line	inter-
       face is selected	to match name.	See section CLI	SELECTION below.

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 support for incremental backup and	restore	similar	to the
       BSD commands dump(1) and	restore(1) that	are known  as  ufsdump(1)  and
       ufsrestore(1) on	Solaris.

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

       Star includes a sophisticated diff command that is able to compare file
       content and meta	data.  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  (typically	1024 bytes) may	be archived by most tar	imple-
       mentrations.  Star allows to archive path names up to 8	GB  on	modern
       platforms.

       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 - if	run as root -, 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.

CLI SELECTION
       If  the first argument is in the	form cli=name, the command line	inter-
       face is selected	to match one of	the supported CLI variants.  The  fol-
       lowing interfaces are supported:

       star	      The  star	 interface  selects the	command	line interface
		      described	in this	manual page.

       suntar	      The suntar interface selects the command line  interface
		      of  the  classical UNIX tar command as described in sun-
		      tar(1).

       gnutar	      The gnutar interface selects the command line  interface
		      of the GNU tar command as	described in gnutar(1).

       pax	      The  pax interface selects the command line interface of
		      the POSIX	pax command as described in spax(1).

       cpio	      The cpio interface selects the command line interface of
		      the  classical  UNIX  cpio  command  as described	in sc-
		      pio(1).

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

	      The  Option  -c may be used together with	-diff and -t.  In this
	      case, the	whole command line has to be similar  to  the  command
	      line for the -copy mode.

       -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 with any
	      filesystem or platforms with  Copy  on  Write  filesystems  like
	      ZFS),  it	 may help to use -no-fsync in addition (see also ENVI-
	      RONMENT and FILES), 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/epax format.  The option	-a or -atime lists the
	      access time instead of the modification time, the	option	-ctime
	      lists  the  file creation	time instead of	the modification time.
	      The option -tpath	may be used in addition	to modify  the	output
	      so it may	be used	in shell scripts.

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

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

	      On operating systems with	slow file I/O (such as Linux with  any
	      filesystem  or  platforms	 with  Copy  on	Write filesystems like
	      ZFS), it may help	to use -no-fsync in addition (see  also	 ENVI-
	      RONMENT  and FILES), 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 ACLs from	the withdrawn  POSIX.1e	 draft
	      and NFSv4	ACLs.  To check	which ACL flavors are supported	on the
	      current platform,	call star -version.   Whether  ACLs  from  the
	      withdrawn	 POSIX.1e  draft  can be converted into	NFSv4 ACLs de-
	      pends 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  in  the
			star archive format contain a 'tar\0' signature.

			This archive format supports very long path names.

	      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.

			GNU tar	is not able to extract files  with  with  long
			path names, but	under some conditions creates archives
			with long path names. We therefore do  not  limit  the
			creation of gnutar archives with long path names.

			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.

			This archive format supports very long path names.

	      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.

			This archive format supports very long path names.

	      epax	A format similar to the	pax  format  but  with	forced
			POSIX.1-2001  extended headers.	 This enforces stimes-
			tamps with nanosecond resolution in the	archive.

			This archive format supports very long path names.

	      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.

			This archive format supports very long path names.

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

			This archive format supports very long path names.

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

			This archive format supports very long path names.

	      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 32-bit checksum.
			Hence the archive type name CRC	as  used  by  AT&T  is
			misleading.   Try  to avoid the	crc archive format be-
			cause 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/epax format.)
	      Another  option to retain	the access time	for the	the files that
	      are going	to be archives is to readonly mount a UFS snapshot and
	      to archive files from the	mount point of the UFS snapshot.

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

       b=#    Set the block size for tape operations.  See option blocks=#.

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

	      Since  the numbers printed by the	-block-number option are based
	      on a block size of 512 bytes and the tape	block size is  usually
	      larger, the tape block number for	the mt fsr command needs to be
	      computed to honor	the tape blocking factor.

       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.

	      The best method to set the blocksize is to use the bs=# option.

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

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

	      mtime	Compare	modification time of file.

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

	      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.

	      nsecs	Check nanoseconds in all selected timestamps as	well.

			Note  that  the	 time resolution of various filesystem
			differs.   While  modern  filesystems  like  ZFS   and
			filesystems  that  introduced  a sub-second resolution
			recently, tend to support  a  nanosecond  granularity,
			filesystems like UFS that support a sub-second resolu-
			tion since the early 1990s tend	to support only	a  mi-
			crosecond  granularity.	 Since	even  in  in 2018, the
			POSIX.1-2008  feature	pathconf(_PC_TIMESTAMP_RESOLU-
			TION)  has  not	 yet been implemented on any platform,
			you may	need to	disable	to compare nanoseconds in some
			cases.

			Star  currently	 first tries to	compare	the timestamps
			based on a nanosecond resolution and if	that fails and
			one  timestamp seems to	have a microsecond resolution,
			the comparison is repeated with	microsecond resolution
			only.

	      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.

       -do-fsync
	      Tell  star to call fsync(2) for every file when in extract mode.
	      This enables star	to check whether a file	could be  successfully
	      extracted.  See -no-fsync	for more information.

       -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 it's
	      own 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.

	      A	solution is to create the time stamp file, then	to create  the
	      snapshot and later use the option	dumpdate=name.

       -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
			  leat another error condition or a list of error con-
			  ditions (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 about read errors on files.

	      WRITE	  Suppress warnings about write	errors on files.

	      READLINK	  Suppress warnings about readlink(2) errors  on  sym-
			  bolic	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.

	      CHDIR	  Suppress warnings about chdir(2) errors.

	      ICONV	  Suppress  warnings about iconv(3) errors.  These er-
			  ror happen,  when  text  is  converted  from	or  to
			  POSIX.1-2001 extended	tar headers.

	      ID	  Suppress warnings about uid/gid range	errors.	 These
			  errors happen	when the archive format	does not  sup-
			  port the actual value.

	      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 target names that start	with  '/'  or  have  a
			  '/../' sequence inside when -no-secure-links has not
			  been specified.  In this case, star tries  to	 match
			  the  link name against the pattern in	the error con-
			  trol file.

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

	      BADACL	  Suppress warnings about access control list  conver-
			  sion 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.

       f=tarfilename
	      Use  tarfilename	as  the	 name for the tar archive.  See	option
	      file=tarfilename.

       -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 from y2000 that gives 12MB/s transfer rate,	a fifo of  256
	      MB  size	will  keep  the	tape at	least streaming	in units of 20
	      seconds.

	      Future LTO tape drives are expected to implement transfer	 rates
	      of  aprox.  3GB/s	 and  need a much larger fifo size to keep the
	      tape streaming.

	      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 -rsh option on how to	set up a different  protocol  for  the
	      connection to the	remote tape server.

	      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:

	      -chatime timespec
		     The primary always	evaluates as  true;  it	 modifies  the
		     time  of  last  access  of	 a  file  in struct stat.  See
		     sfind(1) for a description	of timespec.

	      -chctime timespec
		     The primary always	evaluates as  true;  it	 modifies  the
		     time of last status change	of a file in struct stat.  See
		     sfind(1) for a description	of timespec.

	      -chmtime timespec
		     The primary always	evaluates as  true;  it	 modifies  the
		     time  of last modification	of a file in struct stat.  See
		     sfind(1) for a description	of timespec.

	      -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 there is a dump level  mis-
	      match  or	a reference date mismatch.  See	-wtardumps, level= and
	      sections INCREMENTAL BACKUPS and INCREMENTAL RESTORES  for  more
	      information.

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

       fs=#   Set fifo size to #.  See bs= for the possible syntax.

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

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

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

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

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

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

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

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

	      As star by default does not remove non-empty directories,	an 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.

       -lzma  run the input or output through a	lzma 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/epax 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 that requires a separate
	      open and ioctl.

       -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 with any  filesys-
	      tem  or  platforms with Copy on Write filesystems	like ZFS), 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.

	      See  also	 -do-fsync  and	STAR_FSYNC in ENVIRONMENT and /usr/lo-
	      cal/etc/star for ways to configue	the default behavior.

       -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-secure-links
	      Extract hard links or symbolic links even	if the target  of  the
	      link starts with a slash (/) or if /../ is contained in the link
	      target.  See the description of the option -secure-links below.

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

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

       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
	      directory, then the whole	sub tree matches the pattern.

       -pax-o string
	      Set a pax	like option control pattern.

	      The  only	argument that is currently supported is	binary to cre-
	      ate a hdrcharset=BINARY header.

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

       rmt=path
	      Specify  the  path  to the program at the	remote tape server for
	      the RMT protocol.

	      star by default calls the	UNIX default path /etc/rmt.

	      Since most rmt  implementations  cause  problems	in  case  that
	      server  and  client  are on a different OS, it is	recommended to
	      tell  star  to  call  the	 rmt  program  that  comes  with  star
	      (/opt/schily/sbin/rmt).

       rsh=path
	      Specify  the  program to log into	the remote tape	server for the
	      RMT protocol.  If	the argument is	the empty string,  connections
	      are made via rcmd(3).  The default method	to log into the	remote
	      server is	configurable at	compile	time. The current  default  is
	      set up to	use ssh.

       -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 target	of the
	      link starts with a slash (/) or if /../ is contained in the link
	      target.  Tar archives containing such links  could  be  used  to
	      compromise  the system. If they are unpacked together with a lot
	      of other files, this may not even	be noticed.

	      Links that do not	point outside the tree that  starts  with  the
	      current  working directory are not seen as a security risk. This
	      makes star easy to use.  It is always safe to unpack an  unknown
	      archive in an empty directory.

	      Many  system installations contain plenty	of symbolic links with
	      absolute path name or with /../ inside.  The usability of	a  tar
	      archiver	for  system  backups would be limited if -secure-links
	      checking would be	done by	default	for backups as well, star thus
	      makes  link  checking optional when in -restore mode.  When -re-
	      store has	not been specified,  link  checking  is	 the  default,
	      since  this is the usual way where archives from unknown sources
	      are going	to be unpacked.

	      To turn off this default for the usual case, the option  -no-se-
	      cure-links  may  be used and in -restore mode, -secure-links may
	      be specified to turn it on.

	      If you unpacked a	tar archive while -secure-links	 is  effective
	      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 op-
	      tions -k,	-w and -nowarn in addition to the options used for the
	      first run.  To speed this	up, it helps to	use:

		  star -xvpw -find -type l

	      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 additional
	      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 Reserved for NFSv4 extended attributes.

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

       -zstd  run the input or output through a	zstd  pipe  -  see  option  -z
	      above.

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 filesystem ID or	device ID of the  device  con-
	      taining  the  file)  and	st_ino (The file serial	number).  If a
	      file is renamed, these numbers need to be	retained.   Both  num-
	      bers need	to be a	cardinal scalar	that is	expressible in a deci-
	      mal 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  or  as  a	decimal	number that counts in seconds plus an-
	      other number that	counts in fractions of a second.

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

       In case of a partial backup, it is important that no file or  directory
       will  ever  be  moved  outside  the scope and later move	into the scope
       again. Moving files or directories  outside  the	 scope	of  a  partial
       backup is detected as deletion and moving the files back	into the scope
       does not	make them appear in  an	 incremental  backup  since  the  time
       stamps of files from inside renamed directories did not change.

       Note that a backup must not include files that are mounted from another
       filesystem and a	restore	cannot be done with more than  one  filesystem
       as target.

       Files  in the backup tree that are hidden under a mount point cannot be
       part of the backup as long as the backup	is not done from a snapshot.

       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 from UFS:

       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, but you only need to restore  the	latest
       level  10 dump in order to get all changes back.	 If you	don't like the
       size of the accumulated changes,	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.

       Incremental restores should be run as root user.	 Star supports private
       incremental  dumps  and	restores run as	an unprivileged	user, but this
       mode has	been tested less frequently.

       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 /extract-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 /extract-filestem-mount-point
       star -xpU -restore f=archive-name

       In  order  to  restore  a partial dump, the -partial option needs to be
       specified. This is to make sure that the	user understands that  renames
       to a path outside the scope of the partial dump may result in inconsis-
       tencies during a	restore.

       In case there is	a dump level mismatch or a reference date mismatch, it
       is possible to give a restore a chance by specifying the	-force-restore
       option.

       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
       SIGINFO	 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. Note that the negative	values
       are only	available to modern shells and programs	that use waitid(2)  on
       a  POSIX	 OS  and  thus	can retrieve the full 32 bits of the star exit
       code. The positive number variants are what you get when	only the low 8
       bits from the exit code are available.

       0      All files	were processed successfully.

       -4 / 252
	      Star has been interrupted	in create mode and the end of star has
	      been delayed until the  current  file  has  been	archived  com-
	      pletely. This error is only used in case that no other error oc-
	      cured and	the tar	archive	only has become	shorter	than expected.

       -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	faster rcmd(3) connection  for	a  backup  to  a  remote  tape
       server, one might use:

	      example#	env  RSH=''  star  -cM	fs=128m	 bs=63k	f=tape@remote-
	      host:/dev/rmt/1bn	.

       Note that this requires root privileges.

       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 archive all files	with a mtime of	now, use:

	      example# star -c f=archive-name -find . -chmtime now

       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.

       STAR_FSYNC
	      If set to	`N', the  default  behavior  of	 star  is  as  if  the
	      -no-fsync	option has always been specified.

	      This grants that star is always faster than other	archivers, but
	      makes it impossible for star to check whether the	extracion of a
	      file to the filesystem was successful.

	      If set to	any other value, the default behavior of star is as if
	      the -do-fsync option has always been specified.

	      The  environment	STAR_FSYNC  has	  precedence   over   /usr/lo-
	      cal/etc/star  but	 may  still be overwritten by command line op-
	      tions.

       STAR_WORKAROUNDS
	      If this environment variable is present,	implement  workarounds
	      for  named  problems.   The  environment variable	is expected to
	      contain a	comma separated	list of	bug names:

	      ssh-tcpip
		     implement a workaround for	a bug caused by	ssh or	TCP-IP
		     seen on Linux in 2003.  The bug caused the	verbose	output
		     from star on stderr to be	lost  when  calling  something
		     like:

			 ssh host 'star	-c ...'

		     The  workaround is	activated when stderr is not connected
		     to	a terminal and works by	waiting	 for  0.1 seconds  for
		     the output	to appear.

       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 the default method, but rather uses the pro-
	      gram specified by	RSH.  Use e.g.	RSH=/path/to/ssh to  create  a
	      secure shell connection using a specific ssh version.

	      If  the  RSH environment is not present, the compiled in default
	      is used.	This currently is ssh.

	      If the RSH environment is	empty, then rcmd(3) is used.

	      Former versions of star by default did use rcmd(3) to  create  a
	      remote connection.  Using	a different method forces star to cre-
	      ate a pipe to the	rsh(1) or ssh (1) program and  disallows  star
	      to  directly  access  the	 network  socket to the	remote server.
	      This makes it impossible to  work	 at  maximum  performance  and
	      slows  down  the connection compared to a	root initiated rcmd(3)
	      connection.

	      See rsh= option for more information.

	      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.

	      See rmt= option for more information.

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.

	      STAR_FSYNC
		     If	set to `N', the	default	behavior of star is as if  the
		     -no-fsync option has always been specified.

		     This  grants  that	 star  is  always  faster  than	 other
		     archivers,	but makes it  impossible  for  star  to	 check
		     whether  the  extracion  of  a file to the	filesystem was
		     successful.

		     If	you like to make the default fast, keep	in  mind  that
		     you  need to specify -do-fsync for	cases where star needs
		     to	be able	to know	whether	the extraction was successful.

	      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 interactive 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_sym(1),
       tartest(1), star(4), rcmd(3), fssnap(1m)

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

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

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

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

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

NOTES
       The command line	syntax for the tar command  (as	 defined  in  SUSv2  -
       UNIX-98)	 deviates  from	 the command line syntax defined for all other
       commands. While the POSIX command line 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/epax
       archive format uses a method that allows	an POSIX.1-1988	compliant  way
       of  storing  filenames, if the POSIX method would allow this.  When the
       archive format is xustar, exustar or pax/epax 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/epax archive format.	The  probabil-
       ity  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  neither  specify  the	-/ nor -..  or -no-se-
       cure-links options.  If you get a warning, you should  unpack  the  ar-
       chive a second time and specify the options -k, -w and -nowarn in addi-
       tion 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/epax 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.

       If you ever discover a hang in the fifo of star,	get  the  process  ids
       for both	star processes,	send both a RTMAX signal using kill(1) and re-
       port the	disgnostic output.

       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
       A tar command appeared in Seventh Edition Unix, which was  released  in
       January,	 1979.	It  replaced  the  tp program from Fourth Edition Unix
       which replaced the tap program from First Edition Unix.

       Star was	first created in 1982 to extract tapes on a UNIX clone	(UNOS)
       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:

       joerg.schilling@fokus.fraunhofer.de or joerg@schily.net

SOURCE DOWNLOAD
       The source code for star	is in the star project at Sourceforge at:

	   http://sourceforge.net/projects/s-tar/

       The download directory is:

	   http://sourceforge.net/projects/s-tar/files/

       Frequent	development snapshots of the star source are also included  in
       the  schilytools	 project  and  may  be	retrieved from the schilytools
       project at Sourceforge at:

	   http://sourceforge.net/projects/schilytools/

       The download directory is:

	   http://sourceforge.net/projects/schilytools/files/

       Check for the schily-*.tar.bz2 archives.

Joerg Schilling			  2019/03/27			       STAR(1)

NAME | SYNOPSIS | DESCRIPTION | FEATURES | CLI SELECTION | 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 | SOURCE DOWNLOAD

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

home | help