# @(#)README	1.6 20/09/04 Copyr 1997-2020 J. Schilling

Star is a tar like archiver - TAR stands for Tape ARchiver.


Star saves many files together into a single tape or disk archive,
and can restore individual files from the archive. It includes a FIFO
for speed, a pattern matcher, multivolume support, the ability to correctly
archive sparse files, automatic archive format detection, automatic byte order
recognition, automatic archive compression/decompression, remote archives
and special features that allow star to be used for full backups. it includes
a built in find(1) command that allows to execute find(1) expressions.
It also includes `rmt', a truly portable version of the remote tape server
that supports remote operation between different OS and machine architectures
(hides even Linux oddities) and a portable `mt' tape drive control program
that is able to use the remote tape interface.

The RMT program if 100% compatible with Sun's extensions for inter-platform
operability support (MT status codes) and with GNU extensions for inter-platform
open() interoperability. In addition, it includes my enhancements that
hide Linux MT-ioctl non compliances with other UNIX platforms.

Star is the fastest known implementation of a tar archiver.
Star is even at least 30% faster than ufsdump.

Star development started 1982, the first complete implementation has
been done in 1985. I never did my backups with other tools than star.

Its main advantages over other tar implementations are:

	built-in find		- star is built on top of libfind and thus
				  allows you to execute "find" like expressions
				  in create, extract and list mode. This allows
				  to do a lot of interesting things that could
				  not be done if star and find would be called
				  separatedly

	fifo			- keeps the tape streaming.
				  This gives you at least 30% faster backups
				  than you can achieve with ufsdump or any
				  other known backup method.

	remote tape support	- a fast RMT implementation that has no
				  probems to saturate a 100 Mb/s network and
				  faster networks are usable depending on
				  the quality of the network implementation
				  and the speed of the filesystem.

	selectable cli		- star cli=xxx allows to select a command line
				  interface from the list

					star, suntar, gnutar, pax, cpio.

	accurate sparse files	- star is able to reproduce holes in sparse
				  files accurately if the OS includes
				  the needed support functions. This is
				  currently true for Solaris-2.3 to
				  Solaris-2.5.1 and for Solaris-10 or newer

	infinite path name length - star has no path name limitation at
				  all. It is even able to deal with
				  path names that are longer than the
				  OS limitation PATH_MAX, that is usually
				  1024 octetts.

				  Before July 2018, star did archive and
				  extract Pathnames up to 1024 Bytes. Since
				  July 2018, star deals with long names of
				  arbitrary length. The same limitation
				  applies to linknames.

	pattern matcher		- for a convenient user interface
				  (see manual page for more details).
				  To archive/extract a subset of files.

	sophisticated diff	- user tailorable interface for comparing
				  tar archives against file trees
				  This is one of the most interesting parts
				  of the star implementation.

	no namelen limitation	- Pathnames up 8 GBytes may be archived.
				  (The same limitation applies to linknames)
				  This previous limit was 1024 Bytes (up to
				  June 2018).

	deals with all 3 times	- stores/restores all 3 times of a file
				  (even creation time)
				  With POSIX.1-2001 the times are in nanosecond
				  granularity.
				  Star may reset access time after doing
				  backup. On Solaris this can be done without
				  changing the ctime.

	deals with nanoseconds  - Timestamps are supported with nanosecond
				  granularity (depending on the archive type).

	does not clobber files	- more recent copies on disk will not be
				  clobbered from tape
				  This may be the main advantage over other
				  tar implementations. This allows
				  automatically repairing of corruptions
				  after a crash & fsck (Check for differences
				  after doing this with the diff option).

	automatic byte swap	- star automatically detects swapped archives
				  and transparently reads them the right way

	automatic format detect	- star automatically detects several common
				  archive formats and adopts to them.
				  Supported archive types are:
				  Old tar, gnu tar, ansi tar, star,
				  POSIX.1-2001 PAX, Sun's Solaris tar, cpio.


	automatic compression detect - star automatically detects whether the
				  archive is compressed. If it has been
				  compressed with a compression program that
				  is compatible to decompression with "gzip"
				  "bzip2", "lzop" or "p7zip", star automatically
				  activates decompression.

	fully ansi compatible	- Star is fully ANSI/Posix 1003.1 compatible.
				  See README.otherbugs for a complete
				  description of bugs found in other tar
				  implementations. Star is the first tar
				  implementation that supports POSIX.1-2001.

	support for ACLs and file flags - star supports Access Control Lists
				  and extended file flags (as found on FreeBSD
				  and Linux). Support to archive and restore
				  other file properties may be easily added.

	support for all inode metadata - star supports to put all inode
				  metadata on the archive. This allows future
				  versions of star to perform true
				  incremental dumps.

	sophisticated error control - allows to tell star which error types
				  should be ignored for wich file name pattern.
				  This allows to write backup scripts that give
				  no error messages for all problems that are
				  tolerable (e.g. growing log files).

	'ed' like pattern substitutuions - star supports automated pattern rule
				  based file name substitution as documented
				  for 'pax'.

	fast built in -copy mode  - allows to make fast and accurate copies and
				  directory tree comparisons.

	True incremental dump/restore features - tar is the first TAR based
				  backup system that has been verified to
				  handle typical file system changes
				  correctly.

				  Star uses the same method as
				  ufsdump/ufsrestore but acts OS and FS
				  indeependent.

