ZIPDETAILS(1perl)

okay bestie, sit down, hydrate, and let's talk about ZIPDETAILS(1perl) — that's zipdetails from the Perl Programmers Reference Guide ✨ this little icon opens up a zip file like it's a group chat and reads every message out loud 💅

🎀 NAME 🎀

zipdetails — display the internal structure of zip files 🦋

---

✨ SYNOPSIS ✨

zipdetails [options] zipfile.zip

---

💖 DESCRIPTION 💖

No cap, this program writes you a whole detailed report on what's actually inside a zip file. For every single item of metadata in there, it prints out:

• the offset into the zip file where that item lives 📍
• a text version of the item, so you can actually read it
• optionally, a hex dump of the item, for the girlies who want the raw tea 👀

Heads up: this program assumes you already vibe with how zip files are structured internally. Like, you really should have a copy of the zip file definition, APPNOTE.TXT (https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT), on hand so the output actually makes sense to you. It's giving homework but it's worth it 🫶

🌸 Default Behaviour 🌸

By default this program is expecting a well-formed zip file. It navigates the file by first parsing the zip "Central Directory" sitting at the end of the file. Once it finds that "Central Directory", it walks sequentially through the zip records starting from the very beginning of the file. If you want other ways to process stuff, go peek at "Advanced Analysis" 💫

If the program spots any structural or portability issues with your zip file, it prints a message right at the point it finds the issue, and/or in a summary at the end of the output report. And listen — even though the set of issues that can be detected is exhaustive, do not assume this program can find all the possible issues in a zip file. There are likely edge conditions out there that still need to be addressed, fr fr 😭

If you have suggestions for use-cases where this could be enhanced, pls consider creating an enhancement request (see "SUPPORT") 💌

🕰️ Date & Time fields

Date/time fields found in zip files are displayed in local time. Use the --utc option if you want them shown in Coordinated Universal Time (UTC) 🌍

🏷️ Filenames & Comments

Filenames and comments get decoded/encoded using the default system encoding of the host that's running zipdetails. When the system encoding just can't be determined, cp437 is used as the fallback.

The exceptions to all that are:

• when the "Language Encoding Flag" is set in the zip file, the filename/comment fields are assumed to be encoded in UTF-8.
• the definition for the metadata field implies UTF-8 charset encoding.

See "Filename Encoding Issues" and "Filename & Comment Encoding Options" for the ways you can control the encoding of filename/comment fields 💅

🌈 OPTIONS 🌈

✨ General Options

• -h, --help — Display help.
• --redact — Obscure filenames and payload data in the output. So handy for the use case where the zip file contains sensitive data that literally cannot be shared 🙈
• --scan — Pessimistically scan the zip file looking for possible zip records. Can be error-prone. For very large zip files this option is slow. Consider using the --walk option first. See "Advanced Analysis Options".
• --utc — By default, date/time fields are displayed in local time. Use this option to display them in Coordinated Universal Time (UTC).
• -v — Enable Verbose mode. See "Verbose Output".
• --version — Display version number of the program and exit.
• --walk — Optimistically walk the zip file looking for possible zip records. See "Advanced Analysis Options".

🎀 Filename & Comment Encoding Options 🎀

See "Filename Encoding Issues".

• --encoding name — Use encoding name when reading filenames/comments from the zip file. When this option is not specified, the default is the system encoding.
• --no-encoding — Disable all filename & comment encoding/decoding. Filenames/comments are processed as byte streams. This option is not enabled by default.
• --output-encoding name — Use encoding name when writing filenames/comments to the display. By default the system encoding will be used.
• --language-encoding, --no-language-encoding — Modern zip files set a metadata entry in zip files, called the "Language encoding flag", when they write filenames/comments encoded in UTF-8. Occasionally some applications set the "Language Encoding Flag" but then write data that is not UTF-8 into the filename/comment fields of the zip file. This will usually result in garbled text being output for the filenames/comments 😵‍💫 To deal with this use-case, set the --no-language-encoding option and, if needed, set the --encoding name option to the encoding actually used. Default is --language-encoding.
• --debug-encoding — Display extra debugging info when a filename/comment encoding has changed.

💬 Message Control Options 💬

• --messages, --no-messages — Enable/disable the output of all info/warning/error messages. Disabling messages means that no checks are carried out to check that the zip file is well-formed. Default is enabled.
• --exit-bitmask, --no-exit-bitmask — Enable/disable exit status bitmask for messages. Default disabled. Bitmask values are: 1 for info, 2 for warning and 4 for error.

💅 Default Output 💅

