3 xfs_io \- debug the I/O path of an XFS filesystem
20 is a debugging tool like
22 but is aimed at examining the regular file I/O paths rather than the
23 raw XFS volume itself.
24 These code paths include not only the obvious read/write/mmap interfaces
25 for manipulating files, but also cover all of the XFS extensions (such
26 as space preallocation, additional inode flags, etc).
31 commands may be run interactively (the default) or as arguments on
32 the command line. Multiple
34 arguments may be given. The commands are run in the sequence given,
35 then the program exits.
38 Set the program name for prompts and some error messages,
45 if it does not already exist.
50 read-only, initially. This is required if
52 is immutable or append-only.
55 Expert mode. Dangerous commands are only available in this mode.
56 These commands also tend to require additional privileges.
59 Prints the version number and exits.
63 options described below are also available from the command line.
66 maintains a number of open files and memory mappings.
67 Files can be initially opened on the command line (optionally),
68 and additional files can also be opened later.
71 commands can be broken up into three groups.
72 Some commands are aimed at doing regular file I/O - read, write,
73 sync, space preallocation, etc.
75 The second set of commands exist for manipulating memory mapped regions
76 of a file - mapping, accessing, storing, unmapping, flushing, etc.
78 The remaining commands are for the navigation and display of data
79 structures relating to the open files, mappings, and the filesystems
82 Many commands have extensive online help. Use the
84 command for more details on any command.
88 Display a list of all open files and (optionally) switch to an alternate
91 .BI "open [[ \-acdfrstRT ] " path " ]"
92 Closes the current file, and opens the file specified by
94 instead. Without any arguments, displays statistics about the current
102 opens append-only (O_APPEND).
105 opens for direct I/O (O_DIRECT).
108 creates the file if it doesn't already exist (O_CREAT).
111 opens read-only (O_RDONLY).
114 opens for synchronous I/O (O_SYNC).
117 truncates on open (O_TRUNC).
120 opens in non-blocking mode if possible (O_NONBLOCK).
123 create a temporary file not linked into the filesystem namespace
124 (O_TMPFILE). The pathname passed must refer to a directory which
125 is treated as virtual parent for the newly created invisible file.
126 Can not be used together with the
131 marks the file as a realtime XFS file after
132 opening it, if it is not already marked as such.
142 Closes the current open file, marking the next open file as current
150 .BI "pread [ \-b " bsize " ] [ \-v ] [ \-FBR [ \-Z " seed " ] ] [ \-V " vectors " ] " "offset length"
151 Reads a range of bytes in a specified blocksize from the given
157 can be used to set the blocksize into which the
159 requests will be split. The default blocksize is 4096 bytes.
162 dump the contents of the buffer after reading,
163 by default only the count of bytes actually read is dumped.
166 read the buffers in a forwards sequential direction.
169 read the buffers in a reserve sequential direction.
172 read the buffers in the give range in a random order.
175 specify the random number seed used for random reads.
178 Use the vectored IO read syscall
180 with a number of blocksize length iovecs. The number of iovecs is set by the
191 .BI "pwrite [ \-i " file " ] [ \-d ] [ \-s " skip " ] [ \-b " size " ] [ \-S " seed " ] [ \-FBR [ \-Z " zeed " ] ] [ \-wW ] [ \-V " vectors " ] " "offset length"
192 Writes a range of bytes in a specified blocksize from the given
194 The bytes written can be either a set pattern or read in from another
202 to be specified as the source of the data to be written.
205 causes direct I/O, rather than the usual buffered
206 I/O, to be used when reading the input file.
209 specifies the number of bytes to
211 from the start of the input file before starting to read.
214 used to set the blocksize into which the
216 requests will be split. The default blocksize is 4096 bytes.
219 used to set the (repeated) fill pattern which
220 is used when the data to write is not coming from a file.
221 The default buffer fill pattern value is 0xcdcdcdcd.
224 write the buffers in a forwards sequential direction.
227 write the buffers in a reserve sequential direction.
230 write the buffers in the give range in a random order.
233 specify the random number seed used for random write
238 once all writes are complete (included in timing results)
243 once all writes are complete (included in timing results)
246 Use the vectored IO write syscall
248 with a number of blocksize length iovecs. The number of iovecs is set by the
259 .BI "bmap [ \-adlpv ] [ \-n " nx " ]"
260 Prints the block mapping for the current open file. Refer to the
262 manual page for complete documentation.
264 .BI "fiemap [ \-alv ] [ \-n " nx " ]"
265 Prints the block mapping for the current open file using the fiemap
266 ioctl. Options behave as described in the
270 .BI "extsize [ \-R | \-D ] [ " value " ]"
271 Display and/or modify the preferred extent size used when allocating
272 space for the currently open file. If the
274 option is specified, a recursive descent is performed
275 for all directory entries below the currently open file
277 can be used to restrict the output to directories only).
278 If the target file is a directory, then the inherited extent size
279 is set for that directory (new files created in that directory
280 inherit that extent size).
283 should be specified in bytes, or using one of the usual units suffixes
284 (k, m, g, b, etc). The extent size is always reported in units of bytes.
286 .BI "allocsp " size " 0"
287 Sets the size of the file to
289 and zeroes any additional space allocated using the
290 XFS_IOC_ALLOCSP/XFS_IOC_FREESP system call described in the
296 do exactly the same thing.
298 .BI "freesp " size " 0"
303 .BI "fadvise [ \-r | \-s | [[ \-d | \-n | \-w ] " "offset length " ]]
304 On platforms which support it, allows hints be given to the system
305 regarding the expected I/O patterns on the file.
306 The range arguments are required by some advise commands ([*] below), and
307 the others must have no range arguments.
308 With no arguments, the POSIX_FADV_NORMAL advice is implied (default readahead).
313 the data will not be accessed again in the near future (POSIX_FADV_DONTNEED[*]).
316 data will be accessed once and not be reused (POSIX_FADV_NOREUSE[*]).
319 expect access to data in random order (POSIX_FADV_RANDOM), which sets readahead to zero.
322 expect access to data in sequential order (POSIX_FADV_SEQUENTIAL),
323 which doubles the default readahead on the file.
326 advises the specified data will be needed again (POSIX_FADV_WILLNEED[*])
327 which forces the maximum readahead.
334 to flush the file's in-core data to disk.
339 to flush all in-core file state to disk.
346 .BI "sync_range [ \-a | \-b | \-w ] offset length "
347 On platforms which support it, allows control of syncing a range of the file to
348 disk. With no options, SYNC_FILE_RANGE_WRITE is implied on the range supplied.
353 wait for IO in the given range to finish after writing
354 (SYNC_FILE_RANGE_WAIT_AFTER).
357 wait for IO in the given range to finish before writing
358 (SYNC_FILE_RANGE_WAIT_BEFORE).
361 start writeback of dirty data in the given range (SYNC_FILE_RANGE_WRITE).
368 to flush all filesystems' in-core data to disk.
373 to flush this filesystem's in-core data to disk.
375 .BI resvsp " offset length"
376 Allocates reserved, unwritten space for part of a file using the
377 XFS_IOC_RESVSP system call described in the
381 .BI unresvsp " offset length"
382 Frees reserved space for part of a file using the XFS_IOC_UNRESVSP
383 system call described in the
387 .BI "falloc [ \-k ]" " offset length"
388 Allocates reserved, unwritten space for part of a file using the
389 fallocate routine as described in the
396 will set the FALLOC_FL_KEEP_SIZE flag as described in
401 .BI fcollapse " offset length"
402 Call fallocate with FALLOC_FL_COLLAPSE_RANGE flag as described in the
404 manual page to de-allocates blocks and eliminates the hole created in this process
405 by shifting data blocks into the hole.
407 .BI finsert " offset length"
408 Call fallocate with FALLOC_FL_INSERT_RANGE flag as described in the
410 manual page to create the hole by shifting data blocks.
412 .BI fpunch " offset length"
413 Punches (de-allocates) blocks in the file by calling fallocate with
414 the FALLOC_FL_PUNCH_HOLE flag as described in the
418 .BI fzero " offset length"
419 Call fallocate with FALLOC_FL_ZERO_RANGE flag as described in the
421 manual page to allocate and zero blocks within the range.
423 .BI truncate " offset"
424 Truncates the current file at the given offset using
427 .BI "sendfile \-i " srcfile " | \-f " N " [ " "offset length " ]
428 On platforms which support it, allows a direct in-kernel copy between
429 two file descriptors. The current open file is the target, the source
430 must be specified as another open file
435 .BI "readdir [ -v ] [ -o " offset " ] [ -l " length " ] "
436 Read a range of directory entries from a given offset of a directory.
441 verbose mode - dump dirent content as defined in
456 .BI "seek \-a | \-d | \-h [ \-r ] [ \-s ] offset"
457 On platforms that support the
462 options, display the offsets of the specified segments.
471 segments starting at the specified
477 segment starting at the specified
483 segment starting at the specified
487 Recursively display all the specified segments starting at the specified
491 Display the starting lseek(2) offset. This offset will be a calculated value when
492 both data and holes are displayed together or performing a recusively display.
497 .BI "reflink [ \-C ] [ \-q ] src_file [src_offset dst_offset length]"
498 On filesystems that support the
499 .B XFS_IOC_CLONE_RANGE
501 .B BTRFS_IOC_CLONE_RANGE
506 in the open file to the same physical blocks that are mapped at offset
510 , replacing any contents that may already have been there. If a program
511 writes into a reflinked block range of either file, the dirty blocks will be
512 cloned, written to, and remapped ("copy on write") in the affected file,
513 leaving the other file(s) unchanged. If src_offset, dst_offset, and length
514 are omitted, all contents of src_file will be reflinked into the open file.
519 Print timing statistics in a condensed format.
522 Do not print timing statistics at all.
527 .BI "dedupe [ \-C ] [ \-q ] src_file src_offset dst_offset length"
528 On filesystems that support the
529 .B XFS_IOC_FILE_EXTENT_SAME
531 .B BTRFS_IOC_FILE_EXTENT_SAME
536 in the open file to the same physical blocks that are mapped at offset
540 , but only if the contents of both ranges are identical. This is known as
541 block-based deduplication. If a program writes into a reflinked block range of
542 either file, the dirty blocks will be cloned, written to, and remapped ("copy
543 on write") in the affected file, leaving the other file(s) unchanged.
548 Print timing statistics in a condensed format.
551 Do not print timing statistics at all.
553 .SH MEMORY MAPPED I/O COMMANDS
555 .BI "mmap [ " N " | [[ \-rwx ] " "offset length " ]]
558 shows the current mappings. Specifying a single numeric argument
560 sets the current mapping. If two arguments are specified (a range specified by
564 a new mapping is created spanning the range, and the protection mode can
565 be given as a combination of PROT_READ
577 .BI "mremap [ \-f ] [ \-m ] " new_length
578 Changes the current mapping size to
580 Whether the mapping may be moved is controlled by the flags passed;
592 Unmaps the current memory mapping.
599 .BI "mread [ \-f | \-v ] [ \-r ] [" " offset length " ]
600 Accesses a segment of the current memory mapping, optionally dumping it to
601 the standard output stream (with
605 option) for inspection. The accesses are performed sequentially from the start
607 by default, but can also be done from the end backwards through the
611 The two verbose modes differ only in the relative offsets they display, the
613 option is relative to file start, whereas
615 shows offsets relative to the start of the mapping.
622 .BI "mwrite [ \-r ] [ \-S " seed " ] [ " "offset length " ]
623 Stores a byte into memory for a range within a mapping.
624 The default stored value is 'X', repeated to fill the range specified,
625 but this can be changed using the
628 The memory stores are performed sequentially from the start offset by default,
629 but can also be done from the end backwards through the mapping if the
638 .BI "msync [ \-i ] [ \-a | \-s ] [ " "offset length " ]
639 Writes all modified copies of pages over the specified range (or entire
640 mapping if no range specified) to their backing storage locations.
641 Also, optionally invalidates
643 so that subsequent references to the pages will be obtained from their
644 backing storage locations (instead of cached copies).
645 The flush can be done synchronously
655 .BI "madvise [ \-d | \-r | \-s | \-w ] [ " "offset length " ]
656 Modifies page cache behavior when operating on the current mapping.
657 The range arguments are required by some advise commands ([*] below).
658 With no arguments, the POSIX_MADV_NORMAL advice is implied (default readahead).
663 the pages will not be needed (POSIX_MADV_DONTNEED[*]).
666 expect random page references (POSIX_MADV_RANDOM), which sets readahead to zero.
669 expect sequential page references (POSIX_MADV_SEQUENTIAL),
670 which doubles the default readahead on the file.
673 advises the specified pages will be needed again (POSIX_MADV_WILLNEED[*])
674 which forces the maximum readahead.
679 Dumps a list of pages or ranges of pages that are currently in core,
680 for the current memory mapping.
685 Display a list of all open files and memory mapped regions.
686 The current file and current mapping are distinguishable from
703 .BR lsattr " [ " \-R " | " \-D " | " \-a " | " \-v " ]"
704 List extended inode flags on the currently open file. If the
706 option is specified, a recursive descent is performed
707 for all directory entries below the currently open file
709 can be used to restrict the output to directories only).
710 This is a depth first descent, it does not follow symlinks and
711 it also does not cross mount points.
713 .BR chattr " [ " \-R " | " \-D " ] [ " + / \-riasAdtPneEfS " ]"
714 Change extended inode flags on the currently open file. The
718 options have the same meaning as above. The mapping between each
719 letter and the inode flags (refer to
721 for the full list) is available via the
726 Suspend all write I/O requests to the filesystem of the current file.
727 Only available in expert mode and requires privileges.
730 Undo the effects of a filesystem freeze operation.
731 Only available in expert mode and requires privileges.
734 Link the currently open file descriptor into the filesystem namespace.
736 .BI "inject [ " tag " ]"
737 Inject errors into a filesystem to observe filesystem behavior at
738 specific points under adverse conditions. Without the
740 argument, displays the list of error tags available.
741 Only available in expert mode and requires privileges.
743 .BI "resblks [ " blocks " ]"
744 Get and/or set count of reserved filesystem blocks using the
745 XFS_IOC_GET_RESBLKS or XFS_IOC_SET_RESBLKS system calls.
746 Note \-\- this can be useful for exercising out of space behavior.
747 Only available in expert mode and requires privileges.
749 .BR shutdown " [ " \-f " ]"
750 Force the filesystem to shutdown (with or without flushing the log).
751 Only available in expert mode and requires privileges.
753 .BR stat " [ " \-v " ]"
754 Selected statistics from
756 and the XFS_IOC_GETXATTR system call on the current file. If the
758 option is specified, the atime (last access), mtime
759 (last modify), and ctime (last change) timestamps are also displayed.
762 Selected statistics from
764 and the XFS_IOC_FSGEOMETRY
765 system call on the filesystem where the current file resides.
767 .BR chproj " [ " \-R | \-D " ]"
768 Modifies the project identifier associated with the current path. The
770 option will recursively descend if the current path is a directory. The
772 option will also recursively descend, only setting modifying projects
773 on subdirectories. See the
775 manual page for more information about project identifiers.
777 .BR lsproj " [ " \-R | \-D " ]"
778 Displays the project identifier associated with the current path. The
782 options behave as described above, in
785 .BR parent " [ " \-cpv " ]"
786 By default this command prints out the parent inode numbers,
787 inode generation numbers and basenames of all the hardlinks which
788 point to the inode of the current file.
793 the output is similar to the default output except pathnames up to
794 the mount-point are printed out instead of the component name.
797 the file's filesystem will check all the parent attributes for consistency.
800 verbose output will be printed.
803 .B [NOTE: Not currently operational on Linux.]