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 con-
     tains 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 mag-
     netic 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

Joerg Schilling       Last change: 05/10/19                     1


Schily's USER COMMANDS                                   STAR(4L)

     /*
      * 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 */

Joerg Schilling       Last change: 05/10/19                     2


Schily's USER COMMANDS                                   STAR(4L)

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

Joerg Schilling       Last change: 05/10/19                     3


Schily's USER COMMANDS                                   STAR(4L)

      * 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;

Joerg Schilling       Last change: 05/10/19                     4


Schily's USER COMMANDS                                   STAR(4L)

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

     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  link-
     name 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  trail-
     ing  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 numeri-
     cal 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 charac-
     ter field is set to flag non octal coding.  If base 256 cod-
     ing  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

Joerg Schilling       Last change: 05/10/19                     5


Schily's USER COMMANDS                                   STAR(4L)

     bits are set).  The rightmost character in a 8 or 12 charac-
     ter  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  initial-
     ized 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.

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

     '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  implementations,  the  size field usually
          contains the size of the file and needs to  be  ignored

Joerg Schilling       Last change: 05/10/19                     6


Schily's USER COMMANDS                                   STAR(4L)

          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 link-
          name 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 dev-
          minor  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.

     '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  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  extrac-
          tion.  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 extraction.  No file data may follow  the
          header.

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

     '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

Joerg Schilling       Last change: 05/10/19                     7


Schily's USER COMMANDS                                   STAR(4L)

          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.

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

Joerg Schilling       Last change: 05/10/19                     8


Schily's USER COMMANDS                                   STAR(4L)

     '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 descrip-
          tors 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.

Joerg Schilling       Last change: 05/10/19                     9


Schily's USER COMMANDS                                   STAR(4L)

          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
     typeflag 'g' or 'x' contains one or more records in the fol-
     lowing 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

Joerg Schilling       Last change: 05/10/19                    10


Schily's USER COMMANDS                                   STAR(4L)

          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 can-
          not 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  argu-
          ment  is  a  decimal number.  This field is used if the
          uid ID  of  a  file  is  greater  than  2097151  (octal
          7777777).

Joerg Schilling       Last change: 05/10/19                    11


Schily's USER COMMANDS                                   STAR(4L)

     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  con-
          trol  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

Joerg Schilling       Last change: 05/10/19                    12


Schily's USER COMMANDS                                   STAR(4L)

          star  or  a POSIX.1-2001 compliant pax.  Note that pro-
          grams 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.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  key-
          word 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  charac-
          ter  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.

Joerg Schilling       Last change: 05/10/19                    13


Schily's USER COMMANDS                                   STAR(4L)

     SCHILY.devminor
          The device minor number of the file if it is a  charac-
          ter  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  (incremen-
               tal) dump.

Joerg Schilling       Last change: 05/10/19                    14


Schily's USER COMMANDS                                   STAR(4L)

          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  char-
          acter  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  dif-
          ferent 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.

Joerg Schilling       Last change: 05/10/19                    15


Schily's USER COMMANDS                                   STAR(4L)

          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 con-
          tinuation 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

Joerg Schilling       Last change: 05/10/19                    16


Schily's USER COMMANDS                                   STAR(4L)

          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  continua-
          tion  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 port-
          able 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

Joerg Schilling       Last change: 05/10/19                    17


Schily's USER COMMANDS                                   STAR(4L)

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

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

     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  iden-
          tify  the  file  system  from  which this dump has been
          made.

Joerg Schilling       Last change: 05/10/19                    18


Schily's USER COMMANDS                                   STAR(4L)

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

Joerg Schilling       Last change: 05/10/19                    19


Schily's USER COMMANDS                                   STAR(4L)

          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


Joerg Schilling       Last change: 05/10/19                    20


Man(1) output converted with man2html


FhG FhG FOKUS BerliOS Schily Schily's Home VED powered