{
  "slug": "zfs-gang-block",
  "term": "ZFS gang block",
  "aliases": [
    "OpenZFS gang block"
  ],
  "definition": "A ZFS gang block represents one block as smaller data fragments reached through a separately checksummed header.",
  "note": "OpenZFS 2.3.4 can fall back to gang allocation when it cannot obtain the requested block size, including under severe free-space fragmentation. A member can itself be a gang block, forming a tree. This does not create free space: allocation can still fail. [zio-gang]\n\nIn this version, a gang header holds up to three member block pointers and an embedded checksum trailer. Three is the direct-member limit, not a limit on all leaves of a nested tree. [zio-header]\n\nThe parent block pointer retains the data checksum, not the header checksum, keeping the data signature used for deduplication independent of the allocation layout. [zio-gang] The header instead uses embedded SHA-256 with a verifier derived from the identity block pointer's vdev, offset and birth transaction group. Verification substitutes that expected tuple before recomputing the hash. A header cannot be validated correctly by hashing its stored bytes unchanged; this context binding is not a secret-key authentication scheme. [zio-checksum]\n\nBefore freeing or claiming members, OpenZFS assembles the entire header tree. This avoids freeing one part before discovering that another header cannot be read. On a header-assembly error, the issue stage discards its in-memory traversal tree without dispatching the member operation; that cleanup is not a partial on-disk free. Successful assembly does not certify that payload reads or writes will succeed. Header replication is separately controlled; splitting payload into members is not itself redundancy. [zio-gang]",
  "status": "shipping",
  "advantages": [
    {
      "text": "Allows a larger logical operation to use smaller allocations when an allocation of the requested size is unavailable.",
      "citationIds": [
        "zio-gang"
      ]
    }
  ],
  "limitations": [
    {
      "text": "Requires additional metadata traversal; no throughput or latency improvement is implied.",
      "citationIds": [
        "zio-gang"
      ]
    },
    {
      "text": "A valid header does not establish that every referenced data fragment is readable and correct.",
      "citationIds": [
        "zio-gang",
        "zio-checksum"
      ]
    }
  ],
  "related": [
    "zfs",
    "free-space-fragmentation",
    "checksum",
    "zfs-transaction-group",
    "vdev"
  ],
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-11-03",
  "citations": [
    {
      "id": "zio-gang",
      "title": "OpenZFS 2.3.4: zio.c, gang-tree assembly, allocation and failure paths",
      "url": "https://github.com/openzfs/zfs/blob/34f96a15c73eab27dd6ad17bb5f1263bf26e37d7/module/zfs/zio.c#L2756-L2817",
      "accessed": "2026-11-03"
    },
    {
      "id": "zio-header",
      "title": "OpenZFS 2.3.4: zio.h, gang-header layout and member-count formula",
      "url": "https://github.com/openzfs/zfs/blob/34f96a15c73eab27dd6ad17bb5f1263bf26e37d7/include/sys/zio.h#L50-L76",
      "accessed": "2026-11-03"
    },
    {
      "id": "zio-checksum",
      "title": "OpenZFS 2.3.4: zio_checksum.c, checksum table, gang verifier, compute and verification",
      "url": "https://github.com/openzfs/zfs/blob/34f96a15c73eab27dd6ad17bb5f1263bf26e37d7/module/zfs/zio_checksum.c",
      "accessed": "2026-11-01"
    }
  ],
  "provenance": [
    "Implementation review is pinned to OpenZFS zfs-2.3.4, commit 34f96a15c73eab27dd6ad17bb5f1263bf26e37d7. It is not a claim about every OpenZFS version.",
    "No native gang-block allocation, corruption injection, recovery or performance experiment was performed. Header validity, payload integrity and redundancy are separate questions."
  ]
}