BTRFS-MAP-LOGICAL(8)

📦
version 7.3 · 20 versions
, in arch rolling

💖 BTRFS-MAP-LOGICAL — the manual page, but make it make sense 💖

okay bestie, so this is btrfs-map-logical, part of the btrfs squad, section 8 of the manual (that's the "system admin commands" section, iykyk). She's a lil toolkit utility whose whole entire job is translating btrfs logical extents into physical extents. That's it. That's the girl. ✨

🌸 NAME 🌸

btrfs-map-logical — map a btrfs logical extent to a physical extent 🗺️💫

🎀 SYNOPSIS 🎀

btrfs-map-logical <options> <device>

🦋 DESCRIPTION 🦋

so basically? btrfs-map-logical figures out what the physical offsets are on the mirrors. and by "figures out" I mean she dumps the result to stdout by default. no drama, no fuss, just numbers on your screen. 💅

she's mainly used for debug purposes — like, this is not a "run it every morning with your coffee" kind of tool, she's a "your filesystem is acting up and you need to peer behind the curtain" kind of tool. 🧚

✨ OPTIONS ✨

  • -l, --logical <logical_num> — the logical extent you want to map. give her the number, she'll do the translating. 🔢
  • -c, --copy <copy> — which copy of the extent to read. usually that's 1 or 2, because btrfs keeps mirrors like a responsible queen. 👑
  • -o, --output <filename> — an output file to hold the extent. if you'd rather she write it somewhere instead of just telling you, this is your moment. 📁
  • -b, --bytes <bytes> — how many bytes to read. you decide the size, she respects it. 🍓

💀 EXIT STATUS 💀

btrfs-map-logical returns 0 if nothing bad happened. if any problems happened — and you'll know — she returns 1. that's the whole mood scale, bestie, it's binary. 😭

🔥 SEE ALSO 🔥

mkfs.btrfs(8) <> — go make a filesystem, you icon. 🌈

fr fr, this one is a debug tool, so treat her like one. nothing mysterious, nothing fancy, just logical → physical with receipts. 💖

and that's the page, no cap. this lil writeup is from btrfs version 7.3, dated Oct 24, 2026, and yes she's still BTRFS-MAP-LOGICAL(8) in the header where she lives. slay, go map some extents. 🫶✨

📦 where this page comes from