1STAR(4L) Schily´s USER COMMANDS STAR(4L)
2
6 star - tape archive file format
7
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
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 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 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 #define TMODLEN 8
41 #define TUIDLEN 8
42 #define TGIDLEN 8
43 #define TSIZLEN 12
44 #define TMTMLEN 12
45 #define TCKSLEN 8
46 #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 /*
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 /*
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 See section EXTENDED TAR (PAX) HEADER KEYWORDS for more information
79 about the structure of a POSIX.1-2001 header.
80 /*
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 #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 /*
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 #define TALLMODES 07777 /* The low 12 bits */
118 /*
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 /*
144 * star header specific definitions
145 */
146 #define STMAGIC "tar" /* star magic */
147 #define STMAGLEN 4 /* "tar" including '\0' */
148 /*
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 struct sparse {
191 char t_offset[12];
192 char t_numbytes[12];
193 };
194 #define SPARSE_EXT_HDR 21
196 struct xstar_ext_header {
198 struct sparse t_sp[21];
199 char t_isextended;
200 };
201 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 For maximum portability, all fields that contain character strings
211 should be limited to use the low 7 bits of a character.
212 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 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 The fields magic, uname and gname contain null terminated character
227 strings.
228 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 The typeflag field contains a single character.
234 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 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 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 The mode field contains 12 bits holding permissions, see above for the
266 definitions for each of the permission bits.
267 The uid and gid fields contain the numerical user id of the file.
269 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 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 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 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 '0' REGTYPE
294 A regular file. If the size field is non zero, then file data
295 follows the header.
296 '\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 '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 '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 '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 '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 '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 '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 '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 '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 '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 'A' - 'Z'
372 Reserved for vendor specific implementations.
373 '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 '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 '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 '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 '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 '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 '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 'N' An outdated linktype used by old GNU tar versions to store long
423 file names. This type is unsupported by star.
424 '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 '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 '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
454 Block type Description
455 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 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
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 "%d %s=%s\n", <length>, <keyword>, <value>
474 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 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 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 Null characters do not delimit any value. The data used for value is
488 only limited by its implicit length.
489
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 atime The time from st_atime in sub second granularity. Star cur‐
496 rently supports a nanosecond granularity.
497 charset
499 The name of the character set used to encode the data in the
500 following file(s).
501 The following values are supported for charset:
503 ISO-IR 646 1990 SO/IEC 646:1990
505 ISO-IR 8859 1 1998 ISO/IEC 8859-1:1998
507 ISO-IR 8859 2 1998 ISO/IEC 8859-2:1998
509 ISO-IR 8859 3 1998 ISO/IEC 8859-3:1998
511 ISO-IR 8859 4 1998 ISO/IEC 8859-4:1998
513 ISO-IR 8859 5 1998 ISO/IEC 8859-5:1998
515 ISO-IR 8859 6 1998 ISO/IEC 8859-6:1998
517 ISO-IR 8859 7 1998 ISO/IEC 8859-7:1998
519 ISO-IR 8859 8 1998 ISO/IEC 8859-8:1998
521 ISO-IR 8859 9 1998 ISO/IEC 8859-9:1998
523 ISO-IR 8859 10 1998 ISO/IEC 8859-10:1998
525 ISO-IR 8859 11 1998 ISO/IEC 8859-11:1998
527 ISO-IR 8859 12 1998 ISO/IEC 8859-12:1998
529 ISO-IR 8859 13 1998 ISO/IEC 8859-13:1998
531 ISO-IR 8859 14 1998 ISO/IEC 8859-14:1998
533 ISO-IR 8859 15 1998 ISO/IEC 8859-15:1998
535 ISO-IR 10646 2000 ISO/IEC 10646:2000
537 ISO-IR 10646 2000 UTF-8 ISO/IEC 10646, UTF-8 encoding
539 BINARY None
541 This keyword is currently ignored by star.
543 comment
545 Any number of characters that should be treated as comment.
546 Star ignores the comment as documented by the POSIX standard.
547 ctime The time from st_ctime in sub second granularity. Star cur‐
549 rently supports a nanosecond granularity.
550 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 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 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 The following values are supported for hdrcharset:
565 ISO-IR 10646 2000 UTF-8 ISO/IEC 10646, UTF-8 encoding
567 BINARY None
569 This keyword is currently ignored by star.
571 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 mtime The time from st_mtime in sub second granularity. Star cur‐
577 rently supports a nanosecond granularity.
578 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 realtime.any
584 The keywords prefixed by realtime. are reserved for future
585 standardization.
586 security.any
588 The keywords prefixed by security. are reserved for future
589 standardization.
590 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 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 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 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
612 Star uses own vendor specific extensions. The SCHILY vendor specific
613 extended pax header keywords are:
614 SCHILY.acl.access
616 The ACL for a file.
617 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 Note that the POSIX 1003.1e draft has been withdrawn in 1997 but
626 some operating systems still support it with some filesystems.
627 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 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 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 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 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 SCHILY.acl.default
656 The default ACL for a file. See SCHILY.acl.access for more
657 information.
658 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 SCHILY.acl.default= user::rwx,user:lisa:r-x:502, \
665 group::r-x,mask::r-x,other::r-x
666 SCHILY.acl.type
668 The ACL type used for coding access control lists.
669 The following ACL types are possible:
671 POSIX draft
673 ACLs as defined in POSIX 1003.1e draft standard 17.
674 NFSv4 ACLs as used by NFSv4, NTFS and ZFS.
676 Star currently only implements POSIX draft ACLs. If the
678 SCHILY.acl.type keyword is missing, POSIX draft ACLs are asumed.
679 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 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 SCHILY.dev
697 The device id from st_dev of the file as decimal number. This
698 keyword is used in dump mode.
699 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 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 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 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 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 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 The values are unsigned int. An implementation should be able
735 to handle at least 64 bit unsigned values.
736 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 \000 This is the list terminator character - the second null
748 byte, see below.
749 ^A The default flag that is used in case the dump dir fea‐
751 tures have not been active.
752 Y A non directory file that is in the current (incremental)
754 dump.
755 N A non directory file that is not in the current (incre‐
757 mental) dump.
758 D A directory that is in the current (incremental) dump.
760 d A directory that is not in the current (incremental)
762 dump.
763 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 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 This keyword is used in dump mode.
780 SCHILY.fflags
782 A textual version of the BSD or Linux extended file flags.
783 The following flags are defined by star:
785 arch set the archived flag (super-user only).
787 archived Alias for arch.
789 nodump set the nodump flag (owner or super-user).
791 opaque set the opaque flag (owner or super-user).
793 sappnd set the system append-only flag (super-user
795 only).
796 sappend Alias for sappnd.
798 schg set the system immutable flag (super-user only).
800 schange Alias for schg.
802 simmutable Alias for schg.
804 sunlnk set the system undeletable flag (super-user
806 only).
807 sunlink Alias for sunlnk.
809 uappnd set the user append-only flag (owner or super-
811 user).
812 uappend Alias for uappnd.
814 uchg set the user immutable flag (owner or super-
816 user).
817 uchange Alias for uchg.
819 uimmutable Alias for uchg.
821 uunlnk set the user undeletable flag (owner or super-
823 user).
824 uunlink Alias for uunlnk.
826 The following flags are only available on Linux:
828 compress Set the Linux ext3 journal data flag (owner or
830 super-user).
831 journal-data Set the Linux ext3 journal data flag (super-user
833 only).
834 noatime Set the Linux ext3 no access time flag (owner or
836 super-user).
837 secdel Set the Linux ext3 secure deletion (purge before
839 delete) flag (owner or super-user).
840 sync Set the Linux ext3 sync flag (owner or super-
842 user).
843 undel Set the Linux ext3 "allow unrm" flag (owner or
845 super-user).
846 SCHILY.filetype
848 A textual version of the real file type of the file. The fol‐
849 lowing names are used:
850 unallocated An unknown file type that may be a
852 result of a unlink(2) operation. This
853 should never happen.
854 regular A regular file.
856 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 symlink A symbolic link to any file type.
863 directory A directory.
865 character special A character special file.
867 block special A block special file.
869 fifo A named pipe.
871 socket A UNIX domain socket.
873 mpx character special A multiplexed character special file.
875 mpx block special A multiplexed block special file.
877 XENIX nsem A XENIX named semaphore.
879 XENIX nshd XENIX shared data.
881 door A Solaris door.
883 eventcount A UNOS event count.
885 whiteout A BSD whiteout directory entry.
887 sparse A sparse regular file.
889 volheader A volume header.
891 unknown/bad Any other unknown file type. This
893 should never happen.
894 SCHILY.ino
897 The inode number from st_ino of the file as decimal number.
898 This keyword is used in dump mode.
899 The value is an unsigned int. An implementation should be able
901 to handle at least 64 bit unsigned values.
902 SCHILY.nlink
904 The link count of the file as decimal number. This keyword is
905 used in dump mode.
906 The value is an unsigned int. An implementation should be able
908 to handle at least 32 bit unsigned values.
909 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 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 The value is an unsigned int. An implementation should be able
921 to handle at least 64 bit unsigned values.
922 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 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 The value is an unsigned int. An implementation should be able
938 to handle at least 64 bit unsigned values.
939 SCHILY.tarfiletype
941 The following additional file types are used in SCHILY.tarfile‐
942 type:
943 hardlink
945 A hard link to any file type.
946 dumpdir
948 A directory with dump entries
949 multivol continuation
951 A multi volume continuation for any file type.
952 meta A meta entry (inode meta data only) for any file type.
954 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 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
972 The following star vendor unique extensions may only appear in 'g'lobal
973 extended pax headers:
974 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 The following values may currently appear in a global extended
981 header:
982 xustar 'xstar' format without "tar" signature at header
984 offset 508.
985 exustar 'xustar' format variant that always includes x-
987 headers and g-headers.
988 A complete tar implementation must be prepared to handle all ar‐
990 chives names as documented in star(1).
991 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 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 Other implementations may use a version string that does not
1004 start with the text star.
1005 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 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 SCHILY.volhdr.blocksize
1015 The tape blocksize expressed in 512 byte units that was used
1016 when writing the archive.
1017 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 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 Overwriting SCHILY.volhdr.filesys is needed when backups are run
1029 on file system snapshots rather than on the real file system.
1030 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 This keyword is optional. It helps to correctly identify the
1037 file system from which this dump has been made.
1038 SCHILY.volhdr.dumpdate
1040 This keyword is used in dump mode. It represents the time the
1041 current dump did start.
1042 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 The value is an unsigned int with a valid range between 0 and at
1054 least 100.
1055 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 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 SCHILY.volhdr.hostname
1070 This keyword is used in dump mode. The value is retrieved from
1071 gethostname(3) or uname(2).
1072 SCHILY.volhdr.label
1074 The textual volume label. The volume label must be identical
1075 within a set of multi volume archives.
1076 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 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 The value is an unsigned int with a valid range between 0 and at
1092 least 100.
1093 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 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 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 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
1115 To be documented in the future.
1116
1121Joerg Schilling 11/12/12 STAR(4L)