Provided by: star_1.5final-2ubuntu1_i386 bug

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

       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 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
       question 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
       characters.  All recent implementations only  use  one  space  or  null
       character  at the end of a numerical field to get maximum space for the
       octal number.  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
       character field may hold 56 bits, a base 256 number in a  12  character
       field  may  hold  88 bits. This may extended to 64 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
       implement the same extension.

       While the POSIX standard makes 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 filed contains the number of seconds since Jan 1st 1970 00:00
       UTC as retrived via stat(2) in st_mtime.

       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.

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

       ’\0AREGTYPE
              For  backwards   compatibility   with   pre   POSIX.1-1988   tar
              implementations,  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.

       ’1LNKTYPE
              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
              implementations, 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.

       ’2SYMTYPE
              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.

       ’3CHRTYPE
              A  character  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.

       ’4BLKTYPE
              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.

       ’5DIRTYPE
              A  directory  or  sub  directory.  Old  (pre  POSIX.1-1988)  tar
              implementations 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.

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

       ’7CONTTYPE
              A   contiguous   file.   This  is  a  file  that  gives  special
              performance 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.

       ’gGLOBAL 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
              following  files  in  the archive unless they are overwritten by
              new values.  See EXTENDED TAR (PAX) HEADER FORMAT section below.

       ’xEXTENDED 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
              follows the header is in the pax extended  header  format.   The
              extended  header  records  in  this  header type only affect the
              following file in the archive.  See EXTENDED  TAR  (PAX)  HEADER
              FORMAT 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
              archive 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
              incremental  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  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 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.  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 continuation 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 uses 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
              represents 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 and is meaningless because the size  of
              the sparse hole descriptors does not count.

       ’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=’h’]         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 typeflagg’ 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 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
              currently supports a nanosecond granularity.

       charset
              The name of the character set used to encode  the  data  in  the
              following file(s).  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
              currently 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  323  characters  or  cannot  be
              expressed in 7-Bit ASCII.

       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
              currently 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  323  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.access
              The ACL for a file.

              Since  no  official backup format for POSIX 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 POSIX 1003.1e
              draft standard 17.

              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
              separated  field  containing  the  group identifier (GID) of the
              associated 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
              broken  [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
              created  that  way  can  be  restored  by star or a POSIX.1-2001
              compliant 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
              broken [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 POSIX 1003.1e draft standard 17.

              NFSv4  ACLs as used by NFSv4, NTFS and ZFS.

       Star    currently   only   implements   POSIX draft   ACLs.    If   the
       SCHILY.acl.type keyword is missing, POSIX draft ACLs are asumed.

       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
              numbers. 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
              current device id number is identical to  the  previous  number.
              This  keyword  is  used  in  dump mode.  This keyword is not yet
              implemented.

              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
              directory 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
              limited  by  a  null  character.  The null character is directly
              followed by he flag character for the next file name in case the
              list  is  not  terminated  by  the  current file name.  The flag
              character 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
                     features 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
                     (incremental) 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
              implementations up to star-1.5 do not include this feature.  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.   As
              this  tag has not yet been documented, please look into the star
              source, file fflags.c for more information.

       SCHILY.filetype
              A textual version of the  real  file  type  of  the  file.   The
              following 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.

              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
              keyword in case a size keyword is also present.

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

              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.

SCHILYGLOBAL PAX EXTENSION KEYWORDS
       The following star vendor unique extensions may only appear in ’global
       extended pax headers:

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

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

       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 used  to  contain
              the real backup working directory if the fs-name= option of star
              is  used   to   overwrite   the   SCHILY.volhdr.filesys   value.
              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, 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.  If this keyword is set in
              multi volume mode, the size of the tape is 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