Zarc is a file format specified on top of the Zstandard Compression Format aka RFC8878.
Zarc 是在 Zstandard 压缩格式（又名 RFC8878）之上指定的文件格式。

Zarc is a toy file format: it has received no review, only has a single implementation, and is not considered mature enough for serious use.
Zarc 是一种玩具文件格式：它没有经过审查，只有一个实现，并且不被认为足够成熟以供严肃使用。

Zarc is intended to be fairly simple to parse given a zstd decoder, while providing some interesting features, like:
Zarc 旨在在给定 zstd 解码器的情况下相对简单解析，同时提供一些有趣的功能，比如：

• always-on strong hashing and integrity verification;
  始终开启强哈希和完整性验证;
• full support for extended attributes (xattrs);
  完全支持扩展属性（xattrs）;
• high resolution timestamps;
  高分辨率时间戳;
• user-provided metadata at both archive and file level;
  存档和文件级别的用户提供的元数据;
• basic deduplication via content-addressing;
  通过内容寻址进行基本的重复数据删除;
• minimal uncompressed overhead;
  最小的无损压缩开销;
• appending files is reasonably cheap;
  追加文件是相对便宜的;
• capable of handling archives larger than memory, or even archives containing more file metadata than would fit in memory (allowed by spec but not yet implemented).
  能够处理比内存更大的存档，甚至包含比内存中可容纳的更多文件元数据的存档（规范允许但尚未实现）。

The version of the Zarc format is 1.
Zarc 格式的版本为 1。

The version of this spec is 1.0.0.
该规范的版本为 1.0.0。

CAUTION: the format is currently unstable and changes without version bump or notice.
注意：该格式目前不稳定，可能会在不更改版本或通知的情况下发生变化。

The Zarc magic number is 0xDCAA65 in little-endian.
Zarc 魔法数字是 0xDCAA65，采用小端序。

It is the string Zarc decoded as Base64:
它是字符串 Zarc 解码为 Base64：

$ echo -n 'Zarc' | base64 -d | hexyl -p
65 aa dc

Here's a quick recap of the zstd format:
这里是 zstd 格式的快速回顾：

• The format is a sequence of frames
  该格式是一系列帧
• Frames can either be Zstandard frames or Skippable frames
  帧可以是 Zstandard 帧或可跳帧
• A standard zstd decoder will skip Skippable frames
  标准 zstd 解码器将跳过可跳帧
• Numbers are little-endian
  数字是小端序
