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