1IOCTL_GETFSMAP(2)          Linux Programmer's Manual         IOCTL_GETFSMAP(2)
2
3
4

NAME

6       ioctl_getfsmap - retrieve the physical layout of the filesystem
7

SYNOPSIS

9       #include <linux/fsmap.h>  /* Definition of FS_IOC_GETFSMAP,
10                                    FM?_OF_*, and *FMR_OWN_* constants */
11       #include <sys/ioctl.h>
12
13       int ioctl(int fd, FS_IOC_GETFSMAP, struct fsmap_head * arg);
14

DESCRIPTION

16       This  ioctl(2)  operation  retrieves  physical  extent  mappings  for a
17       filesystem.  This information can be used to discover which  files  are
18       mapped  to  a  physical  block,  examine  free space, or find known bad
19       blocks, among other things.
20
21       The sole argument to this operation should be a  pointer  to  a  single
22       struct fsmap_head:
23
24           struct fsmap {
25               __u32 fmr_device;      /* Device ID */
26               __u32 fmr_flags;       /* Mapping flags */
27               __u64 fmr_physical;    /* Device offset of segment */
28               __u64 fmr_owner;       /* Owner ID */
29               __u64 fmr_offset;      /* File offset of segment */
30               __u64 fmr_length;      /* Length of segment */
31               __u64 fmr_reserved[3]; /* Must be zero */
32           };
33
34           struct fsmap_head {
35               __u32 fmh_iflags;       /* Control flags */
36               __u32 fmh_oflags;       /* Output flags */
37               __u32 fmh_count;        /* # of entries in array incl. input */
38               __u32 fmh_entries;      /* # of entries filled in (output) */
39               __u64 fmh_reserved[6];  /* Must be zero */
40
41               struct fsmap fmh_keys[2];  /* Low and high keys for
42                                             the mapping search */
43               struct fsmap fmh_recs[];   /* Returned records */
44           };
45
46       The two fmh_keys array elements specify the lowest and highest reverse-
47       mapping key for which the application would like physical  mapping  in‐
48       formation.  A reverse mapping key consists of the tuple (device, block,
49       owner, offset).  The owner and offset fields are part of  the  key  be‐
50       cause some filesystems support sharing physical blocks between multiple
51       files and therefore may return multiple mappings for a  given  physical
52       block.
53
54       Filesystem  mappings  are copied into the fmh_recs array, which immedi‐
55       ately follows the header data.
56
57   Fields of struct fsmap_head
58       The fmh_iflags field is a bit mask passed to the kernel  to  alter  the
59       output.   No  flags  are currently defined, so the caller must set this
60       value to zero.
61
62       The fmh_oflags field is a bit mask of flags set by the kernel  concern‐
63       ing the returned mappings.  If FMH_OF_DEV_T is set, then the fmr_device
64       field represents a dev_t structure containing the major and minor  num‐
65       bers of the block device.
66
67       The  fmh_count field contains the number of elements in the array being
68       passed to the kernel.  If this value is 0, fmh_entries will be  set  to
69       the  number of records that would have been returned had the array been
70       large enough; no mapping information will be returned.
71
72       The fmh_entries field contains the number of elements in  the  fmh_recs
73       array that contain useful information.
74
75       The fmh_reserved fields must be set to zero.
76
77   Keys
78       The two key records in fsmap_head.fmh_keys specify the lowest and high‐
79       est extent records in the keyspace that the caller wants  returned.   A
80       filesystem  that can share blocks between files likely requires the tu‐
81       ple (device, physical, owner, offset,  flags)  to  uniquely  index  any
82       filesystem  mapping  record.   Classic non-sharing filesystems might be
83       able to identify any record with only (device, physical,  flags).   For
84       example, if the low key is set to (8:0, 36864, 0, 0, 0), the filesystem
85       will only return records for extents starting at  or  above  36 KiB  on
86       disk.   If the high key is set to (8:0, 1048576, 0, 0, 0), only records
87       below 1 MiB will be returned.  The format of  fmr_device  in  the  keys
88       must  match  the format of the same field in the output records, as de‐
89       fined below.  By convention, the field fsmap_head.fmh_keys[0] must con‐
90       tain  the  low key and fsmap_head.fmh_keys[1] must contain the high key
91       for the request.
92
93       For convenience, if fmr_length is set in the low key, it will be  added
94       to  fmr_block or fmr_offset as appropriate.  The caller can take advan‐
95       tage  of  this  subtlety  to  set  up  subsequent  calls   by   copying
96       fsmap_head.fmh_recs[fsmap_head.fmh_entries  - 1] into the low key.  The
97       function fsmap_advance (defined in linux/fsmap.h) provides  this  func‐
98       tionality.
99
100   Fields of struct fsmap
101       The fmr_device field uniquely identifies the underlying storage device.
102       If the FMH_OF_DEV_T flag is set in the header's fmh_oflags field,  this
103       field  contains  a  dev_t from which major and minor numbers can be ex‐
104       tracted.  If the flag is not set, this field contains a value that must
105       be unique for each unique storage device.
106
107       The  fmr_physical  field  contains  the  disk  address of the extent in
108       bytes.
109
110       The fmr_owner field contains the owner of the extent.  This is an inode
111       number  unless  FMR_OF_SPECIAL_OWNER  is set in the fmr_flags field, in
112       which case the value is determined by the filesystem.  See the  section
113       below about owner values for more details.
114
115       The fmr_offset field contains the logical address in the mapping record
116       in bytes.  This field has no meaning  if  the  FMR_OF_SPECIAL_OWNER  or
117       FMR_OF_EXTENT_MAP flags are set in fmr_flags.
118
119       The fmr_length field contains the length of the extent in bytes.
120
121       The fmr_flags field is a bit mask of extent state flags.  The bits are:
122
123           FMR_OF_PREALLOC
124                  The extent is allocated but not yet written.
125
126           FMR_OF_ATTR_FORK
127                  This extent contains extended attribute data.
128
129           FMR_OF_EXTENT_MAP
130                  This extent contains extent map information for the owner.
131
132           FMR_OF_SHARED
133                  Parts of this extent may be shared.
134
135           FMR_OF_SPECIAL_OWNER
136                  The  fmr_owner  field contains a special value instead of an
137                  inode number.
138
139           FMR_OF_LAST
140                  This is the last record in the data set.
141
142       The fmr_reserved field will be set to zero.
143
144   Owner values
145       Generally, the value of the fmr_owner field  for  non-metadata  extents
146       should  be  an inode number.  However, filesystems are under no obliga‐
147       tion to report inode numbers; they may instead  report  FMR_OWN_UNKNOWN
148       if  the  inode  number  cannot easily be retrieved, if the caller lacks
149       sufficient privilege, if the filesystem does not support  stable  inode
150       numbers,  or for any other reason.  If a filesystem wishes to condition
151       the reporting of inode numbers based on  process  capabilities,  it  is
152       strongly  urged that the CAP_SYS_ADMIN capability be used for this pur‐
153       pose.
154
155       The following special owner values are generic to all filesystems:
156
157           FMR_OWN_FREE
158                  Free space.
159
160           FMR_OWN_UNKNOWN
161                  This extent is in use but its owner is not known or not eas‐
162                  ily retrieved.
163
164           FMR_OWN_METADATA
165                  This extent is filesystem metadata.
166
167       XFS can return the following special owner values:
168
169           XFS_FMR_OWN_FREE
170                  Free space.
171
172           XFS_FMR_OWN_UNKNOWN
173                  This extent is in use but its owner is not known or not eas‐
174                  ily retrieved.
175
176           XFS_FMR_OWN_FS
177                  Static filesystem metadata which exists at a fixed  address.
178                  These  are the AG superblock, the AGF, the AGFL, and the AGI
179                  headers.
180
181           XFS_FMR_OWN_LOG
182                  The filesystem journal.
183
184           XFS_FMR_OWN_AG
185                  Allocation group metadata, such as the free space btrees and
186                  the reverse mapping btrees.
187
188           XFS_FMR_OWN_INOBT
189                  The inode and free inode btrees.
190
191           XFS_FMR_OWN_INODES
192                  Inode records.
193
194           XFS_FMR_OWN_REFC
195                  Reference count information.
196
197           XFS_FMR_OWN_COW
198                  This extent is being used to stage a copy-on-write.
199
200           XFS_FMR_OWN_DEFECTIVE:
201                  This extent has been marked defective either by the filesys‐
202                  tem or the underlying device.
203
204       ext4 can return the following special owner values:
205
206           EXT4_FMR_OWN_FREE
207                  Free space.
208
209           EXT4_FMR_OWN_UNKNOWN
210                  This extent is in use but its owner is not known or not eas‐
211                  ily retrieved.
212
213           EXT4_FMR_OWN_FS
214                  Static  filesystem metadata which exists at a fixed address.
215                  This is the superblock and the group descriptors.
216
217           EXT4_FMR_OWN_LOG
218                  The filesystem journal.
219
220           EXT4_FMR_OWN_INODES
221                  Inode records.
222
223           EXT4_FMR_OWN_BLKBM
224                  Block bit map.
225
226           EXT4_FMR_OWN_INOBM
227                  Inode bit map.
228

