minizip-ng Documentation

minizip-ng is a C library for zip manipulation supporting Windows, macOS, and Linux. Key capabilities include:

• Archive Operations: Creating, extracting, adding, and removing entries; reading/writing raw entry data; and memory-based zip operations.
• Compression: Support for Zlib, BZIP2, LZMA, PPMD, XZ, and ZSTD.
• Encryption: Traditional PKWARE and WinZIP AES encryption.
• Advanced ZIP Features: ZIP64 support, disk splitting, NTFS timestamp support, and symbolic link preservation.
• Encoding: Unicode (UTF-8) filename support and legacy encoding (CP437, CP932, CP936, CP950).
• Compatibility: Includes a compatibility layer for consumers of the original minizip library.

You can navigate through the entries in a zip file using mz_zip_reader_goto_first_entry and mz_zip_reader_goto_next_entry. If a pattern was previously set via mz_zip_reader_set_pattern, these functions will skip to the first or next entry matching that pattern.

To iterate through all entries, start with mz_zip_reader_goto_first_entry and loop using mz_zip_reader_goto_next_entry until it returns MZ_END_OF_LIST.

if (mz_zip_reader_goto_first_entry(zip_reader) == MZ_OK) {
    do {
        mz_zip_file *file_info = NULL;
        if (mz_zip_reader_entry_get_info(zip_reader, &file_info) != MZ_OK) {
            printf("Unable to get zip entry info\n");
            break;
        }
        printf("Zip entry %s\n", file_info->filename);
    } while (mz_zip_reader_goto_next_entry(zip_reader) == MZ_OK);
}

minizip-ng can use system-installed libraries or automatically fetch and compile them from their official repositories if the MZ_FETCH_LIBS option is enabled. The following third-party libraries are supported via specific CMake options:

• bzip2: Controlled by MZ_BZIP2
• liblzma: Controlled by MZ_LZMA
• ppmd: Controlled by MZ_PPMD
• zlib (or zlib-ng): Controlled by MZ_ZLIB
• zstd: Controlled by MZ_ZSTD

The Hash extrafield (ID 0x1a51) allows you to store additional hash digests of uncompressed content alongside the standard CRC hash. This is useful for verifying file integrity using stronger algorithms.

When multiple Hash extrafields are present for a single entry, they should be sorted from most secure to least secure. The first Hash extrafield encountered is considered the most secure and should be used for signing purposes.

Structure:

• Algorithm (2 bytes, uint16_t): The hash algorithm used.
• Digest size (2 bytes, uint16_t): The size of the digest.
• Digest (variable, uint8_t*): The actual hash value.

Supported Algorithms:

• 10: MD5
• 20: SHA1
• 23: SHA256

All I/O operations in minizip-ng are performed through streams. You can use different stream types depending on your requirements:

• Memory Stream (mz_stream_mem): Used for reading from or writing to a buffer in memory. Use mz_stream_mem_set_grow_size for growable streams.
• Buffered Stream (mz_stream_buffered): Wraps another stream (like an OS stream) to improve I/O performance by performing buffered read/write operations.
• Disk Splitting Stream (mz_stream_split): Used to create archives split across multiple disks. You must specify a disk size using the MZ_STREAM_PROP_DISK_SIZE property.
• OS Stream (mz_stream_os): Provides standard operating system level file system operations.

The Central Directory extrafield (ID 0xcdcd) is used when a ZIP entry represents the central directory of the archive itself. It provides metadata about the directory structure.

Structure:

• Number of entries (8 bytes, uint64_t): The total number of entries in the central directory.

The version_madeby and external_fa fields relate to the host system and ZIP specification versions:

• Version Made By: The upper byte indicates compatibility of file attribute information, while the lower byte indicates the ZIP specification version supported by the encoding software. Use the macro MZ_HOST_SYSTEM(version_madeby) to retrieve host system information.
• External File Attributes: These are native host system attribute values. You can convert attributes between different host systems using the mz_zip_attrib_convert function.
• Version Needed: When writing entries, if you set version_needed to zero, the library will automatically fill it in.

The mz_zip object is the primary abstraction in minizip-ng for reading and writing ZIP files and their individual entries. It provides a high-level interface to manage the entire archive (Archive operations) and the individual files contained within it (Entry I/O and Entry Enumeration).

Key functional areas include:

• Archive Management: Creating, deleting, opening, and closing ZIP files, as well as managing archive-level comments and versioning.
• Entry I/O: Reading from and writing to specific entries within the archive, including seeking and stream-based access.
• Entry Enumeration: Navigating through the entries in an archive (e.g., mz_zip_goto_next_entry).
• Metadata & Attributes: Handling file attributes (directories, symlinks), extra fields, and time/date conversions between different formats (DOS, Unix, NTFS).