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

FreeBSD Manual Pages

  
 
  

home | help
STAR(4L)		    Schily's USER COMMANDS		      STAR(4L)

NAME
       star - tape archive file	format

DESCRIPTION
       Tar  Archives  are layered archives.  The basic structure is defined by
       the POSIX.1-1988	archive	format and documented in the BASIC TAR	HEADER
       DESCRIPTION  section  below.   The higher level structure is defined by
       the POSIX.1-2001	extended headers and documented	in  the	 EXTENDED  TAR
       (PAX)  HEADER  STRUCTURE	 section below.	 POSIX.1-2001 extended headers
       are pseudo files	that contain an	unlimited number  of  extended	header
       keywords	 and  associated values. The header keywords are documented in
       the EXTENDED TAR	(PAX) HEADER KEYWORDS section below.

BASIC TAR HEADER DESCRIPTION
       Physically, a POSIX.1-1988 tar archive consists of a  series  of	 fixed
       sized  blocks of	TBLOCK (512) characters.  It contains a	series of file
       entries terminated by a logical end-of-archive marker,  which  consists
       of two blocks of	512 bytes of binary zeroes.  Each file entry is	repre-
       sented by a header block	that describes the file	 followed  by  one  or
       more  blocks  with  the content of the file. The	length of each file is
       rounded up to a multiple	of 512 bytes.

       A number	of TBLOCK sizes	blocks are grouped together to a  tape	record
       for  physical I/O operations. Each record of n blocks is	written	with a
       single write(2) operation.  On magnetic tapes, this results in a	single
       tape record in case the tape drive is in	variable length	record mode.

       The header block	is defined in star.h as	follows:
       /*
	* POSIX.1-1988 field size values and magic.
	*/
       #define	 TBLOCK		512
       #define	 NAMSIZ		100
       #define	 PFXSIZ		155

       #define	 TMODLEN	8
       #define	 TUIDLEN	8
       #define	 TGIDLEN	8
       #define	 TSIZLEN	12
       #define	 TMTMLEN	12
       #define	 TCKSLEN	8

       #define	 TMAGIC		"ustar"	  /* ustar magic 6 chars + '\0'	*/
       #define	 TMAGLEN	6	  /* "ustar" including '\0' */
       #define	 TVERSION	"00"
       #define	 TVERSLEN	2
       #define	 TUNMLEN	32
       #define	 TGNMLEN	32
       #define	 TDEVLEN	8

       /*
	* POSIX.1-1988 typeflag	values
	*/
       #define	 REGTYPE	'0'  /*	Regular	File	      */
       #define	 AREGTYPE	'\0' /*	Regular	File (outdated)	*/
       #define	 LNKTYPE	'1'  /*	Hard Link	      */
       #define	 SYMTYPE	'2'  /*	Symbolic Link	      */
       #define	 CHRTYPE	'3'  /*	Character Special     */
       #define	 BLKTYPE	'4'  /*	Block Special	      */
       #define	 DIRTYPE	'5'  /*	Directory	      */
       #define	 FIFOTYPE	'6'  /*	FIFO (named pipe)     */
       #define	 CONTTYPE	'7'  /*	Contiguous File	      */

       /*
	* POSIX.1-2001 typeflag	extensions.
	* POSIX.1-2001 calls the extended USTAR	format PAX although it is
	* definitely derived from and based on USTAR. The reason may be	that
	* POSIX.1-2001 calls the tar program outdated and lists	the
	* pax program as the successor.
	*/
       #define	 LF_GHDR	'g'  /*	POSIX.1-2001 global extended header */
       #define	 LF_XHDR	'x'  /*	POSIX.1-2001 extended header */

       See  section  EXTENDED  TAR  (PAX) HEADER KEYWORDS for more information
       about the structure of a	POSIX.1-2001 header.

       /*
	* star/gnu/Sun tar extensions:
	*
	* Note that the	standards committee allows only	capital	A through
	* capital Z for	user-defined expansion.	 This means that defining
	* something as,	say '8'	is a *bad* idea.
	*/

       #define	 LF_ACL		'A'  /*	Solaris	Access Control List	*/
       #define	 LF_DUMPDIR	'D'  /*	GNU dump dir			*/
       #define	 LF_EXTATTR	'E'  /*	Solaris	Extended Attribute File	*/
       #define	 LF_META	'I'  /*	Inode (metadata	only) no file content */
       #define	 LF_LONGLINK	'K'  /*	NEXT file has a	long linkname	*/
       #define	 LF_LONGNAME	'L'  /*	NEXT file has a	long name	*/
       #define	 LF_MULTIVOL	'M'  /*	Continuation file rest to be skipped */
       #define	 LF_NAMES	'N'  /*	OLD GNU	for names > 100	characters   */
       #define	 LF_SPARSE	'S'  /*	This is	for sparse files	*/
       #define	 LF_VOLHDR	'V'  /*	tape/volume header Ignore on extraction	*/
       #define	 LF_VU_XHDR	'X'  /*	POSIX.1-2001 xtended (Sun VU version) */

       /*
	* Definitions for the t_mode field
	*/
       #define	 TSUID	   04000     /*	Set UID	on execution  */
       #define	 TSGID	   02000     /*	Set GID	on execution  */
       #define	 TSVTX	   01000     /*	On directories,	restricted deletion flag */
       #define	 TUREAD	   00400     /*	Read by	owner	      */
       #define	 TUWRITE   00200     /*	Write by owner special */
       #define	 TUEXEC	   00100     /*	Execute/search by owner	*/
       #define	 TGREAD	   00040     /*	Read by	group	      */
       #define	 TGWRITE   00020     /*	Write by group	      */
       #define	 TGEXEC	   00010     /*	Execute/search by group	*/
       #define	 TOREAD	   00004     /*	Read by	other	      */
       #define	 TOWRITE   00002     /*	Write by other	      */
       #define	 TOEXEC	   00001     /*	Execute/search by other	*/

       #define	 TALLMODES 07777     /*	The low	12 bits	      */

       /*
	* This is the ustar (Posix 1003.1) header.
	*/
       struct header {
	    char t_name[NAMSIZ];     /*	  0 Filename		   */
	    char t_mode[8];	     /*	100 Permissions		   */
	    char t_uid[8];	     /*	108 Numerical User ID	   */
	    char t_gid[8];	     /*	116 Numerical Group ID	   */
	    char t_size[12];	     /*	124 Filesize		   */
	    char t_mtime[12];	     /*	136 st_mtime		   */
	    char t_chksum[8];	     /*	148 Checksum		   */
	    char t_typeflag;	     /*	156 Typ	of File		   */
	    char t_linkname[NAMSIZ]; /*	157 Target of Links	   */
	    char t_magic[TMAGLEN];   /*	257 "ustar"		   */
	    char t_version[TVERSLEN]; /* 263 Version fixed to 00   */
	    char t_uname[TUNMLEN];   /*	265 User Name		   */
	    char t_gname[TGNMLEN];   /*	297 Group Name		   */
	    char t_devmajor[8];	     /*	329 Major for devices	   */
	    char t_devminor[8];	     /*	337 Minor for devices	   */
	    char t_prefix[PFXSIZ];   /*	345 Prefix for t_name	   */
				     /*	500 End			   */
	    char t_mfill[12];	     /*	500 Filler up to 512	   */
       };

       /*
	* star header specific definitions
	*/
       #define	 STMAGIC	"tar"	  /* star magic	*/
       #define	 STMAGLEN	4	  /* "tar" including '\0' */

       /*
	* This is the new (post	Posix 1003.1-1988) xstar header
	* defined in 1994.
	*
	* t_prefix[130]	   is guaranteed to be ' ' to prevent ustar
	*		   compliant implementations from failing.
	* t_mfill & t_xmagic need to be	zero for a 100%	ustar compliant
	*		   implementation, so setting t_xmagic to
	*		   "tar" should	be avoided in the future.
	*
	* A different method to	recognize this format is to verify that
	* t_prefix[130]		     is	equal to ' ' and
	* t_atime[0]/t_ctime[0]	     is	an octal number	and
	* t_atime[11]		     is	equal to ' ' and
	* t_ctime[11]		     is	equal to ' '.
	*
	* Note that t_atime[11]/t_ctime[11] may	be changed in future.
	*/
       struct xstar_header {
	    char t_name[NAMSIZ];     /*	  0 Filename		   */
	    char t_mode[8];	     /*	100 Permissions		   */
	    char t_uid[8];	     /*	108 Numerical User ID	   */
	    char t_gid[8];	     /*	116 Numerical Group ID	   */
	    char t_size[12];	     /*	124 Filesize		   */
	    char t_mtime[12];	     /*	136 st_mtime		   */
	    char t_chksum[8];	     /*	148 Checksum		   */
	    char t_typeflag;	     /*	156 Typ	of File		   */
	    char t_linkname[NAMSIZ]; /*	157 Target of Links	   */
	    char t_magic[TMAGLEN];   /*	257 "ustar"		   */
	    char t_version[TVERSLEN]; /* 263 Version fixed to 00   */
	    char t_uname[TUNMLEN];   /*	265 User Name		   */
	    char t_gname[TGNMLEN];   /*	297 Group Name		   */
	    char t_devmajor[8];	     /*	329 Major for devices	   */
	    char t_devminor[8];	     /*	337 Minor for devices	   */
	    char t_prefix[131];	     /*	345 Prefix for t_name	   */
	    char t_atime[12];	     /*	476 st_atime		   */
	    char t_ctime[12];	     /*	488 st_ctime		   */
	    char t_mfill[8];	     /*	500 Filler up to star magic	*/
	    char t_xmagic[4];	     /*	508 "tar"		   */
       };

       struct sparse {
	    char t_offset[12];
	    char t_numbytes[12];
       };

       #define	 SPARSE_EXT_HDR	 21

       struct xstar_ext_header {
	    struct sparse t_sp[21];
	    char t_isextended;
       };

       typedef union hblock {
	    char dummy[TBLOCK];
	    long ldummy[TBLOCK/sizeof (long)]; /* force	long alignment */
	    struct header	     dbuf;
	    struct xstar_header	     xstar_dbuf;
	    struct xstar_ext_header  xstar_ext_dbuf;
       } TCB;

       For maximum portability,	all  fields  that  contain  character  strings
       should be limited to use	the low	7 bits of a character.

       The  name,  linkname  and  prefix  field	contain	character strings. The
       strings are null	terminated except when they use	the full space of  100
       characters  for	the  name  or linkname field or	155 characters for the
       prefix field.

       If the prefix does not start with a null	 character,  then  prefix  and
       name  need  to be concatenated by using the prefix, followed by a slash
       character followed by the name field.  If a null	character  appears  in
       name  or	 prefix	before the maximum size	is reached, the	field in ques-
       tion is terminated.  This way file names	up to 256  characters  may  be
       archived.   The prefix is not used together with	the linkname field, so
       the maximum length of a link name is 100	characters.

       The fields magic, uname and gname  contain  null	 terminated  character
       strings.

       The  version field contains the string "00" without a trailing zero. It
       cannot be set to	different values as POSIX.1-1988 did not specify a way
       to handle different version strings.

       The typeflag field contains a single character.

       All  numeric  fields  contain  size-1 leading zero-filled numbers using
       octal digits.  They are followed	by one or more space or	 null  charac-
       ters.   All recent implementations only use one space or	null character
       at the end of a numerical field to get maximum space for	the octal num-
       ber.  Star always uses a	space character	as terminator.	Numeric	fields
       with 8 characters may hold up to	7 octal	digits (7777777) which results
       is  a  maximum value of 2097151.	 Numeric fields	with 12	characters may
       hold up to 11 octal digits (77777777777)	which  results	is  a  maximum
       value of	8589934591.

       Star implements a vendor	specific (and thus non-POSIX) extension	to put
       bigger numbers into the numeric fields. This is done by	using  a  base
       256  coding.   The  top bit of the first	character in the appropriate 8
       character or 12 character field is set to flag non  octal  coding.   If
       base  256  coding  is in	use, then all remaining	characters are used to
       code the	number.	This results in	7  base	 256  digits  in  8  character
       fields  and in 11 base 256 digits in 12 character fields.  All base 256
       numbers are two's complement numbers. A base 256	number in a 8  charac-
       ter  field  may hold 56 bits, a base 256	number in a 12 character field
       may hold	88 bits. This may be extended  to  63  bits  for  8  character
       fields  and  to	95 bits	for 12 character fields. For a negative	number
       the first character currently is	set to a value of 255 (all 8 bits  are
       set).   The  rightmost  character in a 8	or 12 character	field contains
       the least significant base 256 number.  Recent GNU tar versions	imple-
       ment the	same extension.

       While  the  POSIX  standard makes it obvious that the fields mode, uid,
       gid,  size, chksum, devmajor and	devminor should	be treated as unsigned
       numbers,	there is no such definition for	the time field.

       The  mode field contains	12 bits	holding	permissions, see above for the
       definitions for each of the permission bits.

       The uid and gid fields contain the numerical user id of the file.

       The size	field contains the size	of the file in characters.  If the tar
       header  is  followed by file data, then the amount of data that follows
       is computed by (size + 511) / 512.

       The mtime field contains	the number of seconds since Jan	1st 1970 00:00
       UTC as retrived via stat(2) in st_mtime.	 If the	mtime fiels is assumed
       to be a signed 33 bit number, the latest	representable time is 2106 Feb
       7 06:28:15 GMT.

       The  chksum  field  contains  a	simple	checksum over all bytes	of the
       header.	To compute the value, all characters in	the header are treated
       as unsigned integers and	the characters in the chksum field are treated
       as if they were all spaces. When	the computation	starts,	 the  checksum
       value is	initialized to 0.

       The  typeflag field specifies the type of the file that is archived. If
       a specific tar implementation does not include support for  a  specific
       typeflag	value, this implementation will	extract	the unknown file types
       as if they were plain files. For	this reason, the size  field  for  any
       file  type  except  directories,	 hard links, symbolic links, character
       special,	block specials and FIFOs must  always  follow  the  rules  for
       plain files.

       '0' REGTYPE
	      A	 regular  file.	 If the	size field is non zero,	then file data
	      follows the header.

       '\0' AREGTYPE
	      For backwards compatibility with pre POSIX.1-1988	tar  implemen-
	      tations,	a nul character	is also	recognized as marker for plain
	      files.  It is not	generated by recent tar	 implementations.   If
	      the size field is	non zero, then file data follows the header.

       '1' LNKTYPE
	      The  file	 is a hard link	to another file.  The name of the file
	      that the file is linked to  is  in  the  linkname	 part  of  the
	      header.	For tar	archives written by pre	POSIX.1-1988 implemen-
	      tations, the size	field usually contains the size	 of  the  file
	      and  needs to be ignored as no data may follow this header type.
	      For POSIX.1-1988 compliant archives, the size field needs	to  be
	      0.   For	POSIX.1-2001 compliant archives, the size field	may be
	      non zero,	indicating that	file data is included in the archive.

       '2' SYMTYPE
	      The file is a symbolic link to another file.  The	 name  of  the
	      file  that  the file is linked to	is in the linkname part	of the
	      header.  The size	field needs to be 0.  No file data may	follow
	      the header.

       '3' CHRTYPE
	      A	character special file.	 The fields devmajor and devminor con-
	      tain information that defines the	file.  The meaning of the size
	      field  is	 unspecified  by the POSIX standard.  No file data may
	      follow the header.

       '4' BLKTYPE
	      A	block special file.  The fields	devmajor and devminor  contain
	      information  that	 defines  the  file.   The meaning of the size
	      field is unspecified by the POSIX	standard.  No  file  data  may
	      follow the header.

       '5' DIRTYPE
	      A	 directory or sub directory. Old (pre POSIX.1-1988) tar	imple-
	      mentations did use the same typeflag value as  for  plain	 files
	      and  added  a  slash to the name.	 If the	size field is non zero
	      then it indicates	the maximum size in characters the system  may
	      allocate	for  this  directory. If the size field	is 0, then the
	      system shall not limit the size of the directory.	 On  operating
	      systems  where  the  disk	 allocation is not done	on a directory
	      base, the	size field is ignored on extraction.  No file data may
	      follow the header.

       '6' FIFOTYPE
	      A	 named	pipe.  The meaning of the size field is	unspecified by
	      the POSIX	standard.  The size field must be ignored  on  extrac-
	      tion.  No	file data may follow the header.

       '7' CONTTYPE
	      A	 contiguous  file.   This is a file that gives special perfor-
	      mance attributes.	 Operating systems  that  don't	 support  this
	      file  type  extract  this	file type as plain files.  If the size
	      field is non zero, then file data	follows	the header.

       'g' GLOBAL POSIX.1-2001 HEADER
	      With POSIX.1-2001	pax  archives,	this  type  defines  a	global
	      extended	header.	  The  size is always non zero and denotes the
	      sum of the length	fields in the extended header data.  The  data
	      that  follows  the  header is in the pax extended	header format.
	      The extended header records in this header type affect all  fol-
	      lowing  files  in	the archive unless they	are overwritten	by new
	      values.  See EXTENDED TAR	(PAX) HEADER FORMAT section below.

       'x' EXTENDED POSIX.1-2001 HEADER
	      With POSIX.1-2001	pax archives, this type	 defines  an  extended
	      header.	The size is always non zero and	denotes	the sum	of the
	      length fields in the extended header data.  The data  that  fol-
	      lows  the	 header	 is  in	 the  pax extended header format.  The
	      extended header records in this header type only affect the fol-
	      lowing  file in the archive.  See	EXTENDED TAR (PAX) HEADER FOR-
	      MAT section below.

       'A' - 'Z'
	      Reserved for vendor specific implementations.

       'A'    A	Solaris	ACL entry as used by the tar implementation from  Sun.
	      The  size	 is always non zero and	denotes	the length of the data
	      that follows the header.	Star currently is not able  to	handle
	      this header type.

       'D'    A	 GNU  dump directory.  This header type	is not created by star
	      and handled like a directory during an extract operation,	so the
	      content  is  ignored by star.  The size field denotes the	length
	      of the data that follows the header.

       'E'    A	Solaris	Extended Attribute File.  The size field  denotes  the
	      length  of  the data that	follows	the header.  Star currently is
	      not able to handle this header type.

       'I'    A	inode metadata entry.  This header type	is used	by star	to ar-
	      chive  inode  meta  data	only.  To archive more inode meta data
	      than possible with a POSIX-1.1988	tar header, a header with type
	      'I' is usually preceded by a 'x' header.	It is used with	incre-
	      mental backups.  The size	field holds the	length	of  the	 file.
	      No file data follows this	header.

       'K'    A	 long  link name.  Star	is able	to read	and write this type of
	      header with the star, xstar and gnutar formats.  With the	xustar
	      and exustar formats, star	prefers	to store long link names using
	      the POSIX.1-2001 method.	 The  size  is	always	non  zero  and
	      denotes  the length of the long link name	including the trailing
	      null byte. The link name is in the data that follows the header.

       'L'    A	long file name.	 Star is able to read and write	this  type  of
	      header with the star, xstar and gnutar formats.  With the	xustar
	      and exustar formats, star	prefers	to store long file names using
	      the  POSIX.1-2001	 method.   The	size  is  always  non zero and
	      denotes the length of the	long file name including the  trailing
	      null byte. The file name is in the data that follows the header.

       'M'    A	 multi	volume continuation entry.  It is used by star to tell
	      the extraction program via the size field	when the next  regular
	      archive  header  will  follow.   This allows to start extracting
	      multi volume archives with a volume number greater than one.  It
	      is  used by GNU tar to verify multi volume continuation volumes.
	      Other fields in the GNU multi volume continuation	header	are  a
	      result  of  a  GNU  tar  miss conception and cannot be used in a
	      reliable tar implementation.  If the size	field is non zero  the
	      data  following the header is skipped by star if the volume that
	      starts with it is	mounted	as the first volume.  This  header  is
	      ignored if the volume that starts	with it	is mounted as continu-
	      ation volume.

       'N'    An outdated linktype used	by old GNU tar versions	to store  long
	      file names.  This	type is	unsupported by star.

       'S'    A	sparse file.  This header type is used by star and GNU tar.  A
	      sparse header is used instead of a plain file header to denote a
	      sparse  file  that follows. Directly after the header, a list of
	      sparse hole descriptors follows followed by the  compacted  file
	      data.   With star	formats, the size field	holds a	size that rep-
	      resents the sum of the sparse hole descriptors plus the size  of
	      the  compacted  file data. This allows other tar implementations
	      to correctly skip	to the next tar	header.	 With GNU tar, up to 4
	      sparse  hole descriptors fit into	the sparse header.  Additional
	      hole descriptors are not needed if the  file  has	 less  than  4
	      holes.   With  GNU tar, the size field breaks general tar	header
	      rules in case more than 4	sparse hole descriptors	are  used  and
	      is  meaningless  because	the size of the	additional sparse hole
	      descriptors used by GNU tar does not count and cannot be	deter-
	      mined before parsing all sparse hole descriptors.

       'V'    A	 volume	 header.  The name field is is used to hold the	volume
	      name.  Star uses the atime field to hold the  volume  number  in
	      case there is no POSIX.1-2001 extended header.  This header type
	      is used by star and GNU tar.  If the size	field is non zero  the
	      data following the header	is skipped by star.

       'X'    A	 vendor	 unique	 variant  of  the POSIX.1-2001 extended	header
	      type.  It	has been implemented by	 Sun  many  years  before  the
	      POSIX.1-2001  standard has been approved.	 See also the typeflag
	      'x' header type.	Star is	able to	read and write	this  type  of
	      header.

