3
xfs_io \- debug the I/O path of an XFS filesystem
6
\f3xfs_io\f1 [ \f3\-c\f1 cmd ] ... [ \f3\-p\f1 prog ] [ \f3\-adFfmrRstx\f1 ] file
9
\f2xfs_io\f1 is a debugging tool like \f2xfs_db\f1(8), but is aimed
10
at examining the regular file I/O path rather than the raw XFS volume
13
The options to \f2xfs_io\f1 are:
16
\f2xfs_io\f1 commands may be run interactively (the default)
17
or as arguments on the command line.
18
Multiple \f3\-c\f1 arguments may be given.
19
The commands are run in the sequence given, then the program exits.
22
Set the program name for prompts and some error messages,
23
the default value is \f2xfs_io\f1.
26
Allow \f2file\f1 to reside in non-XFS (foreign) filesystems.
27
This mode has a restricted set of commands.
30
Create \f2file\f1 if it does not already exist.
33
Open \f2file\f1 read-only, initially.
37
Dangerous commands are only available in this mode.
38
These commands also tend to require additional privileges.
40
The other \f2open\f1(2) options described below are also available
41
from the command line.
43
\f2xfs_io\f1 maintains a number of open files and memory mappings.
44
Files can be initially opened on the command line (optionally),
45
and additional files can also be opened later.
47
\f2xfs_io\f1 commands can be broken up into three groups.
48
Some commands are aimed at doing regular file I/O - read, write,
49
sync, space preallocation, etc.
51
The second set of commands exist for manipulating memory mapped regions
52
of a file - mapping, accessing, storing, unmapping, flushing, etc.
54
The remaining commands are for the navigation and display of data
55
structures relating to the open files, mappings, and the filesystems
58
Many commands have extensive online help.
59
Use the \f3help\f1 command for more details on any command.
62
\f3file\f1 [ \f2N\f1 ]
63
Display a list of all open files and (optionally) switch to an alternate
66
\f3open\f1 [ \f2\-FacdfrstR\f1 ] [ \f2path\f1 ]
67
Closes the current file, and opens the file specified by \f2path\f1 instead.
68
Without any arguments, displays statistics about the current file \-
69
see the \f3stat\f1 command.
71
The \f3\-F\f1 option allows non-XFS (foreign) files to be opened and
72
operated on with a restricted command set.
74
The \f3\-a\f1 option opens append-only (O_APPEND).
76
The \f3\-d\f1 option opens for direct I/O (O_DIRECT).
78
The \f3\-f\f1 option creates the file if it doesn't already exist (O_CREAT).
80
The \f3\-r\f1 option opens read-only (O_RDONLY).
82
The \f3\-s\f1 option opens for synchronous I/O (O_SYNC).
84
The \f3\-t\f1 option truncates on open (O_TRUNC).
86
The \f3\-R\f1 option marks the file as a realtime XFS file after
87
opening it, if it is not already marked as such.
90
See the \f3open\f1 command.
93
Closes the current open file, marking the next open file as current
97
See the \f3close\f1 command.
99
\f3pread\f1 [ \f2\-b bsize\f1 ] [ \f2\-v\f1 ]
100
Reads a range of bytes in a specified blocksize from the given offset.
102
The \f3\-b\f1 option can be used to set the blocksize into which the
103
\f2read\f1(2) requests will be split.
104
The default blocksize is 4096 bytes.
106
The \f3\-v\f1 option will dump the contents of the buffer after reading,
107
by default only the count of bytes actually read is dumped.
110
See the \f3pread\f1 command.
112
\f3pwrite\f1 [ \f2\-i file\f1 ] [ \f2\-d\f1 ] [ \f2\-s skip\f1 ] [ \f2\-b size\f1 ] [ \f2\-S seed\f1 ]
113
Writes a range of bytes in a specified blocksize from the given offset.
114
The bytes written can be either a set pattern or read in from another
117
The \f3\-i\f1 option allows an input file to be specified as the source
118
of the data to be written.
120
The \f3\-d\f1 option will cause direct I/O, rather than the usual buffered
121
I/O, to be used when reading the input file.
123
The \f3\-s\f1 options specifies the number of bytes to skip from the
124
start of the input file before starting to read.
126
The \f3\-b\f1 option can be used to set the blocksize into which the
127
\f2write\f1(2) requests will be split.
128
The default blocksize is 4096 bytes.
129
The \f3\-S\f1 option is used to set the (repeated) fill pattern which
130
is used when the data to write is not coming from a file.
131
The default buffer fill pattern value is 0xcdcdcdcd.
134
See the \f3pwrite\f1 command.
136
\f3bmap\f1 [ \f2\-adlpv\f1 ] [ \f2\-n nx\f1 ]
137
Prints the block mapping for the current open file.
138
Refer to \f2xfs_bmap\f1(8) for complete documentation.
140
\f3allocsp\f1 \f2offset\f1 \f2length\f1
141
Allocates zeroed space for part of a file using the XFS_IOC_ALLOCSP
142
system call described in \f2xfs\f1(5).
144
\f3freesp\f1 \f2offset\f1 \f2length\f1
145
Frees space for part of a file using the XFS_IOC_FREESP
146
system call described in \f2xfs\f1(5).
148
\f3fadvise\f1 [ \f2\-dnrsw\f1 ]
149
On platforms which support it, allows hints be given to the system
150
regarding the expected I/O patterns on the file.
151
The hints are similar to those of the \f3madvise\f1 command,
155
Calls \f2fdatasync\f1(2) to flush the file's in-core data to disk.
158
Calls \f2fsync\f1(2) to flush all in-core file state to disk.
161
See the \f3fsync\f1 command.
163
\f3resvsp\f1 \f2offset\f1 \f2length\f1
164
Allocates reserved, unwritten space for part of a file using the XFS_IOC_RESVSP
165
system call described in \f2xfs\f1(5).
167
\f3unresvsp\f1 \f2offset\f1 \f2length\f1
168
Frees reserved space for part of a file using the XFS_IOC_UNRESVSP
169
system call described in \f2xfs\f1(5).
171
\f3truncate\f1 \f2offset\f1
172
Truncates the current file at the given offset using \f2ftruncate\f1(2).
174
\f3sendfile\f1 \f2\-i infile\f1 | \f2\-f N\f1 [ \f2offset\f1 \f2length\f1 ]
175
On platforms which support it, allows a direct in-kernel copy between
176
two file descriptors.
177
The current open file is the target, the source must be specified as
178
another open file (\f2-f\f1) or by path (\f2-i\f2).
180
.SH MEMORY MAPPED I/O COMMANDS
182
\f3mmap\f1 [ \f2-rwx\f1 ] [[ N ] | [ \f2offset\f1 \f2length\f1 ]]
183
With no arguments, \f3mmap\f1 shows the current mappings.
184
Specifying a single numeric argument sets the current mapping.
185
If two arguments are specified (a range), a new mapping is created
186
spanning the range, and the protection mode can be given as a combination of
187
PROT_READ (\f2-r\f1), PROT_WRITE (\f2-w\f1), and PROT_EXEC (\f2-x\f1).
190
See the \f3mmap\f1 command.
193
Unmaps the current memory mapping.
196
See the \f3munmap\f1 command.
198
\f3mread\f1 [ \-\f2frv\f1 ]
199
Accesses a segment of the current memory mapping, optionally dumping it to
200
the standard output stream (with \f2-v\f1 or \f2-f\f1 option) for inspection.
201
The accesses are performed sequentially from the start offset by default,
202
but can also be done from the end backwards through the mapping if
203
the \f2-r\f1 option in specified.
204
The two verbose modes differ only in the relative offsets they display,
205
the \f2-f\f1 option is relative to file start, whereas \f2-v\f1 shows
206
offsets relative to the start of the mapping.
209
See the \f3mread\f1 command.
211
\f3mwrite\f1 [ \f2-r\f1 ] [ \f2-S seed\f1 ]
212
Stores a byte into memory for a range within a mapping.
213
The default stored value is 'X', repeated to fill the range specified,
214
but this can be changed using the \f2-S\f1 option.
215
The memory stores are performed sequentially from the start offset by default,
216
but can also be done from the end backwards through the mapping if the \-\f2r\f1
220
See the \f3mwrite\f1 command.
223
Writes all modified copies of pages over the specified range (or entire
224
mapping if no range specified) to their backing storage locations.
225
Also, optionally invalidates (\f2-i\f1) so that subsequent references to
226
the pages will be obtained from their backing storage locations (instead
228
The flush can be done synchronously (\f2-s\f1) or asynchronously (\f2-a\f1).
231
See the \f3msync\f1 command.
233
\f3madvise\f1 [ \-\f2drwsw\f1 ] [ \f2offset\f1 \f2length\f1 ]
234
Modifies page cache behavior when operating on the current mapping.
235
The range arguments are required by some advise commands ([*] below).
236
With no arguments, the POSIX_MADV_NORMAL advice is implied (default readahead).
237
The \f2-d\f1 option says the pages will not be needed (POSIX_MADV_DONTNEED[*]).
238
The \f2-r\f1 option says to expect random page references (POSIX_MADV_RANDOM),
239
which sets readahead to zero.
240
The \f2-s\f1 option says to expect sequential page references
241
(POSIX_MADV_SEQUENTIAL), which doubles the default readahead on the file.
242
The \f2-w\f1 option advises the specified pages will be needed
243
again (POSIX_MADV_WILLNEED[*]) which forces the maximum readahead.
246
Dumps a list of pages or ranges of pages that are currently in core,
247
for the current memory mapping.
252
Display a list of all open files and memory mapped regions.
253
The current file and current mapping are distinguishable from
257
See the \f3print\f1 command.
263
See the \f3quit\f1 command.
266
List extended inode flags on the currently open file.
268
\f3chattr\f1 [ \f2+/\-riasAd\f1 ]
269
Change extended inode flags on the currently open file.
272
Suspend all write I/O requests to the filesystem of the current file.
273
Only available in expert mode and requires privileges.
276
Undo the effects of a filesystem freeze operation.
277
Only available in expert mode and requires privileges.
279
\f3inject\f1 [ \f2tag\f1 ]
280
Inject errors into a filesystem to observe filesystem behavior at
281
specific points under adverse conditions.
282
Without an argument, displays the list of error tags available.
283
Only available in expert mode and requires privileges.
285
\f3resblks\f1 [ \f2blocks\f1 ]
286
Get and/or set count of reserved filesystem blocks using the
287
XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system calls,
288
as described in \f2xfs\f1(5).
289
Note \-\- this can be useful for exercising out of space behavior.
290
Only available in expert mode and requires privileges.
292
\f3shutdown\f1 [ \f2\-f\f1 ]
293
Force the filesystem to shutdown (with or without flushing the log).
294
Only available in expert mode and requires privileges.
296
\f3stat\f1 [ \f2\-v\f1 ]
297
Selected statistics from \f2stat\f1(2) and the XFS_IOC_GETXATTR
298
system call from \f2xfs\f1(5) on the current file.
299
If the \f2-v\f1 option is specified, the atime (last access), mtime
300
(last modify), and ctime (last change) timestamps are also displayed.
303
Selected statistics from \f2statfs\f1(2) and the XFS_IOC_FSGEOMETRY
304
system call from \f2xfs\f1(5) on the filesystem where the current
added
removed
man/man8/xfs_io.8