RETURN VALUE

230       On error, -1 is returned, and errno is set to indicate the error.
231

ERRORS

233       The error placed in errno can be one of, but is  not  limited  to,  the
234       following:
235
236       EBADF  fd is not open for reading.
237
238       EBADMSG
239              The filesystem has detected a checksum error in the metadata.
240
241       EFAULT The pointer passed in was not mapped to a valid memory address.
242
243       EINVAL The  array  is not long enough, the keys do not point to a valid
244              part of the filesystem, the low key points to a higher point  in
245              the  filesystem's  physical  storage address space than the high
246              key, or a nonzero value was passed in one  of  the  fields  that
247              must be zero.
248
249       ENOMEM Insufficient memory to process the request.
250
251       EOPNOTSUPP
252              The filesystem does not support this command.
253
254       EUCLEAN
255              The filesystem metadata is corrupt and needs repair.
256

VERSIONS

258       The FS_IOC_GETFSMAP operation first appeared in Linux 4.12.
259

CONFORMING TO

261       This API is Linux-specific.  Not all filesystems support it.
262

EXAMPLES

264       See io/fsmap.c in the xfsprogs distribution for a sample program.
265

SEE ALSO

267       ioctl(2)
268

COLOPHON

270       This  page  is  part of release 5.13 of the Linux man-pages project.  A
271       description of the project, information about reporting bugs,  and  the
272       latest     version     of     this    page,    can    be    found    at
273       https://www.kernel.org/doc/man-pages/.
274
275
276
277Linux                             2021-03-22                 IOCTL_GETFSMAP(2)
Impressum