Have a look at the manual page, it is included in the distribution.


Author:

Joerg Schilling
D-13353 Berlin
Germany

Email: 	joerg@schily.net

Please mail bugs and suggestions to me.

First support for POSIX ACLs with help from Andreas Gruenbacher <ag@bestbits.at>
First support for Solaris ACLs (converted into POSIX strings).

ACL status for several OS:

SunOS-4.x	No ACL support in the kernel

SunOS-5.x	ACL Support was officially added with Solaris-2.5
		Solaris ACL's are smilar enough to POSIX ACL's so I convert
		them to POSIX ACLs before archiving them.

		Read the man pages: getfacl, setfacl, acl

		Due to a bug in libsec in function aclfromtext(),
		restoring ACLs correctly only works if the full passwd access
		for all users is present during star -x
		So due to this bug, it is impossible to do ACL backup/restores
		on passwd-less file servers.

		**** Solaris BUG ***

		As the function aclfromtext() on Solaris is unable to
		recognise a numerical (all digit) user id, it is not possible
		to do ACL backup/restore on a Solaris fileserver that has no
		access to the same passwd data as it's NFS clients.

		Even worse, aclfromtext() changes the UID for each unknown
		user to NOBODY and the function aclfromtext() returns as if
		there was no error. This is a serious security problem as
		because if this behavior the file becomes (in addition to the
		other users in the ACL) accessible by "nobody" which
		definitely is intended.

		This is Sun bug 4426407 ;-)

		If Sun would make libsec true Open Source, it would be easy
		to fix this bug in less than 10 minutes.

		**** Solaris BUG ***

Linux		ACL support available as Patch for Linux-2.4 and
		Linux-2.2.20.

		You need to install the Linux ACL patch _before_
		compiling star.

		By default Linux does not yet support ACLs. To
		install ACL support get the patch from:

			http://acl.bestbits.at/

		This page also lists the man pages for the ACL support
		commands for Linux.

FreeBSD		FreeBSD-5.0 supports ACLs, but they need to be activated.
		You need to know that you need to activate ACLs in the
		kernel _and_ in each filesystem that should carry ACLs.

