summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorDenis Vlasenko <vda.linux@googlemail.com>2006-11-26 17:07:38 +0000
committerDenis Vlasenko <vda.linux@googlemail.com>2006-11-26 17:07:38 +0000
commitec0c920a78813d1c047924e024017189dedeec93 (patch)
treef81c31d8cb7c0a1e1cad6464e2c69578b74befb6 /docs
parent664733f1a3cfedbb4cde3815b61d9b87dcc42387 (diff)
downloadbusybox-w32-ec0c920a78813d1c047924e024017189dedeec93.tar.gz
busybox-w32-ec0c920a78813d1c047924e024017189dedeec93.tar.bz2
busybox-w32-ec0c920a78813d1c047924e024017189dedeec93.zip
added small doc about tar 'pax header' format
Diffstat (limited to 'docs')
-rw-r--r--docs/tar_pax.txt239
1 files changed, 239 insertions, 0 deletions
diff --git a/docs/tar_pax.txt b/docs/tar_pax.txt
new file mode 100644
index 000000000..8a3f1e755
--- /dev/null
+++ b/docs/tar_pax.txt
@@ -0,0 +1,239 @@
1'pax headers' is POSIX 2003 (iirc) addition designed to fix
2tar format limitations - older tar format has fixed fields
3for everything (filename, uid, filesize etc) which can overflow.
4
5pax Header Block
6
7The pax header block shall be identical to the ustar header block
8described in ustar Interchange Format, except that two additional
9typeflag values are defined:
10
11x
12 Represents extended header records for the following file in
13the archive (which shall have its own ustar header block).
14
15g
16 Represents global extended header records for the following
17files in the archive. Each value shall affect all subsequent files
18that do not override that value in their own extended header
19record and until another global extended header record is reached
20that provides another value for the same field. The typeflag g
21global headers should not be used with interchange media that
22could suffer partial data loss in transporting the archive.
23
24For both of these types, the size field shall be the size of the
25extended header records in octets. The other fields in the header
26block are not meaningful to this version of the pax utility.
27However, if this archive is read by a pax utility conforming to
28the ISO POSIX-2:1993 standard, the header block fields are used to
29create a regular file that contains the extended header records as
30data. Therefore, header block field values should be selected to
31provide reasonable file access to this regular file.
32
33A further difference from the ustar header block is that data
34blocks for files of typeflag 1 (the digit one) (hard link) may be
35included, which means that the size field may be greater than
36zero.
37
38pax Extended Header
39
40An extended header shall consist of one or more records, each
41constructed as follows:
42
43"%d %s=%s\n", <length>, <keyword>, <value>
44
45The <length> field shall be the decimal length of the extended
46header record in octets, including length string itself and the
47trailing <newline>.
48
49[skip]
50
51atime
52 The file access time for the following file(s), equivalent to
53the value of the st_atime member of the stat structure for a file,
54as described by the stat() function. The access time shall be
55restored if the process has the appropriate privilege required to
56do so. The format of the <value> shall be as described in pax
57Extended Header File Times.
58
59charset
60 The name of the character set used to encode the data in the
61following file(s).
62
63 The encoding is included in an extended header for information
64only; when pax is used as described in IEEE Std 1003.1-2001, it
65shall not translate the file data into any other encoding. The
66BINARY entry indicates unencoded binary data.
67
68 When used in write or copy mode, it is implementation-defined
69whether pax includes a charset extended header record for a file.
70
71comment
72 A series of characters used as a comment. All characters in
73the <value> field shall be ignored by pax.
74
75gid
76 The group ID of the group that owns the file, expressed as a
77decimal number using digits from the ISO/IEC 646:1991 standard.
78This record shall override the gid field in the following header
79block(s). When used in write or copy mode, pax shall include a gid
80extended header record for each file whose group ID is greater
81than 2097151 (octal 7777777).
82
83gname
84 The group of the file(s), formatted as a group name in the
85group database. This record shall override the gid and gname
86fields in the following header block(s), and any gid extended
87header record. When used in read, copy, or list mode, pax shall
88translate the name from the UTF-8 encoding in the header record to
89the character set appropriate for the group database on the
90receiving system. If any of the UTF-8 characters cannot be
91translated, and if the -o invalid= UTF-8 option is not specified,
92the results are implementation-defined. When used in write or copy
93mode, pax shall include a gname extended header record for each
94file whose group name cannot be represented entirely with the
95letters and digits of the portable character set.
96
97linkpath
98 The pathname of a link being created to another file, of any
99type, previously archived. This record shall override the linkname
100field in the following ustar header block(s). The following ustar
101header block shall determine the type of link created. If typeflag
102of the following header block is 1, it shall be a hard link. If
103typeflag is 2, it shall be a symbolic link and the linkpath value
104shall be the contents of the symbolic link. The pax utility shall
105translate the name of the link (contents of the symbolic link)
106from the UTF-8 encoding to the character set appropriate for the
107local file system. When used in write or copy mode, pax shall
108include a linkpath extended header record for each link whose
109pathname cannot be represented entirely with the members of the
110portable character set other than NUL.
111
112mtime
113 The file modification time of the following file(s),
114equivalent to the value of the st_mtime member of the stat
115structure for a file, as described in the stat() function. This
116record shall override the mtime field in the following header
117block(s). The modification time shall be restored if the process
118has the appropriate privilege required to do so. The format of the
119<value> shall be as described in pax Extended Header File Times.
120
121path
122 The pathname of the following file(s). This record shall
123override the name and prefix fields in the following header
124block(s). The pax utility shall translate the pathname of the file
125from the UTF-8 encoding to the character set appropriate for the
126local file system.
127
128 When used in write or copy mode, pax shall include a path
129extended header record for each file whose pathname cannot be
130represented entirely with the members of the portable character
131set other than NUL.
132
133realtime.any
134 The keywords prefixed by "realtime." are reserved for future
135standardization.
136
137security.any
138 The keywords prefixed by "security." are reserved for future
139standardization.
140
141size
142 The size of the file in octets, expressed as a decimal number
143using digits from the ISO/IEC 646:1991 standard. This record shall
144override the size field in the following header block(s). When
145used in write or copy mode, pax shall include a size extended
146header record for each file with a size value greater than
1478589934591 (octal 77777777777).
148
149uid
150 The user ID of the file owner, expressed as a decimal number
151using digits from the ISO/IEC 646:1991 standard. This record shall
152override the uid field in the following header block(s). When used
153in write or copy mode, pax shall include a uid extended header
154record for each file whose owner ID is greater than 2097151 (octal
1557777777).
156
157uname
158 The owner of the following file(s), formatted as a user name
159in the user database. This record shall override the uid and uname
160fields in the following header block(s), and any uid extended
161header record. When used in read, copy, or list mode, pax shall
162translate the name from the UTF-8 encoding in the header record to
163the character set appropriate for the user database on the
164receiving system. If any of the UTF-8 characters cannot be
165translated, and if the -o invalid= UTF-8 option is not specified,
166the results are implementation-defined. When used in write or copy
167mode, pax shall include a uname extended header record for each
168file whose user name cannot be represented entirely with the
169letters and digits of the portable character set.
170
171If the <value> field is zero length, it shall delete any header
172block field, previously entered extended header value, or global
173extended header value of the same name.
174
175If a keyword in an extended header record (or in a -o
176option-argument) overrides or deletes a corresponding field in the
177ustar header block, pax shall ignore the contents of that header
178block field.
179
180Unlike the ustar header block fields, NULs shall not delimit
181<value>s; all characters within the <value> field shall be
182considered data for the field. None of the length limitations of
183the ustar header block fields in ustar Header Block shall apply to
184the extended header records.
185
186pax Extended Header File Times
187
188Time records shall be formatted as a decimal representation of the
189time in seconds since the Epoch. If a period ( '.' ) decimal point
190character is present, the digits to the right of the point shall
191represent the units of a subsecond timing granularity. In read or
192copy mode, the pax utility shall truncate the time of a file to
193the greatest value that is not greater than the input header
194file time. In write or copy mode, the pax utility shall output a
195time exactly if it can be represented exactly as a decimal number,
196and otherwise shall generate only enough digits so that the same
197time shall be recovered if the file is extracted on a system whose
198underlying implementation supports the same time granularity.
199
200Example from Linux kernel archive tarball:
201
20200000000 70 61 78 5f 67 6c 6f 62 61 6c 5f 68 65 61 64 65 |pax_global_heade|
20300000010 72 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |r...............|
20400000020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
20500000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
20600000040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
20700000050 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
20800000060 00 00 00 00 30 30 30 30 36 36 36 00 30 30 30 30 |....0000666.0000|
20900000070 30 30 30 00 30 30 30 30 30 30 30 00 30 30 30 30 |000.0000000.0000|
21000000080 30 30 30 30 30 36 34 00 30 30 30 30 30 30 30 30 |0000064.00000000|
21100000090 30 30 30 00 30 30 31 34 30 35 33 00 67 00 00 00 |000.0014053.g...|
212000000a0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
213000000b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
214000000c0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
215000000d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
216000000e0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
217000000f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
21800000100 00 75 73 74 61 72 00 30 30 67 69 74 00 00 00 00 |.ustar.00git....|
21900000110 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
22000000120 00 00 00 00 00 00 00 00 00 67 69 74 00 00 00 00 |.........git....|
22100000130 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
22200000140 00 00 00 00 00 00 00 00 00 30 30 30 30 30 30 30 |.........0000000|
22300000150 00 30 30 30 30 30 30 30 00 00 00 00 00 00 00 00 |.0000000........|
22400000160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
22500000170 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
22600000180 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
22700000190 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
228000001a0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
229000001b0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
230000001c0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
231000001d0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
232000001e0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
233000001f0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
23400000200 35 32 20 63 6f 6d 6d 65 6e 74 3d 62 31 30 35 30 |52 comment=b1050|
23500000210 32 62 32 32 61 31 32 30 39 64 36 62 34 37 36 33 |2b22a1209d6b4763|
23600000220 39 64 38 38 62 38 31 32 62 32 31 66 62 35 39 34 |9d88b812b21fb594|
23700000230 39 65 34 0a 00 00 00 00 00 00 00 00 00 00 00 00 |9e4.............|
23800000240 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
239...
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-17 00:29:12 +0000