Debian Codegraph @

upstream/opensuse-tumbleweed/man1/zipdetails.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "ZIPDETAILS 1"
61 .TH ZIPDETAILS 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 zipdetails \- display the internal structure of zip files
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& zipdetails [options] zipfile.zip
72 .Ve
73 .SH DESCRIPTION
74 .IX Header "DESCRIPTION"
75 This program creates a detailed report on the internal structure of zip
76 files. For each item of metadata within a zip file the program will output
77 .IP "the offset into the zip file where the item is located." 5
78 .IX Item "the offset into the zip file where the item is located."
79 .PD 0
80 .IP "a textual representation for the item." 5
81 .IX Item "a textual representation for the item."
82 .IP "an optional hex dump of the item." 5
83 .IX Item "an optional hex dump of the item."
84 .PD
85 .PP
86 The program assumes a prior understanding of the internal structure of Zip
87 files. You should have a copy of the zip file definition,
88 APPNOTE.TXT <https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT>,
89 at hand to help understand the output from this program.
90 .SS "Default Behaviour"
91 .IX Subsection "Default Behaviour"
92 By default the program expects to be given a well\-formed zip file. It will
93 navigate the zip file by first parsing the zip \f(CW\*(C`Central Directory\*(C'\fR at the end
94 of the file. If the \f(CW\*(C`Central Directory\*(C'\fR is found, it will then walk
95 sequentally through the zip records starting at the beginning of the file.
96 See "Advanced Analysis" for other processing options.
97 .PP
98 If the program finds any structural or portability issues with the zip file
99 it will print a message at the point it finds the issue and/or in a summary
100 at the end of the output report. Whilst the set of issues that can be
101 detected it exhaustive, don\*(Aqt assume that this program can find \fIall\fR the
102 possible issues in a zip file \- there are likely edge conditions that need
103 to be addressed.
104 .PP
105 If you have suggestions for use\-cases where this could be enhanced please
106 consider creating an enhancement request (see "SUPPORT").
107 .PP
108 \fIDate & Time fields\fR
109 .IX Subsection "Date & Time fields"
110 .PP
111 Date/time fields found in zip files are displayed in local time. Use the
112 \&\f(CW\*(C`\-\-utc\*(C'\fR option to display these fields in Coordinated Universal Time (UTC).
113 .PP
114 \fIFilenames & Comments\fR
115 .IX Subsection "Filenames & Comments"
116 .PP
117 Filenames and comments are decoded/encoded using the default system
118 encoding of the host running \f(CW\*(C`zipdetails\*(C'\fR. When the sytem encoding cannot
119 be determined \f(CW\*(C`cp437\*(C'\fR will be used.
120 .PP
121 The exceptions are
122 .IP \(bu 5
123 when the \f(CW\*(C`Language Encoding Flag\*(C'\fR is set in the zip file, the
124 filename/comment fields are assumed to be encoded in UTF\-8.
125 .IP \(bu 5
126 the definition for the metadata field implies UTF\-8 charset encoding
127 .PP
128 See "Filename Encoding Issues" and "Filename & Comment Encoding
129 Options" for ways to control the encoding of filename/comment fields.
130 .SS OPTIONS
131 .IX Subsection "OPTIONS"
132 \fIGeneral Options\fR
133 .IX Subsection "General Options"
134 .ie n .IP """\-h"", ""\-\-help""" 5
135 .el .IP "\f(CW\-h\fR, \f(CW\-\-help\fR" 5
136 .IX Item "-h, --help"
137 Display help
138 .ie n .IP """\-\-redact""" 5
139 .el .IP \f(CW\-\-redact\fR 5
140 .IX Item "--redact"
141 Obscure filenames and payload data in the output. Handy for the use case
142 where the zip files contains sensitive data that cannot be shared.
143 .ie n .IP """\-\-scan""" 5
144 .el .IP \f(CW\-\-scan\fR 5
145 .IX Item "--scan"
146 Pessimistically scan the zip file loking for possible zip records. Can be
147 error\-prone. For very large zip files this option is slow. Consider using
148 the \f(CW\*(C`\-\-walk\*(C'\fR option first. See "Advanced Analysis Options"
149 .ie n .IP """\-\-utc""" 5
150 .el .IP \f(CW\-\-utc\fR 5
151 .IX Item "--utc"
152 By default, date/time fields are displayed in local time. Use this option to
153 display them in in Coordinated Universal Time (UTC).
154 .ie n .IP """\-v""" 5
155 .el .IP \f(CW\-v\fR 5
156 .IX Item "-v"
157 Enable Verbose mode. See "Verbose Output".
158 .ie n .IP """\-\-version""" 5
159 .el .IP \f(CW\-\-version\fR 5
160 .IX Item "--version"
161 Display version number of the program and exit.
162 .ie n .IP """\-\-walk""" 5
163 .el .IP \f(CW\-\-walk\fR 5
164 .IX Item "--walk"
165 Optimistically walk the zip file looking for possible zip records.
166 See "Advanced Analysis Options"
167 .PP
168 \fIFilename & Comment Encoding Options\fR
169 .IX Subsection "Filename & Comment Encoding Options"
170 .PP
171 See "Filename Encoding Issues"
172 .ie n .IP """\-\-encoding name""" 5
173 .el .IP "\f(CW\-\-encoding name\fR" 5
174 .IX Item "--encoding name"
175 Use encoding "name" when reading filenames/comments from the zip file.
176 .Sp
177 When this option is not specified the default the system encoding is used.
178 .ie n .IP """ \-\-no\-encoding""" 5
179 .el .IP "\f(CW \-\-no\-encoding\fR" 5
180 .IX Item " --no-encoding"
181 Disable all filename & comment encoding/decoding. Filenames/comments are
182 processed as byte streams.
183 .Sp
184 This option is not enabled by default.
185 .ie n .IP """\-\-output\-encoding name""" 5
186 .el .IP "\f(CW\-\-output\-encoding name\fR" 5
187 .IX Item "--output-encoding name"
188 Use encoding "name" when writing filename/comments to the display. By
189 default the system encoding will be used.
190 .ie n .IP """\-\-language\-encoding"", ""\-\-no\-language\-encoding""" 5
191 .el .IP "\f(CW\-\-language\-encoding\fR, \f(CW\-\-no\-language\-encoding\fR" 5
192 .IX Item "--language-encoding, --no-language-encoding"
193 Modern zip files set a metadata entry in zip files, called the "Language
194 encoding flag", when they write filenames/comments encoded in UTF\-8.
195 .Sp
196 Occasionally some applications set the \f(CW\*(C`Language Encoding Flag\*(C'\fR but write
197 data that is not UTF\-8 in the filename/comment fields of the zip file. This
198 will usually result in garbled text being output for the
199 filenames/comments.
200 .Sp
201 To deal with this use\-case, set the \f(CW\*(C`\-\-no\-language\-encoding\*(C'\fR option and,
202 if needed, set the \f(CW\*(C`\-\-encoding name\*(C'\fR option to encoding actually used.
203 .Sp
204 Default is \f(CW\*(C`\-\-language\-encoding\*(C'\fR.
205 .ie n .IP """\-\-debug\-encoding""" 5
206 .el .IP \f(CW\-\-debug\-encoding\fR 5
207 .IX Item "--debug-encoding"
208 Display extra debugging info when a filename/comment encoding has changed.
209 .PP
210 \fIMessage Control Options\fR
211 .IX Subsection "Message Control Options"
212 .ie n .IP """\-\-messages"", ""\-\-no\-messages""" 5
213 .el .IP "\f(CW\-\-messages\fR, \f(CW\-\-no\-messages\fR" 5
214 .IX Item "--messages, --no-messages"
215 Enable/disable the output of all info/warning/error messages.
216 .Sp
217 Disabling messages means that no checks are carried out to check that the
218 zip file is well\-formed.
219 .Sp
220 Default is enabled.
221 .ie n .IP """\-\-exit\-bitmask"", ""\-\-no\-exit\-bitmask""" 5
222 .el .IP "\f(CW\-\-exit\-bitmask\fR, \f(CW\-\-no\-exit\-bitmask\fR" 5
223 .IX Item "--exit-bitmask, --no-exit-bitmask"
224 Enable/disable exit status bitmask for messages. Default disabled.
225 Bitmask values are: 1 for info, 2 for warning and 4 for error.
226 .SS "Default Output"
227 .IX Subsection "Default Output"
228 By default \f(CW\*(C`zipdetails\*(C'\fR will output each metadata field from the zip file
229 in three columns.
230 .IP 1. 5
231 The offset, in hex, to the start of the field relative to the beginning of
232 the file.
233 .IP 2. 5
234 The name of the field.
235 .IP 3. 5
236 Detailed information about the contents of the field. The format depends on
237 the type of data:
238 .RS 5
239 .IP \(bu 5
240 Numeric Values
241 .Sp
242 If the field contains an 8\-bit, 16\-bit, 32\-bit or 64\-bit numeric value, it
243 will be displayed in both hex and decimal \-\- for example "\f(CW\*(C`002A (42)\*(C'\fR".
244 .Sp
245 Note that Zip files store most numeric values in \fIlittle\-endian\fR encoding
246 (there area few rare instances where \fIbig\-endian\fR is used). The value read
247 from the zip file will have the \fIendian\fR encoding removed before being
248 displayed.
249 .Sp
250 Next, is an optional description of what the numeric value means.
251 .IP \(bu 5
252 String
253 .Sp
254 If the field corresponds to a printable string, it will be output enclosed
255 in single quotes.
256 .IP \(bu 5
257 Binary Data
258 .Sp
259 The term \fIBinary Data\fR is just a catch\-all for all other metadata in the
260 zip file. This data is displayed as a series of ascii\-hex byte values in
261 the same order they are stored in the zip file.
262 .RE
263 .RS 5
264 .RE
265 .PP
266 For example, assuming you have a zip file, \f(CW\*(C`test,zip\*(C'\fR, with one entry
267 .PP
268 .Vb 7
269 \& $ unzip \-l test.zip
270 \& Archive: test.zip
271 \& Length Date Time Name
272 \& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\- \-\-\-\-
273 \& 446 2023\-03\-22 20:03 lorem.txt
274 \& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
275 \& 446 1 file
276 .Ve
277 .PP
278 Running \f(CW\*(C`zipdetails\*(C'\fR will gives this output
279 .PP
280 .Vb 1
281 \& $ zipdetails test.zip
282 \&
283 \& 0000 LOCAL HEADER #1 04034B50 (67324752)
284 \& 0004 Extract Zip Spec 14 (20) \*(Aq2.0\*(Aq
285 \& 0005 Extract OS 00 (0) \*(AqMS\-DOS\*(Aq
286 \& 0006 General Purpose Flag 0000 (0)
287 \& [Bits 1\-2] 0 \*(AqNormal Compression\*(Aq
288 \& 0008 Compression Method 0008 (8) \*(AqDeflated\*(Aq
289 \& 000A Modification Time 5676A072 (1450614898) \*(AqWed Mar 22 20:03:36 2023\*(Aq
290 \& 000E CRC F90EE7FF (4178503679)
291 \& 0012 Compressed Size 0000010E (270)
292 \& 0016 Uncompressed Size 000001BE (446)
293 \& 001A Filename Length 0009 (9)
294 \& 001C Extra Length 0000 (0)
295 \& 001E Filename \*(Aqlorem.txt\*(Aq
296 \& 0027 PAYLOAD
297 \&
298 \& 0135 CENTRAL HEADER #1 02014B50 (33639248)
299 \& 0139 Created Zip Spec 1E (30) \*(Aq3.0\*(Aq
300 \& 013A Created OS 03 (3) \*(AqUnix\*(Aq
301 \& 013B Extract Zip Spec 14 (20) \*(Aq2.0\*(Aq
302 \& 013C Extract OS 00 (0) \*(AqMS\-DOS\*(Aq
303 \& 013D General Purpose Flag 0000 (0)
304 \& [Bits 1\-2] 0 \*(AqNormal Compression\*(Aq
305 \& 013F Compression Method 0008 (8) \*(AqDeflated\*(Aq
306 \& 0141 Modification Time 5676A072 (1450614898) \*(AqWed Mar 22 20:03:36 2023\*(Aq
307 \& 0145 CRC F90EE7FF (4178503679)
308 \& 0149 Compressed Size 0000010E (270)
309 \& 014D Uncompressed Size 000001BE (446)
310 \& 0151 Filename Length 0009 (9)
311 \& 0153 Extra Length 0000 (0)
312 \& 0155 Comment Length 0000 (0)
313 \& 0157 Disk Start 0000 (0)
314 \& 0159 Int File Attributes 0001 (1)
315 \& [Bit 0] 1 \*(AqText Data\*(Aq
316 \& 015B Ext File Attributes 81ED0000 (2179792896)
317 \& [Bits 16\-24] 01ED (493) \*(AqUnix attrib: rwxr\-xr\-x\*(Aq
318 \& [Bits 28\-31] 08 (8) \*(AqRegular File\*(Aq
319 \& 015F Local Header Offset 00000000 (0)
320 \& 0163 Filename \*(Aqlorem.txt\*(Aq
321 \&
322 \& 016C END CENTRAL HEADER 06054B50 (101010256)
323 \& 0170 Number of this disk 0000 (0)
324 \& 0172 Central Dir Disk no 0000 (0)
325 \& 0174 Entries in this disk 0001 (1)
326 \& 0176 Total Entries 0001 (1)
327 \& 0178 Size of Central Dir 00000037 (55)
328 \& 017C Offset to Central Dir 00000135 (309)
329 \& 0180 Comment Length 0000 (0)
330 \& #
331 \& # Done
332 .Ve
333 .SS "Verbose Output"
334 .IX Subsection "Verbose Output"
335 If the \f(CW\*(C`\-v\*(C'\fR option is present, the metadata output is split into the
336 following columns:
337 .IP 1. 5
338 The offset, in hex, to the start of the field relative to the beginning of
339 the file.
340 .IP 2. 5
341 The offset, in hex, to the end of the field relative to the beginning of
342 the file.
343 .IP 3. 5
344 The length, in hex, of the field.
345 .IP 4. 5
346 A hex dump of the bytes in field in the order they are stored in the zip file.
347 .IP 5. 5
348 A textual description of the field.
349 .IP 6. 5
350 Information about the contents of the field. See the description in the
351 "Default Output" for more details.
352 .PP
353 Here is the same zip file, \f(CW\*(C`test.zip\*(C'\fR, dumped using the \f(CW\*(C`zipdetails\*(C'\fR
354 \&\f(CW\*(C`\-v\*(C'\fR option:
355 .PP
356 .Vb 1
357 \& $ zipdetails \-v test.zip
358 \&
359 \& 0000 0003 0004 50 4B 03 04 LOCAL HEADER #1 04034B50 (67324752)
360 \& 0004 0004 0001 14 Extract Zip Spec 14 (20) \*(Aq2.0\*(Aq
361 \& 0005 0005 0001 00 Extract OS 00 (0) \*(AqMS\-DOS\*(Aq
362 \& 0006 0007 0002 00 00 General Purpose Flag 0000 (0)
363 \& [Bits 1\-2] 0 \*(AqNormal Compression\*(Aq
364 \& 0008 0009 0002 08 00 Compression Method 0008 (8) \*(AqDeflated\*(Aq
365 \& 000A 000D 0004 72 A0 76 56 Modification Time 5676A072 (1450614898) \*(AqWed Mar 22 20:03:36 2023\*(Aq
366 \& 000E 0011 0004 FF E7 0E F9 CRC F90EE7FF (4178503679)
367 \& 0012 0015 0004 0E 01 00 00 Compressed Size 0000010E (270)
368 \& 0016 0019 0004 BE 01 00 00 Uncompressed Size 000001BE (446)
369 \& 001A 001B 0002 09 00 Filename Length 0009 (9)
370 \& 001C 001D 0002 00 00 Extra Length 0000 (0)
371 \& 001E 0026 0009 6C 6F 72 65 Filename \*(Aqlorem.txt\*(Aq
372 \& 6D 2E 74 78
373 \& 74
374 \& 0027 0134 010E ... PAYLOAD
375 \&
376 \& 0135 0138 0004 50 4B 01 02 CENTRAL HEADER #1 02014B50 (33639248)
377 \& 0139 0139 0001 1E Created Zip Spec 1E (30) \*(Aq3.0\*(Aq
378 \& 013A 013A 0001 03 Created OS 03 (3) \*(AqUnix\*(Aq
379 \& 013B 013B 0001 14 Extract Zip Spec 14 (20) \*(Aq2.0\*(Aq
380 \& 013C 013C 0001 00 Extract OS 00 (0) \*(AqMS\-DOS\*(Aq
381 \& 013D 013E 0002 00 00 General Purpose Flag 0000 (0)
382 \& [Bits 1\-2] 0 \*(AqNormal Compression\*(Aq
383 \& 013F 0140 0002 08 00 Compression Method 0008 (8) \*(AqDeflated\*(Aq
384 \& 0141 0144 0004 72 A0 76 56 Modification Time 5676A072 (1450614898) \*(AqWed Mar 22 20:03:36 2023\*(Aq
385 \& 0145 0148 0004 FF E7 0E F9 CRC F90EE7FF (4178503679)
386 \& 0149 014C 0004 0E 01 00 00 Compressed Size 0000010E (270)
387 \& 014D 0150 0004 BE 01 00 00 Uncompressed Size 000001BE (446)
388 \& 0151 0152 0002 09 00 Filename Length 0009 (9)
389 \& 0153 0154 0002 00 00 Extra Length 0000 (0)
390 \& 0155 0156 0002 00 00 Comment Length 0000 (0)
391 \& 0157 0158 0002 00 00 Disk Start 0000 (0)
392 \& 0159 015A 0002 01 00 Int File Attributes 0001 (1)
393 \& [Bit 0] 1 \*(AqText Data\*(Aq
394 \& 015B 015E 0004 00 00 ED 81 Ext File Attributes 81ED0000 (2179792896)
395 \& [Bits 16\-24] 01ED (493) \*(AqUnix attrib: rwxr\-xr\-x\*(Aq
396 \& [Bits 28\-31] 08 (8) \*(AqRegular File\*(Aq
397 \& 015F 0162 0004 00 00 00 00 Local Header Offset 00000000 (0)
398 \& 0163 016B 0009 6C 6F 72 65 Filename \*(Aqlorem.txt\*(Aq
399 \& 6D 2E 74 78
400 \& 74
401 \&
402 \& 016C 016F 0004 50 4B 05 06 END CENTRAL HEADER 06054B50 (101010256)
403 \& 0170 0171 0002 00 00 Number of this disk 0000 (0)
404 \& 0172 0173 0002 00 00 Central Dir Disk no 0000 (0)
405 \& 0174 0175 0002 01 00 Entries in this disk 0001 (1)
406 \& 0176 0177 0002 01 00 Total Entries 0001 (1)
407 \& 0178 017B 0004 37 00 00 00 Size of Central Dir 00000037 (55)
408 \& 017C 017F 0004 35 01 00 00 Offset to Central Dir 00000135 (309)
409 \& 0180 0181 0002 00 00 Comment Length 0000 (0)
410 \& #
411 \& # Done
412 .Ve
413 .SS "Advanced Analysis"
414 .IX Subsection "Advanced Analysis"
415 If you have a corrupt or non\-standard zip file, particulatly one where the
416 \&\f(CW\*(C`Central Directory\*(C'\fR metadata at the end of the file is absent/incomplete, you
417 can use either the \f(CW\*(C`\-\-walk\*(C'\fR option or the \f(CW\*(C`\-\-scan\*(C'\fR option to search for
418 any zip metadata that is still present in the file.
419 .PP
420 When either of these options is enabled, this program will bypass the
421 initial step of reading the \f(CW\*(C`Central Directory\*(C'\fR at the end of the file and
422 simply scan the zip file sequentially from the start of the file looking
423 for zip metedata records. Although this can be error prone, for the most
424 part it will find any zip file metadata that is still present in the file.
425 .PP
426 The difference between the two options is how aggressive the sequential
427 scan is: \f(CW\*(C`\-\-walk\*(C'\fR is optimistic, while \f(CW\*(C`\-\-scan\*(C'\fR is pessimistic.
428 .PP
429 To understand the difference in more detail you need to know a bit about
430 how zip file metadata is structured. Under the hood, a zip file uses a
431 series of 4\-byte signatures to flag the start of a each of the metadata
432 records it uses. When the \f(CW\*(C`\-\-walk\*(C'\fR or the \f(CW\*(C`\-\-scan\*(C'\fR option is enabled both
433 work identically by scanning the file from the beginning looking for any
434 the of these valid 4\-byte metadata signatures. When a 4\-byte signature is
435 found both options will blindly assume that it has found a vald metadata
436 record and display it.
437 .PP
438 \fR\f(CI\*(C`\-\-walk\*(C'\fR\fI\fR
439 .IX Subsection "--walk"
440 .PP
441 The \f(CW\*(C`\-\-walk\*(C'\fR option optimistically assumes that it has found a real zip
442 metatada record and so starts the scan for the next record directly after
443 the record it has just output.
444 .PP
445 \fR\f(CI\*(C`\-\-scan\*(C'\fR\fI\fR
446 .IX Subsection "--scan"
447 .PP
448 The \f(CW\*(C`\-\-scan\*(C'\fR option is pessimistic and assumes the 4\-byte signature
449 sequence may have been a false\-positive, so before starting the scan for
450 the next resord, it will rewind to the location in the file directly after
451 the 4\-byte sequecce it just processed. This means it will rescan data that
452 has already been processed. For very lage zip files the \f(CW\*(C`\-\-scan\*(C'\fR option
453 can be really realy slow, so trying the \f(CW\*(C`\-\-walk\*(C'\fR option first.
454 .PP
455 \&\fBImportant Note\fR: If the zip file being processed contains one or more
456 nested zip files, and the outer zip file uses the \f(CW\*(C`STORE\*(C'\fR compression
457 method, the \f(CW\*(C`\-\-scan\*(C'\fR option will display the zip metadata for both the
458 outer & inner zip files.
459 .SS "Filename Encoding Issues"
460 .IX Subsection "Filename Encoding Issues"
461 Sometimes when displaying the contents of a zip file the filenames (or
462 comments) appear to be garbled. This section walks through the reasons and
463 mitigations that can be applied to work around these issues.
464 .PP
465 \fIBackground\fR
466 .IX Subsection "Background"
467 .PP
468 When zip files were first created in the 1980\*(Aqs, there was no Unicode or
469 UTF\-8. Issues around character set encoding interoperability were not a
470 major concern.
471 .PP
472 Initially, the only official encoding supported in zip files was IBM Code
473 Page 437 (AKA \f(CW\*(C`CP437\*(C'\fR). As time went on users in locales where \f(CW\*(C`CP437\*(C'\fR
474 wasn\*(Aqt appropriate stored filenames in the encoding native to their locale.
475 If you were running a system that matched the locale of the zip file, all
476 was well. If not, you had to post\-process the filenames after unzipping the
477 zip file.
478 .PP
479 Fast forward to the introduction of Unicode and UTF\-8 encoding. The
480 approach now used by all major zip implementations is to set the \f(CW\*(C`Language
481 encoding flag\*(C'\fR (also known as \f(CW\*(C`EFS\*(C'\fR) in the zip file metadata to signal
482 that a filename/comment is encoded in UTF\-8.
483 .PP
484 To ensure maximum interoperability when sharing zip files store 7\-bit
485 filenames as\-is in the zip file. For anything else the \f(CW\*(C`EFS\*(C'\fR bit needs to
486 be set and the filename is encoded in UTF\-8. Although this rule is kept to
487 for the most part, there are exceptions out in the wild.
488 .PP
489 \fIDealing with Encoding Errors\fR
490 .IX Subsection "Dealing with Encoding Errors"
491 .PP
492 The most common filename encoding issue is where the \f(CW\*(C`EFS\*(C'\fR bit is not set and
493 the filename is stored in a character set that doesnt\*(Aqt match the system
494 encoding. This mostly impacts legacy zip files that predate the
495 introduction of Unicode.
496 .PP
497 To deal with this issue you first need to know what encoding was used in
498 the zip file. For example, if the filename is encoded in \f(CW\*(C`ISO\-8859\-1\*(C'\fR you
499 can display the filenames using the \f(CW\*(C`\-\-encoding\*(C'\fR option
500 .PP
501 .Vb 1
502 \& zipdetails \-\-encoding ISO\-8859\-1 myfile.zip
503 .Ve
504 .PP
505 A less common variation of this is where the \f(CW\*(C`EFS\*(C'\fR bit is set, signalling
506 that the filename will be encoded in UTF\-8, but the filename is not encoded
507 in UTF\-8. To deal with this scenarion, use the \f(CW\*(C`\-\-no\-language\-encoding\*(C'\fR
508 option along with the \f(CW\*(C`\-\-encoding\*(C'\fR option.
509 .SH LIMITATIONS
510 .IX Header "LIMITATIONS"
511 The following zip file features are not supported by this program:
512 .IP \(bu 5
513 Multi\-part/Split/Spanned Zip Archives.
514 .Sp
515 This program cannot give an overall report on the combined parts of a
516 multi\-part zip file.
517 .Sp
518 The best you can do is run with either the \f(CW\*(C`\-\-scan\*(C'\fR or \f(CW\*(C`\-\-walk\*(C'\fR options
519 against individual parts. Some will contains zipfile metadata which will be
520 detected and some will only contain compressed payload data.
521 .IP \(bu 5
522 Encrypted Central Directory
523 .Sp
524 When pkzip \fIStrong Encryption\fR is enabled in a zip file this program can
525 still parse most of the metadata in the zip file. The exception is when the
526 \&\f(CW\*(C`Central Directory\*(C'\fR of a zip file is also encrypted. This program cannot
527 parse any metadata from an encrypted \f(CW\*(C`Central Directory\*(C'\fR.
528 .IP \(bu 5
529 Corrupt Zip files
530 .Sp
531 When \f(CW\*(C`zipdetails\*(C'\fR encounters a corrupt zip file, it will do one or more of
532 the following
533 .RS 5
534 .IP \(bu 5
535 Display details of the corruption and carry on
536 .IP \(bu 5
537 Display details of the corruption and terminate
538 .IP \(bu 5
539 Terminate with a generic message
540 .RE
541 .RS 5
542 .Sp
543 Which of the above is output is dependent in the severity of the
544 corruption.
545 .RE
546 .SH TODO
547 .IX Header "TODO"
548 .SS "JSON/YML Output"
549 .IX Subsection "JSON/YML Output"
550 Output some of the zip file metadata as a JSON or YML document.
551 .SS "Corrupt Zip files"
552 .IX Subsection "Corrupt Zip files"
553 Although the detection and reporting of most of the common corruption use\-cases is
554 present in \f(CW\*(C`zipdetails\*(C'\fR, there are likely to be other edge cases that need
555 to be supported.
556 .PP
557 If you have a corrupt Zip file that isn\*(Aqt being processed properly, please
558 report it (see "SUPPORT").
559 .SH SUPPORT
560 .IX Header "SUPPORT"
561 General feedback/questions/bug reports should be sent to
562 <https://github.com/pmqs/zipdetails/issues>.
563 .SH "SEE ALSO"
564 .IX Header "SEE ALSO"
565 The primary reference for Zip files is
566 APPNOTE.TXT <https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT>.
567 .PP
568 An alternative reference is the Info\-Zip appnote. This is available from
569 <ftp://ftp.info\-zip.org/pub/infozip/doc/>
570 .PP
571 For details of WinZip AES encryption see AES Encryption Information:
572 Encryption Specification AE\-1 and
573 AE\-2 <https://www.winzip.com/en/support/aes-encryption/>.
574 .PP
575 The \f(CW\*(C`zipinfo\*(C'\fR program that comes with the info\-zip distribution
576 (<http://www.info\-zip.org/>) can also display details of the structure of a zip
577 file.
578 .SH AUTHOR
579 .IX Header "AUTHOR"
580 Paul Marquess \[email protected]\fR.
581 .SH COPYRIGHT
582 .IX Header "COPYRIGHT"
583 Copyright (c) 2011\-2024 Paul Marquess. All rights reserved.
584 .PP
585 This program is free software; you can redistribute it and/or modify it under
586 the same terms as Perl itself.