By default zipdetails will output each metadata field from the zip file in three columns.

1. The offset, in hex, to the start of the field relative to the beginning of the file.
2. The name of the field.
3. Detailed information about the contents of the field. The format depends on the type of data:
   • Numeric Values — If the field contains an 8-bit, 16-bit, 32-bit or 64-bit numeric value, it will be displayed in both hex and decimal — for example "002A (42)". Note that zip files store most numeric values in little-endian encoding (there are a few rare instances where big-endian is used). The value read from the zip file will have the endian encoding removed before being displayed. Next, there's an optional description of what the numeric value means.
   • String — If the field corresponds to a printable string, it will be output enclosed in single quotes.
   • Binary Data — The term Binary Data is just a catch-all for all other metadata in the zip file. This data is displayed as a series of ascii-hex byte values in the same order they are stored in the zip file.

For example, assuming you have a zip file, test.zip, with one entry:

$ unzip -l  test.zip
Archive:  test.zip
Length      Date    Time    Name
---------  ---------- -----   ----
    446  2023-03-22 20:03   lorem.txt
---------                     -------
    446                     1 file

Running zipdetails will give this output:

$ zipdetails test.zip

0000 LOCAL HEADER #1       04034B50 (67324752)
0004 Extract Zip Spec      14 (20) '2.0'
0005 Extract OS            00 (0) 'MS-DOS'
0006 General Purpose Flag  0000 (0)
    [Bits 1-2]            0 'Normal Compression'
0008 Compression Method    0008 (8) 'Deflated'
000A Modification Time     5676A072 (1450614898) 'Wed Mar 22 20:03:36 2023'
000E CRC                   F90EE7FF (4178503679)
0012 Compressed Size       0000010E (270)
0016 Uncompressed Size     000001BE (446)
001A Filename Length       0009 (9)
001C Extra Length          0000 (0)
001E Filename              'lorem.txt'
0027 PAYLOAD

0135 CENTRAL HEADER #1     02014B50 (33639248)
0139 Created Zip Spec      1E (30) '3.0'
013A Created OS            03 (3) 'Unix'
013B Extract Zip Spec      14 (20) '2.0'
013C Extract OS            00 (0) 'MS-DOS'
013D General Purpose Flag  0000 (0)
    [Bits 1-2]            0 'Normal Compression'
013F Compression Method    0008 (8) 'Deflated'
0141 Modification Time     5676A072 (1450614898) 'Wed Mar 22 20:03:36 2023'
0145 CRC                   F90EE7FF (4178503679)
0149 Compressed Size       0000010E (270)
014D Uncompressed Size     000001BE (446)
0151 Filename Length       0009 (9)
0153 Extra Length          0000 (0)
0155 Comment Length        0000 (0)
0157 Disk Start            0000 (0)
0159 Int File Attributes   0001 (1)
    [Bit 0]               1 'Text Data'
015B Ext File Attributes   81ED0000 (2179792896)
    [Bits 16-24]          01ED (493) 'Unix attrib: rwxr-xr-x'
    [Bits 28-31]          08 (8) 'Regular File'
015F Local Header Offset   00000000 (0)
0163 Filename              'lorem.txt'

016C END CENTRAL HEADER    06054B50 (101010256)
0170 Number of this disk   0000 (0)
0172 Central Dir Disk no   0000 (0)
0174 Entries in this disk  0001 (1)
0176 Total Entries         0001 (1)
0178 Size of Central Dir   00000037 (55)
017C Offset to Central Dir 00000135 (309)
0180 Comment Length        0000 (0)
#
# Done

🔥 Verbose Output 🔥

If the -v option is present, the metadata output gets split into these columns:

1. The offset, in hex, to the start of the field relative to the beginning of the file.
2. The offset, in hex, to the end of the field relative to the beginning of the file.
3. The length, in hex, of the field.
4. A hex dump of the bytes in the field, in the order they are stored in the zip file.
5. A textual description of the field.
6. Information about the contents of the field. See the description in the "Default Output" for more details.

Here's that same zip file, test.zip, dumped using the zipdetails -v option:

$ zipdetails -v test.zip