True64		If you are on True64, you first need to activate extended
		security features in order to use ACLs.
		The administratice command names to list or set ACLs are
		'getacl' and 'setacl'.

		**** First tests on True64 show that the POSIX.1e function
		**** acl_from_text() does not work as expected. I have no
		**** idea how to work around this problem.
		**** It may be that True64 does not support the ACL 'masks'
		**** *entry. This would force us to create syntetic 'mask'
		**** entries when in star create mode and to compute the
		**** effective mode when in extract mode. On True64 also the
		**** function acl_get_file() does not work properly if a file
		**** does not have ACLs. Note that the standard requests that
		**** in this case acl_get_file() should return a 3 entry ACL,
		**** but on True64 it returns NULL with 'errno' unchanged.
		**** Archiving and restoring ACLs from/to True64 will most
		**** likely work. If you like to transfer TAR archives from/to
		**** other platforms you will not be able to restore any ACL.
		****
		**** As a TAR archive with ACLs made on True64 is not usable on
		**** any other system, ACL support on True64 could be called
		**** broken.


HP-UX		HP-UX ACLs are so different from POSIX.1e that it would take a
		significant amount of time to code a translation module for
		star. For this reason, HP-UX is currently not yet not supported.

AIX		AIX ACLs are so different from POSIX.1e that it would take a
		significant amount of time to code a translation module for
		star. For this reason, HP-UX is not supported at the moment.

IRIX		Unknown state, please report

SCO/Caldera	UnixWare/OpenUnix seem to be very similar to Solaris in low
		level but there is no high level (ACL string) support, so
		we cannot support SCO unless Sun makes the source of the
		libsec open.


/*--------------------------------------------------------------------------*/
If you list a TAR archive that contains ACLs for certain files,
those files are marked with a '+' sign past the UNIX permissions
if you request a long listing:

      0 -rw-r--r--  gruenbacher/assis Nov  4 04:43 2001 default/file
      0 drwxrwxr-x+ gruenbacher/assis Nov  4 04:43 2001 default/dir2/
      0 drwxr-xr-x+ gruenbacher/assis Nov  4 04:44 2001 default/dir3/
      0 drwxrwxr-x+ gruenbacher/assis Nov  4 04:44 2001 default/

If you like ACL test tar archives, have a look at:

	http://acl.bestbits.at/pre/

and fetch the files acl*.tar

Note: The ACL support code in star is alpha! Do not expect it to be
stable in any part. I cannot even grant that the archive format
will not change. However, if it turns out to be the right solution, I
will mail the star ACL format to the POSIX.1e standard committee.
All changes have been made in a way that does not affec the behaviour
of star in case no ACLs are present.

The format for ACLs in the extended headers used by star looks like:

SCHILY.acl.access = user::rwx,user:lisa:r-x:502,group::r-x, \
			group:toolies:rwx:102,mask::rwx,other::r-x

SCHILY.acl.default = user::rwx,user:lisa:r-x:502,group::r-x, \
			mask::r-x,other::r-x

The text above has been broken into shorter lines for readability

This is a legal 'vendor unique' POSIX.1-2001 extension for extended
tar headers.

If the format gets accepted by the POSIX.1 and POSIX1e committee, it
would look like:

security.acl...=user::rwx,group::rwx,mask::rwx,other::rwx,....

As the text format specified by POSIX.1e is not sufficient for TAR, we
added a numerical field for all names user and group fields.

POSIX.1e named user entry:	'user:joe:rwx,'
STAR named user entry:		'user:joe:rwx:1431,'

When star extracts the ACL string, it first checks if user 'joe' is
known if 'joe' is known, the numerical value is stripped off and a
standard POSIX.1e ACL entry is created. If 'joe' is not known, the
text 'joe' is replaced by the numerical value '1431' and a new
POSIX.1e entry that looks like 'user:1431:rwx,' is created.

/*--------------------------------------------------------------------------*/
How to use ACLs with star:

