1STAR(4L)                    Schily´s USER COMMANDS                    STAR(4L)
2
3
4

NAME

6       star - tape archive file format
7

DESCRIPTION

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

BASIC TAR HEADER DESCRIPTION

19       Physically, a POSIX.1-1988 tar archive consists of a  series  of  fixed
20       sized  blocks of TBLOCK (512) characters.  It contains a series of file
21       entries terminated by a logical end-of-archive marker,  which  consists
22       of two blocks of 512 bytes of binary zeroes.  Each file entry is repre‐
23       sented by a header block that describes the file  followed  by  one  or
24       more  blocks  with  the content of the file. The length of each file is
25       rounded up to a multiple of 512 bytes.
26
27       A number of TBLOCK sizes blocks are grouped together to a  tape  record
28       for  physical I/O operations. Each record of n blocks is written with a
29       single write(2) operation.  On magnetic tapes, this results in a single
30       tape record in case the tape drive is in variable length record mode.
31
32       The header block is defined in star.h as follows:
33       /*
34        * POSIX.1-1988 field size values and magic.
35        */
36       #define   TBLOCK         512
37       #define   NAMSIZ         100
38       #define   PFXSIZ         155
39
40       #define   TMODLEN        8
41       #define   TUIDLEN        8
42       #define   TGIDLEN        8
43       #define   TSIZLEN        12
44       #define   TMTMLEN        12
45       #define   TCKSLEN        8
46
47       #define   TMAGIC         "ustar"   /* ustar magic 6 chars + '\0' */
48       #define   TMAGLEN        6         /* "ustar" including '\0' */
49       #define   TVERSION       "00"
50       #define   TVERSLEN       2
51       #define   TUNMLEN        32
52       #define   TGNMLEN        32
53       #define   TDEVLEN        8
54
55       /*
56        * POSIX.1-1988 typeflag values
57        */
58       #define   REGTYPE        '0'  /* Regular File          */
59       #define   AREGTYPE       '\0' /* Regular File (outdated) */
60       #define   LNKTYPE        '1'  /* Hard Link             */
61       #define   SYMTYPE        '2'  /* Symbolic Link         */
62       #define   CHRTYPE        '3'  /* Character Special     */
63       #define   BLKTYPE        '4'  /* Block Special         */
64       #define   DIRTYPE        '5'  /* Directory             */
65       #define   FIFOTYPE       '6'  /* FIFO (named pipe)     */
66       #define   CONTTYPE       '7'  /* Contiguous File       */
67
68       /*
69        * POSIX.1-2001 typeflag extensions.
70        * POSIX.1-2001 calls the extended USTAR format PAX although it is
71        * definitely derived from and based on USTAR. The reason may be that
72        * POSIX.1-2001 calls the tar program outdated and lists the
73        * pax program as the successor.
74        */
75       #define   LF_GHDR        'g'  /* POSIX.1-2001 global extended header */
76       #define   LF_XHDR        'x'  /* POSIX.1-2001 extended header */
77
78       See  section  EXTENDED  TAR  (PAX) HEADER KEYWORDS for more information
79       about the structure of a POSIX.1-2001 header.
80
81       /*
82        * star/gnu/Sun tar extensions:
83        *
84        * Note that the standards committee allows only capital A through
85        * capital Z for user-defined expansion.  This means that defining
86        * something as, say '8' is a *bad* idea.
87        */
88
89       #define   LF_ACL         'A'  /* Solaris Access Control List     */
90       #define   LF_DUMPDIR     'D'  /* GNU dump dir                    */
91       #define   LF_EXTATTR     'E'  /* Solaris Extended Attribute File */
92       #define   LF_META        'I'  /* Inode (metadata only) no file content */
93       #define   LF_LONGLINK    'K'  /* NEXT file has a long linkname   */
94       #define   LF_LONGNAME    'L'  /* NEXT file has a long name       */
95       #define   LF_MULTIVOL    'M'  /* Continuation file rest to be skipped */
96       #define   LF_NAMES       'N'  /* OLD GNU for names > 100 characters   */
97       #define   LF_SPARSE      'S'  /* This is for sparse files        */
98       #define   LF_VOLHDR      'V'  /* tape/volume header Ignore on extraction */
99       #define   LF_VU_XHDR     'X'  /* POSIX.1-2001 xtended (Sun VU version) */
100
101       /*
102        * Definitions for the t_mode field
103        */
104       #define   TSUID     04000     /* Set UID on execution  */
105       #define   TSGID     02000     /* Set GID on execution  */
106       #define   TSVTX     01000     /* On directories, restricted deletion flag */
107       #define   TUREAD    00400     /* Read by owner         */
108       #define   TUWRITE   00200     /* Write by owner special */
109       #define   TUEXEC    00100     /* Execute/search by owner */
110       #define   TGREAD    00040     /* Read by group         */
111       #define   TGWRITE   00020     /* Write by group        */
112       #define   TGEXEC    00010     /* Execute/search by group */
113       #define   TOREAD    00004     /* Read by other         */
114       #define   TOWRITE   00002     /* Write by other        */
115       #define   TOEXEC    00001     /* Execute/search by other */
116
117       #define   TALLMODES 07777     /* The low 12 bits       */
118
119       /*
120        * This is the ustar (Posix 1003.1) header.
121        */
122       struct header {
123            char t_name[NAMSIZ];     /*   0 Filename               */
124            char t_mode[8];          /* 100 Permissions            */
125            char t_uid[8];           /* 108 Numerical User ID      */
126            char t_gid[8];           /* 116 Numerical Group ID     */
127            char t_size[12];         /* 124 Filesize               */
128            char t_mtime[12];        /* 136 st_mtime               */
129            char t_chksum[8];        /* 148 Checksum               */
130            char t_typeflag;         /* 156 Typ of File            */
131            char t_linkname[NAMSIZ]; /* 157 Target of Links        */
132            char t_magic[TMAGLEN];   /* 257 "ustar"                */
133            char t_version[TVERSLEN]; /* 263 Version fixed to 00   */
134            char t_uname[TUNMLEN];   /* 265 User Name              */
135            char t_gname[TGNMLEN];   /* 297 Group Name             */
136            char t_devmajor[8];      /* 329 Major for devices      */
137            char t_devminor[8];      /* 337 Minor for devices      */
138            char t_prefix[PFXSIZ];   /* 345 Prefix for t_name      */
139                                     /* 500 End                    */
140            char t_mfill[12];        /* 500 Filler up to 512       */
141       };
142
143       /*
144        * star header specific definitions
145        */
146       #define   STMAGIC        "tar"     /* star magic */
147       #define   STMAGLEN       4         /* "tar" including '\0' */
148
149       /*
150        * This is the new (post Posix 1003.1-1988) xstar header
151        * defined in 1994.
152        *
153        * t_prefix[130]    is guaranteed to be ' ' to prevent ustar
154        *                  compliant implementations from failing.
155        * t_mfill & t_xmagic need to be zero for a 100% ustar compliant
156        *                  implementation, so setting t_xmagic to
157        *                  "tar" should be avoided in the future.
158        *
159        * A different method to recognize this format is to verify that
160        * t_prefix[130]              is equal to ' ' and
161        * t_atime[0]/t_ctime[0]      is an octal number and
162        * t_atime[11]                is equal to ' ' and
163        * t_ctime[11]                is equal to ' '.
164        *
165        * Note that t_atime[11]/t_ctime[11] may be changed in future.
166        */
167       struct xstar_header {
168            char t_name[NAMSIZ];     /*   0 Filename               */
169            char t_mode[8];          /* 100 Permissions            */
170            char t_uid[8];           /* 108 Numerical User ID      */
171            char t_gid[8];           /* 116 Numerical Group ID     */
172            char t_size[12];         /* 124 Filesize               */
173            char t_mtime[12];        /* 136 st_mtime               */
174            char t_chksum[8];        /* 148 Checksum               */
175            char t_typeflag;         /* 156 Typ of File            */
176            char t_linkname[NAMSIZ]; /* 157 Target of Links        */
177            char t_magic[TMAGLEN];   /* 257 "ustar"                */
178            char t_version[TVERSLEN]; /* 263 Version fixed to 00   */
179            char t_uname[TUNMLEN];   /* 265 User Name              */
180            char t_gname[TGNMLEN];   /* 297 Group Name             */
181            char t_devmajor[8];      /* 329 Major for devices      */
182            char t_devminor[8];      /* 337 Minor for devices      */
183            char t_prefix[131];      /* 345 Prefix for t_name      */
184            char t_atime[12];        /* 476 st_atime               */
185            char t_ctime[12];        /* 488 st_ctime               */
186            char t_mfill[8];         /* 500 Filler up to star magic     */
187            char t_xmagic[4];        /* 508 "tar"                  */
188       };
189
190       struct sparse {
191            char t_offset[12];
192            char t_numbytes[12];
193       };
194
195       #define   SPARSE_EXT_HDR  21
196
197       struct xstar_ext_header {
198            struct sparse t_sp[21];
199            char t_isextended;
200       };
201
202       typedef union hblock {
203            char dummy[TBLOCK];
204            long ldummy[TBLOCK/sizeof (long)]; /* force long alignment */
205            struct header            dbuf;
206            struct xstar_header      xstar_dbuf;
207            struct xstar_ext_header  xstar_ext_dbuf;
208       } TCB;
209
210       For maximum portability, all  fields  that  contain  character  strings
211       should be limited to use the low 7 bits of a character.
212
213       The  name,  linkname  and  prefix  field contain character strings. The
214       strings are null terminated except when they use the full space of  100
215       characters  for  the  name  or linkname field or 155 characters for the
216       prefix field.
217
218       If the prefix does not start with a null  character,  then  prefix  and
219       name  need  to be concatenated by using the prefix, followed by a slash
220       character followed by the name field.  If a null character  appears  in
221       name  or  prefix before the maximum size is reached, the field in ques‐
222       tion is terminated.  This way file names up to 256  characters  may  be
223       archived.   The prefix is not used together with the linkname field, so
224       the maximum length of a link name is 100 characters.
225
226       The fields magic, uname and gname  contain  null  terminated  character
227       strings.
228
229       The  version field contains the string "00" without a trailing zero. It
230       cannot be set to different values as POSIX.1-1988 did not specify a way
231       to handle different version strings.
232
233       The typeflag field contains a single character.
234
235       All  numeric  fields  contain  size-1 leading zero-filled numbers using
236       octal digits.  They are followed by one or more space or  null  charac‐
237       ters.   All recent implementations only use one space or null character
238       at the end of a numerical field to get maximum space for the octal num‐
239       ber.  Star always uses a space character as terminator.  Numeric fields
240       with 8 characters may hold up to 7 octal digits (7777777) which results
241       is  a  maximum value of 2097151.  Numeric fields with 12 characters may
242       hold up to 11 octal digits (77777777777) which  results  is  a  maximum
243       value of 8589934591.
244
245       Star implements a vendor specific (and thus non-POSIX) extension to put
246       bigger numbers into the numeric fields. This is done by  using  a  base
247       256  coding.   The  top bit of the first character in the appropriate 8
248       character or 12 character field is set to flag non  octal  coding.   If
249       base  256  coding  is in use, then all remaining characters are used to
250       code the number. This results in 7  base  256  digits  in  8  character
251       fields  and in 11 base 256 digits in 12 character fields.  All base 256
252       numbers are two's complement numbers. A base 256 number in a 8  charac‐
253       ter  field  may hold 56 bits, a base 256 number in a 12 character field
254       may hold 88 bits. This may be extended  to  63  bits  for  8  character
255       fields  and  to  95 bits for 12 character fields. For a negative number
256       the first character currently is set to a value of 255 (all 8 bits  are
257       set).   The  rightmost  character in a 8 or 12 character field contains
258       the least significant base 256 number.  Recent GNU tar versions  imple‐
259       ment the same extension.
260
261       While  the  POSIX  standard makes it obvious that the fields mode, uid,
262       gid,  size, chksum, devmajor and devminor should be treated as unsigned
263       numbers, there is no such definition for the time field.
264
265       The  mode field contains 12 bits holding permissions, see above for the
266       definitions for each of the permission bits.
267
268       The uid and gid fields contain the numerical user id of the file.
269
270       The size field contains the size of the file in characters.  If the tar
271       header  is  followed by file data, then the amount of data that follows
272       is computed by (size + 511) / 512.
273
274       The mtime field contains the number of seconds since Jan 1st 1970 00:00
275       UTC as retrived via stat(2) in st_mtime.  If the mtime fiels is assumed
276       to be a signed 33 bit number, the latest representable time is 2106 Feb
277       7 06:28:15 GMT.
278
279       The  chksum  field  contains  a  simple  checksum over all bytes of the
280       header.  To compute the value, all characters in the header are treated
281       as unsigned integers and the characters in the chksum field are treated
282       as if they were all spaces. When the computation starts,  the  checksum
283       value is initialized to 0.
284
285       The  typeflag field specifies the type of the file that is archived. If
286       a specific tar implementation does not include support for  a  specific
287       typeflag value, this implementation will extract the unknown file types
288       as if they were plain files. For this reason, the size  field  for  any
289       file  type  except  directories,  hard links, symbolic links, character
290       special, block specials and FIFOs must  always  follow  the  rules  for
291       plain files.
292
293       '0' REGTYPE
294              A  regular  file.  If the size field is non zero, then file data
295              follows the header.
296
297       '\0' AREGTYPE
298              For backwards compatibility with pre POSIX.1-1988 tar  implemen‐
299              tations,  a nul character is also recognized as marker for plain
300              files.  It is not generated by recent tar  implementations.   If
301              the size field is non zero, then file data follows the header.
302
303       '1' LNKTYPE
304              The  file  is a hard link to another file.  The name of the file
305              that the file is linked to  is  in  the  linkname  part  of  the
306              header.   For tar archives written by pre POSIX.1-1988 implemen‐
307              tations, the size field usually contains the size  of  the  file
308              and  needs to be ignored as no data may follow this header type.
309              For POSIX.1-1988 compliant archives, the size field needs to  be
310              0.   For  POSIX.1-2001 compliant archives, the size field may be
311              non zero, indicating that file data is included in the archive.
312
313       '2' SYMTYPE
314              The file is a symbolic link to another file.  The  name  of  the
315              file  that  the file is linked to is in the linkname part of the
316              header.  The size field needs to be 0.  No file data may  follow
317              the header.
318
319       '3' CHRTYPE
320              A character special file.  The fields devmajor and devminor con‐
321              tain information that defines the file.  The meaning of the size
322              field  is  unspecified  by the POSIX standard.  No file data may
323              follow the header.
324
325       '4' BLKTYPE
326              A block special file.  The fields devmajor and devminor  contain
327              information  that  defines  the  file.   The meaning of the size
328              field is unspecified by the POSIX standard.  No  file  data  may
329              follow the header.
330
331       '5' DIRTYPE
332              A  directory or sub directory. Old (pre POSIX.1-1988) tar imple‐
333              mentations did use the same typeflag value as  for  plain  files
334              and  added  a  slash to the name.  If the size field is non zero
335              then it indicates the maximum size in characters the system  may
336              allocate  for  this  directory. If the size field is 0, then the
337              system shall not limit the size of the directory.  On  operating
338              systems  where  the  disk  allocation is not done on a directory
339              base, the size field is ignored on extraction.  No file data may
340              follow the header.
341
342       '6' FIFOTYPE
343              A  named  pipe.  The meaning of the size field is unspecified by
344              the POSIX standard.  The size field must be ignored  on  extrac‐
345              tion.  No file data may follow the header.
346
347       '7' CONTTYPE
348              A  contiguous  file.   This is a file that gives special perfor‐
349              mance attributes.  Operating systems  that  don't  support  this
350              file  type  extract  this file type as plain files.  If the size
351              field is non zero, then file data follows the header.
352
353       'g' GLOBAL POSIX.1-2001 HEADER
354              With POSIX.1-2001 pax  archives,  this  type  defines  a  global
355              extended  header.   The  size is always non zero and denotes the
356              sum of the length fields in the extended header data.  The  data
357              that  follows  the  header is in the pax extended header format.
358              The extended header records in this header type affect all  fol‐
359              lowing  files  in the archive unless they are overwritten by new
360              values.  See EXTENDED TAR (PAX) HEADER FORMAT section below.
361
362       'x' EXTENDED POSIX.1-2001 HEADER
363              With POSIX.1-2001 pax archives, this type  defines  an  extended
364              header.   The size is always non zero and denotes the sum of the
365              length fields in the extended header data.  The data  that  fol‐
366              lows  the  header  is  in  the  pax extended header format.  The
367              extended header records in this header type only affect the fol‐
368              lowing  file in the archive.  See EXTENDED TAR (PAX) HEADER FOR‐
369              MAT section below.
370
371       'A' - 'Z'
372              Reserved for vendor specific implementations.
373
374       'A'    A Solaris ACL entry as used by the tar implementation from  Sun.
375              The  size  is always non zero and denotes the length of the data
376              that follows the header.  Star currently is not able  to  handle
377              this header type.
378
379       'D'    A  GNU  dump directory.  This header type is not created by star
380              and handled like a directory during an extract operation, so the
381              content  is  ignored by star.  The size field denotes the length
382              of the data that follows the header.
383
384       'E'    A Solaris Extended Attribute File.  The size field  denotes  the
385              length  of  the data that follows the header.  Star currently is
386              not able to handle this header type.
387
388       'I'    A inode metadata entry.  This header type is used by star to ar‐
389              chive  inode  meta  data  only.  To archive more inode meta data
390              than possible with a POSIX-1.1988 tar header, a header with type
391              'I' is usually preceded by a 'x' header.  It is used with incre‐
392              mental backups.  The size field holds the length  of  the  file.
393              No file data follows this header.
394
395       'K'    A  long  link name.  Star is able to read and write this type of
396              header with the star, xstar and gnutar formats.  With the xustar
397              and exustar formats, star prefers to store long link names using
398              the POSIX.1-2001 method.   The  size  is  always  non  zero  and
399              denotes  the length of the long link name including the trailing
400              null byte. The link name is in the data that follows the header.
401
402       'L'    A long file name.  Star is able to read and write this  type  of
403              header with the star, xstar and gnutar formats.  With the xustar
404              and exustar formats, star prefers to store long file names using
405              the  POSIX.1-2001  method.   The  size  is  always  non zero and
406              denotes the length of the long file name including the  trailing
407              null byte. The file name is in the data that follows the header.
408
409       'M'    A  multi  volume continuation entry.  It is used by star to tell
410              the extraction program via the size field when the next  regular
411              archive  header  will  follow.   This allows to start extracting
412              multi volume archives with a volume number greater than one.  It
413              is  used by GNU tar to verify multi volume continuation volumes.
414              Other fields in the GNU multi volume continuation header  are  a
415              result  of  a  GNU  tar  miss conception and cannot be used in a
416              reliable tar implementation.  If the size field is non zero  the
417              data  following the header is skipped by star if the volume that
418              starts with it is mounted as the first volume.  This  header  is
419              ignored if the volume that starts with it is mounted as continu‐
420              ation volume.
421
422       'N'    An outdated linktype used by old GNU tar versions to store  long
423              file names.  This type is unsupported by star.
424
425       'S'    A sparse file.  This header type is used by star and GNU tar.  A
426              sparse header is used instead of a plain file header to denote a
427              sparse  file  that follows. Directly after the header, a list of
428              sparse hole descriptors follows followed by the  compacted  file
429              data.   With star formats, the size field holds a size that rep‐
430              resents the sum of the sparse hole descriptors plus the size  of
431              the  compacted  file data. This allows other tar implementations
432              to correctly skip to the next tar header.  With GNU tar, up to 4
433              sparse  hole descriptors fit into the sparse header.  Additional
434              hole descriptors are not needed if the  file  has  less  than  4
435              holes.   With  GNU tar, the size field breaks general tar header
436              rules in case more than 4 sparse hole descriptors are  used  and
437              is  meaningless  because  the size of the additional sparse hole
438              descriptors used by GNU tar does not count and cannot be  deter‐
439              mined before parsing all sparse hole descriptors.
440
441       'V'    A  volume  header.  The name field is is used to hold the volume
442              name.  Star uses the atime field to hold the  volume  number  in
443              case there is no POSIX.1-2001 extended header.  This header type
444              is used by star and GNU tar.  If the size field is non zero  the
445              data following the header is skipped by star.
446
447       'X'    A  vendor  unique  variant  of  the POSIX.1-2001 extended header
448              type.  It has been implemented by  Sun  many  years  before  the
449              POSIX.1-2001  standard has been approved.  See also the typeflag
450              'x' header type.  Star is able to read and write  this  type  of
451              header.
452

