[PATCH] docs/power: note Btrfs limitation with FIBMAP for swap file offset

[PATCH] docs/power: note Btrfs limitation with FIBMAP for swap file offset

[Arun Rao Balappa]

On Btrfs, the FIBMAP ioctl does not return physical block addresses.
Tools such as filefrag therefore cannot determine the correct swap file
offset for use as resume_offset. Document the correct btrfs-progs
command to use instead.

Signed-off-by: Arun Rao Balappa <arunraobalappa@gmail.com>
---
 Documentation/power/swsusp-and-swap-files.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/power/swsusp-and-swap-files.rst b/Documentation/power/swsusp-and-swap-files.rst
index a33a2919d..44ffe02b3 100644
--- a/Documentation/power/swsusp-and-swap-files.rst
+++ b/Documentation/power/swsusp-and-swap-files.rst
@@ -35,6 +35,14 @@ FIBMAP ioctl and determine the location of the file's swap header, as the
 offset, in <PAGE_SIZE> units, from the beginning of the partition which
 holds the swap file.
 
+.. note::
+
+   On Btrfs, the FIBMAP ioctl does not return physical block addresses, so
+   tools such as ``filefrag`` cannot be used to determine the correct offset.
+   On Btrfs, use btrfs-progs instead::
+
+      btrfs inspect-internal map-swapfile -r <swap_file_path>
+
 3) Add the following parameters to the kernel command line::
 
     resume=<swap_file_partition> resume_offset=<swap_file_offset>
-- 
2.53.0

Re: [PATCH] docs/power: note Btrfs limitation with FIBMAP for swap file offset

[Christoph Hellwig]

On Tue, May 12, 2026 at 12:07:13PM +0530, Arun Rao Balappa wrote:
> On Btrfs, the FIBMAP ioctl does not return physical block addresses.

On btrfs, and on anything that writes out of place or uses multiple
devices for that matter, FIBMAP is not implemented.

> Tools such as filefrag therefore cannot determine the correct swap file
> offset for use as resume_offset. Document the correct btrfs-progs
> command to use instead.

All of this is inherently unsafe.  File systems and do move file data
without notifying users.  This document is a really bad idea and
should be removed as we should not encourage users to rely on these
kinds of hacks.

Re: [PATCH] docs/power: note Btrfs limitation with FIBMAP for swap file offset

[Arun Rao]

Understood. My intent was mainly to document the current behaviour
observed by users on Btrfs systems where filefrag/FIBMAP-based
guidance fails, and to point users toward the existing btrfs-progs
tooling.

That said, I understand the concern about encouraging users to rely on
resume_offset-based workflows in general given the underlying
fragility of file block mappings on moving or CoW filesystems.