Manpage for star.4
Description: A html version of the manpage for star.4
Keywords: star.4

    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

Schily's Home