EXTENDED TAR (PAX) HEADER STRUCTURE
       Block type			     Description

       Ustar Header [typeflag='g']	Global Extended	Header
       Global Extended Data
       Ustar Header [typeflag='x']	   Extended Header
       Extended	Data
       Ustar header [typeflag='0']    File with	Extended Header
       Data for	File #1

       Ustar header [typeflag='0']   File without Extended Header
       Data for	File #2
       Block of	binary zeroes		   First EOF Block
       Block of	binary zeroes		   Second EOF Block

EXTENDED TAR (PAX) HEADER FORMAT
       The  data  block	that follows a tar archive header with typeflag	'g' or
       'x' contains one	or more	records	in the following format:

	      "%d %s=%s\n", _length_, _keyword_, _value_

       Each record starts with a a decimal length field. The  length  includes
       the  total  size	 of a record including the length field	itself and the
       trailing	new line.

       The keyword may not include an equal sign.  All keywords	beginning with
       lower  case letters and digits are reserved for future use by the POSIX
       standard.

       If the value field is of	zero length, it	deletes	any  header  field  of
       the same	name that is in	effect from the	same extended header or	from a
       previous	global header.

       Null characters do not delimit any value. The data used	for  value  is
       only limited by its implicit length.

EXTENDED TAR (PAX) HEADER KEYWORDS
       POSIX.1-2001  extended  pax  header  keywords. All numerical values are
       represented as decimal strings.	All texts  are	represented  as	 7-bit
       ascii or	UTF-8:

       atime  The  time	 from  st_atime	 in sub	second granularity.  Star cur-
	      rently supports a	nanosecond granularity.

       charset
	      The name of the character	set used to encode  the	 data  in  the
	      following	file(s).

	      The following values are supported for charset:

	      ISO-IR 646 1990	       SO/IEC 646:1990

	      ISO-IR 8859 1 1998       ISO/IEC 8859-1:1998

	      ISO-IR 8859 2 1998       ISO/IEC 8859-2:1998

	      ISO-IR 8859 3 1998       ISO/IEC 8859-3:1998

	      ISO-IR 8859 4 1998       ISO/IEC 8859-4:1998

	      ISO-IR 8859 5 1998       ISO/IEC 8859-5:1998

	      ISO-IR 8859 6 1998       ISO/IEC 8859-6:1998

	      ISO-IR 8859 7 1998       ISO/IEC 8859-7:1998

	      ISO-IR 8859 8 1998       ISO/IEC 8859-8:1998

	      ISO-IR 8859 9 1998       ISO/IEC 8859-9:1998

	      ISO-IR 8859 10 1998      ISO/IEC 8859-10:1998

	      ISO-IR 8859 11 1998      ISO/IEC 8859-11:1998

	      ISO-IR 8859 12 1998      ISO/IEC 8859-12:1998

	      ISO-IR 8859 13 1998      ISO/IEC 8859-13:1998

	      ISO-IR 8859 14 1998      ISO/IEC 8859-14:1998

	      ISO-IR 8859 15 1998      ISO/IEC 8859-15:1998

	      ISO-IR 10646 2000	       ISO/IEC 10646:2000

	      ISO-IR 10646 2000	UTF-8  ISO/IEC 10646, UTF-8 encoding

	      BINARY		       None

	      This keyword is currently	ignored	by star.

       comment
	      Any  number  of  characters  that	 should	be treated as comment.
	      Star ignores the comment as documented by	the POSIX standard.

       ctime  The time from st_ctime in	sub  second  granularity.   Star  cur-
	      rently supports a	nanosecond granularity.

       gid    The group	ID of the group	that owns the file.  The argument is a
	      decimal number.  This field is used if the group ID of a file is
	      greater than 2097151 (octal 7777777).

       gname  The  group  name	of the following file(s) coded in UTF-8	if the
	      group name  does	not  fit  into	32  characters	or  cannot  be
	      expressed	in 7-Bit ASCII.

       hdrcharset
	      The  name	 of  the character set used to encode the data for the
	      gname, linkpath, path  and  uname	 fields	 in  the  POSIX.1-2001
	      extended header records.

	      The following values are supported for hdrcharset:

	      ISO-IR 10646 2000	UTF-8  ISO/IEC 10646, UTF-8 encoding

	      BINARY		       None

	      This keyword is currently	ignored	by star.

       linkpath
	      The name of the linkpath coded in	UTF-8 if it is longer than 100
	      characters or cannot be expressed	in 7-Bit ASCII.

       mtime  The time from st_mtime in	sub  second  granularity.   Star  cur-
	      rently supports a	nanosecond granularity.

       path   The  name	of the linkpath	coded in UTF-8 if it does not fit into
	      100 characters + 155 characters prefix or	cannot be expressed in
	      7-Bit ASCII.

       realtime.any
	      The  keywords  prefixed  by  realtime.   are reserved for	future
	      standardization.

       security.any
	      The keywords prefixed by	security.   are	 reserved  for	future
	      standardization.

       size   The  size	 of  the  file	as  decimal number if the file size is
	      greater than 8589934591 (octal 77777777777).  The	 size  keyword
	      may  not	refer to the real file size but	is related to the size
	      if the file in the archive.  See also SCHILY.realsize  for  more
	      information.

       uid    The  uid	ID of the group	that owns the file.  The argument is a
	      decimal number.  This field is used if the uid ID	of a  file  is
	      greater than 2097151 (octal 7777777).

       uname  The  user	 name  of  the following file(s) coded in UTF-8	if the
	      user name	does not fit into 32 characters	or cannot be expressed
	      in 7-Bit ASCII.

       VENDOR.keyword
	      Any keyword that starts with a vendor name in capital letters is
	      reserved for vendor specific extensions by the  standard.	  Star
	      uses  a  lot  of	these vendor specific extension. See below for
	      more informations.