To archive ACLs (star in create mode, you need to specify a TAR format
that supports extended POSIX.1-2001 headers _and_ uses them by default.
This may currently be achieved by calling "star -Hexustar ...".
In addition, you need to specify the -acl option.
So you need to call "star -Hexustar -acl ...".

To extract ACLs you need to call "star -acl ..."

This option -acl has been introduced because it turns out that it is
impossible to handle the extract case (when the filesystem does
not support ACLs) in a decent way. Without -acl star would either
be forced to suppress eror messages for ACL handling or people
would see hundreds of ACL warnings.

The intention for the -acl option was to make ACL handling easy
to understand.

Here is a description how -acl works:

-	if -acl is not present in create mode, star does not
	archive ACLs

-	if -acl is present in create mode and the header type
	is 'exustar' (selected by H=exustar), star will
	add ACL information to the archive.

-	if -acl is not present in extract mode, star does not
	handle ACL information (i.e. if the FS does not handle
	ACLs, no error messages will occur, if the FS handles
	ACLs and there are default ACLs set up for the directory
	where star puts the extracted files the extracted files
	will have the inherited ACLs from the Default ACL od the
	directory regardless of the ACL information in the archive).

-	if -acl is present in extract mode, star handles ACLs.
	If the tar archive does not include ACL information at all
	or if the archiv does not include ACL information for a
	specific file, star will clear the ACL for this file.
	If the tar archive includes ACL information for the file,
	star will set up the ACL to be the same as the ACL information
	in the archive (i.e. if -acl is present in extract mode,
	no ACL information will be inherited from the ACL information
	that was present in the filesystem tree before the exrtact
	operation took place).

	If -acl is present in extract mode and the filesystem where
	the files are extracted to does not support ACLs, star will
	display an error message fo each file that is extracted.

Star is the best program for automatically recovering
from system crashes.

Consider the case where you have a corrupted filesystem and
no actual backup. It can be repaired with only few manual
actions by using star. Simply follow the following steps:


1)	Do a fsck -y to repair the filesystem.
	Many files will be lost but you may have luck
	and some/all recent files remain intact.

2)	Run star -xp  from the most recent backup you have.
	This will only extract all files that have been
	deleted on the fsck -y run.

3)	Rewind the tape and run:
	star -diff -c diffopts=!times
	to check for file corruptions that have not been
	detected by the fsck -y run.

4)	Do a full backup of the new system to prevent further
	data loss.

If you are running DG/UX, you may want to do some experiments
with unbuffered filereads.
This will in general only work in single user mode because
files that are already open may not be opened unbuffered,
but may give up to 50% more throughput.

The diffs are in the file:

star/create.dgux.patch

and should be applied to the file star/create.c

Big file strategy for star:
According to Posix 1003.1-1988, a 12 byte numeric field contains
11 octal digits and a space or a null.

	1)	Use unsigned 33 bit values conforming to Posix
		to allow 8 GB Filesize.

	2)	Set the top bit of theleftmost byte in the field
		and use base '256' digits to allow 95 bit values inside
		12 byte fields and 63 bit values inside 8 byte fields.

	3)	Use POSIX.1-2001 extended headers to have values
		without any limit.

	Files in type 2) and 3) will not be extractable with
	other tar implementations. Any files 'behind' such a file
	cannot be accessed.

	Files of type 1) may be extractable with other implementations.

Magnetic Tape ioctl's are just (again) a compatibility problem with Linux.


The /etc/rmt protocol allows to send ioctls to the remote system and relies on
the fact that  MTIO opcodes 0..7 of all UNIX systems are mapped to the same function.
Linux unfortunately does not follow these rules.

/*--------------------------------------------------------------------------*/
All other UNIX
/*--------------------------------------------------------------------------*/
/*
 * values for mt_op
 */
#define	MTWEOF		0	/* write an end-of-file record */
#define	MTFSF		1	/* forward space over file mark */
#define	MTBSF		2	/* backward space over file mark (1/2" only ) */
#define	MTFSR		3	/* forward space to inter-record gap */
#define	MTBSR		4	/* backward space to inter-record gap */
#define	MTREW		5	/* rewind */
#define	MTOFFL		6	/* rewind and put the drive offline */
#define	MTNOP		7	/* no operation, sets status only */

/*--------------------------------------------------------------------------*/
Linux
/*--------------------------------------------------------------------------*/
/* Magnetic Tape operations [Not all operations supported by all drivers]: */
#define MTRESET	0	/* +reset drive in case of problems */
#define MTFSF	1	/* forward space over FileMark,
			 * position at first record of next file
			 */
