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  command list=name [options] -find [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).

       tar	      The classical tar	interface selects the command line in-
		      terface  of the classical	UNIX tar command. This is cur-
		      rently an	alias to suntar	and implements extensions  in-
		      troduced by the tar command found	on Solaris.

       gnutar	      The  gnutar interface selects the	command	line interface
		      of the GNU tar command as	described in gnutar(1).	  Star
		      however does not implement the deviations	from the stan-
		      dard behavior, that are caused by	the GNU	option	parser
		      that is used by the original gtar(1) command.

       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 /etc/default/star.	The format for
	      the archive entries is  the  same	 as  the  format  in  /etc/de-
	      fault/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  for  all types of
			files.	This only works	if the archive is  in  exustar
			format and contains star's dump	extensions.

	      dnlink	Compare	 link  count on	hardlinks for directories.  If
			comparing dnlink is excluded  but  nlink  is  not  ex-
			cluded,	this allows to deal with filesystems that dif-
			fer in their directory implementation.	The link count
			of directories in POSIX	is equal to the	number of man-
			ually created additional hard links + 1	(as with other
			file  types),  while on	historical UNIX	filesystems it
			is equal to the	number of sub-directories + 2 +	number
			of  manually created additional	hard links.  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+ Works similar to -dump but creates more  global  archive	header
	      meta data, e.g. the SCHILY.volhdr.hostname tag.

	      This helps to understand where a tar archive has been created.

       -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 thumb for the fifo size is to use more	than the  buffer  size
	      of  the  tape drive and less then	half of	the real memory	of the
	      machine.	A good choice would be to use a	fifo  size  between  8
	      and 256 MB.  This	may increase backup speed up to	5% compared to
	      the speed	achieved with the default fifo size. Note that with  a
	      DLT  drive 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 /etc/default/rmt.  All op-
	      tions 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.

       iskip=#
	      Set the initial skip size	to #.  See bs= for the	possible  syn-
	      tax.

	      The  skip	 size  is the number of	bytes to ignore	from the first
	      tape record. This	option is typically used if a tar archive on a
	      tape  is	not read from the beginning and	the tape has been for-
	      warded before the	tape is	read.  iskip= then specifies the  off-
	      set  of the first	archive	header within the current tape record.
	      It does not work on compressed archives.

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

	      If  used together	with -find, no path list is accepted after the
	      option -find.

	      See also the option pkglist= for a way to	specify	filename, per-
	      mission, owner and group.

	      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.

	      When using -find,	this may not always  work  as  expected,  e.g.
	      when  the	 /proc	filesyestem is involved.  Use -xdev past -find
	      for this reason.

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

       mtskip=#
	      Set  the initial archive skip amount to #.  See bs= for the pos-
	      sible syntax.

	      The archive skip size is the number of 512 byte blocks to	ignore
	      before  starting	to  read  the  archive.	 Typically,  the value
	      printed by the -block-number option is used as the parameter.

	      This option is used if a tar archive on a	tape is	not read  from
	      the beginning in order to	fast forward to	a specific file. Check
	      the -one-file option for a way to	extract	only one file from the
	      archive.

	      If the archive is	a plain	file, this option results in a lseek()
	      call to the input	file.  If the archive is a magnetic tape, this
	      option  results  in  a  mtioctl(MTFSR)  call for the part	of the
	      blocks that can be represented by	the tape block	size  followed
	      by  a  skip  of  the  remainder of the blocks. Since star	learns
	      about the	tape block size	from the first read() call,  this  op-
	      tion does	not work correctly if the tape block size used by star
	      does not match the tape  block  size  on	the  medium.  See  the
	      blocks=# option above for	information on the tape	block size.

	      If  mtskip=# has been specified, a iskip=# option	is ignored and
	      the value	is rather computed from	the mtskip=#  parameter.   mt-
	      skip=# does not work on compressed 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 (even the	last one) if in	 multi
	      volume mode or if	the tsize= option has been specified.  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 parame-
	      ter 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 /etc/de-
	      fault/star for ways to configure 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
	      and  STAR_SECURE_LINKS  in ENVIRONMENT and /etc/default/star for
	      ways to configure	the default behavior.

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

       -one-file
	      Exit star	after one file has been	extracted as a result  from  a
	      match  with a pattern or with a command line argument.  This op-
	      tion is intended for users that need  to	restore	 single	 files
	      from  larger tape	archives and do	not like to wait until the end
	      of the tape is reached.  To let star exit	after the first	 file,
	      call  -one-file  together	 with  pat=*.  This is e.g. useful to-
	      gether with the option mtskip=#.

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

	      If  used together	with -find, the	uid, gid and permission	values
	      from the pkglist=file have precedence over changes on this  meta
	      data introduced by libfind.

	      See list=	option for further information.

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

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

		   -pax-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  new
	      string  may  also	 contain the special strings '\1' .. '\9' that
	      refer to parts of	the old	string selected	by  '\(...\)'  groups.
	      The  optional  trailing 'g' means	global substitution. If	'g' is
	      not used,	a substitution pattern is only used once  on  a	 name.
	      If  the  optional	 trailing  'p'	is  used,  the substitution is
	      printed to standard error.

	      Up to 100	substitute options may be used.	If more	than one  sub-
	      stitute  option has been specified, star will loop over all sub-
	      stitute patterns until one matches.  The up  to  100  substitute
	      options  are  processed  together	with the -s replstr options in
	      the order	they appear on the command line.

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

	      If  the  target  platform	 for star does not support regex func-
	      tions, there is a	silent fallback	to the -s replstr  option  and
	      the '\1' .. '\9' substitutions are not possible.

       -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.  The up  to  100  substitute
	      options  are  processed together with the	-pax-s replstr options
	      in the order they	appear on the command line.

	      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 and in copy mode would be limited if
	      -secure-links  checking  would be	done by	default	for backups or
	      when in copy mode, star thus makes link checking	optional  when
	      in  -restore  or in -copy	mode.  When neither -restore nor -copy
	      have been	specified, link	checking is the	default, since this is
	      the usual	way when 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 or -copy mode, -se-
	      cure-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  section  SECURITY  NOTES  for more information and STAR_SE-
	      CURE_LINKS in ENVIRONMENT	and /etc/default/star for ways to con-
	      figure the default behavior.

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

	      When  using  -find,  this	 may not always	work as	expected, e.g.
	      when the /proc filesyestem is involved.  Use  -xdev  past	 -find
	      for this reason.

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

       -64 / 192
	      An  exit	code has been used that	does not fit into an 8-bit un-
	      signed number and	the environment	 COMERR_EXCODE	has  not  been
	      set.  The	value -64 / 192	in this	case marks a clash.

       -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 /etc/default/rmt	exists
       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

       If you like to split the	content	of an archived tree into tar chunks of
       1 GB, you could call:

	      example# star -c f=/tmp/v.tar tsize=1G \
	      new-volume-script='sh -c "mv /tmp/v.tar /tmp/v$(($1-1)).tar" nv' .