EXTENDED TAR (PAX) HEADER STRUCTURE

454       Block type                            Description
455
456       Ustar Header [typeflag='g']      Global Extended Header
457       Global Extended Data
458       Ustar Header [typeflag='x']         Extended Header
459       Extended Data
460       Ustar header [typeflag='0']    File with Extended Header
461       Data for File #1
462
463       Ustar header [typeflag='0']   File without Extended Header
464       Data for File #2
465       Block of binary zeroes              First EOF Block
466       Block of binary zeroes              Second EOF Block
467
468

EXTENDED TAR (PAX) HEADER FORMAT

470       The  data  block that follows a tar archive header with typeflag 'g' or
471       'x' contains one or more records in the following format:
472
473              "%d %s=%s\n", <length>, <keyword>, <value>
474
475       Each record starts with a a decimal length field. The  length  includes
476       the  total  size  of a record including the length field itself and the
477       trailing new line.
478
479       The keyword may not include an equal sign.  All keywords beginning with
480       lower  case letters and digits are reserved for future use by the POSIX
481       standard.
482
483       If the value field is of zero length, it deletes any  header  field  of
484       the same name that is in effect from the same extended header or from a
485       previous global header.
486
487       Null characters do not delimit any value. The data used  for  value  is
488       only limited by its implicit length.
489

