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 [ -adfmrRstxT ] [ -c cmd ] ... [ -p prog ] file
10 xfs_io -V
11
13 xfs_io is a debugging tool like xfs_db(8), but is aimed at examining
14 the regular file I/O paths rather than the raw XFS volume itself.
15 These code paths include not only the obvious read/write/mmap inter‐
16 faces for manipulating files, but also cover all of the XFS extensions
17 (such as space preallocation, additional inode flags, etc).
18
20 -c cmd xfs_io commands may be run interactively (the default) or as
21 arguments on the command line. Multiple -c arguments may be
22 given. The commands are run in the sequence given, then the
23 program exits.
24 -p prog Set the program name for prompts and some error messages, the
26 default value is xfs_io.
27 -f Create file if it does not already exist.
29 -r Open file read-only, initially. This is required if file is
31 immutable or append-only.
32 -x Expert mode. Dangerous commands are only available in this
34 mode. These commands also tend to require additional privi‐
35 leges.
36 -V Prints the version number and exits.
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 [[ -acdfrstRT ] 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 -a opens append-only (O_APPEND).
71 -d opens for direct I/O (O_DIRECT).
72 -f creates the file if it doesn't already exist (O_CREAT).
73 -r opens read-only (O_RDONLY).
74 -s opens for synchronous I/O (O_SYNC).
75 -t truncates on open (O_TRUNC).
76 -n opens in non-blocking mode if possible (O_NONBLOCK).
77 -T create a temporary file not linked into the filesystem
78 namespace (O_TMPFILE). The pathname passed must refer to
79 a directory which is treated as virtual parent for the
80 newly created invisible file. Can not be used together
81 with the -r option.
82 -R marks the file as a realtime XFS file after opening it,
83 if it is not already marked as such.
84 o See the open command.
86 close Closes the current open file, marking the next open file as cur‐
88 rent (if one exists).
89 c See the close command.
91 pread [ -b bsize ] [ -v ] [ -FBR [ -Z seed ] ] [ -V vectors ] offset
93 length
94 Reads a range of bytes in a specified blocksize from the given
95 offset.
96 -b can be used to set the blocksize into which the read(2)
97 requests will be split. The default blocksize is 4096
98 bytes.
99 -v dump the contents of the buffer after reading, by default
100 only the count of bytes actually read is dumped.
101 -F read the buffers in a forwards sequential direction.
102 -B read the buffers in a reserve sequential direction.
103 -R read the buffers in the give range in a random order.
104 -Z seed
105 specify the random number seed used for random reads.
106 -V vectors
107 Use the vectored IO read syscall preadv(2) with a number
108 of blocksize length iovecs. The number of iovecs is set
109 by the vectors parameter.
110 r See the pread command.
112 pwrite [ -i file ] [ -d ] [ -s skip ] [ -b size ] [ -S seed ] [ -FBR [
114 -Z zeed ] ] [ -wW ] [ -V vectors ] offset length
115 Writes a range of bytes in a specified blocksize from the given
116 offset. The bytes written can be either a set pattern or read
117 in from another file before writing.
118 -i allows an input file to be specified as the source of the
119 data to be written.
120 -d causes direct I/O, rather than the usual buffered I/O, to
121 be used when reading the input file.
122 -s specifies the number of bytes to skip from the start of
123 the input file before starting to read.
124 -b used to set the blocksize into which the write(2)
125 requests will be split. The default blocksize is 4096
126 bytes.
127 -S used to set the (repeated) fill pattern which is used
128 when the data to write is not coming from a file. The
129 default buffer fill pattern value is 0xcdcdcdcd.
130 -F write the buffers in a forwards sequential direction.
131 -B write the buffers in a reserve sequential direction.
132 -R write the buffers in the give range in a random order.
133 -Z seed
134 specify the random number seed used for random write
135 -w call fdatasync(2) once all writes are complete (included
136 in timing results)
137 -W call fsync(2) once all writes are complete (included in
138 timing results)
139 -V vectors
140 Use the vectored IO write syscall pwritev(2) with a num‐
141 ber of blocksize length iovecs. The number of iovecs is
142 set by the vectors parameter.
143 w See the pwrite command.
145 bmap [ -adlpv ] [ -n nx ]
147 Prints the block mapping for the current open file. Refer to the
148 xfs_bmap(8) manual page for complete documentation.
149 fiemap [ -alv ] [ -n nx ]
151 Prints the block mapping for the current open file using the
152 fiemap ioctl. Options behave as described in the xfs_bmap(8)
153 manual page.
154 extsize [ -R | -D ] [ value ]
156 Display and/or modify the preferred extent size used when allo‐
157 cating space for the currently open file. If the -R option is
158 specified, a recursive descent is performed for all directory
159 entries below the currently open file (-D can be used to
160 restrict the output to directories only). If the target file is
161 a directory, then the inherited extent size is set for that
162 directory (new files created in that directory inherit that
163 extent size). The value should be specified in bytes, or using
164 one of the usual units suffixes (k, m, g, b, etc). The extent
165 size is always reported in units of bytes.
166 allocsp size 0
168 Sets the size of the file to size and zeroes any additional
169 space allocated using the XFS_IOC_ALLOCSP/XFS_IOC_FREESP system
170 call described in the xfsctl(3) manual page. allocsp and freesp
171 do exactly the same thing.
172 freesp size 0
174 See the allocsp command.
175 fadvise [ -r | -s | [[ -d | -n | -w ] offset length ]]
177 On platforms which support it, allows hints be given to the sys‐
178 tem regarding the expected I/O patterns on the file. The range
179 arguments are required by some advise commands ([*] below), and
180 the others must have no range arguments. With no arguments, the
181 POSIX_FADV_NORMAL advice is implied (default readahead).
182 -d the data will not be accessed again in the near future
183 (POSIX_FADV_DONTNEED[*]).
184 -n data will be accessed once and not be reused
185 (POSIX_FADV_NOREUSE[*]).
186 -r expect access to data in random order (POSIX_FADV_RAN‐
187 DOM), which sets readahead to zero.
188 -s expect access to data in sequential order
189 (POSIX_FADV_SEQUENTIAL), which doubles the default reada‐
190 head on the file.
191 -w advises the specified data will be needed again
192 (POSIX_FADV_WILLNEED[*]) which forces the maximum reada‐
193 head.
194 fdatasync
196 Calls fdatasync(2) to flush the file's in-core data to disk.
197 fsync Calls fsync(2) to flush all in-core file state to disk.
199 s See the fsync command.
201 sync_range [ -a | -b | -w ] offset length
203 On platforms which support it, allows control of syncing a range
204 of the file to disk. With no options, SYNC_FILE_RANGE_WRITE is
205 implied on the range supplied.
206 -a wait for IO in the given range to finish after writing
207 (SYNC_FILE_RANGE_WAIT_AFTER).
208 -b wait for IO in the given range to finish before writing
209 (SYNC_FILE_RANGE_WAIT_BEFORE).
210 -w start writeback of dirty data in the given range
211 (SYNC_FILE_RANGE_WRITE).
212 sync Calls sync(2) to flush all filesystems' in-core data to disk.
214 syncfs Calls syncfs(2) to flush this filesystem's in-core data to disk.
216 resvsp offset length
218 Allocates reserved, unwritten space for part of a file using the
219 XFS_IOC_RESVSP system call described in the xfsctl(3) manual
220 page.
221 unresvsp offset length
223 Frees reserved space for part of a file using the
224 XFS_IOC_UNRESVSP system call described in the xfsctl(3) manual
225 page.
226 falloc [ -k ] offset length
228 Allocates reserved, unwritten space for part of a file using the
229 fallocate routine as described in the fallocate(2) manual page.
230 -k will set the FALLOC_FL_KEEP_SIZE flag as described in
231 fallocate(2).
232 fcollapse offset length
234 Call fallocate with FALLOC_FL_COLLAPSE_RANGE flag as described
235 in the fallocate(2) manual page to de-allocates blocks and elim‐
236 inates the hole created in this process by shifting data blocks
237 into the hole.
238 finsert offset length
240 Call fallocate with FALLOC_FL_INSERT_RANGE flag as described in
241 the fallocate(2) manual page to create the hole by shifting data
242 blocks.
243 fpunch offset length
245 Punches (de-allocates) blocks in the file by calling fallocate
246 with the FALLOC_FL_PUNCH_HOLE flag as described in the fallo‐
247 cate(2) manual page.
248 fzero offset length
250 Call fallocate with FALLOC_FL_ZERO_RANGE flag as described in
251 the fallocate(2) manual page to allocate and zero blocks within
252 the range.
253 zero offset length
255 Call xfsctl with XFS_IOC_ZERO_RANGE as described in the
256 xfsctl(3) manual page to allocate and zero blocks within the
257 range.
258 truncate offset
260 Truncates the current file at the given offset using ftrun‐
261 cate(2).
262 sendfile -i srcfile | -f N [ offset length ]
264 On platforms which support it, allows a direct in-kernel copy
265 between two file descriptors. The current open file is the tar‐
266 get, the source must be specified as another open file (-f) or
267 by path (-i).
268 readdir [ -v ] [ -o offset ] [ -l length ]
270 Read a range of directory entries from a given offset of a
271 directory.
272 -v verbose mode - dump dirent content as defined in read‐
273 dir(3)
274 -o specify starting offset
275 -l specify total length to read (in bytes)
276 seek -a | -d | -h [ -r ] [ -s ] offset
279 On platforms that support the lseek(2) SEEK_DATA and
280 SEEK_HOLE options, display the offsets of the specified
281 segments.
282 -a Display both data and hole segments starting at
283 the specified offset.
284 -d Display the data segment starting at the specified
285 offset.
286 -h Display the hole segment starting at the specified
287 offset.
288 -r Recursively display all the specified segments
289 starting at the specified offset.
290 -s Display the starting lseek(2) offset. This offset
291 will be a calculated value when both data and
292 holes are displayed together or performing a recu‐
293 sively display.
294 reflink [ -C ] [ -q ] src_file [src_offset dst_offset
297 length]
298 On filesystems that support the
299 XFS_IOC_CLONE_RANGE or BTRFS_IOC_CLONE_RANGE
300 ioctls, map length bytes at offset dst_offset in
301 the open file to the same physical blocks that are
302 mapped at offset src_offset in the file src_file ,
303 replacing any contents that may already have been
304 there. If a program writes into a reflinked block
305 range of either file, the dirty blocks will be
306 cloned, written to, and remapped ("copy on write")
307 in the affected file, leaving the other file(s)
308 unchanged. If src_offset, dst_offset, and length
309 are omitted, all contents of src_file will be
310 reflinked into the open file.
311 -C Print timing statistics in a condensed for‐
312 mat.
313 -q Do not print timing statistics at all.
314 dedupe [ -C ] [ -q ] src_file src_offset dst_off‐
317 set length
318 On filesystems that support the
319 XFS_IOC_FILE_EXTENT_SAME or
320 BTRFS_IOC_FILE_EXTENT_SAME ioctls, map
321 length bytes at offset dst_offset in the
322 open file to the same physical blocks that
323 are mapped at offset src_offset in the file
324 src_file , but only if the contents of both
325 ranges are identical. This is known as
326 block-based deduplication. If a program
327 writes into a reflinked block range of
328 either file, the dirty blocks will be
329 cloned, written to, and remapped ("copy on
330 write") in the affected file, leaving the
331 other file(s) unchanged.
332 -C Print timing statistics in a con‐
333 densed format.
334 -q Do not print timing statistics at
335 all.
336
338 mmap [ N | [[ -rwx ] offset length ]]
339 With no arguments, mmap shows the current
340 mappings. Specifying a single numeric argu‐
341 ment N sets the current mapping. If two
342 arguments are specified (a range specified
343 by offset and length), a new mapping is
344 created spanning the range, and the protec‐
345 tion mode can be given as a combination of
346 PROT_READ (-r), PROT_WRITE (-w), and
347 PROT_EXEC (-x).
348 mm See the mmap command.
349 mremap [ -f ] [ -m ] new_length
350 Changes the current mapping size to
351 new_length. Whether the mapping may be
352 moved is controlled by the flags passed;
353 MREMAP_FIXED (-f), or MREMAP_MAYMOVE (-m).
354 mrm See the mremap command.
355 munmap Unmaps the current memory mapping.
356 mu See the munmap command.
357 mread [ -f | -v ] [ -r ] [ offset length ]
358 Accesses a segment of the current memory
359 mapping, optionally dumping it to the stan‐
360 dard output stream (with -v or -f option)
361 for inspection. The accesses are performed
362 sequentially from the start offset by
363 default, but can also be done from the end
364 backwards through the mapping if the -r
365 option in specified. The two verbose modes
366 differ only in the relative offsets they
367 display, the -f option is relative to file
368 start, whereas -v shows offsets relative to
369 the start of the mapping.
370 mr See the mread command.
371 mwrite [ -r ] [ -S seed ] [ offset length ]
372 Stores a byte into memory for a range
373 within a mapping. The default stored value
374 is 'X', repeated to fill the range speci‐
375 fied, but this can be changed using the -S
376 option. The memory stores are performed
377 sequentially from the start offset by
378 default, but can also be done from the end
379 backwards through the mapping if the -r
380 option in specified.
381 mw See the mwrite command.
382 msync [ -i ] [ -a | -s ] [ offset length ]
383 Writes all modified copies of pages over
384 the specified range (or entire mapping if
385 no range specified) to their backing stor‐
386 age locations. Also, optionally invali‐
387 dates (-i) so that subsequent references to
388 the pages will be obtained from their back‐
389 ing storage locations (instead of cached
390 copies). The flush can be done syn‐
391 chronously (-s) or asynchronously (-a).
392 ms See the msync command.
393 madvise [ -d | -r | -s | -w ] [ offset length ]
394 Modifies page cache behavior when operating
395 on the current mapping. The range argu‐
396 ments are required by some advise commands
397 ([*] below). With no arguments, the
398 POSIX_MADV_NORMAL advice is implied
399 (default readahead).
400 -d the pages will not be needed
401 (POSIX_MADV_DONTNEED[*]).
402 -r expect random page references
403 (POSIX_MADV_RANDOM), which sets
404 readahead to zero.
405 -s expect sequential page references
406 (POSIX_MADV_SEQUENTIAL), which dou‐
407 bles the default readahead on the
408 file.
409 -w advises the specified pages will be
410 needed again (POSIX_MADV_WILL‐
411 NEED[*]) which forces the maximum
412 readahead.
413 mincore
415 Dumps a list of pages or ranges of pages
416 that are currently in core, for the current
417 memory mapping.
418
421 help [ command ]
422 Display a brief description of one or all
423 commands.
424 print Display a list of all open files and memory
426 mapped regions. The current file and cur‐
427 rent mapping are distinguishable from any
428 others.
429 p See the print command.
431 quit Exit xfs_io.
433 q See the quit command.
435 lsattr [ -R | -D | -a | -v ]
437 List extended inode flags on the currently
438 open file. If the -R option is specified, a
439 recursive descent is performed for all
440 directory entries below the currently open
441 file (-D can be used to restrict the output
442 to directories only). This is a depth
443 first descent, it does not follow symlinks
444 and it also does not cross mount points.
445 chattr [ -R | -D ] [ +/-riasAdtPneEfS ]
447 Change extended inode flags on the cur‐
448 rently open file. The -R and -D options
449 have the same meaning as above. The mapping
450 between each letter and the inode flags
451 (refer to xfsctl(3) for the full list) is
452 available via the help command.
453 freeze Suspend all write I/O requests to the
455 filesystem of the current file. Only
456 available in expert mode and requires priv‐
457 ileges.
458 thaw Undo the effects of a filesystem freeze
460 operation. Only available in expert mode
461 and requires privileges.
462 flink path
464 Link the currently open file descriptor
465 into the filesystem namespace.
466 inject [ tag ]
468 Inject errors into a filesystem to observe
469 filesystem behavior at specific points
470 under adverse conditions. Without the tag
471 argument, displays the list of error tags
472 available. Only available in expert mode
473 and requires privileges.
474 resblks [ blocks ]
476 Get and/or set count of reserved filesystem
477 blocks using the XFS_IOC_GET_RESBLKS or
478 XFS_IOC_SET_RESBLKS system calls. Note --
479 this can be useful for exercising out of
480 space behavior. Only available in expert
481 mode and requires privileges.
482 shutdown [ -f ]
484 Force the filesystem to shutdown (with or
485 without flushing the log). Only available
486 in expert mode and requires privileges.
487 stat [ -v ]
489 Selected statistics from stat(2) and the
490 XFS_IOC_GETXATTR system call on the current
491 file. If the -v option is specified, the
492 atime (last access), mtime (last modify),
493 and ctime (last change) timestamps are also
494 displayed.
495 statfs Selected statistics from statfs(2) and the
497 XFS_IOC_FSGEOMETRY system call on the
498 filesystem where the current file resides.
499 chproj [ -R|-D ]
501 Modifies the project identifier associated
502 with the current path. The -R option will
503 recursively descend if the current path is
504 a directory. The -D option will also recur‐
505 sively descend, only setting modifying
506 projects on subdirectories. See the
507 xfs_quota(8) manual page for more informa‐
508 tion about project identifiers.
509 lsproj [ -R|-D ]
511 Displays the project identifier associated
512 with the current path. The -R and -D
513 options behave as described above, in
514 chproj.
515 parent [ -cpv ]
517 By default this command prints out the par‐
518 ent inode numbers, inode generation numbers
519 and basenames of all the hardlinks which
520 point to the inode of the current file.
521 -p the output is similar to the default
522 output except pathnames up to the
523 mount-point are printed out instead
524 of the component name.
525 -c the file's filesystem will check all
526 the parent attributes for consis‐
527 tency.
528 -v verbose output will be printed.
529 [NOTE: Not currently operational on Linux.]
530 label [ -c | -s label ]
532 On filesystems that support online label
533 manipulation, get, set, or clear the
534 filesystem label. With no options, print
535 the current filesystem label. The -c
536 option clears the filesystem label by set‐
537 ting it to the null string. The -s label
538 option sets the filesystem label to label.
539 If the label is longer than the filesystem
540 will accept, xfs_io will print an error
541 message. XFS filesystem labels can be at
542 most 12 characters long.
543
545 mkfs.xfs(8), xfsctl(3), xfs_bmap(8), xfs_db(8),
546 xfs(5), fdatasync(2), fstat(2), fstatfs(2),
547 fsync(2), ftruncate(2), mmap(2), msync(2),
548 open(2), pread(2), pwrite(2), readdir(3).
549 xfs_io(8)