#define MTBSF	2	/* backward space FileMark (position before FM) */
#define MTFSR	3	/* forward space record */
#define MTBSR	4	/* backward space record */
#define MTWEOF	5	/* write an end-of-file record (mark) */
#define MTREW	6	/* rewind */
#define MTOFFL	7	/* rewind and put the drive offline (eject?) */
#define MTNOP	8	/* no op, set status only (read with MTIOCGET) */

Operation	Description			UNIX -> Linux
====================================================================
0 weof		writes EOF (file mark)		resets drive!!!
1 fsf		forward skip file mark		OK
2 bsf		backwd skip file mark		OK
3 fsr		forward skip record		OK
4 bsr		backwd skip record		OK
5 rew		rewind				writes file mark!!!
6 offl		unload media			partially OK
7 nop		set status in driver		unloads media
8						NOP is mapped to the vendor dependant
						range. On Sun this is a retension
						which takes a long time...


The rmt server and client code used in the star distribution voids
these problems with Linux.

#
# @(#)README.otherbugs 1.3 20/08/09 Copyright 2001-2020 J. Schilling
#

I compared several tar implementations with the standard.

	(IEEE/Posix1003/IEC-9945-1 Standard Data Interchange format)

Although the POSIX.1-1988 standard now also defines cpio as an exchange format,
I cannot recommend the cpio archive format for data exchange. There are at
least 6 totally incompatible archive formats - all covered by the name "cpio".
Not all of these formats are supported by all implementations. If you like to
extend the cpio archive format, you need to introduce a completely new variant
that is most likely not understood by other implementations.

David Korn introduced a cpio based format that cheats with the filename length
and adds more meta data after the nul byte from the filename. This proposal has
been discussed by the POSIX committee and given up in favor of the current
enhanced tar.

Note that POSIX.1-2001 will drop the cpio format from the standard as it
is not extendible (e.g. for large files > 8 GB and UID's > 2097151).

Tar in general will at least extract most of the files if you are using a
different implementation to extract the archive.

I've had a look at the following implementations:

	Index:	Program description:		Source of program:
	=====	====================		==================
	1)	bsd 4.3 tar			(Regents of UCB)
	2)	pax / ustar on SunOS 4.1	(USENIX)
	3)	tar on  Solaris 2.3/2.4/2.5	(Sun/AT&T ??)
	4)	gnutar	1.11.8			(gnu)
	5)	gnucpio 2.3			(gnu)


