diff options
Diffstat (limited to 'man2/ioctl_getfsmap.2')
| -rw-r--r-- | man2/ioctl_getfsmap.2 | 351 |
1 files changed, 0 insertions, 351 deletions
diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2 deleted file mode 100644 index d995ad524..000000000 --- a/man2/ioctl_getfsmap.2 +++ /dev/null @@ -1,351 +0,0 @@ -.\" Copyright (c) 2017, Oracle. All rights reserved. -.\" -.\" SPDX-License-Identifier: GPL-2.0-or-later -.TH ioctl_getfsmap 2 (date) "Linux man-pages (unreleased)" -.SH NAME -ioctl_getfsmap \- retrieve the physical layout of the filesystem -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.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 -.I 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 STANDARDS -Linux. -.PP -Not all filesystems support it. -.SH HISTORY -Linux 4.12. -.SH EXAMPLES -See -.I io/fsmap.c -in the -.I xfsprogs -distribution for a sample program. -.SH SEE ALSO -.BR ioctl (2) |