ENVIRONMENT
       COMERR_EXCODE
	      If  this	environment  is	 present, exit codes are not mapped to
	      avoid possible clashes with calling programs that	use  the  out-
	      dated  waitpid(2)	 instead of the	waitid(2) call to wait for the
	      exit status from star.  While waitid(2) returns the full 32  bit
	      exit  code,  waitpid(2)  masks the exit code with	0377.  Without
	      the environment COMERR_EXCODE,  exit  codes  outside  the	 range
	      -63 .. 191 are mapped to -64 (192) to mark a clash.

	      If  the  environment  COMERR_EXCODE  is set and the value	starts
	      with the character '0', an exitcode code > 0 that	leads to exit-
	      code  &  0377  ==	 0,  is	 mapped	to -64 to avoid	confusion with
	      shells that use waitid(2)	but interpret these exit codes as zero
	      with respect to conditional execution in order to	implement com-
	      patibility to historical shells.

	      With a shell that	supports the full exitcode on and a POSIX com-
	      pliant  operating	 system, it is recommended to set the environ-
	      ment COMERR_EXCODE.

       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 /etc/default/star
	      but may still be overwritten by command line options.

       STAR_NOHINT
	      If  this	environment is seen, some informative messages are not
	      printed.	 this  currently  applies  to  messages	  related   to
	      STAR_FSYNC and STAR_SECURE_LINKS.

       STAR_SECURE_LINKS
	      If set to	`N', the default behavior of star is as	if the -no-se-
	      cure-links option	has always been	specified.

	      This disables checks for potentially insecure links by default.

	      If you like to make this the default, keep in mind that you need
	      to  specify  -secure-links in case you like to unpack an archive
	      from unknown sources.

	      The environment STAR_SECURE_LINKS	has precedence	over  /etc/de-
	      fault/star but may still be overwritten by command line options.

       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
       /etc/default/star
	      Default  values can be set for the following options in /etc/de-
	      fault/star.  For example:	CDR_FIFOSIZE=64m

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

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

	      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.

		     This  setting  is	overwritten by the STAR_FSYNC environ-
		     ment, if present.

		     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.

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

		     This  disables  checks  for potentially insecure links by
		     default.

		     This setting is overwritten by the	STAR_SECURE_LINKS  en-
		     vironment,	if present.

		     If	 you  like to make this	the default, keep in mind that
		     you need to specify -secure-links in case you like	to un-
		     pack an archive from unknown sources.

	      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), waitid(2), waitpid(2)

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.

       See the ENVIRONMENT section and /etc/default/star for ways to configure
       the default behavior.

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
       D-13353 Berlin
       Germany

       Mail bugs and suggestions to:

       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/

       The preferred 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 and please use the latter down-
       load  in	 favor	of old so called stable	star releases in separate tar-
       balls.

Joerg Schilling			  2020/09/04			       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