Summary:
	1)	bsd 4.3 tar
		Pre Posix 1003.1

		- Miscomputes the checksum. Therefore it is not able to extract
		  standard conforming tar archives if they contain 8bit chars
		  in the filename. This is a common bug found in many other
		  implementations as well.

		No additional problems on portability except with gnutar
		archives. But this is not a problem of BSD tar.


	2)	pax / ustar (found on SunOS-4.x)

		- Dumps core on every even/odd use.
		- Computes checksums only on the first 500 bytes of the
		  tar header: not conforming to Posix 1003.1 standard.

		Note:	This claims to be a reference implementation for
			the Posix 1003.1 standard!


	3)	tar distributed with Solaris 2.3/2.4/2.5

		- Transfers more than 12 Bit from stat.st_mode (violating Posix)
		- Complains about "impossible file type" when reading
		  tar archives which do not contain these illegal upper bits.
		  This problem is still present in Solaris 7 & Solaris 8,
		  it has been fixed with Solaris 11 (OpenSolaris).

		- Does not handle non null terminated filenames correctly.
		  The standard allows filenames that are exactly 100 chars
		  and therefore are not null terminated. (Fixed in Solaris 2.5)

		For the above reasons, Sun's older tar versions are not
		conforming to Posix 1003.1.

		- Loops infinitely when trying to dump /dev/fd.
		  Caused by incorrect handling of nested directories (assumes
		  all directories seekable).
		  This makes it impossible to use Solaris tar on the root file
		  system. This has been fixed with Solaris 11 (OpenSolaris).


	4)	gnutar
		Claims not to be conforming to Posix 1003.1. (gnu is not tar)

		- Many bugs in implementation and design.
		  (e.g. when handling/creating multi volume archives)

		- The second logical EOF block in GNU-tar archives is missing
		  with a 50% chance.
		  This will cause correctly working tar implementations to
		  complain about an illegal/missing EOF in the tar archive.
		  This bug seems to be fixed with newer 1.13 releases

		- Deeply nested directory trees will not be dumped:
		  Error message is: Too many open files
		  (This is a similar implementation bug as found in Solaris tar
		  with the /dev/fd loop) caused by the fact that GNU-tar
		  assumes infinite resources in file descriptors.

		- Hard links with long names to files with long names do not
		  work. This bug seems to be fixed with newer 1.13 releases.

		- GNU-tar cannot read Posix compliant tar archives with
		  long file names if the filename prefix it at least
		  138 characters. GNU-tar will think that it found an extended
		  sparse GNU tar archive and gets out of sync for the rest of
		  the archive.
		  See --sparse design bug description below.
		  This bug seems to be partially fixed with newer 1.13 releases
		  Even GNU-tar-1.13.19 does not seem to evaluate USTAR magic
		  and version to distinguish between a POSIX tar archive and a
		  non-standard GNU-tar archive.

		- GNU-tar even has a not yet identified bug which causes GNUtar
		  not to be able to partially read star archives if these
		  archives are not created with star -Hustar
		  May be this is caused by aspects of the topic above.

		- Option --sparse produces archives which cannot be read by any
		  other tar implementation known to me (except star), because
		  they will get "out of sync".
		  Posix 1003.1 conforming tar archives let gnutar get
		  "out of sync" even if the --portability option is used (see
		  above). This is a severe design bug in GNU-tar.

			Description:
			The size field in a tar archive cannot reflect the
			real size of a sparse file to have compatibility to
			other implementations (this is also true for "star"
			archives but star archives use a value in the size
			field that is understood by other tar implementations).

			If the "sparse" file contains more than 4 holes,
			the "size" field in the GNU-tar control block does not
			reflect the total size of the (shrunk) sparse file in
			the archive because it does not count the 'sparse'
			extension headers. Posix compliant archives that use
			the name prefix field with more than 137 characters
			will have a value != 0 on a field that that makes
			gnutar believe that such an extension header is
			present - GNU-tar will get out of sync.

			Note: The general rule for any tar is that it should
			be able to read any "tar" compliant data stream with
			the exception that enhancements to the standard
			only will fail on the files that contain the extension.
			Those files should be extracted as if they were
			regular files.

		- When GNU-tar writes archives it is not able to write long
		  filenames correctly according to POSIX.1-1988 or to
		  POSIX.1-2001. As GNU-tar uses a non-standard extension to
		  handle filenames > 100 chars, GNU-tar is a frequent problem
		  of the portability of archives. Is is not uncommon that the
		  length of filenames exceeds 100 chars, while > 99% of the
		  long filenames do not exceed ~ 230 chars. So most of the
		  long filenames may be handled by the POSIX.1-1988 method
		  which has been first documented in the 1987 draft of the
		  POSIX.1 standard. I strongly recommend not to use GNU-tar
		  to create archives for source exchange for this reason.

		- Newer version of GNU-tar support to archive files with
		  a filename longer than PATH_MAX, but they are unable to
		  unpack these own archives.

		- GNU-tar claims to implement support for the base-256
		  encoding scheme for numbers, introduced in 1999 by star
		  but GNU-tar does not correctly handle these numbers in
		  case they are negative. As a result, GNU-tar cannot handle
		  time stamps from before Jan 1 1970 if the archive is not
		  including POSIX.1-2001 extended headers.

		It is bad to see that now (in 2001), 11 years after the
		POSIX.1-1988 standard has become accepted, GNU-tar still does
		not conform to this POSIX standard. Even worse: the first
		draft of the POSIX.1-1988 standard that did not deviate from
		the final in important things, appeared in autumn 1987. This
		is about the first time when PD-tar which was the base for
		GNU-tar appeared. PD-tar (in 1987) _did_ follow the POSIX.1
		standard with one single exception: it did not implement long
		filenames (filenames > 100 chars) at all. The non-standard GNU
		method of handling long filenames has been introduced in 1989
		by people from FSF. At this time, GNU-tar did not yet use the
		POSIX.1 filename prefix for other non-POSIX purposes, so there
		is no excuse for the non-standard way that FSF went. Don't
		believe the false GNU-tar history from FSF. I send a correct
		GNU-tar history to FSF in 1994, FSF still has to correct their
		false claims about GNU-tar history.

		See also https://web.archive.org/web/20000606160915/http://www.geocrawler.com/archives/3/92/1997/2/0/2217471/
		as a proof that a previous GNU tar maintainer did admit the
		wrong design done by FSF members in the past.

		Summary: The main problem with GNU-tar, when it is reading TAR
		archives, is that assumes all tar archives to be non-standard
		GNU-tar archives. It does not implement a TAR format detection
		based on the actual header format (as found in star) in total.
		Instead, it seems to have peep-hole based decisions on how to
		interpret parts of the TAR haeder. This can never work
		correctly.

		Note: I do not recommend GNU tar as an exchange format.
		      Use star -Hustar for maximum portability instead.
		      If you like to write archives compliant to POSIX-1.2001
		      use star -Hexustar to create archives with extended POSIX
		      headers.

	5)	gnucpio

		- Splits long filenames at the leftmost '/' instead of the
		  rightmost position of '/' required by my copy of the
		  Posix standard.

		- The docs claim compatibility with gnutar.
		  But extraction of gnutar archives containing 'atime' gives
		  funny filenames! (try this ...)

		- Octal numbers are left padded with ' ' instead of '0'.
		  The mode field contains more than the lower 12 bits from
		  stat.st_mode.