EXTENDED TAR (PAX) HEADER KEYWORDS

491       POSIX.1-2001  extended  pax  header  keywords. All numerical values are
492       represented as decimal strings.  All texts  are  represented  as  7-bit
493       ascii or UTF-8:
494
495       atime  The  time  from  st_atime  in sub second granularity.  Star cur‐
496              rently supports a nanosecond granularity.
497
498       charset
499              The name of the character set used to encode  the  data  in  the
500              following file(s).
501
502              The following values are supported for charset:
503
504              ISO-IR 646 1990          SO/IEC 646:1990
505
506              ISO-IR 8859 1 1998       ISO/IEC 8859-1:1998
507
508              ISO-IR 8859 2 1998       ISO/IEC 8859-2:1998
509
510              ISO-IR 8859 3 1998       ISO/IEC 8859-3:1998
511
512              ISO-IR 8859 4 1998       ISO/IEC 8859-4:1998
513
514              ISO-IR 8859 5 1998       ISO/IEC 8859-5:1998
515
516              ISO-IR 8859 6 1998       ISO/IEC 8859-6:1998
517
518              ISO-IR 8859 7 1998       ISO/IEC 8859-7:1998
519
520              ISO-IR 8859 8 1998       ISO/IEC 8859-8:1998
521
522              ISO-IR 8859 9 1998       ISO/IEC 8859-9:1998
523
524              ISO-IR 8859 10 1998      ISO/IEC 8859-10:1998
525
526              ISO-IR 8859 11 1998      ISO/IEC 8859-11:1998
527
528              ISO-IR 8859 12 1998      ISO/IEC 8859-12:1998
529
530              ISO-IR 8859 13 1998      ISO/IEC 8859-13:1998
531
532              ISO-IR 8859 14 1998      ISO/IEC 8859-14:1998
533
534              ISO-IR 8859 15 1998      ISO/IEC 8859-15:1998
535
536              ISO-IR 10646 2000        ISO/IEC 10646:2000
537
538              ISO-IR 10646 2000 UTF-8  ISO/IEC 10646, UTF-8 encoding
539
540              BINARY                   None
541
542              This keyword is currently ignored by star.
543
544       comment
545              Any  number  of  characters  that  should be treated as comment.
546              Star ignores the comment as documented by the POSIX standard.
547
548       ctime  The time from st_ctime in sub  second  granularity.   Star  cur‐
549              rently supports a nanosecond granularity.
550
551       gid    The group ID of the group that owns the file.  The argument is a
552              decimal number.  This field is used if the group ID of a file is
553              greater than 2097151 (octal 7777777).
554
555       gname  The  group  name  of the following file(s) coded in UTF-8 if the
556              group name  does  not  fit  into  32  characters  or  cannot  be
557              expressed in 7-Bit ASCII.
558
559       hdrcharset
560              The  name  of  the character set used to encode the data for the
561              gname, linkpath, path  and  uname  fields  in  the  POSIX.1-2001
562              extended header records.
563
564              The following values are supported for hdrcharset:
565
566              ISO-IR 10646 2000 UTF-8  ISO/IEC 10646, UTF-8 encoding
567
568              BINARY                   None
569
570              This keyword is currently ignored by star.
571
572       linkpath
573              The name of the linkpath coded in UTF-8 if it is longer than 100
574              characters or cannot be expressed in 7-Bit ASCII.
575
576       mtime  The time from st_mtime in sub  second  granularity.   Star  cur‐
577              rently supports a nanosecond granularity.
578
579       path   The  name of the linkpath coded in UTF-8 if it does not fit into
580              100 characters + 155 characters prefix or cannot be expressed in
581              7-Bit ASCII.
582
583       realtime.any
584              The  keywords  prefixed  by  realtime.   are reserved for future
585              standardization.
586
587       security.any
588              The keywords prefixed by  security.   are  reserved  for  future
589              standardization.
590
591       size   The  size  of  the  file  as  decimal number if the file size is
592              greater than 8589934591 (octal 77777777777).  The  size  keyword
593              may  not  refer to the real file size but is related to the size
594              if the file in the archive.  See also SCHILY.realsize  for  more
595              information.
596
597       uid    The  uid  ID of the group that owns the file.  The argument is a
598              decimal number.  This field is used if the uid ID of a  file  is
599              greater than 2097151 (octal 7777777).
600
601       uname  The  user  name  of  the following file(s) coded in UTF-8 if the
602              user name does not fit into 32 characters or cannot be expressed
603              in 7-Bit ASCII.
604
605       VENDOR.keyword
606              Any keyword that starts with a vendor name in capital letters is
607              reserved for vendor specific extensions by the  standard.   Star
608              uses  a  lot  of  these vendor specific extension. See below for
609              more informations.
610