0135 0138 0004 50 4B 01 02 CENTRAL HEADER #1 02014B50 (33639248) 0139 0139 0001 1E Created Zip Spec 1E (30) '3.0' 013A 013A 0001 03 Created OS 03 (3) 'Unix' 013B 013B 0001 14 Extract Zip Spec 14 (20) '2.0' 013C 013C 0001 00 Extract OS 00 (0) 'MS-DOS' 013D 013E 0002 00 00 General Purpose Flag 0000 (0) [Bits 1-2] 0 'Normal Compression' 013F 0140 0002 08 00 Compression Method 0008 (8) 'Deflated' 0141 0144 0004 72 A0 76 56 Modification Time 5676A072 (1450614898) 'Wed Mar 22 20:03:36 2023' 0145 0148 0004 FF E7 0E F9 CRC F90EE7FF (4178503679) 0149 014C 0004 0E 01 00 00 Compressed Size 0000010E (270) 014D 0150 0004 BE 01 00 00 Uncompressed Size 000001BE (446) 0151 0152 0002 09 00 Filename Length 0009 (9) 0153 0154 0002 00 00 Extra Length 0000 (0) 0155 0156 0002 00 00 Comment Length 0000 (0) 0157 0158 0002 00 00 Disk Start 0000 (0) 0159 015A 0002 01 00 Int File Attributes 0001 (1) [Bit 0] 1 'Text Data' 015B 015E 0004 00 00 ED 81 Ext File Attributes 81ED0000 (2179792896) [Bits 16-24] 01ED (493) 'Unix attrib: rwxr-xr-x' [Bits 28-31] 08 (8) 'Regular File' 015F 0162 0004 00 00 00 00 Local Header Offset 00000000 (0) 0163 016B 0009 6C 6F 72 65 Filename 'lorem.txt' 6D 2E 74 78 74

016C 016F 0004 50 4B 05 06 END CENTRAL HEADER 06054B50 (101010256) 0170 0171 0002 00 00 Number of this disk 0000 (0) 0172 0173 0002 00 00 Central Dir Disk no 0000 (0) 0174 0175 0002 01 00 Entries in this disk 0001 (1) 0176 0177 0002 01 00 Total Entries 0001 (1) 0178 017B 0004 37 00 00 00 Size of Central Dir 00000037 (55) 017C 017F 0004 35 01 00 00 Offset to Central Dir 00000135 (309) 0180 0181 0002 00 00 Comment Length 0000 (0) # # Done

# 🔍 Advanced Analysis

okay so bestie, sometimes a zip file is <red>corrupt</red> or just built different (non-standard), and specifically the "Central Directory" metadata at the end of the file is missing or incomplete 😭. in that case you've got two glow-up options: the `--walk` option or the `--scan` option, and both of them go hunting for any zip metadata still lurking in the file. 🕵️♀️

when either of those is enabled, this program <pink>skips</pink> the whole opening move of reading the "Central Directory" at the end of the file, and instead just scans the zip file sequentially from the very start, looking for zip metadata records. ngl it can be a lil error prone, but for the most part it will find any zip file metadata that's still present. 💅

the difference between the two is literally just how aggressive the sequential scan is: `--walk` is <green>optimistic</green>, while `--scan` is <blue>pessimistic</blue>.

to really get the difference you gotta know a bit about how zip file metadata is structured, so buckle up 🎀. under the hood, a zip file uses a series of <yellow>4-byte signatures</yellow> to flag the start of each of the metadata records it uses. when you turn on `--walk` or `--scan`, both of them work identically — scanning the file from the beginning, looking for any of these valid 4-byte metadata signatures. and when a 4-byte signature is found, both options <hotpink>blindly assume</hotpink> they've found a valid metadata record and display it. 🙈

## 🚶 `--walk`

`--walk` is the optimist ✨ — it assumes it's found a real zip metadata record, so it starts scanning for the next record <pink>directly after the record it just output</pink>.

## 🔎 `--scan`

`--scan` is the pessimist 💀 — it assumes that 4-byte signature sequence might have been a false positive, so before it starts scanning for the next record it <purple>rewinds</purple> to the location in the file directly after the 4-byte sequence it just processed. which means yes, it will rescan data that's already been processed. 😵💫 for very large zip files `--scan` can be *really really* slow, so <yellow>try the `--walk` option first</yellow>.

> <red>Important Note:</red> if the zip file you're processing contains one or more nested zip files, and the outer zip file uses the `STORE` compression method, the `--scan` option will display the zip metadata for <bold>both the outer & inner zip files</bold>. 👑

---

# 🧚 Filename Encoding Issues

sometimes when you're displaying the contents of a zip file, the filenames (or comments) come out looking <red>garbled</red> 😭. this section walks through why that happens and what you can do to work around it. bestie we're going deep.

## 📜 Background

when zip files were first created back in the 1980's, there was <pink>no Unicode</pink>, <pink>no UTF-8</pink>. character set encoding interoperability was simply not a major concern, periodt. 💅