Star includes a pattern matcher based on the algorithm
presented by Martin Richards in:

"A Compact Function for Regular Expression Pattern Matching",
Software-Practice and Experience, Vol. 9, 527-534 (1979)

Several changes have been made to the original source which has been
written in BCPL:

'/'	is replaced by	'!'		(to allow UNIX filenames)
'(',')' are replaced by	'{', '}'
'\''	is replaced by	'\\'		(UNIX compatible quote)

Character classes have been added to allow "[<character list>]"
to be used.
Start of line '^' and end of line '$' have been added.

A description is available in the man page for the match program.
It may be found in man/man1/match.1

The new command 'spax' implements a POSIX.1 pax style command line interface
on top of star. The command is basically SUSv2/UNIX-98

The following extensions from SVSv3 / POSIX.1-2001 are implemented:

-	The options -H and -L

-	Support for the PSOX.1-2001 extended TAR header format
	called 'pax'. This makes 'spax' the first pax like command that
	supports this infinitely extensible and highly portable archive
	format.

The following limitations currently apply:

-	No support for the -l option (create hard links if possible
	in copy mode).

-	The privileges option -pa is ignored

-	The privileges option -pm will not only not set the mtime
	but also not set the atime in extract and copy mode.

-	without  -po SUID/SGID permission bits are not masked off.

-	Pattern matching for command line type args is not yet POSIX/PAX
	compliant. It should emulate the shell's way of matching file names
	where '/' is not part of the pattern and each path name component
	needs to match separately, but it treats a filename like an unstructured
	piece of text.

Although there are several limitations, spax should be POSIX compliant enough
for the everyday work.

Rationale: spax only implements a limited set of options to grant best POSIX
compliance. Anything you can do with spax may also be done with star. To be able
to do this, a new set of options has been added to star for this reason.

/*--------------------------------------------------------------------------*/

The following non POSIX related CPIO limitations currently apply:

