Debian Codegraph @

upstream/opensuse-tumbleweed/man2/ioctl_xfs_getbmapx.2

raw
1 .\" Copyright (c) 2019, Oracle. All rights reserved.
2 .\"
3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
4 .\" SPDX-License-Identifier: GPL-2.0+
5 .\" %%%LICENSE_END
6 .TH IOCTL-XFS-GETBMAPX 2 2019-06-17 "XFS"
7 .SH NAME
8 ioctl_xfs_getbmapx \- query extent information for an open file
9 .SH SYNOPSIS
10 .br
11 .B #include <xfs/xfs_fs.h>
12 .PP
13 .BI "int ioctl(int " fd ", XFS_IOC_GETBMAP, struct getbmap *" arg );
14 .br
15 .BI "int ioctl(int " fd ", XFS_IOC_GETBMAPA, struct getbmap *" arg );
16 .br
17 .BI "int ioctl(int " fd ", XFS_IOC_GETBMAPX, struct getbmapx *" arg );
18 .SH DESCRIPTION
19 Get the block map for a segment of a file in an XFS file system.
20 The mapping information is conveyed via an array of structures of the
21 following form:
22 .PP
23 .in +4n
24 .nf
25 struct getbmap {
26 __s64 bmv_offset;
27 __s64 bmv_block;
28 __s64 bmv_length;
29 __s32 bmv_count;
30 __s32 bmv_entries;
31 };
32 .fi
33 .in
34 .PP
35 The
36 .B XFS_IOC_GETBMAPX
37 ioctl uses a larger version of that structure:
38 .PP
39 .in +4n
40 .nf
41 struct getbmapx {
42 __s64 bmv_offset;
43 __s64 bmv_block;
44 __s64 bmv_length;
45 __s32 bmv_count;
46 __s32 bmv_entries;
47 __s32 bmv_iflags;
48 __s32 bmv_oflags;
49 __s32 bmv_unused1;
50 __s32 bmv_unused2;
51 };
52 .fi
53 .in
54 .PP
55 All sizes and offsets in the structure are in units of 512 bytes.
56 .PP
57 The first structure in the array is a header and the remaining structures in
58 the array contain block map information on return.
59 The header controls iterative calls to the command and should be filled out as
60 follows:
61 .TP
62 .I bmv_offset
63 The file offset of the area of interest in the file.
64 .TP
65 .I bmv_length
66 The length of the area of interest in the file.
67 If this value is set to -1, the length of the interesting area is the rest of
68 the file.
69 .TP
70 .I bmv_count
71 The number of elements in the array, including this header.
72 The minimum value is 2.
73 .TP
74 .I bmv_entries
75 The number of entries actually filled in by the call.
76 This does not need to be filled out before the call.
77 This value may be zero if no extents were found in the requested
78 range, or if iterated calls have reached the end of the requested
79 range.
80 .TP
81 .I bmv_iflags
82 For the
83 .B XFS_IOC_GETBMAPX
84 function, this is a bitmask containing a combination of the following flags:
85 .RS 0.4i
86 .TP
87 .B BMV_IF_ATTRFORK
88 Return information about the extended attribute fork.
89 .TP
90 .B BMV_IF_PREALLOC
91 Return information about unwritten pre-allocated segments.
92 .TP
93 .B BMV_IF_DELALLOC
94 Return information about delayed allocation reservation segments.
95 .TP
96 .B BMV_IF_NO_HOLES
97 Do not return information about holes.
98 .RE
99 .PD 1
100 .PP
101 The other
102 .I bmv_*
103 fields in the header are ignored.
104 .PP
105 On successful return from a call, the offset and length values in the header
106 are updated so that the command can be reused to obtain more information.
107 The remaining elements of the array will be filled out by the call as follows:
108 .TP
109 .I bmv_offset
110 File offset of segment.
111 .TP
112 .I bmv_block
113 Physical starting block of segment.
114 If this is -1, then the segment is a hole.
115 .TP
116 .I bmv_length
117 Length of segment.
118 .TP
119 .I bmv_oflags
120 The
121 .B XFS_IOC_GETBMAPX
122 function will fill this field with a combination of the following flags:
123 .RS 0.4i
124 .TP
125 .B BMV_OF_PREALLOC
126 The segment is an unwritten pre-allocation.
127 .TP
128 .B BMV_OF_DELALLOC
129 The segment is a delayed allocation reservation.
130 .TP
131 .B BMV_OF_LAST
132 This segment is the last in the file.
133 .TP
134 .B BMV_OF_SHARED
135 This segment shares blocks with other files.
136 .RE
137 .PD 1
138 .PP
139 The other
140 .I bmv_*
141 fields are unused in the array of output records.
142 .PP
143 The
144 .B XFS_IOC_GETBMAPA
145 command is identical to
146 .B XFS_IOC_GETBMAP
147 except that information about the attribute fork of the file is returned.
148 .SH RETURN VALUE
149 On error, \-1 is returned, and
150 .I errno
151 is set to indicate the error.
152 .PP
153 .SH ERRORS
154 Error codes can be one of, but are not limited to, the following:
155 .TP
156 .B EFAULT
157 The kernel was not able to copy into the userspace buffer.
158 .TP
159 .B EFSBADCRC
160 Metadata checksum validation failed while performing the query.
161 .TP
162 .B EFSCORRUPTED
163 Metadata corruption was encountered while performing the query.
164 .TP
165 .B EINVAL
166 One of the arguments was not valid.
167 .TP
168 .B EIO
169 An I/O error was encountered while performing the query.
170 .TP
171 .B ENOMEM
172 There was insufficient memory to perform the query.
173 .SH CONFORMING TO
174 This API is specific to XFS filesystem on the Linux kernel.
175 .SH SEE ALSO
176 .BR ioctl (2)