SCHILY PAX EXTENSION KEYWORDS
       Star uses own vendor specific extensions. The  SCHILY  vendor  specific
       extended	pax header keywords are:

       SCHILY.acl.ace
	      The NFSv4	ACL for	a file.

	      Since  no	 official backup format	for the	NFSv4 ACL standard has
	      been  defined,  star  uses   the	 vendor	  defined   attributes
	      SCHILY.acl.ace for storing the NFSv4 ACL entries.

	      The  format  for the ACL text is the format created by the func-
	      tion acl_totext()	from libsec on Solaris,	using the call:

	      acl_totext(aclp, \
		  ACL_COMPACT_FMT | ACL_APPEND_ID | ACL_SID_FMT);

	      The flags	have the following meaning:

	      ACL_COMPACT_FMT
		     Create the	compact	version	of the	ACL  text  representa-
		     tion.

	      ACL_APPEND_ID
		     Append uid	or gid for additional user or group entries.

	      ACL_SID_FMT
		     Use the usersid or	groupsid format	for entries related to
		     an	ephemeral uid or gid.  The raw sid format will only be
		     used when the "id"	cannot be resolved to a	windows	name.

	      This  is	an  example  of	 the format used for SCHILY.acl.ace (a
	      space has	been inserted after the	equal sign and lines are  bro-
	      ken [marked with '\' ] for readability):

	      SCHILY.acl.ace= user:lisa:rwx-----------:-------:allow:502, \
			  group:toolies:rwx-----------:-------:allow:102, \
				 owner@:--x-----------:-------:deny,  \
				 owner@:rw-p---A-W-Co-:-------:allow, \
				 group@:-wxp----------:-------:deny,  \
				 group@:r-------------:-------:allow, \
			      everyone@:-wxp---A-W-Co-:-------:deny,  \
			      everyone@:r-----a-R-c--s:-------:allow

	      The  numerical  user  and	 group	identifiers are	essential when
	      restoring	a system completely from a backup,  as	initially  the
	      name-to-identifier  mappings may not be available, and then file
	      ownership	restoration would not work.

	      In addition to the documented entry format, a compatible	imple-
	      mentation	needs to be able to understand the long	ace format, if
	      it appears in extended tar headers.

	      As the archive format that is used for backing up	access control
	      lists  is	 compatible with the pax archive format, archives cre-
	      ated that	way can	be restored by star or a POSIX.1-2001  compli-
	      ant pax.	Note that programs other than star will	ignore the ACL
	      information.

       SCHILY.acl.access
	      The withdrawn POSIX draft	ACL for	a file.

	      Since no official	backup format for the  withdrawn  POSIX	 draft
	      access  control  lists  has  been	 defined, star uses the	vendor
	      defined attributes SCHILY.acl.access and SCHILY.acl.default  for
	      storing  the  ACL	 and Default ACL of a file, respectively.  The
	      access control lists are	stored	in  the	 short	text  form  as
	      defined in the withdrawn POSIX 1003.1e draft standard 17.

	      Note that	the POSIX 1003.1e draft	has been withdrawn in 1997 but
	      some operating systems still support it with some	filesystems.

	      To each named user ACL entry  a  fourth  colon  separated	 field
	      field  containing	 the  user  identifier (UID) of	the associated
	      user is appended.	 To each named group entry a fourth colon sep-
	      arated  field containing the group identifier (GID) of the asso-
	      ciated group is appended.	  (POSIX  1003.1e  draft  standard  17
	      allows to	add fields to ACL entries.)

	      This  is	an example of the format used for SCHILY.acl.access (a
	      space has	been inserted after the	equal sign and lines are  bro-
	      ken  [marked  with  '\'  ] for readability, additional fields in
	      bold):

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

	      The numerical user and  group  identifiers  are  essential  when
	      restoring	 a  system  completely from a backup, as initially the
	      name-to-identifier mappings may not be available,	and then  file
	      ownership	restoration would not work.

	      As the archive format that is used for backing up	access control
	      lists is compatible with the pax archive format,	archives  cre-
	      ated  that way can be restored by	star or	a POSIX.1-2001 compli-
	      ant pax.	Note that programs other than star will	ignore the ACL
	      information.

       SCHILY.acl.default
	      The  default  ACL	 for  a	 file.	See SCHILY.acl.access for more
	      information.

	      This is an example of the	format used for	SCHILY.acl.default  (a
	      space  has been inserted after the equal sign and	lines are bro-
	      ken [marked with '\' ] for  readability,	additional  fields  in
	      bold):

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

       SCHILY.acl.type
	      The ACL type used	for coding access control lists.

	      The following ACL	types are possible:

	      POSIX draft
		     ACLs  as  defined	in  the	 withdrawn POSIX 1003.1e draft
		     standard 17.

	      NFSv4  ACLs as used by NFSv4, NTFS and ZFS.

       Note that the SCHILY.acl.type keyword is	 currently  not	 generated  by
       star.   Star however accepts this keyword if it appears in extended tar
       headers.	 The ACL type is determined from the keyword type  that	 holds
       the ACL text.

       SCHILY.ddev
	      The  device  ids for names used is the SCHILY.dir	dump directory
	      list from	st_dev of the file as decimal number.  The SCHILY.ddev
	      keyword  is followed by a	space separated	list of	device id num-
	      bers. Each corresponds exactly to	a name in the  list  found  in
	      SCHILY.dir.  If a	specific device	id number is repeated, a comma
	      (,) without a following space may	be use to denote that the cur-
	      rent device id number is identical to the	previous number.  This
	      keyword is used in dump mode.  This keyword is  not  yet	imple-
	      mented.

	      The  value is a signed int.  An implementation should be able to
	      handle at	least 64 bit values.  Note that	the  value  is	signed
	      because  POSIX  does not specify more than the type should be an
	      int.

       SCHILY.dev
	      The device id from st_dev	of the file as decimal	number.	  This
	      keyword is used in dump mode.

	      The  value is a signed int.  An implementation should be able to
	      handle at	least 64 bit values.  Note that	the  value  is	signed
	      because  POSIX  does not specify more than the type should be an
	      int.

       SCHILY.devmajor
	      The device major number of the file if  it  is  a	 character  or
	      block  special  file.   The  argument is a decimal number.  This
	      field is used if the device major	of the file  is	 greater  than
	      2097151 (octal 7777777).

	      The  value is a signed int.  An implementation should be able to
	      handle at	least 64 bit values.  Note that	the  value  is	signed
	      because  POSIX  does not specify more than the type should be an
	      int.

       SCHILY.devminor
	      The device minor number of the file if  it  is  a	 character  or
	      block  special  file.   The  argument is a decimal number.  This
	      field is used if the device minor	of the file  is	 greater  than
	      2097151 (octal 7777777).

	      The  value is a signed int.  An implementation should be able to
	      handle at	least 64 bit values.  Note that	the  value  is	signed
	      because  POSIX  does not specify more than the type should be an
	      int.

       SCHILY.dino
	      The inode	numbers	for names used is the SCHILY.dir  dump	direc-
	      tory  list  from	st_ino	of  the	 file  as decimal number.  The
	      SCHILY.dino keyword is followed by a  space  separated  list  of
	      inode  numbers.  Each  corresponds exactly to a name in the list
	      found in SCHILY.dir.  This keyword is used in dump mode.

	      The values are unsigned int.  An implementation should  be  able
	      to handle	at least 64 bit	unsigned values.

       SCHILY.dir
	      A	 list  of  filenames  (the content) for	the current directory.
	      The names	are coded in UTF-8.  Each file name is prefixed	 by  a
	      single character that is used as a flag.	Each file name is lim-
	      ited by a	null character.	 The null character is	directly  fol-
	      lowed  by	 he  flag character for	the next file name in case the
	      list is not terminated by	the current file name.	The flag char-
	      acter  must  not	be  a null character.  By default, a ^A	(octal
	      001) is used.  The following flags are defined:

	      \000   This is the list terminator character - the  second  null
		     byte, see below.

	      ^A     The  default  flag	that is	used in	case the dump dir fea-
		     tures have	not been active.

	      Y	     A non directory file that is in the current (incremental)
		     dump.

	      N	     A	non  directory file that is not	in the current (incre-
		     mental) dump.

	      D	     A directory that is in the	current	(incremental) dump.

	      d	     A directory that is  not  in  the	current	 (incremental)
		     dump.

	      The  list	is terminated by two successive	null bytes.  The first
	      is the null byte for the last file name.	The second  null  byte
	      is  at the position where	a flag character would be expected, it
	      acts ad a	list terminator. The length  tag  for  the  SCHILY.dir
	      data includes both null bytes.

	      If  a  dump  mode	has been selected that writes compact complete
	      directory	information to the beginning of	the archive, the  flag
	      character	 may contain values different from ^A.	Star implemen-
	      tations at least up to star-1.5.1	do not use the feature to  tag
	      entries  and use the default entry \001 (^A) for all files.  Tar
	      implementations  that  like  to  read  archives  that  use   the
	      SCHILY.dir  keyword,  shall  not	rely on	values other than \000
	      (^@) or \001 (^A).

	      This keyword is used in dump mode.

       SCHILY.fflags
	      A	textual	version	of the BSD or Linux extended file flags.

	      The following flags are defined by star:

	      arch	     set the archived flag (super-user only).

	      archived	     Alias for arch.

	      nodump	     set the nodump flag (owner	or super-user).

	      opaque	     set the opaque flag (owner	or super-user).

	      sappnd	     set  the  system  append-only  flag   (super-user
			     only).

	      sappend	     Alias for sappnd.

	      schg	     set the system immutable flag (super-user only).

	      schange	     Alias for schg.

	      simmutable     Alias for schg.

	      sunlnk	     set   the	system	undeletable  flag  (super-user
			     only).

	      sunlink	     Alias for sunlnk.

	      uappnd	     set the user append-only flag  (owner  or	super-
			     user).

	      uappend	     Alias for uappnd.

	      uchg	     set  the  user  immutable	flag  (owner or	super-
			     user).

	      uchange	     Alias for uchg.

	      uimmutable     Alias for uchg.

	      uunlnk	     set the user undeletable flag  (owner  or	super-
			     user).

	      uunlink	     Alias for uunlnk.

	      The following flags are only available on	Linux:

	      compress	     Set  the  Linux  ext3 journal data	flag (owner or
			     super-user).

	      journal-data   Set the Linux ext3	journal	data flag  (super-user
			     only).

	      noatime	     Set  the Linux ext3 no access time	flag (owner or
			     super-user).

	      secdel	     Set the Linux ext3	secure deletion	(purge	before
			     delete) flag (owner or super-user).

	      sync	     Set  the  Linux  ext3  sync flag (owner or	super-
			     user).

	      undel	     Set the Linux ext3	"allow unrm"  flag  (owner  or
			     super-user).

       SCHILY.filetype
	      A	 textual  version of the real file type	of the file.  The fol-
	      lowing names are used:

	      unallocated	      An unknown  file	type  that  may	 be  a
				      result  of  a unlink(2) operation.  This
				      should never happen.

	      regular		      A	regular	file.

	      contiguous	      A	contiguous file. On operating  systems
				      or  file systems that don't support this
				      file type, it is handled like a  regular
				      file.

	      symlink		      A	symbolic link to any file type.

	      directory		      A	directory.

	      character	special	      A	character special file.

	      block special	      A	block special file.

	      fifo		      A	named pipe.

	      socket		      A	UNIX domain socket.

	      mpx character special   A	multiplexed character special file.

	      mpx block	special	      A	multiplexed block special file.

	      XENIX nsem	      A	XENIX named semaphore.

	      XENIX nshd	      XENIX shared data.

	      door		      A	Solaris	door.

	      eventcount	      A	UNOS event count.

	      whiteout		      A	BSD whiteout directory entry.

	      sparse		      A	sparse regular file.

	      volheader		      A	volume header.

	      unknown/bad	      Any   other  unknown  file  type.	  This
				      should never happen.

       SCHILY.ino
	      The inode	number from st_ino of  the  file  as  decimal  number.
	      This keyword is used in dump mode.

	      The  value is an unsigned	int.  An implementation	should be able
	      to handle	at least 64 bit	unsigned values.

       SCHILY.nlink
	      The link count of	the file as decimal number.  This  keyword  is
	      used in dump mode.

	      The  value is an unsigned	int.  An implementation	should be able
	      to handle	at least 32 bit	unsigned values.

       SCHILY.offset
	      The offset value for a multi volume continuation	header.	  This
	      keyword  is  used	with multi volume continuation headers.	 Multi
	      volume continuation headers are used to allow to start reading a
	      multi volume archive past	the first volume.

	      SCHILY.offset  specifies	the byte offset	within a file that was
	      split across volumes as a	result of a multi volume media	change
	      operation.

	      The  value is an unsigned	int.  An implementation	should be able
	      to handle	at least 64 bit	unsigned values.

       SCHILY.realsize
	      The real size of the file	as decimal number.   This  keyword  is
	      used  if the real	size of	the file differs from the visible size
	      of the file in the archive.  The real file size differs from the
	      size in the archive if the file type is sparse or	if the file is
	      a	continuation file on a multi  volume  archive.	 In  case  the
	      SCHILY.realsize keyword is needed, it must be past any size key-
	      word in case a size keyword is also present.

	      As sparse	files allocate less space on tape than a regular  file
	      and  as  a continued file	that started on	a previous volume only
	      holds parts of the file, the  SCHILY.realsize  keyword  holds  a
	      bigger number than the size keyword.

	      The  value is an unsigned	int.  An implementation	should be able
	      to handle	at least 64 bit	unsigned values.

       SCHILY.tarfiletype
	      The following additional file types are used in  SCHILY.tarfile-
	      type:

	      hardlink
		     A hard link to any	file type.

	      dumpdir
		     A directory with dump entries

	      multivol continuation
		     A multi volume continuation for any file type.

	      meta   A meta entry (inode meta data only) for any file type.

       SCHILY.xattr.attr
	      A	  POSIX.1-2001	coded  version	of  the	 Linux	extended  file
	      attributes.   Linux  extended  file  attributes  are  name/value
	      pairs.  Every  attribute name results in a SCHILY.xattr.name tag
	      and the value of the extended attribute is used as the value  of
	      the  POSIX.1-2001	 header	 tag.  Note that this way of coding is
	      not portable across platforms.  A	version	for BSD	may be created
	      but  Solaris  includes far more features with extended attribute
	      files than Linux does.

	      A	future version of star will implement a	similar	method as  the
	      tar  program on Solaris currently	uses. When this	implementation
	      is ready,	the SCHILY.xattr.name feature may be removed in	 favor
	      of a truly portable implementation that supports Solaris also.

SCHILY 'G'LOBAL	PAX EXTENSION KEYWORDS
       The following star vendor unique	extensions may only appear in 'g'lobal
       extended	pax headers:

       SCHILY.archtype
	      The textual version of the archive type used.  The textual  val-
	      ues used for SCHILY.archtype are the same	names that are used in
	      the star command line options to set up a	specific archive type.

	      The following values may currently appear	in a  global  extended
	      header:

	      xustar	     'xstar'  format without "tar" signature at	header
			     offset 508.

	      exustar	     'xustar' format variant that always  includes  x-
			     headers and g-headers.

	      A	complete tar implementation must be prepared to	handle all ar-
	      chives names as documented in star(1).

	      In order to allow	archive	type recognition  from	this  keyword,
	      the minimum tape block size must be 2x512	bytes (1024 bytes) and
	      the SCHILY.archtype keyword needs	to be in the first  512	 bytes
	      of  the content of the first 'g'lobal pax	header.	Then the first
	      tape block may be	scanned	to recognize the archive type.

       SCHILY.release
	      The textual version of the star version string and the  platform
	      name  where  this	star has been compiled.	 The same text appears
	      when calling star	-version.

	      Other implementations may	use a version  string  that  does  not
	      start with the text star.

       SCHILY.volhdr.blockoff
	      This  keyword  is	used for multi volume archives.	 It represents
	      the offset within	the whole archive expressed in 512 byte	units.

	      The value	is an unsigned int with	a valid	range  between	1  and
	      infinity.	An implementation should be able to handle at least 64
	      bit unsigned values.

       SCHILY.volhdr.blocksize
	      The tape blocksize expressed in 512 byte	units  that  was  used
	      when writing the archive.

	      The  value  is  an unsigned int with a valid range between 1 and
	      infinity.	An implementation should be able to handle at least 31
	      bit unsigned values.

       SCHILY.volhdr.cwd
	      This  keyword  is	used in	dump mode.  It is only emitted in case
	      the  fs-name=  option  of	 star  was  used  to   overwrite   the
	      SCHILY.volhdr.filesys  value.   If SCHILY.volhdr.cwd is present,
	      it contains the real backup working directory.

	      Overwriting SCHILY.volhdr.filesys	is needed when backups are run
	      on file system snapshots rather than on the real file system.

       SCHILY.volhdr.device
	      This  keyword  is	 used in dump mode.  It	represents the name of
	      the device that holds the	file system data. For disk based  file
	      systems, this is the device name of the mounted device.

	      This  keyword  is	 optional.  It helps to	correctly identify the
	      file system from which this dump has been	made.

       SCHILY.volhdr.dumpdate
	      This keyword is used in dump mode.  It represents	the  time  the
	      current dump did start.

       SCHILY.volhdr.dumplevel
	      This  keyword  is	used in	dump mode.  It represents the level of
	      the current dump.	 Dump levels are  small	 numbers,  the	lowest
	      possible	number	is  0.	Dump level 0 represents	a full backup.
	      Dump level 1 represents a	backup that contains all changes  that
	      did  occur since the last	level 0	dump.  Dump level 2 represents
	      a	backup that contains all changes that did occur	since the last
	      level  1	dump.	Star  does  not	specify	a maximum allowed dump
	      level but	you should try to keep the numbers less	than 100.

	      The value	is an unsigned int with	a valid	range between 0	and at
	      least 100.

       SCHILY.volhdr.dumptype
	      This  keyword  is	 used in dump mode.  If	the dump is a complete
	      dump of a	file system (i.e. no files are	excluded  via  command
	      line),  then the argument	is the text full, else the argument is
	      the text partial.

       SCHILY.volhdr.filesys
	      This keyword is used in dump mode.  It represents	the top	 level
	      directory	 for  the  file	 system	 from which this dump has been
	      made.  If	the dump represents a  dump  that  has	an  associated
	      level, then the this directory needs to be identical to the root
	      directory	of this	file system which is the mount point.

       SCHILY.volhdr.hostname
	      This keyword is used in dump mode.  The value is retrieved  from
	      gethostname(3) or	uname(2).

       SCHILY.volhdr.label
	      The  textual  volume  label.  The	volume label must be identical
	      within a set of multi volume archives.

       SCHILY.volhdr.refdate
	      This keyword is used in dump mode	if  the	 current  dump	is  an
	      incremental  dump	 with a	level >	0.  It represents the time the
	      related dump did start.

       SCHILY.volhdr.reflevel
	      This keyword is used in dump mode	if  the	 current  dump	is  an
	      incremental  dump	 with a	level >	0.  It represents the level of
	      the related dump.	 The related dump is  the  last	 dump  with  a
	      level that is lower that the level of this dump.	If a dump with
	      the level	of the current	dump  -1  exists,  then	 this  is  the
	      related  dump  level.  Otherwise,	 the dump level	is decremented
	      until a valid dump level could be	found in the dump database.

	      The value	is an unsigned int with	a valid	range between 0	and at
	      least 100.

       SCHILY.volhdr.tapesize
	      This  keyword  is	used for multi volume archives and may be used
	      to verify	the volume size	on read	back.  It represents the  tape
	      size  expressed in 512 byte units.  This keyword is set in multi
	      volume mode if the size of the tape was not autodetected but set
	      from a command line option.

	      The  value  is  an unsigned int with a valid range between 1 and
	      infinity.	An implementation should be able to handle at least 64
	      bit unsigned values.

       SCHILY.volhdr.volume
	      This  keyword  is	used for multi volume archives.	 It represents
	      the volume number	within a volume	set.  The number used for  the
	      first volume is 1.

	      The  value  is  an unsigned int with a valid range between 1 and
	      infinity.	An implementation should be able to handle at least 31
	      bit unsigned values.

MULTI VOLUME ARCHIVE HANDLING
       To be documented	in the future.

SEE ALSO
NOTES
BUGS
AUTHOR
Joerg Schilling			   13/11/05			      STAR(4L)

NAME | DESCRIPTION | BASIC TAR HEADER DESCRIPTION | EXTENDED TAR (PAX) HEADER STRUCTURE | EXTENDED TAR (PAX) HEADER FORMAT | EXTENDED TAR (PAX) HEADER KEYWORDS | SCHILY PAX EXTENSION KEYWORDS | SCHILY 'G'LOBAL PAX EXTENSION KEYWORDS | MULTI VOLUME ARCHIVE HANDLING | SEE ALSO | NOTES | BUGS | AUTHOR

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

home | help