-	The checksum with the -Hcrc format is not evaluated in extract mode.

-	Reading the binary cpio format is not yet fully supported.
	This format suffers from design related byte order problems.
	Star thus is unable to auto-detect the byte order status in
	all cases. Auto-detection should work if the string lenght
	if the first filename is odd.

-	Append & Update (star -r & star -u) does not yet work for
	CPIO archives.


These CPIO limitations would be of interest if we would create a 'cpio'
command line program from the star sources.

Hints for using extended POSIX.1-2001 headers:

	Star will understand extended headers if the archive format
	is from 'star', 'ustar', 'pax', 'xustar', 'exustar'.
	In addition, star will understand the POSIX-look-alike
	extended headers from Sun's tar (Solaris) if 'suntar' is selected
	or autodetected.

	Star will create extended POSIX headers when the archive format
	is 'pax', 'xustar' or 'exustar'. When the archive format is
	'exustar', every file will get an extended header which holds
	at least atime/ctime/mtime in sub-second resolution.
	If the archive format is 'pax' or 'xustar', star will create
	the extended header only if there is a need for the extended header
	because one or more of the fields do not fit into the standard ustar
	header.

	Star supports the following fields in the extended header:

	times: "atime"  "ctime"  "mtime"	(create/extract)

	id's (numeric): "uid", "gid"		(create/extract)

	id's (names): "uname", "gname"		(extract only)

	pathnames: "path" "linkpath"		(create/extract)

	filesize: "size"			(create/extract)

	Additional: "charset", "comment"	(extract only - ignored)

	Vendor unique:
	"SCHILY.devmajor" "SCHILY.devminor"	(create/extract)

	In -dump mode (a preparation for incremental dumps) star archives:

	"SCHILY.dev"		The field stat.st_dev	- the filesys indicator
	"SCHILY.ino"		The field stat.st_ino	- the file ID #
	"SCHILY.nlink"		The field stat.st_nlink	- the hard link count
	"SCHILY.filetype"	The real file type 	- this allows e.g.
							  socket/door

	These fields will in future allow star to archive and extract all
	information that is needed for incremental dumps.

	Star now includes ALL file metadata that is available. This allows a
	complete restauration of all file properties and a diff mode that
	checks for diffs in all file properties.

	Sun compatibility:
	"SUN.devmajor"  "SUN.devminor"		(extract only)

	With -Hsuntar:
	"SUN.devmajor"  "SUN.devminor"		(create/extract)

	TODO List for extended headers:

	-	Add better UNICODE support

	-	Add some way of handling UID/GID Overflow in the
		traditional 7 char fields which limit to 2097151.

	-	Add support for sparse files and continuation Files
		into the extended header stuff (as Vendor UNIQUE extensions
		with 'SCHILY.*' name).

	How to use extended POSIX.1-2001 headers:

	-	To emmit xhdr's only if really needed, use 'star -Hpax'
		or 'star -Hxustar'. In this case extended headers will be
		created if the path/linkname will not fit into the 'ustar'
		header or if the filesize is > 8 GB or uid/gid will not fit
		07777777.

	-	To emmit xhdr's always, use 'star -Hexustar' and even when
		no other extended attribute is needed atime/mtime/ctime are
		written in sub-second resolution.

	-	To write extended headers similar to POSIX.1-2001 as used by
		the Solaris tar, use 'star -Hsuntar' and every file will at
		least get a sub-second resolution mtime. Note that Sun's main
		intention was to handle very long filenames and big uid/gid's.

#ident @(#)readme.mk	1.1 07/06/15
###########################################################################
# Sample makefile for installing non-localized auxiliary files
###########################################################################
SRCROOT=	..
RULESDIR=	RULES
include		$(SRCROOT)/$(RULESDIR)/rules.top
###########################################################################

INSDIR=		share/doc/star
TARGET=		README
#XMK_FILE=	Makefile.man

###########################################################################
include		$(SRCROOT)/$(RULESDIR)/rules.aux
###########################################################################