initially, the only official encoding supported in zip files was <yellow>IBM Code Page 437</yellow> (AKA `CP437`). as time went on, users in locales where `CP437` wasn't appropriate stored filenames in the encoding native to their locale. if you were running a system that matched the locale of the zip file, everything was fine and slay ✨. if not, you had to post-process the filenames <purple>after</purple> unzipping the zip file. 😭

fast forward to the introduction of Unicode and UTF-8 encoding 🌈. the approach now used by all major zip implementations is to set the <hotpink>"Language encoding flag"</hotpink> (also known as `EFS`) in the zip file metadata to signal that a filename/comment is encoded in UTF-8.

to ensure maximum interoperability when you're sharing zip files around, store <green>7-bit filenames as-is</green> in the zip file. for anything else, the `EFS` bit needs to be set and the filename is encoded in UTF-8. and yeah, this rule is kept to for the most part... but there are <red>exceptions</red> out there in the wild. 🙈

## 🩹 Dealing with Encoding Errors

the most common filename encoding issue is when the `EFS` bit is <red>not</red> set and the filename is stored in a character set that doesn't match the system encoding. this mostly affects <purple>legacy zip files</purple> that predate the introduction of Unicode. 😔

to deal with this you first need to know what encoding was used in the zip file. for example, if the filename is encoded in `ISO-8859-1` you can display the filenames using the `--encoding` option:

zipdetails --encoding ISO-8859-1 myfile.zip

a <italic>less common</italic> variation of this is when the `EFS` bit <hotpink>is</hotpink> set, signalling that the filename will be encoded in UTF-8, except the filename is *not* actually encoded in UTF-8 😵. to deal with that scenario, use the `--no-language-encoding` option along with the `--encoding` option. 🫶

---

# 🚧 LIMITATIONS

the following zip file features are <red>not supported</red> by this program, bestie. know your limits:

- **Multi-part/Split/Spanned Zip Archives.** <purple>💔</purple>

  this program cannot give an overall report on the combined parts of a multi-part zip file. 😭

  the best you can do is run with either the `--scan` or `--walk` options against individual parts. some will contain zipfile metadata which will be detected, and some will only contain compressed payload data. that's just how it is ngl.

- **Encrypted Central Directory** 🔐

  when pkzip Strong Encryption is enabled in a zip file, this program can still parse most of the metadata in the zip file. the exception is when the "Central Directory" of a zip file is also encrypted. this program <red>cannot parse any metadata</red> from an encrypted "Central Directory". 💀

- **Corrupt Zip files** 🩹

  when `zipdetails` encounters a corrupt zip file, it will do one or more of the following:

  - display details of the corruption and carry on 🚶♀️
  - display details of the corruption and terminate 🛑
  - terminate with a generic message 🤷♀️

  which of the above you get is dependent on the severity of the corruption.

---

# 📝 TODO

the author's got a whole vision board okay, here's what's on deck:

## 🌸 JSON/YML Output

output some of the zip file metadata as a JSON or YML document. (yes please, we love structured data 💅)

## 🩹 Corrupt Zip files

although the detection and reporting of most of the common corruption use-cases is present in `zipdetails`, there are likely to be other <purple>edge cases</purple> that need to be supported.

if you have a corrupt zip file that isn't being processed properly, please report it (see `SUPPORT`). 👑

---

# 🫶 SUPPORT

general feedback, questions and bug reports should be sent to:

`https://github.com/pmqs/zipdetails/issues`

we love a report bestie, don't be shy 🎀

---

# 👀 SEE ALSO

the primary reference for zip files is APPNOTE.TXT at:

`https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT`

if you need to investigate the extra fields that are used in zip files, the `appnote` document covers a lot of them. the Info-ZIP zip distribution, available at `https://infozip.sourceforge.net/`, contains additional extra field definitions — look for the file `extrafld.txt`. 📄

for details of WinZip AES encryption see *AES Encryption Information: Encryption Specification AE-1 and AE-2* at `https://www.winzip.com/en/support/aes-encryption/`. 🔐

the `zipinfo` program that comes with the info-zip distribution (`http://www.info-zip.org/`) can also display details of the structure of a zip file. ✨

---

# 👑 AUTHOR

Paul Marquess `pmqs@cpan.org`.

---

# ©️ COPYRIGHT

Copyright (c) 2011-2026 Paul Marquess. All rights reserved.

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

> <rainbow>and that's a wrap, bestie 💖</rainbow> this whole thing is running under **perl v5.44.0** and it's dated **2026-10-17**, so go forth and read your zips like the main character you are 👑✨🦋 no cap.