{
  "slug": "whiteout",
  "term": "Whiteout",
  "aliases": [
    "whiteout marker"
  ],
  "definition": "A whiteout is a layered-filesystem marker that hides a matching lower-layer name without deleting that lower-layer object.",
  "note": "Linux RENAME_WHITEOUT atomically couples a rename with creating a whiteout at its source. Outside an overlay, that API's marker appears as a character device with device number 0:0; filesystem support and CAP_MKNOD are required. This API representation is not a universal encoding for layered storage. [linux-rename-2]\n\nOCI v1.1.1 instead serializes deletion as an empty regular TAR entry named .wh.<name>. The .wh..wh..opq entry hides lower-layer children of its directory. Both affect lower layers, not additions in the same layer, and the markers themselves are hidden when applied. [oci-layer-111]",
  "advantages": [
    "Represents a deletion in a higher layer without rewriting a lower layer."
  ],
  "limitations": [
    "Visibility suppression is not physical erasure.",
    "OCI archive markers must be interpreted as changes, not restored as ordinary payload files."
  ],
  "related": [
    "overlayfs",
    "unlink"
  ],
  "status": "shipping",
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-11-04",
  "citations": [
    {
      "id": "linux-rename-2",
      "title": "Linux man-pages: rename(2), RENAME_WHITEOUT",
      "url": "https://man7.org/linux/man-pages/man2/rename.2.html",
      "accessed": "2026-11-04"
    },
    {
      "id": "oci-layer-111",
      "title": "OCI Image Specification v1.1.1: layer changesets, whiteouts and opaque whiteouts",
      "url": "https://github.com/opencontainers/image-spec/blob/v1.1.1/layer.md#whiteouts",
      "accessed": "2026-11-04"
    }
  ],
  "provenance": [
    "Source review of Linux 6.12 and the cited API/specification; no mounted-overlay experiment or crash test."
  ]
}