• Zstandard frames:  Zstandard 帧:
  • [magic][header][blocks...][checksum]
  • Magic is 0xFD2FB528 魔数为 0xFD2FB528
  • Header is 2-14 bytes, described in spec
    头部为 2-14 字节，详见规范
  • Checksum is optional, last 4 bytes of xxhash64
    校验和是可选的，是 xxhash64 的最后 4 个字节
  • Blocks are:  区块是：
    • [last][type][size][data]
      • Last is 1 bit (boolean)
        最后一个是 1 位（布尔值）
      • Type is 2 bits (enum)
        类型为 2 位（枚举）
      • Size is 21 bits, unsigned
        大小为 21 位，无符号
    • Type describes: 0. Raw block (data is uncompressed, verbatim)
      类型描述：0. 原始块（ data 未压缩，逐字）
      1. RLE block (data is a single byte, size is how many times it's repeated verbatim)
         RLE 块（ data 是一个字节， size 表示它被逐字重复的次数）
      2. Compressed block 压缩块
      3. Reserved 保留
• Skippable frames:  可跳过的帧：
  • [magic][size][data]
  • Magic is 0x184D2A5? where the last nibble ? is any value from 0x0 to 0xF
    魔数为 0x184D2A5？其中最后一个半字节？可以是 0x0 到 0xF 的任意值
  • Size is unsigned 32-bit int
    大小为无符号 32 位整数

Further reading: 进一步阅读：

• Informational RFC8878: https://datatracker.ietf.org/doc/html/rfc8878
  信息性 RFC8878：https://datatracker.ietf.org/doc/html/rfc8878
• Most up-to-date spec: https://github.com/facebook/zstd/blob/dev/doc/zstd_compression_format.md
  最新规范：https://github.com/facebook/zstd/blob/dev/doc/zstd_compression_format.md

A Zarc is a defined sequence of zstd frames:
Zarc 是一系列 zstd 帧的定义序列：

• one Header, a Skippable frame (0x0), used to identify a file as a Zarc
  一个 Header，一个可跳过的帧（0x0），用于识别文件为 Zarc 文件
• zero or more Zstandard frames, one for each file (modulo deduplication and special files)
  零个或多个 Zstandard 帧，每个文件一个（模除去重复和特殊文件）
• one Directory, a Zstandard (compressed) frame, which contains file list and metadata
  一个目录，一个 Zstandard（压缩）帧，其中包含文件列表和元数据
• one Trailer, a Skippable frame (0xF), used to find and check the Directory
  一个尾部，一个可跳过的帧（0xF），用于查找和检查目录

Zarcs are explicitly files: this is not a format suitable for streaming from a network location, unless random access / seek semantics are available (e.g. using the Range HTTP header).
Zarcs 是明确的文件：这不是适合从网络位置流式传输的格式，除非具有随机访问/寻址语义（例如使用 Range HTTP 标头）。

This is a Skippable frame with magic nibble = 0.
这是一个带有魔术 nibble = 0 的可跳过帧。

It contains: 它包含：

This combined with the Skippable frame header, makes a Zarc file always start with the same 12 bytes:
这个与可跳过的帧头结合在一起，使得 Zarc 文件始终以相同的 12 个字节开头：

This is a Zstandard frame.
这是一个 Zstandard 帧。

It contains a stream of CBOR-encoded Elements, which are framed with a Kind and a length.
它包含一系列 CBOR 编码的元素流，这些元素用一种类型和长度进行帧化。

Element Kinds are described below, along with their integer and CBOR payload structure. Elements of a same Kind are NOT required to be next to each other. Order is insignificant unless stated.
元素种类如下所述，以及它们的整数和 CBOR 负载结构。相同种类的元素不需要相邻。除非另有说明，否则顺序无关紧要。

Implementations MUST ignore Element Kinds they do not recognise.
实现必须忽略它们不认识的元素种类。

Non-normative note: the reserved byte is there mainly for possible expansion of the payload length. 64K per element looks pretty large from here, but who knows what the future brings.
非规范性注释：保留字节主要用于可能扩展有效载荷长度。从这里看，每个元素 64K 看起来相当大，但谁知道未来会带来什么。

Map: unsigned integer keys -> CBOR.
映射：无符号整数键 -> CBOR。

Editions record core metadata about an archive, and also provide a mechanism for retaining the metadata of previous versions of the archive, if it gets appended or edited. At least one edition must be present.
版本记录核心存档的元数据，并提供一种机制，用于保留存档的先前版本的元数据，如果它被追加或编辑。至少必须存在一个版本。

Non-zero unsigned integer. Mandatory.
非零无符号整数。强制性的。

The number of editions in a file is technically unlimited, but as of this version MUST be less than 65536. For practical purposes implementations SHOULD warn when creating more than 1000 editions, and MAY set that limit lower.
文件中的版本数量在技术上是无限的，但截至本版本，必须少于 65536。出于实际目的，实现应在创建超过 1000 个版本时发出警告，并可能将该限制设置得更低。

Creating an edition involves incrementing the edition number, so the latest edition of the file is max(edition list).
创建版本涉及递增版本号，因此文件的最新版本是 max(edition list) 。

This is used in Frame and File types as the Edition field.
这在帧和文件类型中用作 Edition 字段。

Timestamp or DateTime. Mandatory.
时间戳或日期时间。必填项。

When this version was created.
创建此版本的时间。

8-bit unsigned integer. Mandatory.
8 位无符号整数。必填。

Same as the Trailer value, the digest type in use by that edition.
与预告片价值相同，该版本使用的摘要类型。

Map: text string keys -> boolean or text or byte string. Optional.
映射：文本字符串键 -> 布尔值或文本或字节字符串。可选。

User metadata of this edition.
此版本的用户元数据。

Map: unsigned integer keys -> CBOR.
映射：无符号整数键 -> CBOR。

Unsigned integer. Mandatory.
无符号整数。强制性的。

The edition this file entry was added to the archive.
此文件条目添加到存档的版本。

Array of: text string or byte string. Mandatory.
文本字符串或字节字符串的数组。必填项。

If items are of the UTF-8 Text string CBOR type, then they represent UTF-8-encoded Unicode pathname components. If items are of the Byte string CBOR type instead, then they represent raw (non-Unicode) pathname components.
如果项目属于 UTF-8 文本字符串 CBOR 类型，则它们表示 UTF-8 编码的 Unicode 路径名组件。如果项目属于字节字符串 CBOR 类型，则它们表示原始（非 Unicode）路径名组件。

Windows implementations MUST convert raw UTF-16 to UTF-8 during encoding, and from raw bytes to UTF-8 during decoding, and replace invalid wide character sequences with the Unicode REPLACEMENT CHARACTER.
Windows 实现在编码期间必须将原始 UTF-16 转换为 UTF-8，并在解码期间将原始字节转换为 UTF-8，并用 Unicode 替换无效的宽字符序列。

Non-Unicode pathnames may not be supported on all filesystems / operating systems. Implementations SHOULD strongly prefer UTF-8, and SHOULD warn when paths do not convert cleanly.
并非所有文件系统/操作系统都支持非 Unicode 路径名。实现应当强烈倾向于使用 UTF-8，并且在路径无法清晰转换时应当发出警告。

Zarc makes no effort to restrict valid pathnames. The exception is that the components . and .. are disallowed. A Zarc decoder MUST reject such pathnames.
Zarc 不会限制有效路径名。唯一的例外是组件 . 和 .. 被禁止使用。Zarc 解码器必须拒绝这种路径名。

Pathnames are encoded in components. That is, the Unix pathname foo/bar/baz.qux and the Windows pathname foo\bar\baz.qux are encoded the same way. Pathnames can mix UTF-8 and non-Unicode components.
路径名以组件形式进行编码。也就是说，Unix 路径名 foo/bar/baz.qux 和 Windows 路径名 foo\bar\baz.qux 以相同的方式进行编码。路径名可以混合使用 UTF-8 和非 Unicode 组件。

Pathnames do not include drive letters or fileshare prefixes. (It is not possible to construct a Zarc archive spanning multiple Windows drives.)
路径名不包括驱动器字母或文件共享前缀。（无法构建跨多个 Windows 驱动器的 Zarc 归档。）

Pathnames do not encode whether a path is absolute or relative: all paths inside a Zarc archive are relative to an arbitrary root provided by the user when packing or unpacking.
路径名不会编码路径是绝对还是相对的信息：Zarc 归档中的所有路径都相对于用户在打包或解包时提供的任意根目录。

It is possible to have several identical pathname in a Zarc Directory. Implementations SHOULD provide an option to use the first or last or other selection criteria, but MUST default to preferring the last of a set of identical pathnames.
在 Zarc 目录中可能有几个相同的路径名。实现应提供选项以使用第一个、最后一个或其他选择标准，但必须默认偏好于一组相同路径名中的最后一个。

Byte string. Conditional.
字节字符串。条件性的。

The hash of a frame of content. This must be the same value as the h field of a Framelist item.
内容帧的哈希。这必须与 Framelist 项的 h 字段的值相同。

Multiple files can reference the same content frame: this provides file-level deduplication.
多个文件可以引用相同的内容帧：这提供了文件级去重。

The algorithm of the hash is described by the Hash Algorithm field above.
哈希算法由上面的哈希算法字段描述。

This may be absent for some special files (described later).
这可能在一些特殊文件中不存在（稍后描述）。

Unsigned integer. Optional.
无符号整数。可选。

Unix mode bits as an unsigned 32-bit integer.
作为无符号 32 位整数的 Unix 模式位。

If this is not set, implementations SHOULD use a default mode as appropriate.
如果未设置此项，则实现应适当使用默认模式。

Tuple (encoded as an array). Optional.
元组（编码为数组）。可选。

The user that owns this file. This is a structure with at least one of the following types of data:
拥有此文件的用户。这是一个包含以下类型数据之一的结构：

• Unsigned integer. the user ID
  无符号整数。用户 ID
• Text string. the user name as UTF-8 (or ASCII)
  文本字符串。用户名称为 UTF-8（或 ASCII）

There SHOULD NOT be more than one unsigned integer; if there are, the last value wins out.
不应该有多个无符号整数；如果有，则以最后一个值为准。

Implementations SHOULD prefer the name to the ID if there is an existing user named thus on the system with a different ID. Implementations SHOULD prefer to encode IDs as 32-bit unsigned integers, but MUST accept 8-bit, 16-bit, and 64-bit unsigned integers as well.
如果系统中存在一个使用不同 ID 的同名用户，则实现应优先使用名称而不是 ID。实现应优先将 ID 编码为 32 位无符号整数，但也必须接受 8 位、16 位和 64 位无符号整数。

Tuple (encoded as an array). Optional.
元组（编码为数组）。可选。

The group that owns this file. This is a structure with at least one of the following types of data:
拥有此文件的组。这是一个具有以下至少一种数据类型的结构：

• Unsigned integer. the group ID
  无符号整数。组 ID
• Text string. the group name as UTF-8 (or ASCII)
  文本字符串。组名称为 UTF-8（或 ASCII）

Implementations SHOULD prefer the name to the ID if there is an existing group named thus on the system with a different ID.
如果系统上存在一个具有不同 ID 的同名组，则实现应优先使用名称而不是 ID。

Map: unsigned integer keys -> timestamp. Optional.
映射：无符号整数键 -> 时间戳。可选。

Timestamps associated with this file. Any of:
与此文件相关的时间戳。任何一个：

• 1: birth time or file creation time
  1 ：创建时间或文件创建时间
• 2: mtime or file modification time
  2 ：修改时间或文件修改时间
• 3: atime or file access time — this SHOULD be the access time prior to the Zarc tool reading the file
  3 ：atime 或文件访问时间 —— 这应该是 Zarc 工具读取文件之前的访问时间

Timestamps can be stored in either:
时间戳可以存储在以下任一位置：

• RFC3339 in text string with semantic tag 0
  以文本字符串形式的 RFC3339，带有语义标记 0
• seconds from epoch as unsigned or negative integer, or binary64 floating point, with semantic tag 1
  作为无符号或负整数的时代秒数，或者作为二进制 64 浮点数，带有语义标记 1

Non-normative implementation note: the Zarc reference implementation accepts all formats for a timestamp, but always writes RFC3339 text string datetimes.
非规范性实现说明：Zarc 参考实现接受时间戳的所有格式，但始终写入 RFC3339 文本字符串日期时间。

Pair: [unsigned integer, (pathname)?]. Optional.
对：[无符号整数，(路径名)?]。可选的。

This is a structure which encodes special file types.
这是一种编码特殊文件类型的结构。

The mandatory first array item is the type of the special file. Implementations SHOULD ignore unknown or impractical special types.
强制的第一个数组项是特殊文件的类型。实现应忽略未知或不切实际的特殊类型。

• 1 — directory entry. May be used to encode metadata or (x)attributes against a directory.
  1 — 目录条目。可用于对目录编码元数据或（x）属性。

• 10 — unspecified symlink. MUST be followed by the pathname of the link target.
  10 — 未指定的符号链接。必须跟随链接目标的路径名。

  • 11 — internal symlink. MUST be followed by the pathname of another file contained in this Zarc.
    11 — 内部符号链接。必须跟随此 Zarc 中包含的另一个文件的路径名。
  • 12 — external absolute symlink. MUST be followed by the absolute pathname of a file to symlink to. Implementations MAY reject this (e.g. for security reasons).
    12 — 外部绝对符号链接。必须跟随要符号链接到的文件的绝对路径名。实现可能会拒绝此操作（例如出于安全原因）。
  • 13 — external relative symlink. MUST be followed by the relative pathname of a file to symlink to. Implementations MAY reject this (e.g. for security reasons).
    13 — 外部相对符号链接。必须跟随要符号链接到的文件的相对路径名。实现可能会拒绝此操作（例如出于安全原因）。

• 20 — unspecified hardlink. MUST be followed by the pathname of another file contained in this Zarc.
  20 — 未指定的硬链接。必须跟随此 Zarc 中包含的另一个文件的路径名。

  • 21 — internal hardlink. MUST be followed by the pathname of another file contained in this Zarc.
    21 — 内部硬链接。必须跟随此 Zarc 中包含的另一个文件的路径名。
  • 22 — external hardlink. MUST be followed by the absolute pathname of a file to hardlink to. Implementations MAY reject this (e.g. for security reasons).
    22 — 外部硬链接。必须跟随要硬链接到的文件的绝对路径名。实现可能会拒绝此操作（例如出于安全原因）。

Pathnames (as the conditional second array item) are either:
路径名（作为条件性的第二个数组项）可以是：

• Byte string or Text string. An absolute or relative full pathname with platform-specific separators;
  字节字符串或文本字符串。具有特定于平台的分隔符的绝对或相对完整路径名;
• Array(byte or text string). An array of components as for Filemap Names, except that . and .. components are allowed.
  数组（字节或文本字符串）。与 Filemap Names 的组件数组相同，只是允许 . 和 .. 组件。

The second form is preferred, for portability.
第二种形式更受青睐，具有可移植性。

Map: text string keys -> boolean or text or byte string. Optional.
映射：文本字符串键 -> 布尔值或文本或字节字符串。可选。

Arbitrary user-provided metadata for this file entry.
为此文件条目提供的任意用户提供的元数据。

Map: text string keys -> boolean or text or byte string. Optional.
映射：文本字符串键 -> 布尔值或文本或字节字符串。可选。

A map of values (typically boolean flags) which keys SHOULD correspond to file attributes.
一组值的映射（通常是布尔标志），其键应对应文件属性。

Implementations MAY ignore attributes if obtaining or setting them is impossible or impractical.
如果获取或设置属性是不可能或不切实际的，实现可以忽略属性。

Attribute keys MUST either have a prefix signifying the system they apply to:
属性键必须具有表示其适用系统的前缀：

• win32. for Windows  win32. 适用于 Windows
• linux. for Linux 适用于 Linux 的 linux.
• bsd. for BSDs, including MacOS
  适用于 BSD，包括 MacOS 的 bsd.
• _ for implementation-defined prefixes (e.g. _ncc1701.)
  适用于实现定义的前缀（例如 _ncc1701. ）的 _

OR be one of these defined unprefixed values:
或者是这些定义的无前缀值之一：

• append-only
• compressed
• immutable
• read-only

Note: attributes are metadata only, they have no bearing on the Zarc file format semantics.
注意：属性仅为元数据，对 Zarc 文件格式语义没有影响。

Map: text string keys -> boolean or text or byte string. Optional.
映射：文本字符串键 -> 布尔值或文本或字节字符串。可选。

A map of extended attributes (xattr).
一个扩展属性的映射（ xattr ）。

Zarc imposes no restriction on the format of attribute names, nor on the content or length of attribute values.
Zarc 对属性名称的格式、属性值的内容或长度没有限制。

Implementations MAY ignore extended attributes if obtaining or setting them is impossible or impractical. On Linux, implementations MAY assume a user namespace for unprefixed keys.
如果获取或设置扩展属性是不可能或不切实际的，实现可以忽略扩展属性。在 Linux 上，实现可以假定未加前缀的键属于 user 命名空间。

Map: unsigned integer keys -> CBOR. Mandatory, collect-up.
映射：无符号整数键 -> CBOR。强制性的，收集。

Structures of this type SHOULD appear in offset order.
此类型的结构应按偏移顺序出现。

Unsigned integer. Mandatory.
无符号整数。强制性的。

The edition this frame was added to the archive.
此帧添加到存档的版本。

Integer. Mandatory. 整数。强制性。

The offset in bytes from the start of the Zarc file to the first byte of the Zstandard frame header this entry describes.
从 Zarc 文件开头到描述此条目的 Zstandard 帧头的第一个字节的字节偏移量。

There MUST NOT be duplicate Frame Offsets in the Frame list.
帧列表中不能有重复的帧偏移量。

Byte string. Mandatory. 字节字符串。必填项。

The digest of the frame contents.
帧内容的摘要。

Implementations MUST check that frame contents match this digest (unless "insecure" mode is used).
实现必须检查帧内容是否与此摘要匹配（除非使用“不安全”模式）。

Integer. Mandatory. 整数。强制。

The size of the entire frame in bytes.
整个帧的大小（以字节为单位）。

This may be used to request that range of bytes from a remote source without reading too far or incrementally via block information.
这可用于从远程源请求字节范围，而无需读取太远或通过块信息逐步增加。

Integer. Mandatory. 整数。强制性的。

The length of the uncompressed content of the frame in bytes.
帧未压缩内容的长度（以字节为单位）。

This is a complement to the Frame Content Size field available on the Zstandard Frame directly, as that field can be absent depending on zstd parameters.
这是对 Zstandard 帧上直接可用的帧内容大小字段的补充，因为该字段可能根据 zstd 参数的不同而不存在。

This can be used to e.g.:
这可以用于例如：

• avoid unpacking frames which exceed available memory or storage;
  避免解压超出可用内存或存储的帧;
• preallocate storage before unpacking;
  在解压之前预分配存储空间;
• estimate the uncompressed total size of the archive.
  估算存档的未压缩总大小。

This is a Skippable frame with magic nibble = F.
这是一个可跳过的帧，带有魔术咬 = F。

It contains: 它包含：

Non-normative implementation note: This looks upside down, because you can read it from the end. The last three bytes of a Zarc file will always be 65 aa dc, preceded by the version, preceded by the check byte, etc. The critical fixed-width fields are all at the end, so they can be read by seeking to a fixed offset from the end. The Digest Type is then used to derive the length of the Digest field. It's also duplicated on the other side of the Digest, so that the trailer can be read from both sides. Going 8 bytes further back from the 'start' of the trailer will yield the Zstd Skippable frame header if you so wish to check that.
非规范实现说明：这看起来颠倒了，因为您可以从末尾读取它。 Zarc 文件的最后三个字节将始终为 65 aa dc ，之前是版本，之前是校验字节等。关键的固定宽度字段都在末尾，因此可以通过从末尾寻找固定偏移量来读取它们。然后使用 Digest Type 来推导 Digest 字段的长度。它也会在 Digest 的另一侧重复出现，以便可以从两侧读取尾部。如果您希望检查，从尾部的“start”再向后移动 8 个字节将产生 Zstd 可跳过帧头。

Signed 64-bit integer. 有符号 64 位整数。

This is EITHER: 这是“EITHER”：

• a positive value, the offset from the start of the file to the first byte of the Zstandard frame containing the Zarc Directory.
  一个正值，从文件开头到包含 Zarc 目录的第一个字节的 Zstandard 帧的偏移量。
• a negative value, the offset from the end of the file to the first byte of the Zstandard frame containing the Zarc Directory.
  一个负值，从文件末尾到包含 Zarc 目录的第一个字节的 Zstandard 帧的偏移量。

This is the uncompressed length of the Zarc Directory structure.
这是 Zarc 目录结构的未压缩长度。

This may be used to decide whether to decompress the directory in memory or stream it.
这可以用于决定是在内存中解压目录还是在流中解压目录。

Defines the algorithm used for computing digests, as well as the length of the digest fields:
定义用于计算摘要的算法，以及摘要字段的长度：

• 0: not used. This value must not appear.
  0 ：未使用。此值不得出现。
• 1: BLAKE3 hash function, 32-byte digests.
  1 ：BLAKE3 哈希函数，32 字节摘要。

This is the result of XOR'ing every other byte of the trailer together.
这是将尾部每隔一个字节进行异或运算的结果。

It can be used as a quick check for corruption.
它可以用作快速检查腐败。