Map a Btrfs Logical Extent to Its Device Offset

btrfs-map-logical tells you which physical offset holds a Btrfs logical extent, so you can pull the raw bytes straight off the disk. You can pick a mirror copy and save the extent to a file for inspection. This is a read-only debugging operation, but the output can be raw filesystem data. Allow 10 minutes if you already have the logical address and device path, or longer if you first need to identify them.

Before you start

This guide describes btrfs-progs 6.6.3, the version installed on the machine used for these examples. The local command accepts a device as its final argument and has four options: -l for the logical extent, -c for the copy, -o for an output file, and -b for the number of bytes.

You need a Btrfs logical address from the investigation that led you here, plus a device path that belongs to the relevant filesystem. Reading a block device normally requires elevated privileges. Use sudo only for the mapping command if an unprivileged run cannot open the device. Do not guess a device path, and do not use a mounted filesystem as a convenient substitute for an identified source device.

Warning: The tool is intended mainly for debugging. It reads low-level storage and does not interpret the result as a file. Do not open the captured bytes in a program that might modify them, and do not redirect output to a path containing valuable data. The command does not repair, delete or rewrite the filesystem.

1. Confirm the local command

Check the installed version and the command syntax before preparing a run:

btrfs --version
btrfs-map-logical -l 1048576 -b 4096 -o /tmp/btrfs-extent.bin /dev/mapper/example-btrfs

The second command is an example shape, not a safe command to run unchanged. Replace 1048576 with the logical address, 4096 with the byte count you need, and /dev/mapper/example-btrfs with the verified device. The local version reports:

btrfs-progs v6.6.3

If you run btrfs-map-logical --help, this version reports an unrecognised option because the program uses the short option syntax shown in its usage output. That is a common distraction when adapting examples from other tools.

2. Map the logical address

Run the mapping with an explicit byte count and output file:

sudo btrfs-map-logical \
  -l LOGICAL_OFFSET \
  -b BYTE_COUNT \
  -o /tmp/btrfs-logical-extent.bin \
  /dev/DEVICE

For a concrete, copy-and-edit example:

sudo btrfs-map-logical \
  -l 1048576 \
  -b 4096 \
  -o /tmp/btrfs-logical-extent.bin \
  /dev/nvme0n1p3

-l supplies the logical extent address. -b controls how many bytes are read. -o writes those bytes to the named file; without it, the result is sent to standard output. That default is easy to mishandle: the result may be binary, so do not let it spill into a terminal or a text log.

A successful command returns exit status 0 and normally produces no explanatory report on standard output when -o is used. Check both the status and the file:

status=$?
printf 'exit status: %s\n' "$status"
wc -c /tmp/btrfs-logical-extent.bin
file /tmp/btrfs-logical-extent.bin

The byte count should match the requested value when the read completes. The file command may call the result data or identify a recognisable format, but either result is only a description of bytes. It does not prove that the logical address was the one you intended.

3. Select a mirror copy when needed

Use -c when the extent has more than one copy and your investigation needs a particular mirror:

sudo btrfs-map-logical \
  -l 1048576 \
  -c 2 \
  -b 4096 \
  -o /tmp/btrfs-logical-copy-2.bin \
  /dev/nvme0n1p3

The manual describes copy numbers as usually 1 or 2. That is not a promise that every extent has both values. The valid choice depends on the filesystem layout and the extent being examined. If copy 2 fails, retrying with copy 1 is sensible only when the filesystem metadata says a second copy exists. Do not treat a successful read from one copy as proof that another copy is present.

Keep captures separate and label them clearly. For example:

wc -c /tmp/btrfs-logical-copy-2.bin
sha256sum /tmp/btrfs-logical-copy-2.bin

A checksum gives you a stable comparison for later analysis. It does not validate the contents, and it is not a Btrfs integrity check.

4. Handle failures without changing the filesystem

The program returns 1 if a problem occurs. Capture that status explicitly when using it in a script:

if sudo btrfs-map-logical -l 1048576 -b 4096 \
    -o /tmp/btrfs-logical-extent.bin /dev/nvme0n1p3
then
  wc -c /tmp/btrfs-logical-extent.bin
else
  printf '%s\n' 'Mapping failed; inspect the device, offset, byte count and permissions.' >&2
fi

Permission errors usually mean the device could not be opened by the current user. Other failures can mean that the device is not the Btrfs device containing the address, the logical value is invalid for that filesystem, the requested range cannot be read, or the selected copy does not exist. Check the exact device and values before trying again. Do not respond by running filesystem repair tools as a guess.

If you no longer need a capture, remove only the explicit temporary files you created:

rm -- /tmp/btrfs-logical-extent.bin /tmp/btrfs-logical-copy-2.bin

This removes the copies, not anything from Btrfs. If the bytes may be evidence, preserve them and record their checksum instead of deleting them.

Done means