Module macos 

Read-only reader for the macOS Trash put-back metadata stored in a Trash folder’s .DS_Store file.

On modern macOS (Big Sur → Sequoia) there is no $I/$R-style sidecar and no put-back extended attribute: the original location of a trashed item is recorded only inside the Trash folder’s .DS_Store, as two per-item B-tree records keyed by the item’s current name in the Trash:

• ptbN — Put-Back Name: the item’s original filename, and
• ptbL — Put-Back Location: the item’s original parent directory,

both of .DS_Store data type ustr (a length-prefixed UTF-16BE string). ptbL is stored in the APFS firmlink form System/Volumes/Data/…; PutBack::original_path normalises that to the user-visible /… while the raw value stays available verbatim.

Many legitimately trashed items have no put-back record (Finder writes .DS_Store lazily, and rm/non-Finder deletes never write one), so the absence of a record is normal, not evidence of tampering.

.DS_Store / Bud1 format

The container is a Finder “Desktop Services Store”: a 4-byte 00 00 00 01 prefix, the magic Bud1, then a buddy allocator whose table-of-contents maps the key DSDB to a B-tree of records. The layout follows Wim Lewis’s reverse-engineered Mac::Finder::DSStore DSStoreFormat.pod (https://metacpan.org/dist/Mac-Finder-DSStore/view/DSStoreFormat.pod); the ptbN/ptbL record types are newer Finder additions cross-checked against al45tair’s ds_store library, which also generated this crate’s test fixture.

All reads are bounds-checked: a truncated or hostile .DS_Store yields a typed DsStoreError, never a panic, and the B-tree walk is cycle-guarded.

Structs

PutBack

A recovered macOS put-back record: an item in the Trash together with where it came from.

Enums

DsStoreError

Errors returned while parsing a .DS_Store put-back store.

Functions

parse_put_back

Parse the raw bytes of a Trash .DS_Store file and return every put-back record it carries, sorted by trash_name.