SCHILY PAX EXTENSION KEYWORDS

612       Star uses own vendor specific extensions. The  SCHILY  vendor  specific
613       extended pax header keywords are:
614
615       SCHILY.acl.access
616              The ACL for a file.
617
618              Since  no  official backup format for POSIX access control lists
619              has been  defined,  star  uses  the  vendor  defined  attributes
620              SCHILY.acl.access and SCHILY.acl.default for storing the ACL and
621              Default ACL of a file, respectively.  The access  control  lists
622              are  stored  in  the short text form as defined in POSIX 1003.1e
623              draft standard 17.
624
625              Note that the POSIX 1003.1e draft has been withdrawn in 1997 but
626              some operating systems still support it with some filesystems.
627
628              To  each  named  user  ACL  entry a fourth colon separated field
629              field containing the user identifier  (UID)  of  the  associated
630              user is appended.  To each named group entry a fourth colon sep‐
631              arated field containing the group identifier (GID) of the  asso‐
632              ciated  group  is  appended.   (POSIX  1003.1e draft standard 17
633              allows to add fields to ACL entries.)
634
635              This is an example of the format used for  SCHILY.acl.access  (a
636              space  has been inserted after the equal sign and lines are bro‐
637              ken [marked with '\' ] for  readability,  additional  fields  in
638              bold):
639
640              SCHILY.acl.access= user::rwx,user:lisa:r-x:502, \
641                                 group::r-x,group:toolies:rwx:102, \
642                                 mask::rwx,other::r--x
643
644              The  numerical  user  and  group  identifiers are essential when
645              restoring a system completely from a backup,  as  initially  the
646              name-to-identifier  mappings may not be available, and then file
647              ownership restoration would not work.
648
649              As the archive format that is used for backing up access control
650              lists  is  compatible with the pax archive format, archives cre‐
651              ated that way can be restored by star or a POSIX.1-2001  compli‐
652              ant pax.  Note that programs other than star will ignore the ACL
653              information.
654
655       SCHILY.acl.default
656              The default ACL for  a  file.  See  SCHILY.acl.access  for  more
657              information.
658
659              This  is an example of the format used for SCHILY.acl.default (a
660              space has been inserted after the equal sign and lines are  bro‐
661              ken  [marked  with  '\'  ] for readability, additional fields in
662              bold):
663
664              SCHILY.acl.default= user::rwx,user:lisa:r-x:502, \
665                                  group::r-x,mask::r-x,other::r-x
666
667       SCHILY.acl.type
668              The ACL type used for coding access control lists.
669
670              The following ACL types are possible:
671
672              POSIX draft
673                     ACLs as defined in POSIX 1003.1e draft standard 17.
674
675              NFSv4  ACLs as used by NFSv4, NTFS and ZFS.
676
677       Star   currently   only   implements   POSIX draft   ACLs.    If    the
678       SCHILY.acl.type keyword is missing, POSIX draft ACLs are asumed.
679
680       SCHILY.ddev
681              The  device  ids for names used is the SCHILY.dir dump directory
682              list from st_dev of the file as decimal number.  The SCHILY.ddev
683              keyword  is followed by a space separated list of device id num‐
684              bers. Each corresponds exactly to a name in the  list  found  in
685              SCHILY.dir.  If a specific device id number is repeated, a comma
686              (,) without a following space may be use to denote that the cur‐
687              rent device id number is identical to the previous number.  This
688              keyword is used in dump mode.  This keyword is  not  yet  imple‐
689              mented.
690
691              The  value is a signed int.  An implementation should be able to
692              handle at least 64 bit values.  Note that the  value  is  signed
693              because  POSIX  does not specify more than the type should be an
694              int.
695
696       SCHILY.dev
697              The device id from st_dev of the file as decimal  number.   This
698              keyword is used in dump mode.
699
700              The  value is a signed int.  An implementation should be able to
701              handle at least 64 bit values.  Note that the  value  is  signed
702              because  POSIX  does not specify more than the type should be an
703              int.
704
705       SCHILY.devmajor
706              The device major number of the file if  it  is  a  character  or
707              block  special  file.   The  argument is a decimal number.  This
708              field is used if the device major of the file  is  greater  than
709              2097151 (octal 7777777).
710
711              The  value is a signed int.  An implementation should be able to
712              handle at least 64 bit values.  Note that the  value  is  signed
713              because  POSIX  does not specify more than the type should be an
714              int.
715
716       SCHILY.devminor
717              The device minor number of the file if  it  is  a  character  or
718              block  special  file.   The  argument is a decimal number.  This
719              field is used if the device minor of the file  is  greater  than
720              2097151 (octal 7777777).
721
722              The  value is a signed int.  An implementation should be able to
723              handle at least 64 bit values.  Note that the  value  is  signed
724              because  POSIX  does not specify more than the type should be an
725              int.
726
727       SCHILY.dino
728              The inode numbers for names used is the SCHILY.dir  dump  direc‐
729              tory  list  from  st_ino  of  the  file  as decimal number.  The
730              SCHILY.dino keyword is followed by a  space  separated  list  of
731              inode  numbers.  Each  corresponds exactly to a name in the list
732              found in SCHILY.dir.  This keyword is used in dump mode.
733
734              The values are unsigned int.  An implementation should  be  able
735              to handle at least 64 bit unsigned values.
736
737       SCHILY.dir
738              A  list  of  filenames  (the content) for the current directory.
739              The names are coded in UTF-8.  Each file name is prefixed  by  a
740              single character that is used as a flag.  Each file name is lim‐
741              ited by a null character.  The null character is  directly  fol‐
742              lowed  by  he  flag character for the next file name in case the
743              list is not terminated by the current file name.  The flag char‐
744              acter  must  not  be  a null character.  By default, a ^A (octal
745              001) is used.  The following flags are defined:
746
747              \000   This is the list terminator character - the  second  null
748                     byte, see below.
749
750              ^A     The  default  flag that is used in case the dump dir fea‐
751                     tures have not been active.
752
753              Y      A non directory file that is in the current (incremental)
754                     dump.
755
756              N      A  non  directory file that is not in the current (incre‐
757                     mental) dump.
758
759              D      A directory that is in the current (incremental) dump.
760
761              d      A directory that is  not  in  the  current  (incremental)
762                     dump.
763
764              The  list is terminated by two successive null bytes.  The first
765              is the null byte for the last file name.  The second  null  byte
766              is  at the position where a flag character would be expected, it
767              acts ad a list terminator. The length  tag  for  the  SCHILY.dir
768              data includes both null bytes.
769
770              If  a  dump  mode has been selected that writes compact complete
771              directory information to the beginning of the archive, the  flag
772              character  may contain values different from ^A.  Star implemen‐
773              tations at least up to star-1.5.1 do not use the feature to  tag
774              entries  and use the default entry \001 (^A) for all files.  Tar
775              implementations  that  like  to  read  archives  that  use   the
776              SCHILY.dir  keyword,  shall  not  rely on values other than \000
777              (^@) or \001 (^A).
778
779              This keyword is used in dump mode.
780
781       SCHILY.fflags
782              A textual version of the BSD or Linux extended file flags.
783
784              The following flags are defined by star:
785
786              arch           set the archived flag (super-user only).
787
788              archived       Alias for arch.
789
790              nodump         set the nodump flag (owner or super-user).
791
792              opaque         set the opaque flag (owner or super-user).
793
794              sappnd         set  the  system  append-only  flag   (super-user
795                             only).
796
797              sappend        Alias for sappnd.
798
799              schg           set the system immutable flag (super-user only).
800
801              schange        Alias for schg.
802
803              simmutable     Alias for schg.
804
805              sunlnk         set   the  system  undeletable  flag  (super-user
806                             only).
807
808              sunlink        Alias for sunlnk.
809
810              uappnd         set the user append-only flag  (owner  or  super-
811                             user).
812
813              uappend        Alias for uappnd.
814
815              uchg           set  the  user  immutable  flag  (owner or super-
816                             user).
817
818              uchange        Alias for uchg.
819
820              uimmutable     Alias for uchg.
821
822              uunlnk         set the user undeletable flag  (owner  or  super-
823                             user).
824
825              uunlink        Alias for uunlnk.
826
827              The following flags are only available on Linux:
828
829              compress       Set  the  Linux  ext3 journal data flag (owner or
830                             super-user).
831
832              journal-data   Set the Linux ext3 journal data flag  (super-user
833                             only).
834
835              noatime        Set  the Linux ext3 no access time flag (owner or
836                             super-user).
837
838              secdel         Set the Linux ext3 secure deletion (purge  before
839                             delete) flag (owner or super-user).
840
841              sync           Set  the  Linux  ext3  sync flag (owner or super-
842                             user).
843
844              undel          Set the Linux ext3 "allow unrm"  flag  (owner  or
845                             super-user).
846
847       SCHILY.filetype
848              A  textual  version of the real file type of the file.  The fol‐
849              lowing names are used:
850
851              unallocated             An unknown  file  type  that  may  be  a
852                                      result  of  a unlink(2) operation.  This
853                                      should never happen.
854
855              regular                 A regular file.
856
857              contiguous              A contiguous file. On operating  systems
858                                      or  file systems that don't support this
859                                      file type, it is handled like a  regular
860                                      file.
861
862              symlink                 A symbolic link to any file type.
863
864              directory               A directory.
865
866              character special       A character special file.
867
868              block special           A block special file.
869
870              fifo                    A named pipe.
871
872              socket                  A UNIX domain socket.
873
874              mpx character special   A multiplexed character special file.
875
876              mpx block special       A multiplexed block special file.
877
878              XENIX nsem              A XENIX named semaphore.
879
880              XENIX nshd              XENIX shared data.
881
882              door                    A Solaris door.
883
884              eventcount              A UNOS event count.
885
886              whiteout                A BSD whiteout directory entry.
887
888              sparse                  A sparse regular file.
889
890              volheader               A volume header.
891
892              unknown/bad             Any   other  unknown  file  type.   This
893                                      should never happen.
894
895
896       SCHILY.ino
897              The inode number from st_ino of  the  file  as  decimal  number.
898              This keyword is used in dump mode.
899
900              The  value is an unsigned int.  An implementation should be able
901              to handle at least 64 bit unsigned values.
902
903       SCHILY.nlink
904              The link count of the file as decimal number.  This  keyword  is
905              used in dump mode.
906
907              The  value is an unsigned int.  An implementation should be able
908              to handle at least 32 bit unsigned values.
909
910       SCHILY.offset
911              The offset value for a multi volume continuation  header.   This
912              keyword  is  used with multi volume continuation headers.  Multi
913              volume continuation headers are used to allow to start reading a
914              multi volume archive past the first volume.
915
916              SCHILY.offset  specifies  the byte offset within a file that was
917              split across volumes as a result of a multi volume media  change
918              operation.
919
920              The  value is an unsigned int.  An implementation should be able
921              to handle at least 64 bit unsigned values.
922
923       SCHILY.realsize
924              The real size of the file as decimal number.   This  keyword  is
925              used  if the real size of the file differs from the visible size
926              of the file in the archive.  The real file size differs from the
927              size in the archive if the file type is sparse or if the file is
928              a continuation file on a multi  volume  archive.   In  case  the
929              SCHILY.realsize keyword is needed, it must be past any size key‐
930              word in case a size keyword is also present.
931
932              As sparse files allocate less space on tape than a regular  file
933              and  as  a continued file that started on a previous volume only
934              holds parts of the file, the  SCHILY.realsize  keyword  holds  a
935              bigger number than the size keyword.
936
937              The  value is an unsigned int.  An implementation should be able
938              to handle at least 64 bit unsigned values.
939
940       SCHILY.tarfiletype
941              The following additional file types are used in  SCHILY.tarfile‐
942              type:
943
944              hardlink
945                     A hard link to any file type.
946
947              dumpdir
948                     A directory with dump entries
949
950              multivol continuation
951                     A multi volume continuation for any file type.
952
953              meta   A meta entry (inode meta data only) for any file type.
954
955       SCHILY.xattr.attr
956              A   POSIX.1-2001  coded  version  of  the  Linux  extended  file
957              attributes.   Linux  extended  file  attributes  are  name/value
958              pairs.  Every  attribute name results in a SCHILY.xattr.name tag
959              and the value of the extended attribute is used as the value  of
960              the  POSIX.1-2001  header  tag.  Note that this way of coding is
961              not portable across platforms.  A version for BSD may be created
962              but  Solaris  includes far more features with extended attribute
963              files than Linux does.
964
965              A future version of star will implement a similar method as  the
966              tar  program on Solaris currently uses. When this implementation
967              is ready, the SCHILY.xattr.name feature may be removed in  favor
968              of a truly portable implementation that supports Solaris also.
969
970

SCHILY 'G'LOBAL PAX EXTENSION KEYWORDS

972       The following star vendor unique extensions may only appear in 'g'lobal
973       extended pax headers:
974
975       SCHILY.archtype
976              The textual version of the archive type used.  The textual  val‐
977              ues used for SCHILY.archtype are the same names that are used in
978              the star command line options to set up a specific archive type.
979
980              The following values may currently appear in a  global  extended
981              header:
982
983              xustar         'xstar'  format without "tar" signature at header
984                             offset 508.
985
986              exustar        'xustar' format variant that always  includes  x-
987                             headers and g-headers.
988
989              A complete tar implementation must be prepared to handle all ar‐
990              chives names as documented in star(1).
991
992              In order to allow archive type recognition  from  this  keyword,
993              the minimum tape block size must be 2x512 bytes (1024 bytes) and
994              the SCHILY.archtype keyword needs to be in the first  512  bytes
995              of  the content of the first 'g'lobal pax header. Then the first
996              tape block may be scanned to recognize the archive type.
997
998       SCHILY.release
999              The textual version of the star version string and the  platform
1000              name  where  this star has been compiled.  The same text appears
1001              when calling star -version.
1002
1003              Other implementations may use a version  string  that  does  not
1004              start with the text star.
1005
1006       SCHILY.volhdr.blockoff
1007              This  keyword  is used for multi volume archives.  It represents
1008              the offset within the whole archive expressed in 512 byte units.
1009
1010              The value is an unsigned int with a valid range  between  1  and
1011              infinity. An implementation should be able to handle at least 64
1012              bit unsigned values.
1013
1014       SCHILY.volhdr.blocksize
1015              The tape blocksize expressed in 512 byte  units  that  was  used
1016              when writing the archive.
1017
1018              The  value  is  an unsigned int with a valid range between 1 and
1019              infinity. An implementation should be able to handle at least 31
1020              bit unsigned values.
1021
1022       SCHILY.volhdr.cwd
1023              This  keyword  is used in dump mode.  It is only emitted in case
1024              the  fs-name=  option  of  star  was  used  to   overwrite   the
1025              SCHILY.volhdr.filesys  value.   If SCHILY.volhdr.cwd is present,
1026              it contains the real backup working directory.
1027
1028              Overwriting SCHILY.volhdr.filesys is needed when backups are run
1029              on file system snapshots rather than on the real file system.
1030
1031       SCHILY.volhdr.device
1032              This  keyword  is  used in dump mode.  It represents the name of
1033              the device that holds the file system data. For disk based  file
1034              systems, this is the device name of the mounted device.
1035
1036              This  keyword  is  optional.  It helps to correctly identify the
1037              file system from which this dump has been made.
1038
1039       SCHILY.volhdr.dumpdate
1040              This keyword is used in dump mode.  It represents the  time  the
1041              current dump did start.
1042
1043       SCHILY.volhdr.dumplevel
1044              This  keyword  is used in dump mode.  It represents the level of
1045              the current dump.  Dump levels are  small  numbers,  the  lowest
1046              possible  number  is  0.  Dump level 0 represents a full backup.
1047              Dump level 1 represents a backup that contains all changes  that
1048              did  occur since the last level 0 dump.  Dump level 2 represents
1049              a backup that contains all changes that did occur since the last
1050              level  1  dump.   Star  does  not specify a maximum allowed dump
1051              level but you should try to keep the numbers less than 100.
1052
1053              The value is an unsigned int with a valid range between 0 and at
1054              least 100.
1055
1056       SCHILY.volhdr.dumptype
1057              This  keyword  is  used in dump mode.  If the dump is a complete
1058              dump of a file system (i.e. no files are  excluded  via  command
1059              line),  then the argument is the text full, else the argument is
1060              the text partial.
1061
1062       SCHILY.volhdr.filesys
1063              This keyword is used in dump mode.  It represents the top  level
1064              directory  for  the  file  system  from which this dump has been
1065              made.  If the dump represents a  dump  that  has  an  associated
1066              level, then the this directory needs to be identical to the root
1067              directory of this file system which is the mount point.
1068
1069       SCHILY.volhdr.hostname
1070              This keyword is used in dump mode.  The value is retrieved  from
1071              gethostname(3) or uname(2).
1072
1073       SCHILY.volhdr.label
1074              The  textual  volume  label.  The volume label must be identical
1075              within a set of multi volume archives.
1076
1077       SCHILY.volhdr.refdate
1078              This keyword is used in dump mode if  the  current  dump  is  an
1079              incremental  dump  with a level > 0.  It represents the time the
1080              related dump did start.
1081
1082       SCHILY.volhdr.reflevel
1083              This keyword is used in dump mode if  the  current  dump  is  an
1084              incremental  dump  with a level > 0.  It represents the level of
1085              the related dump.  The related dump is  the  last  dump  with  a
1086              level that is lower that the level of this dump.  If a dump with
1087              the level of the current  dump  -1  exists,  then  this  is  the
1088              related  dump  level.  Otherwise,  the dump level is decremented
1089              until a valid dump level could be found in the dump database.
1090
1091              The value is an unsigned int with a valid range between 0 and at
1092              least 100.
1093
1094       SCHILY.volhdr.tapesize
1095              This  keyword  is used for multi volume archives and may be used
1096              to verify the volume size on read back.  It represents the  tape
1097              size  expressed in 512 byte units.  This keyword is set in multi
1098              volume mode if the size of the tape was not autodetected but set
1099              from a command line option.
1100
1101              The  value  is  an unsigned int with a valid range between 1 and
1102              infinity. An implementation should be able to handle at least 64
1103              bit unsigned values.
1104
1105       SCHILY.volhdr.volume
1106              This  keyword  is used for multi volume archives.  It represents
1107              the volume number within a volume set.  The number used for  the
1108              first volume is 1.
1109
1110              The  value  is  an unsigned int with a valid range between 1 and
1111              infinity. An implementation should be able to handle at least 31
1112              bit unsigned values.
1113

MULTI VOLUME ARCHIVE HANDLING

1115       To be documented in the future.
1116

SEE ALSO

NOTES

BUGS

AUTHOR

1121Joerg Schilling                    11/12/12                           STAR(4L)
Impressum