man2/ioctl_getfsmap.2

   1 .\" Copyright (c) 2017, Oracle.  All rights reserved.
   2 .\"
   3 .\" SPDX-License-Identifier: GPL-2.0-or-later
   4 .TH IOCTL_GETFSMAP 2 2021-03-22 "Linux" "Linux Programmer's Manual"
   5 .SH NAME
   6 ioctl_getfsmap \- retrieve the physical layout of the filesystem
   7 .SH LIBRARY
   8 Standard C library
   9 .RI ( libc ", " \-lc )
  10 .SH SYNOPSIS
  11 .nf
  12 .BR "#include <linux/fsmap.h>  " "/* Definition of " FS_IOC_GETFSMAP ,
  13 .BR "                             FM?_OF_*" ", and " *FMR_OWN_* " constants */"
  14 .B #include <sys/ioctl.h>
  15 .PP
  16 .BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg );
  17 .fi
  18 .SH DESCRIPTION
  19 This
  20 .BR ioctl (2)
  21 operation retrieves physical extent mappings for a filesystem.
  22 This information can be used to discover which files are mapped to a physical
  23 block, examine free space, or find known bad blocks, among other things.
  24 .PP
  25 The sole argument to this operation should be a pointer to a single
  26 .IR "struct fsmap_head" ":"
  27 .PP
  28 .in +4n
  29 .EX
  30 struct fsmap {
  31     __u32 fmr_device;      /* Device ID */
  32     __u32 fmr_flags;       /* Mapping flags */
  33     __u64 fmr_physical;    /* Device offset of segment */
  34     __u64 fmr_owner;       /* Owner ID */
  35     __u64 fmr_offset;      /* File offset of segment */
  36     __u64 fmr_length;      /* Length of segment */
  37     __u64 fmr_reserved[3]; /* Must be zero */
  38 };
  39
  40 struct fsmap_head {
  41     __u32 fmh_iflags;       /* Control flags */
  42     __u32 fmh_oflags;       /* Output flags */
  43     __u32 fmh_count;        /* # of entries in array incl. input */
  44     __u32 fmh_entries;      /* # of entries filled in (output) */
  45     __u64 fmh_reserved[6];  /* Must be zero */
  46
  47     struct fsmap fmh_keys[2];  /* Low and high keys for
  48                                   the mapping search */
  49     struct fsmap fmh_recs[];   /* Returned records */
  50 };
  51 .EE
  52 .in
  53 .PP
  54 The two
  55 .I fmh_keys
  56 array elements specify the lowest and highest reverse-mapping
  57 key for which the application would like physical mapping
  58 information.
  59 A reverse mapping key consists of the tuple (device, block, owner, offset).
  60 The owner and offset fields are part of the key because some filesystems
  61 support sharing physical blocks between multiple files and
  62 therefore may return multiple mappings for a given physical block.
  63 .PP
  64 Filesystem mappings are copied into the
  65 .I fmh_recs
  66 array, which immediately follows the header data.
  67 .\"
  68 .SS Fields of struct fsmap_head
  69 The
  70 .I fmh_iflags
  71 field is a bit mask passed to the kernel to alter the output.
  72 No flags are currently defined, so the caller must set this value to zero.
  73 .PP
  74 The
  75 .I fmh_oflags
  76 field is a bit mask of flags set by the kernel concerning the returned mappings.
  77 If
  78 .B FMH_OF_DEV_T
  79 is set, then the
  80 .I fmr_device
  81 field represents a
  82 .I dev_t
  83 structure containing the major and minor numbers of the block device.
  84 .PP
  85 The
  86 .I fmh_count
  87 field contains the number of elements in the array being passed to the
  88 kernel.
  89 If this value is 0,
  90 .I fmh_entries
  91 will be set to the number of records that would have been returned had
  92 the array been large enough;
  93 no mapping information will be returned.
  94 .PP
  95 The
  96 .I fmh_entries
  97 field contains the number of elements in the
  98 .I fmh_recs
  99 array that contain useful information.
 100 .PP
 101 The
 102 .I fmh_reserved
 103 fields must be set to zero.
 104 .\"
 105 .SS Keys
 106 The two key records in
 107 .I fsmap_head.fmh_keys
 108 specify the lowest and highest extent records in the keyspace that the caller
 109 wants returned.
 110 A filesystem that can share blocks between files likely requires the tuple
 111 .RI "(" "device" ", " "physical" ", " "owner" ", " "offset" ", " "flags" ")"
 112 to uniquely index any filesystem mapping record.
 113 Classic non-sharing filesystems might be able to identify any record with only
 114 .RI "(" "device" ", " "physical" ", " "flags" ")."
 115 For example, if the low key is set to (8:0, 36864, 0, 0, 0), the filesystem will
 116 only return records for extents starting at or above 36\ KiB on disk.
 117 If the high key is set to (8:0, 1048576, 0, 0, 0), only records below 1\ MiB will
 118 be returned.
 119 The format of
 120 .I fmr_device
 121 in the keys must match the format of the same field in the output records,
 122 as defined below.
 123 By convention, the field
 124 .I fsmap_head.fmh_keys[0]
 125 must contain the low key and
 126 .I fsmap_head.fmh_keys[1]
 127 must contain the high key for the request.
 128 .PP
 129 For convenience, if
 130 .I fmr_length
 131 is set in the low key, it will be added to
 132 .IR fmr_block " or " fmr_offset
 133 as appropriate.
 134 The caller can take advantage of this subtlety to set up subsequent calls
 135 by copying
 136 .I fsmap_head.fmh_recs[fsmap_head.fmh_entries \- 1]
 137 into the low key.
 138 The function
 139 .I fsmap_advance
 140 (defined in
 141 .IR linux/fsmap.h )
 142 provides this functionality.
 143 .\"
 144 .SS Fields of struct fsmap
 145 The
 146 .I fmr_device
 147 field uniquely identifies the underlying storage device.
 148 If the
 149 .B FMH_OF_DEV_T
 150 flag is set in the header's
 151 .I fmh_oflags
 152 field, this field contains a
 153 .I dev_t
 154 from which major and minor numbers can be extracted.
 155 If the flag is not set, this field contains a value that must be unique
 156 for each unique storage device.
 157 .PP
 158 The
 159 .I fmr_physical
 160 field contains the disk address of the extent in bytes.
 161 .PP
 162 The
 163 .I fmr_owner
 164 field contains the owner of the extent.
 165 This is an inode number unless
 166 .B FMR_OF_SPECIAL_OWNER
 167 is set in the
 168 .I fmr_flags
 169 field, in which case the value is determined by the filesystem.
 170 See the section below about owner values for more details.
 171 .PP
 172 The
 173 .I fmr_offset
 174 field contains the logical address in the mapping record in bytes.
 175 This field has no meaning if the
 176 .BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP
 177 flags are set in
 178 .IR fmr_flags "."
 179 .PP
 180 The
 181 .I fmr_length
 182 field contains the length of the extent in bytes.
 183 .PP
 184 The
 185 .I fmr_flags
 186 field is a bit mask of extent state flags.
 187 The bits are:
 188 .RS 0.4i
 189 .TP
 190 .B FMR_OF_PREALLOC
 191 The extent is allocated but not yet written.
 192 .TP
 193 .B FMR_OF_ATTR_FORK
 194 This extent contains extended attribute data.
 195 .TP
 196 .B FMR_OF_EXTENT_MAP
 197 This extent contains extent map information for the owner.
 198 .TP
 199 .B FMR_OF_SHARED
 200 Parts of this extent may be shared.
 201 .TP
 202 .B FMR_OF_SPECIAL_OWNER
 203 The
 204 .I fmr_owner
 205 field contains a special value instead of an inode number.
 206 .TP
 207 .B FMR_OF_LAST
 208 This is the last record in the data set.
 209 .RE
 210 .PP
 211 The
 212 .I fmr_reserved
 213 field will be set to zero.
 214 .\"
 215 .SS Owner values
 216 Generally, the value of the
 217 .I fmr_owner
 218 field for non-metadata extents should be an inode number.
 219 However, filesystems are under no obligation to report inode numbers;
 220 they may instead report
 221 .B FMR_OWN_UNKNOWN
 222 if the inode number cannot easily be retrieved, if the caller lacks
 223 sufficient privilege, if the filesystem does not support stable
 224 inode numbers, or for any other reason.
 225 If a filesystem wishes to condition the reporting of inode numbers based
 226 on process capabilities, it is strongly urged that the
 227 .B CAP_SYS_ADMIN
 228 capability be used for this purpose.
 229 .TP
 230 The following special owner values are generic to all filesystems:
 231 .RS 0.4i
 232 .TP
 233 .B FMR_OWN_FREE
 234 Free space.
 235 .TP
 236 .B FMR_OWN_UNKNOWN
 237 This extent is in use but its owner is not known or not easily retrieved.
 238 .TP
 239 .B FMR_OWN_METADATA
 240 This extent is filesystem metadata.
 241 .RE
 242 .PP
 243 XFS can return the following special owner values:
 244 .RS 0.4i
 245 .TP
 246 .B XFS_FMR_OWN_FREE
 247 Free space.
 248 .TP
 249 .B XFS_FMR_OWN_UNKNOWN
 250 This extent is in use but its owner is not known or not easily retrieved.
 251 .TP
 252 .B XFS_FMR_OWN_FS
 253 Static filesystem metadata which exists at a fixed address.
 254 These are the AG superblock, the AGF, the AGFL, and the AGI headers.
 255 .TP
 256 .B XFS_FMR_OWN_LOG
 257 The filesystem journal.
 258 .TP
 259 .B XFS_FMR_OWN_AG
 260 Allocation group metadata, such as the free space btrees and the
 261 reverse mapping btrees.
 262 .TP
 263 .B XFS_FMR_OWN_INOBT
 264 The inode and free inode btrees.
 265 .TP
 266 .B XFS_FMR_OWN_INODES
 267 Inode records.
 268 .TP
 269 .B XFS_FMR_OWN_REFC
 270 Reference count information.
 271 .TP
 272 .B XFS_FMR_OWN_COW
 273 This extent is being used to stage a copy-on-write.
 274 .TP
 275 .B XFS_FMR_OWN_DEFECTIVE:
 276 This extent has been marked defective either by the filesystem or the
 277 underlying device.
 278 .RE
 279 .PP
 280 ext4 can return the following special owner values:
 281 .RS 0.4i
 282 .TP
 283 .B EXT4_FMR_OWN_FREE
 284 Free space.
 285 .TP
 286 .B EXT4_FMR_OWN_UNKNOWN
 287 This extent is in use but its owner is not known or not easily retrieved.
 288 .TP
 289 .B EXT4_FMR_OWN_FS
 290 Static filesystem metadata which exists at a fixed address.
 291 This is the superblock and the group descriptors.
 292 .TP
 293 .B EXT4_FMR_OWN_LOG
 294 The filesystem journal.
 295 .TP
 296 .B EXT4_FMR_OWN_INODES
 297 Inode records.
 298 .TP
 299 .B EXT4_FMR_OWN_BLKBM
 300 Block bit map.
 301 .TP
 302 .B EXT4_FMR_OWN_INOBM
 303 Inode bit map.
 304 .RE
 305 .SH RETURN VALUE
 306 On error, \-1 is returned, and
 307 .I errno
 308 is set to indicate the error.
 309 .SH ERRORS
 310 The error placed in
 311 .I errno
 312 can be one of, but is not limited to, the following:
 313 .TP
 314 .B EBADF
 315 .IR fd
 316 is not open for reading.
 317 .TP
 318 .B EBADMSG
 319 The filesystem has detected a checksum error in the metadata.
 320 .TP
 321 .B EFAULT
 322 The pointer passed in was not mapped to a valid memory address.
 323 .TP
 324 .B EINVAL
 325 The array is not long enough, the keys do not point to a valid part of
 326 the filesystem, the low key points to a higher point in the filesystem's
 327 physical storage address space than the high key, or a nonzero value
 328 was passed in one of the fields that must be zero.
 329 .TP
 330 .B ENOMEM
 331 Insufficient memory to process the request.
 332 .TP
 333 .B EOPNOTSUPP
 334 The filesystem does not support this command.
 335 .TP
 336 .B EUCLEAN
 337 The filesystem metadata is corrupt and needs repair.
 338 .SH VERSIONS
 339 The
 340 .B FS_IOC_GETFSMAP
 341 operation first appeared in Linux 4.12.
 342 .SH CONFORMING TO
 343 This API is Linux-specific.
 344 Not all filesystems support it.
 345 .SH EXAMPLES
 346 See
 347 .I io/fsmap.c
 348 in the
 349 .I xfsprogs
 350 distribution for a sample program.
 351 .SH SEE ALSO
 352 .BR ioctl (2)