| .\" Copyright (c) 2017, Oracle. All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .TH IOCTL_GETFSMAP 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| ioctl_getfsmap \- retrieve the physical layout of the filesystem |
| .SH SYNOPSIS |
| .nf |
| .BR "#include <linux/fsmap.h> " "/* Definition of " FS_IOC_GETFSMAP , |
| .BR " FM?_OF_*" ", and " *FMR_OWN_* " constants */" |
| .B #include <sys/ioctl.h> |
| .PP |
| .BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg ); |
| .fi |
| .SH DESCRIPTION |
| This |
| .BR ioctl (2) |
| operation retrieves physical extent mappings for a filesystem. |
| This information can be used to discover which files are mapped to a physical |
| block, examine free space, or find known bad blocks, among other things. |
| .PP |
| The sole argument to this operation should be a pointer to a single |
| .IR "struct fsmap_head" ":" |
| .PP |
| .in +4n |
| .EX |
| struct fsmap { |
| __u32 fmr_device; /* Device ID */ |
| __u32 fmr_flags; /* Mapping flags */ |
| __u64 fmr_physical; /* Device offset of segment */ |
| __u64 fmr_owner; /* Owner ID */ |
| __u64 fmr_offset; /* File offset of segment */ |
| __u64 fmr_length; /* Length of segment */ |
| __u64 fmr_reserved[3]; /* Must be zero */ |
| }; |
| |
| struct fsmap_head { |
| __u32 fmh_iflags; /* Control flags */ |
| __u32 fmh_oflags; /* Output flags */ |
| __u32 fmh_count; /* # of entries in array incl. input */ |
| __u32 fmh_entries; /* # of entries filled in (output) */ |
| __u64 fmh_reserved[6]; /* Must be zero */ |
| |
| struct fsmap fmh_keys[2]; /* Low and high keys for |
| the mapping search */ |
| struct fsmap fmh_recs[]; /* Returned records */ |
| }; |
| .EE |
| .in |
| .PP |
| The two |
| .I fmh_keys |
| array elements specify the lowest and highest reverse-mapping |
| key for which the application would like physical mapping |
| information. |
| A reverse mapping key consists of the tuple (device, block, owner, offset). |
| The owner and offset fields are part of the key because some filesystems |
| support sharing physical blocks between multiple files and |
| therefore may return multiple mappings for a given physical block. |
| .PP |
| Filesystem mappings are copied into the |
| .I fmh_recs |
| array, which immediately follows the header data. |
| .\" |
| .SS Fields of struct fsmap_head |
| The |
| .I fmh_iflags |
| field is a bit mask passed to the kernel to alter the output. |
| No flags are currently defined, so the caller must set this value to zero. |
| .PP |
| The |
| .I fmh_oflags |
| field is a bit mask of flags set by the kernel concerning the returned mappings. |
| If |
| .B FMH_OF_DEV_T |
| is set, then the |
| .I fmr_device |
| field represents a |
| .I dev_t |
| structure containing the major and minor numbers of the block device. |
| .PP |
| The |
| .I fmh_count |
| field contains the number of elements in the array being passed to the |
| kernel. |
| If this value is 0, |
| .I fmh_entries |
| will be set to the number of records that would have been returned had |
| the array been large enough; |
| no mapping information will be returned. |
| .PP |
| The |
| .I fmh_entries |
| field contains the number of elements in the |
| .I fmh_recs |
| array that contain useful information. |
| .PP |
| The |
| .I fmh_reserved |
| fields must be set to zero. |
| .\" |
| .SS Keys |
| The two key records in |
| .I fsmap_head.fmh_keys |
| specify the lowest and highest extent records in the keyspace that the caller |
| wants returned. |
| A filesystem that can share blocks between files likely requires the tuple |
| .RI "(" "device" ", " "physical" ", " "owner" ", " "offset" ", " "flags" ")" |
| to uniquely index any filesystem mapping record. |
| Classic non-sharing filesystems might be able to identify any record with only |
| .RI "(" "device" ", " "physical" ", " "flags" ")." |
| For example, if the low key is set to (8:0, 36864, 0, 0, 0), the filesystem will |
| only return records for extents starting at or above 36\ KiB on disk. |
| If the high key is set to (8:0, 1048576, 0, 0, 0), only records below 1\ MiB will |
| be returned. |
| The format of |
| .I fmr_device |
| in the keys must match the format of the same field in the output records, |
| as defined below. |
| By convention, the field |
| .I fsmap_head.fmh_keys[0] |
| must contain the low key and |
| .I fsmap_head.fmh_keys[1] |
| must contain the high key for the request. |
| .PP |
| For convenience, if |
| .I fmr_length |
| is set in the low key, it will be added to |
| .IR fmr_block " or " fmr_offset |
| as appropriate. |
| The caller can take advantage of this subtlety to set up subsequent calls |
| by copying |
| .I fsmap_head.fmh_recs[fsmap_head.fmh_entries \- 1] |
| into the low key. |
| The function |
| .I fsmap_advance |
| (defined in |
| .IR linux/fsmap.h ) |
| provides this functionality. |
| .\" |
| .SS Fields of struct fsmap |
| The |
| .I fmr_device |
| field uniquely identifies the underlying storage device. |
| If the |
| .B FMH_OF_DEV_T |
| flag is set in the header's |
| .I fmh_oflags |
| field, this field contains a |
| .I dev_t |
| from which major and minor numbers can be extracted. |
| If the flag is not set, this field contains a value that must be unique |
| for each unique storage device. |
| .PP |
| The |
| .I fmr_physical |
| field contains the disk address of the extent in bytes. |
| .PP |
| The |
| .I fmr_owner |
| field contains the owner of the extent. |
| This is an inode number unless |
| .B FMR_OF_SPECIAL_OWNER |
| is set in the |
| .I fmr_flags |
| field, in which case the value is determined by the filesystem. |
| See the section below about owner values for more details. |
| .PP |
| The |
| .I fmr_offset |
| field contains the logical address in the mapping record in bytes. |
| This field has no meaning if the |
| .BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP |
| flags are set in |
| .IR fmr_flags "." |
| .PP |
| The |
| .I fmr_length |
| field contains the length of the extent in bytes. |
| .PP |
| The |
| .I fmr_flags |
| field is a bit mask of extent state flags. |
| The bits are: |
| .RS 0.4i |
| .TP |
| .B FMR_OF_PREALLOC |
| The extent is allocated but not yet written. |
| .TP |
| .B FMR_OF_ATTR_FORK |
| This extent contains extended attribute data. |
| .TP |
| .B FMR_OF_EXTENT_MAP |
| This extent contains extent map information for the owner. |
| .TP |
| .B FMR_OF_SHARED |
| Parts of this extent may be shared. |
| .TP |
| .B FMR_OF_SPECIAL_OWNER |
| The |
| .I fmr_owner |
| field contains a special value instead of an inode number. |
| .TP |
| .B FMR_OF_LAST |
| This is the last record in the data set. |
| .RE |
| .PP |
| The |
| .I fmr_reserved |
| field will be set to zero. |
| .\" |
| .SS Owner values |
| Generally, the value of the |
| .I fmr_owner |
| field for non-metadata extents should be an inode number. |
| However, filesystems are under no obligation to report inode numbers; |
| they may instead report |
| .B FMR_OWN_UNKNOWN |
| if the inode number cannot easily be retrieved, if the caller lacks |
| sufficient privilege, if the filesystem does not support stable |
| inode numbers, or for any other reason. |
| If a filesystem wishes to condition the reporting of inode numbers based |
| on process capabilities, it is strongly urged that the |
| .B CAP_SYS_ADMIN |
| capability be used for this purpose. |
| .TP |
| The following special owner values are generic to all filesystems: |
| .RS 0.4i |
| .TP |
| .B FMR_OWN_FREE |
| Free space. |
| .TP |
| .B FMR_OWN_UNKNOWN |
| This extent is in use but its owner is not known or not easily retrieved. |
| .TP |
| .B FMR_OWN_METADATA |
| This extent is filesystem metadata. |
| .RE |
| .PP |
| XFS can return the following special owner values: |
| .RS 0.4i |
| .TP |
| .B XFS_FMR_OWN_FREE |
| Free space. |
| .TP |
| .B XFS_FMR_OWN_UNKNOWN |
| This extent is in use but its owner is not known or not easily retrieved. |
| .TP |
| .B XFS_FMR_OWN_FS |
| Static filesystem metadata which exists at a fixed address. |
| These are the AG superblock, the AGF, the AGFL, and the AGI headers. |
| .TP |
| .B XFS_FMR_OWN_LOG |
| The filesystem journal. |
| .TP |
| .B XFS_FMR_OWN_AG |
| Allocation group metadata, such as the free space btrees and the |
| reverse mapping btrees. |
| .TP |
| .B XFS_FMR_OWN_INOBT |
| The inode and free inode btrees. |
| .TP |
| .B XFS_FMR_OWN_INODES |
| Inode records. |
| .TP |
| .B XFS_FMR_OWN_REFC |
| Reference count information. |
| .TP |
| .B XFS_FMR_OWN_COW |
| This extent is being used to stage a copy-on-write. |
| .TP |
| .B XFS_FMR_OWN_DEFECTIVE: |
| This extent has been marked defective either by the filesystem or the |
| underlying device. |
| .RE |
| .PP |
| ext4 can return the following special owner values: |
| .RS 0.4i |
| .TP |
| .B EXT4_FMR_OWN_FREE |
| Free space. |
| .TP |
| .B EXT4_FMR_OWN_UNKNOWN |
| This extent is in use but its owner is not known or not easily retrieved. |
| .TP |
| .B EXT4_FMR_OWN_FS |
| Static filesystem metadata which exists at a fixed address. |
| This is the superblock and the group descriptors. |
| .TP |
| .B EXT4_FMR_OWN_LOG |
| The filesystem journal. |
| .TP |
| .B EXT4_FMR_OWN_INODES |
| Inode records. |
| .TP |
| .B EXT4_FMR_OWN_BLKBM |
| Block bit map. |
| .TP |
| .B EXT4_FMR_OWN_INOBM |
| Inode bit map. |
| .RE |
| .SH RETURN VALUE |
| On error, \-1 is returned, and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| The error placed in |
| .I errno |
| can be one of, but is not limited to, the following: |
| .TP |
| .B EBADF |
| .IR fd |
| is not open for reading. |
| .TP |
| .B EBADMSG |
| The filesystem has detected a checksum error in the metadata. |
| .TP |
| .B EFAULT |
| The pointer passed in was not mapped to a valid memory address. |
| .TP |
| .B EINVAL |
| The array is not long enough, the keys do not point to a valid part of |
| the filesystem, the low key points to a higher point in the filesystem's |
| physical storage address space than the high key, or a nonzero value |
| was passed in one of the fields that must be zero. |
| .TP |
| .B ENOMEM |
| Insufficient memory to process the request. |
| .TP |
| .B EOPNOTSUPP |
| The filesystem does not support this command. |
| .TP |
| .B EUCLEAN |
| The filesystem metadata is corrupt and needs repair. |
| .SH VERSIONS |
| The |
| .B FS_IOC_GETFSMAP |
| operation first appeared in Linux 4.12. |
| .SH CONFORMING TO |
| This API is Linux-specific. |
| Not all filesystems support it. |
| .SH EXAMPLES |
| See |
| .I io/fsmap.c |
| in the |
| .I xfsprogs |
| distribution for a sample program. |
| .SH SEE ALSO |
| .BR ioctl (2) |