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.ace
616 The NFSv4 ACL for a file.
617 Since no official backup format for the NFSv4 ACL standard has
619 been defined, star uses the vendor defined attributes
620 SCHILY.acl.ace for storing the NFSv4 ACL entries.
621 The format for the ACL text is the format created by the func‐
623 tion acl_totext() from libsec on Solaris, using the call:
624 acl_totext(aclp, \
626 ACL_COMPACT_FMT | ACL_APPEND_ID | ACL_SID_FMT);
627 The flags have the following meaning:
629 ACL_COMPACT_FMT
631 Create the compact version of the ACL text representa‐
632 tion.
633 ACL_APPEND_ID
635 Append uid or gid for additional user or group entries.
636 ACL_SID_FMT
638 Use the usersid or groupsid format for entries related to
639 an ephemeral uid or gid. The raw sid format will only be
640 used when the "id" cannot be resolved to a windows name.
641 This is an example of the format used for SCHILY.acl.ace (a
643 space has been inserted after the equal sign and lines are bro‐
644 ken [marked with '\' ] for readability):
645 SCHILY.acl.ace= user:lisa:rwx-----------:-------:allow:502, \
647 group:toolies:rwx-----------:-------:allow:102, \
648 owner@:--x-----------:-------:deny, \
649 owner@:rw-p---A-W-Co-:-------:allow, \
650 group@:-wxp----------:-------:deny, \
651 group@:r-------------:-------:allow, \
652 everyone@:-wxp---A-W-Co-:-------:deny, \
653 everyone@:r-----a-R-c--s:-------:allow
654 The numerical user and group identifiers are essential when
656 restoring a system completely from a backup, as initially the
657 name-to-identifier mappings may not be available, and then file
658 ownership restoration would not work.
659 In addition to the documented entry format, a compatible imple‐
661 mentation needs to be able to understand the long ace format, if
662 it appears in extended tar headers.
663 As the archive format that is used for backing up access control
665 lists is compatible with the pax archive format, archives cre‐
666 ated that way can be restored by star or a POSIX.1-2001 compli‐
667 ant pax. Note that programs other than star will ignore the ACL
668 information.
669 SCHILY.acl.access
672 The withdrawn POSIX draft ACL for a file.
673 Since no official backup format for the withdrawn POSIX draft
675 access control lists has been defined, star uses the vendor
676 defined attributes SCHILY.acl.access and SCHILY.acl.default for
677 storing the ACL and Default ACL of a file, respectively. The
678 access control lists are stored in the short text form as
679 defined in the withdrawn POSIX 1003.1e draft standard 17.
680 Note that the POSIX 1003.1e draft has been withdrawn in 1997 but
682 some operating systems still support it with some filesystems.
683 To each named user ACL entry a fourth colon separated field
685 field containing the user identifier (UID) of the associated
686 user is appended. To each named group entry a fourth colon sep‐
687 arated field containing the group identifier (GID) of the asso‐
688 ciated group is appended. (POSIX 1003.1e draft standard 17
689 allows to add fields to ACL entries.)
690 This is an example of the format used for SCHILY.acl.access (a
692 space has been inserted after the equal sign and lines are bro‐
693 ken [marked with '\' ] for readability, additional fields in
694 bold):
695 SCHILY.acl.access= user::rwx,user:lisa:r-x:502, \
697 group::r-x,group:toolies:rwx:102, \
698 mask::rwx,other::r--x
699 The numerical user and group identifiers are essential when
701 restoring a system completely from a backup, as initially the
702 name-to-identifier mappings may not be available, and then file
703 ownership restoration would not work.
704 As the archive format that is used for backing up access control
706 lists is compatible with the pax archive format, archives cre‐
707 ated that way can be restored by star or a POSIX.1-2001 compli‐
708 ant pax. Note that programs other than star will ignore the ACL
709 information.
710 SCHILY.acl.default
712 The default ACL for a file. See SCHILY.acl.access for more
713 information.
714 This is an example of the format used for SCHILY.acl.default (a
716 space has been inserted after the equal sign and lines are bro‐
717 ken [marked with '\' ] for readability, additional fields in
718 bold):
719 SCHILY.acl.default= user::rwx,user:lisa:r-x:502, \
721 group::r-x,mask::r-x,other::r-x
722 SCHILY.acl.type
724 The ACL type used for coding access control lists.
725 The following ACL types are possible:
727 POSIX draft
729 ACLs as defined in the withdrawn POSIX 1003.1e draft
730 standard 17.
731 NFSv4 ACLs as used by NFSv4, NTFS and ZFS.
733 Note that the SCHILY.acl.type keyword is currently not generated by
735 star. Star however accepts this keyword if it appears in extended tar
736 headers. The ACL type is determined from the keyword type that holds
737 the ACL text.
738 SCHILY.ddev
740 The device ids for names used is the SCHILY.dir dump directory
741 list from st_dev of the file as decimal number. The SCHILY.ddev
742 keyword is followed by a space separated list of device id num‐
743 bers. Each corresponds exactly to a name in the list found in
744 SCHILY.dir. If a specific device id number is repeated, a comma
745 (,) without a following space may be use to denote that the cur‐
746 rent device id number is identical to the previous number. This
747 keyword is used in dump mode. This keyword is not yet imple‐
748 mented.
749 The value is a signed int. An implementation should be able to
751 handle at least 64 bit values. Note that the value is signed
752 because POSIX does not specify more than the type should be an
753 int.
754 SCHILY.dev
756 The device id from st_dev of the file as decimal number. This
757 keyword is used in dump mode.
758 The value is a signed int. An implementation should be able to
760 handle at least 64 bit values. Note that the value is signed
761 because POSIX does not specify more than the type should be an
762 int.
763 SCHILY.devmajor
765 The device major number of the file if it is a character or
766 block special file. The argument is a decimal number. This
767 field is used if the device major of the file is greater than
768 2097151 (octal 7777777).
769 The value is a signed int. An implementation should be able to
771 handle at least 64 bit values. Note that the value is signed
772 because POSIX does not specify more than the type should be an
773 int.
774 SCHILY.devminor
776 The device minor number of the file if it is a character or
777 block special file. The argument is a decimal number. This
778 field is used if the device minor of the file is greater than
779 2097151 (octal 7777777).
780 The value is a signed int. An implementation should be able to
782 handle at least 64 bit values. Note that the value is signed
783 because POSIX does not specify more than the type should be an
784 int.
785 SCHILY.dino
787 The inode numbers for names used is the SCHILY.dir dump direc‐
788 tory list from st_ino of the file as decimal number. The
789 SCHILY.dino keyword is followed by a space separated list of
790 inode numbers. Each corresponds exactly to a name in the list
791 found in SCHILY.dir. This keyword is used in dump mode.
792 The values are unsigned int. An implementation should be able
794 to handle at least 64 bit unsigned values.
795 SCHILY.dir
797 A list of filenames (the content) for the current directory.
798 The names are coded in UTF-8. Each file name is prefixed by a
799 single character that is used as a flag. Each file name is lim‐
800 ited by a null character. The null character is directly fol‐
801 lowed by he flag character for the next file name in case the
802 list is not terminated by the current file name. The flag char‐
803 acter must not be a null character. By default, a ^A (octal
804 001) is used. The following flags are defined:
805 \000 This is the list terminator character - the second null
807 byte, see below.
808 ^A The default flag that is used in case the dump dir fea‐
810 tures have not been active.
811 Y A non directory file that is in the current (incremental)
813 dump.
814 N A non directory file that is not in the current (incre‐
816 mental) dump.
817 D A directory that is in the current (incremental) dump.
819 d A directory that is not in the current (incremental)
821 dump.
822 The list is terminated by two successive null bytes. The first
824 is the null byte for the last file name. The second null byte
825 is at the position where a flag character would be expected, it
826 acts ad a list terminator. The length tag for the SCHILY.dir
827 data includes both null bytes.
828 If a dump mode has been selected that writes compact complete
830 directory information to the beginning of the archive, the flag
831 character may contain values different from ^A. Star implemen‐
832 tations at least up to star-1.5.1 do not use the feature to tag
833 entries and use the default entry \001 (^A) for all files. Tar
834 implementations that like to read archives that use the
835 SCHILY.dir keyword, shall not rely on values other than \000
836 (^@) or \001 (^A).
837 This keyword is used in dump mode.
839 SCHILY.fflags
841 A textual version of the BSD or Linux extended file flags.
842 The following flags are defined by star:
844 arch set the archived flag (super-user only).
846 archived Alias for arch.
848 nodump set the nodump flag (owner or super-user).
850 opaque set the opaque flag (owner or super-user).
852 sappnd set the system append-only flag (super-user
854 only).
855 sappend Alias for sappnd.
857 schg set the system immutable flag (super-user only).
859 schange Alias for schg.
861 simmutable Alias for schg.
863 sunlnk set the system undeletable flag (super-user
865 only).
866 sunlink Alias for sunlnk.
868 uappnd set the user append-only flag (owner or super-
870 user).
871 uappend Alias for uappnd.
873 uchg set the user immutable flag (owner or super-
875 user).
876 uchange Alias for uchg.
878 uimmutable Alias for uchg.
880 uunlnk set the user undeletable flag (owner or super-
882 user).
883 uunlink Alias for uunlnk.
885 The following flags are only available on Linux:
887 compress Set the Linux ext3 journal data flag (owner or
889 super-user).
890 journal-data Set the Linux ext3 journal data flag (super-user
892 only).
893 noatime Set the Linux ext3 no access time flag (owner or
895 super-user).
896 secdel Set the Linux ext3 secure deletion (purge before
898 delete) flag (owner or super-user).
899 sync Set the Linux ext3 sync flag (owner or super-
901 user).
902 undel Set the Linux ext3 "allow unrm" flag (owner or
904 super-user).
905 SCHILY.filetype
907 A textual version of the real file type of the file. The fol‐
908 lowing names are used:
909 unallocated An unknown file type that may be a
911 result of a unlink(2) operation. This
912 should never happen.
913 regular A regular file.
915 contiguous A contiguous file. On operating systems
917 or file systems that don't support this
918 file type, it is handled like a regular
919 file.
920 symlink A symbolic link to any file type.
922 directory A directory.
924 character special A character special file.
926 block special A block special file.
928 fifo A named pipe.
930 socket A UNIX domain socket.
932 mpx character special A multiplexed character special file.
934 mpx block special A multiplexed block special file.
936 XENIX nsem A XENIX named semaphore.
938 XENIX nshd XENIX shared data.
940 door A Solaris door.
942 eventcount A UNOS event count.
944 whiteout A BSD whiteout directory entry.
946 sparse A sparse regular file.
948 volheader A volume header.
950 unknown/bad Any other unknown file type. This
952 should never happen.
953 SCHILY.ino
956 The inode number from st_ino of the file as decimal number.
957 This keyword is used in dump mode.
958 The value is an unsigned int. An implementation should be able
960 to handle at least 64 bit unsigned values.
961 SCHILY.nlink
963 The link count of the file as decimal number. This keyword is
964 used in dump mode.
965 The value is an unsigned int. An implementation should be able
967 to handle at least 32 bit unsigned values.
968 SCHILY.offset
970 The offset value for a multi volume continuation header. This
971 keyword is used with multi volume continuation headers. Multi
972 volume continuation headers are used to allow to start reading a
973 multi volume archive past the first volume.
974 SCHILY.offset specifies the byte offset within a file that was
976 split across volumes as a result of a multi volume media change
977 operation.
978 The value is an unsigned int. An implementation should be able
980 to handle at least 64 bit unsigned values.
981 SCHILY.realsize
983 The real size of the file as decimal number. This keyword is
984 used if the real size of the file differs from the visible size
985 of the file in the archive. The real file size differs from the
986 size in the archive if the file type is sparse or if the file is
987 a continuation file on a multi volume archive. In case the
988 SCHILY.realsize keyword is needed, it must be past any size key‐
989 word in case a size keyword is also present.
990 As sparse files allocate less space on tape than a regular file
992 and as a continued file that started on a previous volume only
993 holds parts of the file, the SCHILY.realsize keyword holds a
994 bigger number than the size keyword.
995 The value is an unsigned int. An implementation should be able
997 to handle at least 64 bit unsigned values.
998 SCHILY.tarfiletype
1000 The following additional file types are used in SCHILY.tarfile‐
1001 type:
1002 hardlink
1004 A hard link to any file type.
1005 dumpdir
1007 A directory with dump entries
1008 multivol continuation
1010 A multi volume continuation for any file type.
1011 meta A meta entry (inode meta data only) for any file type.
1013 SCHILY.xattr.attr
1015 A POSIX.1-2001 coded version of the Linux extended file
1016 attributes. Linux extended file attributes are name/value
1017 pairs. Every attribute name results in a SCHILY.xattr.name tag
1018 and the value of the extended attribute is used as the value of
1019 the POSIX.1-2001 header tag. Note that this way of coding is
1020 not portable across platforms. A version for BSD may be created
1021 but Solaris includes far more features with extended attribute
1022 files than Linux does.
1023 A future version of star will implement a similar method as the
1025 tar program on Solaris currently uses. When this implementation
1026 is ready, the SCHILY.xattr.name feature may be removed in favor
1027 of a truly portable implementation that supports Solaris also.
1028
1031 The following star vendor unique extensions may only appear in 'g'lobal
1032 extended pax headers:
1033 SCHILY.archtype
1035 The textual version of the archive type used. The textual val‐
1036 ues used for SCHILY.archtype are the same names that are used in
1037 the star command line options to set up a specific archive type.
1038 The following values may currently appear in a global extended
1040 header:
1041 xustar 'xstar' format without "tar" signature at header
1043 offset 508.
1044 exustar 'xustar' format variant that always includes x-
1046 headers and g-headers.
1047 A complete tar implementation must be prepared to handle all ar‐
1049 chives names as documented in star(1).
1050 In order to allow archive type recognition from this keyword,
1052 the minimum tape block size must be 2x512 bytes (1024 bytes) and
1053 the SCHILY.archtype keyword needs to be in the first 512 bytes
1054 of the content of the first 'g'lobal pax header. Then the first
1055 tape block may be scanned to recognize the archive type.
1056 SCHILY.release
1058 The textual version of the star version string and the platform
1059 name where this star has been compiled. The same text appears
1060 when calling star -version.
1061 Other implementations may use a version string that does not
1063 start with the text star.
1064 SCHILY.volhdr.blockoff
1066 This keyword is used for multi volume archives. It represents
1067 the offset within the whole archive expressed in 512 byte units.
1068 The value is an unsigned int with a valid range between 1 and
1070 infinity. An implementation should be able to handle at least 64
1071 bit unsigned values.
1072 SCHILY.volhdr.blocksize
1074 The tape blocksize expressed in 512 byte units that was used
1075 when writing the archive.
1076 The value is an unsigned int with a valid range between 1 and
1078 infinity. An implementation should be able to handle at least 31
1079 bit unsigned values.
1080 SCHILY.volhdr.cwd
1082 This keyword is used in dump mode. It is only emitted in case
1083 the fs-name= option of star was used to overwrite the
1084 SCHILY.volhdr.filesys value. If SCHILY.volhdr.cwd is present,
1085 it contains the real backup working directory.
1086 Overwriting SCHILY.volhdr.filesys is needed when backups are run
1088 on file system snapshots rather than on the real file system.
1089 SCHILY.volhdr.device
1091 This keyword is used in dump mode. It represents the name of
1092 the device that holds the file system data. For disk based file
1093 systems, this is the device name of the mounted device.
1094 This keyword is optional. It helps to correctly identify the
1096 file system from which this dump has been made.
1097 SCHILY.volhdr.dumpdate
1099 This keyword is used in dump mode. It represents the time the
1100 current dump did start.
1101 SCHILY.volhdr.dumplevel
1103 This keyword is used in dump mode. It represents the level of
1104 the current dump. Dump levels are small numbers, the lowest
1105 possible number is 0. Dump level 0 represents a full backup.
1106 Dump level 1 represents a backup that contains all changes that
1107 did occur since the last level 0 dump. Dump level 2 represents
1108 a backup that contains all changes that did occur since the last
1109 level 1 dump. Star does not specify a maximum allowed dump
1110 level but you should try to keep the numbers less than 100.
1111 The value is an unsigned int with a valid range between 0 and at
1113 least 100.
1114 SCHILY.volhdr.dumptype
1116 This keyword is used in dump mode. If the dump is a complete
1117 dump of a file system (i.e. no files are excluded via command
1118 line), then the argument is the text full, else the argument is
1119 the text partial.
1120 SCHILY.volhdr.filesys
1122 This keyword is used in dump mode. It represents the top level
1123 directory for the file system from which this dump has been
1124 made. If the dump represents a dump that has an associated
1125 level, then the this directory needs to be identical to the root
1126 directory of this file system which is the mount point.
1127 SCHILY.volhdr.hostname
1129 This keyword is used in dump mode. The value is retrieved from
1130 gethostname(3) or uname(2).
1131 SCHILY.volhdr.label
1133 The textual volume label. The volume label must be identical
1134 within a set of multi volume archives.
1135 SCHILY.volhdr.refdate
1137 This keyword is used in dump mode if the current dump is an
1138 incremental dump with a level > 0. It represents the time the
1139 related dump did start.
1140 SCHILY.volhdr.reflevel
1142 This keyword is used in dump mode if the current dump is an
1143 incremental dump with a level > 0. It represents the level of
1144 the related dump. The related dump is the last dump with a
1145 level that is lower that the level of this dump. If a dump with
1146 the level of the current dump -1 exists, then this is the
1147 related dump level. Otherwise, the dump level is decremented
1148 until a valid dump level could be found in the dump database.
1149 The value is an unsigned int with a valid range between 0 and at
1151 least 100.
1152 SCHILY.volhdr.tapesize
1154 This keyword is used for multi volume archives and may be used
1155 to verify the volume size on read back. It represents the tape
1156 size expressed in 512 byte units. This keyword is set in multi
1157 volume mode if the size of the tape was not autodetected but set
1158 from a command line option.
1159 The value is an unsigned int with a valid range between 1 and
1161 infinity. An implementation should be able to handle at least 64
1162 bit unsigned values.
1163 SCHILY.volhdr.volume
1165 This keyword is used for multi volume archives. It represents
1166 the volume number within a volume set. The number used for the
1167 first volume is 1.
1168 The value is an unsigned int with a valid range between 1 and
1170 infinity. An implementation should be able to handle at least 31
1171 bit unsigned values.
1172
1174 To be documented in the future.
1175
1180Joerg Schilling 13/11/05 STAR(4L)