Fiemap: Efficient File Extent Mapping

Background

Before we dive into Fiemap, let’s quickly review some filesystem concepts:

ioctl()

ioctl() 함수란 하드웨어의 제어와 상태 정보를 얻기 위해 제공되는 함수

ioctl() stands for “input/output control” system call. It is method for a user application to send a control command directly to the kernel or device driver. It takes a file descriptor, a request code, and an optional argument (integer or pointer to a data structure), and returns an integer status code.

ioctl() vs read()/write():

ioctl() is used for device-specific operations and configurations. For example, it can be used to change device settings, get device status, or perform operations that are not standard file I/O.
read() and write() are used to transfer the file’s data between the kernel and user space. (i.e. only for reading/writing file content)
Linux Manual Page

Extent

Extent is a contiguous block of storage in a filesystem. An extent is defined by:

Starting Block: The first block of the extent; where it starts on the disk.
Logical Offset: The starting point of the extent within the file; where it starts in the file.
Length: The number of contiguous blocks in the extent.

Why Extents?

File systems, like ext4, XFS, and Btrfs, try to store files in contiguous blocks due to:

Efficiency: Need to seek fewer blocks = faster read/write.
Simplicity: Easier to manage fewer, larger blocks than many small ones.

Instead of tracking every single block, the filesystem tracks extents, which are ranges of contiguous blocks. This reduces metadata overhead and improves performance.

What is Fiemap?

Fiemap Documentation

Fiemap is a Linux ioctl interface that tells the user how a file is laid out on a disk. It returns the extents of a file, which contains a mapping from the file’s logical offsets to its physical disk blocks. Essentially, it shows where the data physically resides on the storage device.

Why Fiemap?

Due to fragmentation or file system behaviour, the data of a file may not be stored in a single contiguous block. Fiemap gives the programmer insight into how the file is actually stored on disk.

How to Use Fiemap

1
#include <linux/fiemap.h>
2

3
ioctl(fd, FS_IOC_FIEMAP, &fiemap);

Input:

fd: File descriptor of the file to be queried.
FS_IOC_FIEMAP: The ioctl command to request file extent mapping.
&fiemap: Pointer to a fiemap structure that will be filled with the extent information.

Output:

On success, the fiemap structure is populated with the file’s extent information.
On failure, it returns -1 and sets errno.

Structure of Fiemap Request

1
struct fiemap {
2
  __u64  fm_start;   /* logical offset (inclusive) at which to start mapping (in) */
3
  __u64  fm_length;   /* logical length of mapping which userspace cares about (in) */
4
  __u32  fm_flags;   /* FIEMAP_FLAG_* flags for request (in/out) */
5
  __u32  fm_mapped_extents; /* number of extents that were mapped (out) */
6
  __u32  fm_extent_count; /* size of fm_extents array (in) */
7
  __u32  fm_reserved;
8
  struct fiemap_extent fm_extents[0]; /* array of mapped extents (out)*/
9
};

Extent Mapping

The extent information is returned within the fiemap_extent array that the user allocates along with the fiemap structure. Each extent is described by a single fiemap_extent structure:

1
struct fiemap_extent {
2
  __u64  fe_logical;  /* logical offset in bytes for the start of the extent */
3
  __u64  fe_physical; /* physical offset in bytes for the start of the extent */
4
  __u64  fe_length;   /* length in bytes for the extent */
5
  __u64  fe_reserved64[2];
6
  __u32  fe_flags;    /* FIEMAP_EXTENT_* flags for this extent */
7
  __u32  fe_reserved[3];
8
};

Code Example

Here is a simple example of how to use Fiemap to get the extent mapping of a file:

1
#define _GNU_SOURCE
2
#include <stdio.h>
3
#include <stdlib.h>
4
#include <fcntl.h>
5
#include <unistd.h>
6
#include <sys/ioctl.h>
7
#include <linux/fs.h>
8
#include <linux/fiemap.h>
9
#include <errno.h>
10
#include <string.h>
11

12
#define EXTENTS_MAX 64   // how many extents we want to retrieve
13

14
int main(int argc, char *argv[]) {
15
    if (argc != 2) {
16
        fprintf(stderr, "Usage: %s <filename>\n", argv[0]);
17
        exit(1);
18
    }
19

20
    const char *path = argv[1];
21
    int fd = open(path, O_RDONLY);
22
    if (fd < 0) {
23
        perror("open");
24
        exit(1);
25
    }
26

27
    // allocate fiemap structure with room for EXTENTS_MAX extents
28
    size_t fiemap_size = sizeof(struct fiemap) +
29
                         EXTENTS_MAX * sizeof(struct fiemap_extent);
30
    struct fiemap *fiemap = (struct fiemap *)calloc(1, fiemap_size);
31
    if (!fiemap) {
32
        perror("calloc");
33
        close(fd);
34
        exit(1);
35
    }
36

37
    fiemap->fm_start = 0;                  // start of file
38
    fiemap->fm_length = ~0ULL;             // map entire file
39
    fiemap->fm_extent_count = EXTENTS_MAX; // request up to EXTENTS_MAX extents
40

41
    if (ioctl(fd, FS_IOC_FIEMAP, fiemap) < 0) {
42
        perror("ioctl(FS_IOC_FIEMAP)");
43
        free(fiemap);
44
        close(fd);
45
        exit(1);
46
    }
47

48
    printf("File: %s\n", path);
49
    printf("Mapped %u extents\n", fiemap->fm_mapped_extents);
50

51
    for (unsigned int i = 0; i < fiemap->fm_mapped_extents; i++) {
52
        struct fiemap_extent *ex = &fiemap->fm_extents[i];
53
        printf("Extent %u: logical=%llu, physical=%llu, length=%llu, flags=0x%x\n",
54
               i,
55
               (unsigned long long)ex->fe_logical,
56
               (unsigned long long)ex->fe_physical,
57
               (unsigned long long)ex->fe_length,
58
               ex->fe_flags);
59
    }
60

61
    free(fiemap);
62
    close(fd);
63
    return 0;
64
}

Output:

root@6a914391cd46:~# ./fiemap_example file.txt
File: file.txt
Mapped 1 extents
Extent 0: logical=0, physical=1337966592, length=12288, flags=0x1