1xfs_io(8) System Manager's Manual xfs_io(8)
2
6 xfs_io - debug the I/O path of an XFS filesystem
7
9 xfs_io [ -adFfmrRstx ] [ -c cmd ] ... [ -p prog ] file
10
12 xfs_io is a debugging tool like xfs_db(8), but is aimed at examining
13 the regular file I/O paths rather than the raw XFS volume itself.
14 These code paths include not only the obvious read/write/mmap inter‐
15 faces for manipulating files, but also cover all of the XFS extensions
16 (such as space preallocation, additional inode flags, etc).
17
19 -c cmd xfs_io commands may be run interactively (the default) or as
20 arguments on the command line. Multiple -c arguments may be
21 given. The commands are run in the sequence given, then the
22 program exits.
23 -p prog Set the program name for prompts and some error messages, the
25 default value is xfs_io.
26 -F Allow file to reside in non-XFS (foreign) filesystems. This
28 mode has a restricted set of commands.
29 -f Create file if it does not already exist.
31 -r Open file read-only, initially. This is required if file is
33 immutable or append-only.
34 -x Expert mode. Dangerous commands are only available in this
36 mode. These commands also tend to require additional privi‐
37 leges.
38 The other open(2) options described below are also available from the
40 command line.
41
43 xfs_io maintains a number of open files and memory mappings. Files can
44 be initially opened on the command line (optionally), and additional
45 files can also be opened later.
46 xfs_io commands can be broken up into three groups. Some commands are
48 aimed at doing regular file I/O - read, write, sync, space prealloca‐
49 tion, etc.
50 The second set of commands exist for manipulating memory mapped regions
52 of a file - mapping, accessing, storing, unmapping, flushing, etc.
53 The remaining commands are for the navigation and display of data
55 structures relating to the open files, mappings, and the filesystems
56 where they reside.
57 Many commands have extensive online help. Use the help command for more
59 details on any command.
60
62 file [ N ]
63 Display a list of all open files and (optionally) switch to an
64 alternate current open file.
65 open [[ -FacdfrstR ] path ]
67 Closes the current file, and opens the file specified by path
68 instead. Without any arguments, displays statistics about the
69 current file - see the stat command.
70 -F allows non-XFS (foreign) files to be opened and operated
71 on with a restricted command set.
72 -a opens append-only (O_APPEND).
73 -d opens for direct I/O (O_DIRECT).
74 -f creates the file if it doesn't already exist (O_CREAT).
75 -r opens read-only (O_RDONLY).
76 -s opens for synchronous I/O (O_SYNC).
77 -t truncates on open (O_TRUNC).
78 -R marks the file as a realtime XFS file after opening it,
79 if it is not already marked as such.
80 o See the open command.
82 close Closes the current open file, marking the next open file as cur‐
84 rent (if one exists).
85 c See the close command.
87 pread [ -b bsize ] [ -v ] offset length
89 Reads a range of bytes in a specified blocksize from the given
90 offset.
91 -b can be used to set the blocksize into which the read(2)
92 requests will be split. The default blocksize is 4096
93 bytes.
94 -v dump the contents of the buffer after reading, by default
95 only the count of bytes actually read is dumped.
96 r See the pread command.
98 pwrite [ -i file ] [ -d ] [ -s skip ] [ -b size ] [ -S seed ] offset
100 length
101 Writes a range of bytes in a specified blocksize from the given
102 offset. The bytes written can be either a set pattern or read
103 in from another file before writing.
104 -i allows an input file to be specified as the source of the
105 data to be written.
106 -d causes direct I/O, rather than the usual buffered I/O, to
107 be used when reading the input file.
108 -s specifies the number of bytes to skip from the start of
109 the input file before starting to read.
110 -b used to set the blocksize into which the write(2)
111 requests will be split. The default blocksize is 4096
112 bytes.
113 -S used to set the (repeated) fill pattern which is used
114 when the data to write is not coming from a file. The
115 default buffer fill pattern value is 0xcdcdcdcd.
116 w See the pwrite command.
118 bmap [ -adlpv ] [ -n nx ]
120 Prints the block mapping for the current open file. Refer to the
121 xfs_bmap(8) manual page for complete documentation.
122 extsize [ -R | -D ] [ value ]
124 Display and/or modify the preferred extent size used when allo‐
125 cating space for the currently open file. If the -R option is
126 specified, a recursive descent is performed for all directory
127 entries below the currently open file (-D can be used to
128 restrict the output to directories only). If the target file is
129 a directory, then the inherited extent size is set for that
130 directory (new files created in that directory inherit that
131 extent size). The value should be specified in bytes, or using
132 one of the usual units suffixes (k, m, g, b, etc). The extent
133 size is always reported in units of bytes.
134 allocsp size 0
136 Sets the size of the file to size and zeroes any additional
137 space allocated using the XFS_IOC_ALLOCSP/XFS_IOC_FREESP system
138 call described in the xfsctl(3) manual page. allocsp and freesp
139 do exactly the same thing.
140 freesp size 0
142 See the allocsp command.
143 fadvise [ -r | -s | [[ -d | -n | -w ] offset length ]]
145 On platforms which support it, allows hints be given to the sys‐
146 tem regarding the expected I/O patterns on the file. The range
147 arguments are required by some advise commands ([*] below), and
148 the others must have no range arguments. With no arguments, the
149 POSIX_FADV_NORMAL advice is implied (default readahead).
150 -d the data will not be accessed again in the near future
151 (POSIX_FADV_DONTNEED[*]).
152 -n data will be accessed once and not be reused
153 (POSIX_FADV_NOREUSE[*]).
154 -r expect access to data in random order (POSIX_FADV_RAN‐
155 DOM), which sets readahead to zero.
156 -s expect access to data in sequential order
157 (POSIX_FADV_SEQUENTIAL), which doubles the default reada‐
158 head on the file.
159 -w advises the specified data will be needed again
160 (POSIX_FADV_WILLNEED[*]) which forces the maximum reada‐
161 head.
162 fdatasync
164 Calls fdatasync(2) to flush the file's in-core data to disk.
165 fsync Calls fsync(2) to flush all in-core file state to disk.
167 s See the fsync command.
169 resvsp offset length
171 Allocates reserved, unwritten space for part of a file using the
172 XFS_IOC_RESVSP system call described in the xfsctl(3) manual
173 page.
174 unresvsp offset length
176 Frees reserved space for part of a file using the
177 XFS_IOC_UNRESVSP system call described in the xfsctl(3) manual
178 page.
179 falloc [ -k ] offset length
181 Allocates reserved, unwritten space for part of a file using the
182 fallocate routine as described in the fallocate(3) manual page.
183 -k will set the FALLOC_FL_KEEP_SIZE flag as described in
184 fallocate(3).
185 truncate offset
187 Truncates the current file at the given offset using ftrun‐
188 cate(2).
189 sendfile -i srcfile | -f N [ offset length ]
191 On platforms which support it, allows a direct in-kernel copy
192 between two file descriptors. The current open file is the tar‐
193 get, the source must be specified as another open file (-f) or
194 by path (-i).
195
198 mmap [ N | [[ -rwx ] offset length ]]
199 With no arguments, mmap shows the current mappings. Specifying a
200 single numeric argument N sets the current mapping. If two argu‐
201 ments are specified (a range specified by offset and length), a
202 new mapping is created spanning the range, and the protection
203 mode can be given as a combination of PROT_READ (-r), PROT_WRITE
204 (-w), and PROT_EXEC (-x).
205 mm See the mmap command.
207 munmap Unmaps the current memory mapping.
209 mu See the munmap command.
211 mread [ -f | -v ] [ -r ] [ offset length ]
213 Accesses a segment of the current memory mapping, optionally
214 dumping it to the standard output stream (with -v or -f option)
215 for inspection. The accesses are performed sequentially from the
216 start offset by default, but can also be done from the end back‐
217 wards through the mapping if the -r option in specified. The
218 two verbose modes differ only in the relative offsets they dis‐
219 play, the -f option is relative to file start, whereas -v shows
220 offsets relative to the start of the mapping.
221 mr See the mread command.
223 mwrite [ -r ] [ -S seed ] [ offset length ]
225 Stores a byte into memory for a range within a mapping. The
226 default stored value is 'X', repeated to fill the range speci‐
227 fied, but this can be changed using the -S option. The memory
228 stores are performed sequentially from the start offset by
229 default, but can also be done from the end backwards through the
230 mapping if the -r option in specified.
231 mw See the mwrite command.
233 msync [ -i ] [ -a | -s ] [ offset length ]
235 Writes all modified copies of pages over the specified range (or
236 entire mapping if no range specified) to their backing storage
237 locations. Also, optionally invalidates (-i) so that subsequent
238 references to the pages will be obtained from their backing
239 storage locations (instead of cached copies). The flush can be
240 done synchronously (-s) or asynchronously (-a).
241 ms See the msync command.
243 madvise [ -d | -r | -s | -w ] [ offset length ]
245 Modifies page cache behavior when operating on the current map‐
246 ping. The range arguments are required by some advise commands
247 ([*] below). With no arguments, the POSIX_MADV_NORMAL advice is
248 implied (default readahead).
249 -d the pages will not be needed (POSIX_MADV_DONTNEED[*]).
250 -r expect random page references (POSIX_MADV_RANDOM), which
251 sets readahead to zero.
252 -s expect sequential page references (POSIX_MADV_SEQUEN‐
253 TIAL), which doubles the default readahead on the file.
254 -w advises the specified pages will be needed again
255 (POSIX_MADV_WILLNEED[*]) which forces the maximum reada‐
256 head.
257 mincore
259 Dumps a list of pages or ranges of pages that are currently in
260 core, for the current memory mapping.
261
264 print Display a list of all open files and memory mapped regions. The
265 current file and current mapping are distinguishable from any
266 others.
267 p See the print command.
269 quit Exit xfs_io.
271 q See the quit command.
273 lsattr [ -R | -D | -a | -v ]
275 List extended inode flags on the currently open file. If the -R
276 option is specified, a recursive descent is performed for all
277 directory entries below the currently open file (-D can be used
278 to restrict the output to directories only). This is a depth
279 first descent, it does not follow symlinks and it also does not
280 cross mount points.
281 chattr [ -R | -D ] [ +/-riasAdtPneEfS ]
283 Change extended inode flags on the currently open file. The -R
284 and -D options have the same meaning as above. The mapping
285 between each letter and the inode flags (refer to xfsctl(3) for
286 the full list) is available via the help command.
287 freeze Suspend all write I/O requests to the filesystem of the current
289 file. Only available in expert mode and requires privileges.
290 thaw Undo the effects of a filesystem freeze operation. Only avail‐
292 able in expert mode and requires privileges.
293 inject [ tag ]
295 Inject errors into a filesystem to observe filesystem behavior
296 at specific points under adverse conditions. Without the tag
297 argument, displays the list of error tags available. Only
298 available in expert mode and requires privileges.
299 resblks [ blocks ]
301 Get and/or set count of reserved filesystem blocks using the
302 XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system calls. Note
303 -- this can be useful for exercising out of space behavior.
304 Only available in expert mode and requires privileges.
305 shutdown [ -f ]
307 Force the filesystem to shutdown (with or without flushing the
308 log). Only available in expert mode and requires privileges.
309 stat [ -v ]
311 Selected statistics from stat(2) and the XFS_IOC_GETXATTR system
312 call on the current file. If the -v option is specified, the
313 atime (last access), mtime (last modify), and ctime (last
314 change) timestamps are also displayed.
315 statfs Selected statistics from statfs(2) and the XFS_IOC_FSGEOMETRY
317 system call on the filesystem where the current file resides.
318 parent [ -cpv ]
320 By default this command prints out the parent inode numbers,
321 inode generation numbers and basenames of all the hardlinks
322 which point to the inode of the current file.
323 -p the output is similar to the default output except path‐
324 names up to the mount-point are printed out instead of
325 the component name.
326 -c the file's filesystem will check all the parent
327 attributes for consistency.
328 -v verbose output will be printed.
329 [NOTE: Not currently operational on Linux.]
330
333 mkfs.xfs(8), xfsctl(3), xfs_bmap(8), xfs_db(8), xfs(5), fdatasync(2),
334 fstat(2), fstatfs(2), fsync(2), ftruncate(2), mmap(2), msync(2),
335 open(2), pread(2), pwrite(2).
336 xfs_io(8)