diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2 index b451950ac..f1b7cb415 100644 --- a/man2/ioctl_getfsmap.2 +++ b/man2/ioctl_getfsmap.2 @@ -20,7 +20,7 @@ .\" License along with this manual; if not, see .\" . .\" %%%LICENSE_END -.TH IOCTL-GETFSMAP 2 2017-02-10 "Linux" "Linux Programmer's Manual" +.TH IOCTL_GETFSMAP 2 2017-02-10 "Linux" "Linux Programmer's Manual" .SH NAME ioctl_getfsmap \- retrieve the physical layout of the filesystem .SH SYNOPSIS @@ -35,34 +35,35 @@ ioctl_getfsmap \- retrieve the physical layout of the filesystem .SH DESCRIPTION This .BR ioctl (2) -retrieves physical extent mappings for a filesystem. +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. - -The sole argument to this ioctl should be a pointer to a single -.BR "struct fsmap_head" ":" +.PP +The sole argument to this operation should be a pointer to a single +.IR "struct fsmap_head" ":" .in +4n .nf 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 */ + __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 */ + __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 */ + struct fsmap fmh_keys[2]; /* Low and high keys for + the mapping search */ + struct fsmap fmh_recs[]; /* Returned records */ }; .fi @@ -70,7 +71,7 @@ struct fsmap_head { The two .I fmh_keys array elements specify the lowest and highest reverse-mapping -keys, respectively, for which userspace would like physical 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 @@ -80,25 +81,24 @@ therefore may return multiple mappings for a given physical block. Filesystem mappings are copied into the .I fmh_recs array, which immediately follows the header data. +.\" .SS Fields of struct fsmap_head .PP The .I fmh_iflags -field is a bitmask passed to the kernel to alter the output. -There are no flags defined, so callers must set this value to zero. - +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 bitmask of flags set by the kernel concerning the returned mappings. +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 -.B dev_t +.I dev_t structure containing the major and minor numbers of the block device. - .PP The .I fmh_count @@ -109,23 +109,21 @@ If this value is 0, 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 .PP The two key records in -.B fsmap_head.fmh_keys +.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 @@ -138,28 +136,30 @@ only return records for extents starting at or above 36KiB on disk. If the high key is set to (8:0, 1048576, 0, 0, 0), only records below 1MiB will be returned. The format of -.B fmr_device +.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 -.B fsmap_head.fmh_keys[0] +.I fsmap_head.fmh_keys[0] must contain the low key and -.B fsmap_head.fmh_keys[1] +.I fsmap_head.fmh_keys[1] must contain the high key for the request. .PP For convenience, if -.B fmr_length +.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 -.B fsmap_head.fmh_recs[fsmap_head.fmh_entries - 1] +.I fsmap_head.fmh_recs[fsmap_head.fmh_entries \- 1] into the low key. The function -.B fsmap_advance +.I fsmap_advance +(defined in +.IR linux/fsmap.h ) provides this functionality. - +.\" .SS Fields of struct fsmap .PP The @@ -170,16 +170,14 @@ If the flag is set in the header's .I fmh_oflags field, this field contains a -.B dev_t +.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 @@ -190,7 +188,6 @@ 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 @@ -199,16 +196,14 @@ 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 bitmask of extent state flags. +field is a bit mask of extent state flags. The bits are: .RS 0.4i .TP @@ -232,13 +227,12 @@ field contains a special value instead of an inode number. .B FMR_OF_LAST This is the last record in the filesystem. .RE - .PP The .I fmr_reserved field will be set to zero. - -.SS Owner Values +.\" +.SS Owner values Generally, the value of the .I fmr_owner field for non-metadata extents should be an inode number. @@ -265,7 +259,7 @@ This extent is in use but its owner is not known or not easily retrieved. .B FMR_OWN_METADATA This extent is filesystem metadata. .RE - +.PP XFS can return the following special owner values: .RS 0.4i .TP @@ -302,7 +296,7 @@ This extent is being used to stage a copy-on-write. 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 @@ -323,19 +317,20 @@ The filesystem journal. Inode records. .TP .B EXT4_FMR_OWN_BLKBM -Block bitmap. +Block bit map. .TP .B EXT4_FMR_OWN_INOBM -Inode bitmap. +Inode bit map. .RE - .SH RETURN VALUE On error, \-1 is returned, and .I errno is set to indicate the error. .PP .SH ERRORS -Error codes can be one of, but are not limited to, the following: +The error placed in +.I errno +can be one of, but is not limited to, the following: .TP .B EINVAL The array is not long enough, the keys do not point to a valid part of @@ -361,15 +356,14 @@ The filesystem has detected a checksum error in the metadata. .TP .B ENOMEM Insufficient memory to process the request. - .SH EXAMPLE -.TP -Please see io/fsmap.c in the xfsprogs distribution for a sample program. - +See +.I io/fsmap.c +in the +.I xfsprogs +distribution for a sample program. .SH CONFORMING TO This API is Linux-specific. Not all filesystems support it. -.fi -.in .SH SEE ALSO .BR ioctl (2)